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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runtime-narrative
-Version: 1.5.2
+Version: 1.5.3
 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
@@ -377,6 +377,7 @@ Every script under `examples/` is runnable as-is: `uv run python examples/<name>
 | `ANTHROPIC_API_KEY` | API key | — | Required by `AnthropicFailureAnalyzer`; read automatically if `api_key=` is not passed |
 | `RUNTIME_NARRATIVE_RICH_LOG_FILE` | file path | — | Adds a file-backed `ConsoleRenderer` writing rich, human-readable output to this path, on top of whichever renderer TTY detection selects. Read by every auto-instrumentation entry point (FastAPI/Starlette, Django, Celery, gRPC) when `renderers=` is omitted |
 | `RUNTIME_NARRATIVE_RICH_LOG_CONSOLE` | `1`, `0` | `1` | With `RUNTIME_NARRATIVE_RICH_LOG_FILE` set and stdout a TTY, `0` suppresses the terminal copy so the narrative goes to the file only |
+| `RUNTIME_NARRATIVE_ANALYZER_TIMEOUT_SECONDS` | seconds (float) | `12` (`OllamaFailureAnalyzer`/`LLMFailureAnalyzer`), `30` (`AnthropicFailureAnalyzer`) | Request timeout for the built-in failure analyzers. Raise it for slower or cold-loading local models (e.g. Ollama loading a multi-GB model from disk); on timeout or any other request failure the analyzer logs a `logging.warning` (module `runtime_narrative.analyzers.*`) and falls back to no LLM analysis rather than failing the story |
 
 ---
 

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

@@ -318,6 +318,7 @@ Every script under `examples/` is runnable as-is: `uv run python examples/<name>
 | `ANTHROPIC_API_KEY` | API key | — | Required by `AnthropicFailureAnalyzer`; read automatically if `api_key=` is not passed |
 | `RUNTIME_NARRATIVE_RICH_LOG_FILE` | file path | — | Adds a file-backed `ConsoleRenderer` writing rich, human-readable output to this path, on top of whichever renderer TTY detection selects. Read by every auto-instrumentation entry point (FastAPI/Starlette, Django, Celery, gRPC) when `renderers=` is omitted |
 | `RUNTIME_NARRATIVE_RICH_LOG_CONSOLE` | `1`, `0` | `1` | With `RUNTIME_NARRATIVE_RICH_LOG_FILE` set and stdout a TTY, `0` suppresses the terminal copy so the narrative goes to the file only |
+| `RUNTIME_NARRATIVE_ANALYZER_TIMEOUT_SECONDS` | seconds (float) | `12` (`OllamaFailureAnalyzer`/`LLMFailureAnalyzer`), `30` (`AnthropicFailureAnalyzer`) | Request timeout for the built-in failure analyzers. Raise it for slower or cold-loading local models (e.g. Ollama loading a multi-GB model from disk); on timeout or any other request failure the analyzer logs a `logging.warning` (module `runtime_narrative.analyzers.*`) and falls back to no LLM analysis rather than failing the story |
 
 ---
 

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

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

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

{runtime_narrative-1.5.2 → runtime_narrative-1.5.3}/runtime_narrative/analyzers/anthropic.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import logging
 import os
 import re
 from dataclasses import dataclass, field
@@ -14,9 +15,12 @@ except ImportError:
     _ANTHROPIC_AVAILABLE = False
 
 from ..failure import FailureSummary
+from .ollama import _default_analyzer_timeout_seconds
 
 __all__ = ["AnthropicFailureAnalyzer"]
 
+logger = logging.getLogger(__name__)
+
 _DEFAULT_MODEL = "claude-haiku-4-5-20251001"
 
 
@@ -24,7 +28,7 @@ _DEFAULT_MODEL = "claude-haiku-4-5-20251001"
 class AnthropicFailureAnalyzer:
     api_key: str = field(default_factory=lambda: os.environ.get("ANTHROPIC_API_KEY", ""))
     model: str = field(default_factory=lambda: os.environ.get("RUNTIME_NARRATIVE_MODEL", _DEFAULT_MODEL))
