fitz-ai 0.4.2

A modular, production-ready knowledge engine platform with clean architecture and multi-paradigm support (RAG, CLaRa).

fitz-ai

---

Honest RAG in 5 minutes. No infrastructure. No boilerplate.

pip install fitz-ai

fitz quickstart ./docs "What is our refund policy?"

That's it. Your documents are now searchable with AI.

---

About 🧑‍🌾

Solo project by Yan Fitzner (LinkedIn, GitHub).

• ~40k lines of Python
• 600+ tests, 100% coverage
• Zero LangChain/LlamaIndex dependencies — built from scratch

---

📦 What is RAG?

Instead of sending all your documents to an AI, RAG:

1. Indexes your documents once — Splits them into chunks, converts to vectors, stores in a database
2. Retrieves only what's relevant — When you ask a question, finds the 5-10 most relevant chunks
3. Sends just those chunks to the LLM — The AI answers based on focused, relevant context

Traditional approach:

  [All 10,000 documents] → LLM → Answer
  ❌ Impossible (too large)
  ❌ Expensive (if possible)
  ❌ Unfocused

RAG approach:

  Question → [Search index] → [5 relevant chunks] → LLM → Answer
  ✅ Works at any scale
  ✅ Costs pennies per query
  ✅ Focused context = better answers

RAG is how ChatGPT's "file search," Notion AI, and enterprise knowledge tools actually work under the hood.

---

📦 Why Can't I Just Send My Documents to ChatGPT directly?

You can—but you'll hit walls fast.

Context window limits ❌

GPT-4 accepts ~128k tokens. That's roughly 300 pages. Your company wiki, codebase, or document archive is likely 10x-100x larger. You physically cannot paste it all.

Cost explosion 💥

Even if you could fit everything, you'd pay for every token on every query. Sending 100k tokens costs ~$1-3 per question. Ask 50 questions a day? That's $50-150 daily—for one user.

No selective retrieval 🚨

When you paste documents, the model reads everything equally. It can't focus on what's relevant. Ask about refund policies and it's also processing your hiring guidelines, engineering specs, and meeting notes—wasting context and degrading answers.

No persistence 💢

Every conversation starts fresh. You re-upload, re-paste, re-explain. There's no knowledge base that accumulates and improves.

---

Why Fitz?

Super fast setup 🐆

Point at a folder. Ask a question. Get an answer with sources. Everything else is handled by Fitz.

Honest answers ✅

Most RAG tools confidently answer even when the answer isn't in your documents. Ask "What was our Q4 revenue?" when your docs only cover Q1-Q3, and typical RAG hallucinates a number. Fitz says: "I cannot find Q4 revenue figures in the provided documents."

Swap engines, keep everything else ⚙️

RAG is evolving fast—GraphRAG, HyDE, ColBERT, whatever's next. Fitz lets you switch engines in one line. Your ingested data stays. Your queries stay. No migration, no re-ingestion, no new API to learn. Frameworks lock you in; Fitz lets you move.

Analytical queries that actually work 📊

Standard RAG fails on questions like "What are the trends?"—it retrieves random chunks instead of insights. Fitz's hierarchical RAG generates multi-level summaries during ingestion. Ask for trends, get aggregated analysis. Ask for specifics, get detail chunks. No special syntax required.

Other Features at a Glance 🃏

1. [x] Local execution possible. FAISS and Ollama support, no API keys required to start.
2. [x] Plugin-based architecture. Swap LLMs, vector databases, rerankers, and retrieval pipelines via YAML config.
3. [X] Incremental ingestion. Only reprocesses changed files, even with new chunking settings.
4. [x] Full provenance. Every answer traces back to the exact chunk and document.
5. [x] Data privacy: No telemetry, no cloud, no external calls except to the LLM provider you configure.

Any questions left? Try fitz on itself:

fitz quickstart ./fitz_ai "How does the chunking pipeline work?"

The codebase speaks for itself.

---

📦 Fitz vs LangChain vs LlamaIndex

