flowra 0.0.24.dev33__tar.gz → 0.0.25.dev35__tar.gz

{flowra-0.0.24.dev33 → flowra-0.0.25.dev35}/CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+## [0.0.24] - 2026-03-24
+
 ### Added
 - **`FlowingRegistry`** — replaces `FlowingContextVar`. Registry of flowing variables
   with `on_enter`/`on_exit` callbacks that fire on context switches, keeping external
@@ -25,6 +27,10 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 - **`experiment_name`** in `MLFLOW_TRACING.install()` is now optional (`None` by default).
   When `None`, no MLflow experiment is created — useful when flowra spans are always
   children of externally created spans (no `mlflow.db` side effect).
+- **MLflow tool output** — JSON tool results are now parsed into structured dicts
+  for display in MLflow UI, instead of escaped strings.
+- **`GoogleVertexProvider.aclose()`** — now properly closes async client via
+  `client.aio.aclose()`, fixing "Event loop is closed" errors.
 
 ### Removed
 - **`FlowingContextVar`** — replaced by `FlowingRegistry`/`FlowingVar`.

{flowra-0.0.24.dev33 → flowra-0.0.25.dev35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowra
-Version: 0.0.24.dev33
+Version: 0.0.25.dev35
 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.24.dev33 → flowra-0.0.25.dev35}/docs/observability.md

@@ -2,20 +2,20 @@
 
 Flowra provides two observability mechanisms: **events** (point-in-time
 notifications) and **spans** (start/end pairs for operations). Both are
-delivered via `HookSubscription`. On top of these primitives, Flowra ships
+delivered via `runtime.hooks`. On top of these primitives, Flowra ships
 integrations with MLflow and OpenTelemetry.
 
 ## Events
 
 Events are point-in-time notifications emitted during agent execution. Register
-handlers via `HookSubscription.on()`:
+handlers via `runtime.hooks.on()`:
 
 ```python
-from flowra.agent import HookSubscription
+from flowra.agent import AgentRuntime
 from flowra.lib.observability import TextDeltaEvent
 
-hooks = HookSubscription()
-hooks.on(TextDeltaEvent, lambda e: print(e.data.text, end="", flush=True))
+runtime = AgentRuntime(agents={...}, services={...})
+runtime.hooks.on(TextDeltaEvent, lambda e: print(e.data.text, end="", flush=True))
 ```
 
 Some events are **mutable** — your handler can modify the event data to influence
@@ -52,7 +52,7 @@ Every event is wrapped in `Event[T]` with a `context` field — the execution
 path from root to the agent that emitted the event:
 
 ```python
-from flowra.agent import Event
+from flowra.agent import AgentRuntime, Event
 from flowra.lib.tool_loop import BeforeToolCallEvent
 
 def on_before_tool(event: Event[BeforeToolCallEvent]) -> None:
@@ -60,7 +60,8 @@ def on_before_tool(event: Event[BeforeToolCallEvent]) -> None:
     tool_name = event.data.tool_use.name
     print(f"[{agent_path}] calling {tool_name}")
 
-hooks.on(BeforeToolCallEvent, on_before_tool)
+runtime = AgentRuntime(agents={...}, services={...})
+runtime.hooks.on(BeforeToolCallEvent, on_before_tool)
 ```
 
 Use `event.context.find_spec(SpecType)` to walk the execution stack and find
@@ -70,13 +71,13 @@ active.
 ## Spans
 
 Spans track operations with a start and end. Register handlers via
-`HookSubscription.on_span()`. The handler receives the span at open time and
+`runtime.hooks.on_span()`. The handler receives the span at open time and
 returns a callback that's invoked at close time:
 
 ```python
-from flowra.agent import AgentSpan, HookSubscription
+from flowra.agent import AgentRuntime, AgentSpan
 
-hooks = HookSubscription()
+runtime = AgentRuntime(agents={...}, services={...})
 
 def on_agent(span: AgentSpan):
     print(f"▶ agent started: {span.agent_info.path}")
@@ -84,7 +85,7 @@ def on_agent(span: AgentSpan):
         print(f"◀ agent ended: {span.agent_info.path} result={span.result}")
     return on_end
 
-hooks.on_span(AgentSpan, on_agent)
+runtime.hooks.on_span(AgentSpan, on_agent)
 ```
 
 ### Span types
