defossil 0.0.1__tar.gz

defossil-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pybass
+
+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.

defossil-0.0.1/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: defossil
+Version: 0.0.1
+Summary: Improve your English by reviewing your own chats with AI coding agents.
+Author: pybass
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Education
+Requires-Dist: fastapi>=0.141.1
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: markupsafe>=3.0.3
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: uvicorn>=0.52.3
+Requires-Python: >=3.14
+Project-URL: Repository, https://github.com/pybass/defossil
+Project-URL: Issues, https://github.com/pybass/defossil/issues
+Description-Content-Type: text/markdown
+
+# defossil
+
+**Status: prototype.** No tests yet; anything can change without backward compatibility.
+
+Improve your English by reviewing your own chats with AI coding agents. The name comes from "fossilized errors" — recurring mistakes that stick in a learner's language. You already write a lot of English when talking to agents like Claude Code and Codex. defossil collects those messages, reviews them with an LLM, and gives you two things:
+
+- **Corrections** — one per mistake: your fragment, the fix, and a short note on how to say it better.
+- **Reports** — the most valuable part. A short lesson over many corrections: the mistakes you repeat, the native-language patterns in your phrasing, shorter ways to say what you keep saying long — real examples from your own text. Fast to read and a realistic picture of your English.
+
+## How it works
+
+One background thread — the pipeline — runs the whole chain every 5 minutes: collect → classify → review → report. Nothing else creates corrections or reports, so both tables are append-only and no step races another. The dashboard only shows what the pipeline did.
+
+1. **Collect** — archive every message you typed, verbatim, into SQLite, deduplicated by the source's own key. Only real typed text: tool output, command expansions, and programmatic runs are skipped. Sources: Claude Code and Codex CLI; one module per source.
+2. **Classify** — stamp each new message `pending` / `non-english` / `too-short` / `no-prose` / `too-long`, once. Only `pending` goes to review; the text itself is never rewritten.
+3. **Review** — send `pending` messages to the LLM in batches, store what it corrects — real mistakes and style (wordiness, calques, register) — as corrections, and stamp the messages `reviewed`. A message is reviewed once, ever. On the dashboard a correction can be acknowledged, and the explain button asks the LLM for a deeper explanation.
+4. **Report** — a markdown lesson over each `corrections_per_report` corrections: repeated mistakes, native-language patterns, shorter phrasings, one focus habit until the next report. Reports are stored and never regenerated.
+
+## Architecture
+
+`web` → `Core` → feature service → `Db`. `Core` is a container and the lifecycle: it opens the database, builds one service per feature, starts them in order and stops them in reverse. A feature is one job, named after the record it owns: `message` (the archive and its sources), `correction`, `report`, `setting`, and `ai` — every prompt the app sends, plus the `ai_calls` log of what each call cost. Every table has exactly one owner, and only the owner writes SQL against it. Features reach each other through `self.core.services.<other>`.
+
+The schema evolves through append-only migrations (`core/migrations.py`, tracked by `PRAGMA user_version`), so it can change without dropping data. Nothing is redone: a message is classified and reviewed once, corrections and reports only accumulate. The archive is the one thing the sources cannot give back (Claude Code deletes transcripts after ~30 days), and nothing drops it.
+
+## Usage
+
+Python, FastAPI, SQLite. LLM calls go through the `claude` CLI by default (`claude -p` — works with a Claude subscription, no API key); a setting switches to `codex exec`. Local only: data never leaves the machine except text sent for review.
+
+Run `defossil`, open http://127.0.0.1:3677.
+
+## Settings
+
+The data root cannot live in the database it locates, so it is the one setting outside it: `~/.local/share/defossil` by default, overridden only by `--data-dir`. Everything else — native language, AI backend, model and effort per prompt category, source roots, batch sizes, page size — lives in the `settings` table, is edited on the dashboard's settings page, and is read at use time, so a change applies without a restart.
+
+## Non-goals
+
+Decided against — do not re-propose or implement:
+
+- **Exercises** — drills, quizzes, flashcards, spaced repetition built from the stored mistakes. The app shows mistakes and writes reports, nothing more.
+- **Dismissing false positives** — a "not a mistake" flag. Premature: the archive shows no false positives yet.
+- **Fossils page** — a page grouping corrections by category and fragment. Fragments group only when they repeat verbatim, so it adds little over the corrections page and the report.
+
+## License
+
+[MIT](LICENSE)

