runtime-narrative 0.1.0__py3-none-any.whl

runtime_narrative/__init__.py

@@ -0,0 +1,23 @@
+__version__ = "0.1.0"
+
+from .analyzers import LLMFailureAnalyzer, OllamaFailureAnalyzer
+from .decorators import runtime_narrative_stage, runtime_narrative_story
+from .renderer.json_renderer import JsonRenderer
+from .stage import stage
+from .story import story
+
+try:
+    from .middleware import RuntimeNarrativeMiddleware
+except ImportError:
+    pass
+
+__all__ = [
+    "story",
+    "stage",
+    "runtime_narrative_story",
+    "runtime_narrative_stage",
+    "LLMFailureAnalyzer",
+    "OllamaFailureAnalyzer",
+    "RuntimeNarrativeMiddleware",
+    "JsonRenderer",
+]

runtime_narrative/analyzers/__init__.py

@@ -0,0 +1,3 @@
+from .ollama import LLMFailureAnalyzer, OllamaFailureAnalyzer
+
+__all__ = ["LLMFailureAnalyzer", "OllamaFailureAnalyzer"]

runtime_narrative/analyzers/ollama.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Optional
+from urllib.error import URLError
+from urllib.request import Request, urlopen
+
+from ..failure import FailureSummary
+
+
+def _build_prompt(
+    *,
+    story_name: str,
+    stage_name: str,
+    failure: FailureSummary,
+    stage_timeline: str,
+    progress_percent: int,
+    include_traceback_lines: int,
+) -> str:
+    traceback_lines = failure.traceback_text.strip().splitlines()
+    traceback_excerpt = "\n".join(traceback_lines[-include_traceback_lines:])
+    return (
+        "You are debugging a Python runtime stage failure.\n"
+        "Return concise markdown with exactly four sections:\n"
+        "1) Exact Why\n"
+        "2) Evidence\n"
+        "3) Targeted Fix\n\n"
+        "4) Code Changes\n\n"
+        "Constraints:\n"
+        "- Do not be generic.\n"
+        "- Point to the exact failing statement and mechanism.\n"
+        "- Mention assumptions only if uncertain.\n\n"
+        "Code Changes format:\n"
+        "- Provide minimal edit-ready snippets.\n"
+        "- Include file path, old line, and new line when possible.\n"
+        "- Prefer small targeted diffs over full-file rewrites.\n\n"
+        f"Story: {story_name}\n"
+        f"Stage: {stage_name}\n"
+        f"Error Type: {failure.error_type}\n"
+        f"Error Message: {failure.error_message}\n"
+        f"Location: {failure.filename}:{failure.lineno} ({failure.function})\n"
+        f"Failing Code: {failure.source_line}\n"
+        f"Exception Chain: {failure.exception_chain}\n"
+        f"Progress: {progress_percent}%\n"
+        f"Recent Stages: {stage_timeline}\n\n"
+        "Traceback Excerpt:\n"
+        f"{traceback_excerpt}\n"
+    )
+
+
+@dataclass
+class LLMFailureAnalyzer:
+    """
+    Failure analyzer for OpenAI-compatible endpoints.
+
+    Works with any backend that serves the /v1/chat/completions API,
+    including vLLM, llama.cpp (--server), LM Studio, Ollama (OpenAI mode), etc.
+
+    Example::
+
+        LLMFailureAnalyzer(
+            model="llama3",
+            endpoint="http://localhost:8000/v1/chat/completions",
+        )
+    """
+
+    model: str
+    endpoint: str
+    timeout_seconds: float = 12.0
+    include_traceback_lines: int = 30
+
+    def analyze_failure(
+        self,
+        *,
+        story_name: str,
+        stage_name: str,
+        failure: FailureSummary,
+        stage_timeline: str,
+        progress_percent: int,
+    ) -> Optional[str]:
+        prompt = _build_prompt(
+            story_name=story_name,
+            stage_name=stage_name,
+            failure=failure,
+            stage_timeline=stage_timeline,
+            progress_percent=progress_percent,
+            include_traceback_lines=self.include_traceback_lines,
+        )
+        payload = {
+            "model": self.model,
+            "messages": [{"role": "user", "content": prompt}],
+            "temperature": 0,
+            "stream": False,
+        }
+        request = Request(
+            self.endpoint,
+            data=json.dumps(payload).encode("utf-8"),
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with urlopen(request, timeout=self.timeout_seconds) as response:
+                body = response.read().decode("utf-8")
+        except (URLError, TimeoutError, Exception):
+            return None
+
+        try:
+            parsed = json.loads(body)
+            text = parsed["choices"][0]["message"]["content"].strip()
+        except Exception:
+            return None
+
+        return text or None
+
+
+@dataclass
+class OllamaFailureAnalyzer:
+    """
+    Failure analyzer using Ollama's native /api/generate endpoint.
+
+    For OpenAI-compatible mode (Ollama >= 0.1.24), prefer LLMFailureAnalyzer
+    with endpoint="http://localhost:11434/v1/chat/completions".
+
+    Example::
+
+        OllamaFailureAnalyzer(
+            model="llama3",
+            endpoint="http://localhost:11434/api/generate",
+        )
+    """
+
+    model: str
+    endpoint: str = "http://127.0.0.1:11434/api/generate"
+    timeout_seconds: float = 12.0
+    include_traceback_lines: int = 30
+
+    def analyze_failure(
+        self,
+        *,
+        story_name: str,
+        stage_name: str,
+        failure: FailureSummary,
+        stage_timeline: str,
+        progress_percent: int,
+    ) -> Optional[str]:
+        prompt = _build_prompt(
+            story_name=story_name,
+            stage_name=stage_name,
+            failure=failure,
+            stage_timeline=stage_timeline,
+            progress_percent=progress_percent,
+            include_traceback_lines=self.include_traceback_lines,
+        )
+        payload = {
+            "model": self.model,
+            "prompt": prompt,
+            "stream": False,
+            "options": {"temperature": 0},
+        }
+        request = Request(
+            self.endpoint,
+            data=json.dumps(payload).encode("utf-8"),
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with urlopen(request, timeout=self.timeout_seconds) as response:
+                body = response.read().decode("utf-8")
+        except (URLError, TimeoutError, Exception):
+            return None
+
+        try:
+            parsed = json.loads(body)
+            text = parsed.get("response", "").strip()
+        except Exception:
+            return None
+
+        return text or None

runtime_narrative/context.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .stage import StageRecord
+    from .story import StoryRuntime
+
+current_story: ContextVar[StoryRuntime | None] = ContextVar("current_story", default=None)
+current_stage_stack: ContextVar[list[StageRecord]] = ContextVar("current_stage_stack", default=[])

runtime_narrative/decorators.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import inspect
+from functools import wraps
+from typing import Any, Callable, Sequence, TypeVar
+
+from .stage import stage
+from .story import story
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def _default_name(func: Callable[..., Any]) -> str:
+    return func.__name__.replace("_", " ").strip().title()
+
+
+def runtime_narrative_story(
+    name: str | None = None,
+    *,
+    renderers: Sequence[object] | None = None,
+    failure_analyzer: Any | None = None,
+) -> Callable[[F], F]:
+    """Decorator to wrap a function in a story context (sync or async)."""
+
+    def decorator(func: F) -> F:
+        story_name = name or _default_name(func)
+
+        if inspect.iscoroutinefunction(func):
+
+            @wraps(func)
+            async def async_wrapper(*args: Any, **kwargs: Any):
+                with story(story_name, renderers=renderers, failure_analyzer=failure_analyzer):
+                    return await func(*args, **kwargs)
+
+            return async_wrapper  # type: ignore[return-value]
+
+        @wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any):
+            with story(story_name, renderers=renderers, failure_analyzer=failure_analyzer):
+                return func(*args, **kwargs)
+
+        return sync_wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+def runtime_narrative_stage(name: str | None = None) -> Callable[[F], F]:
+    """Decorator to wrap a function in a stage context (sync or async)."""
+
+    def decorator(func: F) -> F:
+        stage_name = name or _default_name(func)
+
+        if inspect.iscoroutinefunction(func):
+
+            @wraps(func)
+            async def async_wrapper(*args: Any, **kwargs: Any):
+                with stage(stage_name):
+                    return await func(*args, **kwargs)
+
+            return async_wrapper  # type: ignore[return-value]
+
+        @wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any):
+            with stage(stage_name):
+                return func(*args, **kwargs)
+
+        return sync_wrapper  # type: ignore[return-value]
+
+    return decorator

