transcript-viewer 0.5.0__py3-none-any.whl

transcript_viewer/__init__.py

@@ -0,0 +1,5 @@
+"""transcript-viewer — browse ATIF trajectories in a local web viewer."""
+
+from .viewer import serve
+
+__all__ = ["serve"]

transcript_viewer/ai.py

@@ -0,0 +1,374 @@
+"""Optional Claude-backed help: explain one tool call, or answer a question
+about a transcript.
+
+Nothing here runs unless asked. A transcript carries source code, file contents
+and tool output, so no call is made in the background, on load, or ahead of a
+click — the viewer is local-only until you press a button.
+
+The `anthropic` SDK is an optional extra (`pip install "transcript-viewer[ai]"`) so the
+package keeps its zero-dependency install; these features simply hide when it,
+or a credential, is absent.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterator
+from typing import Any
+
+from . import config
+
+MODEL = "claude-opus-5"
+
+# Most transcripts are small enough to send whole; a few are not. The largest
+# here is 8,445 steps and 12.9M characters, so there has to be a ceiling — but
+# it applies only when a session actually exceeds it.
+ASK_BUDGET_CHARS = 300_000
+ASK_STEPS = 40
+STEP_CLIP = 8_000
+
+
+class Unavailable(RuntimeError):
+    """No SDK, or no credential. Both mean the same thing to a caller."""
+
+
+def _client():
+    try:
+        import anthropic
+    except ImportError as exc:  # pragma: no cover - depends on the extra
+        raise Unavailable(
+            'The anthropic package is not installed: uv tool install "transcript-viewer[ai]"'
+        ) from exc
+    try:
+        # A key from settings, else the SDK's own resolution: ANTHROPIC_API_KEY,
+        # ANTHROPIC_AUTH_TOKEN, or an `ant auth login` profile. Never a key sent
+        # up by the page — it only ever travels from the browser to storage.
+        stored = config.api_key()
+        return anthropic.Anthropic(api_key=stored) if stored else anthropic.Anthropic()
+    except Exception as exc:
+        raise Unavailable(
+            "No Anthropic credential found. Add a key here, or set ANTHROPIC_API_KEY."
+        ) from exc
+
+
+def status() -> tuple[bool, str]:
+    """Whether AI can run, and if not, what is missing.
+
+    A bare boolean was not enough: a saved key with no SDK installed looks
+    exactly like no key at all, which reads as "the save didn't work".
+    """
+    try:
+        _client()
+    except Unavailable as exc:
+        return False, str(exc)
+    return True, ""
+
+
+def available() -> bool:
+    """Whether the controls should be offered at all."""
+    return status()[0]
+
+
+def _stream(
+    client,
+    system: str,
+    messages: list[dict],
+    max_tokens: int,
+    thinking: bool = True,
+) -> Iterator[tuple[str, str]]:
+    """One request, yielding ("thinking" | "text", piece) as it arrives.
+
+    Two kinds, not one, because thinking produces no text: a model that thinks
+    for twenty seconds before its first word looks identical to a hang. The
+    caller can say "thinking" while that is what is happening.
+
+    `thinking` is off for work that does not need it — a two-sentence
+    description of one tool call is delayed, not improved, by deliberation.
+    """
+    import anthropic
+
+    request: dict[str, Any] = {
+        "model": MODEL,
+        "max_tokens": max_tokens,
+        "system": system,
+        "messages": messages,
+    }
+    if thinking:
+        request["thinking"] = {"type": "adaptive"}
+
+    try:
+        with client.messages.stream(**request) as stream:
+            for event in stream:
+                if event.type != "content_block_delta":
+                    continue
+                kind = getattr(event.delta, "type", "")
+                if kind == "thinking_delta":
+                    yield "thinking", event.delta.thinking
+                elif kind == "text_delta":
+                    yield "text", event.delta.text
+            message = stream.get_final_message()
+    except anthropic.NotFoundError as exc:
+        raise Unavailable(f"Model {MODEL} is not available to this account.") from exc
+    except anthropic.RateLimitError as exc:
+        raise Unavailable("Rate limited by the API — try again shortly.") from exc
+    except anthropic.APIStatusError as exc:
+        raise Unavailable(f"The API refused that request: {exc.status_code}") from exc
+    except anthropic.APIConnectionError as exc:
+        raise Unavailable("Could not reach the API.") from exc
+
+    # Raised after the text, so a refusal is not silently shown as an answer.
+    if message.stop_reason == "refusal":
+        raise Unavailable("The model declined to answer that.")
+
+
+def _text_only(pieces: Iterator[tuple[str, str]]) -> str:
+    """Collect a stream into the answer, dropping the thinking."""
+    return "".join(text for kind, text in pieces if kind == "text").strip()
+
+
+def _clip(value: Any, limit: int = 4000) -> str:
+    text = value if isinstance(value, str) else json.dumps(value, indent=2)[:limit]
+    return text[:limit]
+
+
+# ---------------------------------------------------------------- one call ---
+
+CALL_SYSTEM = """You explain a single step from an agent transcript to someone \
+reviewing it later.
+
+Two or three sentences. Start with the call itself. What's it asking, in layperson terms? Then \
+explain what actually came back — including whether it failed. No markdown \
+headings."""
+
+
+def _call_prompt(call: dict, output: Any) -> str:
+    parts = [
+        f"Tool: {call.get('function_name', 'unknown')}",
+        f"Arguments:\n{_clip(call.get('arguments', {}))}",
+    ]
+    parts.append(f"Output:\n{_clip(output, 6000)}" if output else "Output: (none recorded)")
+    return "\n\n".join(parts)
+
+
+def summarise_call_stream(call: dict, output: Any = None) -> Iterator[tuple[str, str]]:
+    """Explain one tool call, a piece at a time.
+
+    The client is built before returning, so a missing credential is an error
+    the caller sees immediately rather than one that surfaces mid-stream.
+    Thinking is off: this is a description, and the first word should be quick.
+    """
+    client = _client()
+    return _stream(
+        client,
+        CALL_SYSTEM,
+        [{"role": "user", "content": _call_prompt(call, output)}],
+        max_tokens=1000,
+        thinking=False,
+    )
+
+
+def summarise_call(call: dict, output: Any = None) -> str:
+    """Explain one tool call and its result."""
+    return _text_only(summarise_call_stream(call, output))
+
+
+# ------------------------------------------------------------------- ask -----
+
+ASK_SYSTEM = """You answer questions about an agent transcript, for someone \
+reviewing what happened.
+
+Answer only from the steps given. Cite the step numbers you used, as (step 42). \
+If the steps do not contain the answer, say so plainly rather than guessing — \
+they are a relevant-looking subset, not the whole transcript, so "it is not in \
+what I was shown" is a useful answer.
+
+This is a conversation. Each turn brings a fresh selection of steps chosen for \
+that question, so steps quoted earlier may not be in front of you now; rely on \
+what you said before rather than pretending to re-read them. A follow-up like \
+"why?" refers to the previous answer.
+
+Be direct and concrete. No preamble."""
+
+# Enough for a real conversation, bounded so a long one cannot grow without
+# limit — each turn already carries a fresh page of steps.
+HISTORY_TURNS = 8
+HISTORY_CHARS = 4000
+
+
+def _text_of(step: dict) -> str:
+    """Everything in a step a reader could have seen."""
+    parts: list[str] = []
+    message = step.get("message")
+    if isinstance(message, str):
+        parts.append(message)
+    elif isinstance(message, list):
+        parts += [p.get("text", "") for p in message if isinstance(p, dict)]
+    if step.get("reasoning_content"):
+        parts.append(step["reasoning_content"])
+    for call in step.get("tool_calls") or []:
+        parts.append(call.get("function_name", ""))
+        parts.append(json.dumps(call.get("arguments", {})))
+    for result in (step.get("observation") or {}).get("results") or []:
+        content = result.get("content")
+        if isinstance(content, str):
+            parts.append(content)
+    return "\n".join(p for p in parts if p)
+
+
+def _fallback(steps: list[dict], limit: int, focus: list[int] | None) -> list[dict]:
+    """Nothing in the question matched anything in the transcript.
+
+    A follow-up is almost always about what the last answer read, so those steps
+    are the better guess than an arbitrary slice. Only a question with no prior
+    turn to lean on gets the closing steps.
+    """
+    if focus:
+        wanted = set(focus)
+        carried = [s for s in steps if s.get("step_id") in wanted]
+        if carried:
+            return carried[:limit]
+    # Latest first: this is a recency guess, so if the budget forces a trim it
+    # should give up the oldest steps, not the newest.
+    return list(reversed(steps[-limit:]))
+
+
+def _ranked_steps(
+    question: str,
+    steps: list[dict],
+    limit: int = ASK_STEPS,
+    focus: list[int] | None = None,
+) -> list[dict]:
+    """The candidate steps, best first.
+
+    Priority order rather than document order, so that a budget trim gives up
+    the least useful steps instead of whichever happen to come last.
+    """
+    words = {w for w in re.findall(r"[a-zA-Z_][\w./-]{2,}", question.lower())}
+
+    # A question says "authentication" where the transcript says "test_auth.py",
+    # so a long word also scores, at a discount, on its first four characters.
+    # Cheaper than tokenising every step, and wrong guesses only mis-rank.
+    stems = {w: w[:4] for w in words if len(w) > 6}
+
+    scored = []
+    for step in steps:
+        haystack = _text_of(step).lower()
+        score = 0
+        for word in words:
+            if word in haystack:
+                score += len(word)
+            elif word in stems and stems[word] in haystack:
+                score += 2
+        if score:
+            scored.append((score, step.get("step_id", 0), step))
+
+    # "Nothing matched" is the condition that matters, not "no words": a
+    # question can be all common words and still hit nothing.
+    if not scored:
+        return _fallback(steps, limit, focus)
+
+    scored.sort(key=lambda row: (-row[0], row[1]))
+    return [row[2] for row in scored[:limit]]
+
+
+def relevant_steps(
+    question: str,
+    steps: list[dict],
+    limit: int = ASK_STEPS,
+    focus: list[int] | None = None,
+) -> list[dict]:
+    """The steps most likely to bear on the question, in document order.
+
+    Scored by how many of the question's words a step mentions, preferring
+    longer words, then sorted chronologically so an answer reads in order.
+    Only reached when a transcript is too large to send whole.
+    """
+    return sorted(
+        _ranked_steps(question, steps, limit, focus),
+        key=lambda s: s.get("step_id", 0),
+    )
+
+
+def _block(step: dict) -> str:
+    body = _text_of(step)[:STEP_CLIP]
+    return f"--- step {step.get('step_id')} ({step.get('source')}) ---\n{body}"
+
+
+def _ask_prompt(
+    question: str, steps: list[dict], focus: list[int] | None = None
+) -> tuple[str, list[int]]:
+    """The prompt, and the step numbers that went into it.
+
+    When the whole transcript fits, the whole transcript goes. Choosing forty
+    steps out of a session that would fit entire only throws information away,
+    and most sessions are that size — selection is the exception, not the rule.
+    """
+    whole = [_block(s) for s in steps]
+    if sum(len(b) + 2 for b in whole) <= ASK_BUDGET_CHARS:
+        chosen = steps
+    else:
+        # Trimmed in priority order, then read back in document order: what
+        # survives the budget should be the most useful steps, but the model
+        # should still see them chronologically.
+        kept: list[dict] = []
+        budget = ASK_BUDGET_CHARS
+        for step in _ranked_steps(question, steps, focus=focus):
+            size = len(_block(step))
+            # Skipped, not stopped at: one oversized step used to truncate every
+            # step after it, including small ones that would have fitted.
+            if size > budget:
+                continue
+            budget -= size
+            kept.append(step)
+        chosen = sorted(kept, key=lambda s: s.get("step_id", 0))
+
+    used = [s.get("step_id", 0) for s in chosen]
+    body = "\n\n".join(_block(s) for s in chosen)
+    return f"Question: {question}\n\nSteps:\n\n{body}", used
+
+
+def _history(turns: list[dict] | None) -> list[dict]:
+    """Prior questions and answers as messages.
+
+    The steps that were sent with an earlier question are deliberately not
+    replayed: they are already digested into the answer, and re-sending a page
+    of transcript per turn would make a long conversation quadratic.
+    """
+    messages: list[dict] = []
+    for turn in (turns or [])[-HISTORY_TURNS:]:
+        question = str(turn.get("q") or "").strip()[:HISTORY_CHARS]
+        answer = str(turn.get("a") or "").strip()[:HISTORY_CHARS]
+        if not question or not answer:
+            continue
+        messages.append({"role": "user", "content": question})
+        messages.append({"role": "assistant", "content": answer})
+    return messages
+
+
+def ask_stream(
+    question: str,
+    steps: list[dict],
+    history: list[dict] | None = None,
+    focus: list[int] | None = None,
+) -> tuple[list[int], Iterator[tuple[str, str]]]:
+    """The steps being used, and the answer as it arrives.
+
+    The steps are known before the first token, so the viewer can say what it is
+    reading while the answer is still being written.
+    """
+    client = _client()
+    prompt, used = _ask_prompt(question, steps, focus)
+    messages = [*_history(history), {"role": "user", "content": prompt}]
+    return used, _stream(client, ASK_SYSTEM, messages, max_tokens=4000)
+
+
+def ask(
+    question: str,
+    steps: list[dict],
+    history: list[dict] | None = None,
+    focus: list[int] | None = None,
+) -> tuple[str, list[int]]:
+    """Answer a question about a transcript. Returns the answer and steps used."""
+    used, chunks = ask_stream(question, steps, history, focus)
+    return _text_only(chunks), used

