ostruct-cli 0.7.1__py3-none-any.whl → 0.8.0__py3-none-any.whl

ostruct/cli/code_interpreter.py

@@ -0,0 +1,238 @@
+"""Code Interpreter integration for ostruct CLI.
+
+This module provides support for uploading files to OpenAI's Code Interpreter
+and integrating code execution capabilities with the OpenAI Responses API.
+"""
+
+import logging
+import os
+from pathlib import Path
+from typing import Any, Dict, List
+
+from openai import AsyncOpenAI
+
+logger = logging.getLogger(__name__)
+
+
+class CodeInterpreterManager:
+    """Manager for Code Interpreter file uploads and tool integration."""
+
+    def __init__(self, client: AsyncOpenAI):
+        """Initialize Code Interpreter manager.
+
+        Args:
+            client: AsyncOpenAI client instance
+        """
+        self.client = client
+        self.uploaded_file_ids: List[str] = []
+
+    async def upload_files_for_code_interpreter(
+        self, files: List[str]
+    ) -> List[str]:
+        """Upload files for Code Interpreter (validated working pattern).
+
+        This method uploads files to OpenAI's file storage with the correct
+        purpose for Code Interpreter usage.
+
+        Args:
+            files: List of file paths to upload
+
+        Returns:
+            List of file IDs from successful uploads
+
+        Raises:
+            FileNotFoundError: If a file doesn't exist
+            Exception: If upload fails
+        """
+        file_ids = []
+
+        for file_path in files:
+            try:
+                # Validate file exists
+                if not os.path.exists(file_path):
+                    raise FileNotFoundError(f"File not found: {file_path}")
+
+                # Get file info
+                file_size = os.path.getsize(file_path)
+                logger.debug(
+                    f"Uploading file: {file_path} ({file_size} bytes)"
+                )
+
+                # Upload with correct purpose for Code Interpreter
+                with open(file_path, "rb") as f:
+                    file_obj = await self.client.files.create(
+                        file=f,
+                        purpose="assistants",  # Validated correct purpose
+                    )
+                    file_ids.append(file_obj.id)
+                    logger.debug(
+                        f"Successfully uploaded {file_path} with ID: {file_obj.id}"
+                    )
+
+            except Exception as e:
+                logger.error(f"Failed to upload file {file_path}: {e}")
+                # Clean up any successfully uploaded files on error
+                await self._cleanup_uploaded_files(file_ids)
+                raise
+
+        # Store for potential cleanup
+        self.uploaded_file_ids.extend(file_ids)
+        return file_ids
+
+    def build_tool_config(self, file_ids: List[str]) -> dict:
+        """Build Code Interpreter tool configuration.
+
+        Creates a tool configuration compatible with the OpenAI Responses API
+        for Code Interpreter functionality.
+
+        Args:
+            file_ids: List of uploaded file IDs
+
+        Returns:
+            Tool configuration dict for Responses API
+        """
+        return {
+            "type": "code_interpreter",
+            "container": {"type": "auto", "file_ids": file_ids},
+        }
+
+    async def download_generated_files(
+        self, response_file_ids: List[str], output_dir: str = "."
+    ) -> List[str]:
+        """Download files generated by Code Interpreter.
+
+        Args:
+            response_file_ids: List of file IDs from Code Interpreter response
+            output_dir: Directory to save downloaded files
+
+        Returns:
+            List of local file paths where files were saved
+
+        Raises:
+            Exception: If download fails
+        """
+        downloaded_paths = []
+        output_path = Path(output_dir)
+        output_path.mkdir(exist_ok=True)
+
+        for file_id in response_file_ids:
+            try:
+                # Get file info
+                file_info = await self.client.files.retrieve(file_id)
+                filename = (
+                    file_info.filename or f"generated_file_{file_id[:8]}.dat"
+                )
+
+                # Download file content
+                file_content = await self.client.files.content(file_id)
+
+                # Save to local file
+                local_path = output_path / filename
+                with open(local_path, "wb") as f:
+                    f.write(file_content.read())
+
+                downloaded_paths.append(str(local_path))
+                logger.debug(f"Downloaded generated file: {local_path}")
+
+            except Exception as e:
+                logger.error(f"Failed to download file {file_id}: {e}")
+                raise
+
+        return downloaded_paths
+
+    async def cleanup_uploaded_files(self) -> None:
+        """Clean up uploaded files from OpenAI storage.
+
+        This method removes files that were uploaded during the session
+        to avoid accumulating files in the user's OpenAI storage.
+        """
+        await self._cleanup_uploaded_files(self.uploaded_file_ids)
+        self.uploaded_file_ids.clear()
+
+    async def _cleanup_uploaded_files(self, file_ids: List[str]) -> None:
+        """Internal method to clean up specific file IDs.
+
+        Args:
+            file_ids: List of file IDs to delete
+        """
+        for file_id in file_ids:
+            try:
+                await self.client.files.delete(file_id)
+                logger.debug(f"Cleaned up uploaded file: {file_id}")
+            except Exception as e:
+                logger.warning(f"Failed to clean up file {file_id}: {e}")
+
+    def validate_files_for_upload(self, files: List[str]) -> List[str]:
+        """Validate files are suitable for Code Interpreter upload.
+
+        Args:
+            files: List of file paths to validate
+
+        Returns:
+            List of validation error messages, empty if all files are valid
+        """
+        errors = []
+
+        # Common file types supported by Code Interpreter
+        supported_extensions = {
+            ".py",
+            ".txt",
+            ".csv",
+            ".json",
+            ".xlsx",
+            ".xls",
+            ".pdf",
+            ".docx",
+            ".md",
+            ".xml",
+            ".html",
+            ".js",
+            ".sql",
+            ".log",
+            ".yaml",
+            ".yml",
+            ".toml",
+            ".ini",
+        }
+
+        # Size limits (approximate - OpenAI has file size limits)
+        max_file_size = 100 * 1024 * 1024  # 100MB
+
+        for file_path in files:
+            try:
+                if not os.path.exists(file_path):
+                    errors.append(f"File not found: {file_path}")
+                    continue
+
+                # Check file size
+                file_size = os.path.getsize(file_path)
+                if file_size > max_file_size:
+                    errors.append(
+                        f"File too large: {file_path} ({file_size / 1024 / 1024:.1f}MB > 100MB)"
+                    )
+
+                # Check file extension
+                file_ext = Path(file_path).suffix.lower()
+                if file_ext not in supported_extensions:
+                    logger.warning(
+                        f"File extension {file_ext} may not be supported by Code Interpreter: {file_path}"
+                    )
+
+            except Exception as e:
+                errors.append(f"Error validating file {file_path}: {e}")
+
+        return errors
+
+    def get_container_limits_info(self) -> Dict[str, Any]:
+        """Get information about Code Interpreter container limits.
+
+        Returns:
+            Dictionary with container limit information
+        """
+        return {
+            "max_runtime_minutes": 20,
+            "idle_timeout_minutes": 2,
+            "max_file_size_mb": 100,
+            "supported_languages": ["python"],
+            "note": "Container expires after 20 minutes of runtime or 2 minutes of inactivity",
+        }

