flowra 0.0.23.dev28__tar.gz → 0.0.23.dev31__tar.gz

{flowra-0.0.23.dev28 → flowra-0.0.23.dev31}/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+### Added
+- **`AnthropicCacheNonTransientTools`** — caching bundle for the last non-transient
+  tool definition. Mirrors existing `NonTransient` bundles for system messages and
+  messages.
+- **`ANTHROPIC_CACHE_NON_TRANSIENT`** preset — composite of
+  `ANTHROPIC_CACHE_NON_TRANSIENT_SYSTEM_MESSAGES` +
+  `ANTHROPIC_CACHE_NON_TRANSIENT_TOOLS` + `ANTHROPIC_CACHE_NON_TRANSIENT_MESSAGES`.
+- **Pre-instantiated constants** for all individual caching bundles:
+  `ANTHROPIC_CACHE_ALL_MESSAGES`, `ANTHROPIC_CACHE_ALL_SYSTEM_MESSAGES`,
+  `ANTHROPIC_CACHE_ALL_TOOLS`, `ANTHROPIC_CACHE_HISTORY_MESSAGES`,
+  `ANTHROPIC_CACHE_NON_TRANSIENT_MESSAGES`, `ANTHROPIC_CACHE_NON_TRANSIENT_SYSTEM_MESSAGES`,
+  `ANTHROPIC_CACHE_NON_TRANSIENT_TOOLS`. No need to instantiate classes manually.
+- **`InMemorySessionStorage` snapshot** — `storage.snapshot()` returns an
+  `InMemorySessionSnapshot` (frozen dataclass) with a deep copy of all data.
+  `InMemorySessionStorage(snapshot)` creates a new storage from a snapshot.
+  Enables cloning: `InMemorySessionStorage(storage.snapshot())`.
+- **External tracing context integration** — both MLflow and OTel integrations now
+  detect and attach to existing external spans. If flowra is called inside
+  `with mlflow.start_span()` or `tracer.start_as_current_span()`, flowra's spans
+  become children of the external span.
+- **Tracing examples** — 7 new examples demonstrating all MLflow/OTel tracing
+  combinations: nested external spans, both independently, dual export, and mixed
+  setups. Console OTel span tree visualizer (`otel_visualize.py`).
+
+### Changed
+- **NonTransient caching logic**: `NonTransient` bundles now cache the last
+  non-transient element in the non-transient prefix — walk forward and stop at
+  the first transient element. Previously they searched for the last non-transient
+  element overall, which could skip over transient content in the middle.
+
 ## [0.0.22] - 2026-03-23
 
 ### Changed

{flowra-0.0.23.dev28 → flowra-0.0.23.dev31}/Makefile

@@ -69,9 +69,31 @@ race:
 mlflow-demo:
 	uv run python examples/mlflow_demo.py $(args)
 
+mlflow-nested-demo:
+	uv run python examples/mlflow_nested_demo.py $(args)
+
 otel-demo:
 	uv run python examples/otel_demo.py $(args)
 
+otel-nested-demo:
+	uv run python examples/otel_nested_demo.py $(args)
+
+otel-nested-visualize:
+	uv run python examples/otel_nested_demo.py 2>&1 | uv run python examples/otel_visualize.py
+
+otel-jaeger-demo:
+	uv run python examples/otel_jaeger_demo.py $(args)
+
+# ── MLflow + OTel combinations ──────────────────────────────────────
+mlflow-otel-both:
+	uv run python examples/mlflow_otel_both_demo.py $(args)
+
+mlflow-dual-export:
+	uv run python examples/mlflow_dual_export_demo.py $(args)
+
+mlflow-otel-nested:
+	uv run python examples/mlflow_otel_nested_demo.py $(args)
+
 escalation:
 	uv run python examples/escalation.py $(if $(fast_model),--fast-model $(fast_model)) $(if $(smart_model),--smart-model $(smart_model)) $(if $(message),--message "$(message)") $(args)
 

