API Reference

ContextOrchestrator

The ContextOrchestrator is the main class you interact with. It is highly recommended to instantiate it using the factory function create_orchestrator rather than constructing its dependencies manually.

create_orchestrator(db, token_budget)

Creates a fully wired orchestrator instance.

• db: An active SQLAlchemy AsyncSession.
• token_budget: Integer representing the maximum context window size in tokens.

async build_context(session_id, query) -> ContextResult

Runs the full context pipeline (retrieval, fusion, reranking, planning) and returns a constructed payload.

• session_id: UUID representing the current conversation or user session.
• query: String query from the user to search the memory store with.

ContextResult

The output of build_context. This object contains the assembled prompt and the metrics from the pipeline run.

• context (str): The final formatted prompt payload to be sent to your LLM.
• selected_items (list[ContextItem]): The raw memory items that were selected.
• decisions (list[MemoryDecision]): The explainable planner decisions for every candidate evaluated.
• trace (ExecutionTrace): The detailed observability trace (timings, pipeline stages).
• tokens_used (int): The total number of tokens consumed by the context payload.
• token_budget (int): The strict budget constraint the planner operated under.

MemoryManager

Accessible via orchestrator._memory_manager, this class handles persistence.

async create_session(session_id)

Initializes a new session in the database. Must be called before adding items to a session.

async add_context_item(item: ContextItem)

Persists a ContextItem. Note that you must embed the item separately via the EmbeddingService and save the embedding via add_context_embedding.