factq 0.1.0__tar.gz

factq-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,75 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  quality-gates:
+    name: Quality Gates
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Lint (ruff)
+        run: uv run ruff check src/ tests/
+
+      - name: Type check (mypy)
+        run: uv run mypy src/
+
+      - name: Test (pytest)
+        run: uv run pytest tests/ -v --cov=src --cov-report=term-missing
+
+  publish:
+    name: Publish to PyPI
+    needs: quality-gates
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      id-token: write
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/factq/
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

factq-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+.python-version
+
+# Testing & coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Secrets & env
+.env
+.env.*
+!.env.example

factq-0.1.0/CLAUDE.md

@@ -0,0 +1,159 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working on the factq CLI project.
+
+## Project Overview
+
+**factq** — Your LLM's Local Source of Truth. A local-first knowledge base and verification engine. Python library + CLI + MCP server. Distributed via PyPI (`pip install factq`).
+
+**Key interfaces:** CLI (`factq`), Python library (`import factq`), MCP server (planned).
+
+## Quick Reference
+
+```bash
+# Quality gates (run before completing any task)
+uv run ruff check src/ tests/    # Lint (auto-fix: --fix)
+uv run mypy src/                 # Type check (strict)
+uv run pytest tests/ -v          # Tests
+
+# All quality gates at once
+uv run ruff check src/ tests/ && uv run mypy src/ && uv run pytest tests/ -v
+
+# CLI testing
+uv run factq --version
+uv run factq init
+uv run factq query "test question"
+```
+
+## Architecture
+
+See `docs/ARCHITECTURE.md` for full details.
+
+### Resolution Pipeline
+
+```
+Query → KB Lookup (docs/ folder, milliseconds)
+  → Deepthink (LLM writes Python to verify, sandbox execution, up to 5 iterations)
+    → Commit (verified fact saved back to docs/, git-versioned)
+```
+
+### Project Structure
+
+```
+factq-cli/
+├── src/factq/           # Core package (hatchling, src layout)
+│   ├── __init__.py      # Package root, version
+│   ├── cli.py           # Click CLI entry point
+│   └── py.typed         # PEP 561 type stub marker
+├── tests/               # Pytest test suite
+├── docs/                # Project documentation
+│   ├── ARCHITECTURE.md  # Technical architecture
+│   └── adr/             # Architecture Decision Records
+├── pyproject.toml       # Project config (Python 3.12+, Apache-2.0)
+└── CLAUDE.md            # This file
+```
+
+### Key Dependencies
+
+| Tool | Purpose |
+|------|---------|
+| **uv** | Package manager, venv (Python 3.12) |
+| **hatchling** | Build backend |
+| **click** | CLI framework |
+| **rich** | Terminal formatting |
+| **pydantic** | Data models |
+| **ruff** | Linter |
+| **mypy** | Type checker (strict mode) |
+| **pytest** | Test runner |
+
+## Common Commands
+
+Always use `uv run python` or `uv run pytest` — never bare `python` or `pytest`.
+
+```bash
+# Install dependencies
+uv sync
+
+# Lint
+uv run ruff check src/ tests/
+
+# Type check
+uv run mypy src/
+
+# Run tests
+uv run pytest tests/ -v
+
+# Run tests with coverage
+uv run pytest tests/ -v --cov=src --cov-report=term-missing
+
+# Build package
+uv run python -m build
+```
+
+## Quality Gates
+
+**All must pass before task completion:**
+
+| Gate | Command | Requirement |
+|------|---------|-------------|
+| Lint | `uv run ruff check src/ tests/` | Zero errors |
+| Types | `uv run mypy src/` | Zero errors |
+| Tests | `uv run pytest tests/ -v` | All pass |
+
+**If any fail, you are NOT DONE.**
+
+## Code Style & Conventions
+
+- **Python 3.12+**, line length 100
+- Type annotations required on all functions (mypy strict)
+- Ruff rules: `E, F, I, N, UP, B, SIM, TCH`
+- License: Apache-2.0
+- Only add dependencies with permissive licenses (Apache 2.0, MIT, BSD)
+
+### Python Conventions
+
+```python
+from __future__ import annotations    # 1. Future
+import sys                            # 2. Stdlib
+from pydantic import BaseModel        # 3. Third-party
+from factq.core import Engine         # 4. Local
+```
+
+- Classes: `PascalCase` | Functions/variables: `snake_case` | Constants: `UPPER_SNAKE_CASE`
+- Prefer `list[str]` over `List[str]`, `str | None` over `Optional[str]`
+- Commit format: `<type>: <description>` (feat/fix/test/refactor/docs/chore)
+
+## Development Principles
+
+### Red / Green / Refactor — MANDATORY
+
+| Phase | Action |
+|-------|--------|
+| RED | Write failing test first |
+| GREEN | Minimal code to pass |
+| REFACTOR | Clean up, tests stay green |
+
+### SOLID
+
+| Principle | Rule |
+|-----------|------|
+| **S**ingle Responsibility | One class, one job |
+| **O**pen/Closed | Extend via composition |
+| **L**iskov Substitution | Subtypes honor contracts |
+| **I**nterface Segregation | Focused interfaces |
+| **D**ependency Inversion | Depend on abstractions |
+
+## Git Rules
+
+- NEVER commit without explicit user request
+- NEVER add Co-Authored-By lines
+- NEVER amend unless explicitly asked
+- Stage specific files, not `git add -A`
+
+## Key Documents
+
+| Document | Purpose |
+|----------|---------|
+| `docs/ARCHITECTURE.md` | Technical architecture and component design |
+| `docs/adr/` | Architecture Decision Records |
+| `docs/adr/001-rlm-over-rag.md` | Why RLM over RAG |