@@ -109,10 +110,10 @@ and populated before close.
 ### Example: console span tree
 
 ```python
-from flowra.agent import AgentSpan, StepSpan, HookSubscription
+from flowra.agent import AgentRuntime, AgentSpan, StepSpan
 from flowra.lib.observability import LLMCallSpan, ToolCallSpan
 
-hooks = HookSubscription()
+runtime = AgentRuntime(agents={...}, services={...})
 indent = 0
 
 def on_agent(span: AgentSpan):
@@ -140,9 +141,9 @@ def on_tool(span: ToolCallSpan):
             print("  " * indent + f"   → {span.result.content[:80]}")
     return on_end
 
-hooks.on_span(AgentSpan, on_agent)
-hooks.on_span(LLMCallSpan, on_llm)
-hooks.on_span(ToolCallSpan, on_tool)
+runtime.hooks.on_span(AgentSpan, on_agent)
+runtime.hooks.on_span(LLMCallSpan, on_llm)
+runtime.hooks.on_span(ToolCallSpan, on_tool)
 ```
 
 ## MLflow integration
@@ -153,17 +154,15 @@ and session grouping.
 **Install:** `pip install flowra[mlflow]`
 
 ```python
-from flowra.agent import HookSubscription
-from flowra.ext.mlflow import install_mlflow_tracing
+from flowra.agent import AgentRuntime
+from flowra.ext.mlflow import MLFLOW_TRACING
 
-hooks = HookSubscription()
-install_mlflow_tracing(
-    hooks,
+runtime = AgentRuntime(agents={...}, services={...})
+MLFLOW_TRACING.install(
+    runtime,
     experiment_name="my-experiment",
     session_id="chat-session-123",   # groups multi-turn traces together
 )
-
-# pass hooks to AgentRuntime via services={HookSubscription: hooks, ...}
 ```
 
 ### What gets traced
@@ -188,8 +187,8 @@ uv run mlflow ui --port 5050
 ### Parameters
 
 ```python
-install_mlflow_tracing(
-    hooks,
+MLFLOW_TRACING.install(
+    runtime,
     experiment_name="flowra",
     session_id="chat-123",       # or a callable: lambda: current_session_id
     trace_agents=True,
@@ -207,11 +206,11 @@ Works with any OTel backend — Jaeger, Grafana Tempo, Datadog, Honeycomb, etc.
 **Install:** `pip install flowra[otel]`
 
 ```python
-from flowra.agent import HookSubscription
-from flowra.ext.otel import install_otel_tracing
+from flowra.agent import AgentRuntime
+from flowra.ext.otel import OTEL_TRACING
 
-hooks = HookSubscription()
-install_otel_tracing(hooks)
+runtime = AgentRuntime(agents={...}, services={...})
+OTEL_TRACING.install(runtime)
 ```
 
 You configure your own `TracerProvider` and exporter — Flowra just creates spans.
@@ -248,8 +247,8 @@ OTel spans include standard GenAI attributes:
 ### Parameters
 
 ```python