{flowra-0.0.23.dev28 → flowra-0.0.23.dev31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowra
-Version: 0.0.23.dev28
+Version: 0.0.23.dev31
 Summary: Flowra — flow infrastructure for building stateful LLM agents
 Project-URL: Repository, https://github.com/anna-money/flowra
 Project-URL: Changelog, https://github.com/anna-money/flowra/blob/master/CHANGELOG.md

{flowra-0.0.23.dev28 → flowra-0.0.23.dev31}/context7.json

@@ -103,8 +103,8 @@
 
     "PROMPT CACHING: handled via composable hook bundles that subscribe to PrepareLLMRequestEvent and set provider-specific cache hints via extra on blocks/tools",
     "PrepareLLMRequestEvent: hook event emitted after LLMRequest is built but before the LLM call. Mutable field: request (LLMRequest). Use to modify messages, tools, or add cache control",
-    "flowra.lib.anthropic: Anthropic provider extensions (caching + tool search). Caching: pre-instantiated constants ANTHROPIC_CACHE_ALL_SYSTEM_MESSAGES, ANTHROPIC_CACHE_NON_TRANSIENT_SYSTEM_MESSAGES, ANTHROPIC_CACHE_ALL_TOOLS, ANTHROPIC_CACHE_ALL_MESSAGES, ANTHROPIC_CACHE_NON_TRANSIENT_MESSAGES, ANTHROPIC_CACHE_HISTORY_MESSAGES. Composite presets: ANTHROPIC_CACHE_ALL, ANTHROPIC_CACHE_SESSION. Tool search: AnthropicToolSearch(variant='bm25'|'regex', predicate=...) — defers tool loading, adds server-side search tool. Install via ext.install(hooks)",
-    "transient hint: blocks/messages with transient=True are (1) skipped by NonTransient caching bundles and (2) auto-filtered from ChatAgent session history",
+    "flowra.lib.anthropic: Anthropic provider extensions (caching + tool search). Caching: pre-instantiated constants ANTHROPIC_CACHE_ALL_SYSTEM_MESSAGES, ANTHROPIC_CACHE_NON_TRANSIENT_SYSTEM_MESSAGES, ANTHROPIC_CACHE_ALL_TOOLS, ANTHROPIC_CACHE_NON_TRANSIENT_TOOLS, ANTHROPIC_CACHE_ALL_MESSAGES, ANTHROPIC_CACHE_NON_TRANSIENT_MESSAGES, ANTHROPIC_CACHE_HISTORY_MESSAGES. Composite presets: ANTHROPIC_CACHE_ALL, ANTHROPIC_CACHE_SESSION, ANTHROPIC_CACHE_NON_TRANSIENT. Tool search: AnthropicToolSearch(variant='bm25'|'regex', predicate=...) — defers tool loading, adds server-side search tool. Install via ext.install(hooks)",
+    "transient hint: blocks/messages/tools with transient=True are (1) skipped by NonTransient caching bundles (which cache the non-transient prefix — stop at first transient) and (2) auto-filtered from ChatAgent session history",
     "Anthropic extra passthrough: AnthropicVertexProvider merges block.extra into output dicts (**block.extra), so cache_control and other Anthropic-specific fields pass through directly",
 
     "CONFIG: LLMConfig(model, temperature, max_tokens, stop_sequences, additional_config) configures LLM calls",
@@ -114,14 +114,15 @@
     "Import ChatAgent: from flowra.lib.chat import ChatAgent, ChatConfig, ChatResult, ChatSpec, SaveHistoryEvent",
     "Import LLMConfig: from flowra.lib import LLMConfig",
     "Import LLM types: from flowra.llm import LLMProvider, SystemMessage, TextBlock, Usage, TextDelta, ThinkingDelta, ContentComplete",
-    "Import agent runtime: from flowra.agent import AgentRuntime, FileSessionStorage, InMemorySessionStorage",
+    "Import agent runtime: from flowra.agent import AgentRuntime, FileSessionStorage, InMemorySessionSnapshot, InMemorySessionStorage",
+    "InMemorySessionStorage.snapshot() returns InMemorySessionSnapshot (frozen dataclass with execution and node_states). InMemorySessionStorage(snapshot) constructs a new storage from snapshot (deep copy). Clone: InMemorySessionStorage(storage.snapshot())",
     "Import tools: from flowra.tools import ToolRegistry, get_local_tool, tool, ToolErrorKind",
 
     "FlowingContextVar: from flowra.agent import FlowingContextVar. Typed variables that flow with agent execution. Engine manages lifecycle (fork/restore for sibling isolation, snapshot/apply for task inheritance). Used by tracing integrations for parent span tracking. Usage: my_var = FlowingContextVar[str | None]('my.var', default=None); my_var.get(); my_var.set('value')",
 
     "EXTENSIONS (flowra/ext/): optional integrations with external services. Each requires its own extra dependency",
-    "MLflow tracing: from flowra.ext.mlflow import install_mlflow_tracing. Requires flowra[mlflow]. Uses FlowingContextVar for parent tracking, MLflow set_span_in_context for W3C propagation. Creates MLflow traces with structured chat UI (CHAT_MODEL spans with OpenAI-format messages). Session support via session_id parameter. Usage: hooks = HookSubscription(); install_mlflow_tracing(hooks, experiment_name='my-exp', session_id='chat-123')",
-    "OpenTelemetry tracing: from flowra.ext.otel import install_otel_tracing. Requires flowra[otel]. Uses FlowingContextVar for parent tracking. Creates OTel spans with GenAI semantic conventions (gen_ai.operation.name, gen_ai.provider.name, gen_ai.usage.*, etc.). Users configure their own TracerProvider. Usage: install_otel_tracing(hooks, capture_content=False, session_id='chat-123')",
+    "MLflow tracing: from flowra.ext.mlflow import install_mlflow_tracing. Requires flowra[mlflow]. Uses FlowingContextVar for parent tracking, MLflow set_span_in_context for W3C propagation. Creates MLflow traces with structured chat UI (CHAT_MODEL spans with OpenAI-format messages). Session support via session_id parameter. Automatically integrates with external MLflow context (mlflow.get_current_active_span). Usage: hooks = HookSubscription(); install_mlflow_tracing(hooks, experiment_name='my-exp', session_id='chat-123')",
+    "OpenTelemetry tracing: from flowra.ext.otel import install_otel_tracing. Requires flowra[otel]. Uses FlowingContextVar for parent tracking. Creates OTel spans with GenAI semantic conventions (gen_ai.operation.name, gen_ai.provider.name, gen_ai.usage.*, etc.). Users configure their own TracerProvider. Automatically integrates with external OTel context (trace.get_current_span). Usage: install_otel_tracing(hooks, capture_content=False, session_id='chat-123')",
     "__preview__() protocol: objects implementing __preview__() -> str get clean text in MLflow trace list/session view instead of str(). Built-in: ChatSpec, ChatResult, ToolLoopSpec, ToolLoopResult. Custom specs/results can implement it for readable summaries in any tracing backend"
   ],
   "previousVersions": []