Fitz opts for a deliberately narrower approach.

LangChain and LlamaIndex are powerful LLM application frameworks designed to help developers build complex, end-to-end AI systems. Fitz provides a minimal, replaceable RAG engine with strong epistemic guarantees — without locking users into a framework, ecosystem, or long-term architectural commitment.

Fitz is not a competitor in scope.
It is an infrastructure primitive.

Core philosophical differences ⚖️

Dimension	Fitz	LangChain	LlamaIndex
Primary role	RAG engine	LLM application framework	LLM data framework
User commitment	No framework lock-in	High	High
Engine coupling	Swappable in one line	Deep	Deep
Design goal	Correctness & honesty	Flexibility	Data integration
Long-term risk	Low	Migration-heavy	Migration-heavy

Epistemic behavior (truth over fluency) 🎯

Aspect	Fitz	LangChain / LlamaIndex
“I don’t know”	First-class behavior	Not guaranteed
Hallucination handling	Designed-in	Usually prompt-level
Confidence signaling	Explicit	Implicit

Fitz treats uncertainty as a feature, not a failure.
If the system cannot support an answer with retrieved evidence, it says so.

Transparency & provenance 🔎

Capability	Fitz	LangChain / LlamaIndex
Source attribution	Mandatory	Optional
Retrieval trace	Explicit & structured	Often opaque
Debuggability	Built-in	Tool-dependent

Every answer in Fitz is fully auditable down to the retrieval step.

Scope & complexity 🪐

Aspect	Fitz	LangChain / LlamaIndex
Chains / agents	❎	✔
Prompt graphs	❎	✔
UI abstractions	❎	Often
Cognitive overhead	Very low	High

Fitz intentionally does less — so it can be trusted more.

Use Fitz if you want:

• A replaceable RAG engine, not a framework marriage
• Strong epistemic guarantees (“I don’t know” is valid output)
• Full provenance for every answer
• A transparent, extensible plugin architecture
• A future-proof ingestion pipeline that survives engine changes

---

📦 Features

Actually admits when it doesn't know 📚

When documents don't contain the answer, fitz says so:

Q: "What was our Q4 revenue?"
A: "I cannot find Q4 revenue figures in the provided documents.
    The available financial data covers Q1-Q3 only."

   Mode: ABSTAIN

Three constraint plugins run automatically:

• 📕 ConflictAwareConstraint: Detects contradictions across sources
• 📗 InsufficientEvidenceConstraint: Blocks answers without evidence
• 📘 CausalAttributionConstraint: Prevents hallucinated cause-effect claims

Swappable RAG Engines 🔄

Your data stays. Your queries stay. Only the engine changes.

       ┌─────────────────────────────────────┐
       │           Your Query                │
       │   "What are the payment terms?"     │
       └──────────────────┬──────────────────┘
                          │
                          ▼
       ┌─────────────────────────────────────┐
       │       engine="..."                  │
       │  ┌─────────┐ ┌───────┐ ┌─────────┐  │
       │  │ classic │ │ clara │ │ graph   │  │
       │  │  _rag   │ │       │ │  _rag   │  │
       │  └────┬────┘ └───┬───┘ └────┬────┘  │
       │       └──────────┼──────────┘       │
       └──────────────────┼──────────────────┘
                          │
                          ▼
       ┌─────────────────────────────────────┐
       │       Your Ingested Knowledge       │
       │      (unchanged across engines)     │
       └─────────────────────────────────────┘

answer = run("What are the payment terms?", engine="classic_rag")
answer = run("What are the payment terms?", engine="clara")
answer = run("What are the payment terms?", engine="graph_rag")  # future

No migration. No re-ingestion. No new API to learn.

Full Provenance 🗂️

Every answer traces back to its source:

Answer: The refund policy allows returns within 30 days...

Sources:
 [1] policies/refund.md [chunk 3] (score: 0.92)
 [2] faq/payments.md [chunk 1] (score: 0.87)

Incremental Ingestion ⚡