factq-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: factq
+Version: 0.1.0
+Summary: Your LLM's Local Source of Truth — a local-first knowledge base and verification engine for hallucination prevention.
+Project-URL: Homepage, https://factq.dev
+Project-URL: Documentation, https://factq.dev
+Project-URL: Repository, https://github.com/factq-dev/factq-cli
+Project-URL: Issues, https://github.com/factq-dev/factq-cli/issues
+Project-URL: Changelog, https://github.com/factq-dev/factq-cli/blob/main/CHANGELOG.md
+Author: FactQ Team
+License: Apache-2.0
+Keywords: factuality,hallucination,knowledge-base,llm,mcp,rlm,verification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# factq
+
+**Your LLM's Local Source of Truth**
+
+A local-first knowledge base and verification engine that sits between you and your AI tools. It answers from proven knowledge first, validates through executable code when needed, and gets smarter with every query.
+
+## Install
+
+```bash
+pip install factq
+```
+
+## Quick Start
+
+```python
+import factq
+
+# Initialize from project root — auto-indexes docs/ folder
+fq = factq.init(".")
+
+# Query checks project docs first, then KB, then Deepthink
+result = fq.query("What version of Pydantic does our project use?")
+# result.source: 'docs' | 'kb' | 'deepthink'
+
+# Save a verified finding to the project's docs/ folder
+fq.save("docs/research/pydantic_v2_migration.md", result)
+```
+
+Or from the CLI:
+
+```bash
+factq init                                    # index current project
+factq query "What is our database schema?"    # docs-first resolution
+factq save docs/research/schema_notes.md      # commit a finding
+```
+
+## How It Works
+
+```
+Query → KB Lookup (docs/ folder, milliseconds)
+  → Deepthink (LLM writes Python to verify, sandbox execution)
+    → Commit (verified fact saved back to docs/, git-versioned)
+```
+
+1. **Docs-First Resolution** — Your project's `docs/` folder is the first source of truth
+2. **Executable Verification** — When docs can't answer, factq writes and runs Python code to verify facts in a secure sandbox
+3. **Self-Growing Knowledge** — Verified facts are saved back as markdown files, version-controlled in git
+4. **MCP Server** — Runs as a local MCP server for Claude Code, Cursor, and Windsurf
+
+## Why factq?
+
+| | Traditional RAG | Cloud Search | **factq** |
+|---|---|---|---|
+| **Verification** | Text similarity | Citation links | Executable code proof |
+| **Infrastructure** | 3-6 GB VRAM | Cloud API | Zero VRAM, ~28 MB |
+| **Knowledge Persistence** | Ephemeral chunks | None | Git-versioned docs/ |
+| **Offline** | Partial | No | **Fully offline** |
+| **Gets Smarter Over Time** | No | No | **Yes** |
+
+## Development
+
+```bash
+git clone https://github.com/factq-dev/factq-cli.git
+cd factq-cli
+uv sync
+uv run pytest tests/ -v
+```
+
+## License
+
+Apache-2.0

factq-0.1.0/README.md

