glaip-sdk 0.0.19__py3-none-any.whl → 0.0.20__py3-none-any.whl

glaip_sdk/cli/transcript/__init__.py

@@ -0,0 +1,71 @@
+"""Transcript utilities package for CLI.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from glaip_sdk.cli.transcript.cache import (
+    TranscriptCacheStats,
+    TranscriptPayload,
+    TranscriptStoreResult,
+    ensure_cache_dir,
+    get_transcript_cache_stats,
+    latest_manifest_entry,
+    manifest_path,
+    resolve_manifest_entry,
+    store_transcript,
+    suggest_filename,
+)
+from glaip_sdk.cli.transcript.cache import (
+    export_transcript as export_cached_transcript,
+)
+from glaip_sdk.cli.transcript.capture import (
+    StoredTranscriptContext,
+    coerce_events,
+    coerce_result_text,
+    compute_finished_at,
+    extract_server_run_id,
+    register_last_transcript,
+    store_transcript_for_session,
+)
+from glaip_sdk.cli.transcript.export import (
+    normalise_export_destination,
+    resolve_manifest_for_export,
+)
+from glaip_sdk.cli.transcript.launcher import (
+    maybe_launch_post_run_viewer,
+    should_launch_post_run_viewer,
+)
+from glaip_sdk.cli.transcript.viewer import (
+    PostRunViewer,
+    ViewerContext,
+    run_viewer_session,
+)
+
+__all__ = [
+    "TranscriptCacheStats",
+    "TranscriptPayload",
+    "TranscriptStoreResult",
+    "ensure_cache_dir",
+    "get_transcript_cache_stats",
+    "manifest_path",
+    "store_transcript",
+    "suggest_filename",
+    "latest_manifest_entry",
+    "resolve_manifest_entry",
+    "export_cached_transcript",
+    "StoredTranscriptContext",
+    "coerce_events",
+    "coerce_result_text",
+    "compute_finished_at",
+    "extract_server_run_id",
+    "register_last_transcript",
+    "store_transcript_for_session",
+    "resolve_manifest_for_export",
+    "normalise_export_destination",
+    "maybe_launch_post_run_viewer",
+    "should_launch_post_run_viewer",
+    "ViewerContext",
+    "PostRunViewer",
+    "run_viewer_session",
+]

glaip_sdk/cli/transcript/cache.py

@@ -0,0 +1,338 @@
+"""Helpers for storing and exporting agent run transcripts.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from collections.abc import Iterable
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+DEFAULT_CACHE_ROOT = Path(
+    os.getenv(
+        "AIP_TRANSCRIPT_CACHE_DIR",
+        Path.home() / ".config" / "glaip-sdk" / "transcripts",
+    )
+)
+MANIFEST_FILENAME = "manifest.jsonl"
+
+
+@dataclass(slots=True)
+class TranscriptPayload:
+    """Data bundle representing a captured agent run."""
+
+    events: list[dict[str, Any]]
+    default_output: str
+    final_output: str
+    agent_id: str | None
+    agent_name: str | None
+    model: str | None
+    server_run_id: str | None
+    started_at: float | None
+    finished_at: float | None
+    created_at: datetime
+    source: str
+    meta: dict[str, Any]
+    run_id: str
+
+
+@dataclass(slots=True)
+class TranscriptStoreResult:
+    """Result of writing a transcript to the local cache."""
+
+    path: Path
+    manifest_entry: dict[str, Any]
+    pruned_entries: list[dict[str, Any]]
+
+
+@dataclass(slots=True)
+class TranscriptCacheStats:
+    """Lightweight usage snapshot for the transcript cache."""
+
+    cache_dir: Path
+    entry_count: int
+    total_bytes: int
+
+
+def ensure_cache_dir(cache_dir: Path | None = None) -> Path:
+    """Ensure the cache directory exists and return it."""
+    directory = cache_dir or DEFAULT_CACHE_ROOT
+    try:
+        directory.mkdir(parents=True, exist_ok=True)
+    except PermissionError:
+        return _fallback_cache_dir()
+
+    if not os.access(directory, os.W_OK):
+        return _fallback_cache_dir()
+
+    return directory
+
+
+def _fallback_cache_dir() -> Path:
+    """Return a writable fallback cache directory under the current working tree."""
+    fallback = Path.cwd() / ".glaip-transcripts"
+    fallback.mkdir(parents=True, exist_ok=True)
+    return fallback
+
+
+def manifest_path(cache_dir: Path | None = None) -> Path:
+    """Return the manifest file path."""
+    return ensure_cache_dir(cache_dir) / MANIFEST_FILENAME
+
+
+def _parse_iso(ts: str | None) -> datetime | None:
+    if not ts:
+        return None
+    try:
+        return datetime.fromisoformat(ts.replace("Z", "+00:00"))
+    except Exception:
+        return None
+
+
+def _load_manifest_entries(cache_dir: Path | None = None) -> list[dict[str, Any]]:
+    path = manifest_path(cache_dir)
+    entries: list[dict[str, Any]] = []
+    if not path.exists():
+        return entries
+
+    with path.open("r", encoding="utf-8") as fh:
+        for line in fh:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                entry = json.loads(line)
+                entries.append(entry)
+            except json.JSONDecodeError:
+                continue
+    return entries
+
+
+def _json_default(value: Any) -> Any:
+    """Ensure non-serialisable values degrade to readable strings."""
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+    if isinstance(value, Path):
+        return str(value)
+    return repr(value)
+
+
+def _write_manifest(
+    entries: Iterable[dict[str, Any]], cache_dir: Path | None = None
+) -> None:
+    path = manifest_path(cache_dir)
+    with path.open("w", encoding="utf-8") as fh:
+        for entry in entries:
+            fh.write(json.dumps(entry, ensure_ascii=False, default=_json_default))
+            fh.write("\n")
+
+
+def store_transcript(
+    payload: TranscriptPayload,
+    *,
+    cache_dir: Path | None = None,
+) -> TranscriptStoreResult:
+    """Persist a transcript to disk and update the manifest."""
+    directory = ensure_cache_dir(cache_dir)
+    filename = f"run-{payload.run_id}.jsonl"
+    transcript_path = directory / filename
+
+    meta_line = {
+        "type": "meta",
+        "run_id": payload.run_id,
+        "agent_id": payload.agent_id,
+        "agent_name": payload.agent_name,
+        "model": payload.model,
+        "created_at": payload.created_at.isoformat(),
+        "default_output": payload.default_output,
+        "final_output": payload.final_output,
+        "server_run_id": payload.server_run_id,
+        "started_at": payload.started_at,
+        "finished_at": payload.finished_at,
+        "meta": payload.meta,
+        "source": payload.source,
+    }
+
+    def _write_transcript(path: Path) -> None:
+        with path.open("w", encoding="utf-8") as fh:
+            fh.write(json.dumps(meta_line, ensure_ascii=False, default=_json_default))
+            fh.write("\n")
+            for event in payload.events:
+                fh.write(
+                    json.dumps(
+                        {"type": "event", "event": event},
+                        ensure_ascii=False,
+                        default=_json_default,
+                    )
+                )
+                fh.write("\n")
+
+    try:
+        _write_transcript(transcript_path)
+    except PermissionError:
+        directory = _fallback_cache_dir()
+        transcript_path = directory / filename
+        _write_transcript(transcript_path)
+
+    size_bytes = transcript_path.stat().st_size
+    manifest_entry = {
+        "run_id": payload.run_id,
+        "agent_id": payload.agent_id,
+        "agent_name": payload.agent_name,
+        "created_at": payload.created_at.isoformat(),
+        "cache_path": str(transcript_path),
+        "size_bytes": size_bytes,
+        "retained": True,
+        "source": payload.source,
+        "server_run_id": payload.server_run_id,
+    }
+
+    existing_entries = _load_manifest_entries(directory)
+    existing_entries.append(manifest_entry)
+    _write_manifest(existing_entries, directory)
+
+    return TranscriptStoreResult(
+        path=transcript_path,
+        manifest_entry=manifest_entry,
+        pruned_entries=[],
+    )
+
+
+def latest_manifest_entry(cache_dir: Path | None = None) -> dict[str, Any] | None:
+    """Return the most recent manifest entry, if any."""
+    entries = _load_manifest_entries(cache_dir)
+    if not entries:
+        return None
+    return max(
+        entries,
+        key=lambda e: _parse_iso(e.get("created_at"))
+        or datetime.min.replace(tzinfo=timezone.utc),
+    )
+
+
+def resolve_manifest_entry(
+    run_id: str,
+    cache_dir: Path | None = None,
+) -> dict[str, Any] | None:
+    """Find a manifest entry by run id."""
+    entries = _load_manifest_entries(cache_dir)
+    for entry in entries:
+        if entry.get("run_id") == run_id:
+            return entry
+    return None
+
+
+def export_transcript(
+    *,
+    destination: Path,
+    run_id: str | None = None,
+    cache_dir: Path | None = None,
+) -> Path:
+    """Copy a cached transcript to the requested destination path."""
+    directory = ensure_cache_dir(cache_dir)
+    entry = (
+        resolve_manifest_entry(run_id, directory)
+        if run_id
+        else latest_manifest_entry(directory)
+    )
+    if entry is None:
+        raise FileNotFoundError("No cached transcripts available for export.")
+
+    cache_path = entry.get("cache_path")
+    if not cache_path:
+        raise FileNotFoundError("Cached transcript path missing from manifest.")
+
+    cache_file = Path(cache_path)
+    if not cache_file.exists():
+        raise FileNotFoundError(f"Cached transcript file not found: {cache_file}")
+
+    destination.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        lines = cache_file.read_text(encoding="utf-8").splitlines()
+        records = [json.loads(line) for line in lines if line.strip()]
+    except json.JSONDecodeError as exc:
+        raise FileNotFoundError(
+            f"Cached transcript file is corrupted: {cache_file}"
+        ) from exc
+
+    with destination.open("w", encoding="utf-8") as fh:
+        for idx, record in enumerate(records):
+            json.dump(record, fh, ensure_ascii=False, indent=2)
+            fh.write("\n")
+            if idx != len(records) - 1:
+                fh.write("\n")
+
+    return destination
+
+
+def suggest_filename(entry: dict[str, Any] | None = None) -> str:
+    """Return a friendly filename suggestion for exporting a transcript."""
+    run_id = entry.get("run_id") if entry else uuid.uuid4().hex
+    created_at = (
+        entry.get("created_at") if entry else datetime.now(timezone.utc).isoformat()
+    )
+    timestamp = (
+        created_at.replace(":", "").replace("-", "").replace("T", "_").split("+")[0]
+    )
+    return f"aip-run-{timestamp}-{run_id}.jsonl"
+
+
+def build_payload(
+    *,
+    events: list[dict[str, Any]],
+    renderer_output: str,
+    final_output: str,
+    agent_id: str | None,
+    agent_name: str | None,
+    model: str | None,
+    server_run_id: str | None,
+    started_at: float | None,
+    finished_at: float | None,
+    meta: dict[str, Any],
+    source: str,
+) -> TranscriptPayload:
+    """Factory helper to prepare payload objects consistently."""
+    return TranscriptPayload(
+        events=events,
+        default_output=renderer_output,
+        final_output=final_output,
+        agent_id=agent_id,
+        agent_name=agent_name,
+        model=model,
+        server_run_id=server_run_id,
+        started_at=started_at,
+        finished_at=finished_at,
+        created_at=datetime.now(timezone.utc),
+        source=source,
+        meta=meta,
+        run_id=uuid.uuid4().hex,
+    )
+
+
+def get_transcript_cache_stats(
+    cache_dir: Path | None = None,
+) -> TranscriptCacheStats:
+    """Return basic usage information about the transcript cache."""
+    directory = ensure_cache_dir(cache_dir)
+    entries = _load_manifest_entries(directory)
+
+    total_bytes = 0
+    for entry in entries:
+        try:
+            total_bytes += int(entry.get("size_bytes") or 0)
+        except Exception:
+            continue
+
+    return TranscriptCacheStats(
+        cache_dir=directory,
+        entry_count=len(entries),
+        total_bytes=total_bytes,
+    )