{flowra-0.0.23.dev28 → flowra-0.0.23.dev31}/docs/agents.md

@@ -135,6 +135,23 @@ if await runtime.has_pending_execution():
     result = await runtime.resume()
 ```
 
+### Cloning in-memory storage
+
+`InMemorySessionStorage` supports snapshotting — take a deep copy of all stored
+data and use it to create a new, independent storage:
+
+```python
+from flowra.agent import InMemorySessionStorage
+
+# After some agent runs have populated the storage...
+snapshot = storage.snapshot()          # deep-copy all data out
+cloned = InMemorySessionStorage(snapshot)  # deep-copy into new storage
+```
+
+This is useful for forking a session (e.g. branching a conversation) or
+inspecting storage contents. The snapshot is a frozen dataclass with `execution`
+and `node_states` fields.
+
 ## Dependency injection
 
 Agent constructors receive services by type matching. Some services are always

{flowra-0.0.23.dev28 → flowra-0.0.23.dev31}/docs/internal/agent.md

@@ -594,6 +594,26 @@ result = await runtime.run(agent=MyAgent, spec=spec)
 result = await runtime.resume()
 ```
 
+#### InMemorySessionStorage snapshot
+
+`InMemorySessionStorage` supports snapshotting for cloning and data inspection:
+
+```python
+from flowra.agent import InMemorySessionSnapshot, InMemorySessionStorage
+
+# Take a deep-copy snapshot of all stored data
+snapshot: InMemorySessionSnapshot = storage.snapshot()
+
+# Create a new storage from snapshot (deep copy)
+cloned = InMemorySessionStorage(snapshot)
+
+# Clone in one line
+cloned = InMemorySessionStorage(storage.snapshot())
+```
+
+`InMemorySessionSnapshot` is a frozen dataclass with `execution` and `node_states`
+fields — the complete contents of the storage.
+
 ---
 
 ## Internal modules (not public)