-    timeout_seconds: float = 30.0
+    timeout_seconds: float = field(default_factory=lambda: _default_analyzer_timeout_seconds(fallback=30.0))
     max_tokens: int = 1024
     system_prompt: str = "You are an expert Python debugging assistant. Be concise and specific."
 
@@ -120,6 +124,15 @@ class AnthropicFailureAnalyzer:
             )
             text = response.content[0].text.strip()
         except Exception:
+            logger.warning(
+                "AnthropicFailureAnalyzer: request to model %s timed out or "
+                "failed (timeout_seconds=%s) -- no LLM analysis for this "
+                "failure. Raise RUNTIME_NARRATIVE_ANALYZER_TIMEOUT_SECONDS "
+                "if the API just needs more time.",
+                self.model,
+                self.timeout_seconds,
+                exc_info=True,
+            )
             return None
         return self._parse_response(text) or None
 
@@ -150,5 +163,14 @@ class AnthropicFailureAnalyzer:
             )
             text = response.content[0].text.strip()
         except Exception:
+            logger.warning(
+                "AnthropicFailureAnalyzer: async request to model %s timed "
+                "out or failed (timeout_seconds=%s) -- no LLM analysis for "
+                "this failure. Raise RUNTIME_NARRATIVE_ANALYZER_TIMEOUT_SECONDS "
+                "if the API just needs more time.",
+                self.model,
+                self.timeout_seconds,
+                exc_info=True,
+            )
             return None
         return self._parse_response(text) or None

{runtime_narrative-1.5.2 → runtime_narrative-1.5.3}/runtime_narrative/analyzers/ollama.py

@@ -2,6 +2,8 @@ from __future__ import annotations
 
 import asyncio
 import json
+import logging
+import os
 import re
 from dataclasses import dataclass, field
 from functools import partial
@@ -11,6 +13,26 @@ from urllib.request import Request, urlopen
 
 from ..failure import FailureSummary
 