runtime_narrative/events.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+
+@dataclass
+class StoryStarted:
+    story_id: str
+    story_name: str
+    timestamp: datetime
+
+
+@dataclass
+class StageStarted:
+    story_id: str
+    stage_name: str
+    timestamp: datetime
+
+
+@dataclass
+class StageCompleted:
+    story_id: str
+    stage_name: str
+    timestamp: datetime
+    duration_seconds: float
+
+
+@dataclass
+class FailureOccurred:
+    story_id: str
+    story_name: str
+    stage_name: str
+    error_type: str
+    error_message: str
+    filename: str
+    lineno: int
+    function: str
+    source_line: str
+    exception_chain: str
+    exact_cause: str
+    llm_analysis: str | None
+    stage_timeline: str
+    progress_percent: int
+    completed_stages: int
+    total_stages: int
+    timestamp: datetime
+    traceback_text: str
+
+
+@dataclass
+class StoryCompleted:
+    story_id: str
+    story_name: str
+    success: bool
+    progress_percent: int
+    completed_stages: int
+    total_stages: int
+    timestamp: datetime
+
+
+from typing import Union
+
+Event = Union[StoryStarted, StageStarted, StageCompleted, FailureOccurred, StoryCompleted]
+Renderer = Any

runtime_narrative/failure.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import traceback
+from dataclasses import dataclass
+from types import TracebackType
+
+
+@dataclass
+class FailureSummary:
+    error_type: str
+    error_message: str
+    filename: str
+    lineno: int
+    function: str
+    source_line: str
+    exception_chain: str
+    exact_cause: str
+    traceback_text: str
+
+
+def _build_exception_chain(exc: BaseException) -> str:
+    parts: list[str] = []
+    current: BaseException | None = exc
+    depth = 0
+    while current is not None and depth < 5:
+        parts.append(f"{type(current).__name__}: {current}")
+        current = current.__cause__ or current.__context__
+        depth += 1
+    return " <- ".join(parts)
+
+
+def _infer_exact_cause(error_type: str, message: str, source_line: str) -> str:
+    line = source_line.strip()
+    if line.startswith("raise "):
+        return f"The code explicitly raises {error_type} here with message: {message}"
+    return f"The statement `{line}` raised {error_type}: {message}"
+
+
+def summarize_exception(exc_type: type[BaseException], exc: BaseException, tb: TracebackType | None) -> FailureSummary:
+    extracted = traceback.extract_tb(tb) if tb else []
+    if extracted:
+        frame = extracted[-1]
+        filename = frame.filename
+        lineno = frame.lineno
+        function = frame.name
+        source_line = frame.line or "<source unavailable>"
+    else:
+        filename = "<unknown>"
+        lineno = 0
+        function = "<unknown>"
+        source_line = "<source unavailable>"
+
+    return FailureSummary(
+        error_type=exc_type.__name__,
+        error_message=str(exc),
+        filename=filename,
+        lineno=lineno,
+        function=function,
+        source_line=source_line,
+        exception_chain=_build_exception_chain(exc),
+        exact_cause=_infer_exact_cause(exc_type.__name__, str(exc), source_line),
+        traceback_text="".join(traceback.format_exception(exc_type, exc, tb)),
+    )