Fitz tracks file hashes and only re-ingests what changed:

$ fitz ingest ./src

Scanning... 847 files
 → 12 new files
 → 3 modified files
 → 832 unchanged (skipped)

Ingesting 15 files...

Re-running ingestion on a large codebase takes seconds, not minutes. Changed your chunking config? Fitz detects that too and re-processes affected files.

Smart Chunking 🧠

Format-aware chunking that preserves structure:

Format	Strategy
Python	AST-aware: keeps classes, functions, imports intact. Large classes split by method.
Markdown	Header-aware: splits on # headers, preserves code blocks and lists. Extracts YAML frontmatter as metadata.
PDF	Section-aware: detects numbered headings (1.1, 2.3.1), roman numerals, and keywords (Abstract, Conclusion).

No more retrieving half a function or a code block split mid-syntax.

Enrichment ✨

Opt-in enrichment plugins enhance your knowledge base:

• Code-derived artifacts: Navigation indexes, interface catalogs, dependency graphs—extracted directly from your codebase via AST analysis. No LLM required.
• LLM-generated summaries: Natural language descriptions for chunks, making code more discoverable via semantic search.

Your question matches enriched context, not just raw text. Fully extensible—add your own enrichment plugins.

Hierarchical RAG 📊

Standard RAG struggles with analytical queries like "What are the trends?" because it retrieves random chunks instead of aggregated insights. Hierarchical RAG solves this.

The problem:

Q: "What are the trends in my comments?"
Standard RAG: Returns random individual comments (not useful)

The solution:

# .fitz/config.yaml
enrichment:
 hierarchy:
   enabled: true
   rules:
     - name: video_comments
       paths: ["comments/**"]
       group_by: video_id
       prompt: "Summarize sentiment and themes"

Fitz generates multi-level summaries during ingestion:

• Level 0: Corpus summary ("Across all videos: 78% positive, top themes are...")
• Level 1: Group summaries ("Video ABC: mostly questions about pricing...")
• Level 2: Original chunks (unchanged)

Now analytical queries retrieve summaries, while specific queries still retrieve details:

Q: "What are the trends in my comments?"
→ Returns corpus + group summaries (aggregated insights)

Q: "What did people say about my hair?"
→ Returns specific comments mentioning hair (detail chunks)

No special query syntax. No retrieval config changes. Summaries match analytical queries naturally via vector similarity.

---

📦 Quick Start

pip install fitz-ai

fitz quickstart ./docs "Your question here"

That's it. Fitz will prompt you for anything it needs.

Want to go fully local with Ollama? No problem:

pip install fitz-ai[local]

ollama pull llama3.2
ollama pull nomic-embed-text

fitz quickstart ./docs "Your question here"

No data leaves your machine. No API costs. Same interface.

---

📦 Real-World Usage

Fitz is a foundation. It handles document ingestion and grounded retrieval—you build whatever sits on top: chatbots, dashboards, alerts, or automation.

Chatbot Backend 🤖

Connect fitz to Slack, Discord, Teams, or your own UI. One function call returns an answer with sources—no hallucinations, full provenance. You handle the conversation flow; fitz handles the knowledge.

Example: A SaaS company plugs fitz into their support bot. Tier-1 questions like "How do I reset my password?" get instant answers. Their support team focuses on edge cases while fitz deflects 60% of incoming tickets.

Internal Knowledge Base 📖

Point fitz at your company's wiki, policies, and runbooks. Employees ask natural language questions instead of hunting through folders or pinging colleagues on Slack.

Example: A 200-person startup ingests their Notion workspace and compliance docs. New hires find answers to "How do I request PTO?" on day one—no more waiting for someone in HR to respond.

Continuous Intelligence & Alerting (Watchdog) 🐶

Pair fitz with cron, Airflow, or Lambda. Ingest data on a schedule, run queries automatically, trigger alerts when conditions match. Fitz provides the retrieval primitive; you wire the automation.

