graphitect 0.2.0__py3-none-any.whl

graphitect/synthesize/engine.py

@@ -0,0 +1,281 @@
+"""Orchestrates the LLM draft step (llm_backend) with the rubric's own
+verification (rubric.py) - the draft is never trusted blindly. A "confirmed"
+claim citing a repository file gets re-checked against the actual file; if
+the cited text isn't really there, the claim is downgraded to inferred
+rather than shipping a fabricated citation. A file-less ``code`` citation is
+reserved for Graphitect's own computed Graphify facts; user citations remain
+the user's own statement.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from ..models import Claim, Confidence, DesignDocSection, Evidence, GroundedUnderstanding
+from .llm_backend import LLMBackend
+from .rubric import build_question
+
+# Keep the draft prompt bounded; truncate, don't fail, on a huge repo. 200K
+# chars (~50K tokens) comfortably covers a well-documented small-to-medium
+# repo's README+CHANGELOG+docs without truncating mid-document - the
+# previous 40K limit was confirmed live to truncate git-resume-agent's own
+# README+CHANGELOG (44KB combined) before the model ever saw all of it,
+# directly undercutting doc richness on exactly the repos this matters most
+# for. Still a single fixed number across every backend regardless of its
+# actual context window (Gemini's is far larger than a small local Ollama
+# model's) - real per-backend tuning is future work, not solved here.
+_MAX_CONTEXT_CHARS = 200_000
+
+# How many of the busiest source files (by node count - a proxy for
+# architectural significance, the same "god nodes" intuition
+# archify_adapter's community-overflow cap uses) get a real code excerpt
+# pulled into the prompt, and how much of each. Naman's request (12 Sep
+# 2026) for a more in-depth, explanatory doc needed real mechanism-level
+# material to explain FROM, not just a flat node/edge list - a node/edge
+# summary alone tells the model *what* is connected, never *how* it works.
+_MAX_CODE_EXCERPT_FILES = 6
+_MAX_CODE_EXCERPT_CHARS = 2_000
+
+
+def build_context(grounding: dict, repo_path: Path) -> str:
+    """Combine Graphify's structure (if present) with repo text (README,
+    CHANGELOG, docs) and a handful of real code excerpts into one
+    prompt-sized context. Graphify tells the model *what* is connected; the
+    repo text and code excerpts are where *why* and *how* actually come from
+    (plan.md §02).
+    """
+    parts: list[str] = []
+
+    if grounding.get("mode") == "graphify":
+        nodes = grounding.get("nodes", [])
+        edges = grounding.get("edges", [])
+        parts.append(f"Structure graph: {len(nodes)} nodes, {len(edges)} edges.")
+        node_lines = [f"- {n.get('id')}: {n.get('label', n.get('id'))}" for n in nodes[:200]]
+        parts.append("Nodes:\n" + "\n".join(node_lines))
+        edge_lines = [
+            f"- {e.get('source') or e.get('from')} -> {e.get('target') or e.get('to')}"
+            f" ({e.get('relation', e.get('label', 'related')) })"
+            for e in edges[:300]
+        ]
+        parts.append("Edges:\n" + "\n".join(edge_lines))
+
+        # Graphify's own `source_file` field on AST nodes (confirmed live
+        # against FundersAI's real graph.json) names exactly which real file
+        # backs each node; the files referenced by the most nodes are a
+        # reasonable proxy for "central to the architecture" without any
+        # extra analysis. Best-effort: a file that no longer exists (stale
+        # grounding, a moved file) is silently skipped, same tolerance
+        # README/docs reading below already has.
+        file_counts: dict[str, int] = {}
+        for n in nodes:
+            source_file = n.get("source_file")
+            if source_file:
+                file_counts[source_file] = file_counts.get(source_file, 0) + 1
+        top_files = sorted(file_counts, key=file_counts.get, reverse=True)[:_MAX_CODE_EXCERPT_FILES]
+        for source_file in top_files:
+            f = repo_path / source_file
+            if f.is_file():
+                excerpt = f.read_text(encoding="utf-8", errors="ignore")[:_MAX_CODE_EXCERPT_CHARS]
+                parts.append(f"\n--- code excerpt: {source_file} ---\n{excerpt}")
+    elif grounding.get("mode") == "describe":
+        parts.append("User's own description:")
+        for claim in grounding.get("claims", []):
+            parts.append(f"- {claim.get('text')}")
+
+    for name in ("README.md", "CHANGELOG.md"):
+        f = repo_path / name
+        if f.exists():
+            parts.append(f"\n--- {name} ---\n" + f.read_text(encoding="utf-8", errors="ignore"))
+
+    docs_dir = repo_path / "docs"
+    if docs_dir.is_dir():
+        for doc in sorted(docs_dir.rglob("*.md"))[:10]:
+            parts.append(
+                f"\n--- {doc.relative_to(repo_path)} ---\n"
+                + doc.read_text(encoding="utf-8", errors="ignore")
+            )
+
+    context = "\n\n".join(parts)
+    if len(context) > _MAX_CONTEXT_CHARS:
+        context = context[:_MAX_CONTEXT_CHARS] + "\n\n[... truncated ...]"
+    return context
+
+
+def _citation_note_is_present(text: str, note: str) -> bool:
+    """Require the full cited phrase, ignoring only case and whitespace."""
+    normalized_note = " ".join(note.casefold().split())
+    return bool(normalized_note) and normalized_note in " ".join(text.casefold().split())
+
+
+def _git_log_contains(repo_path: Path, note: str) -> bool:
+    """Verify a commit citation against Git when it has no source file."""
+    try:
+        result = subprocess.run(
+            ["git", "log", "--all", "--oneline", "--format=%h %s"],
+            cwd=repo_path,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+        )
+    except FileNotFoundError:
+        return False
+    return note.strip() in {line.strip() for line in result.stdout.splitlines()}
+
+
+def _repository_file(repo_path: Path, evidence_file: str | None) -> Path | None:
+    """Resolve a citation only when it remains inside the analyzed repository."""
+    if not evidence_file:
+        return None
+    try:
+        target = (repo_path / evidence_file).resolve()
+        target.relative_to(repo_path.resolve())
+    except ValueError:
+        return None
+    return target
+
+
+def _verify_claim(claim: Claim, repo_path: Path) -> Claim:
+    """Re-check a "confirmed" claim's own citations against the actual file.
+    Downgrades to inferred (with a note) rather than trusting the model's
+    say-so - the honesty guarantee has to survive the LLM being wrong about
+    its own evidence, not just the mining rubric being right.
+    """
+    if claim.confidence != Confidence.CONFIRMED:
+        return claim
+
+    for evidence in claim.cites:
+        if evidence.source == "user":
+            continue
+        if (
+            evidence.source == "code"
+            and evidence.file is None
+            and evidence.note == "Graphify structural extraction"
+        ):
+            # The diagram-only fallback carries this exact computed Graphify
+            # summary. Every host-authored code citation must name a file.
+            continue
+        if evidence.source == "git_log" and not evidence.file:
+            if evidence.note and _git_log_contains(repo_path, evidence.note):
+                continue
+        else:
+            target = _repository_file(repo_path, evidence.file)
+            if target and target.exists() and evidence.note and _citation_note_is_present(
+                target.read_text(encoding="utf-8", errors="ignore"), evidence.note
+            ):
+                continue
+        # Citation didn't check out - downgrade rather than ship a
+        # fabricated "confirmed" tag.
+        return claim.model_copy(
+            update={
+                "confidence": Confidence.INFERRED,
+                "text": f"{claim.text} (citation could not be independently verified)",
+            }
+        )
+    return claim
+
+
+def verify_understanding(understanding: GroundedUnderstanding, repo_path: Path) -> GroundedUnderstanding:
+    """Verify every host- or provider-authored claim before delivery."""
+    pending = []
+    for section in understanding.doc:
+        for i, claim in enumerate(section.claims):
+            verified = _verify_claim(claim, repo_path)
+            section.claims[i] = verified
+            if verified.confidence == Confidence.INFERRED:
+                question = build_question(verified, f"{section.heading}::{i}", section.heading, guess=verified.text)
+                if question:
+                    pending.append(question)
+
+        for tradeoff in section.tradeoffs:
+            tradeoff.decision = _verify_claim(tradeoff.decision, repo_path)
+            tradeoff.pros = [_verify_claim(c, repo_path) for c in tradeoff.pros]
+            tradeoff.cons = [_verify_claim(c, repo_path) for c in tradeoff.cons]
+
+    understanding.pending_questions = pending
+    return understanding
+
+
+def synthesize(
+    grounding: dict,
+    repo_path: Path,
+    backend: LLMBackend,
+    *,
+    diagram_kind: str = "architecture",
+) -> GroundedUnderstanding:
+    context = build_context(grounding, repo_path)
+    draft = backend.draft(context, diagram_kind=diagram_kind)
+
+    if grounding.get("mode") == "graphify":
+        # Use Graphify's real, deterministic AST-extracted nodes/edges for
+        # the diagram rather than trusting whatever the LLM's draft
+        # invented - the model's summary is prone to dropping/renaming/
+        # inventing structure since nothing obliges it to reproduce the real
+        # graph faithfully (Naman's point, 12 Sep 2026: "in-depth coverage
+        # of graphify - what's connected to what" was the actual goal, not
+        # an LLM's approximation of it). The LLM's own nodes/edges draft is
+        # discarded entirely here; only its `doc` (rationale claims) survives.
+        draft["nodes"] = grounding.get("nodes", [])
+        draft["edges"] = grounding.get("edges", [])
+        draft["community_labels"] = grounding.get("community_labels", {})
+
+    understanding = GroundedUnderstanding.model_validate(draft)
+
+    if grounding.get("mode") == "graphify":
+        # The LLM's related_node_ids referenced ITS OWN invented node ids,
+        # which mean nothing now that real Graphify nodes/edges replaced the
+        # draft's - drop any that don't exist in the real graph rather than
+        # relying on the model having been told (and having obeyed) to cite
+        # real ids. A stale reference should disappear, not silently point
+        # at a node that no longer exists.
+        real_ids = {n["id"] for n in understanding.nodes if "id" in n}
+        for section in understanding.doc:
+            section.related_node_ids = [rid for rid in section.related_node_ids if rid in real_ids]
+
+    return verify_understanding(understanding, repo_path)
+
+
+def synthesize_diagram_only(grounding: dict, *, diagram_kind: str = "architecture") -> GroundedUnderstanding:
+    """No LLM call at all - the fallback when no backend key is configured.
+
+    The diagram itself needs zero LLM involvement in graphify mode:
+    nodes/edges/community_labels are already deterministic Graphify output,
+    untouched by the draft step even when an LLM IS available (see
+    synthesize() above - the model's own nodes/edges get discarded and
+    replaced with these same real ones). Only the narrative `doc` ever
+    actually required a model. Rather than failing outright and leaving the
+    user with nothing, hand back the real diagram data with one purely
+    factual, computed overview claim (node/edge/community counts - no
+    interpretation involved, so it's honestly "confirmed" with no
+    verification pass needed) - so `deliver` can still produce a full
+    interactive diagram (Naman, 12 Sep 2026: "the diagram is a must").
+
+    Only meaningful for graphify-mode grounding - `describe` mode has no
+    structural data to fall back on and genuinely needs the LLM to turn a
+    free-text description into anything at all; callers should keep failing
+    loudly in that case rather than call this with an empty result.
+    """
+    nodes = grounding.get("nodes", [])
+    edges = grounding.get("edges", [])
+    communities = grounding.get("communities", {})
+
+    summary = f"{len(nodes)} structural nodes and {len(edges)} relationships were extracted by Graphify"
+    if communities:
+        summary += f", grouped into {len(communities)} communities"
+    summary += ". No LLM backend was available, so this doc is structure-only - no rationale was drafted."
+
+    overview_claim = Claim(
+        text=summary,
+        confidence=Confidence.CONFIRMED,
+        cites=[Evidence(source="code", note="Graphify structural extraction")],
+    )
+
+    return GroundedUnderstanding(
+        diagram_kind=diagram_kind,
+        nodes=nodes,
+        edges=edges,
+        doc=[DesignDocSection(heading="Overview", claims=[overview_claim])],
+        community_labels=grounding.get("community_labels", {}),
+    )

graphitect/synthesize/llm_backend.py

@@ -0,0 +1,331 @@
+"""The one genuinely LLM-dependent piece of Synthesize: turning raw grounding
+data (Graphify's nodes/edges, a plain description, or repo text) into
+Claim/DesignDocSection objects in the first place.
+
+Two concrete backends for standalone CLI use (`--anthropic` / `--gemini`,
+plan.md §05's "what differs standalone" note) plus the seam a skill uses
+instead: SkillBackend.draft() is never called in-process at all - the
+SKILL.md instructs the host to do this reasoning itself and hand back JSON
+matching the same schema, so graphitect's own code never needs to know it's
+running inside an agent.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Protocol
+
+_CANONICAL_SECTIONS = [
+    "Overview",
+    "Components & responsibilities",
+    "Technology choices & why",
+    "Tradeoffs & alternatives considered",
+    "Key workflows",
+    "Limitations & future work",
+]
+
+_SYSTEM_PROMPT = f"""\
+You are graphitect's Synthesize step. Given grounding data about a
+repository (a structural graph from Graphify, repo text: README, CHANGELOG,
+docs, and excerpts of its most central source files), produce a
+GroundedUnderstanding: a diagram structure plus a sourced, IN-DEPTH design
+doc. A reader should come away understanding HOW the system actually works,
+not just a list of facts about it - write substantive claims, not headlines.
+For every claim, explain the mechanism, grounded in whatever real evidence
+you have. "Uses a queue for background jobs" is a headline; "Background
+jobs are pushed onto a Redis-backed queue (worker.py) and processed by a
+separate worker process, decoupling slow operations like PDF generation
+from the request/response cycle" is a substantive claim. Prefer fewer,
+denser claims over many thin ones.
+
+Write this as an interview-ready architecture explanation, not a dependency
+inventory. For each applicable section, aim for 3-6 self-contained,
+mechanism-level claims. In particular:
+- In "Technology choices & why", every load-bearing choice should name the
+  technology, its concrete role in this repository, why that role fits the
+  system, and one operational consequence. Do not merely repeat a package
+  name.
+- In "Tradeoffs & alternatives considered", analyze 3-5 significant choices
+  when the evidence supports them. Each analysis should name plausible
+  alternatives, at least two concrete benefits, and at least one cost,
+  constraint, or risk. Keep uncertainty explicit rather than inventing a
+  historical decision record.
+- In "Key workflows", explain the actual sequence of handoffs, persistence,
+  background work, and user-visible result where those are evidenced. A
+  workflow claim should let a reader narrate the path without opening the
+  source tree.
+- Cover security, data boundaries, operations, and failure behavior when
+  they are present in the evidence; do not force them into a repository that
+  does not implement them.
+
+Use ONLY these section headings, spelled exactly as shown, and only the ones
+that actually apply - do not invent your own heading, and do not rename or
+paraphrase these:
+{chr(10).join(f'  - "{h}"' for h in _CANONICAL_SECTIONS)}
+This matters beyond formatting: only claims placed in "Technology choices &
+why" or "Tradeoffs & alternatives considered" ever get offered back to the
+user as a follow-up question when they're inferred and unresolved. A
+genuinely uncertain claim placed under an invented heading instead silently
+skips that step - always use the closest matching canonical heading above
+rather than inventing a more specific-sounding one.
+
+"Components & responsibilities" and "Key workflows" should read as a real
+walkthrough - what a component actually does and why it exists, or how a
+workflow actually proceeds step by step - not just a names-only inventory.
+Include a claim for every component/workflow that's genuinely worth
+explaining, not only the ones with a citable "why" (that stricter load-
+bearing bar below still applies to "Technology choices & why" and
+"Tradeoffs & alternatives considered" specifically).
+
+Follow the rationale-mining rubric for every claim you write:
+1. If the grounding data or repo text directly states a fact or reason,
+   the claim is "confirmed" and MUST cite where (source: code/readme/
+   git_log/docs, with a file/note).
+2. If you cannot find direct evidence but the claim is still worth making,
+   mark it "inferred" and say so plainly in the text - never phrase a guess
+   as if it were verified.
+3. Classify every claim's kind:
+   - "descriptive": a fact about a past decision (why X was chosen, what
+     tradeoff was made). These are the ones a human could later confirm or
+     correct.
+   - "prescriptive": your own recommendation for what to do next. These are
+     never verifiable against the past, so always "inferred" and never
+     phrased as a fact.
+4. Only put a claim in "Technology choices & why" or "Tradeoffs &
+   alternatives considered" if it's genuinely load-bearing - not every
+   detail needs a claim.
+
+For each genuinely significant decision in "Technology choices & why" or
+"Tradeoffs & alternatives considered", also add an entry to that section's
+`tradeoffs` list - a real pros/cons comparison, not just the flat claim.
+`decision` is itself a normal cited/confidence-tagged claim (it may restate
+or elaborate a claim already in this section's own `claims`);
+`alternatives_considered` names what else was plausible (say plainly if
+this is your own inference rather than something the repo actually
+discussed); `pros` and `cons` are themselves lists of normal cited/
+confidence-tagged claims, never bare strings - do not invent a benefit or
+drawback with no basis, mark it "inferred" like any other unverified claim.
+Not every claim needs a tradeoffs entry - reserve it for choices substantial
+enough to warrant a real comparison.
+
+Never fabricate a citation. Never mark a claim "confirmed" without a
+specific source you can point to. When genuinely unsure whether something
+is confirmed or inferred, choose inferred.
+
+If a structure graph (from Graphify) is included in the context below, your
+own "nodes" and "edges" in the response are discarded and replaced with the
+real graph - don't spend effort inventing a diagram structure in that case.
+Instead, set each doc section's related_node_ids to actual node ids quoted
+from that structure graph (not names you invent) - anything that isn't a
+real id from the graph is silently dropped rather than shown as a broken
+reference. Code excerpts in the context (when present) are real file
+contents from the repository's most central files - use them as your
+primary source for HOW claims, citing them as source "code" with the file
+path shown in the excerpt's header.
+"""
+
+_DRAFT_TOOL_NAME = "emit_grounded_understanding"
+
+
+class LLMBackend(Protocol):
+    def draft(self, context: str, *, diagram_kind: str) -> dict:
+        """Return a dict matching GroundedUnderstanding's schema (not yet
+        validated - callers run it through GroundedUnderstanding.model_validate).
+        """
+        ...
+
+    def complete_json(self, system_prompt: str, user_prompt: str, schema: dict, *, tool_name: str) -> dict:
+        """General structured-output call: force the model to return a dict
+        matching `schema`. `draft()` is just this with a fixed prompt/schema;
+        archify_repair's layout-fix loop is the other caller, with a
+        different prompt/schema (ArchitectureIR, not GroundedUnderstanding) -
+        shared here rather than duplicated per backend.
+        """
+        ...
+
+
+def _draft_tool_schema() -> dict:
+    from ..models import GroundedUnderstanding
+
+    schema = GroundedUnderstanding.model_json_schema()
+    return {
+        "name": _DRAFT_TOOL_NAME,
+        "description": "Emit the drafted GroundedUnderstanding for this repository.",
+        "input_schema": schema,
+    }
+
+
+class AnthropicBackend:
+    """Standalone backend backed by the caller's own ANTHROPIC_API_KEY.
+    The `anthropic` client ships with Graphitect.
+    """
+
+    def __init__(self, api_key: str, model: str = "claude-sonnet-5"):
+        try:
+            import anthropic
+        except ImportError as exc:
+            raise ImportError(
+                "AnthropicBackend needs the bundled `anthropic` package; "
+                "reinstall Graphitect with `pip install --force-reinstall graphitect`."
+            ) from exc
+        self._client = anthropic.Anthropic(api_key=api_key)
+        self._model = model
+
+    def draft(self, context: str, *, diagram_kind: str) -> dict:
+        schema = _draft_tool_schema()["input_schema"]
+        user = f"diagram_kind: {diagram_kind}\n\nGrounding data and repo text:\n\n{context}"
+        return self.complete_json(_SYSTEM_PROMPT, user, schema, tool_name=_DRAFT_TOOL_NAME)
+
+    def complete_json(self, system_prompt: str, user_prompt: str, schema: dict, *, tool_name: str) -> dict:
+        tool = {"name": tool_name, "description": f"Emit {tool_name}.", "input_schema": schema}
+        response = self._client.messages.create(
+            model=self._model,
+            max_tokens=8192,
+            system=system_prompt,
+            tools=[tool],
+            tool_choice={"type": "tool", "name": tool_name},
+            messages=[{"role": "user", "content": user_prompt}],
+        )
+        for block in response.content:
+            if block.type == "tool_use" and block.name == tool_name:
+                return block.input
+        raise RuntimeError(f"Model did not call the expected tool {tool_name!r} - no output produced.")
+
+
+class GeminiBackend:
+    """Standalone backend backed by the caller's own GEMINI_API_KEY /
+    GOOGLE_API_KEY, via Gemini's OpenAI-compatible endpoint (matching how
+    Graphify's own gemini extra is structured: openai + tiktoken).
+    """
+
+    def __init__(self, api_key: str, model: str = "gemini-3-flash-preview"):
+        try:
+            from openai import OpenAI
+        except ImportError as exc:
+            raise ImportError(
+                "GeminiBackend needs the bundled `openai` package; "
+                "reinstall Graphitect with `pip install --force-reinstall graphitect`."
+            ) from exc
+        self._client = OpenAI(
+            api_key=api_key, base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
+        )
+        self._model = model
+
+    def draft(self, context: str, *, diagram_kind: str) -> dict:
+        schema = _draft_tool_schema()["input_schema"]
+        user = f"diagram_kind: {diagram_kind}\n\nGrounding data and repo text:\n\n{context}"
+        return self.complete_json(_SYSTEM_PROMPT, user, schema, tool_name=_DRAFT_TOOL_NAME)
+
+    def complete_json(self, system_prompt: str, user_prompt: str, schema: dict, *, tool_name: str) -> dict:
+        response = self._client.chat.completions.create(
+            model=self._model,
+            response_format={"type": "json_schema", "json_schema": {"name": tool_name, "schema": schema}},
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_prompt},
+            ],
+        )
+        return json.loads(response.choices[0].message.content)
+
+
+class OllamaBackend:
+    """Local Ollama (no key needed, `http://localhost:11434`) or Ollama
+    Cloud (an API key, generous free tier) - same OpenAI-compatible wire
+    protocol either way, so one class covers both; only the default
+    base_url changes depending on whether a key was given. Mirrors
+    git-resume-agent's own confirmed Ollama-first LLM strategy (this
+    project's own Phase 0 doc, §02 "Ollama-first" row).
+
+    The bundled `openai` package is used for Ollama's compatibility layer;
+    it does not require an OpenAI account.
+    """
+
+    # Confirmed live against https://ollama.com/v1/models (12 Sep 2026) - Cloud's
+    # catalog is a completely different namespace from local model names (no
+    # "llama3.1" on Cloud at all). A model name valid on one is very likely
+    # invalid on the other, and Cloud returns a bare 401 for an inaccessible/
+    # unrecognized model rather than 404 - which looks exactly like a bad key
+    # until you check /v1/models directly with the same key and see it's fine.
+    _CLOUD_DEFAULT_MODEL = "gpt-oss:20b"
+    _LOCAL_DEFAULT_MODEL = "llama3.1"
+
+    def __init__(
+        self,
+        model: str | None = None,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+    ):
+        try:
+            from openai import OpenAI
+        except ImportError as exc:
+            raise ImportError(
+                "OllamaBackend needs the bundled `openai` package; reinstall "
+                "Graphitect with `pip install --force-reinstall graphitect`."
+            ) from exc
+        is_cloud = bool(api_key)
+        resolved_base = base_url or ("https://ollama.com/v1" if is_cloud else "http://localhost:11434/v1")
+        # Local Ollama ignores the key entirely but the OpenAI client requires
+        # a non-empty string; Cloud actually checks it.
+        self._client = OpenAI(api_key=api_key or "ollama-local", base_url=resolved_base)
+        self._model = model or (self._CLOUD_DEFAULT_MODEL if is_cloud else self._LOCAL_DEFAULT_MODEL)
+
+    def draft(self, context: str, *, diagram_kind: str) -> dict:
+        schema = _draft_tool_schema()["input_schema"]
+        user = f"diagram_kind: {diagram_kind}\n\nGrounding data and repo text:\n\n{context}"
+        return self.complete_json(_SYSTEM_PROMPT, user, schema, tool_name=_DRAFT_TOOL_NAME)
+
+    def complete_json(self, system_prompt: str, user_prompt: str, schema: dict, *, tool_name: str) -> dict:
+        # Unlike Gemini's stricter json_schema mode, Ollama's OpenAI-compat
+        # layer support for response_format varies by model, so the schema
+        # is embedded directly in the prompt as the more portable path -
+        # every model can at least follow instructions in plain text even
+        # if it can't honor a strict schema constraint.
+        system_with_schema = (
+            f"{system_prompt}\n\nRespond with ONLY a JSON object matching this schema "
+            f"exactly - no markdown fences, no explanation before or after:\n{json.dumps(schema)}"
+        )
+        response = self._client.chat.completions.create(
+            model=self._model,
+            response_format={"type": "json_object"},
+            messages=[
+                {"role": "system", "content": system_with_schema},
+                {"role": "user", "content": user_prompt},
+            ],
+        )
+        return json.loads(response.choices[0].message.content)
+
+
+def resolve_backend(
+    *,
+    anthropic_key: str | None,
+    gemini_key: str | None,
+    ollama_key: str | None = None,
+    ollama_base_url: str | None = None,
+    ollama_model: str | None = None,
+    ollama_local: bool = False,
+) -> LLMBackend:
+    """Standalone CLI resolution order: Ollama (key, or `--ollama-local` for
+    a locally-running server with no key at all) first - free tier, no
+    account needed for local use - then Anthropic, then Gemini, then fail
+    loudly. Matches Graphify's own "no other keys are read" honesty rule:
+    never silently fall back to a key or endpoint the user didn't ask for.
+    """
+    if ollama_key or ollama_local:
+        return OllamaBackend(
+            # Preserve None so OllamaBackend can select the correct default
+            # for Cloud (gpt-oss:20b) versus a local server (llama3.1).
+            model=ollama_model,
+            api_key=ollama_key,
+            base_url=ollama_base_url,
+        )
+    if anthropic_key:
+        return AnthropicBackend(anthropic_key)
+    if gemini_key:
+        return GeminiBackend(gemini_key)
+    raise RuntimeError(
+        "No LLM backend available. Set OLLAMA_API_KEY (Ollama Cloud), pass "
+        "--ollama-local for a locally-running Ollama server, or set ANTHROPIC_API_KEY / "
+        "GEMINI_API_KEY - or run graphitect as a Claude Code/Cursor/Codex skill instead, "
+        "where the host's own reasoning does this step for free (plan.md §05)."
+    )