runtime-narrative 1.5.0__tar.gz → 1.5.2__tar.gz

{runtime_narrative-1.5.0/runtime_narrative.egg-info → runtime_narrative-1.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runtime-narrative
-Version: 1.5.0
+Version: 1.5.2
 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
@@ -353,6 +353,7 @@ Every script under `examples/` is runnable as-is: `uv run python examples/<name>
 | `middleware_skip_if.py` | `RuntimeNarrativeMiddleware(skip_if=...)` for FastAPI/Starlette |
 | `task_group.py` | `NarrativeTaskGroup` — concurrent asyncio tasks under one story |
 | `fastapi_app/` | Full FastAPI demo app (`uv run python -m examples.fastapi_app.run`) |
+| `fastapi_ugly_traceback_demo.py` | The same deep async bug (route → orchestrator → retry-wrapped pricing engine → `asyncio.gather` fan-out → the actual TypeError), run once with no instrumentation and once with runtime-narrative — a raw ~35-frame traceback vs. one pinpointed line, source snippet, and locals |
 
 **Testing and lifecycle utilities**
 | Script | Demonstrates |

{runtime_narrative-1.5.0 → runtime_narrative-1.5.2}/README.md

@@ -294,6 +294,7 @@ Every script under `examples/` is runnable as-is: `uv run python examples/<name>
 | `middleware_skip_if.py` | `RuntimeNarrativeMiddleware(skip_if=...)` for FastAPI/Starlette |
 | `task_group.py` | `NarrativeTaskGroup` — concurrent asyncio tasks under one story |
 | `fastapi_app/` | Full FastAPI demo app (`uv run python -m examples.fastapi_app.run`) |
+| `fastapi_ugly_traceback_demo.py` | The same deep async bug (route → orchestrator → retry-wrapped pricing engine → `asyncio.gather` fan-out → the actual TypeError), run once with no instrumentation and once with runtime-narrative — a raw ~35-frame traceback vs. one pinpointed line, source snippet, and locals |
 
 **Testing and lifecycle utilities**
 | Script | Demonstrates |

{runtime_narrative-1.5.0 → runtime_narrative-1.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "runtime-narrative"
-version = "1.5.0"
+version = "1.5.2"
 description = "Model execution as human-readable stories with lean/rich failure diagnostics and optional LLM analysis"
 readme = "README.md"
 license = "MIT"

{runtime_narrative-1.5.0 → runtime_narrative-1.5.2}/runtime_narrative/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.5.0"
+__version__ = "1.5.2"
 
 from .analyzers import FailureAnalyzer, LLMFailureAnalyzer, OllamaFailureAnalyzer, DeduplicatingAnalyzer
 from .context import has_active_story

{runtime_narrative-1.5.0 → runtime_narrative-1.5.2}/runtime_narrative/diagnostics.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import ast
 import os
 import re
 import sys
@@ -261,6 +262,114 @@ def _should_redact_key(
     return False
 
 
+# ── Operand-type-mismatch explanation ───────────────────────────────────────
+# Names the specific variable(s)/expression(s) behind a
+# "TypeError: unsupported operand type(s) for OP: 'A' and 'B'" instead of just
+# restating the exception message. Only activates in rich mode, reusing the
+# frame locals already captured there (no extra capture cost) and the same
+# redaction pipeline as the locals section. Anything it can't confidently
+# resolve falls back to the generic exact_cause untouched.
+
+_OPERAND_TYPE_ERROR_RE = re.compile(
+    r"^unsupported operand type\(s\) for (?P<op>\S+): '(?P<left_type>\w+)' and '(?P<right_type>\w+)'$"
+)
+
+_OP_SYMBOL_TO_AST: dict[str, type] = {
+    "+": ast.Add, "-": ast.Sub, "*": ast.Mult, "/": ast.Div,
+    "//": ast.FloorDiv, "%": ast.Mod, "**": ast.Pow, "@": ast.MatMult,
+    "&": ast.BitAnd, "|": ast.BitOr, "^": ast.BitXor, "<<": ast.LShift, ">>": ast.RShift,
+}
+
+
+def _safe_resolve_expr(node: ast.AST, frame_locals: Mapping[str, Any]) -> tuple[bool, Any]:
+    """Resolve a bare name or a one-level constant-key subscript (e.g. ``item["price"]``)
+    against already-captured frame locals. Never calls into user code (no
+    attribute access, no function calls) — only dict/list/tuple __getitem__ on
+    values we already hold a reference to."""
+    if isinstance(node, ast.Name):
+        if node.id in frame_locals:
+            return True, frame_locals[node.id]
+        return False, None
+    if isinstance(node, ast.Subscript):
+        base_ok, base_val = _safe_resolve_expr(node.value, frame_locals)
+        if not base_ok:
+            return False, None
+        key_node = node.slice
+        if isinstance(key_node, ast.Constant):
+            try:
+                return True, base_val[key_node.value]
+            except Exception:
+                return False, None
+    return False, None
+
+
+def _describe_operand(
+    node: ast.AST,
+    type_name: str,
+    frame_locals: Mapping[str, Any],
+    *,
+    max_len: int,
+    extra_redact: tuple[str, ...],
+    redact_patterns: tuple[str, ...],
+    redact_callback: Any,
+) -> str:
+    try:
+        text = ast.unparse(node)
+    except Exception:
+        text = "<expr>"
+    if isinstance(node, ast.Name) and _should_redact_key(
+        node.id, extra=extra_redact, patterns=redact_patterns, callback=redact_callback
+    ):
+        return f"`{text}` ({type_name}, redacted)"
+    resolved, value = _safe_resolve_expr(node, frame_locals)
+    if resolved:
+        value_repr = _serialize_value(
+            value, max_len=max_len, depth=0, max_depth=1,
+            extra_redact=extra_redact, redact_patterns=redact_patterns, redact_callback=redact_callback,
+        )
+        return f"`{text}` = {value_repr} ({type_name})"
+    return f"`{text}` ({type_name})"
+
+
+def _infer_operand_type_mismatch(
+    message: str,
+    source_line: str,
+    frame_locals: Mapping[str, Any],
+    *,
+    max_len: int,
+    extra_redact: tuple[str, ...],
+    redact_patterns: tuple[str, ...],
+    redact_callback: Any,
+) -> str | None:
+    """For 'unsupported operand type(s) for OP: A and B', name the specific
+    operands involved and (when safely resolvable) their actual values,
+    instead of just restating the exception message. Returns None on any
+    parse/resolution failure so callers can fall back to the generic cause."""
+    m = _OPERAND_TYPE_ERROR_RE.match(message.strip())
+    if not m:
+        return None
+    op_cls = _OP_SYMBOL_TO_AST.get(m.group("op"))
+    if op_cls is None:
+        return None
+    try:
+        tree = ast.parse(f"async def _f():\n    {source_line.strip()}")
+    except SyntaxError:
+        return None
+    binop = next(
+        (n for n in ast.walk(tree) if isinstance(n, ast.BinOp) and isinstance(n.op, op_cls)),
+        None,
+    )
+    if binop is None:
+        return None
+    kwargs = dict(max_len=max_len, extra_redact=extra_redact, redact_patterns=redact_patterns, redact_callback=redact_callback)
+    left_desc = _describe_operand(binop.left, m.group("left_type"), frame_locals, **kwargs)
+    right_desc = _describe_operand(binop.right, m.group("right_type"), frame_locals, **kwargs)
+    return (
+        f"{left_desc} and {right_desc} can't be combined with '{m.group('op')}' - "
+        f"{m.group('left_type')} and {m.group('right_type')} are incompatible operand types."
+    )
+
+
 def _capture_locals_mapping(
     locals_map: Mapping[str, Any],
     *,
@@ -384,6 +493,18 @@ def build_enriched_failure(
     elif config.max_traceback_chars is not None:
         tb_out, truncated = _truncate_tb(full_tb, config.max_traceback_chars)
 
+    exact_cause = _infer_exact_cause(exc_type.__name__, str(exc), source_line)
+    if mode == "rich" and exc_type.__name__ == "TypeError" and frame_objs and 0 <= primary_idx < len(frame_objs):
+        enhanced_cause = _infer_operand_type_mismatch(
+            str(exc), source_line, frame_objs[primary_idx].f_locals,
+            max_len=config.max_local_value_len,
+            extra_redact=config.redact_extra,
+            redact_patterns=config.redact_patterns,
+            redact_callback=config.redact_callback,
+        )
+        if enhanced_cause is not None:
+            exact_cause = enhanced_cause
+
     summary = FailureSummary(
         error_type=exc_type.__name__,
         error_message=str(exc),
@@ -392,7 +513,7 @@ def build_enriched_failure(
         function=function,
         source_line=source_line,
         exception_chain=_build_exception_chain(exc),
-        exact_cause=_infer_exact_cause(exc_type.__name__, str(exc), source_line),
+        exact_cause=exact_cause,
         traceback_text=tb_out,
     )
 

{runtime_narrative-1.5.0 → runtime_narrative-1.5.2}/runtime_narrative/failure.py

@@ -19,12 +19,29 @@ class FailureSummary:
 
 
 def _build_exception_chain(exc: BaseException) -> str:
+    """Walk __cause__/__context__ the same way Python's own traceback module does.
+
+    Explicit chaining (``raise X from Y``) is always followed. Implicit
+    chaining (``__context__``, set automatically when an exception is raised
+    while handling another) is followed *unless* the raiser suppressed it
+    with ``raise X from None`` — ``__suppress_context__`` is exactly that
+    signal. Ignoring it here would surface unrelated exceptions the original
+    author deliberately hid (e.g. cleanup/cancellation noise from a retry
+    wrapper's ``raise last_exc from None``), and the raw traceback wouldn't
+    show them either — so this would silently disagree with Python's own
+    output.
+    """
     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__
+        if current.__cause__ is not None:
+            current = current.__cause__
+        elif not current.__suppress_context__:
+            current = current.__context__
+        else:
+            current = None
         depth += 1
     return " <- ".join(parts)
 

{runtime_narrative-1.5.0 → runtime_narrative-1.5.2}/runtime_narrative/renderer/console.py

@@ -68,10 +68,12 @@ class ConsoleRenderer:
             self._glyph_arrow = "▶"
             self._glyph_check = "✔"
             self._glyph_cross = "❌"
+            self._glyph_dash = "—"
         else:
             self._glyph_arrow = ">"
             self._glyph_check = "[ok]"
             self._glyph_cross = "[FAIL]"
+            self._glyph_dash = "-"
         # story_id -> indent level of that story's own Story started/ended lines
         self._story_base_indent: dict[str, int] = {}
         # story_id -> stack of currently open stage names, for indent depth
@@ -404,7 +406,7 @@ class ConsoleRenderer:
                 for label, payload in locals_by_frame.items():
                     locs = payload.get("locals", {})
                     where = f"{payload.get('filename')}:{payload.get('lineno')} in {payload.get('function')}"
-                    self._secho(f"  {label} — {where}", fg=self._failure_heading_color)
+                    self._secho(f"  {label} {self._glyph_dash} {where}", fg=self._failure_heading_color)
                     for k, v in locs.items():
                         self._secho(f"    {k} = {v}", fg=self._failure_value_color)
                 removed = getattr(event, "redaction_removed_keys", 0)

{runtime_narrative-1.5.0 → runtime_narrative-1.5.2/runtime_narrative.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runtime-narrative
-Version: 1.5.0
+Version: 1.5.2
 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
@@ -353,6 +353,7 @@ Every script under `examples/` is runnable as-is: `uv run python examples/<name>
 | `middleware_skip_if.py` | `RuntimeNarrativeMiddleware(skip_if=...)` for FastAPI/Starlette |
 | `task_group.py` | `NarrativeTaskGroup` — concurrent asyncio tasks under one story |
 | `fastapi_app/` | Full FastAPI demo app (`uv run python -m examples.fastapi_app.run`) |
+| `fastapi_ugly_traceback_demo.py` | The same deep async bug (route → orchestrator → retry-wrapped pricing engine → `asyncio.gather` fan-out → the actual TypeError), run once with no instrumentation and once with runtime-narrative — a raw ~35-frame traceback vs. one pinpointed line, source snippet, and locals |
 
 **Testing and lifecycle utilities**
 | Script | Demonstrates |

{runtime_narrative-1.5.0 → runtime_narrative-1.5.2}/tests/test_console_renderer.py

@@ -40,6 +40,7 @@ def test_renderer_ascii_glyphs_on_non_unicode_terminal(monkeypatch):
     assert r._glyph_arrow == ">"
     assert r._glyph_check == "[ok]"
     assert r._glyph_cross == "[FAIL]"
+    assert r._glyph_dash == "-"
 
 
 def test_renderer_unicode_glyphs_on_unicode_terminal(monkeypatch):
@@ -48,6 +49,33 @@ def test_renderer_unicode_glyphs_on_unicode_terminal(monkeypatch):
     assert r._glyph_arrow == "▶"
     assert r._glyph_check == "✔"
     assert r._glyph_cross == "❌"
+    assert r._glyph_dash == "—"
+
+
+def test_rich_locals_line_uses_ascii_dash_on_non_unicode_terminal(monkeypatch, capsys):
+    """The 'frame_N — file:line in func' locals heading must go through the same
+    ASCII-fallback path as the other glyphs, not a hardcoded em-dash that would
+    degrade to a '?' replacement character on a non-UTF-8 stream."""
+    monkeypatch.setattr(console_mod, "_stdout_supports_unicode", lambda: False)
+    r = ConsoleRenderer()
+    event = FailureOccurred(
+        story_id="sid", story_name="S", stage_name="St",
+        error_type="TypeError", error_message="m", filename="f.py", lineno=1,
+        function="fn", source_line="raise TypeError", exception_chain="TypeError: m",
+        exact_cause="because", llm_analysis=None, stage_timeline="x",
+        progress_percent=0, completed_stages=0, total_stages=1,
+        timestamp=datetime(2024, 1, 1),
+        diagnostics_mode="rich", primary_frame_reason="innermost_app",
+        stack_frames=[], source_snippet=None, compressed_stack_summary="",
+        hidden_frame_count=0, traceback_truncated=False,
+        locals_by_frame={"frame_0": {"filename": "f.py", "lineno": 1, "function": "fn", "locals": {"x": "1"}}},
+        redaction_removed_keys=0,
+        traceback_text="Traceback...",
+    )
+    r.handle(event)
+    out = capsys.readouterr().out
+    assert "frame_0 - f.py:1 in fn" in out
+    assert "—" not in out
 
 
 def test_secho_survives_unicode_encode_error_from_typer(monkeypatch):

{runtime_narrative-1.5.0 → runtime_narrative-1.5.2}/tests/test_diagnostics.py

@@ -252,3 +252,86 @@ def test_compressed_stack_summary_counts_app_frames() -> None:
 
     assert "app frame" in enriched.compressed_stack_summary
     assert str(len(enriched.stack_frames)) in enriched.compressed_stack_summary
+
+
+# ── Operand-type-mismatch exact_cause enhancement ─────────────────────────────
+
+def test_exact_cause_names_operands_on_type_mismatch_in_rich_mode() -> None:
+    cfg = FailureDiagnosticsConfig(runtime_environment="development", failure_diagnostics="rich")
+
+    def inner() -> None:
+        item = {"price": 29.99}
+        promo = {"buy": 1, "get": 1}
+        item["price"] * promo  # noqa: B018 - deliberately triggers TypeError
+
+    try:
+        inner()
+    except TypeError as e:
+        enriched = build_enriched_failure(type(e), e, e.__traceback__, config=cfg)
+
+    cause = enriched.summary.exact_cause
+    assert "item['price']" in cause
+    assert "29.99" in cause
+    assert "promo" in cause
+    assert "{'buy': 1, 'get': 1}" in cause
+    assert "float" in cause and "dict" in cause
+    # Must stay plain ASCII -- this string also flows into JSON/OTel, not just
+    # a Unicode-aware console.
+    assert all(ord(c) < 128 for c in cause)
+
+
+def test_exact_cause_falls_back_to_generic_in_lean_mode() -> None:
+    """The enhancement only fires in rich mode -- lean mode never inspects locals."""
+    cfg = FailureDiagnosticsConfig(runtime_environment="development", failure_diagnostics="lean")
+
+    def inner() -> None:
+        item = {"price": 29.99}
+        promo = {"buy": 1, "get": 1}
+        item["price"] * promo  # noqa: B018
+
+    try:
+        inner()
+    except TypeError as e:
+        enriched = build_enriched_failure(type(e), e, e.__traceback__, config=cfg)
+
+    assert enriched.summary.exact_cause.startswith("The statement `")
+
+
+def test_exact_cause_redacts_operand_named_like_a_secret() -> None:
+    cfg = FailureDiagnosticsConfig(runtime_environment="development", failure_diagnostics="rich")
+
+    def inner() -> None:
+        api_token = {"scope": "read"}
+        1.5 * api_token  # noqa: B018
+
+    try:
+        inner()
+    except TypeError as e:
+        enriched = build_enriched_failure(type(e), e, e.__traceback__, config=cfg)
+
+    cause = enriched.summary.exact_cause
+    assert "redacted" in cause
+    assert "scope" not in cause
+
+
+def test_exact_cause_falls_back_when_operand_not_a_simple_expression() -> None:
+    """Function calls / complex expressions aren't safely resolvable -- the
+    enhancement should still fire (naming the expression text) without
+    evaluating anything, and never raise."""
+    cfg = FailureDiagnosticsConfig(runtime_environment="development", failure_diagnostics="rich")
+
+    def get_promo() -> dict:
+        return {"buy": 1}
+
+    def inner() -> None:
+        price = 10.0
+        price * get_promo()  # noqa: B018
+
+    try:
+        inner()
+    except TypeError as e:
+        enriched = build_enriched_failure(type(e), e, e.__traceback__, config=cfg)
+
+    cause = enriched.summary.exact_cause
+    assert "get_promo()" in cause
+    assert "price" in cause

runtime_narrative-1.5.2/tests/test_failure.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from runtime_narrative.failure import summarize_exception
+
+
+def test_summarize_exception_extracts_leaf_frame() -> None:
+    def inner() -> None:
+        raise KeyError("missing")
+
+    try:
+        inner()
+    except KeyError as e:
+        summary = summarize_exception(type(e), e, e.__traceback__)
+
+    assert summary.error_type == "KeyError"
+    assert "missing" in summary.error_message
+    assert summary.function == "inner"
+    assert "KeyError" in summary.exception_chain
+    assert "inner" in summary.traceback_text
+
+
+def test_exception_chain_respects_suppress_context() -> None:
+    """`raise X from None` must stop the chain, matching Python's own traceback
+    output. Naively following __context__ would surface unrelated exceptions
+    (e.g. cleanup/cancellation noise) that the raiser deliberately hid."""
+    def inner() -> None:
+        try:
+            raise ValueError("unrelated cleanup noise")
+        except ValueError:
+            raise TypeError("the real error") from None
+
+    try:
+        inner()
+    except TypeError as e:
+        summary = summarize_exception(type(e), e, e.__traceback__)
+
+    assert summary.exception_chain == "TypeError: the real error"
+    assert "ValueError" not in summary.exception_chain
+
+
+def test_exception_chain_follows_explicit_cause_even_with_suppress_context() -> None:
+    """`raise X from Y` always shows Y — __suppress_context__ only governs
+    the implicit __context__ fallback, never an explicit __cause__."""
+    def inner() -> None:
+        try:
+            raise ValueError("root cause")
+        except ValueError as root:
+            raise TypeError("wrapped") from root
+
+    try:
+        inner()
+    except TypeError as e:
+        summary = summarize_exception(type(e), e, e.__traceback__)
+
+    assert summary.exception_chain == "TypeError: wrapped <- ValueError: root cause"

runtime_narrative-1.5.0/tests/test_failure.py

@@ -1,19 +0,0 @@
-from __future__ import annotations
-
-from runtime_narrative.failure import summarize_exception
-
-
-def test_summarize_exception_extracts_leaf_frame() -> None:
-    def inner() -> None:
-        raise KeyError("missing")
-
-    try:
-        inner()
-    except KeyError as e:
-        summary = summarize_exception(type(e), e, e.__traceback__)
-
-    assert summary.error_type == "KeyError"
-    assert "missing" in summary.error_message
-    assert summary.function == "inner"
-    assert "KeyError" in summary.exception_chain
-    assert "inner" in summary.traceback_text