ostruct/cli/commands/__init__.py

@@ -0,0 +1,32 @@
+"""Command modules for ostruct CLI."""
+
+import click
+
+from .list_models import list_models
+from .quick_ref import quick_reference
+from .run import run
+from .update_registry import update_registry
+
+
+def create_command_group() -> click.Group:
+    """Create and configure the CLI command group with all commands."""
+    # Create the main CLI group
+    group = click.Group()
+
+    # Add all commands to the group
+    group.add_command(run)
+    group.add_command(quick_reference)
+    group.add_command(update_registry)
+    group.add_command(list_models)
+
+    return group
+
+
+# Export commands for easy importing
+__all__ = [
+    "run",
+    "quick_reference",
+    "update_registry",
+    "list_models",
+    "create_command_group",
+]

ostruct/cli/commands/list_models.py

@@ -0,0 +1,128 @@
+"""List models command for ostruct CLI."""
+
+import json
+import sys
+
+import click
+from openai_model_registry import ModelRegistry
+
+from ..exit_codes import ExitCode
+
+
+@click.command("list-models")
+@click.option(
+    "--format",
+    type=click.Choice(["table", "json", "simple"]),
+    default="table",
+    help="Output format for model list",
+)
+@click.option(
+    "--show-deprecated",
+    is_flag=True,
+    help="Include deprecated models in output",
+)
+def list_models(format: str = "table", show_deprecated: bool = False) -> None:
+    """List available models from the registry."""
+    try:
+        registry = ModelRegistry.get_instance()
+        models = registry.models
+
+        # Filter models if not showing deprecated
+        if not show_deprecated:
+            # Filter out deprecated models (this depends on registry implementation)
+            filtered_models = []
+            for model_id in models:
+                try:
+                    capabilities = registry.get_capabilities(model_id)
+                    # If we can get capabilities, it's likely not deprecated
+                    filtered_models.append(
+                        {
+                            "id": model_id,
+                            "context_window": capabilities.context_window,
+                            "max_output": capabilities.max_output_tokens,
+                        }
+                    )
+                except Exception:
+                    # Skip models that can't be accessed (likely deprecated)
+                    continue
+            models_data = filtered_models
+        else:
+            # Include all models
+            models_data = []
+            for model_id in models:
+                try:
+                    capabilities = registry.get_capabilities(model_id)
+                    models_data.append(
+                        {
+                            "id": model_id,
+                            "context_window": capabilities.context_window,
+                            "max_output": capabilities.max_output_tokens,
+                            "status": "active",
+                        }
+                    )
+                except Exception:
+                    models_data.append(
+                        {
+                            "id": model_id,
+                            "context_window": "N/A",
+                            "max_output": "N/A",
+                            "status": "deprecated",
+                        }
+                    )
+
+        if format == "table":
+            # Calculate dynamic column widths based on actual data
+            max_id_width = (
+                max(len(str(model["id"])) for model in models_data)
+                if models_data
+                else 8
+            )
+            max_id_width = max(max_id_width, len("Model ID"))
+
+            max_context_width = (
+                15  # Keep reasonable default for context window
+            )
+            max_output_width = 12  # Keep reasonable default for max output
+            status_width = 10  # Keep fixed for status
+
+            # Ensure minimum widths for readability
+            id_width = max(max_id_width, 8)
+
+            total_width = (
+                id_width
+                + max_context_width
+                + max_output_width
+                + status_width
+                + 6
+            )  # 6 for spacing
+
+            click.echo("Available Models:")
+            click.echo("-" * total_width)
+            click.echo(
+                f"{'Model ID':<{id_width}} {'Context Window':<{max_context_width}} {'Max Output':<{max_output_width}} {'Status':<{status_width}}"
+            )
+            click.echo("-" * total_width)
+            for model in models_data:
+                status = model.get("status", "active")
+                context = (
+                    f"{model['context_window']:,}"
+                    if isinstance(model["context_window"], int)
+                    else model["context_window"]
+                )
+                output = (
+                    f"{model['max_output']:,}"
+                    if isinstance(model["max_output"], int)
+                    else model["max_output"]
+                )
+                click.echo(
+                    f"{model['id']:<{id_width}} {context:<{max_context_width}} {output:<{max_output_width}} {status:<{status_width}}"
+                )
+        elif format == "json":
+            click.echo(json.dumps(models_data, indent=2))
+        else:  # simple
+            for model in models_data:
+                click.echo(model["id"])
+
+    except Exception as e:
+        click.echo(f"❌ Error listing models: {str(e)}")
+        sys.exit(ExitCode.API_ERROR.value)