Example: A security team ingests SIEM logs nightly. Every morning, a scheduled job asks "Were there failed logins from unusual locations?" If fitz finds evidence, an alert fires to the on-call channel before anyone checks email.

Web Knowledge Base 🌎

Scrape the web with Scrapy, BeautifulSoup, or Playwright. Save to disk, ingest with fitz. The web becomes a queryable knowledge base.

Example: A football analytics hobbyist scrapes Premier League match reports. After ingesting, they ask "How did Arsenal perform against top 6 teams?" or "What tactics did Liverpool use in away games?"—insights that would take hours to compile manually.

Codebase Search 🐍

Fitz includes built-in AST-aware chunking for Python. Functions, classes, and modules become individual searchable units with docstrings and imports preserved. Ask questions in natural language; get answers pointing to specific code.

Example: A team inherits a legacy Django monolith—200k lines, sparse docs. They ingest the codebase and ask "Where is user authentication handled?" or "What API endpoints modify the billing table?" New developers onboard in days instead of weeks.

---

📦 Architecture

┌───────────────────────────────────────────────────────────────┐
│                         fitz-ai                               │
├───────────────────────────────────────────────────────────────┤
│  CLI Layer                                                    │
│  quickstart | init | ingest | query | chat | config | doctor  │
├───────────────────────────────────────────────────────────────┤
│  Engines                                                      │
│  ┌───────────────┐  ┌───────────┐                             │
│  │  Classic RAG  │  │   CLaRa   │  (pluggable)                │
│  └───────────────┘  └───────────┘                             │
├───────────────────────────────────────────────────────────────┤
│  Plugin System (all YAML-defined)                             │
│  ┌────────┐ ┌───────────┐ ┌────────┐ ┌──────────┐             │
│  │  LLM   │ │ Embedding │ │ Rerank │ │ VectorDB │             │
│  └────────┘ └───────────┘ └────────┘ └──────────┘             │
│  openai, cohere, anthropic, ollama, azure...                  │
├───────────────────────────────────────────────────────────────┤
│  Retrieval Pipelines (YAML-composed)                          │
│  dense.yaml | dense_rerank.yaml | custom...                   │
├───────────────────────────────────────────────────────────────┤
│  Enrichment (opt-in)                                          │
│  code artifacts | LLM summaries | hierarchical RAG | custom   │
├───────────────────────────────────────────────────────────────┤
│  Constraints (epistemic safety)                               │
│  ConflictAware | InsufficientEvidence | CausalAttribution     │
└───────────────────────────────────────────────────────────────┘

---

📦 CLI Reference

fitz quickstart [PATH] [QUESTION]    # Zero-config RAG (start here)
fitz init                            # Interactive setup wizard
fitz ingest                          # Interactive ingestion
fitz query                           # Single question with sources
fitz chat                            # Multi-turn conversation with your knowledge base
fitz collections                     # List and delete knowledge collections
fitz config                          # View/edit configuration
fitz doctor                          # System diagnostics

---

📦 Beyond RAG

RAG is a method. Knowledge access is a strategy.

Fitz is not a RAG framework. It's a knowledge platform that currently uses RAG as its primary engine.

from fitz_ai import run

# Today: Classic RAG
answer = run("What are the payment terms?", engine="classic_rag")

# Also available: CLaRa (compressed RAG, 16x smaller context)
answer = run("What are the payment terms?", engine="clara")

# Tomorrow: GraphRAG, HyDE, or whatever comes next
answer = run("What are the payment terms?", engine="graph_rag")

The engine is an implementation detail. Your ingested knowledge, your queries, your workflow—all stay the same. When a better retrieval paradigm emerges, swap one line, not your entire codebase.

---

📦 Philosophy

Principles:

• Explicit over clever: No magic. Read the config, know what happens.
• Answers over architecture: Optimize for time-to-insight, not flexibility.
• Honest over helpful: Better to say "I don't know" than hallucinate.
• Files over frameworks: YAML plugins over class hierarchies.

---

License

MIT

---

Links

• GitHub
• PyPI
• Changelog
• CLI Documentation