transcript_viewer/cli.py

@@ -0,0 +1,87 @@
+"""transcript-viewer command line."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import corpus, store
+from atif_make.archive import is_archive
+
+from .viewer import serve
+
+
+def _single_entry(path: Path) -> list[corpus.Entry]:
+    """One file as an index entry, so it can be viewed without indexing.
+
+    Built by corpus.describe rather than assembled here: an Entry that is put
+    together in two places drifts the moment a field is added, and this one had
+    already fallen behind.
+    """
+    entry = corpus.describe(path)
+    return [entry] if entry else []
+
+
+def cmd_view(args: argparse.Namespace) -> int:
+    # The tool was called atif-view and kept its library under ~/.atif. Adopt
+    # one if it is still there, before anything reads an index that would
+    # otherwise look empty.
+    if store.adopt_legacy():
+        print(
+            f"transcript-viewer: moved your library from {store.LEGACY_ROOT} "
+            f"to {store.ROOT}",
+            file=sys.stderr,
+        )
+
+    if args.input:
+        path = Path(args.input).expanduser()
+        if not path.exists():
+            print(f"transcript-viewer: no such path: {path}", file=sys.stderr)
+            return 2
+        # A directory or archive holds many sessions; a plain file holds one.
+        entries = (
+            corpus.scan([path])
+            if path.is_dir() or is_archive(path)
+            else _single_entry(path)
+        )
+        # An explicit path that holds nothing is a mistake worth reporting; an
+        # empty library is not, so this only guards the argument.
+        if not entries:
+            print(f"transcript-viewer: nothing convertible in {path}", file=sys.stderr)
+            return 1
+    else:
+        # Only what has been added deliberately. Scanning a machine because the
+        # library happens to be empty indexes someone's whole history of every
+        # agent without being asked; the viewer opens empty and offers to.
+        entries = corpus.load()
+    serve(
+        entries,
+        port=args.port or 7433,
+        open_browser=not args.no_open,
+        explicit_port=args.port is not None,
+    )
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="transcript-viewer",
+        description="Browse agent transcripts in a local viewer.",
+    )
+    parser.add_argument("input", nargs="?",
+                        help="file, directory or archive (default: the atif-make index)")
+    parser.add_argument("--port", type=int, default=None,
+                        help="port to listen on (default: 7433, or the next free one)")
+    parser.add_argument("--no-open", action="store_true", help="do not open a browser")
+    parser.set_defaults(func=cmd_view)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(list(sys.argv[1:] if argv is None else argv))
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

transcript_viewer/config.py

@@ -0,0 +1,193 @@
+"""Viewer settings, including optional API tokens.
+
+A token kept in a file is weaker than one in the system keychain or a password
+manager, so this module is deliberately narrow about them:
+
+  * they live at ~/.transcript-viewer/config.json, 0600, inside a 0700 directory;
+  * they are never returned to the page, never logged, and never put in a URL —
+    the page only ever learns that one is set and its last four characters;
+  * they are only ever read to authenticate a request.
+
+The environment is still honoured. With nothing stored, each service's usual
+variables apply as they would anywhere else.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from . import store
+
+CONFIG_PATH = store.ROOT / "config.json"
+VERSION = 1
+
+# Long enough to be a real token, short enough to reject a pasted paragraph.
+MIN_TOKEN = 20
+MAX_TOKEN = 300
+
+
+@dataclass(frozen=True)
+class Secret:
+    """One credential the viewer can hold."""
+
+    name: str
+    label: str
+    field: str  # where it is kept in config.json
+    env: tuple[str, ...]  # the variables that stand in for it
+    placeholder: str
+
+
+SECRETS: dict[str, Secret] = {
+    "anthropic": Secret(
+        "anthropic",
+        "Anthropic API key",
+        "api_key",
+        ("ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"),
+        "sk-ant-…",
+    ),
+    "hf": Secret(
+        "hf",
+        "Hugging Face token",
+        "hf_token",
+        ("HF_TOKEN", "HUGGING_FACE_HUB_TOKEN"),
+        "hf_…",
+    ),
+    "github": Secret(
+        "github",
+        "GitHub token",
+        "github_token",
+        ("GITHUB_TOKEN", "GH_TOKEN"),
+        "ghp_…",
+    ),
+}
+
+
+# The AWS profile is a name rather than a credential — the CLI holds the
+# credential — so it is stored and shown in full.
+PROFILE_FIELD = "aws_profile"
+# A leading "-" would be read as an option by the CLI, so a name may not
+# start with one. Empty is allowed and means the default profile.
+PROFILE_OK = re.compile(r"^(?:[\w.@][\w.@-]{0,63})?$")
+
+
+def aws_profile(path: Path | None = None) -> str:
+    value = load(path).get(PROFILE_FIELD)
+    return value if isinstance(value, str) else ""
+
+
+def set_aws_profile(value: str, path: Path | None = None) -> None:
+    value = (value or "").strip()
+    if not PROFILE_OK.match(value):
+        raise ValueError("that does not look like an AWS profile name")
+    path = path or CONFIG_PATH
+    store.write_json(
+        path, {**load(path), "version": VERSION, PROFILE_FIELD: value}, private=True
+    )
+
+
+def load(path: Path | None = None) -> dict[str, Any]:
+    return store.read_json(path or CONFIG_PATH)
+
+
+def _spec(name: str) -> Secret:
+    secret = SECRETS.get(name)
+    if secret is None:
+        raise ValueError(f"unknown secret: {name}")
+    return secret
+
+
+def secret(name: str, path: Path | None = None) -> str | None:
+    """The stored token, else whatever the environment supplies.
+
+    A token typed into settings wins: it is the more explicit, more recent act,
+    and `source()` shows which is in use so the precedence is never a surprise.
+    """
+    spec = _spec(name)
+    value = load(path).get(spec.field)
+    if isinstance(value, str) and value:
+        return value
+    for variable in spec.env:
+        from_env = os.environ.get(variable)
+        if from_env:
+            return from_env
+    return None
+
+
+def stored(name: str, path: Path | None = None) -> str | None:
+    """Only what settings holds, ignoring the environment."""
+    value = load(path).get(_spec(name).field)
+    return value if isinstance(value, str) and value else None
+
+
+def source(name: str, path: Path | None = None) -> str | None:
+    """Where a credential comes from — for display, not for logic."""
+    if stored(name, path):
+        return "settings"
+    if any(os.environ.get(v) for v in _spec(name).env):
+        return "environment"
+    return None
+
+
+def hint(name: str, path: Path | None = None) -> str:
+    """The last four characters of a stored token, enough to tell two apart."""
+    value = stored(name, path)
+    return f"…{value[-4:]}" if value else ""
+
+
+def set_secret(name: str, value: str, path: Path | None = None) -> None:
+    """Store a token. Raises ValueError on anything that is plainly not one."""
+    spec = _spec(name)
+    value = (value or "").strip()
+    if not value:
+        raise ValueError("no token given")
+    if len(value) < MIN_TOKEN or len(value) > MAX_TOKEN:
+        raise ValueError(f"that does not look like a {spec.label.lower()}")
+    if any(c.isspace() for c in value):
+        raise ValueError("a token contains no spaces — check what was pasted")
+
+    path = path or CONFIG_PATH
+    store.write_json(
+        path, {**load(path), "version": VERSION, spec.field: value}, private=True
+    )
+
+
+def clear_secret(name: str, path: Path | None = None) -> None:
+    """Forget a stored token, falling back to the environment."""
+    path = path or CONFIG_PATH
+    data = load(path)
+    data.pop(_spec(name).field, None)
+    store.write_json(path, {**data, "version": VERSION}, private=True)
+
+
+def state(path: Path | None = None) -> dict[str, dict[str, str]]:
+    """What the page may know: which tokens exist and where from. Never a value."""
+    return {
+        name: {
+            "label": spec.label,
+            "placeholder": spec.placeholder,
+            "env": spec.env[0],
+            "source": source(name, path) or "",
+            "hint": hint(name, path),
+        }
+        for name, spec in SECRETS.items()
+    }
+
+
+def tokens(path: Path | None = None) -> dict[str, str | None]:
+    """The fetch credentials, by service name."""
+    return {
+        "hf": secret("hf", path),
+        "github": secret("github", path),
+        # Not a credential: the aws CLI resolves the session from this name.
+        "aws": aws_profile(path),
+    }
+
+
+# The Anthropic key predates the others and is referenced by name elsewhere.
+def api_key(path: Path | None = None) -> str | None:
+    """The Anthropic key, from settings or the environment."""
+    return secret("anthropic", path)