ostruct/cli/commands/quick_ref.py

@@ -0,0 +1,50 @@
+"""Quick reference command for ostruct CLI."""
+
+import click
+
+
+@click.command("quick-ref")
+def quick_reference() -> None:
+    """Show quick reference for file routing and common usage patterns."""
+    quick_ref = """
+🚀 OSTRUCT QUICK REFERENCE
+
+📁 FILE ROUTING:
+  -ft FILE    📄 Template access only       (config files, small data)
+  -fc FILE    💻 Code Interpreter upload    (data files, scripts)
+  -fs FILE    🔍 File Search vector store   (documents, manuals)
+
+  -dt DIR     📁 Template directory         (config dirs, reference data)
+  -dc DIR     📂 Code execution directory   (datasets, code repos)
+  -ds DIR     📁 Search directory           (documentation, knowledge)
+
+🔄 ADVANCED ROUTING:
+  --file-for code-interpreter data.csv      Single tool, single file
+  --file-for file-search docs.pdf           Single tool, single file
+  --file-for code-interpreter shared.json --file-for file-search shared.json   Multi-tool routing
+
+🏷️  VARIABLES:
+  -V name=value                             Simple string variables
+  -J config='{"key":"value"}'               JSON structured data
+
+🔌 TOOLS:
+  --mcp-server label@https://server.com/sse MCP server integration
+  --timeout 7200                           2-hour timeout for long operations
+
+⚡ COMMON PATTERNS:
+  # Basic template rendering
+  ostruct run template.j2 schema.json -V env=prod
+
+  # Data analysis with Code Interpreter
+  ostruct run analysis.j2 schema.json -fc data.csv -V task=analyze
+
+  # Document search + processing
+  ostruct run search.j2 schema.json -fs docs/ -ft config.yaml
+
+  # Multi-tool workflow
+  ostruct run workflow.j2 schema.json -fc raw_data.csv -fs knowledge/ -ft config.json
+
+📖 Full help: ostruct run --help
+📖 Documentation: https://ostruct.readthedocs.io
+"""
+    click.echo(quick_ref)

