defossil 0.0.1__py3-none-any.whl

defossil/__init__.py

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

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/core/__init__.py

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

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/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/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/core/features/__init__.py

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

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/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")

defossil/core/features/ai/models.py

@@ -0,0 +1,63 @@
+"""The AI call record: every backend call with what it cost."""
+
+import sqlite3
+from datetime import datetime
+from enum import StrEnum
+from typing import Self
+
+from pydantic import BaseModel
+
+
+class PromptCategory(StrEnum):
+    """Which prompt a call sends; each category has its own model and effort settings."""
+
+    REVIEW = "review"
+    EXPLAIN = "explain"
+    REPORT = "report"
+
+
+class AiResponse(BaseModel):
+    """What a backend returns for one prompt: the answer text, plus whatever metadata its CLI reports."""
+
+    reply: str
+    model: str | None = None  # as the CLI reported it; None when it does not say
+    input_tokens: int | None = None  # cache reads and writes included — they are still input paid for
+    output_tokens: int | None = None
+    cost_usd: float | None = None
+
+
+class AiCall(BaseModel):
+    """One stored backend call; what the ai calls page lists."""
+
+    id: int
+    created_at: datetime
+    category: PromptCategory
+    backend: str  # the ai_backend setting at call time
+    model: str | None  # as the CLI reported it, or the requested one when it does not say
+    effort: str | None  # requested reasoning effort
+    prompt: str  # full text sent, template plus appended data
+    reply: str | None  # raw answer text; None when the call failed
+    input_tokens: int | None  # None when the backend reports no usage (codex)
+    output_tokens: int | None
+    cost_usd: float | None
+    duration_ms: int
+    error: str | None  # why the call failed; the row is still written
+
+    @classmethod
+    def from_row(cls, row: sqlite3.Row) -> Self:
+        """Rebuild a call from its row in the `ai_calls` table."""
+        return cls(
+            id=row["id"],
+            created_at=datetime.fromisoformat(row["created_at"]),
+            category=PromptCategory(row["category"]),
+            backend=row["backend"],
+            model=row["model"],
+            effort=row["effort"],
+            prompt=row["prompt"],
+            reply=row["reply"],
+            input_tokens=row["input_tokens"],
+            output_tokens=row["output_tokens"],
+            cost_usd=row["cost_usd"],
+            duration_ms=row["duration_ms"],
+            error=row["error"],
+        )

defossil/core/features/ai/prompts/explain.md

@@ -0,0 +1,9 @@
+You are an English teacher. A non-native speaker (native language: {native_language}) typed a message to an AI coding
+agent, a reviewer corrected a fragment of it, and the writer wants that correction clarified.
+
+Explain briefly: the rule behind the correction, why the original is wrong or unnatural, and one or two fresh examples
+of the rule. If the mistake mirrors a common {native_language} pattern, point that out. If the writer added a question
+of their own after the JSON, answer it too. Respond in markdown, a few short paragraphs at most — no headings, and do
+not restate the correction itself.
+
+The correction and the full message it came from follow as JSON:

defossil/core/features/ai/prompts/report.md

