ostruct-cli 0.8.8__py3-none-any.whl → 1.0.0__py3-none-any.whl

ostruct/cli/config.py

@@ -8,6 +8,8 @@ from typing import Any, Dict, Optional, Union
 import yaml
 from pydantic import BaseModel, Field, field_validator, model_validator
 
+from .constants import DefaultConfig, DefaultSecurity
+
 logger = logging.getLogger(__name__)
 
 
@@ -40,14 +42,10 @@ class ToolsConfig(BaseModel):
     """Configuration for tool-specific settings."""
 
     code_interpreter: Dict[str, Any] = Field(
-        default_factory=lambda: {
-            "auto_download": True,
-            "output_directory": "./output",
-            "download_strategy": "single_pass",  # "single_pass" | "two_pass_sentinel"
-        }
+        default_factory=lambda: DefaultConfig.CODE_INTERPRETER.copy()
     )
     file_search: Dict[str, Any] = Field(
-        default_factory=lambda: {"max_results": 10}
+        default_factory=lambda: DefaultConfig.FILE_SEARCH.copy()
     )
     web_search: WebSearchToolConfig = Field(
         default_factory=WebSearchToolConfig
@@ -57,30 +55,33 @@ class ToolsConfig(BaseModel):
 class ModelsConfig(BaseModel):
     """Configuration for model settings."""
 
-    default: str = "gpt-4o"
+    default: str = DefaultConfig.DEFAULT_MODEL
 
 
 class OperationConfig(BaseModel):
     """Configuration for operation settings."""
 
-    timeout_minutes: int = 60
-    retry_attempts: int = 3
-    require_approval: str = "never"
+    timeout_minutes: int = DefaultConfig.OPERATION_TIMEOUT_MINUTES
+    retry_attempts: int = DefaultConfig.OPERATION_RETRY_ATTEMPTS
+    require_approval: str = DefaultConfig.OPERATION_REQUIRE_APPROVAL
 
     @field_validator("require_approval")
     @classmethod
     def validate_approval_setting(cls, v: str) -> str:
-        valid_values = ["never", "always", "expensive"]
-        if v not in valid_values:
-            raise ValueError(f"require_approval must be one of {valid_values}")
+        if v not in DefaultSecurity.VALID_APPROVAL_SETTINGS:
+            raise ValueError(
+                f"require_approval must be one of {DefaultSecurity.VALID_APPROVAL_SETTINGS}"
+            )
         return v
 
 
 class LimitsConfig(BaseModel):
     """Configuration for cost and operation limits."""
 
-    max_cost_per_run: float = 10.00
-    warn_expensive_operations: bool = True
+    max_cost_per_run: float = DefaultConfig.LIMITS_MAX_COST_PER_RUN
+    warn_expensive_operations: bool = (
+        DefaultConfig.LIMITS_WARN_EXPENSIVE_OPERATIONS
+    )
 
 
 class OstructConfig(BaseModel):
@@ -173,12 +174,12 @@ class OstructConfig(BaseModel):
         # MCP server URLs from environment
         mcp_config = config_data.setdefault("mcp", {})
 
-        # Look for MCP_* environment variables
+        # Look for OSTRUCT_MCP_URL_* environment variables
         for key, value in os.environ.items():
-            if key.startswith("MCP_") and key.endswith("_URL"):
+            if key.startswith("OSTRUCT_MCP_URL_"):
                 server_name = key[
-                    4:-4
-                ].lower()  # Remove MCP_ prefix and _URL suffix
+                    16:
+                ].lower()  # Remove OSTRUCT_MCP_URL_ prefix
                 mcp_config[server_name] = value
 
         # Built-in MCP server shortcuts
@@ -189,7 +190,7 @@ class OstructConfig(BaseModel):
 
         for name, url in builtin_servers.items():
             if name not in mcp_config:
-                env_key = f"MCP_{name.upper()}_URL"
+                env_key = f"OSTRUCT_MCP_URL_{name}"
                 if os.getenv(env_key):
                     mcp_config[name] = os.getenv(env_key)
 