runtime_narrative/middleware.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+from .story import story
+
+
+class RuntimeNarrativeMiddleware(BaseHTTPMiddleware):
+    """
+    FastAPI/Starlette middleware that wraps every HTTP request in a runtime_narrative story.
+
+    Each request gets a story named "<METHOD> <path>" (e.g. "POST /customers").
+    The story context is available to all stages declared inside route handlers.
+
+    Usage::
+
+        from runtime_narrative.middleware import RuntimeNarrativeMiddleware
+        from runtime_narrative.renderer.json_renderer import JsonRenderer
+
+        app.add_middleware(
+            RuntimeNarrativeMiddleware,
+            renderers=[JsonRenderer()],   # optional, defaults to ConsoleRenderer
+            failure_analyzer=None,        # optional OllamaFailureAnalyzer
+        )
+
+    Once added, individual route handlers no longer need to create their own
+    ``story()`` context — they can use ``stage()`` directly::
+
+        @app.post("/orders")
+        async def create_order(payload: OrderIn):
+            with stage("Validate Input"):
+                ...
+            with stage("Persist Order"):
+                ...
+    """
+
+    def __init__(
+        self,
+        app,
+        renderers: Sequence[object] | None = None,
+        failure_analyzer: Any | None = None,
+    ):
+        super().__init__(app)
+        self._renderers = renderers
+        self._failure_analyzer = failure_analyzer
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        story_name = f"{request.method} {request.url.path}"
+        with story(story_name, renderers=self._renderers, failure_analyzer=self._failure_analyzer):
+            response = await call_next(request)
+        return response
+
+
+__all__ = ["RuntimeNarrativeMiddleware"]

runtime_narrative/renderer/__init__.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class RenderProtocol(Protocol):
+    def handle(self, event: object) -> None:
+        ...
+
+
+__all__ = ["RenderProtocol"]