defossil-0.0.1/README.md

@@ -0,0 +1,45 @@
+# defossil
+
+**Status: prototype.** No tests yet; anything can change without backward compatibility.
+
+Improve your English by reviewing your own chats with AI coding agents. The name comes from "fossilized errors" — recurring mistakes that stick in a learner's language. You already write a lot of English when talking to agents like Claude Code and Codex. defossil collects those messages, reviews them with an LLM, and gives you two things:
+
+- **Corrections** — one per mistake: your fragment, the fix, and a short note on how to say it better.
+- **Reports** — the most valuable part. A short lesson over many corrections: the mistakes you repeat, the native-language patterns in your phrasing, shorter ways to say what you keep saying long — real examples from your own text. Fast to read and a realistic picture of your English.
+
+## How it works
+
+One background thread — the pipeline — runs the whole chain every 5 minutes: collect → classify → review → report. Nothing else creates corrections or reports, so both tables are append-only and no step races another. The dashboard only shows what the pipeline did.
+
+1. **Collect** — archive every message you typed, verbatim, into SQLite, deduplicated by the source's own key. Only real typed text: tool output, command expansions, and programmatic runs are skipped. Sources: Claude Code and Codex CLI; one module per source.
+2. **Classify** — stamp each new message `pending` / `non-english` / `too-short` / `no-prose` / `too-long`, once. Only `pending` goes to review; the text itself is never rewritten.
+3. **Review** — send `pending` messages to the LLM in batches, store what it corrects — real mistakes and style (wordiness, calques, register) — as corrections, and stamp the messages `reviewed`. A message is reviewed once, ever. On the dashboard a correction can be acknowledged, and the explain button asks the LLM for a deeper explanation.
+4. **Report** — a markdown lesson over each `corrections_per_report` corrections: repeated mistakes, native-language patterns, shorter phrasings, one focus habit until the next report. Reports are stored and never regenerated.
+
+## Architecture
+
+`web` → `Core` → feature service → `Db`. `Core` is a container and the lifecycle: it opens the database, builds one service per feature, starts them in order and stops them in reverse. A feature is one job, named after the record it owns: `message` (the archive and its sources), `correction`, `report`, `setting`, and `ai` — every prompt the app sends, plus the `ai_calls` log of what each call cost. Every table has exactly one owner, and only the owner writes SQL against it. Features reach each other through `self.core.services.<other>`.
+
+The schema evolves through append-only migrations (`core/migrations.py`, tracked by `PRAGMA user_version`), so it can change without dropping data. Nothing is redone: a message is classified and reviewed once, corrections and reports only accumulate. The archive is the one thing the sources cannot give back (Claude Code deletes transcripts after ~30 days), and nothing drops it.
+
+## Usage
+
+Python, FastAPI, SQLite. LLM calls go through the `claude` CLI by default (`claude -p` — works with a Claude subscription, no API key); a setting switches to `codex exec`. Local only: data never leaves the machine except text sent for review.
+
+Run `defossil`, open http://127.0.0.1:3677.
+
+## Settings
+
+The data root cannot live in the database it locates, so it is the one setting outside it: `~/.local/share/defossil` by default, overridden only by `--data-dir`. Everything else — native language, AI backend, model and effort per prompt category, source roots, batch sizes, page size — lives in the `settings` table, is edited on the dashboard's settings page, and is read at use time, so a change applies without a restart.
+
+## Non-goals
+
+Decided against — do not re-propose or implement:
+
+- **Exercises** — drills, quizzes, flashcards, spaced repetition built from the stored mistakes. The app shows mistakes and writes reports, nothing more.
+- **Dismissing false positives** — a "not a mistake" flag. Premature: the archive shows no false positives yet.
+- **Fossils page** — a page grouping corrections by category and fragment. Fragments group only when they repeat verbatim, so it adds little over the corrections page and the report.
+
+## License
+
+[MIT](LICENSE)

defossil-0.0.1/pyproject.toml

