saga-cli 0.1.0__tar.gz → 0.2.0__tar.gz

saga_cli-0.2.0/.github/CODEOWNERS

@@ -0,0 +1,3 @@
+# Every change requires review from the maintainer.
+# See https://docs.github.com/articles/about-code-owners
+* @JakeBeresford

{saga_cli-0.1.0 → saga_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: saga-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: Generate a self-contained static HTML saga of a git diff — a chapter-by-chapter guided tour of a change.
 Project-URL: Homepage, https://github.com/JakeBeresford/saga
 Project-URL: Repository, https://github.com/JakeBeresford/saga
@@ -43,7 +43,8 @@ the data). Open it offline, email it, commit it, or drop it on any static host.
 - Python 3.11+
 - `git`
 - An API key for your chosen provider, in the standard environment variable:
-  `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY`
+  `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY` — or a running
+  local server (Ollama / LM Studio) and no key, with a `local/` model
 
 Generation is one structured LLM call made through [`instructor`](https://python.useinstructor.com).
 
@@ -64,7 +65,13 @@ e.g. `uv tool install /path/to/saga`. To upgrade: `uv tool install --force saga-
 
 ## Usage
 
-From inside the repo you want to review:
+From inside the repo, on the branch you want to review:
+
+```sh
+saga
+```
+
+From inside the repo, reviewing a different branch:
 
 ```sh
 saga --base main --head my-feature -o saga.html --open
@@ -97,6 +104,8 @@ the matching API key:
 | Anthropic  | `anthropic/claude-opus-4-8`              | `ANTHROPIC_API_KEY`  |
 | OpenAI     | `openai/gpt-4o`                          | `OPENAI_API_KEY`     |
 | OpenRouter | `openrouter/anthropic/claude-3.5-sonnet` | `OPENROUTER_API_KEY` |
+| Local      | `local/qwen2.5-coder:14b`                | none                 |
+| Claude CLI | `claude-cli` or `claude-cli/sonnet`      | none (Claude Code login) |
 
 ```sh
 export SAGA_MODEL=openai/gpt-4o
@@ -104,6 +113,47 @@ export OPENAI_API_KEY=sk-…
 saga --base main --head my-feature -o saga.html
 ```
 
+### Local LLMs (Ollama / LM Studio)
+
+A `local/` model runs against any OpenAI-compatible local server, with no API
+key. Pull a capable coder model first (`ollama pull qwen2.5-coder:14b`), then:
+
+```sh
+saga --model local/qwen2.5-coder:14b --base main --head my-feature
+```
+
+`local/` defaults to Ollama's endpoint (`http://localhost:11434/v1`). Point it
+at another server — e.g. LM Studio — with `SAGA_LOCAL_BASE_URL`:
+
+```sh
+export SAGA_LOCAL_BASE_URL=http://localhost:1234/v1   # LM Studio
+saga --model local/your-loaded-model --base main --head my-feature
+```
+
+Two caveats: saga requires schema-valid JSON output, so use an instruction-tuned
+model that follows JSON prompting reliably; and the full diff plus a 16k output
+budget can exceed a small model's context window — prefer larger-context models
+and expect weaker narration than a frontier hosted model.
+
+### Claude Code CLI (no API key)
+
+If you don't have an Anthropic API key but you are logged into the
+[Claude Code](https://claude.com/claude-code) CLI — for example with a Claude
+Pro/Max subscription — the `claude-cli` model routes generation through
+`claude -p` instead of the API, reusing that login:
+
+```sh
+saga --model claude-cli --base main --head my-feature
+saga --model claude-cli/sonnet --base main --head my-feature   # pin a model
+```
+
+This shells out to the `claude` binary (which must be on your `PATH` and logged
+in), constrains its output to saga's schema via `--json-schema`, and runs it as
+a plain transform with no tools. `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN`
+are dropped for the subprocess so it uses your Claude Code login rather than
+silently billing an API key. It is slower than a direct API call (Claude Code
+boots an agent per run) and subject to your subscription's usage limits.
+
 ## As a Claude Code skill
 
 The `skills/` directory contains two Claude Code skills. To install both:
@@ -154,5 +204,4 @@ it on GitHub. Requires the [`gh`](https://cli.github.com) CLI, authenticated.
 
 ## Not included (yet)
 
-- Support for Local LLMs via ollama / LM Studio
 - A GitHub Action to auto-generate saga on PRs.

{saga_cli-0.1.0 → saga_cli-0.2.0}/README.md

@@ -16,7 +16,8 @@ the data). Open it offline, email it, commit it, or drop it on any static host.
 - Python 3.11+
 - `git`
 - An API key for your chosen provider, in the standard environment variable:
-  `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY`
+  `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY` — or a running
+  local server (Ollama / LM Studio) and no key, with a `local/` model
 
 Generation is one structured LLM call made through [`instructor`](https://python.useinstructor.com).
 
@@ -37,7 +38,13 @@ e.g. `uv tool install /path/to/saga`. To upgrade: `uv tool install --force saga-
 
 ## Usage
 
-From inside the repo you want to review:
+From inside the repo, on the branch you want to review:
+
+```sh
+saga
+```
+
+From inside the repo, reviewing a different branch:
 
 ```sh
 saga --base main --head my-feature -o saga.html --open
@@ -70,6 +77,8 @@ the matching API key:
 | Anthropic  | `anthropic/claude-opus-4-8`              | `ANTHROPIC_API_KEY`  |
 | OpenAI     | `openai/gpt-4o`                          | `OPENAI_API_KEY`     |
 | OpenRouter | `openrouter/anthropic/claude-3.5-sonnet` | `OPENROUTER_API_KEY` |
+| Local      | `local/qwen2.5-coder:14b`                | none                 |
+| Claude CLI | `claude-cli` or `claude-cli/sonnet`      | none (Claude Code login) |
 
 ```sh
 export SAGA_MODEL=openai/gpt-4o
@@ -77,6 +86,47 @@ export OPENAI_API_KEY=sk-…
 saga --base main --head my-feature -o saga.html
 ```
 
+### Local LLMs (Ollama / LM Studio)
+
+A `local/` model runs against any OpenAI-compatible local server, with no API
+key. Pull a capable coder model first (`ollama pull qwen2.5-coder:14b`), then:
+
+```sh
+saga --model local/qwen2.5-coder:14b --base main --head my-feature
+```
+
+`local/` defaults to Ollama's endpoint (`http://localhost:11434/v1`). Point it
+at another server — e.g. LM Studio — with `SAGA_LOCAL_BASE_URL`:
+
+```sh
+export SAGA_LOCAL_BASE_URL=http://localhost:1234/v1   # LM Studio
+saga --model local/your-loaded-model --base main --head my-feature
+```
+
+Two caveats: saga requires schema-valid JSON output, so use an instruction-tuned
+model that follows JSON prompting reliably; and the full diff plus a 16k output
+budget can exceed a small model's context window — prefer larger-context models
+and expect weaker narration than a frontier hosted model.
+
+### Claude Code CLI (no API key)
+
+If you don't have an Anthropic API key but you are logged into the
+[Claude Code](https://claude.com/claude-code) CLI — for example with a Claude
+Pro/Max subscription — the `claude-cli` model routes generation through
+`claude -p` instead of the API, reusing that login:
+
+```sh
+saga --model claude-cli --base main --head my-feature
+saga --model claude-cli/sonnet --base main --head my-feature   # pin a model
+```
+
+This shells out to the `claude` binary (which must be on your `PATH` and logged
+in), constrains its output to saga's schema via `--json-schema`, and runs it as
+a plain transform with no tools. `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN`
+are dropped for the subprocess so it uses your Claude Code login rather than
+silently billing an API key. It is slower than a direct API call (Claude Code
+boots an agent per run) and subject to your subscription's usage limits.
+
 ## As a Claude Code skill
 
 The `skills/` directory contains two Claude Code skills. To install both:
@@ -127,5 +177,4 @@ it on GitHub. Requires the [`gh`](https://cli.github.com) CLI, authenticated.
 
 ## Not included (yet)
 
-- Support for Local LLMs via ollama / LM Studio
 - A GitHub Action to auto-generate saga on PRs.

{saga_cli-0.1.0 → saga_cli-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "saga-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "Generate a self-contained static HTML saga of a git diff — a chapter-by-chapter guided tour of a change."
 readme = "README.md"
 requires-python = ">=3.11"

{saga_cli-0.1.0 → saga_cli-0.2.0}/saga/cli.py

@@ -2,7 +2,10 @@
 
 Installs a ``saga`` command usable from any repo. Needs Python 3, git, and
 an API key for the chosen provider (``ANTHROPIC_API_KEY`` / ``OPENAI_API_KEY`` /
-``OPENROUTER_API_KEY``). Run from inside the repo you want to review:
+``OPENROUTER_API_KEY``) — or, with a ``local/`` model, a running Ollama or
+LM Studio server and no key, or the ``claude-cli`` model, a logged-in Claude
+Code CLI (e.g. a Claude subscription, no key). Run from inside the repo you
+want to review:
 
     saga --base main --head my-feature -o saga.html --open
 
@@ -45,7 +48,10 @@ def main(
         envvar="SAGA_MODEL",
         help=(
             "provider/model to use, e.g. anthropic/claude-opus-4-8, openai/gpt-4o, "
-            "openrouter/anthropic/claude-3.5-sonnet "
+            "openrouter/anthropic/claude-3.5-sonnet, local/qwen2.5-coder:14b, "
+            "claude-cli or claude-cli/sonnet "
+            "(local/ targets Ollama or LM Studio; see $SAGA_LOCAL_BASE_URL. "
+            "claude-cli routes through your logged-in Claude Code CLI) "
             "(default: $SAGA_MODEL or anthropic/claude-opus-4-8)"
         ),
     ),

saga_cli-0.2.0/saga/generate.py

@@ -0,0 +1,301 @@
+"""Generate a saga for one change set via a single structured LLM call.
+
+The call takes the full diff (every hunk labeled by a stable id), the commit
+messages, and an optional intent document, and returns strict, schema-validated
+JSON. Coverage is re-validated in code before trusting it — nothing the model
+returns is assumed complete.
+
+Provider-agnostic: the model is chosen by a ``provider/model`` string (e.g.
+``anthropic/claude-opus-4-8``, ``openai/gpt-4o``,
+``openrouter/anthropic/claude-3.5-sonnet``) and dispatched through ``instructor``.
+The API key is read from the provider's standard environment variable
+(``ANTHROPIC_API_KEY`` / ``OPENAI_API_KEY`` / ``OPENROUTER_API_KEY``).
+
+The ``local/`` prefix targets any OpenAI-compatible local server — Ollama or
+LM Studio — with no API key. It defaults to Ollama's endpoint; point it at a
+different server (e.g. LM Studio on port 1234) with ``$SAGA_LOCAL_BASE_URL``.
+
+The ``claude-cli`` provider shells out to a local Claude Code CLI (``claude -p``)
+instead of the Anthropic SDK, so it uses whatever the user's Claude Code is
+logged in with — including a Claude Pro/Max subscription, with no API key. The
+saga schema is enforced via ``claude``'s ``--json-schema`` flag.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from pathlib import Path
+from typing import Literal
+
+import instructor
+from pydantic import BaseModel, Field
+
+from .diff import DiffResult, compute_diff, rev_parse
+from .model import (
+    Chapter,
+    Hunk,
+    Saga,
+    SagaError,
+    parse_hunks,
+    validate_coverage,
+)
+
+_MAX_TOKENS = 16000
+_OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
+# Ollama's OpenAI-compatible endpoint; override with $SAGA_LOCAL_BASE_URL (e.g.
+# http://localhost:1234/v1 for LM Studio).
+_LOCAL_DEFAULT_BASE_URL = "http://localhost:11434/v1"
+# Claude Code boot + generation for a full saga can take a while; be generous.
+_CLAUDE_CLI_TIMEOUT = 300
+_PROMPT_PATH = Path(__file__).resolve().parent / "prompts" / "saga.md"
+
+
+# ---------------------------------------------------------------------------
+# LLM response schema — what the model must return (validated by instructor).
+# Mapped onto the persisted ``Chapter`` dataclass below so model.py's core,
+# validate_coverage, and render.py stay untouched.
+# ---------------------------------------------------------------------------
+
+
+class _QAOut(BaseModel):
+    status: str
+    note: str = ""
+
+
+class _ChapterOut(BaseModel):
+    id: str
+    title: str
+    summary: str
+    narration: str
+    hunks: list[str] = Field(default_factory=list)
+    plan_step: str | None = None
+    confidence: Literal["high", "medium", "low"] = "medium"
+    deviation: str | None = None
+    qa: _QAOut | None = None
+
+
+class _SagaOut(BaseModel):
+    chapters: list[_ChapterOut]
+
+
+def _to_chapter(c: _ChapterOut) -> Chapter:
+    return Chapter(
+        id=c.id,
+        title=c.title,
+        summary=c.summary,
+        narration=c.narration,
+        hunks=list(c.hunks),
+        plan_step=c.plan_step,
+        confidence=c.confidence,
+        deviation=c.deviation or None,
+        qa=c.qa.model_dump() if c.qa else None,
+    )
+
+
+def labeled_diff(hunks: list[Hunk]) -> str:
+    """Render the diff for the prompt with each hunk headed by its stable id."""
+    out: list[str] = []
+    for h in hunks:
+        first = h.body.splitlines()[0] if h.body else ""
+        out.append(f"### HUNK {h.id} — {h.file_path}  ({first.strip()})")
+        out.append(h.body.rstrip("\n"))
+    return "\n".join(out)
+
+
+def _build_message(diff: DiffResult, hunks: list[Hunk], intent: str | None) -> str:
+    """Assemble the user message: intent (optional), commits, and labeled diff."""
+    commits = "\n".join(diff.commits) or "(no commit messages)"
+    intent_block = (
+        ["# Intent (what this change set out to do)", intent.strip(), ""]
+        if intent and intent.strip()
+        else []
+    )
+    return "\n".join(
+        [
+            *intent_block,
+            "# Commits",
+            commits,
+            "",
+            "# Full diff (every hunk must be assigned to a chapter)",
+            labeled_diff(hunks),
+        ]
+    )
+
+
+def _build_client(model: str) -> instructor.Instructor:
+    """Build an instructor client for a ``provider/model`` string.
+
+    OpenRouter is OpenAI-compatible, so it needs an explicit base URL and its own
+    key; Anthropic and OpenAI resolve their keys from the SDK's standard env vars.
+    ``local`` targets an OpenAI-compatible local server (Ollama/LM Studio) via the
+    OpenAI SDK — no key, and forced JSON mode since local models' tool-calling is
+    unreliable and saga depends on schema-valid output.
+    """
+    provider = model.split("/", 1)[0]
+    try:
+        if provider == "openrouter":
+            key = os.environ.get("OPENROUTER_API_KEY")
+            if not key:
+                raise SagaError("OPENROUTER_API_KEY is not set.")
+            return instructor.from_provider(
+                model, base_url=_OPENROUTER_BASE_URL, api_key=key
+            )
+        if provider == "local":
+            model_name = model.split("/", 1)[1]
+            base_url = os.environ.get("SAGA_LOCAL_BASE_URL", _LOCAL_DEFAULT_BASE_URL)
+            return instructor.from_provider(
+                f"openai/{model_name}",
+                base_url=base_url,
+                api_key="local",  # unused by the local server, but must be non-empty
+                mode=instructor.Mode.JSON,
+            )
+        return instructor.from_provider(model)
+    except SagaError:
+        raise
+    except Exception as e:
+        raise SagaError(f"Could not initialize model {model!r}: {e}") from e
+
+
+def _generate_via_claude_cli(
+    model: str, system_prompt: str, user_message: str
+) -> _SagaOut:
+    """Generate a saga through a local Claude Code CLI (``claude -p``).
+
+    Unlike the ``anthropic/`` provider (which needs ``ANTHROPIC_API_KEY``), this
+    runs the ``claude`` binary and reuses its stored login, so a user with only a
+    Claude Pro/Max subscription can generate sagas. Output is constrained to the
+    saga schema with ``--json-schema`` and read back from the JSON envelope's
+    ``structured_output`` field. ``model`` is ``claude-cli`` (Claude Code's
+    default model) or ``claude-cli/<alias>`` (e.g. ``claude-cli/sonnet``).
+    """
+    parts = model.split("/", 1)
+    cmd = [
+        "claude",
+        "-p",
+        "--output-format",
+        "json",
+        # Replace Claude Code's default system prompt with saga's — a focused,
+        # tool-free transform rather than a coding agent.
+        "--system-prompt",
+        system_prompt,
+        "--allowedTools",
+        "",  # no tools: prompt in, schema-valid JSON out
+        "--json-schema",
+        json.dumps(_SagaOut.model_json_schema()),
+    ]
+    if len(parts) == 2 and parts[1]:
+        cmd += ["--model", parts[1]]
+
+    # ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN outrank the Claude Code login, so a
+    # stray key would silently bill the API instead of the subscription this
+    # provider exists to use. Drop them for the subprocess.
+    env = {
+        k: v
+        for k, v in os.environ.items()
+        if k not in ("ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN")
+    }
+
+    try:
+        proc = subprocess.run(
+            cmd,
+            input=user_message,
+            capture_output=True,
+            text=True,
+            env=env,
+            timeout=_CLAUDE_CLI_TIMEOUT,
+        )
+    except FileNotFoundError as e:
+        raise SagaError(
+            "claude CLI not found. Install Claude Code and log in "
+            "(https://claude.com/claude-code), or choose a different --model."
+        ) from e
+    except subprocess.TimeoutExpired as e:
+        raise SagaError(f"claude CLI timed out after {_CLAUDE_CLI_TIMEOUT}s.") from e
+
+    if proc.returncode != 0:
+        detail = (proc.stderr or proc.stdout).strip()
+        raise SagaError(f"claude CLI failed (exit {proc.returncode}): {detail}")
+
+    # stdout may carry a leading warning line before the JSON object; start at the
+    # first brace.
+    text = proc.stdout.strip()
+    start = text.find("{")
+    if start == -1:
+        raise SagaError(f"claude CLI returned no JSON:\n{text[:500]}")
+    try:
+        envelope = json.loads(text[start:])
+    except json.JSONDecodeError as e:
+        raise SagaError(f"could not parse claude CLI output: {e}") from e
+
+    if envelope.get("is_error"):
+        raise SagaError(f"claude CLI reported an error: {envelope.get('result')}")
+    structured = envelope.get("structured_output")
+    if structured is None:
+        raise SagaError(
+            "claude CLI returned no structured_output — the model did not "
+            "produce schema-valid output."
+        )
+    try:
+        return _SagaOut.model_validate(structured)
+    except Exception as e:
+        raise SagaError(f"claude CLI output did not match the saga schema: {e}") from e
+
+
+def generate(
+    repo_root: Path,
+    base: str,
+    head: str,
+    *,
+    model: str,
+    intent: str | None = None,
+) -> Saga:
+    """Generate the saga for *base*...*head*.
+
+    Raises ``SagaError`` on an empty diff, a provider/model error, or a
+    coverage gap. The caller renders the error as a user-facing message.
+    """
+    diff = compute_diff(repo_root, base, head)
+    hunks = parse_hunks(diff.diff_text)
+    if not hunks:
+        raise SagaError("No reviewable hunks in this change set.")
+
+    provider = model.split("/", 1)[0]
+    system_prompt = _PROMPT_PATH.read_text()
+    user_message = _build_message(diff, hunks, intent)
+
+    if provider == "claude-cli":
+        result = _generate_via_claude_cli(model, system_prompt, user_message)
+    else:
+        client = _build_client(model)
+        kwargs: dict = {}
+        if provider == "openrouter":
+            # Ask OpenRouter to route only to providers that support the params we
+            # send (structured output), so schema enforcement is honored.
+            kwargs["extra_body"] = {"provider": {"require_parameters": True}}
+
+        try:
+            result: _SagaOut = client.create(
+                response_model=_SagaOut,
+                max_tokens=_MAX_TOKENS,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_message},
+                ],
+                **kwargs,
+            )
+        except SagaError:
+            raise
+        except Exception as e:
+            raise SagaError(f"Saga generation failed: {e}") from e
+
+    chapters = [_to_chapter(c) for c in result.chapters]
+    validate_coverage(chapters, hunks)
+
+    return Saga(
+        branch=head,
+        base=base,
+        commit_sha=rev_parse(repo_root, head),
+        chapters=chapters,
+    )

saga_cli-0.2.0/tests/test_generate.py

@@ -0,0 +1,319 @@
+"""Tests for saga generation.
+
+The one real LLM HTTP call is recorded to a VCR cassette (auth headers scrubbed)
+and replayed offline. Everything around it — prompt assembly, client selection,
+schema→dataclass mapping, and the empty-diff guard — is tested without network.
+
+Re-record with a real key via:  SAGA_RECORD=1 ANTHROPIC_API_KEY=... pytest
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from saga.generate import (
+    _build_client,
+    _build_message,
+    _ChapterOut,
+    _generate_via_claude_cli,
+    _QAOut,
+    _SagaOut,
+    _to_chapter,
+    generate,
+    labeled_diff,
+)
+from saga.model import SagaError, parse_hunks
+
+# ---------------------------------------------------------------------------
+# Prompt assembly (pure)
+# ---------------------------------------------------------------------------
+
+TWO_FILE_DIFF = (
+    "diff --git a/foo.py b/foo.py\n"
+    "--- a/foo.py\n+++ b/foo.py\n"
+    "@@ -1,2 +1,2 @@\n a\n-b\n+B\n"
+)
+
+
+def test_labeled_diff_heads_each_hunk_with_id():
+    hunks = parse_hunks(TWO_FILE_DIFF)
+    out = labeled_diff(hunks)
+    assert "### HUNK h0 — foo.py" in out
+    assert "@@ -1,2 +1,2 @@" in out
+
+
+def test_build_message_includes_intent_commits_and_diff():
+    from saga.diff import DiffResult
+
+    diff = DiffResult(diff_text=TWO_FILE_DIFF, commits=["abc fix bug"], diffstat="")
+    hunks = parse_hunks(TWO_FILE_DIFF)
+    msg = _build_message(diff, hunks, intent="Fix the bug.")
+    assert "# Intent" in msg
+    assert "Fix the bug." in msg
+    assert "abc fix bug" in msg
+    assert "### HUNK h0" in msg
+
+
+def test_build_message_omits_intent_block_when_absent():
+    from saga.diff import DiffResult
+
+    diff = DiffResult(diff_text=TWO_FILE_DIFF, commits=[], diffstat="")
+    hunks = parse_hunks(TWO_FILE_DIFF)
+    msg = _build_message(diff, hunks, intent=None)
+    assert "# Intent" not in msg
+    assert "(no commit messages)" in msg
+
+
+def test_to_chapter_maps_schema_to_dataclass():
+    out = _ChapterOut(
+        id="c1",
+        title="T",
+        summary="S",
+        narration="N",
+        hunks=["h0"],
+        confidence="high",
+        deviation="",
+        qa=_QAOut(status="green", note="ok"),
+    )
+    ch = _to_chapter(out)
+    assert ch.id == "c1"
+    assert ch.confidence == "high"
+    # Empty-string deviation normalizes to None.
+    assert ch.deviation is None
+    assert ch.qa == {"status": "green", "note": "ok"}
+
+
+# ---------------------------------------------------------------------------
+# Client selection / error handling (no network)
+# ---------------------------------------------------------------------------
+
+
+def test_build_client_openrouter_without_key_raises(monkeypatch):
+    monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
+    with pytest.raises(SagaError, match="OPENROUTER_API_KEY"):
+        _build_client("openrouter/anthropic/claude-3.5-sonnet")
+
+
+def test_build_client_unknown_provider_raises_sagaerror(monkeypatch):
+    with pytest.raises(SagaError, match="Could not initialize model"):
+        _build_client("bogusprovider/some-model")
+
+
+def _capture_from_provider(monkeypatch) -> dict:
+    """Patch instructor.from_provider to record its args instead of building a
+    real client, so local-provider wiring can be checked without a server."""
+    import saga.generate as gen
+
+    captured: dict = {}
+
+    def fake(model, **kwargs):
+        captured["model"] = model
+        captured.update(kwargs)
+        return object()
+
+    monkeypatch.setattr(gen.instructor, "from_provider", fake)
+    return captured
+
+
+def test_build_client_local_defaults_to_ollama(monkeypatch):
+    import saga.generate as gen
+
+    monkeypatch.delenv("SAGA_LOCAL_BASE_URL", raising=False)
+    captured = _capture_from_provider(monkeypatch)
+    _build_client("local/qwen2.5-coder:14b")
+    # local/ is dispatched through the OpenAI SDK at Ollama's endpoint, key unused.
+    assert captured["model"] == "openai/qwen2.5-coder:14b"
+    assert captured["base_url"] == "http://localhost:11434/v1"
+    assert captured["api_key"]
+    assert captured["mode"] == gen.instructor.Mode.JSON
+
+
+def test_build_client_local_honors_base_url_override(monkeypatch):
+    # Point local/ at LM Studio (or any OpenAI-compatible server) via the env var.
+    monkeypatch.setenv("SAGA_LOCAL_BASE_URL", "http://localhost:1234/v1")
+    captured = _capture_from_provider(monkeypatch)
+    _build_client("local/lmstudio-community/Qwen2.5-Coder-GGUF")
+    assert captured["base_url"] == "http://localhost:1234/v1"
+    # A slash-bearing model id keeps its slashes after the local/ prefix is stripped.
+    assert captured["model"] == "openai/lmstudio-community/Qwen2.5-Coder-GGUF"
+
+
+def test_generate_empty_diff_raises_before_any_network(empty_diff_repo: Path):
+    with pytest.raises(SagaError, match="No reviewable hunks"):
+        generate(empty_diff_repo, "main", "feature", model="anthropic/claude-opus-4-8")
+
+
+# ---------------------------------------------------------------------------
+# Full generation, replayed from a scrubbed cassette
+# ---------------------------------------------------------------------------
+
+
+def test_generate_full_saga_from_cassette(git_repo: Path, vcr_cassette, monkeypatch):
+    # Replay needs a syntactically-valid key for client construction; the real
+    # HTTP is served by the cassette. Don't clobber a real key while recording.
+    if not os.environ.get("ANTHROPIC_API_KEY"):
+        monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-ant-test-dummy")
+
+    with vcr_cassette.use_cassette("generate_anthropic.yaml"):
+        saga = generate(git_repo, "main", "feature", model="anthropic/claude-opus-4-8")
+
+    assert saga.base == "main"
+    assert saga.branch == "feature"
+    assert saga.commit_sha and len(saga.commit_sha) == 40
+    assert len(saga.chapters) >= 1
+    # generate() re-validates coverage internally, so reaching here means every
+    # hunk in the live diff was assigned. Confirm the chapters carry content.
+    assert all(c.id for c in saga.chapters)
+    assert any(c.hunks for c in saga.chapters)
+
+
+def test_generate_wraps_provider_errors_as_sagaerror(git_repo: Path, monkeypatch):
+    """A failure from the LLM client is surfaced as a SagaError, not a raw
+    provider exception."""
+    import saga.generate as gen
+
+    class BoomClient:
+        def create(self, **kwargs):
+            raise RuntimeError("upstream 529 overloaded")
+
+    monkeypatch.setattr(gen, "_build_client", lambda model: BoomClient())
+    with pytest.raises(SagaError, match="Saga generation failed"):
+        generate(git_repo, "main", "feature", model="anthropic/claude-opus-4-8")
+
+
+def test_cassette_is_scrubbed():
+    """Committed cassette must not carry a real API key."""
+    cassette = Path(__file__).parent / "cassettes" / "generate_anthropic.yaml"
+    if not cassette.exists():
+        pytest.skip("cassette not recorded yet")
+    text = cassette.read_text()
+    assert "sk-ant-" not in text
+    assert "REDACTED" in text
+
+
+# ---------------------------------------------------------------------------
+# claude-cli provider (subprocess out to `claude -p`), no network / no binary
+# ---------------------------------------------------------------------------
+
+_ENVELOPE_CHAPTERS = {
+    "chapters": [
+        {"id": "c1", "title": "T", "summary": "S", "narration": "N", "hunks": ["h0"]}
+    ]
+}
+
+
+def _envelope(**fields) -> str:
+    """Serialize a `claude -p --output-format json` envelope for stubbed stdout."""
+    return json.dumps(fields)
+
+
+def _fake_claude(monkeypatch, *, stdout: str, returncode: int = 0) -> dict:
+    """Patch subprocess.run to skip the real binary and record how it was called."""
+    import saga.generate as gen
+
+    captured: dict = {}
+
+    def fake_run(cmd, **kwargs):
+        captured["cmd"] = cmd
+        captured["kwargs"] = kwargs
+        return subprocess.CompletedProcess(cmd, returncode, stdout=stdout, stderr="")
+
+    monkeypatch.setattr(gen.subprocess, "run", fake_run)
+    return captured
+
+
+def test_claude_cli_parses_structured_output(monkeypatch):
+    stdout = _envelope(is_error=False, structured_output=_ENVELOPE_CHAPTERS)
+    _fake_claude(monkeypatch, stdout=stdout)
+    result = _generate_via_claude_cli("claude-cli", "sys prompt", "the diff")
+    assert result.chapters[0].id == "c1"
+    assert result.chapters[0].hunks == ["h0"]
+
+
+def test_claude_cli_command_pins_model_and_scrubs_key(monkeypatch):
+    monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-ant-should-be-dropped")
+    monkeypatch.setenv("ANTHROPIC_AUTH_TOKEN", "tok-should-be-dropped")
+    captured = _fake_claude(
+        monkeypatch, stdout=_envelope(structured_output=_ENVELOPE_CHAPTERS)
+    )
+
+    _generate_via_claude_cli("claude-cli/sonnet", "sys prompt", "the diff")
+
+    cmd = captured["cmd"]
+    assert cmd[:2] == ["claude", "-p"]
+    assert "--json-schema" in cmd
+    # claude-cli/<alias> pins the model; bare claude-cli would omit --model.
+    assert cmd[cmd.index("--model") + 1] == "sonnet"
+    # The diff is piped on stdin, not passed as an argument.
+    assert captured["kwargs"]["input"] == "the diff"
+    # API-key env vars are dropped so the subprocess uses the Claude Code login.
+    env = captured["kwargs"]["env"]
+    assert "ANTHROPIC_API_KEY" not in env
+    assert "ANTHROPIC_AUTH_TOKEN" not in env
+
+
+def test_claude_cli_bare_model_omits_model_flag(monkeypatch):
+    captured = _fake_claude(
+        monkeypatch, stdout=_envelope(structured_output=_ENVELOPE_CHAPTERS)
+    )
+    _generate_via_claude_cli("claude-cli", "sys prompt", "the diff")
+    assert "--model" not in captured["cmd"]
+
+
+def test_claude_cli_tolerates_leading_warning_line(monkeypatch):
+    # Claude Code prints a stray warning before the JSON envelope on some setups.
+    stdout = "⚠ connectors disabled\n" + _envelope(structured_output=_ENVELOPE_CHAPTERS)
+    _fake_claude(monkeypatch, stdout=stdout)
+    result = _generate_via_claude_cli("claude-cli", "sys prompt", "the diff")
+    assert result.chapters[0].id == "c1"
+
+
+def test_claude_cli_missing_binary_raises_sagaerror(monkeypatch):
+    import saga.generate as gen
+
+    def boom(cmd, **kwargs):
+        raise FileNotFoundError("claude")
+
+    monkeypatch.setattr(gen.subprocess, "run", boom)
+    with pytest.raises(SagaError, match="claude CLI not found"):
+        _generate_via_claude_cli("claude-cli", "sys prompt", "the diff")
+
+
+def test_claude_cli_nonzero_exit_raises_sagaerror(monkeypatch):
+    _fake_claude(monkeypatch, stdout="", returncode=1)
+    with pytest.raises(SagaError, match="claude CLI failed"):
+        _generate_via_claude_cli("claude-cli", "sys prompt", "the diff")
+
+
+def test_claude_cli_missing_structured_output_raises_sagaerror(monkeypatch):
+    _fake_claude(monkeypatch, stdout=_envelope(is_error=False, result="text only"))
+    with pytest.raises(SagaError, match="no structured_output"):
+        _generate_via_claude_cli("claude-cli", "sys prompt", "the diff")
+
+
+def test_generate_dispatches_to_claude_cli(git_repo: Path, monkeypatch):
+    """A claude-cli model routes through the subprocess path, not instructor."""
+    import saga.generate as gen
+
+    called: dict = {}
+
+    def fake_cli(model, system_prompt, user_message):
+        called["model"] = model
+        return _SagaOut.model_validate(_ENVELOPE_CHAPTERS)
+
+    def no_client(model):
+        pytest.fail("should not build an instructor client")
+
+    monkeypatch.setattr(gen, "_generate_via_claude_cli", fake_cli)
+    monkeypatch.setattr(gen, "_build_client", no_client)
+    # Coverage against git_repo's real hunks isn't the point of this test — the
+    # stub chapters don't span them — so neutralize the check here.
+    monkeypatch.setattr(gen, "validate_coverage", lambda chapters, hunks: None)
+    saga = generate(git_repo, "main", "feature", model="claude-cli/sonnet")
+    assert called["model"] == "claude-cli/sonnet"
+    assert len(saga.chapters) >= 1

saga_cli-0.1.0/saga/generate.py

@@ -1,182 +0,0 @@
-"""Generate a saga for one change set via a single structured LLM call.
-
-The call takes the full diff (every hunk labeled by a stable id), the commit
-messages, and an optional intent document, and returns strict, schema-validated
-JSON. Coverage is re-validated in code before trusting it — nothing the model
-returns is assumed complete.
-
-Provider-agnostic: the model is chosen by a ``provider/model`` string (e.g.
-``anthropic/claude-opus-4-8``, ``openai/gpt-4o``,
-``openrouter/anthropic/claude-3.5-sonnet``) and dispatched through ``instructor``.
-The API key is read from the provider's standard environment variable
-(``ANTHROPIC_API_KEY`` / ``OPENAI_API_KEY`` / ``OPENROUTER_API_KEY``).
-"""
-
-from __future__ import annotations
-
-import os
-from pathlib import Path
-from typing import Literal
-
-import instructor
-from pydantic import BaseModel, Field
-
-from .diff import DiffResult, compute_diff, rev_parse
-from .model import (
-    Chapter,
-    Hunk,
-    Saga,
-    SagaError,
-    parse_hunks,
-    validate_coverage,
-)
-
-_MAX_TOKENS = 16000
-_OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
-_PROMPT_PATH = Path(__file__).resolve().parent / "prompts" / "saga.md"
-
-
-# ---------------------------------------------------------------------------
-# LLM response schema — what the model must return (validated by instructor).
-# Mapped onto the persisted ``Chapter`` dataclass below so model.py's core,
-# validate_coverage, and render.py stay untouched.
-# ---------------------------------------------------------------------------
-
-
-class _QAOut(BaseModel):
-    status: str
-    note: str = ""
-
-
-class _ChapterOut(BaseModel):
-    id: str
-    title: str
-    summary: str
-    narration: str
-    hunks: list[str] = Field(default_factory=list)
-    plan_step: str | None = None
-    confidence: Literal["high", "medium", "low"] = "medium"
-    deviation: str | None = None
-    qa: _QAOut | None = None
-
-
-class _SagaOut(BaseModel):
-    chapters: list[_ChapterOut]
-
-
-def _to_chapter(c: _ChapterOut) -> Chapter:
-    return Chapter(
-        id=c.id,
-        title=c.title,
-        summary=c.summary,
-        narration=c.narration,
-        hunks=list(c.hunks),
-        plan_step=c.plan_step,
-        confidence=c.confidence,
-        deviation=c.deviation or None,
-        qa=c.qa.model_dump() if c.qa else None,
-    )
-
-
-def labeled_diff(hunks: list[Hunk]) -> str:
-    """Render the diff for the prompt with each hunk headed by its stable id."""
-    out: list[str] = []
-    for h in hunks:
-        first = h.body.splitlines()[0] if h.body else ""
-        out.append(f"### HUNK {h.id} — {h.file_path}  ({first.strip()})")
-        out.append(h.body.rstrip("\n"))
-    return "\n".join(out)
-
-
-def _build_message(diff: DiffResult, hunks: list[Hunk], intent: str | None) -> str:
-    """Assemble the user message: intent (optional), commits, and labeled diff."""
-    commits = "\n".join(diff.commits) or "(no commit messages)"
-    intent_block = (
-        ["# Intent (what this change set out to do)", intent.strip(), ""]
-        if intent and intent.strip()
-        else []
-    )
-    return "\n".join(
-        [
-            *intent_block,
-            "# Commits",
-            commits,
-            "",
-            "# Full diff (every hunk must be assigned to a chapter)",
-            labeled_diff(hunks),
-        ]
-    )
-
-
-def _build_client(model: str) -> instructor.Instructor:
-    """Build an instructor client for a ``provider/model`` string.
-
-    OpenRouter is OpenAI-compatible, so it needs an explicit base URL and its own
-    key; Anthropic and OpenAI resolve their keys from the SDK's standard env vars.
-    """
-    provider = model.split("/", 1)[0]
-    try:
-        if provider == "openrouter":
-            key = os.environ.get("OPENROUTER_API_KEY")
-            if not key:
-                raise SagaError("OPENROUTER_API_KEY is not set.")
-            return instructor.from_provider(
-                model, base_url=_OPENROUTER_BASE_URL, api_key=key
-            )
-        return instructor.from_provider(model)
-    except SagaError:
-        raise
-    except Exception as e:
-        raise SagaError(f"Could not initialize model {model!r}: {e}") from e
-
-
-def generate(
-    repo_root: Path,
-    base: str,
-    head: str,
-    *,
-    model: str,
-    intent: str | None = None,
-) -> Saga:
-    """Generate the saga for *base*...*head*.
-
-    Raises ``SagaError`` on an empty diff, a provider/model error, or a
-    coverage gap. The caller renders the error as a user-facing message.
-    """
-    diff = compute_diff(repo_root, base, head)
-    hunks = parse_hunks(diff.diff_text)
-    if not hunks:
-        raise SagaError("No reviewable hunks in this change set.")
-
-    client = _build_client(model)
-    system_prompt = _PROMPT_PATH.read_text()
-    kwargs: dict = {}
-    if model.split("/", 1)[0] == "openrouter":
-        # Ask OpenRouter to route only to providers that support the params we
-        # send (structured output), so schema enforcement is honored.
-        kwargs["extra_body"] = {"provider": {"require_parameters": True}}
-
-    try:
-        result: _SagaOut = client.create(
-            response_model=_SagaOut,
-            max_tokens=_MAX_TOKENS,
-            messages=[
-                {"role": "system", "content": system_prompt},
-                {"role": "user", "content": _build_message(diff, hunks, intent)},
-            ],
-            **kwargs,
-        )
-    except SagaError:
-        raise
-    except Exception as e:
-        raise SagaError(f"Saga generation failed: {e}") from e
-
-    chapters = [_to_chapter(c) for c in result.chapters]
-    validate_coverage(chapters, hunks)
-
-    return Saga(
-        branch=head,
-        base=base,
-        commit_sha=rev_parse(repo_root, head),
-        chapters=chapters,
-    )

saga_cli-0.1.0/tests/test_generate.py

@@ -1,153 +0,0 @@
-"""Tests for saga generation.
-
-The one real LLM HTTP call is recorded to a VCR cassette (auth headers scrubbed)
-and replayed offline. Everything around it — prompt assembly, client selection,
-schema→dataclass mapping, and the empty-diff guard — is tested without network.
-
-Re-record with a real key via:  SAGA_RECORD=1 ANTHROPIC_API_KEY=... pytest
-"""
-
-from __future__ import annotations
-
-import os
-from pathlib import Path
-
-import pytest
-
-from saga.generate import (
-    _build_client,
-    _build_message,
-    _ChapterOut,
-    _QAOut,
-    _to_chapter,
-    generate,
-    labeled_diff,
-)
-from saga.model import SagaError, parse_hunks
-
-# ---------------------------------------------------------------------------
-# Prompt assembly (pure)
-# ---------------------------------------------------------------------------
-
-TWO_FILE_DIFF = (
-    "diff --git a/foo.py b/foo.py\n"
-    "--- a/foo.py\n+++ b/foo.py\n"
-    "@@ -1,2 +1,2 @@\n a\n-b\n+B\n"
-)
-
-
-def test_labeled_diff_heads_each_hunk_with_id():
-    hunks = parse_hunks(TWO_FILE_DIFF)
-    out = labeled_diff(hunks)
-    assert "### HUNK h0 — foo.py" in out
-    assert "@@ -1,2 +1,2 @@" in out
-
-
-def test_build_message_includes_intent_commits_and_diff():
-    from saga.diff import DiffResult
-
-    diff = DiffResult(diff_text=TWO_FILE_DIFF, commits=["abc fix bug"], diffstat="")
-    hunks = parse_hunks(TWO_FILE_DIFF)
-    msg = _build_message(diff, hunks, intent="Fix the bug.")
-    assert "# Intent" in msg
-    assert "Fix the bug." in msg
-    assert "abc fix bug" in msg
-    assert "### HUNK h0" in msg
-
-
-def test_build_message_omits_intent_block_when_absent():
-    from saga.diff import DiffResult
-
-    diff = DiffResult(diff_text=TWO_FILE_DIFF, commits=[], diffstat="")
-    hunks = parse_hunks(TWO_FILE_DIFF)
-    msg = _build_message(diff, hunks, intent=None)
-    assert "# Intent" not in msg
-    assert "(no commit messages)" in msg
-
-
-def test_to_chapter_maps_schema_to_dataclass():
-    out = _ChapterOut(
-        id="c1",
-        title="T",
-        summary="S",
-        narration="N",
-        hunks=["h0"],
-        confidence="high",
-        deviation="",
-        qa=_QAOut(status="green", note="ok"),
-    )
-    ch = _to_chapter(out)
-    assert ch.id == "c1"
-    assert ch.confidence == "high"
-    # Empty-string deviation normalizes to None.
-    assert ch.deviation is None
-    assert ch.qa == {"status": "green", "note": "ok"}
-
-
-# ---------------------------------------------------------------------------
-# Client selection / error handling (no network)
-# ---------------------------------------------------------------------------
-
-
-def test_build_client_openrouter_without_key_raises(monkeypatch):
-    monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
-    with pytest.raises(SagaError, match="OPENROUTER_API_KEY"):
-        _build_client("openrouter/anthropic/claude-3.5-sonnet")
-
-
-def test_build_client_unknown_provider_raises_sagaerror(monkeypatch):
-    with pytest.raises(SagaError, match="Could not initialize model"):
-        _build_client("bogusprovider/some-model")
-
-
-def test_generate_empty_diff_raises_before_any_network(empty_diff_repo: Path):
-    with pytest.raises(SagaError, match="No reviewable hunks"):
-        generate(empty_diff_repo, "main", "feature", model="anthropic/claude-opus-4-8")
-
-
-# ---------------------------------------------------------------------------
-# Full generation, replayed from a scrubbed cassette
-# ---------------------------------------------------------------------------
-
-
-def test_generate_full_saga_from_cassette(git_repo: Path, vcr_cassette, monkeypatch):
-    # Replay needs a syntactically-valid key for client construction; the real
-    # HTTP is served by the cassette. Don't clobber a real key while recording.
-    if not os.environ.get("ANTHROPIC_API_KEY"):
-        monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-ant-test-dummy")
-
-    with vcr_cassette.use_cassette("generate_anthropic.yaml"):
-        saga = generate(git_repo, "main", "feature", model="anthropic/claude-opus-4-8")
-
-    assert saga.base == "main"
-    assert saga.branch == "feature"
-    assert saga.commit_sha and len(saga.commit_sha) == 40
-    assert len(saga.chapters) >= 1
-    # generate() re-validates coverage internally, so reaching here means every
-    # hunk in the live diff was assigned. Confirm the chapters carry content.
-    assert all(c.id for c in saga.chapters)
-    assert any(c.hunks for c in saga.chapters)
-
-
-def test_generate_wraps_provider_errors_as_sagaerror(git_repo: Path, monkeypatch):
-    """A failure from the LLM client is surfaced as a SagaError, not a raw
-    provider exception."""
-    import saga.generate as gen
-
-    class BoomClient:
-        def create(self, **kwargs):
-            raise RuntimeError("upstream 529 overloaded")
-
-    monkeypatch.setattr(gen, "_build_client", lambda model: BoomClient())
-    with pytest.raises(SagaError, match="Saga generation failed"):
-        generate(git_repo, "main", "feature", model="anthropic/claude-opus-4-8")
-
-
-def test_cassette_is_scrubbed():
-    """Committed cassette must not carry a real API key."""
-    cassette = Path(__file__).parent / "cassettes" / "generate_anthropic.yaml"
-    if not cassette.exists():
-        pytest.skip("cassette not recorded yet")
-    text = cassette.read_text()
-    assert "sk-ant-" not in text
-    assert "REDACTED" in text