Skip to content

Varagity

Varagity is a self-hosted, GPU-accelerated Retrieval-Augmented Generation (RAG) system implementing Anthropic-style Contextual Retrieval: documents are parsed, chunked, situated with LLM-generated context blurbs, then indexed for hybrid (semantic + BM25) retrieval with cross-encoder reranking and grounded, cited answers. The primary surface is the web GUI at :3000 — streaming chat whose evidence panel shows how each answer was built, chunk by chunk — with the terminal CLI as a peer front-end over the same Prefect flows, and a Prometheus/Grafana pair watching the whole pipeline.

This site is the as-built documentation of the system (v1 + v2):

  • Architecture

    Service topology, the two pipelines, the (doc_id, original_index) identity thread, and why Contextual Retrieval.

    Read the architecture

  • Codebase map

    The whole system as one interactive graph — the web GUI's /map, built into this site: click a card to trace its downstream flow.

    Explore the map

  • Data model

    The chunk metadata record, PostgreSQL schema, Elasticsearch mapping, and idempotency semantics.

    Read the data model

  • Pipelines

    The ingest/query/eval Prefect task graphs and their retry/caching posture.

    Follow the pipelines

  • Runbook

    Clean clone to answered question, plus every operational gotcha — healthchecks, volumes, GPUs, OCR, Elasticsearch.

    Open the runbook

  • HTTP API

    The wire contract, auto-rendered from the checked-in OpenAPI snapshot, plus the two SSE event protocols and the error-envelope conventions.

    Browse the API

  • ADRs

    The decisions with lasting consequences and their why — from pgvector-over-Qdrant to document page previews.

    Read the decisions

  • API reference

    Every public module, class, and function, rendered from the package's Google-style docstrings via mkdocstrings.

    Explore the reference

  • Specs & plans

    spec.md and spec_v2.md at the repository root are the forward-looking designs this system was built from; thoughts/shared/plans/ holds the vertical slices each build followed.

    Visit the repository

Naming caution

docs/ in this repository is the gitignored ingest corpus (the documents the RAG system indexes), not project documentation. Project documentation — what you are reading — lives in golden-docs/.