@@ -0,0 +1,87 @@
+[project]
+name = "defossil"
+version = "0.0.1"
+description = "Improve your English by reviewing your own chats with AI coding agents."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.14"
+classifiers = [
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Education",
+]
+dependencies = [
+    "fastapi>=0.141.1",
+    "jinja2>=3.1.6",
+    "markupsafe>=3.0.3",
+    "pydantic>=2.13.4",
+    "uvicorn>=0.52.3",
+]
+
+[[project.authors]]
+name = "pybass"
+
+[project.urls]
+Repository = "https://github.com/pybass/defossil"
+Issues = "https://github.com/pybass/defossil/issues"
+
+[project.scripts]
+defossil = "defossil.__main__:main"
+
+[build-system]
+requires = ["uv_build>=0.12,<0.13"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "ruff~=0.16.3",
+    "mypy~=2.3.1",
+    "pip-audit~=2.10.1",
+    "deptry~=0.25.1",
+    "pre-commit~=4.6.2",
+    "watchfiles~=1.2.0",
+]
+
+[tool.uv]
+required-version = ">=0.12"
+
+[tool.ruff]
+line-length = 130
+target-version = "py314"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812",
+    "D203",
+    "D213",
+    "PLC0414",
+    "RET503",
+    "G004",
+    "FIX",
+    "FBT",
+    "EM",
+    "CPY",
+    "TC",
+    "TRY003",
+    "C901",
+    "PLR0911",
+    "PLR0912",
+    "PLR0913",
+    "PLR2004",
+    "ASYNC109",
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true
+
+[tool.mypy]
+python_version = "3.14"
+strict = true
+
+[tool.deptry.per_rule_ignores]
+DEP002 = ["jinja2"]

defossil-0.0.1/pyproject.toml.orig

@@ -0,0 +1,126 @@
+# ============================================================================
+#  Project metadata
+# ============================================================================
+[project]
+name = "defossil"
+version = "0.0.1"
+description = "Improve your English by reviewing your own chats with AI coding agents."
+readme = "README.md"
+authors = [{ name = "pybass" }]
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.14"
+classifiers = [
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Education",
+]
+dependencies = [
+    "fastapi>=0.141.1",
+    "jinja2>=3.1.6",
+    "markupsafe>=3.0.3",
+    "pydantic>=2.13.4",
+    "uvicorn>=0.52.3",
+]
+
+[project.urls]
+Repository = "https://github.com/pybass/defossil"
+Issues = "https://github.com/pybass/defossil/issues"
+
+[project.scripts]
+defossil = "defossil.__main__:main"
+
+# ============================================================================
+#  Build system
+# ============================================================================
+[build-system]
+requires = ["uv_build>=0.12,<0.13"]  # pinned: backends live outside uv.lock — an open range breaks reproducible tag builds
+build-backend = "uv_build"
+
+
+# ============================================================================
+#  Development dependencies — grouped by role (mirrors the tool sections below)
+# ============================================================================
+[dependency-groups]
+dev = [
+    # Linting & formatting
+    "ruff~=0.16.3",
+    # Type checking
+    "mypy~=2.3.1",
+    # Security & vulnerability audit
+    "pip-audit~=2.10.1",
+    # Dependency hygiene — imports vs declared deps
+    "deptry~=0.25.1",
+    # Git pre-commit hooks
+    "pre-commit~=4.6.2",
+    # Dev-server auto-restart (justfile `dev`)
+    "watchfiles~=1.2.0",
+]
+
+
+# ============================================================================
+#  uv
+# ============================================================================
+[tool.uv]
+required-version = ">=0.12"  # refuse a uv too old for the lock/sync behaviors the justfile relies on
+
+
+# ============================================================================
+#  Ruff — linting & formatting
+# ============================================================================
+[tool.ruff]
+line-length = 130
+target-version = "py314"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    # --- Ecosystem / tool conflicts ---
+    "COM812",   # redundant and incompatible with ruff format
+    "D203",     # one-blank-line-before-class — conflicts with D211
+    "D213",     # multi-line-summary-second-line — conflicts with D212
+
+    # --- Stylistic preferences ---
+    "PLC0414",  # useless-import-alias — `import x as x` is our explicit re-export marker
+    "RET503",   # implicit-return — explicit None returns are noisy
+    "G004",     # f-strings in logging — accepted
+
+    # --- Categories that fight our coding style ---
+    "FIX",      # flake8-fixme — TODOs are fine; tracked elsewhere
+    "FBT",      # boolean-trap — too restrictive
+    "EM",       # error-message strings — inline messages accepted
+    "CPY",      # flake8-copyright — no copyright headers
+    "TC",       # flake8-type-checking — TYPE_CHECKING blocks save import time we don't care about; cost: import noise + broken runtime annotations (pydantic)
+    "TRY003",   # raise-vanilla-args — too noisy
+    "C901",     # complex-structure — judgment call
+
+    # --- Soft pylint thresholds ---
+    "PLR0911",  # too-many-return-statements
+    "PLR0912",  # too-many-branches
+    "PLR0913",  # too-many-arguments
+    "PLR2004",  # magic-value-comparison
+
+    # --- Async edge case ---
+    "ASYNC109", # async-function-with-timeout — debatable, off
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true
+
+
+# ============================================================================
+#  Type checking — mypy (strict)
+# ============================================================================
+[tool.mypy]
+python_version = "3.14"
+strict = true
+
+
+# ============================================================================
+#  deptry — imports vs declared deps
+# ============================================================================
+[tool.deptry.per_rule_ignores]
+DEP002 = ["jinja2"]  # used only through fastapi.templating (an optional fastapi extra), never imported directly

