fitz-ai 0.3.4__tar.gz

fitz_ai-0.3.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yan Fitzner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fitz_ai-0.3.4/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: fitz-ai
+Version: 0.3.4
+Summary: A modular, production-ready engine platform with clean architecture and comprehensive observability.
+Author: Yan Fitzner
+License: MIT
+Project-URL: Homepage, https://github.com/yafitzdev/fitz-ai
+Project-URL: Repository, https://github.com/yafitzdev/fitz-ai
+Project-URL: Issues, https://github.com/yafitzdev/fitz-ai/issues
+Project-URL: Changelog, https://github.com/yafitzdev/fitz-ai/blob/main/CHANGELOG.md
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: qdrant-client>=1.7
+Requires-Dist: httpx>=0.24
+Requires-Dist: typing-extensions>=4.7
+Requires-Dist: typer>=0.9
+Requires-Dist: jinja2>=3.1
+Provides-Extra: ingest
+Requires-Dist: pdfminer.six; extra == "ingest"
+Requires-Dist: python-docx; extra == "ingest"
+Provides-Extra: local
+Requires-Dist: ollama>=0.1.0; extra == "local"
+Requires-Dist: faiss-cpu>=1.7.0; extra == "local"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: isort>=5.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Dynamic: license-file
+
+# fitz-ai
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-0.3.3-green.svg)](CHANGELOG.md)
+
+## 🎯 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
+
+```bash
+pip install fitz-ai
+```
+
+```python
+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.
+
+```python
+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.
+
+```python
+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
+
+```bash
+# 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](docs/ENGINES.md) | Choosing and using engines
+- [Architecture](docs/architecture.md) | Deep dive for contributors
+- [Changelog](CHANGELOG.md) | Release history
+
+---
+
+## 📄 License
+
+MIT

fitz_ai-0.3.4/README.md

@@ -0,0 +1,235 @@
+# fitz-ai
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-0.3.3-green.svg)](CHANGELOG.md)
+
+## 🎯 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
+
+```bash
+pip install fitz-ai
+```
+
+```python
+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.
+
+```python
+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.
+
+```python
+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
+
+```bash
+# 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](docs/ENGINES.md) | Choosing and using engines
+- [Architecture](docs/architecture.md) | Deep dive for contributors
+- [Changelog](CHANGELOG.md) | Release history
+
+---
+
+## 📄 License
+
+MIT

fitz_ai-0.3.4/fitz_ai/__init__.py

@@ -0,0 +1,139 @@
+"""
+Fitz - Local-First RAG Framework & Engine Platform
+
+Fitz is a paradigm-agnostic knowledge engine platform that supports multiple
+approaches to knowledge retrieval and synthesis (Classic RAG, CLaRa, custom engines).
+
+Quick Start:
+    >>> from fitz import run
+    >>> answer = run("What is quantum computing?")
+    >>> print(answer.text)
+
+Public API:
+    Core Types:
+        - Query: Input to engines
+        - Answer: Output from engines
+        - Provenance: Source attribution
+        - Constraints: Query-time constraints
+
+    Runtime:
+        - run: Universal entry point (any engine)
+        - create_engine: Factory for creating engines
+        - list_engines: List available engines
+
+    Classic RAG:
+        - run_classic_rag: RAG-specific entry point
+        - create_classic_rag_engine: RAG engine factory
+
+Architecture:
+    fitz_ai/
+    ├── core/              # Paradigm-agnostic contracts
+    ├── engines/           # Engine implementations
+    │   └── classic_rag/   # Retrieval-augmented generation
+    ├── runtime/           # Multi-engine orchestration
+    ├── llm/               # LLM service (chat, embedding, rerank)
+    ├── vector_db/         # Vector database service
+    └── ingest/            # Document ingestion
+
+Philosophy:
+    Knowledge → Engine → Answer
+
+    Engines are black boxes that transform queries into answers.
+    The platform only cares about the interface, not the implementation.
+
+Examples:
+    Simple query:
+    >>> from fitz import run
+    >>> answer = run("What is quantum computing?")
+
+    With constraints:
+    >>> from fitz import run, Constraints
+    >>> constraints = Constraints(max_sources=5)
+    >>> answer = run("Explain entanglement", constraints=constraints)
+
+    Specific engine:
+    >>> answer = run("What is X?", engine="classic_rag")
+
+    Reusable engine:
+    >>> from fitz import create_engine, Query
+    >>> engine = create_engine("classic_rag")
+    >>> query = Query(text="What is Y?")
+    >>> answer = engine.answer(query)
+"""
+
+__version__ = "0.3.0"
+
+# =============================================================================
+# CORE TYPES
+# =============================================================================
+
+from fitz_ai.core import (  # Protocol; Types; Exceptions
+    Answer,
+    ConfigurationError,
+    Constraints,
+    EngineError,
+    GenerationError,
+    KnowledgeEngine,
+    KnowledgeError,
+    Provenance,
+    Query,
+    QueryError,
+    TimeoutError,
+    UnsupportedOperationError,
+)
+from fitz_ai.engines.classic_rag import (
+    ClassicRagEngine,
+    create_classic_rag_engine,
+    run_classic_rag,
+)
+from fitz_ai.runtime import (
+    create_engine,
+    get_engine_registry,
+    list_engines,
+    list_engines_with_info,
+    run,
+)
+
+# =============================================================================
+# RUNTIME (UNIVERSAL)
+# =============================================================================
+
+
+# =============================================================================
+# CLASSIC RAG (CONVENIENCE)
+# =============================================================================
+
+
+# =============================================================================
+# PUBLIC API
+# =============================================================================
+
+__all__ = [
+    # Version
+    "__version__",
+    # Core Protocol
+    "KnowledgeEngine",
+    # Core Types
+    "Query",
+    "Answer",
+    "Provenance",
+    "Constraints",
+    # Core Exceptions
+    "EngineError",
+    "QueryError",
+    "KnowledgeError",
+    "GenerationError",
+    "ConfigurationError",
+    "TimeoutError",
+    "UnsupportedOperationError",
+    # Universal Runtime
+    "run",
+    "create_engine",
+    "list_engines",
+    "list_engines_with_info",
+    "get_engine_registry",
+    # Classic RAG
+    "run_classic_rag",
+    "create_classic_rag_engine",
+    "ClassicRagEngine",
+]

fitz_ai-0.3.4/fitz_ai/backends/__init__.py

@@ -0,0 +1,16 @@
+# fitz_ai/backends/local_llm/__init__.py
+from __future__ import annotations
+
+from fitz_ai.backends.local_llm.chat import LocalChatConfig, LocalChatLLM
+from fitz_ai.backends.local_llm.runtime import LocalLLMRuntime, LocalLLMRuntimeConfig
+
+__all__ = [
+    "LocalLLMRuntime",
+    "LocalLLMRuntimeConfig",
+    "LocalChatLLM",
+    "LocalChatConfig",
+    "LocalEmbedder",
+    "LocalEmbedderConfig",
+    "LocalReranker",
+    "LocalRerankerConfig",
+]