flowra 0.0.2.dev5__tar.gz → 0.0.4__tar.gz

{flowra-0.0.2.dev5 → flowra-0.0.4}/.gitignore

@@ -12,4 +12,6 @@ build/
 *.egg
 /.idea/
 .chat_sessions/
-logs/
+logs/
+.voice_rt_logs/
+.voice_payment_sessions/

{flowra-0.0.2.dev5 → flowra-0.0.4}/CHANGELOG.md

@@ -5,7 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com),
 and this project adheres to [Semantic Versioning](https://semver.org).
 
-## [Unreleased]
+## [0.0.4] - 2026-03-09
+
+### Fixed
+- **JSON schema response cleanup**: `AnthropicVertexProvider` now returns a single `TextBlock`
+  with clean JSON when `json_schema` is set — markdown fences and thinking blocks are stripped.
+  Previously, validated JSON was cleaned internally but the original (fenced) text was returned.
+- `validate_json_schema` now returns `(error, cleaned_text)` tuple so callers get the
+  fence-stripped text.
+
+## [0.0.3] - 2026-03-08
+
+### Changed
+- **Hook system redesign**: replaced `ToolLoopHooks`/`ChatHooks` (24 Protocol classes, 12 executor
+  functions, 5 result dataclasses) with generic `HookRegistry` + `Event[T]` pattern. Supports
+  multiple handlers per event, `HookProvider` for distributable hook sets, and `propagate_to()`
+  for parent/child isolation. Hook events are plain mutable dataclasses with result fields.
+- `ToolLoopSpec.meta` / `ChatSpec.meta` renamed to `metadata`.
+
+## [0.0.2] - 2026-03-08
 
 ### Added
 - **Streaming**: `LLMProvider.stream()` method returns `AsyncIterator[StreamEvent]` with `TextDelta`, `ThinkingDelta`, and `ContentComplete` events. All three built-in providers implement real-time streaming. Default fallback calls `call()` and yields `ContentComplete`.

{flowra-0.0.2.dev5 → flowra-0.0.4}/CLAUDE.md

@@ -58,6 +58,39 @@ Review prompts live in `docs/review_prompts/`:
 
 Test directory structure mirrors `flowra/`. E2E tests use `_e2e` suffix (e.g., `test_anthropic_e2e.py`). Environment variables loaded from `.env` via Makefile.
 
+## Releases
+
+CI workflow: `.github/workflows/publish.yml` (manual trigger via `workflow_dispatch`).
+
+### Pre-release
+
+No preparation needed. Tell the user to trigger the `publish` workflow with `type: pre-release` in GitHub Actions. Do NOT trigger it yourself. CI appends `.dev{run_number}` to the current version automatically.
+
+### Release
+
+**Preparation (manual):**
+
+1. Check that `flowra/version.py` has the correct version (CI bumps it automatically after each release, so it should already be set)
+2. Rename the `[Unreleased]` section in `CHANGELOG.md` to `[X.Y.Z] - YYYY-MM-DD` matching the version in `version.py`
+3. Verify documentation is up to date with code changes (especially `docs/llm.md`, `context7.json`)
+4. Run `make check` — lint + all tests must pass
+5. Commit, push to `master`
+
+**Publishing:**
+
+Tell the user to trigger the `publish` workflow manually in GitHub Actions. Do NOT trigger it yourself.
+
+CI (`type: release`) will:
+- Validate that the branch is `master`
+- Validate that `CHANGELOG.md` has a section matching the version
+- Run lint + tests
+- Build and publish to PyPI
+- Create git tag `v{version}` and GitHub Release
+- Bump version for next cycle (patch increment) and add `[Unreleased]` section
+- Push the version bump commit to `master`
+
+**Do NOT** create git tags manually — CI handles this.
+
 ## Maintenance
 
 - **`context7.json`** — project description for [Context7](https://context7.com). Must be updated when adding new features, changing public APIs, or modifying architecture. Keep rules in sync with actual capabilities.

{flowra-0.0.2.dev5 → flowra-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowra
-Version: 0.0.2.dev5
+Version: 0.0.4
 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.2.dev5 → flowra-0.0.4}/context7.json

@@ -62,15 +62,15 @@
     "ChatAgent usage: runtime.run(agent=ChatAgent, step=ChatAgent.process_message, spec=ChatSpec(user_message=text))",
     "ChatSpec(user_message: str) is the input, ChatResult(response: str | None, usage: Usage | None) is the output",
     "ChatConfig configures ChatAgent: ChatConfig(llm_config=LLMConfig(model='...'), system_messages=[SystemMessage(...)])",
-    "ChatHooks provides chat-level lifecycle hooks (DI service, same pattern as ToolLoopHooks): ChatHooks(on_save_turn_messages=filter_fn)",
-    "on_save_turn_messages hook filters turn messages before saving to session history — useful for excluding transient messages injected by hooks",
-    "Transient message pattern: mark messages with metadata={'transient': True}, then filter in on_save_turn_messages hook",
+    "HookRegistry from flowra.agent provides generic Event[T] + handler pattern for lifecycle hooks. Register handlers via hooks.on(EventType, handler). Supports multiple handlers, sync/async transparency, HookProvider composition, and propagate_to() for isolation",
+    "SaveTurnMessagesEvent filters turn messages before saving to session history — mutate event.data.messages in place to control what gets persisted. Useful for excluding transient messages injected by hooks",
+    "Transient message pattern: mark messages with metadata={'transient': True}, then filter in SaveTurnMessagesEvent handler",
 
     "PRE-BUILT AGENTS — ToolLoopAgent: single-turn LLM tool loop with hooks and caching",
     "ToolLoopAgent sends messages to LLM, executes tool calls, feeds results back, repeats until done",
     "ToolLoopConfig configures ToolLoopAgent: ToolLoopConfig(llm_config=LLMConfig(model='...'), cache_config=CacheConfig(...))",
-    "ToolLoopHooks provides lifecycle callbacks: on_user_message, on_message_accepted, on_start_iteration, on_before_llm_call, on_text_delta, on_thinking_delta, on_after_llm_call, on_text_reasoning, on_thinking, on_result_message, on_before_tool_call, on_after_tool_call",
-    "When on_text_delta or on_thinking_delta hooks are set, ToolLoopAgent automatically uses provider.stream() instead of provider.call()",
+    "ToolLoopAgent hook events: UserMessageEvent, MessageAcceptedEvent, StartIterationEvent, BeforeLLMCallEvent, TextDeltaEvent, ThinkingDeltaEvent, AfterLLMCallEvent, TextReasoningEvent, ThinkingEvent, ResultMessageEvent, BeforeToolCallEvent, AfterToolCallEvent",
+    "When TextDeltaEvent or ThinkingDeltaEvent handlers are registered, ToolLoopAgent automatically uses provider.stream() instead of provider.call()",
 
     "CACHING: CacheConfig(system_prompt, tools, messages) controls prompt caching strategies",
     "Predefined configs: CACHE_ALL, CACHE_SESSION, CACHE_MANUAL, NO_CACHE",
@@ -80,7 +80,7 @@
     "ConfigValue[T] wraps static or dynamic (callable) config values: ConfigValue[str] | ConfigValue[Callable[[], str]]",
 
     "QUICK START: Create provider -> create ToolRegistry -> create Config -> create AgentRuntime -> runtime.run()",
-    "Import ChatAgent: from flowra.lib.chat import ChatAgent, ChatConfig, ChatHooks, ChatResult, ChatSpec",
+    "Import ChatAgent: from flowra.lib.chat import ChatAgent, ChatConfig, ChatResult, ChatSpec, SaveTurnMessagesEvent",
     "Import LLMConfig: from flowra.lib import LLMConfig",
     "Import LLM types: from flowra.llm import LLMProvider, SystemMessage, TextBlock, Usage, TextDelta, ThinkingDelta, ContentComplete",
     "Import runtime: from flowra.runtime import AgentRuntime, FileSessionStorage",

{flowra-0.0.2.dev5 → flowra-0.0.4}/docs/architecture.md

@@ -56,7 +56,8 @@ Pre-built agents for common patterns:
 - **`ToolLoopAgent`** — single-turn LLM tool loop. Sends messages to the LLM,
   executes tool calls, feeds results back, repeats until done.
 
-Also provides lifecycle hooks, prompt caching strategies, and dynamic config. → [docs/lib.md](lib.md)
+Also provides a generic `HookRegistry` + `Event[T]` hook system, prompt caching strategies,
+and dynamic config. → [docs/lib.md](lib.md)
 
 ## Data flow
 

{flowra-0.0.2.dev5 → flowra-0.0.4}/docs/lib.md

@@ -11,14 +11,12 @@ flowra/lib/
 ├── chat/
 │   ├── agent.py             # ChatAgent — multi-turn chat with session history
 │   ├── config.py            # ChatConfig — chat-level configuration
-│   ├── hooks.py             # ChatHooks — chat-level lifecycle hooks
-│   ├── hook_executor.py     # Internal: async/sync hook dispatch
+│   ├── hook_events.py       # SaveTurnMessagesEvent
 │   └── spec.py              # ChatSpec, ChatResult
 └── tool_loop/
     ├── agent.py             # ToolLoopAgent — single-turn LLM tool loop
     ├── config.py            # ToolLoopConfig
-    ├── hooks.py             # ToolLoopHooks, hook protocols and result types
-    ├── hook_executor.py     # Internal: async/sync hook dispatch
+    ├── hook_events.py       # 12 event dataclasses for hook system
     ├── spec.py              # ToolLoopSpec, ToolLoopResult, ToolLoopStatus
     ├── context.py           # ToolLoopAgentContext — tool-accessible loop context
     ├── cache.py             # CacheConfig, cache strategies and presets
@@ -114,10 +112,10 @@ Input for `ChatAgent.process_message`.
 | Field          | Type                     | Default |
 |----------------|--------------------------|---------|
 | `user_message` | `str`                    | —       |
-| `meta`         | `dict[str, Any] \| None` | `None`  |
+| `metadata`     | `dict[str, Any] \| None` | `None`  |
 
-`meta` is passed through to `ToolLoopSpec` and delivered to the `on_message_accepted`
-hook — useful for tracking message IDs in interrupt scenarios.
+`metadata` is passed through to `ToolLoopSpec` and delivered to `MessageAcceptedEvent`
+— useful for tracking message IDs in interrupt scenarios.
 
 ### `ChatResult`
 
@@ -151,31 +149,32 @@ sync callable, or async callable (see [ConfigValue](#configvalue) below).
 instead of `session_messages`. The chat agent builds `session_messages` automatically
 by prepending `system_messages` to the accumulated conversation history.
 
-### `ChatHooks`
+### Chat hooks
 
-Chat-level lifecycle hooks, injected via DI as a service (same pattern as `ToolLoopHooks`).
+Chat-level hook events, registered on the same `HookRegistry` instance as tool loop hooks.
 
-| Field                    | Type                                                           | Default |
-|--------------------------|----------------------------------------------------------------|---------|
-| `on_save_turn_messages`  | `OnSaveTurnMessages \| OnSaveTurnMessagesAsync \| None`        | `None`  |
+**`SaveTurnMessagesEvent`** — emitted before turn messages are saved into session history.
+Handlers mutate `messages` in place to control what gets persisted. Useful for excluding
+transient messages (e.g. dynamic context injected by hooks) from long-term session history.
 
-**`on_save_turn_messages`** — called before turn messages are saved into session history.
-Receives the full list of turn messages and returns the filtered list to persist.
-Useful for excluding transient messages (e.g. dynamic context injected by hooks)
-from long-term session history.
+| Field               | Type                      | Default |
+|---------------------|---------------------------|---------|
+| `messages`          | `list[Message]`           | —       |
 
 ```python
-from flowra.lib.chat import ChatAgent, ChatConfig, ChatHooks
+from flowra.agent import HookRegistry
+from flowra.lib.chat import ChatAgent, ChatConfig, SaveTurnMessagesEvent
 from flowra.llm import Message
 
-def filter_transient(messages: list[Message]) -> list[Message]:
-    return [m for m in messages if not m.metadata.get("transient")]
+def filter_transient(event):
+    event.data.messages = [m for m in event.data.messages if not m.metadata.get("transient")]
 
-hooks = ChatHooks(on_save_turn_messages=filter_transient)
+hooks = HookRegistry()
+hooks.on(SaveTurnMessagesEvent, filter_transient)
 
 runtime = AgentRuntime(
     agents={"chat": ChatAgent},
-    services={..., ChatConfig: config, ChatHooks: hooks},
+    services={..., ChatConfig: config, HookRegistry: hooks},
 )
 ```
 
@@ -217,7 +216,7 @@ Input for `ToolLoopAgent.start`.
 | Field          | Type                     | Default |
 |----------------|--------------------------|---------|
 | `user_message` | `str`                    | —       |
-| `meta`         | `dict[str, Any] \| None` | `None`  |
+| `metadata`     | `dict[str, Any] \| None` | `None`  |
 
 ### `ToolLoopResult`
 
@@ -278,99 +277,78 @@ the agent tells the LLM to try a different approach.
 
 ## Hooks
 
-All lifecycle hooks are grouped into the `ToolLoopHooks` dataclass, injected via DI as
-a service. Every hook is optional, and each accepts either a sync or async callable.
+Lifecycle hooks use a generic `HookRegistry` + `Event[T]` pattern from `flowra.agent`.
+Register handlers for typed event dataclasses. Supports multiple handlers per event,
+sync/async transparency, and composition via `HookProvider`.
 
 ```python
-from flowra.lib.tool_loop import ToolLoopHooks
+from flowra.agent import HookRegistry
+from flowra.lib.tool_loop import BeforeLLMCallEvent, AfterLLMCallEvent
 
-hooks = ToolLoopHooks(
-    on_before_llm_call=lambda req, ctx: print(f"Calling LLM with {len(req.messages)} messages"),
-    on_after_llm_call=lambda req, res, ctx: print(f"LLM returned {res.stop_reason}"),
-)
+hooks = HookRegistry()
+hooks.on(BeforeLLMCallEvent, lambda e: print(f"Calling LLM with {len(e.data.request.messages)} messages"))
+hooks.on(AfterLLMCallEvent, lambda e: print(f"LLM returned {e.data.response.stop_reason}"))
 
 runtime = AgentRuntime(
     agents={"chat": ChatAgent},
-    services={..., ToolLoopHooks: hooks},
+    services={..., HookRegistry: hooks},
 )
 ```
 
-### `ToolLoopHooks`
-
-| Field                  | Type                                                           | Default |
-|------------------------|----------------------------------------------------------------|---------|
-| `on_user_message`      | `OnUserMessage \| OnUserMessageAsync \| None`                  | `None`  |
-| `on_message_accepted`  | `OnMessageAccepted \| OnMessageAcceptedAsync \| None`          | `None`  |
-| `on_start_iteration`   | `OnStartIteration \| OnStartIterationAsync \| None`            | `None`  |
-| `on_before_llm_call`   | `OnBeforeLLMCall \| OnBeforeLLMCallAsync \| None`              | `None`  |
-| `on_after_llm_call`    | `OnAfterLLMCall \| OnAfterLLMCallAsync \| None`                | `None`  |
-| `on_result_message`    | `OnResultMessage \| OnResultMessageAsync \| None`              | `None`  |
-| `on_text_delta`        | `OnTextDelta \| OnTextDeltaAsync \| None`                      | `None`  |
-| `on_thinking_delta`    | `OnThinkingDelta \| OnThinkingDeltaAsync \| None`              | `None`  |
-| `on_text_reasoning`    | `OnTextReasoning \| OnTextReasoningAsync \| None`              | `None`  |
-| `on_thinking`          | `OnThinking \| OnThinkingAsync \| None`                        | `None`  |
-| `on_before_tool_call`  | `OnBeforeToolCall \| OnBeforeToolCallAsync \| None`            | `None`  |
-| `on_after_tool_call`   | `OnAfterToolCall \| OnAfterToolCallAsync \| None`              | `None`  |
+### `HookRegistry`
+
+| Method                                      | Description                                      |
+|---------------------------------------------|--------------------------------------------------|
+| `on(event_type, handler, *, prepend=False)` | Register a handler for an event type             |
+| `has_handlers(event_type) -> bool`          | Check if any handlers are registered             |
+| `add(provider: HookProvider)`               | Register all hooks from a HookProvider           |
+| `async emit(data: T) -> T`                  | Wrap data in `Event`, call handlers, return data |
+| `propagate_to(target, *, only, exclude)`    | Forward events to another registry               |
+
+Handlers receive `Event[T]` where `T` is the event dataclass. `Event` has two fields:
+`data: T` (the event payload) and `context: HookContext | None` (metadata stamped by emit).
+`HookContext` carries `agent_type: type[AbstractAgent] | None` and `agent_path: str`.
+Handlers can mutate `event.data` fields to communicate results back.
+
+### Hook events
+
+| Event                  | Mutable fields                                   | Description                                                               |
+|------------------------|--------------------------------------------------|---------------------------------------------------------------------------|
+| `UserMessageEvent`     | `messages: list[UserMessage]`                    | Once at loop start. Mutate to replace or augment the initial messages.    |
+| `MessageAcceptedEvent` | —                                                | After messages accepted (incl. on resume). Has `messages: list[Message]`. |
+| `StartIterationEvent`  | `additional_messages: list[UserMessage]`         | At start of each iteration. Append to inject context before LLM call.     |
+| `BeforeLLMCallEvent`   | —                                                | Before each LLM request. Has `request`, `context`.                        |
+| `TextDeltaEvent`       | —                                                | During streaming. Has `text` (str), `context`.                            |
+| `ThinkingDeltaEvent`   | —                                                | During streaming. Has `text` (str), `context`.                            |
+| `AfterLLMCallEvent`    | —                                                | After each LLM response. Has `request`, `response`, `context`.            |
+| `TextReasoningEvent`   | —                                                | For each `TextBlock` in response. Has `text` (TextBlock), `context`.      |
+| `ThinkingEvent`        | —                                                | For each `ThinkingBlock` in response. Has `thinking`, `context`.          |
+| `BeforeToolCallEvent`  | `tool_use: ToolUseBlock`                         | Before tool execution. Replace to modify tool parameters.                 |
+| `AfterToolCallEvent`   | `result: ToolResultBlock`, `additional_messages` | After tool execution. Replace result or inject messages.                  |
+| `ResultMessageEvent`   | `continue_messages: list[UserMessage]`           | On END_TURN. Set to continue loop instead of finishing.                   |
 
 ### Hook lifecycle
 
-Hooks fire in this order during a single tool loop iteration:
-
-1. **`on_user_message`** — once at loop start, before the first iteration. Receives the
-   `UserMessage` built from the spec. Return `UserMessageResult(messages=[...])` to
-   replace the initial messages (include the original in the list to keep it).
-
-2. **`on_message_accepted`** — once after the user message is persisted via `flush()`.
-   Receives `meta` from the spec. Useful for tracking accepted message IDs.
-
-3. **`on_start_iteration`** — at the start of each iteration. Receives 1-indexed
-   iteration number and `ToolLoopAgentContext`. Return `StartIterationResult` with
-   `additional_messages` to inject context before the LLM call.
-
-4. **`on_before_llm_call`** — before each LLM request. Receives `LLMRequest` and context.
-   Observational only (no return value).
+Events fire in this order during a single tool loop iteration:
 
-5. **`on_text_delta`** / **`on_thinking_delta`** — when either hook is set, the agent
-   uses `provider.stream()` instead of `provider.call()`. `on_text_delta` fires for
-   each incremental text chunk; `on_thinking_delta` fires for each thinking chunk.
-   These fire **during** the LLM call, before `on_after_llm_call`. The stream is
-   wrapped with `with_interrupt`, so an `InterruptToken` signal exits immediately —
-   even if the LLM is slow to produce the next token.
-
-6. **`on_after_llm_call`** — after each LLM response. Receives `LLMRequest`, `LLMResponse`,
-   and context. Observational only.
-
-7. **`on_text_reasoning`** — for each `TextBlock` in the assistant response. Fires
-   regardless of stop reason — useful for observing text output even when tool calls
-   are also present.
-
-8. **`on_thinking`** — for each `ThinkingBlock` in the assistant response. Fires
-   for models with thinking/reasoning enabled (e.g. extended thinking).
+1. **`UserMessageEvent`** — once at loop start, before the first iteration.
+2. **`MessageAcceptedEvent`** — once after messages are accepted (including on resume).
+3. **`StartIterationEvent`** — at the start of each iteration.
+4. **`BeforeLLMCallEvent`** — before each LLM request.
+5. **`TextDeltaEvent`** / **`ThinkingDeltaEvent`** — when handlers are registered for either,
+   the agent uses `provider.stream()` instead of `provider.call()`. These fire **during**
+   the LLM call, before `AfterLLMCallEvent`.
+6. **`AfterLLMCallEvent`** — after each LLM response.
+7. **`TextReasoningEvent`** — for each `TextBlock` in the assistant response.
+8. **`ThinkingEvent`** — for each `ThinkingBlock` in the assistant response.
 
 Then the flow branches based on stop reason:
 
 - **If `TOOL_USE`:**
-
-  9. **`on_before_tool_call`** — before each tool execution. Return `BeforeToolCallResult`
-     with `amended_tool_use` to modify tool parameters.
-
-  10. **`on_after_tool_call`** — after each tool execution. Return `AfterToolCallResult`
-      with `amended_result` and/or `additional_messages`.
-
+  9. **`BeforeToolCallEvent`** — before each tool execution.
+  10. **`AfterToolCallEvent`** — after each tool execution.
 - **If `END_TURN`:**
-
-  11. **`on_result_message`** — return `ResultMessageResult` with `continue_messages`
-      to force the loop to continue instead of finishing.
-
-### Hook result types
-
-| Type                     | Fields                                                                              |
-|--------------------------|-------------------------------------------------------------------------------------|
-| `UserMessageResult`      | `messages: list[UserMessage]`                                                       |
-| `StartIterationResult`   | `additional_messages: list[UserMessage]` (default `[]`)                             |
-| `BeforeToolCallResult`   | `amended_tool_use: ToolUseBlock \| None` (default `None`)                           |
-| `AfterToolCallResult`    | `amended_result: ToolResultBlock \| None`, `additional_messages: list[UserMessage]` |
-| `ResultMessageResult`    | `continue_messages: list[UserMessage]` (default `[]`)                               |
+  11. **`ResultMessageEvent`** — set `continue_messages` to force the loop to continue.
 
 ## Prompt caching
 
@@ -515,23 +493,6 @@ value = await resolve_config_value(config.max_iterations)  # always returns T
 ## Type aliases
 
 ```python
-# Chat hook protocols (each has sync and async variant)
-OnSaveTurnMessages / OnSaveTurnMessagesAsync
-
-# Tool loop hook protocols (each has sync and async variant)
-OnUserMessage / OnUserMessageAsync
-OnMessageAccepted / OnMessageAcceptedAsync
-OnStartIteration / OnStartIterationAsync
-OnBeforeLLMCall / OnBeforeLLMCallAsync
-OnAfterLLMCall / OnAfterLLMCallAsync
-OnTextDelta / OnTextDeltaAsync
-OnThinkingDelta / OnThinkingDeltaAsync
-OnTextReasoning / OnTextReasoningAsync
-OnThinking / OnThinkingAsync
-OnResultMessage / OnResultMessageAsync
-OnBeforeToolCall / OnBeforeToolCallAsync
-OnAfterToolCall / OnAfterToolCallAsync
-
 # Cache strategy protocols
 SystemPromptCacheStrategy   # (messages: list[SystemMessage]) -> list[SystemMessage]
 ToolsCacheStrategy          # (tools: list[Tool]) -> list[Tool]
@@ -554,23 +515,16 @@ ChatAgent
 
 ### Tool loop flow
 
-1. `start` — accepts user message, runs `on_user_message` hook, appends to
-   `turn_messages`, flushes, fires `on_message_accepted`, then gotos `call_llm`.
-2. `call_llm` — checks interrupt/finish/max_iterations, runs `on_start_iteration`,
-   builds `LLMRequest`, runs `on_before_llm_call`, calls LLM (streaming deltas via
-   `on_text_delta`/`on_thinking_delta` if set), runs `on_after_llm_call`,
-   `on_text_reasoning`, and `on_thinking`, then:
-   - `END_TURN` → runs `on_result_message`, returns `ToolLoopResult` (or continues
+1. `start` — accepts user message, emits `UserMessageEvent`, appends to
+   `turn_messages`, flushes, emits `MessageAcceptedEvent`, then gotos `call_llm`.
+2. `call_llm` — checks interrupt/finish/max_iterations, emits `StartIterationEvent`,
+   builds `LLMRequest`, emits `BeforeLLMCallEvent`, calls LLM (streaming deltas via
+   `TextDeltaEvent`/`ThinkingDeltaEvent` if handlers registered), emits `AfterLLMCallEvent`,
+   `TextReasoningEvent`, and `ThinkingEvent`, then:
+   - `END_TURN` → emits `ResultMessageEvent`, returns `ToolLoopResult` (or continues
      if `continue_messages` is non-empty)
-   - `TOOL_USE` → runs `on_before_tool_call` for each tool, spawns `ToolCallAgent`
+   - `TOOL_USE` → emits `BeforeToolCallEvent` for each tool, spawns `ToolCallAgent`
      children in parallel
-3. `collect_results` — gathers results from `ToolCallAgent` children, runs
-   `on_after_tool_call` for each, applies `max_consecutive_errors` logic,
+3. `collect_results` — gathers results from `ToolCallAgent` children, emits
+   `AfterToolCallEvent` for each, applies `max_consecutive_errors` logic,
    appends tool results to `turn_messages`, gotos `call_llm`.
-
-### Hook executor
-
-`hook_executor.py` provides `execute_*_hook()` functions that handle the sync/async
-dispatch transparently — each function calls the hook, checks `inspect.isawaitable()`,
-and awaits if needed. This allows hooks to be plain functions or async functions
-interchangeably.

{flowra-0.0.2.dev5 → flowra-0.0.4}/docs/llm.md

@@ -525,8 +525,11 @@ print(format_schema_for_llm(schema))
 #### Schema validation (`schema_validation.py`)
 
 `validate_json_schema(text, schema)` strips markdown code fences, parses JSON, and
-validates against the schema. Returns `None` on success, or an error description string
-on failure. Used internally by `AnthropicVertexProvider` for structured output retries.
+validates against the schema. Returns `(error, cleaned_text)` tuple — `error` is `None`
+on success (and `cleaned_text` contains the fence-stripped JSON), or an error description
+when validation fails. Used internally by `AnthropicVertexProvider` for structured output
+retries. When validation succeeds, the provider returns a single `TextBlock` with the
+cleaned JSON (no markdown fences, no thinking blocks).
 
 Internally, `strip_markdown_code_block(text)` removes surrounding markdown code fences
 (`` ```...``` ``) before parsing. This is an implementation detail, not part of the public API.