ostruct/cli/commands/run.py

@@ -0,0 +1,137 @@
+"""Run command for ostruct CLI."""
+
+import asyncio
+import json
+import logging
+import sys
+from typing import Any
+
+import click
+
+from ..click_options import all_options
+from ..config import OstructConfig
+from ..errors import (
+    CLIError,
+    InvalidJSONError,
+    SchemaFileError,
+    SchemaValidationError,
+    handle_error,
+)
+from ..exit_codes import ExitCode
+from ..runner import run_cli_async
+from ..types import CLIParams
+
+logger = logging.getLogger(__name__)
+
+
+@click.command()
+@click.argument("task_template", type=click.Path(exists=True))
+@click.argument("schema_file", type=click.Path(exists=True))
+@all_options
+@click.pass_context
+def run(
+    ctx: click.Context,
+    task_template: str,
+    schema_file: str,
+    **kwargs: Any,
+) -> None:
+    """Run structured output generation with multi-tool integration.
+
+    \b
+    📁 FILE ROUTING OPTIONS:
+
+    Template Access Only:
+      -ft, --file-for-template FILE     Files available in template only
+      -dt, --dir-for-template DIR       Directories for template access
+
+    Code Interpreter (execution & analysis):
+      -fc, --file-for-code-interpreter FILE    Upload files for code execution
+      -dc, --dir-for-code-interpreter DIR      Upload directories for analysis
+
+    File Search (document retrieval):
+      -fs, --file-for-file-search FILE         Upload files for vector search
+      -ds, --dir-for-search DIR                Upload directories for search
+
+    Advanced Routing:
+      --file-for TOOL PATH              Route files to specific tools
+                                        Example: --file-for code-interpreter data.json
+
+    \b
+    🔧 TOOL INTEGRATION:
+
+    MCP Servers:
+      --mcp-server [LABEL@]URL          Connect to MCP server
+                                        Example: --mcp-server deepwiki@https://mcp.deepwiki.com/sse
+
+    \b
+    ⚡ EXAMPLES:
+
+    Basic usage:
+      ostruct run template.j2 schema.json -V name=value
+
+    Multi-tool explicit routing:
+      ostruct run analysis.j2 schema.json -fc data.csv -fs docs.pdf -ft config.yaml
+
+    Legacy compatibility (still works):
+      ostruct run template.j2 schema.json -f config main.py -d src ./src
+
+    \b
+    Arguments:
+      TASK_TEMPLATE  Path to Jinja2 template file
+      SCHEMA_FILE    Path to JSON schema file defining output structure
+    """
+    try:
+        # Convert Click parameters to typed dict
+        params: CLIParams = {
+            "task_file": task_template,
+            "task": None,
+            "schema_file": schema_file,
+        }
+        # Add all kwargs to params (type ignore for dynamic key assignment)
+        for k, v in kwargs.items():
+            params[k] = v  # type: ignore[literal-required]
+
+        # Apply configuration defaults if values not explicitly provided
+        # Check for command-level config option first, then group-level
+        command_config = kwargs.get("config")
+        if command_config:
+            config = OstructConfig.load(command_config)
+        else:
+            config = ctx.obj.get("config") if ctx.obj else OstructConfig()
+
+        if params.get("model") is None:
+            params["model"] = config.get_model_default()
+
+        # Run the async function synchronously
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        try:
+            exit_code = loop.run_until_complete(run_cli_async(params))
+            sys.exit(int(exit_code))
+        except SchemaValidationError as e:
+            # Log the error with full context
+            logger.error("Schema validation error: %s", str(e))
+            if e.context:
+                logger.debug(
+                    "Error context: %s", json.dumps(e.context, indent=2)
+                )
+            # Re-raise to preserve error chain and exit code
+            raise
+        except (CLIError, InvalidJSONError, SchemaFileError) as e:
+            handle_error(e)
+            sys.exit(
+                e.exit_code
+                if hasattr(e, "exit_code")
+                else ExitCode.INTERNAL_ERROR
+            )
+        except click.UsageError as e:
+            handle_error(e)
+            sys.exit(ExitCode.USAGE_ERROR)
+        except Exception as e:
+            handle_error(e)
+            sys.exit(ExitCode.INTERNAL_ERROR)
+        finally:
+            loop.close()
+    except KeyboardInterrupt:
+        logger.info("Operation cancelled by user")
+        raise

