Pharos

Turn PDFs, scans, docx, pptx and xlsx into a local knowledge base you can ask questions of — with enterprise access control and citations you can trace back to the page. Each RAG component was sharpened on its own, then folded into one repository: multi-identity auth, observability and systemd supervision come with it.

A note on language. The code, CLI and commit history are in English; the documentation — including the 12-part learning series — is written in Chinese. This README is the English entry point and covers what the system is, how it is put together and how to run it. For anything deeper, you will be reading Chinese (or machine-translating it).

---

The Lighthouse of Alexandria stood beside the Library, guiding ships to shore. Pharos does the same job, except what it lights up is your team's document library.

This is not another chunking toy. Every significant decision here is backed by a measurement, argued through several rounds of adversarial review, and is running today over 77 real documents and 7,652 chunks. Installing it is one line: pip install -e '.[dev]' (src-layout, editable).

Two exits, one set of semantics

One knowledge base, one door for each kind of consumer:

Exit	Command	Who uses it	What it does
HTTP API	pharos serve	curl, scripts, frontends	Closed-pipeline QA: /v1/ask runs retrieve → grounding → DeepSeek → an answer with citations, plus six retrieval endpoints
MCP	pharos mcp	agents such as Claude Code	Agentic RAG: when to retrieve, how to rewrite, whether to go multi-hop — the agent decides

Both doors share one set of semantics, held in place by two rules: the tool contract has exactly one source (toolcore, so the stdio and HTTP sides cannot drift), and identity is decided server-side (an agent cannot edit its own permissions).

Architecture

Why a resident daemon? Embedded Qdrant admits a single client and holds an exclusive lock, and an 8B model takes a minute or two just to load. Under the earlier stdio-direct design, every agent session spawned its own process — fighting over the lock and reloading the model each time. Pharos inverts that: the daemon owns the heavy resources, MCP shrinks to a thin HTTP adapter that starts in milliseconds, and every session shares one already-warm backend. The trade-offs behind this are in docs/DESIGN.md (Chinese).

Production shape: from one box to three independently scalable tiers

The single-node problem is that the GPU model, embedded Qdrant and application logic all live in one process, so horizontal scaling hits a ceiling immediately. Split apart, there are three tiers that scale independently:

• inference (FastAPI on :8900) — GPU forward passes lifted out on their own, returning full-width vectors that the client then truncates, with both sides kept equivalent;
• pharos — the application layer sheds torch entirely (set inference_url and it never loads a model), which is what makes --scale pharos=N possible;
• Qdrant in server mode — replicas share one source of truth, with nginx in front for load balancing; docker kill on any replica goes unnoticed.

docker compose --env-file .env.compose up -d --scale pharos=3   # entry point: http://127.0.0.1:8080