Production-ready patterns for extending graphcrew. Each pattern is a minimal, working skeleton you can adapt.
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"}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()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.
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)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.