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

{runtime_narrative-1.5.1/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.1
+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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "runtime-narrative"
-version = "1.5.1"
+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.1 → runtime_narrative-1.5.2}/runtime_narrative/__init__.py

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

{runtime_narrative-1.5.1 → 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.1 → 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.1
+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

{runtime_narrative-1.5.1 → 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