flowra 0.0.26.dev37__tar.gz → 0.0.27.dev40__tar.gz

{flowra-0.0.26.dev37 → flowra-0.0.27.dev40}/CHANGELOG.md

@@ -7,8 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+### Added
+- **Schema utilities exported** — `format_schema_for_llm`, `format_output_schema_for_description`,
+  `validate_json_schema`, `strip_markdown_code_block` now available from `flowra.llm` for custom providers.
+- **`MediaBlock`** — replaces `ImageBlock`. Supports images, PDFs, and other documents via
+  `media_type` dispatch. Providers choose the right wire format automatically (e.g. `image` vs
+  `document` for Anthropic, `image_url` vs `file` for OpenAI). Optional `filename` field.
+
+## [0.0.26] - 2026-03-25
+
 ### Added
 - **`top_p`** parameter in `LLMRequest` and `LLMConfig` — nucleus sampling, supported by all providers.
+- **`additional_config` in traces** — OTel span attributes (`gen_ai.request.<key>`) and MLflow
+  inputs now include provider-specific config (e.g. `thinking_budget_tokens`).
 
 ### Changed
 - **Universal pricing registry** — replaced three separate per-protocol pricing modules

{flowra-0.0.26.dev37 → flowra-0.0.27.dev40}/CLAUDE.md

@@ -45,7 +45,7 @@ Provider-agnostic interface for calling LLMs:
 - `StreamEvent` = `TextDelta | ThinkingDelta | ContentComplete` — stream events for real-time token delivery
 - `Usage` — input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens, cost_usd, cost (`CostBreakdown` with input/output/cache_read/cache_creation). Token contract: `input_tokens` excludes cached tokens
 - Messages: `SystemMessage`, `UserMessage`, `AssistantMessage` — system messages are separate in `LLMRequest.system`
-- Blocks: `TextBlock`, `ImageBlock`, `ToolUseBlock`, `ToolResultBlock`, `ThinkingBlock` — all inherit `LLMData` (metadata, extra, transient)
+- Blocks: `TextBlock`, `MediaBlock`, `ToolUseBlock`, `ToolResultBlock`, `ThinkingBlock` — all inherit `LLMData` (metadata, extra, transient)
 - `Tool` — inherits from `LLMData` (has metadata, extra, transient). Fields: name, description, input_schema, output_schema
 - Span types (in `flowra.lib.observability`): `LLMCallSpan` (request + response), `ToolCallSpan` (tool_use + result + error_kind) — mutable, for observability via span-hooks
 

{flowra-0.0.26.dev37 → flowra-0.0.27.dev40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowra
-Version: 0.0.26.dev37
+Version: 0.0.27.dev40
 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.26.dev37 → flowra-0.0.27.dev40}/context7.json

@@ -18,7 +18,7 @@
     "LLMResponse contains: message (AssistantMessage), stop_reason (StopReason), stop_sequence (str | None), usage (Usage | None), extra (dict[str, Any] — provider-specific data like provider_stop_reason, id)",
     "Usage contains: input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens, cost_usd (total), cost (CostBreakdown with input/output/cache_read/cache_creation and total property). Token contract: input_tokens excludes cached tokens",
     "Messages: SystemMessage, UserMessage, AssistantMessage. System messages go in LLMRequest.system, conversation messages in LLMRequest.messages",
-    "Blocks: TextBlock, ImageBlock, ToolUseBlock, ToolResultBlock, ThinkingBlock — all inherit LLMData (metadata, extra, transient)",
+    "Blocks: TextBlock, MediaBlock, ToolUseBlock, ToolResultBlock, ThinkingBlock — all inherit LLMData (metadata, extra, transient)",
     "LLMData base: metadata (dict, not sent to LLM), extra (dict, provider-specific passthrough), transient (bool, non-permanent content hint)",
     "ThinkingBlock holds reasoning/thinking text from models with extended thinking (Anthropic Claude, Google Gemini). Preserved in history by Anthropic (with signature in extra) and Google providers. OpenAI strips them",
     "Tool definition for LLM: Tool inherits LLMData, fields: name, description, input_schema, output_schema (plus metadata, extra, transient from LLMData)",