@@ -0,0 +1,71 @@
+# factq
+
+**Your LLM's Local Source of Truth**
+
+A local-first knowledge base and verification engine that sits between you and your AI tools. It answers from proven knowledge first, validates through executable code when needed, and gets smarter with every query.
+
+## Install
+
+```bash
+pip install factq
+```
+
+## Quick Start
+
+```python
+import factq
+
+# Initialize from project root — auto-indexes docs/ folder
+fq = factq.init(".")
+
+# Query checks project docs first, then KB, then Deepthink
+result = fq.query("What version of Pydantic does our project use?")
+# result.source: 'docs' | 'kb' | 'deepthink'
+
+# Save a verified finding to the project's docs/ folder
+fq.save("docs/research/pydantic_v2_migration.md", result)
+```
+
+Or from the CLI:
+
+```bash
+factq init                                    # index current project
+factq query "What is our database schema?"    # docs-first resolution
+factq save docs/research/schema_notes.md      # commit a finding
+```
+
+## How It Works
+
+```
+Query → KB Lookup (docs/ folder, milliseconds)
+  → Deepthink (LLM writes Python to verify, sandbox execution)
+    → Commit (verified fact saved back to docs/, git-versioned)
+```
+
+1. **Docs-First Resolution** — Your project's `docs/` folder is the first source of truth
+2. **Executable Verification** — When docs can't answer, factq writes and runs Python code to verify facts in a secure sandbox
+3. **Self-Growing Knowledge** — Verified facts are saved back as markdown files, version-controlled in git
+4. **MCP Server** — Runs as a local MCP server for Claude Code, Cursor, and Windsurf
+
+## Why factq?
+
+| | Traditional RAG | Cloud Search | **factq** |
+|---|---|---|---|
+| **Verification** | Text similarity | Citation links | Executable code proof |
+| **Infrastructure** | 3-6 GB VRAM | Cloud API | Zero VRAM, ~28 MB |
+| **Knowledge Persistence** | Ephemeral chunks | None | Git-versioned docs/ |
+| **Offline** | Partial | No | **Fully offline** |
+| **Gets Smarter Over Time** | No | No | **Yes** |
+
+## Development
+
+```bash
+git clone https://github.com/factq-dev/factq-cli.git
+cd factq-cli
+uv sync
+uv run pytest tests/ -v
+```
+
+## License
+
+Apache-2.0

factq-0.1.0/docs/ARCHITECTURE.md

@@ -0,0 +1,101 @@
+# Architecture
+
+## Overview
+
+factq is a local-first knowledge base and verification engine. It intercepts LLM queries, resolves them against proven local knowledge, and falls back to executable verification when the knowledge base cannot answer.
+
+## Resolution Pipeline
+
+```
+User Query
+  │
+  ▼
+┌─────────────────┐
+│  Phase 0: KB    │  Check docs/ folder and indexed knowledge base
+│  Lookup         │  Returns in milliseconds if found
+└────────┬────────┘
+         │ miss
+         ▼
+┌─────────────────┐
+│  Phase 1:       │  LLM generates Python code to retrieve
+│  Generate       │  and verify the fact from external sources
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Phase 2:       │  Code runs in sandbox. Errors trigger
+│  Validate       │  self-correction. Up to 5 iterations.
+└────────┬────────┘
+         │ verified
+         ▼
+┌─────────────────┐
+│  Phase 3:       │  Verified result offered for commit
+│  Commit         │  to docs/. KB grows with every query.
+└─────────────────┘
+```
+
+## Component Architecture
+
+```
+factq/
+├── cli.py              # Click CLI entry point
+├── core/
+│   ├── engine.py       # Query orchestrator (KB → Deepthink → Commit)
+│   ├── kb.py           # Knowledge base: indexing, search, persistence
+│   └── result.py       # Query result model (answer, source, confidence)
+├── deepthink/
+│   ├── generator.py    # Code generation for fact verification
+│   ├── sandbox.py      # Secure execution environment
+│   └── validator.py    # Output validation and retry logic
+├── indexer/
+│   ├── markdown.py     # Markdown file parser and indexer
+│   └── store.py        # Index storage (local SQLite or flat files)
+├── mcp/
+│   └── server.py       # MCP server for Claude Code, Cursor, Windsurf
+└── adapters/
+    └── llm.py          # LLM backend abstraction (local, API)
+```
+
+## Key Design Decisions
+
+### RLM Over RAG
+
+factq uses the Recursive Language Model paradigm instead of traditional RAG. The LLM writes code to navigate and verify knowledge rather than relying on embedding-based similarity search. This eliminates 3-6 GB of VRAM overhead from embedding models and vector databases.
+
+### Local-First
+
+All data stays on the user's machine. The knowledge base is plain markdown files in `docs/`, version-controlled in git. No cloud dependency, no API keys required for core functionality.
+
+### Sandbox Security
+
+Five-layer defense-in-depth for Deepthink code execution:
+1. Safe builtins (restricted Python runtime)
+2. AST validation (block dangerous constructs)
+3. Function whitelisting (approved stdlib only)
+4. Execution timeouts (hard kill after N seconds)
+5. Output truncation (prevent memory exhaustion)
+
+### MCP Integration
+
+factq runs as a local MCP server so AI coding tools can call `factq.query()` as a tool. The MCP interface is a thin wrapper around the core engine.
+
+## Data Flow
+
+```
+docs/ folder (markdown) ──┐
+                          ├──► KB Index ──► Query Engine ──► Result
+External sources ─────────┘        ▲                │
+                                   │                ▼
+                              Deepthink ◄──── Sandbox
+                              (generate)      (execute)
+```
+
+## Dependencies
+
+| Layer | Dependencies | Rationale |
+|-------|-------------|-----------|
+| Core | pydantic, pyyaml | Data models, config |
+| CLI | click, rich | Terminal interface |
+| Deepthink | (stdlib only) | Sandbox uses restricted Python |
+| MCP | mcp (optional) | Protocol server |
+| LLM | (pluggable) | Adapter pattern for backends |

factq-0.1.0/docs/adr/001-rlm-over-rag.md

@@ -0,0 +1,35 @@
+# ADR-001: Use RLM Over RAG for Knowledge Retrieval
+
+## Status
+
+Accepted
+
+## Context
+
+Traditional RAG (Retrieval-Augmented Generation) requires embedding models (3-6 GB VRAM), vector databases, and chunk-based similarity search. This creates significant infrastructure overhead and produces results based on text similarity rather than verified truth.
+
+The Recursive Language Model (RLM) paradigm (Zhang, Kraska, Khattab 2025) treats knowledge as variables to be explored programmatically. Instead of embedding and retrieving chunks, the LLM writes code to navigate, read, and cross-reference knowledge sources.
+
+## Decision
+
+factq uses RLM instead of RAG for knowledge retrieval and verification. The LLM generates Python code to:
+
+1. Navigate the knowledge base structure
+2. Read and parse relevant documents
+3. Cross-reference multiple sources
+4. Verify facts through executable code
+
+Code execution happens in a sandboxed environment with five layers of security.
+
+## Consequences
+
+**Easier:**
+- Zero VRAM overhead (no embedding models or vector databases)
+- Deterministic verification (code either produces the answer or fails)
+- Handles dependency chains that similarity search cannot follow
+- Works fully offline with no cloud infrastructure
+
+**Harder:**
+- Requires a capable LLM backend for code generation
+- Sandbox security must be maintained rigorously
+- Latency is higher than vector similarity search for simple lookups (mitigated by KB cache)

factq-0.1.0/docs/adr/README.md

@@ -0,0 +1,13 @@
+# Architecture Decision Records
+
+This directory contains Architecture Decision Records (ADRs) for the factq project.
+
+## Index
+
+| ADR | Title | Status | Date |
+|-----|-------|--------|------|
+| [001](001-rlm-over-rag.md) | Use RLM over RAG for knowledge retrieval | Accepted | 2026-02-28 |
+
+## Template
+
+Use `TEMPLATE.md` when creating new ADRs. Number sequentially (e.g., `002-title.md`).

factq-0.1.0/docs/adr/TEMPLATE.md

@@ -0,0 +1,17 @@
+# ADR-NNN: Title
+
+## Status
+
+Proposed | Accepted | Deprecated | Superseded by [ADR-NNN](NNN-title.md)
+
+## Context
+
+What is the issue that we're seeing that is motivating this decision or change?
+
+## Decision
+
+What is the change that we're proposing and/or doing?
+
+## Consequences
+
+What becomes easier or more difficult to do because of this change?

factq-0.1.0/pyproject.toml

@@ -0,0 +1,85 @@
+[project]
+name = "factq"
+version = "0.1.0"
+description = "Your LLM's Local Source of Truth — a local-first knowledge base and verification engine for hallucination prevention."
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.12"
+authors = [{ name = "FactQ Team" }]
+keywords = [
+    "llm",
+    "hallucination",
+    "verification",
+    "knowledge-base",
+    "rlm",
+    "mcp",
+    "factuality",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "click>=8.1",
+    "rich>=13.0",
+    "pydantic>=2.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+mcp = [
+    "mcp>=1.0",
+]
+
+[project.urls]
+Homepage = "https://factq.dev"
+Documentation = "https://factq.dev"
+Repository = "https://github.com/factq-dev/factq-cli"
+Issues = "https://github.com/factq-dev/factq-cli/issues"
+Changelog = "https://github.com/factq-dev/factq-cli/blob/main/CHANGELOG.md"
+
+[project.scripts]
+factq = "factq.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/factq"]
+
+[tool.uv]
+dev-dependencies = [
+    "pytest>=8.0",
+    "pytest-cov>=6.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.9",
+    "mypy>=1.14",
+    "pre-commit>=4.0",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "SIM", "TCH"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra -q"

factq-0.1.0/src/factq/__init__.py

@@ -0,0 +1,3 @@
+"""factq — Your LLM's Local Source of Truth."""
+
+__version__ = "0.1.0"