runtime_narrative/renderer/console.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+import re
+import shutil
+import textwrap
+
+try:
+    import typer
+except ImportError:  # pragma: no cover
+    typer = None
+
+from . import RenderProtocol
+
+
+class ConsoleRenderer:
+    @property
+    def _success_color(self):
+        if typer:
+            return typer.colors.GREEN
+        return None
+
+    @property
+    def _success_value_color(self):
+        if typer:
+            return getattr(typer.colors, "BRIGHT_WHITE", typer.colors.WHITE)
+        return None
+
+    @property
+    def _failure_color(self):
+        if typer:
+            return getattr(typer.colors, "BRIGHT_RED", typer.colors.RED)
+        return None
+
+    @property
+    def _failure_value_color(self):
+        if typer:
+            return getattr(typer.colors, "BRIGHT_YELLOW", typer.colors.YELLOW)
+        return None
+
+    @property
+    def _failure_heading_color(self):
+        if typer:
+            return getattr(typer.colors, "BRIGHT_WHITE", typer.colors.WHITE)
+        return None
+
+    @property
+    def _fix_heading_color(self):
+        if typer:
+            return getattr(typer.colors, "BRIGHT_GREEN", typer.colors.GREEN)
+        return None
+
+    @staticmethod
+    def _secho(text: str, *, fg=None, bold: bool = False, nl: bool = True) -> None:
+        if typer is None:
+            if nl:
+                print(text)
+            else:
+                print(text, end="")
+            return
+        typer.secho(text, fg=fg, bold=bold, nl=nl)
+
+    def _label(self, label: str, value: str, *, label_fg=None, value_fg=None) -> None:
+        self._secho(f"{label} ", fg=label_fg, bold=True, nl=False)
+        self._secho(value, fg=value_fg)
+
+    @staticmethod
+    def _strip_markdown(text: str) -> str:
+        fence_languages = {"python", "bash", "json", "yaml", "yml", "text"}
+        cleaned_lines: list[str] = []
+        for raw_line in text.splitlines():
+            line = raw_line.strip()
+            line = re.sub(r"^#{1,6}\s*", "", line)
+            line = re.sub(r"^\s*[-*+]\s+", "", line)
+            line = re.sub(r"^\s*\d+[.)]\s+", "", line)
+            line = line.replace("**", "").replace("__", "").replace("`", "")
+            if line.lower() in fence_languages:
+                continue
+            if line:
+                cleaned_lines.append(line)
+        return "\n".join(cleaned_lines)
+
+    @staticmethod
+    def _is_heading_line(line: str) -> bool:
+        normalized = line.strip().rstrip(":")
+        if not normalized:
+            return False
+        known = {"exact why", "evidence", "targeted fix", "targetted fix", "code changes"}
+        if normalized.lower() in known:
+            return True
+        if len(normalized.split()) <= 4 and re.match(r"^[A-Za-z][A-Za-z\s/-]*$", normalized):
+            return True
+        return False
+
+    @staticmethod
+    def _is_fix_heading_line(line: str) -> bool:
+        normalized = line.strip().rstrip(":").lower()
+        return normalized in {"targeted fix", "targetted fix", "code changes"}
+
+    def _render_box(self, title: str, text: str, *, border_fg=None, text_fg=None, heading_fg=None) -> None:
+        terminal_width = shutil.get_terminal_size((100, 20)).columns
+        width = max(60, min(110, terminal_width - 2))
+        inner = width - 2
+        content_width = max(10, inner - 2)
+
+        title_chunk = f" {title} "
+        if len(title_chunk) < inner:
+            top = "+" + title_chunk + ("-" * (inner - len(title_chunk))) + "+"
+        else:
+            top = "+" + ("-" * inner) + "+"
+        bottom = "+" + ("-" * inner) + "+"
+
+        self._secho(top, fg=border_fg, bold=True)
+        plain_text = self._strip_markdown(text)
+        lines = plain_text.splitlines()
+        first_section = True
+        for paragraph in lines:
+            is_heading = self._is_heading_line(paragraph)
+            if is_heading and not first_section:
+                self._secho("|", fg=border_fg, bold=True, nl=False)
+                self._secho(f" {' '.ljust(content_width)} ", fg=text_fg, nl=False)
+                self._secho("|", fg=border_fg, bold=True)
+            if is_heading:
+                first_section = False
+            is_fix_heading = self._is_fix_heading_line(paragraph)
+            line_fg = heading_fg if is_heading else text_fg
+            if is_fix_heading:
+                line_fg = self._fix_heading_color or heading_fg
+            line_bold = is_heading
+            wrapped = textwrap.wrap(paragraph, width=content_width) or [""]
+            for line in wrapped:
+                self._secho("|", fg=border_fg, bold=True, nl=False)
+                display_line = f">> {line}" if is_fix_heading else line
+                self._secho(f" {display_line.ljust(content_width)} ", fg=line_fg, bold=line_bold, nl=False)
+                self._secho("|", fg=border_fg, bold=True)
+        self._secho(bottom, fg=border_fg, bold=True)
+
+    def handle(self, event: object) -> None:
+        event_name = event.__class__.__name__
+
+        if event_name == "StoryStarted":
+            self._secho("▶ Stage started: ", fg=self._success_color, bold=True, nl=False)
+            self._secho(event.story_name, fg=self._success_value_color, bold=True)
+            return
+
+        if event_name == "StageStarted":
+            self._secho("▶ Stage started: ", fg=self._success_color, bold=True, nl=False)
+            self._secho(event.stage_name, fg=self._success_value_color)
+            return
+
+        if event_name == "StageCompleted":
+            self._secho("✔ Stage completed: ", fg=self._success_color, bold=True, nl=False)
+            self._secho(
+                f"{event.stage_name} ({event.duration_seconds:.3f}s)",
+                fg=self._success_value_color,
+            )
+            return
+
+        if event_name == "FailureOccurred":
+            self._secho("\n❌ Failure detected", fg=self._failure_color, bold=True)
+            self._label("Story:", event.story_name, label_fg=self._failure_color, value_fg=self._failure_value_color)
+            self._label("Stage:", event.stage_name, label_fg=self._failure_color, value_fg=self._failure_value_color)
+            self._label(
+                "Error:",
+                f"{event.error_type} - {event.error_message}",
+                label_fg=self._failure_color,
+                value_fg=self._failure_value_color,
+            )
+            self._label(
+                "Location:",
+                f"{event.filename}:{event.lineno} ({event.function})",
+                label_fg=self._failure_color,
+                value_fg=self._failure_value_color,
+            )
+            self._label("Code:", event.source_line, label_fg=self._failure_color, value_fg=self._failure_value_color)
+            if not event.llm_analysis:
+                self._label(
+                    "What happened:",
+                    event.exception_chain,
+                    label_fg=self._failure_color,
+                    value_fg=self._failure_value_color,
+                )
+                self._label(
+                    "Why (exact):",
+                    event.exact_cause,
+                    label_fg=self._failure_color,
+                    value_fg=self._failure_value_color,
+                )
+            if event.llm_analysis:
+                self._secho("")
+                self._render_box(
+                    "LLM Debug",
+                    event.llm_analysis,
+                    border_fg=self._failure_color,
+                    text_fg=self._failure_value_color,
+                    heading_fg=self._failure_heading_color,
+                )
+            self._label(
+                "Recent stages:",
+                event.stage_timeline,
+                label_fg=self._failure_color,
+                value_fg=self._failure_value_color,
+            )
+            self._label(
+                "Progress:",
+                f"{event.progress_percent}% ({event.completed_stages} / {event.total_stages})",
+                label_fg=self._failure_color,
+                value_fg=self._failure_value_color,
+            )
+            return
+
+        if event_name == "StoryCompleted":
+            state = "SUCCESS" if event.success else "FAILED"
+            color = self._success_color if event.success else self._failure_color
+            value_color = self._success_value_color if event.success else self._failure_value_color
+            self._secho("▶ Story ended: ", fg=color, bold=True, nl=False)
+            self._secho(state, fg=value_color, bold=True)
+
+
+__all__ = ["ConsoleRenderer"]

