agent-runtime-core 0.7.1__py3-none-any.whl → 0.8.0__py3-none-any.whl

agent_runtime_core/files/tools.py

@@ -0,0 +1,317 @@
+"""
+File read/write tools for agents.
+
+Provides sandboxed file access tools that agents can use to read and write files.
+All file operations are restricted to configured allowed directories.
+
+Example:
+    from agent_runtime_core.files.tools import FileTools, FileToolsConfig
+
+    config = FileToolsConfig(
+        allowed_directories=["/app/uploads", "/app/outputs"],
+        max_file_size_bytes=50 * 1024 * 1024,  # 50MB
+    )
+    tools = FileTools(config)
+
+    # Read a file
+    result = await tools.read_file("document.pdf")
+
+    # Write a file
+    await tools.write_file("output.txt", "Hello, world!")
+"""
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional, Union
+import base64
+
+from .base import FileProcessorRegistry, ProcessingOptions, ProcessedFile, FileType
+
+
+@dataclass
+class FileToolsConfig:
+    """Configuration for file tools."""
+    # Sandboxing
+    allowed_directories: list[str] = field(default_factory=lambda: ["."])
+
+    # Size limits
+    max_file_size_bytes: int = 100 * 1024 * 1024  # 100MB default
+    max_write_size_bytes: int = 100 * 1024 * 1024  # 100MB default
+
+    # Processing options
+    use_ocr: bool = False
+    ocr_provider: Optional[str] = None
+    use_vision: bool = False
+    vision_provider: Optional[str] = None
+
+    # Write options
+    allow_overwrite: bool = False
+    create_directories: bool = True
+
+
+def get_file_read_schema() -> dict[str, Any]:
+    """Get the tool schema for file_read in OpenAI format."""
+    from ..tools import ToolSchemaBuilder
+
+    return (
+        ToolSchemaBuilder("file_read")
+        .description(
+            "Read and process a file. Extracts text content from various file types "
+            "including PDF, DOCX, images (with optional OCR), spreadsheets, and text files. "
+            "Returns the extracted text and metadata."
+        )
+        .param("path", "string", "Path to the file to read", required=True)
+        .param("use_ocr", "boolean", "Use OCR for images/scanned documents", default=False)
+        .param("ocr_provider", "string", "OCR provider to use",
+               enum=["tesseract", "google", "aws", "azure"])
+        .param("use_vision", "boolean", "Use AI vision for image analysis", default=False)
+        .param("vision_provider", "string", "Vision AI provider to use",
+               enum=["openai", "anthropic", "gemini"])
+        .param("vision_prompt", "string", "Custom prompt for vision analysis")
+        .to_openai_format()
+    )
+
+
+def get_file_write_schema() -> dict[str, Any]:
+    """Get the tool schema for file_write in OpenAI format."""
+    from ..tools import ToolSchemaBuilder
+
+    return (
+        ToolSchemaBuilder("file_write")
+        .description(
+            "Write content to a file. Can write text content or base64-encoded binary data. "
+            "The file path must be within allowed directories."
+        )
+        .param("path", "string", "Path where the file should be written", required=True)
+        .param("content", "string", "Content to write (text or base64 for binary)", required=True)
+        .param("encoding", "string", "Content encoding", enum=["text", "base64"], default="text")
+        .param("overwrite", "boolean", "Whether to overwrite existing files", default=False)
+        .to_openai_format()
+    )
+
+
+class FileTools:
+    """
+    File read/write tools for agents with sandboxing.
+
+    All file operations are restricted to configured allowed directories.
+    """
+
+    def __init__(
+        self,
+        config: Optional[FileToolsConfig] = None,
+        registry: Optional[FileProcessorRegistry] = None,
+    ):
+        self.config = config or FileToolsConfig()
+        self.registry = registry
+        if self.registry is None:
+            self.registry = FileProcessorRegistry()
+            self.registry.auto_register()
+
+    def _resolve_path(self, path: str) -> Path:
+        """Resolve and validate a file path against allowed directories."""
+        # Resolve to absolute path
+        resolved = Path(path).resolve()
+
+        # Check if path is within any allowed directory
+        for allowed_dir in self.config.allowed_directories:
+            allowed_path = Path(allowed_dir).resolve()
+            try:
+                resolved.relative_to(allowed_path)
+                return resolved
+            except ValueError:
+                continue
+
+        raise PermissionError(
+            f"Access denied: '{path}' is not within allowed directories. "
+            f"Allowed: {self.config.allowed_directories}"
+        )
+
+    async def read_file(
+        self,
+        path: str,
+        use_ocr: bool = False,
+        ocr_provider: Optional[str] = None,
+        use_vision: bool = False,
+        vision_provider: Optional[str] = None,
+        vision_prompt: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """
+        Read and process a file.
+
+        Args:
+            path: Path to file
+            use_ocr: Whether to use OCR for images/scanned documents
+            ocr_provider: OCR provider (tesseract, google, aws, azure)
+            use_vision: Whether to use AI vision analysis
+            vision_provider: Vision provider (openai, anthropic, gemini)
+            vision_prompt: Custom prompt for vision analysis
+
+        Returns:
+            Dict with extracted text, metadata, and processing info
+        """
+        resolved_path = self._resolve_path(path)
+
+        if not resolved_path.exists():
+            raise FileNotFoundError(f"File not found: {path}")
+
+        # Check file size
+        file_size = resolved_path.stat().st_size
+        if file_size > self.config.max_file_size_bytes:
+            raise ValueError(
+                f"File size ({file_size} bytes) exceeds limit "
+                f"({self.config.max_file_size_bytes} bytes)"
+            )
+
+        # Read file content
+        content = resolved_path.read_bytes()
+
+        # Build processing options
+        options = ProcessingOptions(
+            max_size_bytes=self.config.max_file_size_bytes,
+            use_ocr=use_ocr or self.config.use_ocr,
+            ocr_provider=ocr_provider or self.config.ocr_provider,
+            use_vision=use_vision or self.config.use_vision,
+            vision_provider=vision_provider or self.config.vision_provider,
+            vision_prompt=vision_prompt,
+        )
+
+        # Process file
+        result = await self.registry.process(resolved_path.name, content, options)
+
+        # Return as dict for tool response
+        return {
+            "filename": result.filename,
+            "file_type": result.file_type.value,
+            "mime_type": result.mime_type,
+            "size_bytes": result.size_bytes,
+            "text": result.text,
+            "metadata": result.metadata,
+            "ocr_text": result.ocr_text,
+            "vision_description": result.vision_description,
+            "warnings": result.warnings,
+        }
+
+    async def write_file(
+        self,
+        path: str,
+        content: str,
+        encoding: str = "text",
+        overwrite: bool = False,
+    ) -> dict[str, Any]:
+        """
+        Write content to a file.
+
+        Args:
+            path: Path where the file should be written
+            content: Content to write (text or base64 for binary)
+            encoding: Content encoding ("text" or "base64")
+            overwrite: Whether to overwrite existing files
+
+        Returns:
+            Dict with file info after writing
+        """
+        resolved_path = self._resolve_path(path)
+
+        # Check if file exists and overwrite is allowed
+        if resolved_path.exists():
+            if not (overwrite or self.config.allow_overwrite):
+                raise FileExistsError(
+                    f"File already exists: {path}. Set overwrite=True to replace."
+                )
+
+        # Decode content
+        if encoding == "base64":
+            try:
+                data = base64.b64decode(content)
+            except Exception as e:
+                raise ValueError(f"Invalid base64 content: {e}")
+        else:
+            data = content.encode("utf-8")
+
+        # Check size limit
+        if len(data) > self.config.max_write_size_bytes:
+            raise ValueError(
+                f"Content size ({len(data)} bytes) exceeds write limit "
+                f"({self.config.max_write_size_bytes} bytes)"
+            )
+
+        # Create parent directories if needed
+        if self.config.create_directories:
+            resolved_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Write file
+        resolved_path.write_bytes(data)
+
+        return {
+            "success": True,
+            "path": str(resolved_path),
+            "size_bytes": len(data),
+            "encoding": encoding,
+            "overwritten": resolved_path.exists() and (overwrite or self.config.allow_overwrite),
+        }
+
+    async def list_files(
+        self,
+        directory: str = ".",
+        pattern: str = "*",
+        recursive: bool = False,
+    ) -> dict[str, Any]:
+        """
+        List files in a directory.
+
+        Args:
+            directory: Directory to list (must be within allowed directories)
+            pattern: Glob pattern to filter files
+            recursive: Whether to search recursively
+
+        Returns:
+            Dict with list of files
+        """
+        resolved_dir = self._resolve_path(directory)
+
+        if not resolved_dir.is_dir():
+            raise NotADirectoryError(f"Not a directory: {directory}")
+
+        if recursive:
+            files = list(resolved_dir.rglob(pattern))
+        else:
+            files = list(resolved_dir.glob(pattern))
+
+        # Filter to only files (not directories)
+        files = [f for f in files if f.is_file()]
+
+        return {
+            "directory": str(resolved_dir),
+            "pattern": pattern,
+            "recursive": recursive,
+            "count": len(files),
+            "files": [
+                {
+                    "name": f.name,
+                    "path": str(f),
+                    "size_bytes": f.stat().st_size,
+                    "modified": f.stat().st_mtime,
+                }
+                for f in files[:100]  # Limit to 100 files
+            ],
+            "truncated": len(files) > 100,
+        }
+
+
+def get_file_list_schema() -> dict[str, Any]:
+    """Get the tool schema for file_list in OpenAI format."""
+    from ..tools import ToolSchemaBuilder
+
+    return (
+        ToolSchemaBuilder("file_list")
+        .description(
+            "List files in a directory. Returns file names, sizes, and modification times. "
+            "The directory must be within allowed directories."
+        )
+        .param("directory", "string", "Directory to list", default=".")
+        .param("pattern", "string", "Glob pattern to filter files", default="*")
+        .param("recursive", "boolean", "Search recursively", default=False)
+        .to_openai_format()
+    )

agent_runtime_core/files/vision.py

@@ -0,0 +1,360 @@
+"""
+AI Vision providers for image analysis.
+
+Supports multiple AI vision providers:
+- OpenAI GPT-4 Vision
+- Anthropic Claude Vision
+- Google Gemini Vision
+
+All providers are optional - install the corresponding library to use.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+import base64
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class VisionResult:
+    """Result from AI vision analysis."""
+
+    description: str
+    """Natural language description of the image."""
+
+    labels: list[str] = field(default_factory=list)
+    """Detected labels/objects in the image."""
+
+    raw_response: Any = None
+    """Raw response from the vision provider."""
+
+    model: str = ""
+    """Model used for analysis."""
+
+    usage: dict[str, int] = field(default_factory=dict)
+    """Token usage information."""
+
+
+class VisionProvider(ABC):
+    """Abstract base class for AI vision providers."""
+
+    name: str = "base"
+
+    @abstractmethod
+    async def analyze_image(
+        self,
+        image_data: bytes,
+        prompt: str = "Describe this image in detail.",
+        mime_type: str = "image/png",
+        **kwargs,
+    ) -> VisionResult:
+        """
+        Analyze an image using AI vision.
+
+        Args:
+            image_data: Raw image bytes
+            prompt: Question or instruction for the vision model
+            mime_type: MIME type of the image
+            **kwargs: Provider-specific options
+
+        Returns:
+            VisionResult with description and metadata
+        """
+        pass
+
+    @classmethod
+    def is_available(cls) -> bool:
+        """Check if this provider's dependencies are installed."""
+        return False
+
+    def _encode_image(self, image_data: bytes) -> str:
+        """Encode image data to base64."""
+        return base64.b64encode(image_data).decode("utf-8")
+
+
+class OpenAIVision(VisionProvider):
+    """OpenAI GPT-4 Vision provider."""
+
+    name = "openai"
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        model: str = "gpt-4o",
+        max_tokens: int = 1024,
+    ):
+        self.api_key = api_key
+        self.model = model
+        self.max_tokens = max_tokens
+        self._client = None
+
+    @classmethod
+    def is_available(cls) -> bool:
+        try:
+            import openai  # noqa: F401
+            return True
+        except ImportError:
+            return False
+
+    def _get_client(self):
+        if self._client is None:
+            try:
+                from openai import AsyncOpenAI
+                self._client = AsyncOpenAI(api_key=self.api_key)
+            except ImportError:
+                raise ImportError(
+                    "OpenAI library not installed. Install with: pip install openai"
+                )
+        return self._client
+
+    async def analyze_image(
+        self,
+        image_data: bytes,
+        prompt: str = "Describe this image in detail.",
+        mime_type: str = "image/png",
+        **kwargs,
+    ) -> VisionResult:
+        client = self._get_client()
+
+        base64_image = self._encode_image(image_data)
+        data_url = f"data:{mime_type};base64,{base64_image}"
+
+        response = await client.chat.completions.create(
+            model=kwargs.get("model", self.model),
+            max_tokens=kwargs.get("max_tokens", self.max_tokens),
+            messages=[
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": prompt},
+                        {"type": "image_url", "image_url": {"url": data_url}},
+                    ],
+                }
+            ],
+        )
+
+        description = response.choices[0].message.content or ""
+
+        return VisionResult(
+            description=description,
+            model=response.model,
+            raw_response=response.model_dump(),
+            usage={
+                "prompt_tokens": response.usage.prompt_tokens if response.usage else 0,
+                "completion_tokens": response.usage.completion_tokens if response.usage else 0,
+            },
+        )
+
+
+class AnthropicVision(VisionProvider):
+    """Anthropic Claude Vision provider."""
+
+    name = "anthropic"
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        model: str = "claude-sonnet-4-20250514",
+        max_tokens: int = 1024,
+    ):
+        self.api_key = api_key
+        self.model = model
+        self.max_tokens = max_tokens
+        self._client = None
+
+
+
+    @classmethod
+    def is_available(cls) -> bool:
+        try:
+            import anthropic  # noqa: F401
+            return True
+        except ImportError:
+            return False
+
+    def _get_client(self):
+        if self._client is None:
+            try:
+                from anthropic import AsyncAnthropic
+                self._client = AsyncAnthropic(api_key=self.api_key)
+            except ImportError:
+                raise ImportError(
+                    "Anthropic library not installed. Install with: pip install anthropic"
+                )
+        return self._client
+
+    async def analyze_image(
+        self,
+        image_data: bytes,
+        prompt: str = "Describe this image in detail.",
+        mime_type: str = "image/png",
+        **kwargs,
+    ) -> VisionResult:
+        client = self._get_client()
+
+        base64_image = self._encode_image(image_data)
+
+        response = await client.messages.create(
+            model=kwargs.get("model", self.model),
+            max_tokens=kwargs.get("max_tokens", self.max_tokens),
+            messages=[
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "image",
+                            "source": {
+                                "type": "base64",
+                                "media_type": mime_type,
+                                "data": base64_image,
+                            },
+                        },
+                        {"type": "text", "text": prompt},
+                    ],
+                }
+            ],
+        )
+
+        description = response.content[0].text if response.content else ""
+
+        return VisionResult(
+            description=description,
+            model=response.model,
+            raw_response=response.model_dump(),
+            usage={
+                "input_tokens": response.usage.input_tokens if response.usage else 0,
+                "output_tokens": response.usage.output_tokens if response.usage else 0,
+            },
+        )
+
+
+class GeminiVision(VisionProvider):
+    """Google Gemini Vision provider."""
+
+    name = "gemini"
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        model: str = "gemini-2.0-flash",
+    ):
+        self.api_key = api_key
+        self.model = model
+        self._client = None
+
+    @classmethod
+    def is_available(cls) -> bool:
+        try:
+            import google.generativeai  # noqa: F401
+            return True
+        except ImportError:
+            return False
+
+    def _get_client(self):
+        if self._client is None:
+            try:
+                import google.generativeai as genai
+                if self.api_key:
+                    genai.configure(api_key=self.api_key)
+                self._client = genai.GenerativeModel(self.model)
+            except ImportError:
+                raise ImportError(
+                    "Google Generative AI library not installed. "
+                    "Install with: pip install google-generativeai"
+                )
+        return self._client
+
+    async def analyze_image(
+        self,
+        image_data: bytes,
+        prompt: str = "Describe this image in detail.",
+        mime_type: str = "image/png",
+        **kwargs,
+    ) -> VisionResult:
+        client = self._get_client()
+
+        # Gemini uses PIL Image or inline data
+        image_part = {
+            "mime_type": mime_type,
+            "data": image_data,
+        }
+
+        # Gemini's generate_content is sync, wrap it
+        import asyncio
+        response = await asyncio.to_thread(
+            client.generate_content,
+            [prompt, image_part],
+        )
+
+        description = response.text if response.text else ""
+
+        usage = {}
+        if hasattr(response, "usage_metadata") and response.usage_metadata:
+            usage = {
+                "prompt_tokens": response.usage_metadata.prompt_token_count,
+                "completion_tokens": response.usage_metadata.candidates_token_count,
+            }
+
+        return VisionResult(
+            description=description,
+            model=kwargs.get("model", self.model),
+            raw_response=response,
+            usage=usage,
+        )
+
+
+# Registry of all vision providers
+VISION_PROVIDERS: dict[str, type[VisionProvider]] = {
+    "openai": OpenAIVision,
+    "anthropic": AnthropicVision,
+    "gemini": GeminiVision,
+}
+
+
+def get_vision_provider(
+    name: str,
+    **kwargs,
+) -> VisionProvider:
+    """
+    Get a vision provider by name.
+
+    Args:
+        name: Provider name ('openai', 'anthropic', 'gemini')
+        **kwargs: Provider-specific configuration
+
+    Returns:
+        Configured VisionProvider instance
+
+    Raises:
+        ValueError: If provider name is unknown
+        ImportError: If provider dependencies are not installed
+    """
+    if name not in VISION_PROVIDERS:
+        available = list(VISION_PROVIDERS.keys())
+        raise ValueError(f"Unknown vision provider: {name}. Available: {available}")
+
+    provider_class = VISION_PROVIDERS[name]
+
+    if not provider_class.is_available():
+        raise ImportError(
+            f"Vision provider '{name}' dependencies not installed. "
+            f"Check the provider documentation for installation instructions."
+        )
+
+    return provider_class(**kwargs)
+
+
+def get_available_vision_providers() -> list[str]:
+    """
+    Get list of vision providers that have their dependencies installed.
+
+    Returns:
+        List of available provider names
+    """
+    return [
+        name for name, cls in VISION_PROVIDERS.items()
+        if cls.is_available()
+    ]