defossil-0.0.1/src/defossil/__init__.py

@@ -0,0 +1 @@
+"""defossil — improve your English by reviewing your own chats with AI coding agents."""

defossil-0.0.1/src/defossil/__main__.py

@@ -0,0 +1,38 @@
+"""Entry point: defossil runs the web dashboard."""
+
+import argparse
+import logging
+from importlib.metadata import version
+from pathlib import Path
+
+import uvicorn
+
+from defossil.core.core import Core
+from defossil.web.app import create_app
+
+
+def main() -> None:
+    """Parse arguments and run the web dashboard."""
+    parser = argparse.ArgumentParser(prog="defossil", description="Improve your English by reviewing your chats with AI agents.")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {version('defossil')}")
+    parser.add_argument("--port", type=int, default=3677, help="dashboard port on 127.0.0.1")
+    parser.add_argument(
+        "--data-dir", type=Path, default=Core.DEFAULT_DATA_DIR, help="data root (default: ~/.local/share/defossil)"
+    )
+    args = parser.parse_args()
+    # uvicorn configures its own loggers and leaves the root one bare, which would drop every line the workers log.
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+    logging.getLogger("defossil").info(f"dashboard: http://127.0.0.1:{args.port}")
+    # log_config=None routes uvicorn's records to our root handler; warnings and errors still show, its chatter does not.
+    uvicorn.run(
+        create_app(Core(args.data_dir)),
+        host="127.0.0.1",
+        port=args.port,
+        log_config=None,
+        log_level="warning",
+        access_log=False,
+    )
+
+
+if __name__ == "__main__":
+    main()

defossil-0.0.1/src/defossil/core/__init__.py

@@ -0,0 +1 @@
+"""The application core: configuration, storage, and one service per feature."""

defossil-0.0.1/src/defossil/core/core.py

@@ -0,0 +1,68 @@
+"""Composition root — the single object the CLI and the web app work through."""
+
+from pathlib import Path
+
+from defossil.core.db import Db
+from defossil.core.features.ai.service import AiService
+from defossil.core.features.correction.service import CorrectionService
+from defossil.core.features.message.service import MessageService
+from defossil.core.features.report.service import ReportService
+from defossil.core.features.setting.service import SettingService
+from defossil.core.pipeline import Pipeline
+from defossil.core.service import Service
+
+
+class Services:
+    """Every feature service in one namespace, so `core.*` stays the storage and `core.services.*` the work.
+
+    Plain fields, listed by hand: a service is added here and nowhere else. The pipeline sits last so it starts
+    after every service it drives and stops before them.
+    """
+
+    def __init__(self, core: Core) -> None:
+        """Build one service per feature over *core*. None of them may touch another while this runs."""
+        self.setting = SettingService(core)
+        self.ai = AiService(core)
+        self.message = MessageService(core)
+        self.correction = CorrectionService(core)
+        self.report = ReportService(core)
+        self.pipeline = Pipeline(core)
+        # Read off the fields above, so a service is still added in one place.
+        self._services: list[Service] = [value for value in vars(self).values() if isinstance(value, Service)]
+
+    def start_all(self) -> None:
+        """Start the services in the order they were built."""
+        for service in self._services:
+            service.on_start()
+
+    def stop_all(self) -> None:
+        """Stop them in the reverse order, so nothing is torn down under a service still using it."""
+        for service in reversed(self._services):
+            service.on_stop()
+
+
+class Core:
+    """A container, not a layer with behaviour: it owns the storage and the feature services over it.
+
+    A client builds one Core and calls `core.services.correction.get_corrections(...)`; nothing here forwards that call.
+    Core is also the lifecycle: `start` is what lets the pipeline run in the background, and only the server calls it.
+    """
+
+    # Where the data lives without --data-dir. A fixed path, never read from the environment:
+    # a variable exported for some other tool must not move the archive.
+    DEFAULT_DATA_DIR = Path.home() / ".local" / "share" / "defossil"
+
+    def __init__(self, data_dir: Path) -> None:
+        """Open the database under *data_dir* and build the services over it. Nothing runs yet."""
+        data_dir.mkdir(parents=True, exist_ok=True)
+        self.db = Db(data_dir / "defossil.db")
+        self.services = Services(self)
+
+    def start(self) -> None:
+        """Start every service; nothing runs in the background before this."""
+        self.services.start_all()
+
+    def stop(self) -> None:
+        """Stop the services, then close the database — in that order, or the pipeline outlives its connection."""
+        self.services.stop_all()
+        self.db.close()

