agentle 0.9.4__py3-none-any.whl → 0.9.28__py3-none-any.whl

agentle/generations/providers/google/adapters/generate_generate_content_response_to_generation_adapter.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import datetime
 import logging
 import uuid
-from collections.abc import AsyncIterator
+from collections.abc import AsyncGenerator, AsyncIterator
 from logging import Logger
 from typing import TYPE_CHECKING, Any, Literal, cast, overload
 
@@ -88,11 +88,11 @@ class GenerateGenerateContentResponseToGenerationAdapter[T](
     @overload
     def adapt(
         self, _f: AsyncIterator["GenerateContentResponse"]
-    ) -> AsyncIterator[Generation[T]]: ...
+    ) -> AsyncGenerator[Generation[T], None]: ...
 
     def adapt(
         self, _f: "GenerateContentResponse | AsyncIterator[GenerateContentResponse]"
-    ) -> Generation[T] | AsyncIterator[Generation[T]]:
+    ) -> Generation[T] | AsyncGenerator[Generation[T], None]:
         """
         Convert Google response(s) to Agentle Generation object(s).
 
@@ -214,7 +214,7 @@ class GenerateGenerateContentResponseToGenerationAdapter[T](
 
     async def _adapt_streaming(
         self, response_stream: AsyncIterator["GenerateContentResponse"]
-    ) -> AsyncIterator[Generation[T]]:
+    ) -> AsyncGenerator[Generation[T], None]:
         """Adapt a streaming response with proper text accumulation."""
         generation_id = self.preferred_id or uuid.uuid4()
         created_time = datetime.datetime.now()
@@ -253,16 +253,19 @@ class GenerateGenerateContentResponseToGenerationAdapter[T](
                 _all_parts.extend(_parts)
 
                 if _optional_model is not None:
-                    optional_model = parse_streaming_json(
-                        "".join([str(p.text) for p in _all_parts]),
+                    # Parse streaming JSON and update final_parsed
+                    accumulated_json_text = "".join([str(p.text) for p in _all_parts])
+                    parsed_optional_model = parse_streaming_json(
+                        accumulated_json_text,
                         model=_optional_model,
                     )
-                    chunk.parsed = optional_model
+                    # Cast the optional model back to T for use in the generation
+                    final_parsed = cast(T, parsed_optional_model)
                 else:
-                    chunk.parsed = None
+                    final_parsed = None
 
-            # Extract parsed data (usually only available in final chunk)
-            if hasattr(chunk, "parsed") and chunk.parsed is not None:
+            # Also check if chunk has parsed attribute from Google API
+            elif hasattr(chunk, "parsed") and chunk.parsed is not None:
                 final_parsed = cast(T | None, chunk.parsed)
 
             # Extract usage (usually only in final chunk)

agentle/generations/providers/google/google_generation_provider.py

@@ -182,6 +182,37 @@ class GoogleGenerationProvider(GenerationProvider):
         """
         return "google"
 
+    @overload
+    def stream_async[T](
+        self,
+        *,
+        model: str | ModelKind | None = None,
+        messages: Sequence[Message],
+        response_schema: type[T],
+        generation_config: GenerationConfig | GenerationConfigDict | None = None,
+    ) -> AsyncGenerator[Generation[T], None]: ...
+
+    @overload
+    def stream_async(
+        self,
+        *,
+        model: str | ModelKind | None = None,
+        messages: Sequence[Message],
+        response_schema: None = None,
+        generation_config: GenerationConfig | GenerationConfigDict | None = None,
+        tools: Sequence[Tool],
+    ) -> AsyncGenerator[Generation[WithoutStructuredOutput], None]: ...
+
+    @overload
+    def stream_async(
+        self,
+        *,
+        model: str | ModelKind | None = None,
+        messages: Sequence[Message],
+        response_schema: None = None,
+        generation_config: GenerationConfig | GenerationConfigDict | None = None,
+    ) -> AsyncGenerator[Generation[WithoutStructuredOutput], None]: ...
+
     async def stream_async[T = WithoutStructuredOutput](
         self,
         *,
@@ -190,7 +221,7 @@ class GoogleGenerationProvider(GenerationProvider):
         response_schema: type[T] | None = None,
         generation_config: GenerationConfig | GenerationConfigDict | None = None,
         tools: Sequence[Tool] | None = None,
-    ) -> AsyncGenerator[Generation[WithoutStructuredOutput], None]:
+    ) -> AsyncGenerator[Generation[T], None]:
         from google.genai import types
 
         if self._normalize_generation_config(generation_config).n > 1:
@@ -260,6 +291,7 @@ class GoogleGenerationProvider(GenerationProvider):
             tools=_tools,
             max_output_tokens=_generation_config.max_output_tokens,
             response_schema=response_schema if bool(response_schema) else None,
+            response_mime_type="application/json" if bool(response_schema) else None,
             automatic_function_calling=types.AutomaticFunctionCallingConfig(
                 disable=disable_function_calling,
                 maximum_remote_calls=maximum_remote_calls,
@@ -295,10 +327,8 @@ class GoogleGenerationProvider(GenerationProvider):
             raise
 
         # Create the response
-        response = GenerateGenerateContentResponseToGenerationAdapter[
-            WithoutStructuredOutput
-        ](
-            response_schema=None,
+        response = GenerateGenerateContentResponseToGenerationAdapter[T](
+            response_schema=response_schema,
             model=used_model,
         ).adapt(generate_content_response_stream)
 

agentle/generations/providers/openrouter/_adapters/openrouter_message_to_generated_assistant_message_adapter.py

@@ -84,11 +84,45 @@ class OpenRouterMessageToGeneratedAssistantMessageAdapter[T](
         tool_parts: list[ToolExecutionSuggestion] = []
         for tool_call in tool_calls_data:
             function_data = tool_call.get("function", {})
+
+            # Parse arguments with error handling for malformed JSON
+            args_str = str(function_data.get("arguments", "{}"))
+            args: dict[str, object] = {}
+            try:
+                args = json.loads(args_str)
+            except json.JSONDecodeError as e:
+                # Log the error and try to extract the first valid JSON object
+                import logging
+
+                logger = logging.getLogger(__name__)
+                logger.warning(
+                    f"Malformed JSON in tool call arguments: {e}. "
+                    + "Attempting to parse first valid JSON object. "
+                    + f"Raw arguments: {args_str[:200]}..."
+                )
+
+                # Try to find the first complete JSON object
+                try:
+                    # Use JSONDecoder to parse incrementally
+                    decoder = json.JSONDecoder()
+                    args, idx = decoder.raw_decode(args_str)
+                    if idx < len(args_str.strip()):
+                        logger.warning(
+                            f"Extra data found after position {idx}. "
+                            + "Using first valid JSON object only."
+                        )
+                except (json.JSONDecodeError, ValueError) as e2:
+                    logger.error(
+                        f"Failed to parse tool call arguments even with recovery: {e2}. "
+                        + "Using empty dict."
+                    )
+                    args = {}
+
             tool_parts.append(
                 ToolExecutionSuggestion(
                     id=str(tool_call.get("id", "")),
                     tool_name=str(function_data.get("name", "")),
-                    args=json.loads(str(function_data.get("arguments", "{}"))),
+                    args=args,
                 )
             )
 

agentle/mcp/servers/stdio_mcp_server.py

@@ -451,12 +451,19 @@ class StdioMCPServer(MCPServerProtocol):
                     self._logger.warning("Server closed stdout")
                     break
 
+                message_str = ""
                 try:
                     message_str = line.decode("utf-8").strip()
                     if not message_str:
                         continue
 
                     self._logger.debug(f"<- RECV: {message_str}")
+
+                    # Skip lines that don't look like JSON (common with MCP servers that log to stdout)
+                    if not message_str.startswith("{"):
+                        self._logger.debug(f"Skipping non-JSON line: {message_str}")
+                        continue
+
                     message = json.loads(message_str)
 
                     if "id" in message:
@@ -468,8 +475,10 @@ class StdioMCPServer(MCPServerProtocol):
                     else:
                         self._logger.warning(f"Unknown message type: {message}")
 
-                except json.JSONDecodeError as e:
-                    self._logger.error(f"Failed to parse JSON: {e}")
+                except json.JSONDecodeError:
+                    self._logger.debug(
+                        f"Skipping invalid JSON line: {message_str[:100]}"
+                    )
                 except UnicodeDecodeError as e:
                     self._logger.error(f"Failed to decode UTF-8: {e}")
 
@@ -762,7 +771,12 @@ class StdioMCPServer(MCPServerProtocol):
 
     async def _send_request(self, request: _JsonRpcRequest) -> _JsonRpcResponse:
         """Send a request to the server and wait for response."""
-        if not self._is_connected() or not self._stdin:
+        # Allow requests during INITIALIZING state (for the initialize request itself)
+        if (
+            self._connection_state
+            not in [ConnectionState.CONNECTED, ConnectionState.INITIALIZING]
+            or not self._stdin
+        ):
             raise ConnectionError("Server not connected")
 
         request_id = request["id"]
@@ -798,7 +812,12 @@ class StdioMCPServer(MCPServerProtocol):
 
     async def _send_notification(self, notification: _JsonRpcNotification) -> None:
         """Send a notification to the server."""
-        if not self._is_connected() or not self._stdin:
+        # Allow notifications during INITIALIZING state (for the initialized notification)
+        if (
+            self._connection_state
+            not in [ConnectionState.CONNECTED, ConnectionState.INITIALIZING]
+            or not self._stdin
+        ):
             raise ConnectionError("Server not connected")
 
         try:

agentle/parsing/parsers/docx.py

@@ -20,6 +20,7 @@ from typing import Literal, Any
 from rsb.models.field import Field
 
 
+from agentle.generations.models.generation.generation_config import GenerationConfig
 from agentle.generations.models.message_parts.file import FilePart
 from agentle.generations.models.structured_outputs_store.visual_media_description import (
     VisualMediaDescription,
@@ -182,6 +183,9 @@ class DocxFileParser(DocumentParser):
     Note: When this is enabled, most other configuration options are ignored as the AI handles all processing.
     """
 
+    max_output_tokens: int | None = Field(default=None)
+    """Maximum number of tokens to generate in the response."""
+
     async def parse_async(
         self,
         document_path: str,
@@ -517,6 +521,9 @@ class DocxFileParser(DocumentParser):
                                             "Output clear, concise descriptions suitable for a 'Visual Content' section."
                                         ),
                                         response_schema=VisualMediaDescription,
+                                        generation_config=GenerationConfig(
+                                            max_output_tokens=self.max_output_tokens
+                                        ),
                                     )
                                     page_description = agent_response.parsed.md
                                     image_cache[page_hash] = (page_description, "")
@@ -663,6 +670,7 @@ class DocxFileParser(DocumentParser):
                 model=self.model,
                 use_native_pdf_processing=True,
                 strategy=self.strategy,
+                max_output_tokens=self.max_output_tokens,
             )
 
             logger.debug("Delegating to PDFFileParser with native processing")

agentle/parsing/parsers/file_parser.py

@@ -261,6 +261,9 @@ class FileParser(DocumentParser):
     Note: When this is enabled, most other configuration options are ignored as the AI handles all processing.
     """
 
+    max_output_tokens: int | None = Field(default=None)
+    """Maximum number of tokens to generate in the response."""
+
     async def parse_async(self, document_path: str) -> ParsedFile:
         """
         Asynchronously parse a document using the appropriate parser for its file type.
@@ -378,4 +381,5 @@ class FileParser(DocumentParser):
             use_native_docx_processing=self.use_native_docx_processing,
             strategy=self.strategy,
             model=self.model,
+            max_output_tokens=self.max_output_tokens,
         ).parse_async(document_path=str(resolved_path))

agentle/parsing/parsers/pdf.py

@@ -258,6 +258,9 @@ class PDFFileParser(DocumentParser):
     # Metrics state
     last_parse_metrics: PDFParseMetrics | None = None
 
+    max_output_tokens: int | None = Field(default=None)
+    """Maximum number of tokens to generate in the response."""
+
     async def parse_async(self, document_path: str) -> ParsedFile:
         """
         Asynchronously parse a PDF document and convert it to a structured representation.
@@ -739,6 +742,9 @@ class PDFFileParser(DocumentParser):
                             file_part,
                             developer_prompt=developer_prompt,
                             response_schema=VisualMediaDescription,
+                            generation_config=GenerationConfig(
+                                max_output_tokens=self.max_output_tokens
+                            ),
                         ),
                         timeout=self.image_description_timeout,
                     )
@@ -855,7 +861,7 @@ class PDFFileParser(DocumentParser):
                 prompt=[pdf_file_part, prompt],
                 response_schema=PDFPageExtraction,
                 generation_config=GenerationConfig(
-                    timeout_s=300.0,
+                    timeout_s=300.0, max_output_tokens=self.max_output_tokens
                 ),
                 model=self.model,
             )

agentle/storage/__init__.py

@@ -0,0 +1,11 @@
+"""Storage module for file management."""
+
+from agentle.storage.file_storage_manager import FileStorageManager
+from agentle.storage.local_file_storage_manager import LocalFileStorageManager
+from agentle.storage.s3_file_storage_manager import S3FileStorageManager
+
+__all__ = [
+    "FileStorageManager",
+    "LocalFileStorageManager",
+    "S3FileStorageManager",
+]

agentle/storage/file_storage_manager.py

@@ -0,0 +1,44 @@
+"""Abstract file storage manager interface."""
+
+from abc import ABC, abstractmethod
+
+
+class FileStorageManager(ABC):
+    """Interface for file storage management."""
+
+    @abstractmethod
+    async def upload_file(self, file_data: bytes, filename: str, mime_type: str) -> str:
+        """
+        Upload file to storage and return public URL.
+
+        Args:
+            file_data: The file content as bytes
+            filename: The filename to use for storage
+            mime_type: The MIME type of the file
+
+        Returns:
+            Public URL to access the uploaded file
+
+        Raises:
+            FileStorageError: If upload fails
+        """
+        pass
+
+    @abstractmethod
+    async def delete_file(self, file_url: str) -> bool:
+        """
+        Delete file from storage by URL.
+
+        Args:
+            file_url: The public URL of the file to delete
+
+        Returns:
+            True if deletion was successful, False otherwise
+        """
+        pass
+
+
+class FileStorageError(Exception):
+    """Exception raised for file storage operations."""
+
+    pass

agentle/storage/local_file_storage_manager.py

@@ -0,0 +1,122 @@
+"""Local file storage manager implementation."""
+
+import logging
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+from agentle.storage.file_storage_manager import FileStorageError, FileStorageManager
+
+logger = logging.getLogger(__name__)
+
+
+class LocalFileStorageManager(FileStorageManager):
+    """Local filesystem implementation of file storage manager."""
+
+    def __init__(
+        self,
+        storage_dir: str | Path = "./storage",
+        base_url: str = "http://localhost:8000",
+        create_dirs: bool = True,
+    ):
+        """
+        Initialize local file storage manager.
+
+        Args:
+            storage_dir: Directory to store files
+            base_url: Base URL for accessing files (e.g., "http://localhost:8000")
+            create_dirs: Whether to create storage directory if it doesn't exist
+        """
+        self.storage_dir = Path(storage_dir)
+        self.base_url = base_url.rstrip("/")
+
+        if create_dirs:
+            self.storage_dir.mkdir(parents=True, exist_ok=True)
+            logger.info(f"Created storage directory: {self.storage_dir}")
+
+        logger.info(f"LocalFileStorageManager initialized: {self.storage_dir}")
+
+    async def upload_file(self, file_data: bytes, filename: str, mime_type: str) -> str:
+        """Upload file to local storage and return public URL."""
+        try:
+            # Ensure filename is safe
+            safe_filename = self._make_filename_safe(filename)
+            file_path = self.storage_dir / safe_filename
+
+            logger.debug(
+                f"Uploading file to local storage: {file_path} ({len(file_data)} bytes)"
+            )
+
+            # Write file to disk
+            with open(file_path, "wb") as f:
+                f.write(file_data)
+
+            # Generate public URL
+            url = f"{self.base_url}/files/{safe_filename}"
+
+            logger.info(f"File uploaded successfully: {url}")
+            return url
+
+        except OSError as e:
+            error_msg = f"Failed to write file to local storage: {e}"
+            logger.error(error_msg)
+            raise FileStorageError(error_msg) from e
+        except Exception as e:
+            error_msg = f"Unexpected error uploading to local storage: {e}"
+            logger.error(error_msg)
+            raise FileStorageError(error_msg) from e
+
+    async def delete_file(self, file_url: str) -> bool:
+        """Delete file from local storage by URL."""
+        try:
+            # Extract filename from URL
+            if "/files/" in file_url:
+                filename = file_url.split("/files/")[-1]
+            else:
+                logger.warning(f"Could not extract filename from URL: {file_url}")
+                return False
+
+            file_path = self.storage_dir / filename
+
+            if not file_path.exists():
+                logger.warning(f"File not found: {file_path}")
+                return False
+
+            logger.debug(f"Deleting file from local storage: {file_path}")
+
+            file_path.unlink()
+
+            logger.info(f"File deleted successfully: {filename}")
+            return True
+
+        except OSError as e:
+            logger.error(f"Failed to delete file from local storage: {e}")
+            return False
+        except Exception as e:
+            logger.error(f"Unexpected error deleting from local storage: {e}")
+            return False
+
+    def _make_filename_safe(self, filename: str) -> str:
+        """Make filename safe for filesystem."""
+        # Remove or replace unsafe characters
+        safe_chars = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789.-_"
+        safe_filename = "".join(c if c in safe_chars else "_" for c in filename)
+
+        # Ensure it's not empty and has reasonable length
+        if not safe_filename or len(safe_filename) > 255:
+            timestamp = int(time.time())
+            safe_filename = f"file_{timestamp}"
+
+        return safe_filename
+
+    def get_storage_info(self) -> dict[str, Any]:
+        """Get information about the storage configuration."""
+        return {
+            "storage_dir": str(self.storage_dir),
+            "base_url": self.base_url,
+            "exists": self.storage_dir.exists(),
+            "is_writable": os.access(self.storage_dir, os.W_OK)
+            if self.storage_dir.exists()
+            else False,
+        }

agentle/storage/s3_file_storage_manager.py

@@ -0,0 +1,124 @@
+"""S3 file storage manager implementation."""
+
+import logging
+from typing import Any
+
+try:
+    import boto3
+    from botocore.exceptions import ClientError
+
+    has_boto3 = True
+except ImportError:
+    boto3 = None  # type: ignore
+    ClientError = Exception  # type: ignore
+    has_boto3 = False
+
+from agentle.storage.file_storage_manager import FileStorageManager, FileStorageError
+
+logger = logging.getLogger(__name__)
+
+
+class S3FileStorageManager(FileStorageManager):
+    """S3 implementation of file storage manager."""
+
+    def __init__(
+        self,
+        bucket_name: str,
+        region: str = "us-east-1",
+        aws_access_key_id: str | None = None,
+        aws_secret_access_key: str | None = None,
+        endpoint_url: str | None = None,
+    ):
+        """
+        Initialize S3 file storage manager.
+
+        Args:
+            bucket_name: S3 bucket name
+            region: AWS region
+            aws_access_key_id: AWS access key (optional, uses default credentials if not provided)
+            aws_secret_access_key: AWS secret key (optional, uses default credentials if not provided)
+            endpoint_url: Custom S3 endpoint URL (for S3-compatible services like MinIO)
+        """
+        if not has_boto3 or boto3 is None:
+            raise ImportError(
+                "boto3 is required for S3FileStorageManager. "
+                + "Install it with: pip install boto3"
+            )
+
+        self.bucket_name = bucket_name
+        self.region = region
+
+        # Configure S3 client
+        client_kwargs: dict[str, Any] = {"region_name": region}
+
+        if aws_access_key_id and aws_secret_access_key:
+            client_kwargs.update(
+                {
+                    "aws_access_key_id": aws_access_key_id,
+                    "aws_secret_access_key": aws_secret_access_key,
+                }
+            )
+
+        if endpoint_url:
+            client_kwargs["endpoint_url"] = endpoint_url
+
+        self.s3_client = boto3.client("s3", **client_kwargs)
+
+        logger.info(f"S3FileStorageManager initialized for bucket: {bucket_name}")
+
+    async def upload_file(self, file_data: bytes, filename: str, mime_type: str) -> str:
+        """Upload file to S3 and return public URL."""
+        try:
+            logger.debug(f"Uploading file to S3: {filename} ({len(file_data)} bytes)")
+
+            self.s3_client.put_object(
+                Bucket=self.bucket_name,
+                Key=filename,
+                Body=file_data,
+                ContentType=mime_type,
+                ACL="public-read",  # Make file publicly accessible
+            )
+
+            # Generate public URL
+            if self.s3_client.meta.region_name == "us-east-1":
+                url = f"https://{self.bucket_name}.s3.amazonaws.com/{filename}"
+            else:
+                url = f"https://{self.bucket_name}.s3.{self.region}.amazonaws.com/{filename}"
+
+            logger.info(f"File uploaded successfully: {url}")
+            return url
+
+        except ClientError as e:
+            error_msg = f"Failed to upload file to S3: {e}"
+            logger.error(error_msg)
+            raise FileStorageError(error_msg) from e
+        except Exception as e:
+            error_msg = f"Unexpected error uploading to S3: {e}"
+            logger.error(error_msg)
+            raise FileStorageError(error_msg) from e
+
+    async def delete_file(self, file_url: str) -> bool:
+        """Delete file from S3 by URL."""
+        try:
+            # Extract key from URL
+            if f"s3.{self.region}.amazonaws.com" in file_url:
+                key = file_url.split(f"s3.{self.region}.amazonaws.com/")[-1]
+            elif "s3.amazonaws.com" in file_url:
+                key = file_url.split("s3.amazonaws.com/")[-1]
+            else:
+                logger.warning(f"Could not extract S3 key from URL: {file_url}")
+                return False
+
+            logger.debug(f"Deleting file from S3: {key}")
+
+            self.s3_client.delete_object(Bucket=self.bucket_name, Key=key)
+
+            logger.info(f"File deleted successfully: {key}")
+            return True
+
+        except ClientError as e:
+            logger.error(f"Failed to delete file from S3: {e}")
+            return False
+        except Exception as e:
+            logger.error(f"Unexpected error deleting from S3: {e}")
+            return False

agentle/tts/audio_format.py

@@ -0,0 +1,6 @@
+from typing import Literal
+
+
+AudioFormat = Literal[
+    "audio/mpeg", "audio/wav", "audio/opus", "audio/basic", "application/octet-stream"
+]