glaip_sdk/cli/transcript/capture.py

@@ -0,0 +1,278 @@
+"""Helpers for capturing and caching agent run transcripts.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from glaip_sdk.cli.transcript.cache import (
+    TranscriptPayload,
+    TranscriptStoreResult,
+    store_transcript,
+)
+from glaip_sdk.cli.transcript.cache import (
+    build_payload as build_transcript_payload,
+)
+from glaip_sdk.utils.rendering.renderer.progress import format_tool_title
+
+
+@dataclass(slots=True)
+class StoredTranscriptContext:
+    """Simple container linking payload and manifest data."""
+
+    payload: TranscriptPayload
+    store_result: TranscriptStoreResult
+
+
+def coerce_events(value: Any) -> list[dict[str, Any]]:
+    """Normalise renderer events into a list of dictionaries."""
+    if not value:
+        return []
+    if isinstance(value, list):
+        return [item for item in value if isinstance(item, dict)]
+    try:
+        return [item for item in value if isinstance(item, dict)]
+    except Exception:
+        return []
+
+
+def coerce_result_text(result: Any) -> str:
+    """Serialise renderer output to a string for transcript payloads."""
+    if result is None:
+        return ""
+    if isinstance(result, str):
+        return result
+    try:
+        return json.dumps(result, ensure_ascii=False, indent=2)
+    except Exception:
+        return str(result)
+
+
+def compute_finished_at(renderer: Any) -> float | None:
+    """Best-effort end-time calculation based on renderer state."""
+    state = getattr(renderer, "state", None)
+    if state is not None:
+        started_at = getattr(state, "streaming_started_at", None)
+        duration = getattr(state, "final_duration_seconds", None)
+    else:
+        started_at = None
+        duration = None
+
+    if started_at is None:
+        stream_processor = getattr(renderer, "stream_processor", None)
+        started_at = (
+            getattr(stream_processor, "streaming_started_at", None)
+            if stream_processor is not None
+            else None
+        )
+    if started_at is None or duration is None:
+        return None
+    try:
+        return float(started_at) + float(duration)
+    except Exception:
+        return None
+
+
+def extract_server_run_id(
+    meta: dict[str, Any], events: list[dict[str, Any]]
+) -> str | None:
+    """Derive a server-side run identifier from renderer metadata."""
+    run_id = meta.get("run_id") or meta.get("id")
+    if run_id:
+        return str(run_id)
+    for event in events:
+        metadata = event.get("metadata") or {}
+        candidate = metadata.get("run_id") or metadata.get("request_id")
+        if candidate:
+            return str(candidate)
+    return None
+
+
+def _coerce_meta(meta: Any) -> dict[str, Any]:
+    """Ensure renderer metadata is recorded as a plain dictionary."""
+    if meta is None:
+        return {}
+    if isinstance(meta, dict):
+        return meta
+    if hasattr(meta, "items"):
+        try:
+            return {str(key): value for key, value in meta.items()}
+        except Exception:
+            pass
+    return {"value": coerce_result_text(meta)}
+
+
+def register_last_transcript(
+    ctx: Any, payload: TranscriptPayload, store_result: TranscriptStoreResult
+) -> None:
+    """Persist last-run transcript references onto the Click context."""
+    ctx_obj = getattr(ctx, "obj", None)
+    if not isinstance(ctx_obj, dict):
+        return
+    ctx_obj["_last_transcript_payload"] = payload
+    ctx_obj["_last_transcript_manifest"] = store_result.manifest_entry
+    ctx_obj["_last_transcript_path"] = str(store_result.path)
+
+
+def _extract_step_summaries(renderer: Any) -> list[dict[str, Any]]:
+    """Return lightweight step summaries for the transcript viewer."""
+    steps = getattr(renderer, "steps", None)
+    if steps is None:
+        return []
+
+    order = getattr(steps, "order", []) or []
+    by_id = getattr(steps, "by_id", {}) or {}
+
+    return [
+        _build_step_summary(by_id.get(step_id), index)
+        for index, step_id in enumerate(order)
+        if by_id.get(step_id) is not None
+    ]
+
+
+def _build_step_summary(step: Any, index: int) -> dict[str, Any]:
+    """Construct a single step summary entry."""
+    kind = getattr(step, "kind", "") or ""
+    name = getattr(step, "name", "") or ""
+    status = getattr(step, "status", "") or ""
+    duration_ms = _coerce_duration_ms(getattr(step, "duration_ms", None))
+    display_name = _format_step_display_name(name)
+
+    return {
+        "index": index,
+        "step_id": getattr(step, "step_id", f"step-{index}"),
+        "kind": kind,
+        "name": name,
+        "display_name": display_name,
+        "status": status,
+        "duration_ms": duration_ms,
+    }
+
+
+def _coerce_duration_ms(value: Any) -> int | None:
+    """Return duration in milliseconds if numeric, otherwise None."""
+    try:
+        if isinstance(value, (int, float)):
+            return int(value)
+    except Exception:
+        return None
+    return None
+
+
+def _format_step_display_name(name: str) -> str:
+    """Apply tool title formatting with a safe fallback."""
+    try:
+        return format_tool_title(name)
+    except Exception:
+        return name
+
+
+def _collect_renderer_outputs(
+    renderer: Any, final_result: Any
+) -> tuple[
+    list[dict[str, Any]],
+    str,
+    str,
+]:
+    """Collect events and text outputs from a renderer with safe fallbacks."""
+    events_raw = []
+    if hasattr(renderer, "get_transcript_events"):
+        try:
+            events_raw = renderer.get_transcript_events()
+        except Exception:
+            events_raw = []
+    events = coerce_events(events_raw)
+
+    aggregated_raw = ""
+    if hasattr(renderer, "get_aggregated_output"):
+        try:
+            aggregated_raw = renderer.get_aggregated_output()
+        except Exception:
+            aggregated_raw = ""
+
+    aggregated_output = coerce_result_text(aggregated_raw)
+    final_output = coerce_result_text(final_result)
+    return events, aggregated_output, final_output
+
+
+def _derive_transcript_meta(
+    renderer: Any, model: str | None
+) -> tuple[dict[str, Any], float | None, float | None, str | None]:
+    """Build transcript metadata including step summaries and timings."""
+    raw_meta = getattr(getattr(renderer, "state", None), "meta", {}) or {}
+    meta = _coerce_meta(raw_meta)
+
+    step_summaries = _extract_step_summaries(renderer)
+    if step_summaries:
+        meta["transcript_steps"] = step_summaries
+
+    stream_processor = getattr(renderer, "stream_processor", None)
+    stream_started_at = (
+        getattr(stream_processor, "streaming_started_at", None)
+        if stream_processor is not None
+        else None
+    )
+    finished_at = compute_finished_at(renderer)
+    model_name = meta.get("model") or model
+    return meta, stream_started_at, finished_at, model_name
+
+
+def store_transcript_for_session(
+    ctx: Any,
+    renderer: Any,
+    *,
+    final_result: Any,
+    agent_id: str | None,
+    agent_name: str | None,
+    model: str | None,
+    source: str,
+) -> StoredTranscriptContext | None:
+    """Capture renderer output and persist the transcript for later reuse."""
+    if not hasattr(renderer, "get_transcript_events"):
+        return None
+
+    events, aggregated_output, final_output = _collect_renderer_outputs(
+        renderer, final_result
+    )
+
+    if not (events or aggregated_output or final_output):
+        return None
+
+    meta, stream_started_at, finished_at, model_name = _derive_transcript_meta(
+        renderer, model
+    )
+
+    payload: TranscriptPayload = build_transcript_payload(
+        events=events,
+        renderer_output=aggregated_output,
+        final_output=final_output,
+        agent_id=agent_id,
+        agent_name=agent_name,
+        model=model_name,
+        server_run_id=extract_server_run_id(meta, events),
+        started_at=stream_started_at,
+        finished_at=finished_at,
+        meta=meta,
+        source=source,
+    )
+
+    store_result = store_transcript(payload)
+    register_last_transcript(ctx, payload, store_result)
+
+    return StoredTranscriptContext(payload=payload, store_result=store_result)
+
+
+__all__ = [
+    "StoredTranscriptContext",
+    "coerce_events",
+    "coerce_result_text",
+    "compute_finished_at",
+    "extract_server_run_id",
+    "register_last_transcript",
+    "store_transcript_for_session",
+]