Skip to content

Latest commit

 

History

History
213 lines (147 loc) · 6.32 KB

common-patterns.md

File metadata and controls

213 lines (147 loc) · 6.32 KB

Common Patterns

Production-ready patterns for extending graphcrew. Each pattern is a minimal, working skeleton you can adapt.


PostgreSQL SessionManager

Connection-pool-backed session manager with batch inserts and cursor pagination.

from __future__ import annotations

from typing import Any

import asyncpg

from graphcrew import SessionManager
from graphcrew import Memory, PaginatedResult, SessionMessage


class PostgresSessionManager(SessionManager):
    def __init__(self, pool: asyncpg.Pool) -> None:
        self._pool = pool

    async def save_messages(self, session_id: str, messages: list[SessionMessage]) -> None:
        async with self._pool.acquire() as conn:
            await conn.executemany(
                "INSERT INTO messages (session_id, role, content, timestamp) VALUES ($1, $2, $3, $4)",
                [(session_id, m.role, m.content, m.timestamp) for m in messages],
            )

    async def get_messages(self, session_id: str, limit: int = 50) -> list[SessionMessage]:
        async with self._pool.acquire() as conn:
            rows = await conn.fetch(
                "SELECT role, content, timestamp FROM messages "
                "WHERE session_id = $1 ORDER BY timestamp DESC LIMIT $2",
                session_id, limit,
            )
        return [SessionMessage(role=r["role"], content=r["content"]) for r in reversed(rows)]

    async def clear_session(self, session_id: str) -> None:
        async with self._pool.acquire() as conn:
            await conn.execute("DELETE FROM messages WHERE session_id = $1", session_id)

    async def health_check(self) -> dict[str, Any]:
        async with self._pool.acquire() as conn:
            await conn.fetchval("SELECT 1")
        return {"status": "ok", "pool_size": self._pool.get_size()}

    async def close(self) -> None:
        await self._pool.close()

    def get_capabilities(self) -> set[str]:
        return {"get_messages", "save_messages", "clear_session"}

Redis SlotPersistence

JSON-serialized slots with automatic TTL expiry.

from __future__ import annotations

import json
from typing import Any

import redis.asyncio as redis

from graphcrew import Slot, SlotPersistence


class RedisSlotPersistence(SlotPersistence):
    def __init__(self, client: redis.Redis, ttl_seconds: int = 3600) -> None:
        self._client = client
        self._ttl = ttl_seconds

    def _key(self, prefix: str, identifier: str) -> str:
        return f"slots:{prefix}:{identifier}"

    async def load_session_slots(self, session_id: str) -> list[Slot]:
        raw = await self._client.get(self._key("session", session_id))
        if not raw:
            return []
        return [Slot(**item) for item in json.loads(raw)]

    async def save_session_slots(self, session_id: str, slots: list[Slot]) -> None:
        data = json.dumps([s.__dict__ for s in slots])
        await self._client.set(self._key("session", session_id), data, ex=self._ttl)

    async def delete_session_slots(self, session_id: str) -> None:
        await self._client.delete(self._key("session", session_id))

    async def load_long_term_slots(self, user_id: str) -> list[Slot]:
        raw = await self._client.get(self._key("long_term", user_id))
        if not raw:
            return []
        return [Slot(**item) for item in json.loads(raw)]

    async def save_long_term_slots(self, user_id: str, slots: list[Slot]) -> None:
        data = json.dumps([s.__dict__ for s in slots])
        await self._client.set(self._key("long_term", user_id), data, ex=self._ttl)

    async def delete_long_term_slots(self, user_id: str) -> None:
        await self._client.delete(self._key("long_term", user_id))

    async def health_check(self) -> dict[str, Any]:
        pong = await self._client.ping()
        return {"status": "ok" if pong else "degraded"}

    async def close(self) -> None:
        await self._client.aclose()

tiktoken TokenCounter

Model-specific token counting with lazy encoder initialization.

from __future__ import annotations

import tiktoken

from graphcrew import TokenCounter


class TiktokenCounter(TokenCounter):
    def __init__(self, model: str = "gpt-4") -> None:
        self._model = model
        self._encoder: tiktoken.Encoding | None = None

    def _get_encoder(self) -> tiktoken.Encoding:
        if self._encoder is None:
            self._encoder = tiktoken.encoding_for_model(self._model)
        return self._encoder

    def count(self, text: str) -> int:
        if not text:
            return 0
        return len(self._get_encoder().encode(text))

See also examples/custom_token_counter/ for a runnable example.


Multi-Tenant Setup

Combine TenantIsolationMiddleware, PII redaction, and per-agent circuit breakers.

from graphcrew import CircuitBreakerMiddleware, TenantIsolationMiddleware, bind_logging_context

# One circuit breaker per agent (not shared)
worker_cb = CircuitBreakerMiddleware(failure_threshold=5, recovery_timeout_seconds=30.0)
reviewer_cb = CircuitBreakerMiddleware(failure_threshold=3, recovery_timeout_seconds=60.0)

# Tenant isolation is safe to share (uses contextvars)
tenant_guard = TenantIsolationMiddleware()

worker = MyWorkerAgent(
    config=worker_config,
    middleware=[tenant_guard, worker_cb],
)
reviewer = MyReviewerAgent(
    config=reviewer_config,
    middleware=[tenant_guard, reviewer_cb],
)

# At request boundary, enable PII redaction for logs
bind_logging_context(state, config, redact_pii=True)

FastAPI Lifecycle

Use OrchestratorContext as an async context manager in FastAPI's lifespan.

from contextlib import asynccontextmanager
from collections.abc import AsyncIterator

from fastapi import FastAPI, Request

from graphcrew import OrchestratorContext


@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
    ctx = OrchestratorContext(
        slot_manager=my_slot_manager,
        session_manager=my_session_manager,
    )
    async with ctx:
        app.state.orchestrator = ctx
        yield


app = FastAPI(lifespan=lifespan)


@app.get("/health")
async def health(request: Request) -> dict:
    ctx: OrchestratorContext = request.app.state.orchestrator
    return {"status": "ok", "orchestrator": repr(ctx)}

See also examples/fastapi_app/ for a complete runnable example.