@@ -251,7 +252,7 @@ models:
 tools:
   code_interpreter:
     auto_download: true
-    output_directory: "./output"
+    output_directory: "./downloads"
 
   file_search:
     max_results: 10
@@ -287,7 +288,7 @@ limits:
 
 # Environment Variables for Secrets:
 # OPENAI_API_KEY - Your OpenAI API key
-# MCP_<NAME>_URL - URL for custom MCP servers (e.g., MCP_STRIPE_URL)
+# OSTRUCT_MCP_URL_<name> - URL for custom MCP servers (e.g., OSTRUCT_MCP_URL_stripe)
 """
 
 

ostruct/cli/constants.py

@@ -0,0 +1,89 @@
+"""Centralized constants for ostruct CLI."""
+
+from typing import Any, Dict
+
+
+class DefaultPaths:
+    """Default paths and directories for ostruct."""
+
+    # Code Interpreter defaults
+    CODE_INTERPRETER_OUTPUT_DIR = "./downloads"
+
+    # Configuration file paths
+    CONFIG_FILE_NAME = "ostruct.yaml"
+    HOME_CONFIG_DIR = ".ostruct"
+    HOME_CONFIG_FILE = "config.yaml"
+
+
+class DefaultConfig:
+    """Default configuration values for ostruct."""
+
+    # Model defaults
+    DEFAULT_MODEL: str = "gpt-4.1"
+
+    # Code Interpreter defaults
+    CODE_INTERPRETER: Dict[str, Any] = {
+        "auto_download": True,
+        "output_directory": DefaultPaths.CODE_INTERPRETER_OUTPUT_DIR,
+        "download_strategy": "single_pass",
+    }
+
+    # File Search defaults
+    FILE_SEARCH: Dict[str, Any] = {
+        "max_results": 10,
+    }
+
+    # Web Search defaults
+    WEB_SEARCH: Dict[str, Any] = {
+        "enable_by_default": False,
+        "search_context_size": None,
+        "user_location": None,
+    }
+
+    # Operation defaults - individual values for direct access
+    OPERATION_TIMEOUT_MINUTES: int = 60
+    OPERATION_RETRY_ATTEMPTS: int = 3
+    OPERATION_REQUIRE_APPROVAL: str = "never"
+
+    # Limits defaults - individual values for direct access
+    LIMITS_MAX_COST_PER_RUN: float = 10.00
+    LIMITS_WARN_EXPENSIVE_OPERATIONS: bool = True
+
+    # Template processing defaults
+    TEMPLATE: Dict[str, Any] = {
+        "system_prompt": "You are a helpful assistant.",
+        "file_limit": 65536,  # 64KB
+        "total_limit": 1048576,  # 1MB
+        "preview_limit": 4096,  # 4KB
+    }
+
+
+class DefaultTimeouts:
+    """Default timeout values."""
+
+    API_TIMEOUT = 60.0
+    MAX_API_TIMEOUT = 300.0  # 5 minutes cap
+
+
+class DefaultSecurity:
+    """Default security settings."""
+
+    PATH_SECURITY_MODE = "permissive"
+    VALID_SECURITY_MODES = ["permissive", "warn", "strict"]
+    VALID_APPROVAL_SETTINGS = ["never", "always", "expensive"]
+
+
+# Environment variable names (for consistency)
+class EnvVars:
+    """Environment variable names."""
+
+    OPENAI_API_KEY = "OPENAI_API_KEY"
+    OSTRUCT_DISABLE_REGISTRY_UPDATE_CHECKS = (
+        "OSTRUCT_DISABLE_REGISTRY_UPDATE_CHECKS"
+    )
+    OSTRUCT_TEMPLATE_FILE_LIMIT = "OSTRUCT_TEMPLATE_FILE_LIMIT"
+    OSTRUCT_TEMPLATE_TOTAL_LIMIT = "OSTRUCT_TEMPLATE_TOTAL_LIMIT"
+    OSTRUCT_TEMPLATE_PREVIEW_LIMIT = "OSTRUCT_TEMPLATE_PREVIEW_LIMIT"
+
+    # MCP URL pattern: OSTRUCT_MCP_URL_<name>
+    MCP_URL_PREFIX = "OSTRUCT_MCP_URL_"

ostruct/cli/errors.py

@@ -252,7 +252,20 @@ class PathSecurityError(SecurityErrorBase):
 class TaskTemplateError(CLIError):
     """Base class for task template-related errors."""
 
-    pass
+    def __init__(
+        self,
+        message: str,
+        context: Optional[Dict[str, Any]] = None,
+        exit_code: int = ExitCode.VALIDATION_ERROR,
+    ) -> None:
+        """Initialize task template error.
+
+        Args:
+            message: Error message
+            context: Additional error context
+            exit_code: Exit code (defaults to VALIDATION_ERROR)
+        """
+        super().__init__(message, context=context, exit_code=exit_code)
 
 
 class TaskTemplateSyntaxError(TaskTemplateError):
@@ -285,13 +298,43 @@ class TaskTemplateVariableError(TaskTemplateError):
 class TemplateValidationError(TaskTemplateError):
     """Raised when template validation fails."""
 
-    pass
+    def __init__(
+        self,
+        message: str,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Initialize template validation error.
+
+        Args:
+            message: Error message
+            context: Additional error context
+        """
+        super().__init__(
+            message,
+            context=context,
+            exit_code=ExitCode.VALIDATION_ERROR,
+        )
 
 
 class SystemPromptError(TaskTemplateError):
     """Raised when there are issues with system prompt loading or processing."""
 