{flowra-0.0.23.dev28 → flowra-0.0.23.dev31}/docs/internal/ext/mlflow.md

@@ -39,6 +39,26 @@ MLflow's `set_span_in_context()` / `detach_span_from_context()` populate
 the MLflow context stack, enabling `update_current_trace()` for trace
 previews and W3C `traceparent` propagation for distributed tracing.
 
+## External context integration
+
+When no flowra parent exists (root of execution), handlers check for an
+external MLflow span via `mlflow.get_current_active_span()`. If found,
+flowra's root span becomes a child of the external span.
+
+This allows flowra to nest inside existing MLflow traces — e.g. when called
+from a `with mlflow.start_span()` block or a `@mlflow.trace`-decorated function:
+
+```python
+import mlflow
+
+with mlflow.start_span(name="my_business_logic"):
+    # flowra spans become children of "my_business_logic"
+    result = await runtime.run(agent=MyAgent, spec=MySpec(...))
+```
+
+Priority: internal flowra context (`FlowingContextVar`) > external MLflow context
+(`get_current_active_span()`). External context is only used at the root.
+
 ## Parameters
 
 ```python
@@ -110,8 +130,9 @@ uv run mlflow ui --port 5050
 # Open http://localhost:5050
 ```
 
-## Example
+## Examples
 
 ```bash
-make mlflow-demo
+make mlflow-demo            # basic MLflow tracing
+make mlflow-nested-demo     # external MLflow span wrapping flowra
 ```

{flowra-0.0.23.dev28 → flowra-0.0.23.dev31}/docs/internal/ext/otel.md

@@ -93,6 +93,29 @@ provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
 trace.set_tracer_provider(provider)
 ```
 
+## External context integration
+
+When no flowra parent exists (root of execution), `_start_span` checks for an
+external OTel span via `trace.get_current_span()`. If a recording span is found,
+flowra's root span becomes a child of the external span.
+
+This allows flowra to nest inside existing OTel traces — e.g. when called
+from a `tracer.start_as_current_span()` block:
+
+```python
+from opentelemetry import trace
+
+app_tracer = trace.get_tracer("my_app")
+
+with app_tracer.start_as_current_span("my_business_logic"):
+    # flowra spans become children of "my_business_logic"
+    result = await runtime.run(agent=MyAgent, spec=MySpec(...))
+```
+
+Priority: internal flowra context (`FlowingContextVar`) > external OTel context
+(`trace.get_current_span()`). External context is only used at the root.
+Non-recording spans (e.g. `INVALID_SPAN`) are ignored.
+
 ## Using with MLflow
 
 Both integrations can run side by side — they use independent `FlowingContextVar`
@@ -111,8 +134,11 @@ Alternatively, MLflow can export to OTel backends via dual export
 (`MLFLOW_TRACE_ENABLE_OTLP_DUAL_EXPORT=true`) — in that case you only need
 the MLflow integration.
 
-## Example
+## Examples
 
 ```bash