+logger = logging.getLogger(__name__)
+
+
+def _default_analyzer_timeout_seconds(fallback: float = 12.0) -> float:
+    """Default request timeout for LLM failure analyzers.
+
+    Reads `RUNTIME_NARRATIVE_ANALYZER_TIMEOUT_SECONDS` so deployments with
+    slower/cold-loading local models (e.g. Ollama loading a multi-GB model
+    from disk) can raise it without subclassing or passing timeout_seconds=
+    at every call site. Falls back to `fallback` (each analyzer's own
+    previous hardcoded default) when the env var is unset or invalid.
+    """
+    raw = os.getenv("RUNTIME_NARRATIVE_ANALYZER_TIMEOUT_SECONDS")
+    if not raw:
+        return fallback
+    try:
+        return float(raw)
+    except ValueError:
+        return fallback
+
 
 _SECTION_LABELS = {
     "exact_why": "Exact Why",
@@ -114,7 +136,7 @@ class LLMFailureAnalyzer:
 
     model: str
     endpoint: str
-    timeout_seconds: float = 12.0
+    timeout_seconds: float = field(default_factory=_default_analyzer_timeout_seconds)
     include_traceback_lines: int = 30
     max_context_chars: int = 8000
 
@@ -152,12 +174,27 @@ class LLMFailureAnalyzer:
             with urlopen(request, timeout=self.timeout_seconds) as response:
                 body = response.read().decode("utf-8")
         except (URLError, TimeoutError, Exception):
+            logger.warning(
+                "LLMFailureAnalyzer: request to %s timed out or failed "
+                "(timeout_seconds=%s) -- no LLM analysis for this failure. "
+                "Raise RUNTIME_NARRATIVE_ANALYZER_TIMEOUT_SECONDS if the "
+                "endpoint just needs more time (e.g. a cold model load).",
+                self.endpoint,
+                self.timeout_seconds,
+                exc_info=True,
+            )
             return None
 
         try:
             parsed = json.loads(body)
             text = parsed["choices"][0]["message"]["content"].strip()
         except Exception:
+            logger.warning(
+                "LLMFailureAnalyzer: response from %s was not the expected "
+                "chat-completions JSON shape -- no LLM analysis for this failure.",
+                self.endpoint,
+                exc_info=True,
+            )
             return None
 
         return _parse_structured_response(text) or None
@@ -200,7 +237,7 @@ class OllamaFailureAnalyzer:
 
     model: str
     endpoint: str = "http://127.0.0.1:11434/api/generate"
-    timeout_seconds: float = 12.0
+    timeout_seconds: float = field(default_factory=_default_analyzer_timeout_seconds)
     include_traceback_lines: int = 30
     max_context_chars: int = 8000
 
@@ -238,12 +275,27 @@ class OllamaFailureAnalyzer:
             with urlopen(request, timeout=self.timeout_seconds) as response:
                 body = response.read().decode("utf-8")
         except (URLError, TimeoutError, Exception):
+            logger.warning(
+                "OllamaFailureAnalyzer: request to %s timed out or failed "
+                "(timeout_seconds=%s) -- no LLM analysis for this failure. "
+                "Raise RUNTIME_NARRATIVE_ANALYZER_TIMEOUT_SECONDS if the "
+                "endpoint just needs more time (e.g. a cold model load).",
+                self.endpoint,
+                self.timeout_seconds,
+                exc_info=True,
+            )
             return None
 
         try:
             parsed = json.loads(body)
             text = parsed.get("response", "").strip()
         except Exception:
+            logger.warning(
+                "OllamaFailureAnalyzer: response from %s was not the expected "
+                "/api/generate JSON shape -- no LLM analysis for this failure.",
+                self.endpoint,
+                exc_info=True,
+            )
             return None
 
         return _parse_structured_response(text) or None

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runtime-narrative
-Version: 1.5.2
+Version: 1.5.3
 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
@@ -377,6 +377,7 @@ Every script under `examples/` is runnable as-is: `uv run python examples/<name>
 | `ANTHROPIC_API_KEY` | API key | — | Required by `AnthropicFailureAnalyzer`; read automatically if `api_key=` is not passed |
 | `RUNTIME_NARRATIVE_RICH_LOG_FILE` | file path | — | Adds a file-backed `ConsoleRenderer` writing rich, human-readable output to this path, on top of whichever renderer TTY detection selects. Read by every auto-instrumentation entry point (FastAPI/Starlette, Django, Celery, gRPC) when `renderers=` is omitted |
 | `RUNTIME_NARRATIVE_RICH_LOG_CONSOLE` | `1`, `0` | `1` | With `RUNTIME_NARRATIVE_RICH_LOG_FILE` set and stdout a TTY, `0` suppresses the terminal copy so the narrative goes to the file only |
+| `RUNTIME_NARRATIVE_ANALYZER_TIMEOUT_SECONDS` | seconds (float) | `12` (`OllamaFailureAnalyzer`/`LLMFailureAnalyzer`), `30` (`AnthropicFailureAnalyzer`) | Request timeout for the built-in failure analyzers. Raise it for slower or cold-loading local models (e.g. Ollama loading a multi-GB model from disk); on timeout or any other request failure the analyzer logs a `logging.warning` (module `runtime_narrative.analyzers.*`) and falls back to no LLM analysis rather than failing the story |
 
 ---
 

{runtime_narrative-1.5.2 → runtime_narrative-1.5.3}/tests/test_analyzers.py

@@ -131,3 +131,47 @@ def test_ollama_analyzer_returns_none_on_url_error():
     with patch("runtime_narrative.analyzers.ollama.urlopen", side_effect=URLError("no route")):
         result = analyzer.analyze_failure(**_KWARGS)
     assert result is None
+
+
+# ── Configurable timeout + failure visibility ─────────────────────────────────
+
+def test_default_timeout_seconds_falls_back_when_env_unset(monkeypatch):
+    monkeypatch.delenv("RUNTIME_NARRATIVE_ANALYZER_TIMEOUT_SECONDS", raising=False)
+    assert OllamaFailureAnalyzer(model="llama3").timeout_seconds == 12.0
+    assert LLMFailureAnalyzer(model="gpt-4", endpoint="http://x/v1/chat/completions").timeout_seconds == 12.0
+
+
+def test_default_timeout_seconds_reads_env(monkeypatch):
+    monkeypatch.setenv("RUNTIME_NARRATIVE_ANALYZER_TIMEOUT_SECONDS", "45")
+    assert OllamaFailureAnalyzer(model="llama3").timeout_seconds == 45.0
+
+
+def test_default_timeout_seconds_falls_back_on_invalid_env(monkeypatch):
+    monkeypatch.setenv("RUNTIME_NARRATIVE_ANALYZER_TIMEOUT_SECONDS", "not-a-number")
+    assert OllamaFailureAnalyzer(model="llama3").timeout_seconds == 12.0
+
+
+def test_explicit_timeout_seconds_overrides_env(monkeypatch):
+    monkeypatch.setenv("RUNTIME_NARRATIVE_ANALYZER_TIMEOUT_SECONDS", "45")
+    assert OllamaFailureAnalyzer(model="llama3", timeout_seconds=5.0).timeout_seconds == 5.0
+
+
+def test_ollama_analyzer_logs_warning_on_request_failure(caplog):
+    from urllib.error import URLError
+    analyzer = OllamaFailureAnalyzer(model="llama3", timeout_seconds=12.0)
+    with caplog.at_level("WARNING", logger="runtime_narrative.analyzers.ollama"):
+        with patch("runtime_narrative.analyzers.ollama.urlopen", side_effect=URLError("no route")):
+            result = analyzer.analyze_failure(**_KWARGS)
+    assert result is None
+    assert any("no LLM analysis" in record.message for record in caplog.records)
+    assert any("12.0" in record.message for record in caplog.records)
+
+
+def test_llm_analyzer_logs_warning_on_malformed_response(caplog):
+    body = b"not json at all"
+    analyzer = LLMFailureAnalyzer(model="gpt-4", endpoint="http://localhost/v1/chat/completions")
+    with caplog.at_level("WARNING", logger="runtime_narrative.analyzers.ollama"):
+        with patch("runtime_narrative.analyzers.ollama.urlopen", return_value=_mock_http_response(body)):
+            result = analyzer.analyze_failure(**_KWARGS)
+    assert result is None
+    assert any("no LLM analysis" in record.message for record in caplog.records)

{runtime_narrative-1.5.2 → runtime_narrative-1.5.3}/tests/test_anthropic_analyzer.py

@@ -132,3 +132,31 @@ def test_parse_response_valid_json() -> None:
 def test_parse_response_fallback() -> None:
     result = _make_analyzer()._parse_response("plain text")
     assert result == "plain text"
+
+
+def test_default_timeout_falls_back_to_thirty_seconds(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("RUNTIME_NARRATIVE_ANALYZER_TIMEOUT_SECONDS", raising=False)
+    assert _make_analyzer().timeout_seconds == 30.0
+
+
+def test_default_timeout_reads_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("RUNTIME_NARRATIVE_ANALYZER_TIMEOUT_SECONDS", "45")
+    assert _make_analyzer().timeout_seconds == 45.0
+
+
+def test_explicit_timeout_overrides_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("RUNTIME_NARRATIVE_ANALYZER_TIMEOUT_SECONDS", "45")
+    assert _make_analyzer(timeout_seconds=5.0).timeout_seconds == 5.0
+
+
+def test_analyze_failure_logs_warning_on_exception(caplog: pytest.LogCaptureFixture) -> None:
+    mock_client = mock.MagicMock()
+    mock_client.messages.create.side_effect = Exception("network error")
+
+    with mock.patch.object(_anthropic_mod, "_anthropic") as patched:
+        patched.Anthropic.return_value = mock_client
+        with caplog.at_level("WARNING", logger="runtime_narrative.analyzers.anthropic"):
+            result = _make_analyzer().analyze_failure(**_CALL_KWARGS)
+
+    assert result is None
+    assert any("no LLM analysis" in record.message for record in caplog.records)