Skip to content

CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.

6.4 KB
Raw Blame
"""Persist an agent conversation in Postgres and resume it after a restart.

This is a runnable, end-to-end example of `PostgresCheckpointer`. It uses
`FauxProvider`, so it needs no API key — only a reachable Postgres.

    CUBELOOP_PG_DSN=postgresql://user:pass@host:5432/dbname \
        uv run python examples/checkpointing_postgres.py

Defaults to `postgresql://postgres:postgres@localhost:5432/postgres`.

What it shows:

1. Bootstrapping the cubepi v2 schema. In production this is your host
   application's Alembic migration — see
   `cubepi/checkpointer/postgres/README.md`. The DDL here mirrors exactly
   what that migration produces, using the same `alembic_helpers`.
2. Running an `Agent` whose turns are persisted by the checkpointer.
3. A simulated process restart: a brand-new checkpointer loads the thread's
   full history back.

The example creates a throwaway database and drops it on exit, so it is safe
to run repeatedly against a dev server.
"""

import asyncio
import os
import secrets

import asyncpg

from cubeloop.agent.agent import Agent
from cubeloop.checkpointer.postgres import PostgresCheckpointer
from cubeloop.checkpointer.postgres.alembic_helpers import (
    create_message_partitions_op,
    create_runs_partitions_op,
    write_schema_version_op,
)
from cubeloop.providers.faux import FauxProvider, faux_assistant_message

ADMIN_DSN = os.environ.get(
    "CUBELOOP_PG_DSN",
    os.environ.get(
        "CUBEPI_PG_DSN",
        "postgresql://postgres:postgres@localhost:5432/postgres",
    ),
)
THREAD_ID = "user-42"


async def bootstrap_schema(dsn: str) -> None:
    """Create the CubeLoop checkpointer schema v5.

    In a real deployment this DDL belongs in the host's Alembic history.
    """
    conn = await asyncpg.connect(dsn)
    try:
        await conn.execute("""
            CREATE TABLE cubepi_threads (
                thread_id TEXT PRIMARY KEY,
                parent_thread_id TEXT REFERENCES cubepi_threads(thread_id),
                forked_at_seq BIGINT,
                extra JSONB NOT NULL DEFAULT '{}'::jsonb,
                pending_request JSONB,
                run_id TEXT,
                created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
                updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
            );
        """)
        await conn.execute("""
            CREATE TABLE cubepi_messages (
                thread_id TEXT NOT NULL
                    REFERENCES cubepi_threads(thread_id) ON DELETE CASCADE,
                seq BIGINT NOT NULL,
                role TEXT NOT NULL,
                metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
                payload BYTEA NOT NULL,
                run_id TEXT,
                created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
                PRIMARY KEY (thread_id, seq)
            ) PARTITION BY HASH (thread_id);
        """)
        await conn.execute(create_message_partitions_op())
        await conn.execute("""
            CREATE INDEX ix_cubepi_messages_metadata_gin
            ON cubepi_messages USING GIN (metadata jsonb_path_ops);
        """)
        await conn.execute("""
            CREATE TABLE cubepi_schema_version (version INTEGER PRIMARY KEY);
        """)
        await conn.execute("""
            CREATE TABLE cubepi_runs (
                thread_id TEXT NOT NULL REFERENCES cubepi_threads(thread_id)
                    ON DELETE CASCADE,
                run_id TEXT NOT NULL,
                claimed_at TIMESTAMPTZ NOT NULL DEFAULT now(),
                completed_at TIMESTAMPTZ,
                completion_seq BIGINT,
                PRIMARY KEY (thread_id, run_id)
            ) PARTITION BY HASH (thread_id);
        """)
        await conn.execute(create_runs_partitions_op())
        await conn.execute("""
            CREATE TABLE cubepi_hitl_answers (
                thread_id TEXT NOT NULL REFERENCES cubepi_threads(thread_id)
                    ON DELETE CASCADE,
                run_id TEXT NOT NULL,
                question_id TEXT NOT NULL,
                answer JSONB NOT NULL,
                answered_at TIMESTAMPTZ NOT NULL DEFAULT now(),
                PRIMARY KEY (thread_id, run_id, question_id)
            );
        """)
        await conn.execute(write_schema_version_op())
    finally:
        await conn.close()


def build_agent(checkpointer: PostgresCheckpointer) -> Agent:
    provider = FauxProvider(provider_id="faux")
    provider.set_responses([faux_assistant_message("Hi! I'll remember this.")])
    return Agent(
        model=provider.model("faux"),
        checkpointer=checkpointer,
        thread_id=THREAD_ID,
    )


def transcript(messages) -> list[str]:
    return [
        f"{type(m).__name__}: {getattr(c, 'text', '')}"
        for m in messages
        for c in m.content
        if getattr(c, "text", "")
    ]


async def main() -> None:
    # Throwaway DB so the example is safe to re-run.
    db_name = f"cubeloop_example_{secrets.token_hex(5)}"
    admin = await asyncpg.connect(ADMIN_DSN)
    try:
        await admin.execute(f'CREATE DATABASE "{db_name}"')
    finally:
        await admin.close()

    dsn = f"{ADMIN_DSN.rsplit('/', 1)[0]}/{db_name}"
    try:
        await bootstrap_schema(dsn)
        print(f"Created schema in throwaway database {db_name}\n")

        # First "process": run a turn. Entering the context manager verifies
        # the schema; the agent persists each turn through the checkpointer.
        async with PostgresCheckpointer(dsn) as cp:
            agent = build_agent(cp)
            await agent.prompt("Remember that my favourite colour is teal.")
            print("First run transcript:")
            for line in transcript(agent.state.messages):
                print(f"  {line}")

        # Second "process": a fresh checkpointer loads the whole thread back.
        async with PostgresCheckpointer(dsn) as cp:
            data = await cp.load(THREAD_ID)
            assert data is not None
            print(f"\nAfter restart, loaded {len(data.messages)} messages:")
            for line in transcript(data.messages):
                print(f"  {line}")
    finally:
        admin = await asyncpg.connect(ADMIN_DSN)
        try:
            await admin.execute(
                "SELECT pg_terminate_backend(pid) FROM pg_stat_activity "
                "WHERE datname = $1",
                db_name,
            )
            await admin.execute(f'DROP DATABASE IF EXISTS "{db_name}"')
        finally:
            await admin.close()
        print(f"\nDropped throwaway database {db_name}")


if __name__ == "__main__":
    asyncio.run(main())