runtime_narrative/renderer/json_renderer.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime
+from typing import IO
+
+
+class JsonRenderer:
+    """Renderer that emits one JSON object per event to a file-like output (default: stdout)."""
+
+    def __init__(self, output: IO[str] | None = None, indent: int | None = None):
+        self._output = output or sys.stdout
+        self._indent = indent
+
+    def _dump(self, data: dict) -> None:
+        self._output.write(json.dumps(data, default=str, indent=self._indent) + "\n")
+        if hasattr(self._output, "flush"):
+            self._output.flush()
+
+    def handle(self, event: object) -> None:
+        event_name = event.__class__.__name__
+
+        if event_name == "StoryStarted":
+            self._dump({
+                "event": "StoryStarted",
+                "story_id": event.story_id,
+                "story_name": event.story_name,
+                "timestamp": event.timestamp.isoformat(),
+            })
+
+        elif event_name == "StageStarted":
+            self._dump({
+                "event": "StageStarted",
+                "story_id": event.story_id,
+                "stage_name": event.stage_name,
+                "timestamp": event.timestamp.isoformat(),
+            })
+
+        elif event_name == "StageCompleted":
+            self._dump({
+                "event": "StageCompleted",
+                "story_id": event.story_id,
+                "stage_name": event.stage_name,
+                "duration_seconds": event.duration_seconds,
+                "timestamp": event.timestamp.isoformat(),
+            })
+
+        elif event_name == "FailureOccurred":
+            self._dump({
+                "event": "FailureOccurred",
+                "story_id": event.story_id,
+                "story_name": event.story_name,
+                "stage_name": event.stage_name,
+                "error_type": event.error_type,
+                "error_message": event.error_message,
+                "location": {
+                    "filename": event.filename,
+                    "lineno": event.lineno,
+                    "function": event.function,
+                    "source_line": event.source_line,
+                },
+                "exception_chain": event.exception_chain,
+                "exact_cause": event.exact_cause,
+                "llm_analysis": event.llm_analysis,
+                "stage_timeline": event.stage_timeline,
+                "progress": {
+                    "percent": event.progress_percent,
+                    "completed_stages": event.completed_stages,
+                    "total_stages": event.total_stages,
+                },
+                "timestamp": event.timestamp.isoformat(),
+            })
+
+        elif event_name == "StoryCompleted":
+            self._dump({
+                "event": "StoryCompleted",
+                "story_id": event.story_id,
+                "story_name": event.story_name,
+                "success": event.success,
+                "progress": {
+                    "percent": event.progress_percent,
+                    "completed_stages": event.completed_stages,
+                    "total_stages": event.total_stages,
+                },
+                "timestamp": event.timestamp.isoformat(),
+            })
+
+
+__all__ = ["JsonRenderer"]