{flowra-0.0.26.dev37 → flowra-0.0.27.dev40}/docs/internal/llm.md

@@ -9,7 +9,7 @@ from flowra.llm import (
     # Messages
     SystemMessage, UserMessage, AssistantMessage, Message,
     # Content blocks
-    TextBlock, ImageBlock, ToolUseBlock, ToolResultBlock, ThinkingBlock,
+    TextBlock, MediaBlock, ToolUseBlock, ToolResultBlock, ThinkingBlock,
     # Block type aliases
     UserBlock, AssistantBlock,
     # Tool schema
@@ -114,18 +114,21 @@ TextBlock(text="Injected context", transient=True)  # mark as non-permanent
 |---------|--------|---------|---------------------|
 | `text`  | `str`  | —       | Text content        |
 
-### `ImageBlock`
+### `MediaBlock`
 
-Binary image data. Valid in `UserMessage`.
+Binary media content: images, PDFs, documents. Valid in `UserMessage`.
+Providers dispatch on `media_type` to choose the right wire format.
 
 ```python
-ImageBlock(data=image_bytes, media_type="image/png")
+MediaBlock(data=image_bytes, media_type="image/png")
+MediaBlock(data=pdf_bytes, media_type="application/pdf", filename="invoice.pdf")
 ```
 
-| Field        | Type    | Default | Description                               |
-|--------------|---------|---------|-------------------------------------------|
-| `data`       | `bytes` | —       | Binary image data                         |
-| `media_type` | `str`   | —       | MIME type (`"image/png"`, `"image/jpeg"`) |
+| Field        | Type            | Default | Description                                          |
+|--------------|-----------------|---------|------------------------------------------------------|
+| `data`       | `bytes`         | —       | Binary content                                       |
+| `media_type` | `str`           | —       | MIME type (`"image/png"`, `"application/pdf"`, etc.) |
+| `filename`   | `str \| None`   | `None`  | Optional filename (used by OpenAI for documents)     |
 
 ### `ToolUseBlock`
 
@@ -179,7 +182,7 @@ ThinkingBlock(text="Let me reason about this...")
 ### Block type aliases
 
 ```python
-type UserBlock = TextBlock | ImageBlock | ToolResultBlock
+type UserBlock = TextBlock | MediaBlock | ToolResultBlock
 type AssistantBlock = TextBlock | ToolUseBlock | ThinkingBlock
 ```
 
@@ -216,7 +219,7 @@ UserMessage(blocks=[TextBlock(text="What's the weather in Paris?")])
 # Text + image
 UserMessage(blocks=[
     TextBlock(text="What's in this picture?"),
-    ImageBlock(data=png_bytes, media_type="image/png"),
+    MediaBlock(data=png_bytes, media_type="image/png"),
 ])
 
 # Tool result
@@ -787,7 +790,7 @@ if response.usage is not None:
 | `AssistantMessage`   | dataclass  | LLM response message                                                   |
 | `Message`            | type alias | Union of all message types                                             |
 | `TextBlock`          | dataclass  | Text content                                                           |
-| `ImageBlock`         | dataclass  | Binary image                                                           |
+| `MediaBlock`         | dataclass  | Binary image                                                           |
 | `ToolUseBlock`       | dataclass  | Tool call from LLM                                                     |
 | `ToolResultBlock`    | dataclass  | Tool result for LLM                                                    |
 | `ThinkingBlock`      | dataclass  | Thinking/reasoning content                                             |

{flowra-0.0.26.dev37 → flowra-0.0.27.dev40}/examples/llm_logging.py

@@ -17,7 +17,7 @@ from typing import Any
 
 from flowra.agent import HookSubscription
 from flowra.lib.observability import LLMCallSpan
-from flowra.llm import ImageBlock, Message, TextBlock, ThinkingBlock, ToolResultBlock, ToolUseBlock
+from flowra.llm import MediaBlock, Message, TextBlock, ThinkingBlock, ToolResultBlock, ToolUseBlock
 
 _LOGS_DIR = ".logs"
 
@@ -82,6 +82,6 @@ def _format_messages(messages: list[Message]) -> str:
                     parts.append(f"       tool_result: (id={tid}){error_marker} {content}")
                 case ThinkingBlock(text=text):
                     parts.append(f"       thinking: {text[:200]}...")
-                case ImageBlock(media_type=media_type):
+                case MediaBlock(media_type=media_type):
                     parts.append(f"       image: {media_type}")
     return "\n".join(parts)

{flowra-0.0.26.dev37 → flowra-0.0.27.dev40}/flowra/ext/mlflow.py

@@ -31,8 +31,8 @@ from ..agent import AgentRuntime, AgentSpan, FlowingVar, StepSpan
 from ..lib.observability import LLMCallSpan, ToolCallSpan
 from ..llm import (
     AssistantMessage,
-    ImageBlock,
     LLMRequest,
+    MediaBlock,
     Message,
     SystemMessage,
     TextBlock,
@@ -452,7 +452,7 @@ def _user_message_to_openai(msg: UserMessage) -> list[dict[str, Any]]:
                         "tool_call_id": tool_use_id,
                     }
                 )