-install_otel_tracing(
-    hooks,
+OTEL_TRACING.install(
+    runtime,
     tracer_name="flowra",
     trace_agents=True,
     trace_steps=True,
@@ -274,10 +273,11 @@ detects it via `mlflow.get_current_active_span()` and nests inside:
 
 ```python
 import mlflow
-from flowra.ext.mlflow import install_mlflow_tracing
+from flowra.agent import AgentRuntime
+from flowra.ext.mlflow import MLFLOW_TRACING
 
-hooks = HookSubscription()
-install_mlflow_tracing(hooks, experiment_name="my-experiment")
+runtime = AgentRuntime(agents={...}, services={...})
+MLFLOW_TRACING.install(runtime, experiment_name="my-experiment")
 
 # External MLflow span — flowra spans become children
 with mlflow.start_span(name="my_business_logic"):
@@ -291,10 +291,11 @@ via `trace.get_current_span()` and nests inside:
 
 ```python
 from opentelemetry import trace
-from flowra.ext.otel import install_otel_tracing
+from flowra.agent import AgentRuntime
+from flowra.ext.otel import OTEL_TRACING
 
-hooks = HookSubscription()
-install_otel_tracing(hooks)
+runtime = AgentRuntime(agents={...}, services={...})
+OTEL_TRACING.install(runtime)
 
 app_tracer = trace.get_tracer("my_app")
 
@@ -341,15 +342,19 @@ Two independent span trees — MLflow for LLM-specific analysis, OTel for
 distributed tracing. Traces are not linked (different trace IDs).
 
 ```python
-hooks = HookSubscription()
-install_mlflow_tracing(hooks, experiment_name="my-experiment")
-install_otel_tracing(hooks)
+from flowra.agent import AgentRuntime
+from flowra.ext.mlflow import MLFLOW_TRACING
+from flowra.ext.otel import OTEL_TRACING
+
+runtime = AgentRuntime(agents={...}, services={...})
+MLFLOW_TRACING.install(runtime, experiment_name="my-experiment")
+OTEL_TRACING.install(runtime)
 ```
 
 ### MLflow with OTel export
 
 MLflow is built on OTel internally. With dual export enabled, MLflow sends
-spans to both backends — no `install_otel_tracing` needed. Single trace ID
+spans to both backends — no `OTEL_TRACING.install()` needed. Single trace ID
 shared between both.
 
 Trade-off: MLflow uses its own attribute names (`mlflow.chat.tokenUsage`, etc.)
@@ -357,8 +362,11 @@ rather than `gen_ai.*`, so OTel backends won't recognize them as standard GenAI
 spans.
 
 ```python
-hooks = HookSubscription()
-install_mlflow_tracing(hooks, experiment_name="my-experiment")
+from flowra.agent import AgentRuntime
+from flowra.ext.mlflow import MLFLOW_TRACING
+
+runtime = AgentRuntime(agents={...}, services={...})
+MLFLOW_TRACING.install(runtime, experiment_name="my-experiment")
 ```
 
 ```bash

{flowra-0.0.24.dev33 → flowra-0.0.25.dev35}/examples/tools/random_numbers.py

@@ -2,6 +2,7 @@
 
 import asyncio
 import dataclasses
+import json
 import logging
 import random
 
@@ -22,7 +23,7 @@ class RandomNumbersParams:
 
 @tool("random_numbers")
 async def random_numbers(params: RandomNumbersParams, interrupt: InterruptToken) -> str:
-    """Generate random integers. Returns them comma-separated."""
+    """Generate random integers. Returns JSON with the numbers array."""
     log.info(
         "TOOL random_numbers(count=%d, min=%d, max=%d) — sleeping %.1fs",
         params.count,
@@ -37,6 +38,6 @@ async def random_numbers(params: RandomNumbersParams, interrupt: InterruptToken)
     except TimeoutError:
         pass
     nums = [random.randint(params.min, params.max) for _ in range(params.count)]
-    result = ", ".join(str(n) for n in nums)
+    result = json.dumps({"numbers": nums, "count": len(nums), "range": {"min": params.min, "max": params.max}})
     log.info("TOOL random_numbers => %s", result[:120])
     return result

{flowra-0.0.24.dev33 → flowra-0.0.25.dev35}/flowra/agent/__init__.py

@@ -29,7 +29,7 @@ from .flow import (
 from .runtime import AgentRuntime, AgentSpan, StepSpan
 from .services import ServiceLocator
 from .state import FORK, NEW_SCOPE, AgentStore, AppendOnlyList, Scalar
-from .storage import FileSessionStorage, InMemorySessionSnapshot, InMemorySessionStorage
+from .storage import ChangeSet, FileSessionStorage, InMemorySessionSnapshot, InMemorySessionStorage, SessionStorage
 
 __all__ = [
     "FORK",
@@ -43,6 +43,7 @@ __all__ = [
     "AppendOnlyList",
     "CallAgent",
     "CallStep",
+    "ChangeSet",
     "ChildOutput",
     "Event",
     "ExecutionContext",
@@ -63,6 +64,7 @@ __all__ = [
     "InterruptedError",
     "Scalar",
     "ServiceLocator",
+    "SessionStorage",
     "Spawn",
     "SpawnChild",
     "StepSpan",

{flowra-0.0.24.dev33 → flowra-0.0.25.dev35}/flowra/ext/mlflow.py

@@ -322,7 +322,10 @@ def _make_tool_handler(
             detach_span_from_context(context_token)
             outputs: dict[str, Any] = {}
             if span.result is not None:
-                outputs["content"] = span.result.content
+                try:
+                    outputs["content"] = json.loads(span.result.content)
+                except (json.JSONDecodeError, TypeError):
+                    outputs["content"] = span.result.content
                 outputs["is_error"] = span.result.is_error
             if span.error_kind is not None:
                 outputs["error_kind"] = str(span.error_kind)

flowra-0.0.25.dev35/flowra/version.py

@@ -0,0 +1,2 @@
+# Updated by CI/CD pipeline
+__version__ = "0.0.25.dev35"

flowra-0.0.24.dev33/flowra/version.py

@@ -1,2 +0,0 @@
-# Updated by CI/CD pipeline
-__version__ = "0.0.24.dev33"