fitz-ai 0.3.4

A modular, production-ready engine platform with clean architecture and comprehensive observability.

fitz-ai

🎯 Stable Knowledge Access, Today and Tomorrow

fitz-ai is a knowledge access platform for teams that need reliable, configurable retrieval today, without locking themselves into a single reasoning paradigm tomorrow.

You ingest your knowledge once. How it gets queried can evolve.

---

🤔 Why fitz-ai Exists

Organizations repeatedly rebuild the same systems: ingest documents, chunk them, embed them, retrieve them, generate answers. Every time the reasoning method changes, everything breaks.

The insight: Reasoning methods evolve faster than knowledge.

• RAG today
• Compression-native models tomorrow
• Something else after that

But the knowledge layer remains.

Most RAG tools optimize one method. fitz-ai stabilizes the knowledge layer itself.

---

🧠 The Mental Model

  Your Knowledge
      ↓
  fitz-ai (Knowledge Access Layer)
      ↓
  Engines (replaceable)
      ↓
  Answer

What stays stable: Ingested documents, chunking decisions, metadata, provenance, API contracts.

What can change: Retrieval strategies, reasoning methods, model providers, compression techniques.

You optimize for stability where it matters and flexibility where change is inevitable.

---

⚖️ How fitz-ai Is Different

This isn't a critique of other tools. It's a design difference.

	LangChain & Similar	fitz-ai
Optimizes for	Flows & prompt chains	Knowledge stability
Assumes	Rapid experimentation	Systems live for years
Switching paradigms	Often means refactoring	Means changing engines
Best for	Exploring ideas	Building infrastructure

If you're exploring ideas, LangChain is excellent. If you're building infrastructure that will outlive your current model choices, fitz-ai is designed for that.

---

🚀 Quick Start

pip install fitz-ai

from fitz_ai.engines.classic_rag import run_classic_rag

answer = run_classic_rag("What does our contract say about termination?")
print(answer.text)

That's it. Classic RAG works out of the box.

---

⚙️ Engines

Engines encapsulate how knowledge is queried. They're not plugins. They're paradigms.

Classic RAG (Default) ✅

Production-ready retrieval-augmented generation.

from fitz_ai.engines.classic_rag import run_classic_rag

answer = run_classic_rag("What is our refund policy?")

for source in answer.provenance:
    print(f"{source.source_id}: {source.excerpt}")

CLaRa (Experimental) 🧪

Compression-native reasoning for large document collections. 16x to 128x compression with unified retrieval and generation.

from fitz_ai.engines.clara import create_clara_engine

engine = create_clara_engine()
engine.add_documents(my_documents)
answer = engine.answer(Query(text="What patterns emerge across these reports?"))

Engines are interchangeable. Your knowledge is not.

---

✅ When fitz-ai Makes Sense

• Internal company knowledge bases
• Compliance-sensitive environments
• Teams running local and cloud LLMs
• Long-lived systems where methods will change

❌ When fitz-ai Is Not a Fit

• Prompt-only experiments
• One-off demos
• No ingestion, no retrieval needed

---

📁 Project Structure

fitz_ai/
├── core/        # Stable contracts (Query, Answer, Provenance)
├── engines/     # Reasoning paradigms (classic_rag, clara)
├── ingest/      # Knowledge ingestion
├── runtime/     # Engine orchestration
├── llm/         # LLM plugins
└── vector_db/   # Vector DB plugins

Architecture enforces separation: engines can be added or removed without destabilizing the core.

---

💻 CLI

Core Commands

Command	Description
fitz init	Interactive setup wizard
fitz query "question"	Query your knowledge base
fitz config	Show current configuration
fitz db	List/inspect vector collections
fitz chunk ./file.txt	Preview chunking strategies
fitz doctor	System diagnostics
fitz plugins	List all available plugins

Ingestion Commands

Command	Description
fitz ingest ./docs collection	Ingest documents into collection
fitz ingest ./docs coll --chunk-size 500	Custom chunk size
fitz ingest validate ./docs	Validate before ingesting
fitz ingest plugins	List ingest plugins

Database Commands

Command	Description
fitz db	List all collections
fitz db default	Inspect 'default' collection
fitz db my_docs -n 10	Show 10 sample chunks

Chunking Preview

Command	Description
fitz chunk ./doc.txt	Preview with defaults (1000 chars)
fitz chunk ./doc.txt --size 500	Smaller chunks
fitz chunk ./docs/ --stats	Stats only, no content
fitz chunk --list	List available chunkers

Examples

# Setup and first query
fitz init
fitz ingest ./documents knowledge_base
fitz query "What are the main topics?"

# Inspect what's stored
fitz db knowledge_base

# Preview chunking before committing
fitz chunk ./large_doc.pdf --size 500 --stats

# Check system health
fitz doctor

---

📐 Design Principles

• Explicit over clever | No hidden magic
• Stable contracts | The API doesn't break when internals change
• Knowledge outlives methods | Ingest once, query many ways
• Engines are paradigms | Not just config switches

---

💡 Philosophy

RAG is a method.
Knowledge access is a strategy.

fitz-ai is built for the strategy.

---

📚 Documentation

• Engine Guide | Choosing and using engines
• Architecture | Deep dive for contributors
• Changelog | Release history

---

📄 License

MIT