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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runtime-narrative
-Version: 1.3.0
+Version: 1.5.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
@@ -234,6 +234,55 @@ with story("GET /api/call") as runtime:
 
 ---
 
+## Rich logs to a file, and no more flooded polling loops
+
+`ConsoleRenderer` writes its colored, human-readable output to any file-like object, not just the terminal — so the same troubleshooting-friendly narrative can land in a log file alongside the structured JSON stream:
+
+```python
+with open("narrative.log.txt", "a", encoding="utf-8") as log_file:
+    with story("Import Pipeline", renderers=[ConsoleRenderer(output=log_file), JsonRenderer("narrative.log")]):
+        ...
+```
+
+Every auto-instrumentation entry point (FastAPI/Starlette middleware, Django middleware, Celery, gRPC interceptors) picks this up automatically via two environment variables, with no code changes:
+
+```bash
+RUNTIME_NARRATIVE_RICH_LOG_FILE=/var/log/app/narrative.log.txt   # rich console output also goes here
+RUNTIME_NARRATIVE_RICH_LOG_CONSOLE=0                             # optional: stop echoing it to the terminal too
+```
+
+Long-running, poll-heavy stages (status checks every couple of seconds during a big upload or pipeline run) no longer flood the log either. `CoalescingRenderer` wraps any other renderer and collapses a run of identical back-to-back stages into one summary line — total call count and total time, not one line per poll:
+
+```python
+from runtime_narrative import ConsoleRenderer, CoalescingRenderer
+
+with story("Process Upload", renderers=[CoalescingRenderer(ConsoleRenderer())]):
+    for _ in range(45):
+        with stage("Check Pipeline Status"):
+            poll()
+```
+
+```
+[abcdef] ▶ Stage started: Check Pipeline Status
+[abcdef] ✔ Stage completed: Check Pipeline Status (2.010s)
+[abcdef] ▶ Stage started: Check Pipeline Status
+[abcdef] ✔ Stage completed: Check Pipeline Status (2.005s)
+[abcdef] 'Check Pipeline Status' repeated 43 more times (45 total) over 90.400s (avg 2.009s/call)
+```
+
+Every `ConsoleRenderer` line also carries a `YYYY-MM-DD HH:MM:SS.mmm` timestamp, and the module that opened a story or stage — auto-detected with a single cheap frame lookup, no stack walking — shown once on `Story started` and again only when a stage transitions to a different module, so multi-module workflows stay traceable without repeating the tag on every line:
+
+```
+2026-07-03 12:03:41.208 [abcdef] ▶ Story started: Process Upload (app.routes.upload)
+2026-07-03 12:03:41.209 [abcdef]   ▶ Stage started: Validate Input (app.validators)
+2026-07-03 12:03:41.210 [abcdef]   ✔ Stage completed: Validate Input (0.001s)
+2026-07-03 12:03:41.211 [abcdef]   ▶ Stage started: Insert Record (app.db)
+```
+
+Run: `uv run python examples/colorful_errors_and_emojis.py` — full reference: [WIKI §10.1](WIKI.md#101-consolerenderer), [§10.1b](WIKI.md#101b-coalescingrenderer)
+
+---
+
 ## 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.
@@ -244,7 +293,7 @@ Everything below works the same way in every context (sync/async, decorators, au
 | Auto-instrumentation | `@narrative_class`, `@no_stage`, `instrument_module()`, `auto_instrument()` — instrument classes/modules with zero call-site changes | [WIKI §8](WIKI.md#8-auto-instrumentation) |
 | Failure diagnostics | Lean/rich modes, production traceback caps, secret redaction, `FailureDiagnosticsConfig` | [WIKI §9](WIKI.md#9-failure-diagnostics) |
 | Failure analyzers | `OllamaFailureAnalyzer`, `LLMFailureAnalyzer`, `AnthropicFailureAnalyzer`, `DeduplicatingAnalyzer`, `background_analysis=True` | [WIKI §9](WIKI.md#9-failure-diagnostics), [§16](WIKI.md#16-background-analysis) |
-| Renderers | `ConsoleRenderer`, `JsonRenderer`/`RotatingJsonRenderer`, `HtmlReportRenderer`, `SqliteStoryRenderer`, `OtelRenderer`/`OtelLogRenderer`/`OtelMetricsRenderer`, `PrometheusRenderer`, `AlertRoutingRenderer`, `FilteredRenderer` | [WIKI §10](WIKI.md#10-renderers) |
+| Renderers | `ConsoleRenderer` (optional file `output=`), `JsonRenderer`/`RotatingJsonRenderer`, `HtmlReportRenderer`, `SqliteStoryRenderer`, `OtelRenderer`/`OtelLogRenderer`/`OtelMetricsRenderer`, `PrometheusRenderer`, `AlertRoutingRenderer`, `FilteredRenderer`, `CoalescingRenderer` | [WIKI §10](WIKI.md#10-renderers) |
 | Framework integrations | FastAPI/Starlette middleware, Django ASGI/WSGI middleware, Celery task base class, gRPC interceptors | [WIKI §11](WIKI.md#11-framework-integrations) |
 | Async task groups | `NarrativeTaskGroup` — concurrent `asyncio` tasks under one shared story | [WIKI §12](WIKI.md#12-async-task-groups) |
 | Persistence & CLI | `SqliteStoryRenderer` + `runtime-narrative failures` / `runtime-narrative story <id>` | [WIKI §13](WIKI.md#13-sqlite-persistence-and-cli) |
@@ -325,6 +374,8 @@ Every script under `examples/` is runnable as-is: `uv run python examples/<name>
 | `RUNTIME_NARRATIVE_ALLOW_RICH_IN_PRODUCTION` | `1`, `true` | off | Bypass production safeguard; allow rich diagnostics in production |
 | `RUNTIME_NARRATIVE_MODEL` | model name string | — | Default model for `AnthropicFailureAnalyzer`; also used by example scripts for `OllamaFailureAnalyzer` / `LLMFailureAnalyzer` |
 | `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-1.3.0 → runtime_narrative-1.5.0}/README.md

@@ -175,6 +175,55 @@ with story("GET /api/call") as runtime:
 
 ---
 
+## Rich logs to a file, and no more flooded polling loops
+
+`ConsoleRenderer` writes its colored, human-readable output to any file-like object, not just the terminal — so the same troubleshooting-friendly narrative can land in a log file alongside the structured JSON stream:
+
+```python
+with open("narrative.log.txt", "a", encoding="utf-8") as log_file:
+    with story("Import Pipeline", renderers=[ConsoleRenderer(output=log_file), JsonRenderer("narrative.log")]):
+        ...
+```
+
+Every auto-instrumentation entry point (FastAPI/Starlette middleware, Django middleware, Celery, gRPC interceptors) picks this up automatically via two environment variables, with no code changes:
+
+```bash
+RUNTIME_NARRATIVE_RICH_LOG_FILE=/var/log/app/narrative.log.txt   # rich console output also goes here
+RUNTIME_NARRATIVE_RICH_LOG_CONSOLE=0                             # optional: stop echoing it to the terminal too
+```
+
+Long-running, poll-heavy stages (status checks every couple of seconds during a big upload or pipeline run) no longer flood the log either. `CoalescingRenderer` wraps any other renderer and collapses a run of identical back-to-back stages into one summary line — total call count and total time, not one line per poll:
+
+```python
+from runtime_narrative import ConsoleRenderer, CoalescingRenderer
+
+with story("Process Upload", renderers=[CoalescingRenderer(ConsoleRenderer())]):
+    for _ in range(45):
+        with stage("Check Pipeline Status"):
+            poll()
+```
+
+```
+[abcdef] ▶ Stage started: Check Pipeline Status
+[abcdef] ✔ Stage completed: Check Pipeline Status (2.010s)
+[abcdef] ▶ Stage started: Check Pipeline Status
+[abcdef] ✔ Stage completed: Check Pipeline Status (2.005s)
+[abcdef] 'Check Pipeline Status' repeated 43 more times (45 total) over 90.400s (avg 2.009s/call)
+```
+
+Every `ConsoleRenderer` line also carries a `YYYY-MM-DD HH:MM:SS.mmm` timestamp, and the module that opened a story or stage — auto-detected with a single cheap frame lookup, no stack walking — shown once on `Story started` and again only when a stage transitions to a different module, so multi-module workflows stay traceable without repeating the tag on every line:
+
+```
+2026-07-03 12:03:41.208 [abcdef] ▶ Story started: Process Upload (app.routes.upload)
+2026-07-03 12:03:41.209 [abcdef]   ▶ Stage started: Validate Input (app.validators)
+2026-07-03 12:03:41.210 [abcdef]   ✔ Stage completed: Validate Input (0.001s)
+2026-07-03 12:03:41.211 [abcdef]   ▶ Stage started: Insert Record (app.db)
+```
+
+Run: `uv run python examples/colorful_errors_and_emojis.py` — full reference: [WIKI §10.1](WIKI.md#101-consolerenderer), [§10.1b](WIKI.md#101b-coalescingrenderer)
+
+---
+
 ## 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.
@@ -185,7 +234,7 @@ Everything below works the same way in every context (sync/async, decorators, au
 | Auto-instrumentation | `@narrative_class`, `@no_stage`, `instrument_module()`, `auto_instrument()` — instrument classes/modules with zero call-site changes | [WIKI §8](WIKI.md#8-auto-instrumentation) |
 | Failure diagnostics | Lean/rich modes, production traceback caps, secret redaction, `FailureDiagnosticsConfig` | [WIKI §9](WIKI.md#9-failure-diagnostics) |
 | Failure analyzers | `OllamaFailureAnalyzer`, `LLMFailureAnalyzer`, `AnthropicFailureAnalyzer`, `DeduplicatingAnalyzer`, `background_analysis=True` | [WIKI §9](WIKI.md#9-failure-diagnostics), [§16](WIKI.md#16-background-analysis) |
-| Renderers | `ConsoleRenderer`, `JsonRenderer`/`RotatingJsonRenderer`, `HtmlReportRenderer`, `SqliteStoryRenderer`, `OtelRenderer`/`OtelLogRenderer`/`OtelMetricsRenderer`, `PrometheusRenderer`, `AlertRoutingRenderer`, `FilteredRenderer` | [WIKI §10](WIKI.md#10-renderers) |
+| Renderers | `ConsoleRenderer` (optional file `output=`), `JsonRenderer`/`RotatingJsonRenderer`, `HtmlReportRenderer`, `SqliteStoryRenderer`, `OtelRenderer`/`OtelLogRenderer`/`OtelMetricsRenderer`, `PrometheusRenderer`, `AlertRoutingRenderer`, `FilteredRenderer`, `CoalescingRenderer` | [WIKI §10](WIKI.md#10-renderers) |
 | Framework integrations | FastAPI/Starlette middleware, Django ASGI/WSGI middleware, Celery task base class, gRPC interceptors | [WIKI §11](WIKI.md#11-framework-integrations) |
 | Async task groups | `NarrativeTaskGroup` — concurrent `asyncio` tasks under one shared story | [WIKI §12](WIKI.md#12-async-task-groups) |
 | Persistence & CLI | `SqliteStoryRenderer` + `runtime-narrative failures` / `runtime-narrative story <id>` | [WIKI §13](WIKI.md#13-sqlite-persistence-and-cli) |
@@ -266,6 +315,8 @@ Every script under `examples/` is runnable as-is: `uv run python examples/<name>
 | `RUNTIME_NARRATIVE_ALLOW_RICH_IN_PRODUCTION` | `1`, `true` | off | Bypass production safeguard; allow rich diagnostics in production |
 | `RUNTIME_NARRATIVE_MODEL` | model name string | — | Default model for `AnthropicFailureAnalyzer`; also used by example scripts for `OllamaFailureAnalyzer` / `LLMFailureAnalyzer` |
 | `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-1.3.0 → runtime_narrative-1.5.0}/pyproject.toml

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

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

@@ -1,4 +1,4 @@
-__version__ = "1.3.0"
+__version__ = "1.5.0"
 
 from .analyzers import FailureAnalyzer, LLMFailureAnalyzer, OllamaFailureAnalyzer, DeduplicatingAnalyzer
 from .context import has_active_story
@@ -19,6 +19,7 @@ from .logging_bridge import NarrativeLogHandler
 from .outcome import http_outcome
 from .renderer.console import ConsoleRenderer
 from .renderer.filter_renderer import FilteredRenderer
+from .renderer.coalescing_renderer import CoalescingRenderer
 from .renderer.json_renderer import JsonRenderer, RotatingJsonRenderer
 from .stage import stage
 from .story import story, StoryRuntime
@@ -106,6 +107,7 @@ __all__ = [
     "RuntimeNarrativeMiddleware",
     "ConsoleRenderer",
     "FilteredRenderer",
+    "CoalescingRenderer",
     "JsonRenderer",
     "RotatingJsonRenderer",
     "OtelRenderer",

{runtime_narrative-1.3.0 → runtime_narrative-1.5.0}/runtime_narrative/celery.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
-import sys
 from typing import Any, Sequence
 
+from .renderer_defaults import default_renderers
 from .story import story
 
 try:
@@ -15,14 +15,6 @@ except ImportError:
     _TaskBase = object
 
 
-def _default_renderers() -> tuple:
-    if getattr(sys.stdout, "isatty", lambda: False)():
-        from .renderer.console import ConsoleRenderer
-        return (ConsoleRenderer(),)
-    from .renderer.json_renderer import JsonRenderer
-    return (JsonRenderer(),)
-
-
 class NarrativeTask(_TaskBase):  # type: ignore[valid-type,misc]
     abstract = True
 
@@ -47,7 +39,7 @@ class NarrativeTask(_TaskBase):  # type: ignore[valid-type,misc]
         request = getattr(self, "request", None)
         task_id = getattr(request, "id", None) or "unknown"
         story_name = f"{self.name} [task_id={task_id}]"
-        renderers = self.narrative_renderers if self.narrative_renderers is not None else _default_renderers()
+        renderers = self.narrative_renderers if self.narrative_renderers is not None else default_renderers()
         with story(
             story_name,
             renderers=renderers,

{runtime_narrative-1.3.0 → runtime_narrative-1.5.0}/runtime_narrative/decorators.py

@@ -41,6 +41,10 @@ def runtime_narrative_story(
             "failure_diagnostics": failure_diagnostics,
             "allow_rich_in_production": allow_rich_in_production,
             "app_roots": app_roots,
+            # Without this, story() would auto-detect the caller's frame as
+            # this decorator's own wrapper closure, reporting every decorated
+            # story as "runtime_narrative.decorators" instead of func's module.
+            "module": func.__module__,
         }
 
         if inspect.iscoroutinefunction(func):
@@ -72,14 +76,14 @@ def runtime_narrative_stage(name: str | None = None) -> Callable[[F], F]:
 
             @wraps(func)
             async def async_wrapper(*args: Any, **kwargs: Any):
-                async with stage(stage_name):
+                async with stage(stage_name, module=func.__module__):
                     return await func(*args, **kwargs)
 
             return async_wrapper  # type: ignore[return-value]
 
         @wraps(func)
         def sync_wrapper(*args: Any, **kwargs: Any):
-            with stage(stage_name):
+            with stage(stage_name, module=func.__module__):
                 return func(*args, **kwargs)
 
         return sync_wrapper  # type: ignore[return-value]

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

@@ -12,6 +12,7 @@ class StoryStarted:
     timestamp: datetime
     parent_story_id: str | None = None
     root_story_id: str = ""
+    module: str = ""
 
 
 @dataclass
@@ -23,6 +24,7 @@ class StageStarted:
     parent_stage_name: str | None = None
     story_name: str = ""
     root_story_id: str = ""
+    module: str = ""
 
 
 @dataclass

{runtime_narrative-1.3.0 → runtime_narrative-1.5.0}/runtime_narrative/grpc_interceptor.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
-import sys
 from typing import Any, Callable, Sequence
 
+from .renderer_defaults import default_renderers
 from .story import story
 
 try:
@@ -24,17 +24,9 @@ except ImportError:
     _AsyncBase = object
 
 
-def _default_renderers() -> tuple:
-    if getattr(sys.stdout, "isatty", lambda: False)():
-        from .renderer.console import ConsoleRenderer
-        return (ConsoleRenderer(),)
-    from .renderer.json_renderer import JsonRenderer
-    return (JsonRenderer(),)
-
-
 def _story_kwargs(interceptor: Any) -> dict:
     return {
-        "renderers": interceptor._renderers or _default_renderers(),
+        "renderers": interceptor._renderers or default_renderers(),
         "failure_analyzer": interceptor._failure_analyzer,
         "diagnostics_config": interceptor._diagnostics_config,
         "runtime_environment": interceptor._runtime_environment,

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

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import sys
 from typing import Any, Callable, Sequence
 
 from starlette.middleware.base import BaseHTTPMiddleware
@@ -9,6 +8,7 @@ from starlette.responses import Response
 
 from .diagnostics import FailureDiagnosticsConfig
 from .outcome import http_outcome
+from .renderer_defaults import default_renderers
 from .story import story
 
 try:
@@ -19,17 +19,6 @@ except ImportError:
     _OTEL_PROPAGATION_AVAILABLE = False
 
 
-def _default_middleware_renderers() -> tuple:
-    """Return ConsoleRenderer when attached to a real terminal, JsonRenderer otherwise."""
-    if getattr(sys.stdout, "isatty", lambda: False)():
-        from .renderer.console import ConsoleRenderer
-        return (ConsoleRenderer(),)
-    from .renderer.json_renderer import JsonRenderer
-    return (JsonRenderer(),)
-
-
-
-
 class RuntimeNarrativeMiddleware(BaseHTTPMiddleware):
     """
     FastAPI/Starlette middleware that wraps every HTTP request in a runtime_narrative story.
@@ -40,6 +29,8 @@ class RuntimeNarrativeMiddleware(BaseHTTPMiddleware):
     When no ``renderers`` are passed, the middleware auto-selects:
     - ``ConsoleRenderer`` if ``sys.stdout`` is a real TTY (local dev server)
     - ``JsonRenderer`` otherwise (production, Docker, CI — any non-interactive environment)
+    - Set ``RUNTIME_NARRATIVE_RICH_LOG_FILE=<path>`` to also (or instead, combined with
+      ``RUNTIME_NARRATIVE_RICH_LOG_CONSOLE=0``) write the human-readable narrative to a file.
 
     Usage::
 
@@ -79,7 +70,7 @@ class RuntimeNarrativeMiddleware(BaseHTTPMiddleware):
         skip_if: Callable[[Request], bool] | None = None,
     ):
         super().__init__(app)
-        self._renderers = tuple(renderers) if renderers is not None else _default_middleware_renderers()
+        self._renderers = tuple(renderers) if renderers is not None else default_renderers()
         self._failure_analyzer = failure_analyzer
         self._diagnostics_config = diagnostics_config
         self._runtime_environment = runtime_environment

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

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
-import sys
 from typing import Any, Sequence
 
 from .diagnostics import FailureDiagnosticsConfig
 from .outcome import http_outcome
+from .renderer_defaults import default_renderers
 from .story import story
 
 try:
@@ -14,14 +14,6 @@ except ImportError:
     _DJANGO_AVAILABLE = False
 
 
-def _default_renderers() -> tuple:
-    if getattr(sys.stdout, "isatty", lambda: False)():
-        from .renderer.console import ConsoleRenderer
-        return (ConsoleRenderer(),)
-    from .renderer.json_renderer import JsonRenderer
-    return (JsonRenderer(),)
-
-
 class RuntimeNarrativeDjangoMiddleware:
     async_capable = True
     sync_capable = False
@@ -45,7 +37,7 @@ class RuntimeNarrativeDjangoMiddleware:
                 "Install it with: pip install django"
             )
         self.get_response = get_response
-        self._renderers = tuple(renderers) if renderers is not None else _default_renderers()
+        self._renderers = tuple(renderers) if renderers is not None else default_renderers()
         self._failure_analyzer = failure_analyzer
         self._diagnostics_config = diagnostics_config
         self._runtime_environment = runtime_environment
@@ -97,7 +89,7 @@ class RuntimeNarrativeDjangoSyncMiddleware:
                 "Install it with: pip install django"
             )
         self.get_response = get_response
-        self._renderers = tuple(renderers) if renderers is not None else _default_renderers()
+        self._renderers = tuple(renderers) if renderers is not None else default_renderers()
         self._failure_analyzer = failure_analyzer
         self._diagnostics_config = diagnostics_config
         self._runtime_environment = runtime_environment

runtime_narrative-1.5.0/runtime_narrative/renderer/coalescing_renderer.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+from ..events import LogRecorded
+
+
+class CoalescingRenderer:
+    """Wraps another renderer, collapsing a run of identical back-to-back stages --
+    e.g. a "poll status every 2s until done" loop -- into a single summary line
+    instead of flooding the log with one StageStarted/StageCompleted pair per
+    iteration.
+
+    The wrapped renderer still sees the first `threshold` occurrences of a
+    repeated (story_id, stage_name) pair in full, so the pattern is visible as
+    it starts. From the next occurrence on, StageStarted/StageCompleted for
+    that stage are suppressed and accumulated instead of forwarded. As soon as
+    a different event arrives for that story (a different stage, a failure, or
+    the story completing), the run is flushed as one LogRecorded summary line
+    -- reporting the total call count and total time spent in that stage --
+    forwarded through the wrapped renderer before the triggering event.
+
+    Only wrap the human-facing renderer(s) with this (typically ConsoleRenderer).
+    Renderers meant for full-fidelity machine consumption -- JsonRenderer,
+    SqliteStoryRenderer, OtelRenderer, and friends -- should keep receiving
+    every real event and should NOT be wrapped.
+
+    Example -- a status-polling loop inside one long-running story::
+
+        with story("Process Upload", renderers=[CoalescingRenderer(ConsoleRenderer())]):
+            with stage("Upload File"):
+                ...
+            while not done:
+                with stage("Check Pipeline Status"):
+                    done = check_status()
+                time.sleep(2)
+
+    Only the first two (default `threshold`) status checks print a
+    StageStarted/StageCompleted pair; the rest are folded into one line like::
+
+        'Check Pipeline Status' repeated 41 more times (43 total) over 84.200s (avg 1.958s/call)
+
+    Limitations: a run is keyed on (story_id, stage_name) alone, without regard
+    to nesting -- a differently named stage nested *inside* the repeated one
+    (e.g. a "Parse Response" sub-stage on every poll) counts as "a different
+    stage" and ends the run early. Keep the polling loop's stage as a single,
+    unnested stage per iteration to get full coalescing. Also, if the stage
+    that's mid-run raises before completing, that final in-flight call's
+    duration is not included in the summary total (though it is still counted).
+    """
+
+    def __init__(self, renderer: Any, *, threshold: int = 2) -> None:
+        if threshold < 1:
+            raise ValueError("threshold must be >= 1")
+        self._renderer = renderer
+        self._threshold = threshold
+        self._runs: dict[str, dict[str, Any]] = {}
+        if inspect.iscoroutinefunction(getattr(renderer, "handle", None)):
+            self.handle = self._handle_async
+        else:
+            self.handle = self._handle_sync
+
+    # ------------------------------------------------------------------
+    # Shared run-tracking logic (pure, no I/O).
+    # ------------------------------------------------------------------
+
+    def _track_stage_started(self, event: Any) -> tuple[Any | None, bool]:
+        """Returns (summary_event_to_flush_first_or_None, should_forward_this_event)."""
+        story_id = event.story_id
+        stage_name = event.stage_name
+        run = self._runs.get(story_id)
+
+        if run is not None and run["stage_name"] == stage_name:
+            run["count"] += 1
+            return None, run["count"] <= self._threshold
+
+        summary = self._pop_summary(story_id)
+        self._runs[story_id] = {
+            "stage_name": stage_name,
+            "count": 1,
+            "total_duration": 0.0,
+            "first_started_at": event.timestamp,
+            "story_name": event.story_name,
+            "root_story_id": event.root_story_id or story_id,
+        }
+        return summary, True
+
+    def _track_stage_completed(self, event: Any) -> tuple[Any | None, bool]:
+        story_id = event.story_id
+        run = self._runs.get(story_id)
+        if run is None or run["stage_name"] != event.stage_name:
+            # Unbalanced (shouldn't normally happen) -- forward as-is.
+            return None, True
+        run["total_duration"] += event.duration_seconds
+        return None, run["count"] <= self._threshold
+
+    def _pop_summary(self, story_id: str) -> Any | None:
+        run = self._runs.pop(story_id, None)
+        if run is None or run["count"] <= self._threshold:
+            return None
+        suppressed = run["count"] - self._threshold
+        avg = run["total_duration"] / run["count"] if run["count"] else 0.0
+        return LogRecorded(
+            story_id=story_id,
+            story_name=run["story_name"],
+            root_story_id=run["root_story_id"],
+            stage_name=run["stage_name"],
+            level="INFO",
+            logger_name="runtime_narrative.coalesce",
+            message=(
+                f"{run['stage_name']!r} repeated {suppressed} more time"
+                f"{'s' if suppressed != 1 else ''} ({run['count']} total) "
+                f"over {run['total_duration']:.3f}s (avg {avg:.3f}s/call)"
+            ),
+            timestamp=run["first_started_at"],
+        )
+
+    def _flush(self, story_id: str) -> Any | None:
+        return self._pop_summary(story_id)
+
+    # ------------------------------------------------------------------
+    # Sync / async dispatch
+    # ------------------------------------------------------------------
+
+    def _handle_sync(self, event: object) -> None:
+        event_name = event.__class__.__name__
+        story_id = getattr(event, "story_id", None)
+
+        if event_name == "StageStarted":
+            summary, forward = self._track_stage_started(event)
+            if summary is not None:
+                self._renderer.handle(summary)
+            if forward:
+                self._renderer.handle(event)
+            return
+
+        if event_name == "StageCompleted":
+            summary, forward = self._track_stage_completed(event)
+            if summary is not None:
+                self._renderer.handle(summary)
+            if forward:
+                self._renderer.handle(event)
+            return
+
+        if story_id is not None:
+            summary = self._flush(story_id)
+            if summary is not None:
+                self._renderer.handle(summary)
+        self._renderer.handle(event)
+
+    async def _handle_async(self, event: object) -> None:
+        event_name = event.__class__.__name__
+        story_id = getattr(event, "story_id", None)
+
+        if event_name == "StageStarted":
+            summary, forward = self._track_stage_started(event)
+            if summary is not None:
+                await self._renderer.handle(summary)
+            if forward:
+                await self._renderer.handle(event)
+            return
+
+        if event_name == "StageCompleted":
+            summary, forward = self._track_stage_completed(event)
+            if summary is not None:
+                await self._renderer.handle(summary)
+            if forward:
+                await self._renderer.handle(event)
+            return
+
+        if story_id is not None:
+            summary = self._flush(story_id)
+            if summary is not None:
+                await self._renderer.handle(summary)
+        await self._renderer.handle(event)
+
+
+__all__ = ["CoalescingRenderer"]