defossil-0.0.1/src/defossil/core/db.py

@@ -0,0 +1,55 @@
+"""SQLite storage: the connection and the migration runner.
+
+It runs no query of its own — a table's SQL belongs to its feature, and the schema lives in migrations.py.
+"""
+
+import sqlite3
+import threading
+from collections.abc import Generator
+from contextlib import contextmanager
+from pathlib import Path
+
+from defossil.core.migrations import MIGRATIONS
+
+
+class Db:
+    """The one connection every feature service runs its own SQL on."""
+
+    def __init__(self, path: Path) -> None:
+        """Open the database and apply pending migrations; the directory must exist (Core makes it)."""
+        # autocommit=True gives every lone statement its own transaction, so a write is never left hanging in an
+        # implicit one. check_same_thread=False because fastapi serves sync handlers from a threadpool, so a request
+        # is not handled by the thread that opened this connection.
+        self.conn = sqlite3.connect(path, autocommit=True, check_same_thread=False)
+        self.conn.row_factory = sqlite3.Row
+        self._migrate()
+        self._write_lock = threading.Lock()
+
+    def close(self) -> None:
+        """Close the connection."""
+        self.conn.close()
+
+    def _migrate(self) -> None:
+        """Apply pending migrations, tracked via PRAGMA user_version."""
+        version = int(self.conn.execute("PRAGMA user_version").fetchone()[0])
+        for number, script in enumerate(MIGRATIONS[version:], start=version + 1):
+            # The script and the version bump commit together: a crash mid-migration rolls back cleanly, so a
+            # migration is either fully applied and recorded, or not at all.
+            self.conn.executescript(f"BEGIN;\n{script}\nPRAGMA user_version = {number};\nCOMMIT;")
+
+    @contextmanager
+    def transaction(self) -> Generator[sqlite3.Connection]:
+        """Run one or more statements as a single transaction; every write goes through here, reads need not.
+
+        One at a time, under the lock: the connection is shared by the request threadpool, the pipeline worker and
+        the explain pool, so a lone autocommit write could join another thread's open transaction and be rolled
+        back with it, and overlapping transactions would nest and commit each other's rows.
+        """
+        with self._write_lock:
+            self.conn.execute("BEGIN")
+            try:
+                yield self.conn
+            except Exception:
+                self.conn.execute("ROLLBACK")
+                raise
+            self.conn.execute("COMMIT")

defossil-0.0.1/src/defossil/core/errors.py

@@ -0,0 +1,17 @@
+"""Errors Core raises on purpose. Each client maps them to its own vocabulary — HTTP status, exit code."""
+
+
+class DefossilError(Exception):
+    """Base of everything Core raises deliberately, so a client can catch the whole family."""
+
+
+class NotFoundError(DefossilError):
+    """A record was asked for by id and does not exist."""
+
+
+class InvalidOperationError(DefossilError):
+    """The operation a caller asked for would break a rule of the model."""
+
+
+class AiError(DefossilError):
+    """A backend call failed or its answer could not be read; the same ask can be retried later."""

defossil-0.0.1/src/defossil/core/features/__init__.py

@@ -0,0 +1 @@
+"""One package per feature: the record it owns, its table, and every operation over both."""