-make otel-demo
+make otel-demo              # basic OTel tracing (console)
+make otel-nested-demo       # external OTel span wrapping flowra (console)
+make otel-nested-visualize  # same, with tree visualization
+make otel-jaeger-demo       # external OTel span, exported to Jaeger
 ```

{flowra-0.0.23.dev28 → flowra-0.0.23.dev31}/docs/internal/ext/tracing-guide.md

@@ -148,6 +148,35 @@ This tells MLflow to use the global OTel `TracerProvider` instead of its own
 isolated one. All spans — from your web framework, from flowra, from any other
 OTel-instrumented library — appear in a single unified trace.
 
+## Integration with external tracing context
+
+Both MLflow and OTel integrations automatically detect and attach to an existing
+tracing context. If your application already creates spans before calling flowra,
+flowra's spans become children of the external span.
+
+- **MLflow:** detects via `mlflow.get_current_active_span()`
+- **OTel:** detects via `trace.get_current_span()` (ignores non-recording spans)
+
+This works in all setups:
+
+| Setup               | External MLflow span | External OTel span         |
+|---------------------|----------------------|----------------------------|
+| MLflow only         | Nested inside        | Not detected               |
+| OTel only           | Not detected         | Nested inside              |
+| Both independently  | MLflow: nested       | OTel: nested (independent) |
+| MLflow + OTel export| Nested inside        | Via MLflow's OTel layer    |
+
+Priority: internal flowra context > external context. External context is only
+used when there is no flowra parent (i.e. at the root of flowra's execution).
+
+```python
+# Example: external OTel span wrapping flowra with both tracing systems
+with app_tracer.start_as_current_span("business_workflow"):
+    # OTel integration: nests inside "business_workflow"
+    # MLflow integration: creates independent trace (no OTel awareness)
+    result = await runtime.run(agent=MyAgent, spec=MySpec(...))
+```
+
 ## Choosing the right setup
 
 ```

{flowra-0.0.23.dev28 → flowra-0.0.23.dev31}/docs/internal/lib/anthropic.md

@@ -28,10 +28,11 @@ All bundles are pre-instantiated constants (no need to call constructors):
 | Constant                                        | What it caches                                                                           |
 |-------------------------------------------------|------------------------------------------------------------------------------------------|
 | `ANTHROPIC_CACHE_ALL_SYSTEM_MESSAGES`           | Last block of the last system message                                                    |
-| `ANTHROPIC_CACHE_NON_TRANSIENT_SYSTEM_MESSAGES` | Last non-transient block of the last non-transient system message                        |
+| `ANTHROPIC_CACHE_NON_TRANSIENT_SYSTEM_MESSAGES` | Last non-transient system block in the non-transient prefix (stops at first transient)   |
 | `ANTHROPIC_CACHE_ALL_TOOLS`                     | Last tool definition                                                                     |
+| `ANTHROPIC_CACHE_NON_TRANSIENT_TOOLS`           | Last non-transient tool in the non-transient prefix (stops at first transient)           |
 | `ANTHROPIC_CACHE_ALL_MESSAGES`                  | Last block of the last message                                                           |
