runtime-narrative 1.2.1__tar.gz → 1.3.0__tar.gz

{runtime_narrative-1.2.1/runtime_narrative.egg-info → runtime_narrative-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runtime-narrative
-Version: 1.2.1
+Version: 1.3.0
 Summary: Model execution as human-readable stories with lean/rich failure diagnostics and optional LLM analysis
 Author-email: Shashank Raj <shashank.raj28@gmail.com>
 License-Expression: MIT
@@ -211,6 +211,29 @@ Run: `uv run python examples/logging_bridge.py`, `uv run python examples/structu
 
 ---
 
+## Story outcomes: fold the access log into the story line
+
+`StoryCompleted` carries an `outcome` label. The FastAPI/Starlette and Django middlewares set it automatically from the response status, and `ConsoleRenderer` then renders a single self-contained line per request — story name, result, and HTTP status together:
+
+```
+[d7678e] ▶ Story started: GET /api/call
+[d7678e] ▶ Story ended: GET /api/call - SUCCESS (200 OK, 0.023s)
+```
+
+Since the story line now carries everything the server access log would print, you can silence the duplicate line — e.g. `uvicorn.run(app, access_log=False)`.
+
+Outside middleware, set an outcome on any story yourself:
+
+```python
+from runtime_narrative import http_outcome, story
+
+with story("GET /api/call") as runtime:
+    ...
+    runtime.set_outcome(http_outcome(200))   # or any short label, e.g. "3 rows"
+```
+
+---
+
 ## Feature tour
 
 Everything below works the same way in every context (sync/async, decorators, auto-instrumentation, any framework middleware). One line each here; full detail and every parameter in the Wiki.

{runtime_narrative-1.2.1 → runtime_narrative-1.3.0}/README.md

@@ -152,6 +152,29 @@ Run: `uv run python examples/logging_bridge.py`, `uv run python examples/structu
 
 ---
 
+## Story outcomes: fold the access log into the story line
+
+`StoryCompleted` carries an `outcome` label. The FastAPI/Starlette and Django middlewares set it automatically from the response status, and `ConsoleRenderer` then renders a single self-contained line per request — story name, result, and HTTP status together:
+
+```
+[d7678e] ▶ Story started: GET /api/call
+[d7678e] ▶ Story ended: GET /api/call - SUCCESS (200 OK, 0.023s)
+```
+
+Since the story line now carries everything the server access log would print, you can silence the duplicate line — e.g. `uvicorn.run(app, access_log=False)`.
+
+Outside middleware, set an outcome on any story yourself:
+
+```python
+from runtime_narrative import http_outcome, story
+
+with story("GET /api/call") as runtime:
+    ...
+    runtime.set_outcome(http_outcome(200))   # or any short label, e.g. "3 rows"
+```
+
+---
+
 ## Feature tour
 
 Everything below works the same way in every context (sync/async, decorators, auto-instrumentation, any framework middleware). One line each here; full detail and every parameter in the Wiki.

{runtime_narrative-1.2.1 → runtime_narrative-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "runtime-narrative"
-version = "1.2.1"
+version = "1.3.0"
 description = "Model execution as human-readable stories with lean/rich failure diagnostics and optional LLM analysis"
 readme = "README.md"
 license = "MIT"
@@ -84,13 +84,17 @@ packages = ["runtime_narrative", "runtime_narrative.renderer", "runtime_narrativ
 [dependency-groups]
 dev = [
     "build>=1.4.0",
+    "fastapi>=0.100.0",
     "httpx>=0.27.0",
     "opentelemetry-api>=1.20.0",
     "opentelemetry-sdk>=1.20.0",
     "prometheus-client>=0.19.0",
+    "pydantic>=2.0.0",
     "pytest>=8.0.0",
     "starlette>=0.27.0",
     "twine>=6.2.0",
+    "typer>=0.9.0",
+    "uvicorn>=0.23.0",
 ]
 
 [tool.pytest.ini_options]

{runtime_narrative-1.2.1 → runtime_narrative-1.3.0}/runtime_narrative/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.2.1"
+__version__ = "1.3.0"
 
 from .analyzers import FailureAnalyzer, LLMFailureAnalyzer, OllamaFailureAnalyzer, DeduplicatingAnalyzer
 from .context import has_active_story
@@ -16,6 +16,7 @@ from .events import (
 )
 from .instrumentation import auto_instrument, instrument_module, narrative_class, narrative_stage, no_stage
 from .logging_bridge import NarrativeLogHandler
+from .outcome import http_outcome
 from .renderer.console import ConsoleRenderer
 from .renderer.filter_renderer import FilteredRenderer
 from .renderer.json_renderer import JsonRenderer, RotatingJsonRenderer
@@ -120,6 +121,7 @@ __all__ = [
     "LLMAnalysisReady",
     "LogRecorded",
     "NarrativeLogHandler",
+    "http_outcome",
     "FailureDiagnosticsConfig",
     "build_enriched_failure",
     "effective_diagnostics_mode",

{runtime_narrative-1.2.1 → runtime_narrative-1.3.0}/runtime_narrative/events.py

@@ -82,6 +82,7 @@ class StoryCompleted:
     duration_seconds: float = 0.0
     parent_story_id: str | None = None
     root_story_id: str = ""
+    outcome: str = ""
 
 
 @dataclass

{runtime_narrative-1.2.1 → runtime_narrative-1.3.0}/runtime_narrative/middleware.py

@@ -8,6 +8,7 @@ from starlette.requests import Request
 from starlette.responses import Response
 
 from .diagnostics import FailureDiagnosticsConfig
+from .outcome import http_outcome
 from .story import story
 
 try:
@@ -27,6 +28,8 @@ def _default_middleware_renderers() -> tuple:
     return (JsonRenderer(),)
 
 
+
+
 class RuntimeNarrativeMiddleware(BaseHTTPMiddleware):
     """
     FastAPI/Starlette middleware that wraps every HTTP request in a runtime_narrative story.
@@ -107,8 +110,9 @@ class RuntimeNarrativeMiddleware(BaseHTTPMiddleware):
                 allow_rich_in_production=self._allow_rich_in_production,
                 app_roots=self._app_roots,
                 redact_extra=self._redact_extra,
-            ):
+            ) as runtime:
                 response = await call_next(request)
+                runtime.set_outcome(http_outcome(response.status_code))
             return response
         finally:
             if token is not None:

{runtime_narrative-1.2.1 → runtime_narrative-1.3.0}/runtime_narrative/middleware_django.py

@@ -4,6 +4,7 @@ import sys
 from typing import Any, Sequence
 
 from .diagnostics import FailureDiagnosticsConfig
+from .outcome import http_outcome
 from .story import story
 
 try:
@@ -65,8 +66,11 @@ class RuntimeNarrativeDjangoMiddleware:
             allow_rich_in_production=self._allow_rich_in_production,
             app_roots=self._app_roots,
             redact_extra=self._redact_extra,
-        ):
+        ) as runtime:
             response = await self.get_response(request)
+            status_code = getattr(response, "status_code", None)
+            if status_code is not None:
+                runtime.set_outcome(http_outcome(status_code))
         return response
 
 
@@ -114,8 +118,11 @@ class RuntimeNarrativeDjangoSyncMiddleware:
             allow_rich_in_production=self._allow_rich_in_production,
             app_roots=self._app_roots,
             redact_extra=self._redact_extra,
-        ):
+        ) as runtime:
             response = self.get_response(request)
+            status_code = getattr(response, "status_code", None)
+            if status_code is not None:
+                runtime.set_outcome(http_outcome(status_code))
         return response
 
 

runtime_narrative-1.3.0/runtime_narrative/outcome.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from http import HTTPStatus
+
+
+def http_outcome(status_code: int) -> str:
+    """Format an HTTP status code as a "200 OK"-style story outcome label.
+
+    Sync by design: pure data transformation with no I/O.
+    """
+    try:
+        return f"{status_code} {HTTPStatus(status_code).phrase}"
+    except ValueError:
+        return str(status_code)
+
+
+__all__ = ["http_outcome"]

{runtime_narrative-1.2.1 → runtime_narrative-1.3.0}/runtime_narrative/renderer/console.py

@@ -425,7 +425,17 @@ class ConsoleRenderer:
             self._secho(f"{indent}{tag} ", fg=tag_color, bold=True, nl=False)
             self._secho(f"{self._glyph_arrow} Story ended: ", fg=color, bold=True, nl=False)
             duration = getattr(event, "duration_seconds", 0.0)
-            self._secho(f"{state} ({duration:.3f}s)", fg=value_color, bold=True)
+            outcome = getattr(event, "outcome", "")
+            if outcome:
+                # Outcome-bearing stories (e.g. HTTP requests) get a self-contained
+                # summary line: name + state + outcome, replacing a separate access log.
+                self._secho(
+                    f"{event.story_name} - {state} ({outcome}, {duration:.3f}s)",
+                    fg=value_color,
+                    bold=True,
+                )
+            else:
+                self._secho(f"{state} ({duration:.3f}s)", fg=value_color, bold=True)
             self._story_base_indent.pop(event.story_id, None)
             self._stage_stacks.pop(event.story_id, None)
 

{runtime_narrative-1.2.1 → runtime_narrative-1.3.0}/runtime_narrative/renderer/json_renderer.py

@@ -129,6 +129,7 @@ class JsonRenderer:
                 "duration_seconds": getattr(event, "duration_seconds", 0.0),
                 "parent_story_id": getattr(event, "parent_story_id", None),
                 "root_story_id": getattr(event, "root_story_id", ""),
+                "outcome": getattr(event, "outcome", ""),
             })
 
 

{runtime_narrative-1.2.1 → runtime_narrative-1.3.0}/runtime_narrative/story.py

@@ -30,10 +30,18 @@ class StoryRuntime:
     parent_story_id: str | None = None
     root_story_id: str = ""
     failure_analyzer: Any = field(default=None, repr=False)
+    outcome: str = ""
 
     def set_total_stages(self, n: int) -> None:
         self.declared_total_stages = n
 
+    def set_outcome(self, outcome: str) -> None:
+        """Attach a short result label (e.g. "200 OK") to the StoryCompleted event.
+
+        Sync by design: a pure in-memory setter with no I/O.
+        """
+        self.outcome = outcome
+
     def emit(self, event: object) -> None:
         for renderer in self.renderers:
             try:
@@ -398,6 +406,7 @@ class story:
                 duration_seconds=(datetime.now() - self.runtime.started_at).total_seconds(),
                 parent_story_id=self.runtime.parent_story_id,
                 root_story_id=self.runtime.root_story_id,
+                outcome=self.runtime.outcome,
             )
         )
 
@@ -489,6 +498,7 @@ class story:
                 duration_seconds=(datetime.now() - self.runtime.started_at).total_seconds(),
                 parent_story_id=self.runtime.parent_story_id,
                 root_story_id=self.runtime.root_story_id,
+                outcome=self.runtime.outcome,
             )
         )
 

{runtime_narrative-1.2.1 → runtime_narrative-1.3.0/runtime_narrative.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runtime-narrative
-Version: 1.2.1
+Version: 1.3.0
 Summary: Model execution as human-readable stories with lean/rich failure diagnostics and optional LLM analysis
 Author-email: Shashank Raj <shashank.raj28@gmail.com>
 License-Expression: MIT
@@ -211,6 +211,29 @@ Run: `uv run python examples/logging_bridge.py`, `uv run python examples/structu
 
 ---
 
+## Story outcomes: fold the access log into the story line
+
+`StoryCompleted` carries an `outcome` label. The FastAPI/Starlette and Django middlewares set it automatically from the response status, and `ConsoleRenderer` then renders a single self-contained line per request — story name, result, and HTTP status together:
+
+```
+[d7678e] ▶ Story started: GET /api/call
+[d7678e] ▶ Story ended: GET /api/call - SUCCESS (200 OK, 0.023s)
+```
+
+Since the story line now carries everything the server access log would print, you can silence the duplicate line — e.g. `uvicorn.run(app, access_log=False)`.
+
+Outside middleware, set an outcome on any story yourself:
+
+```python
+from runtime_narrative import http_outcome, story
+
+with story("GET /api/call") as runtime:
+    ...
+    runtime.set_outcome(http_outcome(200))   # or any short label, e.g. "3 rows"
+```
+
+---
+
 ## Feature tour
 
 Everything below works the same way in every context (sync/async, decorators, auto-instrumentation, any framework middleware). One line each here; full detail and every parameter in the Wiki.

{runtime_narrative-1.2.1 → runtime_narrative-1.3.0}/runtime_narrative.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ runtime_narrative/instrumentation.py
 runtime_narrative/logging_bridge.py
 runtime_narrative/middleware.py
 runtime_narrative/middleware_django.py
+runtime_narrative/outcome.py
 runtime_narrative/stage.py
 runtime_narrative/story.py
 runtime_narrative/task_group.py
@@ -65,6 +66,7 @@ tests/test_middleware_propagation.py
 tests/test_otel_log_renderer.py
 tests/test_otel_metrics_renderer.py
 tests/test_otel_renderer.py
+tests/test_outcome.py
 tests/test_persistence_renderer.py
 tests/test_prometheus_renderer.py
 tests/test_redaction_extended.py

{runtime_narrative-1.2.1 → runtime_narrative-1.3.0}/tests/test_console_renderer.py

@@ -97,6 +97,42 @@ def test_all_event_types_render_without_typer(monkeypatch, capsys):
     assert "SUCCESS" in out
 
 
+def test_story_completed_with_outcome_renders_combined_line(monkeypatch, capsys):
+    monkeypatch.setattr(console_mod, "typer", None)
+    ts = datetime(2024, 6, 1)
+    r = ConsoleRenderer()
+
+    r.handle(StoryCompleted(
+        story_id="d7678e", story_name="GET /api/call", success=True,
+        progress_percent=100, completed_stages=1, total_stages=1, timestamp=ts,
+        duration_seconds=0.023, outcome="200 OK",
+    ))
+
+    out = capsys.readouterr().out
+    # One self-contained line: name, state, and HTTP outcome together.
+    line = next(l for l in out.splitlines() if "Story ended" in l)
+    assert "GET /api/call" in line
+    assert "SUCCESS" in line
+    assert "200 OK" in line
+
+
+def test_story_completed_without_outcome_keeps_legacy_line(monkeypatch, capsys):
+    monkeypatch.setattr(console_mod, "typer", None)
+    ts = datetime(2024, 6, 1)
+    r = ConsoleRenderer()
+
+    r.handle(StoryCompleted(
+        story_id="s1", story_name="My Story", success=True,
+        progress_percent=100, completed_stages=1, total_stages=1, timestamp=ts,
+        duration_seconds=0.023,
+    ))
+
+    out = capsys.readouterr().out
+    line = next(l for l in out.splitlines() if "Story ended" in l)
+    assert "My Story" not in line
+    assert "SUCCESS (0.023s)" in line
+
+
 def test_failure_event_renders_without_typer(monkeypatch, capsys):
     monkeypatch.setattr(console_mod, "typer", None)
 

{runtime_narrative-1.2.1 → runtime_narrative-1.3.0}/tests/test_json_renderer.py

@@ -151,3 +151,20 @@ def test_json_renderer_story_completed_includes_duration_and_parent_id() -> None
     assert data["duration_seconds"] == 0.42
     assert data["parent_story_id"] == "s1"
     assert data["root_story_id"] == "s1"
+    assert data["outcome"] == ""
+
+
+def test_json_renderer_story_completed_includes_outcome() -> None:
+    from runtime_narrative.events import StoryCompleted
+
+    buf = StringIO()
+    r = JsonRenderer(output=buf)
+    event = StoryCompleted(
+        story_id="s1", story_name="GET /api/call", success=True, progress_percent=100,
+        completed_stages=1, total_stages=1, timestamp=datetime(2024, 6, 1),
+        duration_seconds=0.02, outcome="200 OK",
+    )
+    r.handle(event)
+    buf.seek(0)
+    data = json.loads(buf.read())
+    assert data["outcome"] == "200 OK"

{runtime_narrative-1.2.1 → runtime_narrative-1.3.0}/tests/test_middleware.py

@@ -62,3 +62,24 @@ def test_middleware_success_emits_story_completed() -> None:
     r = client.get("/ok")
     assert r.status_code == 200
     assert [type(e).__name__ for e in cap.events][-1] == "StoryCompleted"
+    completed = cap.events[-1]
+    assert completed.outcome == "200 OK"
+
+
+def test_middleware_records_error_status_outcome() -> None:
+    cap = CapturingRenderer()
+
+    async def teapot(_request):
+        return PlainTextResponse("no", status_code=418)
+
+    app = Starlette(
+        routes=[Route("/tea", endpoint=teapot, methods=["GET"])],
+        middleware=[Middleware(RuntimeNarrativeMiddleware, renderers=[cap])],
+    )
+
+    client = TestClient(app)
+    r = client.get("/tea")
+    assert r.status_code == 418
+    completed = cap.events[-1]
+    assert type(completed).__name__ == "StoryCompleted"
+    assert completed.outcome.startswith("418")

{runtime_narrative-1.2.1 → runtime_narrative-1.3.0}/tests/test_middleware_django.py

@@ -79,6 +79,42 @@ def test_async_failure_reraises() -> None:
         asyncio.run(mw(_FakeDjangoRequest()))
 
 
+class _FakeDjangoResponse:
+    status_code = 200
+
+
+async def _ok_with_status(request):
+    return _FakeDjangoResponse()
+
+
+def _sync_ok_with_status(request):
+    return _FakeDjangoResponse()
+
+
+def test_async_records_status_outcome() -> None:
+    renderer = CapturingRenderer()
+    mw = _django_mod.RuntimeNarrativeDjangoMiddleware(_ok_with_status, renderers=[renderer])
+    asyncio.run(mw(_FakeDjangoRequest()))
+    completed = next(e for e in renderer.events if type(e).__name__ == "StoryCompleted")
+    assert completed.outcome == "200 OK"
+
+
+def test_sync_records_status_outcome() -> None:
+    renderer = CapturingRenderer()
+    mw = _django_mod.RuntimeNarrativeDjangoSyncMiddleware(_sync_ok_with_status, renderers=[renderer])
+    mw(_FakeDjangoRequest())
+    completed = next(e for e in renderer.events if type(e).__name__ == "StoryCompleted")
+    assert completed.outcome == "200 OK"
+
+
+def test_async_response_without_status_leaves_outcome_empty() -> None:
+    renderer = CapturingRenderer()
+    mw = _django_mod.RuntimeNarrativeDjangoMiddleware(_ok, renderers=[renderer])
+    asyncio.run(mw(_FakeDjangoRequest()))
+    completed = next(e for e in renderer.events if type(e).__name__ == "StoryCompleted")
+    assert completed.outcome == ""
+
+
 def test_sync_emits_story_events() -> None:
     renderer = CapturingRenderer()
     mw = _django_mod.RuntimeNarrativeDjangoSyncMiddleware(_sync_ok, renderers=[renderer])

runtime_narrative-1.3.0/tests/test_outcome.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from runtime_narrative.outcome import http_outcome
+
+
+def test_http_outcome_known_codes() -> None:
+    assert http_outcome(200) == "200 OK"
+    assert http_outcome(404) == "404 Not Found"
+    assert http_outcome(500) == "500 Internal Server Error"
+
+
+def test_http_outcome_unknown_code_falls_back_to_number() -> None:
+    assert http_outcome(599) == "599"

{runtime_narrative-1.2.1 → runtime_narrative-1.3.0}/tests/test_story.py

@@ -273,3 +273,31 @@ def test_background_analysis_emits_llm_ready() -> None:
     assert "FailureOccurred" in kinds
     assert "StoryCompleted" in kinds
     assert "LLMAnalysisReady" in kinds
+
+
+def test_sync_story_set_outcome_flows_to_story_completed() -> None:
+    cap = CapturingRenderer()
+    with story("GET /api/call", renderers=[cap]) as runtime:
+        runtime.set_outcome("200 OK")
+    completed = next(e for e in cap.events if isinstance(e, StoryCompleted))
+    assert completed.outcome == "200 OK"
+
+
+def test_async_story_set_outcome_flows_to_story_completed() -> None:
+    cap = AsyncCapturingRenderer()
+
+    async def run() -> None:
+        async with story("GET /api/call", renderers=[cap]) as runtime:
+            runtime.set_outcome("201 Created")
+
+    asyncio.run(run())
+    completed = next(e for e in cap.events if isinstance(e, StoryCompleted))
+    assert completed.outcome == "201 Created"
+
+
+def test_story_outcome_defaults_to_empty() -> None:
+    cap = CapturingRenderer()
+    with story("S", renderers=[cap]):
+        pass
+    completed = next(e for e in cap.events if isinstance(e, StoryCompleted))
+    assert completed.outcome == ""