-            case ImageBlock():
+            case MediaBlock():
                 text_parts.append("[image]")
     if text_parts:
         result.append({"role": "user", "content": "\n".join(text_parts)})

{flowra-0.0.26.dev37 → flowra-0.0.27.dev40}/flowra/llm/__init__.py

@@ -1,9 +1,11 @@
 from .base import LLMData
-from .blocks import AssistantBlock, ImageBlock, TextBlock, ThinkingBlock, ToolResultBlock, ToolUseBlock, UserBlock
+from .blocks import AssistantBlock, MediaBlock, TextBlock, ThinkingBlock, ToolResultBlock, ToolUseBlock, UserBlock
 from .messages import AssistantMessage, Message, SystemMessage, UserMessage
 from .provider import LLMProvider
 from .request import LLMRequest
 from .response import CostBreakdown, LLMResponse, StopReason, Usage
+from .schema_formatting import format_output_schema_for_description, format_schema_for_llm
+from .schema_validation import strip_markdown_code_block, validate_json_schema
 from .stream import ContentComplete, StreamEvent, TextDelta, ThinkingDelta
 from .tools import Tool
 
@@ -12,11 +14,11 @@ __all__ = [
     "AssistantMessage",
     "ContentComplete",
     "CostBreakdown",
-    "ImageBlock",
     "LLMData",
     "LLMProvider",
     "LLMRequest",
     "LLMResponse",
+    "MediaBlock",
     "Message",
     "StopReason",
     "StreamEvent",
@@ -31,4 +33,8 @@ __all__ = [
     "Usage",
     "UserBlock",
     "UserMessage",
+    "format_output_schema_for_description",
+    "format_schema_for_llm",
+    "strip_markdown_code_block",
+    "validate_json_schema",
 ]

{flowra-0.0.26.dev37 → flowra-0.0.27.dev40}/flowra/llm/blocks.py

@@ -5,7 +5,7 @@ from .base import LLMData
 
 __all__ = [
     "AssistantBlock",
-    "ImageBlock",
+    "MediaBlock",
     "TextBlock",
     "ThinkingBlock",
     "ToolResultBlock",
@@ -21,10 +21,18 @@ class TextBlock(LLMData):
 
 
 @dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
-class ImageBlock(LLMData):
-    type: Literal["image"] = "image"
+class MediaBlock(LLMData):
+    """Binary media content: images, PDFs, documents.
+
+    Providers dispatch on *media_type* to choose the right wire format
+    (e.g. ``image`` vs ``document`` for Anthropic, ``image_url`` vs ``file``
+    for OpenAI).
+    """
+
+    type: Literal["media"] = "media"
     data: bytes
     media_type: str
+    filename: str | None = None
 
 
 @dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
@@ -49,5 +57,5 @@ class ThinkingBlock(LLMData):
     text: str
 
 
-type UserBlock = TextBlock | ImageBlock | ToolResultBlock
+type UserBlock = TextBlock | MediaBlock | ToolResultBlock
 type AssistantBlock = TextBlock | ToolUseBlock | ThinkingBlock

{flowra-0.0.26.dev37 → flowra-0.0.27.dev40}/flowra/llm/providers/anthropic_vertex.py

@@ -10,7 +10,7 @@ from anthropic import AsyncAnthropicVertex, omit
 from anthropic.types import Message as AnthropicMessage, StopReason as AnthropicStopReason, Usage as AnthropicUsage
 from google.oauth2 import service_account
 
-from ..blocks import AssistantBlock, ImageBlock, TextBlock, ThinkingBlock, ToolResultBlock, ToolUseBlock
+from ..blocks import AssistantBlock, MediaBlock, TextBlock, ThinkingBlock, ToolResultBlock, ToolUseBlock
 from ..messages import AssistantMessage, SystemMessage, UserMessage
 from ..pricing import estimate_cost as pricing_estimate_cost
 from ..provider import LLMProvider
@@ -241,10 +241,11 @@ class AnthropicVertexProvider(LLMProvider):
                     match block:
                         case TextBlock() as tb:
                             content.append(cls.__convert_text_block(tb))
-                        case ImageBlock(data=data, media_type=media_type):
+                        case MediaBlock(data=data, media_type=media_type):
+                            block_type = "image" if media_type.startswith("image/") else "document"
                             content.append(
                                 {
-                                    "type": "image",
+                                    "type": block_type,
                                     "source": {
                                         "type": "base64",
                                         "media_type": media_type,

{flowra-0.0.26.dev37 → flowra-0.0.27.dev40}/flowra/llm/providers/google_vertex.py

@@ -10,7 +10,7 @@ from google import genai
 from google.genai import types as genai_types
 from google.oauth2 import service_account
 
-from ..blocks import AssistantBlock, ImageBlock, TextBlock, ThinkingBlock, ToolResultBlock, ToolUseBlock
+from ..blocks import AssistantBlock, MediaBlock, TextBlock, ThinkingBlock, ToolResultBlock, ToolUseBlock
 from ..messages import AssistantMessage, SystemMessage, UserMessage
 from ..pricing import estimate_cost as pricing_estimate_cost
 from ..provider import LLMProvider
@@ -211,7 +211,7 @@ class GoogleVertexProvider(LLMProvider):
                     match block:
                         case TextBlock(text=text):
                             parts.append(genai_types.Part(text=text))
-                        case ImageBlock(data=data, media_type=media_type):
+                        case MediaBlock(data=data, media_type=media_type):
                             parts.append(
                                 genai_types.Part(
                                     inline_data=genai_types.Blob(mime_type=media_type, data=data),

{flowra-0.0.26.dev37 → flowra-0.0.27.dev40}/flowra/llm/providers/openai.py

@@ -8,7 +8,7 @@ from openai.types import CompletionUsage
 from openai.types.chat import ChatCompletion
 from openai.types.chat.chat_completion_message_function_tool_call import ChatCompletionMessageFunctionToolCall
 
-from ..blocks import AssistantBlock, ImageBlock, TextBlock, ThinkingBlock, ToolResultBlock, ToolUseBlock
+from ..blocks import AssistantBlock, MediaBlock, TextBlock, ThinkingBlock, ToolResultBlock, ToolUseBlock
 from ..messages import AssistantMessage, Message, SystemMessage, UserMessage
 from ..pricing import estimate_cost as pricing_estimate_cost
 from ..provider import LLMProvider
@@ -130,14 +130,16 @@ class OpenAIProvider(LLMProvider):
                     match block:
                         case TextBlock(text=text):
                             content_parts.append({"type": "text", "text": text})
-                        case ImageBlock(data=data, media_type=media_type):
+                        case MediaBlock(data=data, media_type=media_type, filename=filename):
                             b64 = base64.b64encode(data).decode()
-                            content_parts.append(
-                                {
-                                    "type": "image_url",
-                                    "image_url": {"url": f"data:{media_type};base64,{b64}"},
-                                }
-                            )
+                            data_uri = f"data:{media_type};base64,{b64}"
+                            if media_type.startswith("image/"):
+                                content_parts.append({"type": "image_url", "image_url": {"url": data_uri}})
+                            else:
+                                file_data: dict[str, str] = {"file_data": data_uri}
+                                if filename:
+                                    file_data["filename"] = filename
+                                content_parts.append({"type": "file", "file": file_data})
                         case ToolResultBlock(tool_use_id=tool_use_id, content=content, is_error=is_error):
                             if content_parts:
                                 result.append({"role": "user", "content": cls.__simplify_content(content_parts)})

flowra-0.0.27.dev40/flowra/version.py

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

{flowra-0.0.26.dev37 → flowra-0.0.27.dev40}/tests/agent/runtime/test_serialization.py

@@ -9,7 +9,7 @@ from flowra.agent import Interrupted
 from flowra.agent.runtime.serialization import deserialize_value, serialize_value
 from flowra.llm import (
     AssistantMessage,
-    ImageBlock,
+    MediaBlock,
     SystemMessage,
     TextBlock,
     ToolResultBlock,
@@ -49,7 +49,7 @@ TYPE_REGISTRY: dict[str, type] = {
     "AssistantMessage": AssistantMessage,
     "Usage": Usage,
     "TextBlock": TextBlock,
-    "ImageBlock": ImageBlock,
+    "MediaBlock": MediaBlock,
     "ToolUseBlock": ToolUseBlock,
     "ToolResultBlock": ToolResultBlock,
     "MySpec": MySpec,
@@ -392,10 +392,10 @@ class TestRoundTripBytes:
         assert restored == data
 
     def test_image_block_round_trip(self) -> None:
-        block = ImageBlock(data=b"\x89PNG\r\n", media_type="image/png")
+        block = MediaBlock(data=b"\x89PNG\r\n", media_type="image/png")
         serialized = serialize_value(block, TYPE_TAGS)
         restored = deserialize_value(serialized, TYPE_REGISTRY)
-        assert isinstance(restored, ImageBlock)
+        assert isinstance(restored, MediaBlock)
         assert restored.data == b"\x89PNG\r\n"
         assert restored.media_type == "image/png"
 
@@ -403,13 +403,13 @@ class TestRoundTripBytes:
         msg = UserMessage(
             blocks=[
                 TextBlock(text="look at this"),
-                ImageBlock(data=b"\xff\xd8\xff", media_type="image/jpeg"),
+                MediaBlock(data=b"\xff\xd8\xff", media_type="image/jpeg"),
             ]
         )
         serialized = serialize_value(msg, TYPE_TAGS)
         restored = deserialize_value(serialized, TYPE_REGISTRY)
         assert isinstance(restored, UserMessage)
-        assert isinstance(restored.blocks[1], ImageBlock)
+        assert isinstance(restored.blocks[1], MediaBlock)
         assert restored.blocks[1].data == b"\xff\xd8\xff"
 
 

{flowra-0.0.26.dev37 → flowra-0.0.27.dev40}/tests/llm/providers/test_anthropic_vertex.py

@@ -4,7 +4,7 @@ from unittest.mock import AsyncMock, MagicMock
 
 import pytest
 
-from flowra.llm import ContentComplete, ImageBlock, LLMRequest, StopReason, TextBlock, ThinkingBlock, Tool, UserMessage
+from flowra.llm import ContentComplete, LLMRequest, MediaBlock, StopReason, TextBlock, ThinkingBlock, Tool, UserMessage
 from flowra.llm.providers.anthropic_vertex import AnthropicVertexProvider
 
 
@@ -282,18 +282,18 @@ class TestThinkingSupport:
         assert call_kwargs["temperature"] == 1  # forced by thinking
 
 
-class TestImageBlockConversion:
+class TestMediaBlockConversion:
     async def test_image_block_converted_to_base64_source(
         self, provider: AnthropicVertexProvider, mock_client: AsyncMock
     ) -> None:
-        """ImageBlock in UserMessage is converted to Anthropic base64 image format."""
+        """MediaBlock in UserMessage is converted to Anthropic base64 image format."""
         image_data = b"\x89PNG\r\n\x1a\n"
         request = LLMRequest(
             model="test",
             messages=[
                 UserMessage(
                     blocks=[
-                        ImageBlock(data=image_data, media_type="image/png"),
+                        MediaBlock(data=image_data, media_type="image/png"),
                     ]
                 ),
             ],
@@ -313,14 +313,14 @@ class TestImageBlockConversion:
         assert "cache_control" not in img
 
     async def test_image_block_with_extra(self, provider: AnthropicVertexProvider, mock_client: AsyncMock) -> None:
-        """ImageBlock with cache_control in extra includes cache_control."""
+        """MediaBlock with cache_control in extra includes cache_control."""
         image_data = b"\x89PNG\r\n\x1a\n"
         request = LLMRequest(
             model="test",
             messages=[
                 UserMessage(
                     blocks=[
-                        ImageBlock(
+                        MediaBlock(
                             data=image_data,
                             media_type="image/png",
                             extra={"cache_control": {"type": "ephemeral"}},

{flowra-0.0.26.dev37 → flowra-0.0.27.dev40}/tests/llm/providers/test_google_vertex.py

@@ -7,8 +7,8 @@ from google.genai import types as genai_types
 
 from flowra.llm import (
     AssistantMessage,
-    ImageBlock,
     LLMRequest,
+    MediaBlock,
     StopReason,
     TextBlock,
     ThinkingBlock,
@@ -434,11 +434,11 @@ class TestAdditionalConfig:
         assert thinking_config.include_thoughts is True
 
 
-class TestImageBlockConversion:
+class TestMediaBlockConversion:
     async def test_image_block_converted_to_inline_data(
         self, provider: GoogleVertexProvider, mock_client: MagicMock
     ) -> None:
-        """ImageBlock in UserMessage is converted to Gemini inline_data Part."""
+        """MediaBlock in UserMessage is converted to Gemini inline_data Part."""
         image_data = b"\x89PNG\r\n\x1a\n"
 
         text_part = MagicMock()
@@ -456,7 +456,7 @@ class TestImageBlockConversion:
             messages=[
                 UserMessage(
                     blocks=[
-                        ImageBlock(data=image_data, media_type="image/png"),
+                        MediaBlock(data=image_data, media_type="image/png"),
                     ]
                 ),
             ],

{flowra-0.0.26.dev37 → flowra-0.0.27.dev40}/tests/llm/providers/test_openai_provider.py

@@ -6,8 +6,8 @@ import pytest
 
 from flowra.llm import (
     AssistantMessage,
-    ImageBlock,
     LLMRequest,
+    MediaBlock,
     SystemMessage,
     TextBlock,
     ToolResultBlock,
@@ -189,16 +189,16 @@ class TestSchemaStrictTransformation:
         assert "$ref" in item_prop
 
 
-class TestImageBlockConversion:
+class TestMediaBlockConversion:
     async def test_image_block_converted_to_image_url(self, provider: OpenAIProvider, mock_client: AsyncMock) -> None:
-        """ImageBlock in UserMessage is converted to OpenAI image_url format with data URI."""
+        """MediaBlock in UserMessage is converted to OpenAI image_url format with data URI."""
         image_data = b"\x89PNG\r\n\x1a\n"
         request = LLMRequest(
             model="gpt-4",
             messages=[
                 UserMessage(
                     blocks=[
-                        ImageBlock(data=image_data, media_type="image/png"),
+                        MediaBlock(data=image_data, media_type="image/png"),
                     ]
                 ),
             ],

flowra-0.0.26.dev37/flowra/version.py

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