Quickstart

Build your first token-budgeted context payload from scratch.

This guide assumes you have already completed the Installation steps, including running PostgreSQL with pgvector and running the Alembic migrations.

We will use the local embedding provider for this quickstart, which downloads a lightweight BGE embedding model to your machine.

1. Initialize the Orchestrator

The ContextOrchestrator is the main entry point to ContextOS. It wires together the retrieval, fusion, and planning components.

import asyncio
from uuid import uuid4
from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker

from contextos.factory import create_orchestrator
from contextos.domain.context_item import ContextItem
from contextos.domain.enums import Role, ContextSource
from contextos.embedding.embedding_service import get_embedding_service

async def main():
    # 1. Connect to PostgreSQL
    db_url = "postgresql+asyncpg://postgres:postgres@localhost:5433/contextos"
    engine = create_async_engine(db_url)
    async_session = async_sessionmaker(engine, expire_on_commit=False)
    
    async with async_session() as db:
        # 2. Create the orchestrator with a strict 4,000 token budget
        orchestrator = create_orchestrator(db=db, token_budget=4000)

2. Add Context Items (Memory)

Before we can build a context window, we need to populate the database with some candidates. When you add a ContextItem, ContextOS automatically persists it and queues it for embedding generation.

        session_id = uuid4()
        memory_manager = orchestrator._memory_manager
        
        # Create a session
        await memory_manager.create_session(session_id=session_id)
        
        # Add a system prompt (Guaranteed to be included)
        await memory_manager.add_context_item(ContextItem(
            id=uuid4(),
            session_id=session_id,
            role=Role.SYSTEM,
            source=ContextSource.SYSTEM,
            content="You are a helpful assistant. Be concise.",
        ))
        
        # Add a historical memory
        await memory_manager.add_context_item(ContextItem(
            id=uuid4(),
            session_id=session_id,
            role=Role.USER,
            source=ContextSource.SYSTEM,
            content="I previously had issues with asyncpg connection timeouts.",
        ))

Note: In a real application, you would also use the EmbeddingService to embed these items, or run a background worker to embed new items asynchronously. For a complete example, see examples/1_minimal_quickstart.py in the repository.

3. Build the Context Payload

Now, we query the orchestrator. ContextOS will embed the query, retrieve candidates using dense search (and BM25 if configured), rank them, and pack them into the token budget.

        query = "Why is my database timing out?"
        
        # 3. Retrieve, rerank, and plan the context window
        result = await orchestrator.build_context(
            session_id=session_id, 
            query=query
        )

4. Inspect the Result

The ContextResult object contains the fully assembled text string ready for your LLM, as well as metadata about token usage and the detailed execution trace.

        # Pass this directly to OpenAI, Anthropic, etc.
        print("\n=== FINAL CONTEXT PAYLOAD ===")
        print(result.context)
        
        print("\n=== EXECUTION METRICS ===")
        print(f"Tokens Used: {result.tokens_used} / {result.token_budget}")
        print(f"Candidates Retrieved: {result.trace.candidate_pool.total_candidates}")
        
        print("\n=== TRACE DECISIONS ===")
        for decision in result.decisions:
            status = "SELECTED" if decision.selected else "REJECTED"
            print(f"- {status} | Score: {decision.final_score:.3f} | Reason: {decision.reason}")

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

Next Steps

To understand exactly how ContextOS selected those items, read about the Token Budget Planner.