runtime-narrative 0.1.0__tar.gz

runtime_narrative-0.1.0/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/PKG-INFO

@@ -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/README.MD

@@ -0,0 +1,160 @@
+# 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/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "runtime-narrative"
+version = "0.1.0"
+description = "runtime-narrative — model execution as human-readable stories"
+readme = "README.MD"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+# TODO: replace with your real name and email before publishing
+authors = [
+    { name = "Shashank Raj", email = "shashank.raj28@gmail.com" },
+]
+keywords = ["logging", "observability", "tracing", "fastapi", "debugging", "runtime_narrative"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Logging",
+    "Topic :: System :: Monitoring",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+# Colored terminal output via typer
+console = ["typer>=0.9.0"]
+# FastAPI / Starlette middleware
+fastapi = ["starlette>=0.27.0"]
+# Install everything
+all = [
+    "typer>=0.9.0",
+    "starlette>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/sraj0501/runtime_narrative"
+Repository = "https://github.com/sraj0501/runtime_narrative"
+"Bug Tracker" = "https://github.com/sraj0501/runtime_narrative/issues"
+
+[tool.setuptools]
+packages = ["runtime_narrative", "runtime_narrative.renderer", "runtime_narrative.analyzers"]
+
+[dependency-groups]
+dev = [
+    "build>=1.4.0",
+    "twine>=6.2.0",
+]

runtime_narrative-0.1.0/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-0.1.0/runtime_narrative/analyzers/__init__.py

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

runtime_narrative-0.1.0/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-0.1.0/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=[])