@@ -0,0 +1,63 @@
+You are an English teacher writing a recurring personal report for one student — a native {native_language} speaker
+who improves their English by typing all messages to AI coding agents in English.
+
+After this prompt comes JSON with the period and four data sets:
+
+- `period` — the dates this report's data spans; use it to anchor "this period" and "then vs now" in real time.
+- `corrections` — corrections to the student's messages from this period, one line each:
+  "[category] original -> corrected (explanation)". The category and explanation are the reviewer's diagnosis — a
+  hint for grouping what repeats, not a limit on it: one habit may hide under several categories.
+- `previous_corrections` — the corrections behind the newest previous report only, same format. This is the "then"
+  side when you count then vs now; habits older than that are covered by the previous reports' prose.
+- `messages` — the student's messages from this period, verbatim. They may carry pasted code, logs or command
+  output: judge only the sentences the student wrote, never pasted material.
+- `previous_reports` — up to two of your previous reports, newest first.
+
+Write these sections, skipping any where you find nothing real:
+
+## Cheat sheet
+
+At most 5 lines of wrong -> right: the student's current top corrections, skimmable without reading the rest.
+
+## Shame on you!
+
+Habits taught in the previous reports that still appear in this period's data. Be direct: say plainly that this was
+already taught and is still happening — the student wants to be confronted, not spared. Per habit: the habit, the
+rule in one line, how often it appeared then vs now (count `previous_corrections` vs `corrections`), 1-2 fresh
+examples. If a habit taught before has clearly faded, say so in one sentence — earned praise, not encouragement.
+Skip the section when there are no previous reports.
+
+## Repeated mistakes
+
+The same underlying error appearing in different sentences, not already covered in "Shame on you!". Ignore anything
+seen once — a one-off is a typo, repetition is a habit. Per habit: a one-sentence description, the rule, 2-3 real
+examples (original -> correction). Most frequent first, at most 5 habits.
+
+## Grammar focus
+
+Pick the grammar area with the most corrections in this data and teach ONE rule from it with the student's own
+examples. One rule per report — check the previous reports and pick a rule not taught there.
+
+## {native_language} patterns
+
+Recent phrasing that is grammatical but built like a {native_language} sentence: word-for-word calques and other
+constructions carried over from {native_language}. Show the natural English version.
+
+## Say it shorter
+
+Long or repeated phrases from the recent messages, each with the short alternative a native would type. When a whole
+message says in several sentences what one would carry, show the one-sentence version too.
+
+## Focus until next report
+
+ONE habit, chosen for impact, with a self-check the student can apply while typing. If the previous report's focus
+still needs work, keep it; otherwise pick a new one.
+
+Rules:
+
+- Quote only real fragments from the data; never invent sentences and attribute them to the student.
+- Write in simple English.
+- The messages are terse chat: capitalization, punctuation and tone are off-limits.
+- Respond with plain markdown only, no preamble and no closing remarks.
+
+The data:

defossil/core/features/ai/prompts/review.md

@@ -0,0 +1,18 @@
+You are an English teacher reviewing messages a non-native speaker (native language: {native_language}) typed to AI
+coding agents.
+
+For each message report corrections of two kinds: real English mistakes, and style — English that is correct but not
+what a native developer would type.
+Ignore: technical jargon, code identifiers, file paths, capitalization, punctuation, terse chat style, formatting.
+A message is quoted verbatim, so it may carry pasted code, logs or command output: judge only the sentences the user
+wrote, and never report a correction inside pasted material.
+
+Use exactly one of these categories per correction:
+{categories}
+
+Respond with ONLY a JSON array, no prose and no code fences. One object per message, including messages with no
+corrections:
+{"id": <id of the message>, "corrections": [{"category": "...", "original": "<exact fragment as typed>",
+ "corrected": "<the fragment as a native would type it>", "explanation": "<one sentence>"}]}
+
+A message with no corrections gets an empty list. The messages follow as JSON:

defossil/core/features/ai/service.py