runtime_narrative/stage.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from .context import current_stage_stack, current_story
+
+
+@dataclass
+class StageRecord:
+    name: str
+    started_at: datetime = field(default_factory=datetime.now)
+    ended_at: datetime | None = None
+    duration_seconds: float | None = None
+    completed: bool = False
+    failed: bool = False
+
+
+class stage:
+    def __init__(self, name: str):
+        self.name = name
+        self.record = StageRecord(name=name)
+
+    def __enter__(self) -> StageRecord:
+        story_runtime = current_story.get()
+        if story_runtime is None:
+            raise RuntimeError("stage() must run inside an active story() context")
+
+        story_runtime.register_stage(self.record)
+        stack = list(current_stage_stack.get())
+        stack.append(self.record)
+        current_stage_stack.set(stack)
+        story_runtime.on_stage_started(self.record)
+        return self.record
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        ended_at = datetime.now()
+        self.record.ended_at = ended_at
+        self.record.duration_seconds = (ended_at - self.record.started_at).total_seconds()
+
+        story_runtime = current_story.get()
+        if story_runtime is not None and exc_type is not None:
+            story_runtime.failed_stage_name = self.record.name
+
+        stack = list(current_stage_stack.get())
+        if stack:
+            stack.pop()
+        current_stage_stack.set(stack)
+
+        if story_runtime is None:
+            return False
+
+        if exc_type is None:
+            self.record.completed = True
+            story_runtime.on_stage_completed(self.record)
+        else:
+            self.record.failed = True
+        return False

runtime_narrative/story.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Sequence
+from uuid import uuid4
+
+from .context import current_stage_stack, current_story
+from .events import FailureOccurred, StoryCompleted, StoryStarted, StageCompleted, StageStarted
+from .failure import summarize_exception
+from .stage import StageRecord
+
+
+@dataclass
+class StoryRuntime:
+    name: str
+    story_id: str = field(default_factory=lambda: str(uuid4()))
+    started_at: datetime = field(default_factory=datetime.now)
+    stages: list[StageRecord] = field(default_factory=list)
+    renderers: Sequence[object] = field(default_factory=tuple)
+    failed_stage_name: str | None = None
+
+    def emit(self, event: object) -> None:
+        for renderer in self.renderers:
+            renderer.handle(event)
+
+    def register_stage(self, stage: StageRecord) -> None:
+        self.stages.append(stage)
+
+    def on_stage_started(self, stage: StageRecord) -> None:
+        self.emit(StageStarted(story_id=self.story_id, stage_name=stage.name, timestamp=datetime.now()))
+
+    def on_stage_completed(self, stage: StageRecord) -> None:
+        completed_at = datetime.now()
+        duration_seconds = stage.duration_seconds
+        if duration_seconds is None:
+            duration_seconds = (completed_at - stage.started_at).total_seconds()
+        self.emit(
+            StageCompleted(
+                story_id=self.story_id,
+                stage_name=stage.name,
+                timestamp=completed_at,
+                duration_seconds=duration_seconds,
+            )
+        )
+
+    def build_stage_timeline(self) -> str:
+        if not self.stages:
+            return "<no stages>"
+
+        rendered: list[str] = []
+        for stage in self.stages[-5:]:
+            if stage.completed:
+                duration = f"{stage.duration_seconds:.3f}s" if stage.duration_seconds is not None else "n/a"
+                rendered.append(f"{stage.name}=completed ({duration})")
+            elif stage.failed:
+                duration = f"{stage.duration_seconds:.3f}s" if stage.duration_seconds is not None else "n/a"
+                rendered.append(f"{stage.name}=failed ({duration})")
+            else:
+                rendered.append(f"{stage.name}=in-progress")
+        return " | ".join(rendered)
+
+    @property
+    def completed_stages(self) -> int:
+        return sum(1 for s in self.stages if s.completed)
+
+    @property
+    def total_stages(self) -> int:
+        return len(self.stages)
+
+    @property
+    def progress_percent(self) -> int:
+        if not self.total_stages:
+            return 0
+        return int((self.completed_stages / self.total_stages) * 100)
+
+
+class story:
+    def __init__(
+        self,
+        name: str,
+        *,
+        renderers: Sequence[object] | None = None,
+        failure_analyzer: Any | None = None,
+    ):
+        from .renderer.console import ConsoleRenderer
+
+        self.runtime = StoryRuntime(name=name, renderers=renderers or (ConsoleRenderer(),))
+        self.failure_analyzer = failure_analyzer
+        self._story_token = None
+        self._stack_token = None
+
+    def __enter__(self) -> StoryRuntime:
+        self._story_token = current_story.set(self.runtime)
+        self._stack_token = current_stage_stack.set([])
+        self.runtime.emit(
+            StoryStarted(
+                story_id=self.runtime.story_id,
+                story_name=self.runtime.name,
+                timestamp=datetime.now(),
+            )
+        )
+        return self.runtime
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        if exc_type is not None and exc is not None:
+            failure = summarize_exception(exc_type, exc, tb)
+            failed_stage_name = self.runtime.failed_stage_name or (
+                current_stage_stack.get()[-1].name if current_stage_stack.get() else "<unknown>"
+            )
+            stage_timeline = self.runtime.build_stage_timeline()
+            llm_analysis = None
+            if self.failure_analyzer is not None:
+                analyze_fn = getattr(self.failure_analyzer, "analyze_failure", None)
+                if callable(analyze_fn):
+                    llm_analysis = analyze_fn(
+                        story_name=self.runtime.name,
+                        stage_name=failed_stage_name,
+                        failure=failure,
+                        stage_timeline=stage_timeline,
+                        progress_percent=self.runtime.progress_percent,
+                    )
+            self.runtime.emit(
+                FailureOccurred(
+                    story_id=self.runtime.story_id,
+                    story_name=self.runtime.name,
+                    stage_name=failed_stage_name,
+                    error_type=failure.error_type,
+                    error_message=failure.error_message,
+                    filename=failure.filename,
+                    lineno=failure.lineno,
+                    function=failure.function,
+                    source_line=failure.source_line,
+                    exception_chain=failure.exception_chain,
+                    exact_cause=failure.exact_cause,
+                    llm_analysis=llm_analysis,
+                    stage_timeline=stage_timeline,
+                    progress_percent=self.runtime.progress_percent,
+                    completed_stages=self.runtime.completed_stages,
+                    total_stages=self.runtime.total_stages,
+                    timestamp=datetime.now(),
+                    traceback_text=failure.traceback_text,
+                )
+            )
+
+        self.runtime.emit(
+            StoryCompleted(
+                story_id=self.runtime.story_id,
+                story_name=self.runtime.name,
+                success=exc_type is None,
+                progress_percent=self.runtime.progress_percent,
+                completed_stages=self.runtime.completed_stages,
+                total_stages=self.runtime.total_stages,
+                timestamp=datetime.now(),
+            )
+        )
+
+        if self._stack_token is not None:
+            current_stage_stack.reset(self._stack_token)
+        if self._story_token is not None:
+            current_story.reset(self._story_token)
+        return False

