Skip to content

Polaris — Brain Builder Platform

Polaris is a domain-agnostic, multi-tenant knowledge engine — "the Shopify for brains." It runs three uniform Pydantic AI agents over a shared store substrate, governed by a draft → certify → publish lifecycle, and fronted by a React web app.

Every served answer is grounded in source passages — cite-then-verify, or it isn't served.

  • Discover

    The Scout reaches outward (Firecrawl) to find candidate sources, stages them, and targets them into the ingestion loop.

  • Curate

    The Librarian is the single write gate: human-in-the-loop ingest → draft → certify → publish, fully audited.

  • Serve

    The Advisor answers synchronously from published versions only, every claim cite-then-verified.

  • Govern

    The Sentinel watches for drift and staleness (event contracts today; sense worker deferred).

The agents

Agent Role Notes
Advisor Synchronous read/serve Published versions only; every claim cite-then-verified. (Named Counselor in code.)
Librarian The single write gate HITL ingest → draft → certify → publish.
Scout Outward discovery Firecrawl sweep → staged candidates → target into the Librarian loop.
Sentinel Sense / drift watch Monitoring MVP: sweeps flag freshness, temporal, and grounding drift on known sources; confirmed flags re-enter the Librarian loop.

New to Polaris? The User Guide walks through the whole lifecycle — discover, curate, publish, consult, monitor — from an end-user perspective.

Architecture at a glance

flowchart LR
    subgraph Web
        SPA[Brain Builder SPA<br/>React / Vite]
    end
    subgraph Gateway["Capability Gateway (FastAPI)"]
        REST[REST]
        WS[WebSocket chat]
        SSE[SSE events]
    end
    subgraph Stores["Store substrate (Docker)"]
        PG[(Postgres + pgvector)]
        GRAPH[/NetworkX GraphML/]
        REDIS[(Redis)]
        MINIO[(MinIO)]
        LR[LightRAG]
    end
    SPA -->|/v1| Gateway
    Gateway --> Stores
    Scout -->|candidates| Librarian
    Librarian -->|draft → publish| Stores
    Advisor -->|cite-then-verify| Stores

The app services run on the host via uv (--reload / HMR); only the stores run in Docker. An optional containerized app tier (gateway + librarian + advisor) is available behind the compose app profile — see Dev Loop.

Where to go next

  • User Guide

    Using the app: the four agents, the review pipeline, and every feature — for end users.

  • Dev Loop

    Get the stack running with one command; understand what auto-reloads.

  • Workspaces

    Provision and stand up an isolated per-brain instance from a manifest.

  • Linkage Loop

    Raise a corpus to publishable linkage quality — the agent procedure, and how to tell when the number in front of you is wrong.

  • Capability Gateway

    The REST + WebSocket + SSE API, auth, and the /v1 contract.

  • MCP (Advisor)

    Wire the Advisor into any MCP client with an API key — answer, retrieve, read_wiki.

  • Claude Code

    Use the Advisor from Claude Code — as an MCP tool, or as a model backend via a gateway.

  • OpenCode

    Native OpenCode integration — remote MCP tool or an OpenAI-compatible provider (no bridge).

Status

Phases 0–5 complete (substrate → deterministic rebuild → HITL ingestion → certify/publish → Advisor serve → JWT auth) plus the web tier (capability gateway + Brain Builder SPA). Phase 6 (containerizing the app services + observability) is in progress.