ostruct/cli/commands/update_registry.py

@@ -0,0 +1,71 @@
+"""Update registry command for ostruct CLI."""
+
+import sys
+from typing import Optional
+
+import click
+from openai_model_registry import ModelRegistry
+
+from ..exit_codes import ExitCode
+
+
+@click.command("update-registry")
+@click.option(
+    "--url",
+    help="URL to fetch the registry from. Defaults to official repository.",
+    default=None,
+)
+@click.option(
+    "--force",
+    is_flag=True,
+    help="Force update even if the registry is already up to date.",
+    default=False,
+)
+def update_registry(url: Optional[str] = None, force: bool = False) -> None:
+    """Update the model registry with the latest model definitions.
+
+    This command fetches the latest model registry from the official repository
+    or a custom URL if provided, and updates the local registry file.
+
+    Example:
+        ostruct update-registry
+        ostruct update-registry --url https://example.com/models.yml
+    """
+    try:
+        registry = ModelRegistry.get_instance()
+
+        # Show current registry config path
+        config_path = registry.config.registry_path
+        click.echo(f"Current registry file: {config_path}")
+
+        if force:
+            click.echo("🔄 Forcing registry update...")
+            refresh_result = registry.refresh_from_remote(url)
+            if refresh_result.success:
+                click.echo("✅ Registry successfully updated!")
+            else:
+                click.echo(
+                    f"❌ Failed to update registry: {refresh_result.message}"
+                )
+            return
+
+        click.echo("🔍 Checking for registry updates...")
+        update_result = registry.check_for_updates()
+
+        if update_result.status.value == "update_available":
+            click.echo(f"📦 Update available: {update_result.message}")
+            click.echo("🔄 Updating registry...")
+            refresh_result = registry.refresh_from_remote(url)
+            if refresh_result.success:
+                click.echo("✅ Registry successfully updated!")
+            else:
+                click.echo(
+                    f"❌ Failed to update registry: {refresh_result.message}"
+                )
+        elif update_result.status.value == "already_current":
+            click.echo("✅ Registry is already up to date")
+        else:
+            click.echo(f"⚠️ Registry check failed: {update_result.message}")
+    except Exception as e:
+        click.echo(f"❌ Error updating registry: {str(e)}")
+        sys.exit(ExitCode.API_ERROR.value)