runtime_narrative-0.1.0.dist-info/METADATA

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: runtime-narrative
+Version: 0.1.0
+Summary: runtime-narrative — model execution as human-readable stories
+Author-email: Shashank Raj <shashank.raj28@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sraj0501/runtime_narrative
+Project-URL: Repository, https://github.com/sraj0501/runtime_narrative
+Project-URL: Bug Tracker, https://github.com/sraj0501/runtime_narrative/issues
+Keywords: logging,observability,tracing,fastapi,debugging,runtime_narrative
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: console
+Requires-Dist: typer>=0.9.0; extra == "console"
+Provides-Extra: fastapi
+Requires-Dist: starlette>=0.27.0; extra == "fastapi"
+Provides-Extra: all
+Requires-Dist: typer>=0.9.0; extra == "all"
+Requires-Dist: starlette>=0.27.0; extra == "all"
+Dynamic: license-file
+
+# runtime_narrative
+
+Model your application's execution as **human-readable stories** instead of scattered log lines.
+
+When something fails, instead of a raw traceback you get:
+
+```
+❌ Failure detected
+Story:    Create Customer
+Stage:    Validate Input
+Error:    ValueError - invalid email
+Location: handlers.py:24 (validate_customer)
+Code:     if "@" not in payload.email:
+Progress: 33% (1 / 3 stages completed)
+Recent stages: Validate Input=failed (0.001s)
+```
+
+## Installation
+
+```bash
+# Core only (zero dependencies)
+pip install runtime-narrative
+
+# With colored console output
+pip install "runtime-narrative[console]"
+
+# With FastAPI middleware
+pip install "runtime-narrative[fastapi]"
+
+# Everything
+pip install "runtime-narrative[all]"
+```
+
+## Quick start
+
+```python
+from runtime_narrative import story, stage
+
+with story("Import Customers"):
+    with stage("Load CSV"):
+        load_file()
+
+    with stage("Validate Data"):
+        validate()
+
+    with stage("Insert Records"):
+        insert()
+```
+
+## FastAPI — middleware (recommended)
+
+Add middleware once and every request gets a story automatically.
+Route handlers only need to declare stages:
+
+```python
+from runtime_narrative import RuntimeNarrativeMiddleware, stage
+
+app.add_middleware(RuntimeNarrativeMiddleware)
+
+@app.post("/customers")
+async def create_customer(payload: CustomerIn):
+    with stage("Validate Input"):
+        ...
+    with stage("Insert Into Database"):
+        ...
+    with stage("Build Response"):
+        return {"ok": True}
+```
+
+## FastAPI — decorator style
+
+```python
+from runtime_narrative import runtime_narrative_story, runtime_narrative_stage
+
+@app.post("/customers")
+@runtime_narrative_story("Create Customer")
+async def create_customer(payload: CustomerIn):
+    return await _save(payload)
+
+@runtime_narrative_stage("Save to Database")
+async def _save(payload):
+    ...
+```
+
+## Structured JSON output
+
+Pipe one JSON object per lifecycle event to stdout, a file, or any stream:
+
+```python
+from runtime_narrative import RuntimeNarrativeMiddleware, JsonRenderer
+
+app.add_middleware(RuntimeNarrativeMiddleware, renderers=[JsonRenderer()])
+```
+
+Output (one line per event):
+```json
+{"event": "StoryStarted", "story_id": "...", "story_name": "POST /customers", "timestamp": "..."}
+{"event": "StageStarted", "story_id": "...", "stage_name": "Validate Input", "timestamp": "..."}
+{"event": "StageCompleted", "story_id": "...", "stage_name": "Validate Input", "duration_seconds": 0.001, "timestamp": "..."}
+{"event": "StoryCompleted", "story_id": "...", "success": true, "progress": {"percent": 100, ...}, "timestamp": "..."}
+```
+
+Write to a file instead of stdout:
+
+```python
+JsonRenderer(output=open("runtime_narrative.log", "a"))
+```
+
+## LLM failure analysis
+
+Plug in any LLM backend — model name and endpoint are always required (no defaults).
+
+**OpenAI-compatible backends** (vLLM, llama.cpp `--server`, LM Studio, Ollama OpenAI mode):
+
+```python
+from runtime_narrative import LLMFailureAnalyzer, story
+
+analyzer = LLMFailureAnalyzer(
+    model="llama3",
+    endpoint="http://localhost:8000/v1/chat/completions",
+)
+
+with story("Process Orders", failure_analyzer=analyzer):
+    ...
+```
+
+**Ollama native API:**
+
+```python
+from runtime_narrative import OllamaFailureAnalyzer, story
+
+analyzer = OllamaFailureAnalyzer(
+    model="llama3",
+    endpoint="http://localhost:11434/api/generate",
+)
+
+with story("Process Orders", failure_analyzer=analyzer):
+    ...
+```
+
+Falls back silently if the endpoint is unavailable.
+
+## Custom renderer
+
+Implement a single `handle` method to receive all lifecycle events:
+
+```python
+class MyRenderer:
+    def handle(self, event):
+        print(event.__class__.__name__, event.__dict__)
+
+with story("My Story", renderers=[MyRenderer()]):
+    ...
+```
+
+Events: `StoryStarted`, `StageStarted`, `StageCompleted`, `FailureOccurred`, `StoryCompleted`.
+
+## License
+
+MIT