-    pass
+    def __init__(
+        self,
+        message: str,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Initialize system prompt error.
+
+        Args:
+            message: Error message
+            context: Additional error context
+        """
+        super().__init__(
+            message,
+            context=context,
+            exit_code=ExitCode.VALIDATION_ERROR,
+        )
 
 
 class SchemaError(CLIError):
@@ -561,7 +604,7 @@ class APIErrorMapper:
         ):
             return PromptTooLargeError(
                 f"Prompt exceeds model context window (128,000 token limit). "
-                f"Tip: Use explicit file routing (-fc for code, -fs for docs, -ft for config). "
+                f"Tip: Use explicit file routing (--file ci:data for code, --file fs:docs for docs, --file config for config). "
                 f"Original error: {error}"
             )
 
@@ -630,7 +673,7 @@ class APIErrorMapper:
             if "upload" in error_msg or "vector_store" in error_msg:
                 return FileSearchUploadError(
                     f"File Search upload failed: {error}. "
-                    f"This can be intermittent - retry with --file-search-retry-count option."
+                    f"This can be intermittent - retry with --fs-retries option."
                 )
             return FileSearchError(f"File Search error: {error}")
 
@@ -733,7 +776,17 @@ def handle_error(e: Exception) -> None:
         msg = f"Model creation error: {str(e)}"
         exit_code = ExitCode.SCHEMA_ERROR
     elif isinstance(e, click.UsageError):
-        msg = f"Usage error: {str(e)}"
+        error_msg = str(e)
+
+        # Enhance usage error messages with helpful guidance
+        if "Missing parameter" in error_msg:
+            if "task_template" in error_msg:
+                msg = f"Usage error: {error_msg}\n\nTry 'ostruct run --help' for usage information, 'ostruct --quick-ref' for examples, or 'ostruct run --help-debug' for troubleshooting help."
+            else:
+                msg = f"Usage error: {error_msg}\n\nTry 'ostruct run --help' for usage information or 'ostruct --quick-ref' for examples."
+        else:
+            msg = f"Usage error: {error_msg}"
+
         exit_code = ExitCode.USAGE_ERROR
     elif isinstance(e, SchemaFileError):
         msg = str(e)  # Use existing __str__ formatting
@@ -800,3 +853,135 @@ __all__ = [
     "InvalidResponseFormatError",
     "handle_error",
 ]
+
+# Download-specific error classes for Task 3
+
+
+class DownloadError(CLIError):
+    """Base class for download-related errors."""
+
+    def __init__(
+        self,
+        message: str,
+        context: Optional[Dict[str, Any]] = None,
+        exit_code: int = ExitCode.API_ERROR,
+    ) -> None:
+        """Initialize download error.
+
+        Args:
+            message: Error message
+            context: Additional error context
+            exit_code: Exit code for the error
+        """
+        super().__init__(message, context=context, exit_code=exit_code)
+
+
+class DownloadPermissionError(DownloadError):
+    """Raised when download fails due to permission issues."""
+
+    def __init__(
+        self,
+        directory: str,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Initialize permission error.
+
+        Args:
+            directory: Directory that caused the permission error
+            context: Additional error context
+        """
+        context = context or {}
+        context.update(
+            {
+                "directory": directory,
+                "details": "Unable to write to the specified download directory",
+                "troubleshooting": [
+                    f"Check write permissions for directory: {directory}",
+                    "Verify the directory exists and is accessible",
+                    "Try using a different download directory with --ci-download-dir",
+                    "Check if the parent directory exists and is writable",
+                    "Ensure sufficient disk space is available",
+                ],
+            }
+        )
+
+        message = f"Permission denied when writing to download directory: {directory}"
+        super().__init__(
+            message, context=context, exit_code=ExitCode.FILE_ERROR
+        )
+
+
+class DownloadNetworkError(DownloadError):
+    """Raised when download fails due to network issues."""
+
+    def __init__(
+        self,
+        file_id: str,
+        original_error: Optional[Exception] = None,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Initialize network error.
+
+        Args:
+            file_id: File ID that failed to download
+            original_error: Original exception that caused the failure
+            context: Additional error context
+        """
+        context = context or {}
+        context.update(
+            {
+                "file_id": file_id,
+                "details": "Network error occurred while downloading file from OpenAI",
+                "troubleshooting": [
+                    "Check your internet connection",
+                    "Verify OpenAI API is accessible",
+                    "Try the download again in a few moments",
+                    "Check if your API key has the necessary permissions",
+                    "Ensure the file ID is valid and not expired",
+                ],
+            }
+        )
+
+        if original_error:
+            context["original_error"] = str(original_error)
+
+        message = f"Network error downloading file {file_id}"
+        if original_error:
+            message += f": {original_error}"
+
+        super().__init__(message, context=context)
+
+
+class DownloadFileNotFoundError(DownloadError):
+    """Raised when a file to download is not found."""
+
+    def __init__(
+        self,
+        file_id: str,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Initialize file not found error.
+
+        Args:
+            file_id: File ID that was not found
+            context: Additional error context
+        """
+        context = context or {}
+        context.update(
+            {
+                "file_id": file_id,
+                "details": "The requested file was not found or is no longer available",
+                "troubleshooting": [
+                    "Verify the file ID is correct",
+                    "Check if the file was generated in this session",
+                    "Ensure the Code Interpreter execution completed successfully",
+                    "Try running the analysis again to regenerate the file",
+                    "Check if the file has expired (files have limited lifetime)",
+                ],
+            }
+        )
+
+        message = f"File not found for download: {file_id}"
+        super().__init__(
+            message, context=context, exit_code=ExitCode.FILE_ERROR
+        )

ostruct/cli/explicit_file_processor.py

@@ -135,21 +135,6 @@ class ExplicitFileProcessor:
         """
         routing = ExplicitRouting()
 
-        # Legacy options (-f, -d) are handled separately in create_template_context_from_routing
-        # to preserve their custom variable naming semantics
-        legacy_files = args.get("files", [])
-        legacy_dirs = args.get("dir", [])
-
-        if legacy_files:
-            logger.debug(
-                f"Legacy -f flag detected: {len(legacy_files)} files (handled separately)"
-            )
-
-        if legacy_dirs:
-            logger.debug(
-                f"Legacy -d flag detected: {len(legacy_dirs)} dirs (handled separately)"
-            )
-
         # Handle explicit tool routing - file options now have different formats
 
         # Template files (from -ft) - now single-argument auto-naming

ostruct/cli/file_info.py

@@ -5,7 +5,7 @@ import logging
 import os
 from enum import Enum
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any, Iterator, Optional
 
 from .errors import FileReadError, OstructFileNotFoundError, PathSecurityError
 from .security import SecurityManager
@@ -18,9 +18,9 @@ class FileRoutingIntent(Enum):
     to provide appropriate warnings and optimizations.
     """
 
-    TEMPLATE_ONLY = "template_only"  # -ft, --fta, legacy -f, -d
-    CODE_INTERPRETER = "code_interpreter"  # -fc, --fca
-    FILE_SEARCH = "file_search"  # -fs, --fsa
+    TEMPLATE_ONLY = "template_only"  # --file [alias] (template access only)
+    CODE_INTERPRETER = "code_interpreter"  # --file ci:[alias]
+    FILE_SEARCH = "file_search"  # --file fs:[alias]
 
 
 logger = logging.getLogger(__name__)
@@ -30,7 +30,8 @@ class FileInfo:
     """Represents a file with metadata and content.
 
     This class provides access to file metadata (path, size, etc.) and content,
-    with caching support for efficient access.
+    with caching support for efficient access. Implements the file-sequence protocol
+    by being iterable (yields itself) while maintaining scalar access to properties.
 
     Args:
         path: Path to the file
@@ -77,6 +78,19 @@ class FileInfo:
         self.routing_type = routing_type
         self.routing_intent = routing_intent
 
+        # TSES v2.0 fields for alias tracking
+        self.parent_alias: Optional[str] = (
+            None  # CLI alias this file came from
+        )
+        self.relative_path: Optional[str] = (
+            None  # Path relative to attachment root
+        )
+        self.base_path: Optional[str] = None  # Base path of attachment
+        self.from_collection: bool = False  # Whether file came from --collect
+        self.attachment_type: str = (
+            "file"  # Original attachment type: "file", "dir", or "collection"
+        )
+
         logger.debug(
             "Creating FileInfo for path: %s, routing_type: %s",
             path,
@@ -149,6 +163,39 @@ class FileInfo:
                 f"Permission denied: {os.path.basename(str(path))}"
             ) from e
 
+    def __iter__(self) -> Iterator["FileInfo"]:
+        """Make FileInfo iterable by yielding itself.
+
+        This implements the file-sequence protocol, allowing single files
+        to be treated uniformly with file collections in templates.
+
+        Returns:
+            Iterator that yields this FileInfo instance
+        """
+        yield self
+
+    @property
+    def first(self) -> "FileInfo":
+        """Get the first file in the sequence (itself for single files).
+
+        This provides a uniform interface with FileInfoList.first,
+        allowing templates to use .first regardless of whether they're
+        dealing with a single file or a collection.
+
+        Returns:
+            This FileInfo instance
+        """
+        return self
+
+    @property
+    def is_collection(self) -> bool:
+        """Indicate whether this is a collection of files.
+
+        Returns:
+            False, since FileInfo represents a single file
+        """
+        return False
+
     @property
     def path(self) -> str:
         """Get the path relative to security manager's base directory.
@@ -156,25 +203,52 @@ class FileInfo:
         Returns a path relative to the security manager's base directory.
         This ensures consistent path handling across the entire codebase.
 
+        For paths outside the base directory but within allowed directories,
+        returns the absolute path.
+
         Example:
             security_manager = SecurityManager(base_dir="/base")
             file_info = FileInfo("/base/file.txt", security_manager)
             print(file_info.path)  # Outputs: "file.txt"
 
+            # With allowed directory outside base:
+            file_info = FileInfo("/tmp/file.txt", security_manager)
+            print(file_info.path)  # Outputs: "/tmp/file.txt"
+
         Returns:
-            str: Path relative to security manager's base directory
+            str: Path relative to security manager's base directory, or absolute path
+                 if outside base directory but within allowed directories
 
         Raises:
-            ValueError: If the path is not within the base directory
+            ValueError: If the path is not within the base directory or allowed directories
         """
+        abs_path = Path(self.abs_path)
+        base_dir = Path(self.__security_manager.base_dir)
+
         try:
-            abs_path = Path(self.abs_path)
-            base_dir = Path(self.__security_manager.base_dir)
             return str(abs_path.relative_to(base_dir))
-        except ValueError as e:
-            logger.error("Error making path relative: %s", e)
+        except ValueError:
+            # Path is outside base_dir, check if it's allowed by enhanced security model
+            try:
+                if self.__security_manager.is_path_allowed_enhanced(abs_path):
+                    logger.debug(
+                        "Path outside base_dir but allowed, returning absolute path: %s",
+                        abs_path,
+                    )
+                    return str(abs_path)
+            except Exception:
+                # In strict mode, is_path_allowed_enhanced() raises exceptions
+                # If we reach this except block, the path is not allowed
+                pass
+
+            # Should never reach here if SecurityManager validation was done properly
+            logger.error(
+                "Error making path relative: %s is not within base directory %s",
+                abs_path,
+                base_dir,
+            )
             raise ValueError(
-                f"Path {abs_path} must be within base directory {base_dir}"
+                f"Path {abs_path} is not within base directory {base_dir}"
             )
 
     @path.setter
@@ -280,7 +354,7 @@ class FileInfo:
                 f"File '{self.path}' ({self.size / 1024:.1f}KB) was routed for template-only access "
                 f"but its .content is being accessed. This will include the entire file content "
                 f"in the prompt sent to the AI. For large files intended for analysis or search, "
-                f"consider using -fc (Code Interpreter) or -fs (File Search) to optimize token usage, "
+                f"consider using --file ci:data (Code Interpreter) or --file fs:docs (File Search) to optimize token usage, "
                 f"cost, and avoid exceeding model context limits."
             )
 
@@ -411,6 +485,11 @@ class FileInfo:
         security_manager: SecurityManager,
         routing_type: Optional[str] = None,
         routing_intent: Optional[FileRoutingIntent] = None,
+        parent_alias: Optional[str] = None,
+        relative_path: Optional[str] = None,
+        base_path: Optional[str] = None,
+        from_collection: bool = False,
+        attachment_type: str = "file",
     ) -> "FileInfo":
         """Create FileInfo instance from path.
 
@@ -419,6 +498,11 @@ class FileInfo:
             security_manager: Security manager for path validation
             routing_type: How the file was routed (e.g., 'template', 'code-interpreter')
             routing_intent: The intended use of the file in the pipeline
+            parent_alias: CLI alias this file came from (for TSES)
+            relative_path: Path relative to attachment root (for TSES)
+            base_path: Base path of attachment (for TSES)
+            from_collection: Whether file came from --collect (for TSES)
+            attachment_type: Original attachment type: "file", "dir", or "collection" (for TSES)
 
         Returns:
             FileInfo instance
@@ -427,13 +511,22 @@ class FileInfo:
             FileNotFoundError: If file does not exist
             PathSecurityError: If path is not allowed
         """
-        return cls(
+        file_info = cls(
             path,
             security_manager,
             routing_type=routing_type,
             routing_intent=routing_intent,
         )
 
+        # Set TSES fields
+        file_info.parent_alias = parent_alias
+        file_info.relative_path = relative_path
+        file_info.base_path = base_path
+        file_info.from_collection = from_collection
+        file_info.attachment_type = attachment_type
+
+        return file_info
+
     def __str__(self) -> str:
         """String representation showing path."""
         return f"FileInfo({self.__path})"
@@ -459,6 +552,17 @@ class FileInfo:
             object.__setattr__(self, name, value)
             return
 
+        # Allow setting TSES fields
+        if name in (
+            "parent_alias",
+            "relative_path",
+            "base_path",
+            "from_collection",
+            "attachment_type",
+        ):
+            object.__setattr__(self, name, value)
+            return
+
         # Allow setting private attributes from internal methods
         if name.startswith("_FileInfo__") and self._is_internal_call():
             object.__setattr__(self, name, value)