-| `ANTHROPIC_CACHE_NON_TRANSIENT_MESSAGES`        | Last non-transient block of the last non-transient message                               |
+| `ANTHROPIC_CACHE_NON_TRANSIENT_MESSAGES`        | Last non-transient message block in the non-transient prefix (stops at first transient)  |
 | `ANTHROPIC_CACHE_HISTORY_MESSAGES`              | Last message that was in history before the current turn (via `SaveHistoryEvent` marker) |
 
 ```python

{flowra-0.0.23.dev28 → flowra-0.0.23.dev31}/docs/internal/lib.md

@@ -271,7 +271,8 @@ and conversation messages. Individual bundles are also available — see
 
 The `transient` hint on blocks and messages lets caching bundles skip non-permanent
 content when placing cache breakpoints. For example,
-`AnthropicCacheNonTransientMessages` only caches the last non-transient message.
+`AnthropicCacheNonTransientMessages` caches the last non-transient message block
+in the non-transient prefix (stops at the first transient message).
 
 To implement custom caching logic for other providers, subscribe to
 `PrepareLLMRequestEvent` and modify `event.data.request` directly.

{flowra-0.0.23.dev28 → flowra-0.0.23.dev31}/docs/llm.md

@@ -217,14 +217,15 @@ message — covers the most common case.
 
 For fine-grained control, install individual bundles (all are pre-instantiated constants):
 
-| Constant                                        | What it caches                             |
-|-------------------------------------------------|--------------------------------------------|
-| `ANTHROPIC_CACHE_ALL_SYSTEM_MESSAGES`           | Last block of the last system message      |
-| `ANTHROPIC_CACHE_NON_TRANSIENT_SYSTEM_MESSAGES` | Last non-transient system block            |
-| `ANTHROPIC_CACHE_ALL_TOOLS`                     | Last tool definition                       |
-| `ANTHROPIC_CACHE_ALL_MESSAGES`                  | Last block of the last message             |
-| `ANTHROPIC_CACHE_NON_TRANSIENT_MESSAGES`        | Last non-transient message block           |
-| `ANTHROPIC_CACHE_HISTORY_MESSAGES`              | Last history message (before current turn) |
+| Constant                                        | What it caches                                                          |
+|-------------------------------------------------|-------------------------------------------------------------------------|
+| `ANTHROPIC_CACHE_ALL_SYSTEM_MESSAGES`           | Last block of the last system message                                   |
+| `ANTHROPIC_CACHE_NON_TRANSIENT_SYSTEM_MESSAGES` | Last non-transient system block (stops at first transient)              |
+| `ANTHROPIC_CACHE_ALL_TOOLS`                     | Last tool definition                                                    |
+| `ANTHROPIC_CACHE_NON_TRANSIENT_TOOLS`           | Last non-transient tool (stops at first transient)                      |
+| `ANTHROPIC_CACHE_ALL_MESSAGES`                  | Last block of the last message                                          |
+| `ANTHROPIC_CACHE_NON_TRANSIENT_MESSAGES`        | Last non-transient message block (stops at first transient)             |
+| `ANTHROPIC_CACHE_HISTORY_MESSAGES`              | Last history message (before current turn)                              |
 
 ```python
 from flowra.lib.anthropic import (

{flowra-0.0.23.dev28 → flowra-0.0.23.dev31}/docs/observability.md

@@ -260,6 +260,55 @@ install_otel_tracing(
 )
 ```
 
+## Integration with external tracing context
+
+Both integrations automatically detect and attach to an existing tracing context.
+If your application already creates spans (e.g. a FastAPI middleware, a gRPC
+interceptor, or business-logic code), flowra's spans become children of the
+external span.
+
+### MLflow
+
+If a span was created with `with mlflow.start_span()` or `@mlflow.trace`, flowra
+detects it via `mlflow.get_current_active_span()` and nests inside:
+
+```python
+import mlflow
+from flowra.ext.mlflow import install_mlflow_tracing
+
+hooks = HookSubscription()
+install_mlflow_tracing(hooks, experiment_name="my-experiment")
+
+# External MLflow span — flowra spans become children
+with mlflow.start_span(name="my_business_logic"):
+    result = await runtime.run(agent=MyAgent, spec=MySpec(...))
+```
+
+### OpenTelemetry
+
+If a span was created with `tracer.start_as_current_span()`, flowra detects it
+via `trace.get_current_span()` and nests inside:
+
+```python
+from opentelemetry import trace
+from flowra.ext.otel import install_otel_tracing
+
+hooks = HookSubscription()
+install_otel_tracing(hooks)
+
+app_tracer = trace.get_tracer("my_app")
+
+# External OTel span — flowra spans become children
+with app_tracer.start_as_current_span("my_business_logic"):
+    result = await runtime.run(agent=MyAgent, spec=MySpec(...))
+```
+
+### Priority
+
+Internal flowra context (from parent agent/step spans) takes priority over
+external context. External context is only used when there is no flowra parent —
+i.e. at the root of the flowra execution.
+
 ## Choosing the right tracing setup
 
 | Setup                   | Best for                                         | What you get                                          |

{flowra-0.0.23.dev28 → flowra-0.0.23.dev31}/docs/research/mlflow_context_migration.md

@@ -9,6 +9,12 @@ Implemented via `FlowingContextVar` (see `flowing_context.md`). The MLflow
 handler uses `_mlflow_parent: FlowingContextVar[LiveSpan | None]` for parent
 tracking. The engine's fork/restore mechanism handles sibling isolation.
 
+**Update (2026-03-24):** Added external context integration. When no flowra
+parent exists, handlers check `mlflow.get_current_active_span()` to detect
+external MLflow spans. This allows flowra to nest inside existing MLflow traces
+(e.g. `with mlflow.start_span()` blocks). Same approach for OTel via
+`trace.get_current_span()`.
+
 ## Problem
 
 `flowra/ext/mlflow.py` manually managed span parent-child relationships via a

{flowra-0.0.23.dev28 → flowra-0.0.23.dev31}/docs/research/otel_integration.md

@@ -9,6 +9,11 @@ Phase 1 implemented as `flowra/ext/otel.py`. Span-hook integration with GenAI
 semantic conventions. Uses `FlowingContextVar` for parent tracking (same as MLflow).
 Optional dependency: `flowra[otel]` (`opentelemetry-api`, `opentelemetry-sdk`).
 
+**Update (2026-03-24):** Added external context integration. When no flowra
+parent exists, `_start_span` checks `trace.get_current_span()` to detect
+external OTel spans (ignoring non-recording spans). This allows flowra to nest
+inside existing OTel traces (e.g. `tracer.start_as_current_span()` blocks).
+
 ## 1. MLflow + OTel Relationship
 
 ### Architecture

flowra-0.0.23.dev31/examples/TRACING_COMBINATIONS.md

@@ -0,0 +1,180 @@
+# MLflow + OpenTelemetry Tracing Combinations
+
+This directory contains examples demonstrating different ways to use MLflow and OpenTelemetry tracing together.
+
+## Quick Reference
+
+| Example | MLflow | OTel | Trace IDs | Best for |
+|---------|--------|------|-----------|----------|
+| `mlflow_otel_both_demo.py` | ✓ Independent | ✓ Independent | Different | Full picture, two UIs |
+| `mlflow_dual_export_demo.py` | ✓ Dual export | Via MLflow | **Same** | Single instrumentation |
+| `mlflow_otel_nested_demo.py` | ✓ Independent | ✓ Nested | Different | External OTel context |
+
+## Examples
+
+### 1. Both Independently (`mlflow_otel_both_demo.py`)
+
+**What it does:**
+- Enables both MLflow and OTel tracing
+- Creates two independent trace trees
+- Different trace IDs
+
+**Run:**
+```bash
+make mlflow-otel-both
+```
+
+**View traces:**
+- MLflow: http://localhost:5050 (experiment: `mlflow-otel-both`)
+- Jaeger: http://localhost:16686 (service: `flowra`)
+
+**Use case:**
+You want the full picture with both UIs:
+- MLflow for LLM-specific details (cost, tokens, chat preview)
+- OTel for distributed tracing with standard GenAI semantic conventions
+
+**Trade-off:** Two separate trace IDs — no direct link between traces.
+
+---
+
+### 2. MLflow Dual Export (`mlflow_dual_export_demo.py`)
+
+**What it does:**
+- Enables only MLflow tracing
+- MLflow automatically exports spans to OTel collector
+- Same trace ID in both systems
+
+**Setup:**
+Requires environment variables:
+```bash
+export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://localhost:4317"
+export MLFLOW_TRACE_ENABLE_OTLP_DUAL_EXPORT="true"
+export OTEL_SERVICE_NAME="flowra-mlflow-dual"
+```
+
+**Run:**
+```bash
+make mlflow-dual-export
+```
+
+**View traces:**
+- MLflow: http://localhost:5050 (experiment: `mlflow-dual-export`)
+- Jaeger: http://localhost:16686 (service: `flowra-mlflow-dual`)
+
+**Check:** Trace IDs should be **identical** in both UIs!
+
+**Use case:**
+Single instrumentation with dual output. MLflow is the source of truth, OTel gets a copy.
+
+**Trade-off:** MLflow uses its own attribute names (`mlflow.chat.tokenUsage`) instead of
+standard GenAI semantic conventions (`gen_ai.usage.input_tokens`), so OTel backends
+won't recognize them as standard GenAI spans.
+
+---
+
+### 3. External OTel Span Wrapping Flowra (`mlflow_otel_nested_demo.py`)
+
+**What it does:**
+- External OTel span created by business application
+- Flowra runs inside with BOTH MLflow and OTel tracing
+- OTel spans nest into external context
+- MLflow creates independent trace tree
+
+**Run:**
+```bash
+make mlflow-otel-nested
+```
+
+**View traces:**
+- Jaeger: http://localhost:16686 (service: `business_app`)
+  - Shows: `business_workflow` span with flowra spans nested inside
+- MLflow: http://localhost:5050 (experiment: `mlflow-otel-nested`)
+  - Shows: independent MLflow trace tree
+
+**Use case:**
+Flowra is part of a larger service that already uses OTel tracing. You want:
+- OTel: full distributed trace including external business logic
+- MLflow: LLM-specific view with cost/token details
+
+**Key insight:**
+- OTel integrates with external context (same trace tree)
+- MLflow creates independent tree (its own trace ID)
+- Both capture the SAME execution from different perspectives
+
+---
+
+## Other Examples
+
+### 4. MLflow Only with External Span (`mlflow_nested_demo.py`)
+
+External MLflow span wrapping flowra (only MLflow tracing).
+
+```bash
+make mlflow-nested-demo
+```
+
+### 5. OTel Only with External Span (`otel_nested_demo.py`)
+
+External OTel span wrapping flowra (only OTel tracing).
+
+```bash
+make otel-nested-demo
+# Visualize:
+make otel-nested-visualize
+```
+
+### 6. OTel with Jaeger (`otel_jaeger_demo.py`)
+
+OTel tracing with external span, exported to Jaeger.
+
+```bash
+make otel-jaeger-demo
+```
+
+---
+
+## Decision Tree
+
+```
+Do you use OTel in your service already?
+├── No → MLflow only (simplest, best LLM UI)
+└── Yes
+    ├── Do you need MLflow's LLM-specific UI?
+    │   ├── No → OTel only (standard, lightweight)
+    │   └── Yes
+    │       ├── Do you want one trace ID across both?
+    │       │   ├── Yes → MLflow with OTel export (dual export)
+    │       │   └── No → Both independently
+    │       └── Do you need standard GenAI semconv attributes?
+    │           ├── Yes → Both independently (OTel uses gen_ai.*)
+    │           └── No → MLflow with OTel export (simpler)
+```
+
+---
+
+## Quick Start
+
+1. **Start Jaeger** (for OTel examples):
+   ```bash
+   docker run -d --name jaeger \
+     -p 16686:16686 \
+     -p 4317:4317 \
+     jaegertracing/all-in-one:latest
+   ```
+
+2. **Run an example**:
+   ```bash
+   make mlflow-otel-both
+   ```
+
+3. **View traces**:
+   - MLflow UI: `uv run mlflow ui --port 5050` → http://localhost:5050
+   - Jaeger UI: http://localhost:16686
+
+---
+
+## See Also
+
+- `docs/observability.md` — full documentation on tracing options
+- `flowra/ext/mlflow.py` — MLflow integration implementation
+- `flowra/ext/otel.py` — OpenTelemetry integration implementation