runtime_narrative-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+runtime_narrative/__init__.py,sha256=XKhfk-UfLwrzAEWE0g66XVoo1vcrcnOAefsvoNyK21k,562
+runtime_narrative/context.py,sha256=9Zxfm0_hQHntO4Fkv1uyHVHLdxsQMrF7Yxt8wV6UXWk,385
+runtime_narrative/decorators.py,sha256=2-n_vt7g8fFlIcWW-tgBEHW4vUSZUUtcmrrHl82hj5U,2087
+runtime_narrative/events.py,sha256=TAzvtBI1h88EZoXjP3tZ6OZvqplYHZjBlVj4A7mBUsw,1192
+runtime_narrative/failure.py,sha256=0s2jCdBgvuIjVd3_ucpcjSblL5S0N2d0Y_M3WG0ZSOQ,1935
+runtime_narrative/middleware.py,sha256=SWlH66TR0vOKn6tUveJDhPWd6QVSv0p_IDbR00dVR3k,1917
+runtime_narrative/stage.py,sha256=w3c6h5zLDHxyDwVWodMJcO-yP4qFl8g4_o_HOpMyWlk,1759
+runtime_narrative/story.py,sha256=B7v-J2RrvNCZv3qPfL7RNNxKDJG9Hy2nk4RaTV5F9DY,6221
+runtime_narrative/analyzers/__init__.py,sha256=Nf7O3tHKbd1CUcSQ-mla6EGdY_rl3yDhZ8PIa4WW4Eg,121
+runtime_narrative/analyzers/ollama.py,sha256=YCHJKoqJ4x6ChX5bnb1yygcI77VraxWDbM81SVMQimw,5417
+runtime_narrative/renderer/__init__.py,sha256=EP3bq4H44d6RYsX0tkQA69pwJEhYILwx5KB7ndLOQ4U,186
+runtime_narrative/renderer/console.py,sha256=rBy5WqvDhfoSyHo7EFM4OirpmnukpVu9LCtMFiS0Tbs,8446
+runtime_narrative/renderer/json_renderer.py,sha256=9IlhbjrQpHXME-H1PvjOXV_GygNDZsqRg8PaBj6JFF4,3258
+runtime_narrative-0.1.0.dist-info/licenses/LICENSE,sha256=AnFni0sUptWdCh6Pfj-Llrls83LIp0ySaATuR8fq3Vg,1069
+runtime_narrative-0.1.0.dist-info/METADATA,sha256=vZHhthWuS4eD4tA_In-HqtZWFRNWEd26KLf6VmK3-eQ,5383
+runtime_narrative-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+runtime_narrative-0.1.0.dist-info/top_level.txt,sha256=3WFs84Eqwjm7qQAyTrrrkbkXT9fGkZvpy3IgscQ9F98,18
+runtime_narrative-0.1.0.dist-info/RECORD,,

runtime_narrative-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

runtime_narrative-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Shashank Raj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

runtime_narrative-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+runtime_narrative