defossil-0.0.1/src/defossil/core/features/ai/__init__.py

@@ -0,0 +1 @@
+"""AI: the backend contract and the CLIs behind it, every prompt the app sends, and the log of what each query cost."""

defossil-0.0.1/src/defossil/core/features/ai/backends.py

@@ -0,0 +1,85 @@
+"""The backend contract, both CLI implementations, and the one place a name from the settings becomes a backend.
+
+A failed call raises to the caller, which decides whether that is recorded or fatal. A missing CLI binary is not
+that: it is the machine being wrong, and it stops the run.
+"""
+
+import json
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Protocol
+
+from defossil.core.features.ai.models import AiResponse
+
+
+class AiBackend(Protocol):
+    """One prompt in, the answer with its metadata out; what is asked and how it is read is the caller's."""
+
+    def send_prompt(self, prompt: str, model: str, effort: str) -> AiResponse:
+        """Answer *prompt* on *model* at *effort*; a failed call raises to the caller."""
+        ...
+
+
+class ClaudeBackend:
+    """Answers a prompt by running the `claude` CLI in print mode."""
+
+    def send_prompt(self, prompt: str, model: str, effort: str) -> AiResponse:
+        """Run `claude -p` over *prompt* with the given model and effort."""
+        claude_bin = shutil.which("claude")
+        if claude_bin is None:
+            raise RuntimeError("claude CLI not found in PATH")
+        # Hooks are for interactive sessions: without this they fire on every call (sounds, prompt-injecting hooks).
+        argv = [claude_bin, "-p", "--output-format", "json", "--settings", '{"disableAllHooks": true}']
+        argv += ["--model", model, "--effort", effort]
+        result = subprocess.run(  # noqa: S603 -- fixed argv, resolved binary, no shell; nothing user-controlled is executed
+            argv, input=prompt, capture_output=True, text=True, check=True
+        )
+        answer = json.loads(result.stdout)
+        usage = answer.get("usage")
+        # modelUsage also lists the CLI's internal haiku helper calls; the answer comes from the model that wrote the most.
+        model_usage = answer.get("modelUsage") or {}
+        return AiResponse(
+            reply=str(answer["result"]).strip(),
+            model=max(model_usage, key=lambda m: model_usage[m].get("outputTokens") or 0, default=None),
+            # Cache writes and reads are counted in: with `claude -p` almost the whole prompt lands there.
+            input_tokens=sum(
+                usage.get(k) or 0 for k in ("input_tokens", "cache_creation_input_tokens", "cache_read_input_tokens")
+            )
+            if usage
+            else None,
+            output_tokens=usage.get("output_tokens") if usage else None,
+            cost_usd=answer.get("total_cost_usd"),
+        )
+
+
+class CodexBackend:
+    """Answers a prompt by running the `codex` CLI non-interactively; the CLI reports no usable usage metadata."""
+
+    def send_prompt(self, prompt: str, model: str, effort: str) -> AiResponse:
+        """Run `codex exec` over *prompt*; tokens and cost stay None — only the machine-readable answer file comes back."""
+        codex_bin = shutil.which("codex")
+        if codex_bin is None:
+            raise RuntimeError("codex CLI not found in PATH")
+        # --ephemeral keeps the run out of ~/.codex/sessions, so the collector never re-ingests defossil's own prompts.
+        with tempfile.TemporaryDirectory() as tmp:
+            answer_file = Path(tmp) / "answer.txt"
+            flags = ["--skip-git-repo-check", "--ephemeral", "--sandbox", "read-only", "-o", str(answer_file)]
+            flags += ["--model", model, "-c", f"model_reasoning_effort={effort}"]
+            argv = [codex_bin, "exec", *flags, "-"]
+            subprocess.run(  # noqa: S603 -- fixed argv, resolved binary, no shell; the prompt only travels over stdin
+                argv, input=prompt, capture_output=True, text=True, check=True
+            )
+            return AiResponse(reply=answer_file.read_text().strip())
+
+
+def build_backend(name: str) -> AiBackend:
+    """Return the backend *name* names; an unknown name stops the run."""
+    match name:
+        case "claude":
+            return ClaudeBackend()
+        case "codex":
+            return CodexBackend()
+        case _:
+            raise ValueError(f"Unknown AI backend {name!r}: use claude or codex")