andyliszewski/grounding-ai

**Local-first document corpus pipeline for grounded AI agents.**
**Measured:** with a Grounding corpus of 25 public-domain engineering documents to search, Claude answered 96% of 26 answerable regulatory and engineering questions correctly, against 46% without it: **+50 points** (95% CI +31 to +69). Every answer was graded by hand, blind to whether it had the corpus, under an analysis written down before the run. The citation check failed its own validation gate, and the write-up reports that too (details below).
Grounding converts PDF, EPUB, DOCX, and Markdown documents into a structured, searchable corpus with per-agent embedding indexes. Drop documents into staging, get chunked Markdown with provenance hashing, FAISS vector indexes, and agent-filtered search -- all running locally, no cloud APIs required.
What It Does
Key Features
- **Deterministic pipeline** -- same inputs produce byte-identical outputs
- **Content provenance** -- SHA-1, SHA-256, and BLAKE3 hashing on every document and chunk
- **Agent-based corpus partitioning** -- YAML-defined agents filter the corpus by collection tags, each with their own FAISS embedding index
- **Persona system** -- agents have configurable communication styles, expertise areas, and greeting messages
- **Staging watcher** -- drop files into a folder, auto-ingest with embedding updates
- **Multi-machine ready** -- optional Syncthing-based architecture for dedicated ingestion servers
- **Fully local** -- no cloud APIs, no telemetry, your documents stay on your machine
- **Agentic RAG** -- local LLMs autonomously decide when to search the corpus via tool calling
Why Grounding? (vs. LlamaIndex / Haystack / txtai)
Grounding is an opinionated pipeline, not a framework:
- **Per-agent FAISS partitioning as a first-class primitive.** Each agent YAML defines a corpus slice and gets its own index -- no single monolithic index where unrelated domains compete for top-k. Other frameworks treat this as a filter you bolt on at query time; here it's the core data model.
- **Determinism and provenance for citable output.** Every chunk carries SHA-1 / SHA-256 / BLAKE3 hashes, page ranges, and section headings; same inputs produce byte-identical chunks. Built for agents that must cite sources.
- **Local-first by construction.** No cloud APIs, no telemetry. Runs against Ollama or any OpenAI-compatible local server. Cloud isn't a default path -- it's not a path at all.
- **Opinionated fixed pipeline** (parse → chunk → hash → index → query). Less surface area than a framework, less to configure, less to break.
Use LlamaIndex / Haystack if you want a framework to assemble custom retrieval flows. Use grounding-ai if you want a citation-grade local RAG pipeline with per-agent separation, working today.
Quick Start
Install from PyPI
Then grab the example configs and agents from the repo:
Install from source (for development)
First run (end-to-end)
A typical session looks like this:
Agent System
Agents are YAML files that define a persona and a corpus filter:
Each agent gets its own FAISS embedding index containing only documents matching its collections. See agents/examples/ for starter templates.
Creating Your Own Agents
1. **Define the agent.** Create a YAML file in agents/:
2. **Ingest documents with matching collection tags.** Collections are kebab-case labels you assign when ingesting:
A document can belong to multiple collections (comma-separated). An agent sees all documents whose collection tags overlap with its corpus_filter.collections list.
3. **Generate embeddings** for the agent:
This builds a FAISS index at embeddings/my-agent/ containing only chunks from documents matching the agent's collection filter.
4. **Query** the agent:
Where Do My Agent Files Live?
By default, agents/*.yaml is **gitignored** (only agents/examples/ is tracked). This means YAMLs you create in agents/ won't show up in git status and won't be committed to your fork. There are three common workflows depending on how you want to manage your agents: