lore-llm 0.1.0__tar.gz

lore_llm-0.1.0/.github/workflows/catalog-refresh.yml

@@ -0,0 +1,44 @@
+name: Refresh model catalog
+
+on:
+  schedule:
+    - cron: "17 6 * * 1" # weekly, Monday 06:17 UTC
+  workflow_dispatch: {}
+
+jobs:
+  refresh:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+      - name: Check catalog entries against the Ollama registry
+        id: refresh
+        run: |
+          set +e
+          uv run --with httpx --with pyyaml python scripts/refresh_model_catalog.py
+          code=$?
+          set -e
+          if [ "$code" = "2" ]; then
+            echo "registry unreachable; skipping this run"
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "changed=$([ "$code" = "1" ] && echo true || echo false)" >> "$GITHUB_OUTPUT"
+      - name: Open update PR
+        if: steps.refresh.outputs.changed == 'true'
+        uses: peter-evans/create-pull-request@v6
+        with:
+          branch: bot/catalog-refresh
+          title: "Model catalog refresh: registry availability changed"
+          commit-message: "Refresh model catalog against the Ollama registry"
+          body: >
+            Automated weekly check of `src/lore/models_catalog.yaml` against
+            the Ollama registry. Entries whose tags no longer resolve are
+            marked `available: false` (and vice versa). Review and merge —
+            the catalog is curated, never silently self-modified.
+          labels: automated

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

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+      - run: uv sync --dev
+      - name: ruff lint
+        run: uv run ruff check .
+      - name: ruff format
+        run: uv run ruff format --check .
+      - name: mypy (strict)
+        run: uv run mypy
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --dev
+      - name: unit tests (integration tests requiring Ollama are skipped)
+        run: uv run pytest -m "not requires_ollama" -q

lore_llm-0.1.0/.github/workflows/docker.yml

@@ -0,0 +1,43 @@
+name: Docker image
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    paths: ["deploy/**", "src/**", "pyproject.toml"]
+
+jobs:
+  image:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - name: Log in to GHCR
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Image metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=ref,event=tag
+            type=raw,value=latest,enable={{is_default_branch}}
+      - name: Build (and push on main/tags)
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: deploy/Dockerfile
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

lore_llm-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,73 @@
+name: Release
+
+# Cut a release by pushing a version tag (see docs/RELEASING.md):
+#   git tag v0.1.0 && git push origin v0.1.0
+# Pipeline: full checks → build → publish to PyPI (trusted publishing,
+# no tokens) → GitHub release with the artifacts attached.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+      - run: uv sync --dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy
+      - run: uv run pytest -m "not requires_ollama" -q
+      - name: Tag must match the project version
+        run: |
+          v=$(uv run python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "v$v" != "$GITHUB_REF_NAME" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match pyproject version v$v"
+            exit 1
+          fi
+
+  build:
+    needs: checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # OIDC for PyPI trusted publishing — no API tokens
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

lore_llm-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Environments
+.venv/
+venv/
+
+# Tooling caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Editors
+.idea/
+.vscode/
+*.swp
+
+# Lore runtime state (never commit a live home dir)
+.lore/
+*.db
+*.db-wal
+*.db-shm

lore_llm-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.5.7
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

lore_llm-0.1.0/CLAUDE.md

@@ -0,0 +1,333 @@
+# Project: Sage — Local-First LLM Instance Framework
+
+> **RENAMED (2026-07-06): the framework is now "Lore"** — CLI command `lore`,
+> PyPI distribution `lore-llm`, home dir `~/.lore`, default port 5673
+> (L-O-R-E on a phone keypad), env vars `LORE_*`. "Sage" below is the
+> historical working name; this document is kept as the original design spec.
+> Current sequencing lives in `docs/ROADMAP.md`.
+
+> **Working name.** "Sage" is a placeholder — rename freely. One word, easy to type as a CLI command.
+
+This document is the authoritative context for implementing Sage. Read it fully before writing any code. It defines the vision, architecture, design decisions (with rationale), the phased PR plan, and the engineering conventions this project must follow.
+
+---
+
+## 1. Vision
+
+Sage is a framework for deploying, managing, and specializing LLM instances — locally first, cloud optionally — without sending private data to commercial AI providers or paying per-token.
+
+A user should be able to:
+
+1. **Deploy a model with one command**, locally (`sage up`) or to a cloud target (`sage deploy --target <cloud>`).
+2. **Create named, specialized instances** of a model, each grounded in a private knowledge base (datasheets, source code, AOU documents, coding standards).
+3. **Chat with an instance** from the CLI or a web UI, with responses grounded in and cited against the instance's knowledge base.
+4. **Configure response strictness** — a confidence/grounding threshold below which the instance must refuse, hedge, or flag uncertainty instead of answering.
+5. **Retain memory per instance across runs** (local or cloud), with explicit user-controlled deletion.
+6. **Tweak everything via YAML** (CLI-first), with full feature parity in the web frontend.
+
+### Motivating use cases (acceptance scenarios)
+
+These three scenarios define "done" for the MVP. Every architectural decision should be sanity-checked against them.
+
+- **UC-1: Datasheet expert.** Point an instance at a processor datasheet set (e.g., Qualcomm SA8775 docs, multi-thousand-page PDFs). Ask detailed technical questions; get accurate, cited answers with page/section references.
+- **UC-2: AOU gap analysis.** Point an instance at a source tree plus an Assumptions-of-Use document. Ask it to cross-reference: which AOUs are implemented, which are missing, which are partially/incorrectly handled. Output a structured gap report.
+- **UC-3: Code-quality agent.** An instance specialized for unit test generation and static-analysis triage against a Parasoft or SonarQube-based project, following project conventions it learned from the knowledge base.
+
+### Non-goals (v1)
+
+- **No model fine-tuning / weight training in v1.** "Training" an instance means RAG (retrieval-augmented generation) over its knowledge base plus persistent memory — not gradient updates. Fine-tuning (LoRA adapters via e.g. `unsloth` or `axolotl`) is a v2+ phase; the `Instance` abstraction must not preclude it, but do not build it now.
+- **No multi-user auth/tenancy in v1.** Single user, local trust boundary. Cloud deploys get a single API token.
+- **No support for closed-source cloud LLM APIs as the primary path.** An OpenAI-compatible provider adapter exists for flexibility/testing, but the design center is local + self-hosted.
+
+---
+
+## 2. Core concepts
+
+| Concept | Definition |
+|---|---|
+| **Provider** | A backend that serves model inference. v1: Ollama (primary), llama.cpp server, vLLM, generic OpenAI-compatible endpoint. Swappable via YAML. |
+| **Model** | A concrete model identifier on a provider (e.g., `qwen2.5:32b-instruct` on Ollama). |
+| **Instance** | The central abstraction. A named, persistent specialization = model + knowledge base(s) + memory store + behavior config (system prompt, accuracy gate, citation policy). Instances are what users chat with. |
+| **Knowledge Base (KB)** | An ingested, chunked, embedded document/code corpus. KBs are independent objects; an instance can mount one or more. Re-ingestable and versioned. |
+| **Memory** | Per-instance persistent state across sessions: conversation summaries, user-stated facts/preferences, and instance-learned notes. Stored locally, fully inspectable, deletable on command. |
+| **Accuracy Gate** | A configurable grounding/confidence threshold governing when the instance answers vs. refuses/hedges. See §4.3 — this is *not* a magic accuracy dial; the semantics matter. |
+| **Session** | One conversation thread with an instance. Sessions feed memory (via summarization) but are distinct from it. |
+
+---
+
+## 3. Architecture
+
+```
+                ┌───────────────────────────────────────────────┐
+                │                  Clients                      │
+                │  sage CLI (Typer)      Web UI (React, later)  │
+                └──────────────┬────────────────┬───────────────┘
+                               │  (same API)    │
+                        ┌──────▼────────────────▼──────┐
+                        │        sage-server           │
+                        │   FastAPI  (REST + SSE)      │
+                        ├──────────────────────────────┤
+                        │  Instance Manager            │
+                        │  Session Manager             │
+                        │  Accuracy Gate / Verifier    │
+                        │  Citation Assembler          │
+                        ├──────────┬──────────┬────────┤
+                        │ RAG      │ Memory   │Provider│
+                        │ Pipeline │ Layer    │Adapters│
+                        └────┬─────┴────┬─────┴───┬────┘
+                             │          │         │
+                     ┌───────▼───┐ ┌────▼────┐ ┌──▼──────────────┐
+                     │ Vector DB │ │ SQLite  │ │ Ollama / vLLM / │
+                     │ (Chroma / │ │ (memory,│ │ llama.cpp /     │
+                     │  Qdrant)  │ │ configs,│ │ OpenAI-compat   │
+                     └───────────┘ │ sessions│ └─────────────────┘
+                                   └─────────┘
+```
+
+**Key structural decision: the CLI is a thin client of the local server.** The CLI does not implement chat/RAG logic itself; it talks to `sage-server` over HTTP (auto-starting it if needed, like `ollama` does). This guarantees CLI/web feature parity by construction — both are clients of one API — and makes the cloud story trivial: a cloud deploy is the same server on a remote box.
+
+### 3.1 Tech stack
+
+| Layer | Choice | Rationale |
+|---|---|---|
+| Language | Python 3.11+ | Ecosystem for RAG/embeddings; user preference for tooling. |
+| CLI | Typer + Rich | Modern, typed, good help text, pretty terminal output. |
+| Server | FastAPI + Uvicorn | Async, SSE streaming, OpenAPI schema for free (web UI consumes it). |
+| Config | YAML + Pydantic v2 models | Every config file validates against a Pydantic schema; schema errors are user-facing and precise. |
+| Vector store | ChromaDB (embedded) default; Qdrant adapter for scale/cloud | Chroma = zero-ops local. Qdrant when a KB outgrows it or for cloud. Behind a `VectorStore` interface. |
+| Relational store | SQLite (WAL mode) | Instances, sessions, memory, KB manifests. Single file per Sage home dir; trivial backup. |
+| Embeddings | Local via Ollama (`nomic-embed-text` / `bge-m3`) or `sentence-transformers` | No data leaves the machine. Pluggable. |
+| Inference providers | Ollama (primary), llama.cpp server, vLLM, OpenAI-compatible | Behind a `Provider` interface; see §4.4. |
+| Doc parsing | PyMuPDF (PDF), `unstructured` fallback, tree-sitter (code), plain parsers (md/txt/rst) | Datasheets are PDF-heavy; code KBs need syntax-aware chunking. |
+| Web UI (Phase 5) | React + Vite, consuming the FastAPI OpenAPI schema | Deferred until CLI proves the workflows. |
+| Packaging | `uv` + `pyproject.toml`; single `pipx install sage` target | One-command install. |
+| Cloud deploy | Dockerfile + compose; `sage deploy` wraps provisioning for a v1 target (Fly.io or a bare VPS via SSH) | One command, but honest: v1 supports ONE cloud target well rather than five badly. |
+
+### 3.2 Repository layout
+
+```
+sage/
+├── CLAUDE.md                    # this file
+├── pyproject.toml
+├── docs/
+│   ├── design/                  # ADRs — one per significant decision
+│   └── lessons.md               # running lessons log (see §7)
+├── src/sage/
+│   ├── cli/                     # Typer app; thin HTTP client of the server
+│   ├── server/
+│   │   ├── api/                 # FastAPI routers (instances, kb, chat, memory, config)
+│   │   ├── core/                # instance manager, session manager
+│   │   ├── rag/                 # ingestion, chunking, embedding, retrieval, reranking
+│   │   ├── verify/              # accuracy gate: grounding checks, self-consistency, citation assembly
+│   │   ├── memory/              # memory store, summarizer, deletion
+│   │   └── providers/           # ollama.py, llamacpp.py, vllm.py, openai_compat.py + base.py
+│   ├── config/                  # Pydantic schemas for all YAML files
+│   └── store/                   # SQLite + vector store interfaces and impls
+├── tests/
+│   ├── unit/
+│   ├── integration/             # against a real local Ollama (marked, skippable in CI)
+│   └── fixtures/                # sample PDFs, code trees, AOU docs for UC-1/2/3
+└── deploy/
+    ├── Dockerfile
+    └── compose.yaml
+```
+
+---
+
+## 4. Design decisions and rationale
+
+### 4.1 RAG-first, not fine-tuning-first
+
+"Feed it a datasheet and it becomes an expert" is achieved in v1 by high-quality RAG: parsing → structure-aware chunking → embedding → hybrid retrieval (dense + BM25) → optional reranking → grounded generation with citations. This is the right call because:
+
+- Fine-tuning on a datasheet teaches *style*, not reliable *facts*; RAG with citations gives verifiable answers, which is the whole point of the accuracy requirement.
+- KB updates (datasheet rev 2.1 → 2.2) become a re-ingest, not a re-train.
+- It keeps v1 shippable on a single workstation GPU/CPU.
+
+The `Instance` schema reserves an `adapters:` field (unused in v1) so LoRA support can arrive later without a breaking change.
+
+### 4.2 Knowledge bases are versioned and swappable
+
+Each ingest produces an immutable KB **snapshot** with a content hash and manifest (source files, parser versions, chunking params, embedding model). An instance mounts a KB by name at a pinned snapshot or `latest`. This gives:
+
+- Clean rollback when a new datasheet rev has errors.
+- Reproducibility: an answer can be traced to KB snapshot + chunk IDs.
+- Instance history survives KB swaps — memory and sessions live separately from KBs.
+
+### 4.3 The Accuracy Gate — honest semantics
+
+**Be direct about this in the implementation and the docs: no system can guarantee "≥85% accurate responses."** Accuracy is only measurable against ground truth after the fact. What we *can* build — and what the user's requirement actually operationalizes to — is a **grounding and confidence gate**:
+
+1. **Grounding check (primary).** After generation, verify each factual claim in the draft answer is supported by retrieved chunks. Implementation: a second lightweight verification pass ("judge" call to the same or a smaller model) scoring claim⇄chunk support. Compute a grounding score ∈ [0,1].
+2. **Retrieval confidence.** If top-k retrieval similarity scores are weak (below a floor), the KB likely doesn't contain the answer → refuse early with "not in my knowledge base," *before* generation.
+3. **Self-consistency (optional, expensive, off by default).** Sample N=3 answers at temperature; measure agreement.
+
+The YAML knob:
+
+```yaml
+accuracy:
+  min_grounding_score: 0.85      # gate on the grounding check
+  on_below_threshold: refuse     # refuse | hedge | answer_with_warning
+  require_citations: true        # every factual claim must carry chunk citations
+  retrieval_floor: 0.35          # refuse pre-generation if retrieval is this weak
+  self_consistency:
+    enabled: false
+    samples: 3
+```
+
+`refuse` responses must say *why* (weak retrieval vs. failed grounding) and show the nearest chunks found, so the user can judge whether the KB is missing material or the question is out of scope. This is the anti-hallucination ("ghosting") mechanism: the instance is structurally prevented from confidently asserting unsupported claims when the gate is on.
+
+### 4.4 Provider abstraction
+
+```python
+class Provider(ABC):
+    async def list_models(self) -> list[ModelInfo]: ...
+    async def pull(self, model: str) -> AsyncIterator[PullProgress]: ...
+    async def chat(self, req: ChatRequest) -> AsyncIterator[ChatChunk]: ...  # streaming
+    async def embed(self, texts: list[str], model: str) -> list[list[float]]: ...
+    async def health(self) -> ProviderHealth: ...
+```
+
+All four v1 adapters (Ollama, llama.cpp, vLLM, OpenAI-compatible) implement this. Instance YAML selects provider + model; switching is a config edit, nothing else. The OpenAI-compatible adapter doubles as the escape hatch for any hosted endpoint the user chooses to trust.
+
+**Recommended default models (document in README, don't hardcode):**
+
+- General instruct, 16–24 GB VRAM class: `qwen2.5:32b-instruct` (or 14b for smaller GPUs)
+- Code-heavy instances (UC-2, UC-3): `qwen2.5-coder:32b`
+- Small/fast judge model for grounding checks: `qwen2.5:7b` or `llama3.1:8b`
+- Embeddings: `nomic-embed-text` (fast) or `bge-m3` (better multilingual/long-doc)
+
+These are defaults, not requirements — the whole point is that they're YAML.
+
+### 4.5 Memory design
+
+Per-instance memory, three tiers, all in SQLite, all inspectable:
+
+1. **Session transcripts** — raw, per session.
+2. **Rolling summaries** — each session is summarized on close (or every N turns) into compact memory entries; these are injected into future system prompts within a token budget.
+3. **Pinned facts** — user-stated ("remember that our target is SA8797 rev B") or explicitly promoted from summaries.
+
+Commands / API:
+
+```
+sage memory show <instance>              # full, human-readable dump
+sage memory pin  <instance> "fact..."
+sage memory forget <instance> --entry <id>
+sage memory wipe <instance> [--sessions] [--all]   # explicit, confirmed deletion
+```
+
+`wipe --all` deletes memory rows *and* runs `VACUUM` so the data is actually gone from the SQLite file, not just unlinked. Memory sync for cloud instances is out of scope for v1 (cloud instance has its own memory on its own volume); a export/import command (`sage memory export/import`) covers migration.
+
+### 4.6 Config: YAML everywhere, one schema
+
+Global config: `~/.sage/config.yaml`. Per-instance config: `~/.sage/instances/<name>/instance.yaml`. Every file validates against Pydantic schemas in `src/sage/config/`; the web UI edits the same objects via the API. Example instance file:
+
+```yaml
+name: sa8775-expert
+provider: ollama
+model: qwen2.5:32b-instruct
+system_prompt: |
+  You are an expert on the Qualcomm SA8775 platform. Answer strictly from
+  the mounted knowledge base. Cite sections for every factual claim.
+knowledge_bases:
+  - name: sa8775-docs
+    snapshot: latest
+accuracy:
+  min_grounding_score: 0.85
+  on_below_threshold: refuse
+  require_citations: true
+memory:
+  enabled: true
+  summary_every_n_turns: 12
+  max_memory_tokens: 2000
+generation:
+  temperature: 0.2
+  max_tokens: 2048
+```
+
+### 4.7 CLI surface (v1 target)
+
+```
+sage init                                  # create ~/.sage, global config
+sage up | down | status                    # local server lifecycle
+sage models list | pull <model>
+sage instance create <name> [--from instance.yaml]
+sage instance list | show | edit | delete <name>
+sage kb create <name> --source <path> [--source ...]   # ingest files/dirs
+sage kb update <name> | list | show <name> | snapshots <name>
+sage chat <instance>                       # interactive REPL, streaming, citations rendered
+sage ask  <instance> "question" [--json]   # one-shot, scriptable
+sage memory show|pin|forget|wipe <instance>
+sage analyze aou --code <dir> --aou <file> --instance <name>   # UC-2 workflow command
+sage deploy --target <name> | sage deploy status|destroy       # Phase 4
+sage doctor                                # env/provider/GPU diagnostics
+```
+
+---
+
+## 5. Phased implementation plan
+
+Rules: every PR is small, independently mergeable, and leaves `main` green. Each PR lists its own verification steps; **do not mark a PR done until its verification steps have actually been run and pass.** Integration tests that need a live Ollama are marked `@pytest.mark.requires_ollama` and skipped in CI, but must be run locally before merging PRs that touch inference paths.
+
+### Phase 0 — Skeleton & foundations (PRs 1–4)
+
+- **PR-1**: Repo scaffold. `pyproject.toml` (uv), `src/sage` package layout, ruff + mypy + pytest config, pre-commit, CI workflow (lint + unit tests), empty Typer app (`sage --version`), `docs/lessons.md`. *Verify: `uv run sage --version`; CI green.*
+- **PR-2**: Config schemas. Pydantic models for global + instance + KB YAML; loader with precise validation errors; `sage init`. *Verify: unit tests for valid/invalid YAML round-trips.*
+- **PR-3**: SQLite store. Schema (instances, kbs, kb_snapshots, sessions, messages, memory_entries), migrations (simple versioned SQL), WAL mode, repository layer. *Verify: unit tests incl. migration from empty DB.*
+- **PR-4**: FastAPI server skeleton + lifecycle. `sage up/down/status`, health endpoint, CLI HTTP client base with auto-start. *Verify: `sage up && sage status && sage down`.*
+
+### Phase 1 — Providers & basic chat (PRs 5–8)
+
+- **PR-5**: `Provider` interface + Ollama adapter (chat streaming, embed, pull, health). *Verify: integration test against local Ollama.*
+- **PR-6**: Instance CRUD (API + CLI). `instance create/list/show/edit/delete`, instance.yaml materialization. *Verify: unit + CLI e2e tests.*
+- **PR-7**: Sessions + basic chat (no RAG yet). `sage chat` REPL with streaming via SSE, `sage ask`, transcripts persisted. *Verify: live chat against Ollama; transcript rows present.*
+- **PR-8**: OpenAI-compatible adapter + provider selection in instance YAML. *Verify: adapter integration test against Ollama's OpenAI-compat endpoint (no external network needed).*
+
+### Phase 2 — RAG & knowledge bases (PRs 9–13)
+
+- **PR-9**: Ingestion pipeline core. Source walker, file-type routing, PDF (PyMuPDF) + text/markdown parsers, structure-aware chunking with metadata (page, heading path). *Verify: fixture datasheet PDF chunks with correct page metadata.*
+- **PR-10**: Embedding + vector store. `VectorStore` interface, Chroma impl, embed-on-ingest, KB snapshots with content-hash manifests. *Verify: ingest fixture KB; re-ingest unchanged → same snapshot hash.*
+- **PR-11**: Retrieval. Hybrid dense + BM25, top-k merge, retrieval-floor check. *Verify: recall test on fixture Q/A pairs.*
+- **PR-12**: Grounded chat. Retrieval → prompt assembly → generation → citation assembly (chunk IDs → page/section refs rendered in CLI). Instance mounts KBs. *Verify: UC-1 smoke — ask 10 fixture questions, all answers carry correct citations.*
+- **PR-13**: Code ingestion. tree-sitter chunking for C/C++/Python, file-path metadata. *Verify: ingest a fixture C project; retrieval returns function-level chunks.*
+
+### Phase 3 — Accuracy gate & memory (PRs 14–17)
+
+- **PR-14**: Grounding verifier. Claim extraction + judge pass + grounding score; gate actions (refuse/hedge/warn) per YAML; refusal messages include nearest chunks + reason. *Verify: adversarial fixture questions (answers NOT in KB) get refused; in-KB questions pass.*
+- **PR-15**: Memory layer. Session summarization, pinned facts, token-budgeted injection, `sage memory show/pin/forget/wipe` (with VACUUM on wipe). *Verify: fact stated in session 1 is recalled in session 2; wiped memory is unrecoverable.*
+- **PR-16**: `sage analyze aou` (UC-2). Structured workflow: enumerate AOU items → per-item retrieval against code KB → implemented/partial/missing classification with cited evidence → markdown/JSON report. *Verify: fixture code tree + AOU doc produces correct gap report.*
+- **PR-17**: Self-consistency option + `sage doctor`. *Verify: doctor detects missing Ollama, missing models, GPU presence.*
+
+### Phase 4 — Deploy (PRs 18–19)
+
+- **PR-18**: Dockerfile + compose (server + Ollama + volume layout); `sage deploy` for local Docker. *Verify: `sage deploy --target docker` yields a working remote-style instance; memory persists across container restarts.*
+- **PR-19**: One real cloud target (pick: Fly.io GPU or SSH-to-VPS provisioner). `sage deploy --target <name>`, `deploy status/destroy`, token auth on the server, `memory export/import`. *Verify: end-to-end deploy, chat, destroy.*
+
+### Phase 5 — Web UI (PRs 20+)
+
+- **PR-20**: React scaffold consuming the OpenAPI schema; chat view with streaming + citation rendering.
+- **PR-21+**: Instance management UI, KB upload/ingest UI, memory browser, config editor (schema-driven forms from Pydantic → JSON Schema). Feature parity is cheap because everything is already API-first.
+
+---
+
+## 6. Testing & verification requirements
+
+- Unit tests for every module; no PR merges without tests for its new logic.
+- Fixture corpus in `tests/fixtures/`: a small public processor datasheet (or synthetic equivalent), a toy C project + hand-written AOU doc with known implemented/missing items, and Q/A ground-truth pairs for retrieval/grounding evals.
+- **Grounding eval harness** (built in PR-14, extended after): a scored set of in-KB and out-of-KB questions; track grounding-gate precision/recall across changes. This is how "accuracy" claims stay honest — measured, not asserted.
+- Sanitizer-grade discipline applies conceptually: run integration tests before claiming inference-path PRs done; never claim "verified" for anything not actually executed.
+
+## 7. Engineering conventions
+
+- Small, independently mergeable PRs per the plan above; each PR description lists verification steps actually performed.
+- Architecture changes get a short ADR in `docs/design/` before implementation.
+- Maintain `docs/lessons.md`: every non-obvious bug or wrong assumption gets an entry.
+- Python style: ruff + mypy strict on `src/`; type hints everywhere; async throughout the server.
+- Honest limitations stay documented: the accuracy gate reduces hallucination and gates on grounding — it does not and cannot guarantee a numeric accuracy percentage. Never let README copy claim otherwise.
+
+## 8. Open questions (decide before or during the relevant PR)
+
+1. Judge model for grounding: same model as generator (simpler) vs. dedicated small model (faster, cheaper)? Default: small dedicated model, configurable. (PR-14)
+2. Reranker (e.g., `bge-reranker-v2-m3`) in the retrieval path: measurable win on datasheets, adds latency. Decide with eval data. (PR-11/12)
+3. Cloud target for PR-19: Fly.io GPU vs. plain VPS+SSH. VPS is more universal; Fly is less work.
+4. Qdrant adapter timing: only when a real KB outgrows Chroma — don't build speculatively.