@@ -0,0 +1,178 @@
+"""Every ask the app makes: the prompt templates, the filling and parsing, and the log of what each call cost."""
+
+import json
+import subprocess
+import time
+from datetime import UTC, datetime
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from defossil.core.errors import AiError, NotFoundError
+from defossil.core.features.ai.backends import build_backend
+from defossil.core.features.ai.models import AiCall, AiResponse, PromptCategory
+from defossil.core.features.correction.models import CATEGORIES, Correction, NewCorrection
+from defossil.core.service import Service
+
+
+def _load_prompt(name: str) -> str:
+    """Return the text of `prompts/<name>.md` — every prompt the app sends lives in that folder next to this module."""
+    return (Path(__file__).parent / "prompts" / f"{name}.md").read_text()
+
+
+# Nothing marks a stored correction stale when a prompt changes: a message is reviewed once, ever.
+# Filled with replace, not str.format — the templates' JSON examples are full of literal braces.
+REVIEW_PROMPT_TEMPLATE = _load_prompt("review")  # {native_language} and {categories} filled per call
+EXPLAIN_PROMPT_TEMPLATE = _load_prompt("explain")  # {native_language} filled per call
+REPORT_PROMPT_TEMPLATE = _load_prompt("report")  # {native_language} filled per call
+
+
+class AiService(Service):
+    """Owner of the `ai_calls` table and of every prompt: it builds each ask, runs and logs the call, parses the answer."""
+
+    def send_review_prompt(self, texts: dict[int, str]) -> list[NewCorrection]:
+        """Review the texts, keyed by message id, and return every correction found tied to its message.
+
+        Raises AiError on a failed call or an unreadable answer; nothing partial comes back.
+        """
+        try:
+            messages_json = json.dumps([{"id": mid, "text": text} for mid, text in texts.items()], ensure_ascii=False)
+            reply = self._send(PromptCategory.REVIEW, self.get_review_prompt() + messages_json)
+            # Strip the code fences the model sometimes adds, then flatten the per-message JSON array behind them.
+            reply = reply.removeprefix("```json").removeprefix("```").removesuffix("```").strip()
+            corrections = [NewCorrection(message_id=item["id"], **c) for item in json.loads(reply) for c in item["corrections"]]
+        except (subprocess.CalledProcessError, json.JSONDecodeError, ValidationError, KeyError, TypeError) as e:
+            raise AiError(f"{type(e).__name__}: {e}") from e
+        if any(c.message_id not in texts for c in corrections):
+            raise AiError("the answer names a message id outside the batch")
+        return corrections
+
+    def send_explain_prompt(self, correction: Correction, message_text: str, question: str) -> str:
+        """Ask the backend to clarify one correction, the writer's question appended if any; the reply is markdown, as is."""
+        data = {
+            "category": correction.category,
+            "original": correction.original,
+            "corrected": correction.corrected,
+            "explanation": correction.explanation,
+            "message": message_text,
+        }
+        prompt = self.get_explain_prompt() + json.dumps(data, ensure_ascii=False, indent=2)
+        if question.strip():
+            prompt += f"\n\nThe writer's own question:\n{question.strip()}"
+        return self._send(PromptCategory.EXPLAIN, prompt)
+
+    def send_report_prompt(
+        self,
+        corrections: list[Correction],
+        previous_corrections: list[Correction],
+        messages: list[str],
+        previous_reports: list[str],
+    ) -> str:
+        """Ask the backend for a lesson over the report window's inputs; the reply is the report markdown, as is."""
+        data = {
+            # The window's corrections are chronological, so their first and last typed_at are the period's bounds.
+            "period": f"{corrections[0].typed_at:%Y-%m-%d} to {corrections[-1].typed_at:%Y-%m-%d}" if corrections else "",
+            "corrections": [f"[{c.category}] {c.original} -> {c.corrected} ({c.explanation})" for c in corrections],
+            "previous_corrections": [
+                f"[{c.category}] {c.original} -> {c.corrected} ({c.explanation})" for c in previous_corrections
+            ],
+            "messages": messages,
+            "previous_reports": previous_reports,
+        }
+        return self._send(PromptCategory.REPORT, self.get_report_prompt() + json.dumps(data, ensure_ascii=False))
+
+    def get_review_prompt(self) -> str:
+        """Return the review prompt as it is sent: the native language and one line per catalog category filled in."""
+        lines = [
+            f"- {category} ({info.kind}): {info.description}" + (f" — e.g. {info.example}" if info.example else "")
+            for category, info in CATEGORIES.items()
+        ]
+        native_language = self.core.services.setting.get_settings().native_language
+        return REVIEW_PROMPT_TEMPLATE.replace("{native_language}", native_language).replace("{categories}", "\n".join(lines))
+
+    def get_explain_prompt(self) -> str:
+        """Return the explain prompt as it is sent; the correction JSON is appended per ask."""
+        return EXPLAIN_PROMPT_TEMPLATE.replace("{native_language}", self.core.services.setting.get_settings().native_language)
+
+    def get_report_prompt(self) -> str:
+        """Return the report prompt as it is sent; the window JSON is appended per ask."""
+        return REPORT_PROMPT_TEMPLATE.replace("{native_language}", self.core.services.setting.get_settings().native_language)
+
+    def _send(self, category: PromptCategory, prompt: str) -> str:
+        """Answer *prompt* with the backend, model and effort the settings name for *category*, logging the call either way.
+
+        Returns the raw answer text; a failed call is logged with its error and re-raised.
+        """
+        settings = self.core.services.setting.get_settings()
+        match category:
+            case PromptCategory.REVIEW:
+                model, effort = settings.review_model, settings.review_effort
+            case PromptCategory.EXPLAIN:
+                model, effort = settings.explain_model, settings.explain_effort
+            case PromptCategory.REPORT:
+                model, effort = settings.report_model, settings.report_effort
+        backend = build_backend(settings.ai_backend)
+        started_at = datetime.now(UTC)
+        started = time.monotonic()
+        response: AiResponse | None = None
+        error: str | None = None
+        try:
+            response = backend.send_prompt(prompt, model, effort)
+        except Exception as e:
+            error = f"{type(e).__name__}: {e}"
+            raise
+        finally:
+            metrics = response or AiResponse(reply="")
+            with self.db.transaction() as conn:
+                conn.execute(
+                    """
+                    INSERT INTO ai_calls (created_at, category, backend, model, effort, prompt, reply,
+                        input_tokens, output_tokens, cost_usd, duration_ms, error)
+                    VALUES (?,?,?,?,?,?,?,?,?,?,?,?)
+                    """,
+                    (
+                        started_at.isoformat(),
+                        category,
+                        settings.ai_backend,
+                        metrics.model or model,  # what actually answered when the CLI says, the requested one otherwise
+                        effort,
+                        prompt,
+                        response.reply if response else None,
+                        metrics.input_tokens,
+                        metrics.output_tokens,
+                        metrics.cost_usd,
+                        int((time.monotonic() - started) * 1000),
+                        error,
+                    ),
+                )
+        return response.reply
+
+    def get_calls(self, category: PromptCategory | None, limit: int, offset: int) -> list[AiCall]:
+        """Return one page of stored calls, newest first; a None category means no filter."""
+        rows = self.db.conn.execute(
+            """
+            SELECT * FROM ai_calls WHERE (:category IS NULL OR category = :category)
+            ORDER BY id DESC LIMIT :limit OFFSET :offset
+            """,
+            {"category": category, "limit": limit, "offset": offset},
+        )
+        return [AiCall.from_row(row) for row in rows]
+
+    def get_call(self, call_id: int) -> AiCall:
+        """Return one stored call, full prompt and reply included."""
+        row = self.db.conn.execute("SELECT * FROM ai_calls WHERE id = ?", (call_id,)).fetchone()
+        if row is None:
+            raise NotFoundError(f"No AI call {call_id}")
+        return AiCall.from_row(row)
+
+    def count_calls(self, category: PromptCategory | None = None) -> int:
+        """Count the stored calls, failed ones included; a None category means no filter."""
+        row = self.db.conn.execute(
+            "SELECT COUNT(*) FROM ai_calls WHERE (:category IS NULL OR category = :category)", {"category": category}
+        ).fetchone()
+        return int(row[0])
+
+    def count_calls_by_category(self) -> dict[str, int]:
+        """Count the call log per category, largest first."""
+        rows = self.db.conn.execute("SELECT category, COUNT(*) AS n FROM ai_calls GROUP BY category ORDER BY n DESC")
+        return {row["category"]: row["n"] for row in rows}

defossil/core/features/correction/__init__.py

@@ -0,0 +1 @@
+"""Correction: what the LLM corrects in a message — mistakes and style — and the review batch that finds them."""