ostruct-cli 0.4.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

ostruct/cli/cli.py

@@ -5,10 +5,10 @@ import json
 import logging
 import os
 import sys
-from dataclasses import dataclass
 from enum import Enum, IntEnum
 from typing import (
     Any,
+    AsyncGenerator,
     Dict,
     List,
     Literal,
@@ -16,6 +16,7 @@ from typing import (
     Set,
     Tuple,
     Type,
+    TypedDict,
     TypeVar,
     Union,
     cast,
@@ -31,20 +32,10 @@ from pathlib import Path
 
 import click
 import jinja2
-import tiktoken
 import yaml
-from openai import (
-    APIConnectionError,
-    AsyncOpenAI,
-    AuthenticationError,
-    BadRequestError,
-    InternalServerError,
-    RateLimitError,
-)
+from openai import AsyncOpenAI
 from openai_structured.client import (
     async_openai_structured_stream,
-    get_context_window_limit,
-    get_default_token_limit,
     supports_structured_output,
 )
 from openai_structured.errors import (
@@ -54,12 +45,9 @@ from openai_structured.errors import (
     ModelNotSupportedError,
     ModelVersionError,
     OpenAIClientError,
-    SchemaFileError,
-    SchemaValidationError,
     StreamBufferError,
-    StreamInterruptedError,
-    StreamParseError,
 )
+from openai_structured.model_registry import ModelRegistry
 from pydantic import (
     AnyUrl,
     BaseModel,
@@ -74,61 +62,63 @@ from pydantic.functional_validators import BeforeValidator
 from pydantic.types import constr
 from typing_extensions import TypeAlias
 
-from ostruct.cli.click_options import create_click_command
+from ostruct.cli.click_options import all_options
+from ostruct.cli.exit_codes import ExitCode
 
 from .. import __version__  # noqa: F401 - Used in package metadata
 from .errors import (
     CLIError,
     DirectoryNotFoundError,
     FieldDefinitionError,
-    FileNotFoundError,
     InvalidJSONError,
     ModelCreationError,
     ModelValidationError,
     NestedModelError,
+    OstructFileNotFoundError,
     PathSecurityError,
+    SchemaFileError,
+    SchemaValidationError,
+    StreamInterruptedError,
+    StreamParseError,
     TaskTemplateSyntaxError,
     TaskTemplateVariableError,
-    VariableError,
     VariableNameError,
     VariableValueError,
 )
-from .file_utils import FileInfoList, TemplateValue, collect_files
+from .file_utils import FileInfoList, collect_files
 from .path_utils import validate_path_mapping
 from .security import SecurityManager
+from .serialization import LogSerializer
 from .template_env import create_jinja_env
 from .template_utils import SystemPromptError, render_template
+from .token_utils import estimate_tokens_with_encoding
 
 # Constants
 DEFAULT_SYSTEM_PROMPT = "You are a helpful assistant."
 
 
-@dataclass
-class Namespace:
-    """Compatibility class to mimic argparse.Namespace for existing code."""
+class CLIParams(TypedDict, total=False):
+    """Type-safe CLI parameters."""
 
-    task: Optional[str]
-    task_file: Optional[str]
-    file: List[str]
-    files: List[str]
-    dir: List[str]
-    allowed_dir: List[str]
+    files: List[
+        Tuple[str, str]
+    ]  # List of (name, path) tuples from Click's nargs=2
+    dir: List[
+        Tuple[str, str]
+    ]  # List of (name, dir) tuples from Click's nargs=2
+    patterns: List[
+        Tuple[str, str]
+    ]  # List of (name, pattern) tuples from Click's nargs=2
+    allowed_dirs: List[str]
     base_dir: str
     allowed_dir_file: Optional[str]
-    dir_recursive: bool
-    dir_ext: Optional[str]
+    recursive: bool
     var: List[str]
     json_var: List[str]
     system_prompt: Optional[str]
     system_prompt_file: Optional[str]
     ignore_task_sysprompt: bool
-    schema_file: str
     model: str
-    temperature: float
-    max_tokens: Optional[int]
-    top_p: float
-    frequency_penalty: float
-    presence_penalty: float
     timeout: float
     output_file: Optional[str]
     dry_run: bool
@@ -138,7 +128,16 @@ class Namespace:
     debug_openai_stream: bool
     show_model_schema: bool
     debug_validation: bool
-    progress_level: str = "basic"  # Default to 'basic' if not specified
+    temperature: Optional[float]
+    max_output_tokens: Optional[int]
+    top_p: Optional[float]
+    frequency_penalty: Optional[float]
+    presence_penalty: Optional[float]
+    reasoning_effort: Optional[str]
+    progress_level: str
+    task_file: Optional[str]
+    task: Optional[str]
+    schema_file: str
 
 
 # Set up logging
@@ -176,45 +175,6 @@ ostruct_file_handler.setFormatter(
 logger.addHandler(ostruct_file_handler)
 
 
-class ExitCode(IntEnum):
-    """Exit codes for the CLI following standard Unix conventions.
-
-    Categories:
-    - Success (0-1)
-    - User Interruption (2-3)
-    - Input/Validation (64-69)
-    - I/O and File Access (70-79)
-    - API and External Services (80-89)
-    - Internal Errors (90-99)
-    """
-
-    # Success codes
-    SUCCESS = 0
-
-    # User interruption
-    INTERRUPTED = 2
-
-    # Input/Validation errors (64-69)
-    USAGE_ERROR = 64
-    DATA_ERROR = 65
-    SCHEMA_ERROR = 66
-    VALIDATION_ERROR = 67
-
-    # I/O and File Access errors (70-79)
-    IO_ERROR = 70
-    FILE_NOT_FOUND = 71
-    PERMISSION_ERROR = 72
-    SECURITY_ERROR = 73
-
-    # API and External Service errors (80-89)
-    API_ERROR = 80
-    API_TIMEOUT = 81
-
-    # Internal errors (90-99)
-    INTERNAL_ERROR = 90
-    UNKNOWN_ERROR = 91
-
-
 # Type aliases
 FieldType = (
     Any  # Changed from Type[Any] to allow both concrete types and generics
@@ -281,7 +241,7 @@ def _get_type_with_constraints(
                 show_schema=False,
                 debug_validation=False,
             )
-            array_type: Type[List[Any]] = List[array_item_model]  # type: ignore[valid-type]
+            array_type: Type[List[Any]] = List[array_item_model]  # type: ignore
             return (array_type, Field(**field_kwargs))
 
         # For non-object items, use the type directly
@@ -403,64 +363,17 @@ K = TypeVar("K")
 V = TypeVar("V")
 
 
-def estimate_tokens_for_chat(
-    messages: List[Dict[str, str]],
-    model: str,
-    encoder: Any = None,
-) -> int:
-    """Estimate the number of tokens in a chat completion.
-
-    Args:
-        messages: List of chat messages
-        model: Model name
-        encoder: Optional tiktoken encoder for testing. If provided, only uses encoder.encode() results.
-    """
-    if encoder is None:
-        try:
-            # Try to get the encoding for the specific model
-            encoder = tiktoken.get_encoding("o200k_base")
-        except KeyError:
-            # Fall back to cl100k_base for unknown models
-            encoder = tiktoken.get_encoding("cl100k_base")
-
-        # Use standard token counting logic for real tiktoken encoders
-        num_tokens = 0
-        for message in messages:
-            # Add message overhead
-            num_tokens += 4  # every message follows <im_start>{role/name}\n{content}<im_end>\n
-            for key, value in message.items():
-                num_tokens += len(encoder.encode(str(value)))
-                if key == "name":  # if there's a name, the role is omitted
-                    num_tokens -= 1  # role is omitted
-        num_tokens += 2  # every reply is primed with <im_start>assistant
-        return num_tokens
-    else:
-        # For mock encoders in tests, just return the length of encoded content
-        num_tokens = 0
-        for message in messages:
-            for value in message.values():
-                num_tokens += len(encoder.encode(str(value)))
-        return num_tokens
-
-
 def validate_token_limits(
     model: str, total_tokens: int, max_token_limit: Optional[int] = None
 ) -> None:
-    """Validate token counts against model limits.
-
-    Args:
-        model: The model name
-        total_tokens: Total number of tokens in the prompt
-        max_token_limit: Optional user-specified token limit
-
-    Raises:
-        ValueError: If token limits are exceeded
-    """
-    context_limit = get_context_window_limit(model)
+    """Validate token counts against model limits."""
+    registry = ModelRegistry()
+    capabilities = registry.get_capabilities(model)
+    context_limit = capabilities.context_window
     output_limit = (
         max_token_limit
         if max_token_limit is not None
-        else get_default_token_limit(model)
+        else capabilities.max_output_tokens
     )
 
     # Check if total tokens exceed context window
@@ -522,8 +435,12 @@ def process_system_prompt(
             )
             with open(path, "r", encoding="utf-8") as f:
                 system_prompt = f.read().strip()
-        except (FileNotFoundError, PathSecurityError) as e:
-            raise SystemPromptError(f"Invalid system prompt file: {e}")
+        except OstructFileNotFoundError as e:
+            raise SystemPromptError(
+                f"Failed to load system prompt file: {e}"
+            ) from e
+        except PathSecurityError as e:
+            raise SystemPromptError(f"Invalid system prompt file: {e}") from e
 
     if system_prompt is not None:
         # Render system prompt with template context
@@ -591,7 +508,8 @@ def validate_variable_mapping(
                 value = json.loads(value)
             except json.JSONDecodeError as e:
                 raise InvalidJSONError(
-                    f"Invalid JSON value for variable {name!r}: {value!r}"
+                    f"Invalid JSON value for variable {name!r}: {value!r}",
+                    context={"variable_name": name},
                 ) from e
 
         return name, value
@@ -787,11 +705,20 @@ def validate_task_template(
     template_content: str
     if task_file is not None:
         try:
-            name, path = validate_path_mapping(f"task={task_file}")
-            with open(path, "r", encoding="utf-8") as f:
+            with open(task_file, "r", encoding="utf-8") as f:
                 template_content = f.read()
-        except (FileNotFoundError, PathSecurityError) as e:
-            raise TaskTemplateVariableError(str(e))
+        except FileNotFoundError:
+            raise TaskTemplateVariableError(
+                f"Task template file not found: {task_file}"
+            )
+        except PermissionError:
+            raise TaskTemplateVariableError(
+                f"Permission denied reading task template file: {task_file}"
+            )
+        except Exception as e:
+            raise TaskTemplateVariableError(
+                f"Error reading task template file: {e}"
+            )
     else:
         template_content = task  # type: ignore  # We know task is str here due to the checks above
 
@@ -809,10 +736,10 @@ def validate_schema_file(
     path: str,
     verbose: bool = False,
 ) -> Dict[str, Any]:
-    """Validate a JSON schema file.
+    """Validate and load a JSON schema file.
 
     Args:
-        path: Path to the schema file
+        path: Path to schema file
         verbose: Whether to enable verbose logging
 
     Returns:
@@ -827,14 +754,42 @@ def validate_schema_file(
         logger.info("Validating schema file: %s", path)
 
     try:
-        with open(path) as f:
-            schema = json.load(f)
+        logger.debug("Opening schema file: %s", path)
+        with open(path, "r", encoding="utf-8") as f:
+            logger.debug("Loading JSON from schema file")
+            try:
+                schema = json.load(f)
+                logger.debug(
+                    "Successfully loaded JSON: %s",
+                    json.dumps(schema, indent=2),
+                )
+            except json.JSONDecodeError as e:
+                logger.error("JSON decode error in %s: %s", path, str(e))
+                logger.debug(
+                    "Error details - line: %d, col: %d, msg: %s",
+                    e.lineno,
+                    e.colno,
+                    e.msg,
+                )
+                raise InvalidJSONError(
+                    f"Invalid JSON in schema file {path}: {e}",
+                    context={"schema_path": path},
+                ) from e
     except FileNotFoundError:
-        raise SchemaFileError(f"Schema file not found: {path}")
-    except json.JSONDecodeError as e:
-        raise InvalidJSONError(f"Invalid JSON in schema file: {e}")
+        msg = f"Schema file not found: {path}"
+        logger.error(msg)
+        raise SchemaFileError(msg, schema_path=path)
+    except PermissionError:
+        msg = f"Permission denied reading schema file: {path}"
+        logger.error(msg)
+        raise SchemaFileError(msg, schema_path=path)
     except Exception as e:
-        raise SchemaFileError(f"Failed to read schema file: {e}")
+        if isinstance(e, InvalidJSONError):
+            raise
+        msg = f"Failed to read schema file {path}: {e}"
+        logger.error(msg)
+        logger.debug("Unexpected error details: %s", str(e))
+        raise SchemaFileError(msg, schema_path=path) from e
 
     # Pre-validation structure checks
     if verbose:
@@ -842,11 +797,9 @@ def validate_schema_file(
         logger.debug("Loaded schema: %s", json.dumps(schema, indent=2))
 
     if not isinstance(schema, dict):
-        if verbose:
-            logger.error(
-                "Schema is not a dictionary: %s", type(schema).__name__
-            )
-        raise SchemaValidationError("Schema must be a JSON object")
+        msg = f"Schema in {path} must be a JSON object"
+        logger.error(msg)
+        raise SchemaValidationError(msg, context={"path": path})
 
     # Validate schema structure
     if "schema" in schema:
@@ -854,30 +807,37 @@ def validate_schema_file(
             logger.debug("Found schema wrapper, validating inner schema")
         inner_schema = schema["schema"]
         if not isinstance(inner_schema, dict):
-            if verbose:
-                logger.error(
-                    "Inner schema is not a dictionary: %s",
-                    type(inner_schema).__name__,
-                )
-            raise SchemaValidationError("Inner schema must be a JSON object")
+            msg = f"Inner schema in {path} must be a JSON object"
+            logger.error(msg)
+            raise SchemaValidationError(msg, context={"path": path})
         if verbose:
             logger.debug("Inner schema validated successfully")
+            logger.debug(
+                "Inner schema: %s", json.dumps(inner_schema, indent=2)
+            )
     else:
         if verbose:
             logger.debug("No schema wrapper found, using schema as-is")
+            logger.debug("Schema: %s", json.dumps(schema, indent=2))
+
+    # Additional schema validation
+    if "type" not in schema.get("schema", schema):
+        msg = f"Schema in {path} must specify a type"
+        logger.error(msg)
+        raise SchemaValidationError(msg, context={"path": path})
 
     # Return the full schema including wrapper
     return schema
 
 
 def collect_template_files(
-    args: Namespace,
+    args: CLIParams,
     security_manager: SecurityManager,
-) -> Dict[str, TemplateValue]:
+) -> Dict[str, Union[FileInfoList, str, List[str], Dict[str, str]]]:
     """Collect files from command line arguments.
 
     Args:
-        args: Parsed command line arguments
+        args: Command line arguments
         security_manager: Security manager for path validation
 
     Returns:
@@ -888,15 +848,31 @@ def collect_template_files(
         ValueError: If file mappings are invalid or files cannot be accessed
     """
     try:
-        result = collect_files(
-            file_mappings=args.file,
-            pattern_mappings=args.files,
-            dir_mappings=args.dir,
-            dir_recursive=args.dir_recursive,
-            dir_extensions=args.dir_ext.split(",") if args.dir_ext else None,
+        # Get files, directories, and patterns from args - they are already tuples from Click's nargs=2
+        files = list(
+            args.get("files", [])
+        )  # List of (name, path) tuples from Click
+        dirs = args.get("dir", [])  # List of (name, dir) tuples from Click
+        patterns = args.get(
+            "patterns", []
+        )  # List of (name, pattern) tuples from Click
+
+        # Collect files from directories and patterns
+        dir_files = collect_files(
+            file_mappings=cast(List[Tuple[str, Union[str, Path]]], files),
+            dir_mappings=cast(List[Tuple[str, Union[str, Path]]], dirs),
+            pattern_mappings=cast(
+                List[Tuple[str, Union[str, Path]]], patterns
+            ),
+            dir_recursive=args.get("recursive", False),
             security_manager=security_manager,
         )
-        return cast(Dict[str, TemplateValue], result)
+
+        # Combine results
+        return cast(
+            Dict[str, Union[FileInfoList, str, List[str], Dict[str, str]]],
+            dir_files,
+        )
     except PathSecurityError:
         # Let PathSecurityError propagate without wrapping
         raise
@@ -914,11 +890,11 @@ def collect_template_files(
         raise ValueError(f"Error collecting files: {e}")
 
 
-def collect_simple_variables(args: Namespace) -> Dict[str, str]:
+def collect_simple_variables(args: CLIParams) -> Dict[str, str]:
     """Collect simple string variables from --var arguments.
 
     Args:
-        args: Parsed command line arguments
+        args: Command line arguments
 
     Returns:
         Dictionary mapping variable names to string values
@@ -929,10 +905,15 @@ def collect_simple_variables(args: Namespace) -> Dict[str, str]:
     variables: Dict[str, str] = {}
     all_names: Set[str] = set()
 
-    if args.var:
-        for mapping in args.var:
+    if args.get("var"):
+        for mapping in args["var"]:
             try:
-                name, value = mapping.split("=", 1)
+                # Handle both tuple format and string format
+                if isinstance(mapping, tuple):
+                    name, value = mapping
+                else:
+                    name, value = mapping.split("=", 1)
+
                 if not name.isidentifier():
                     raise VariableNameError(f"Invalid variable name: {name}")
                 if name in all_names:
@@ -947,11 +928,11 @@ def collect_simple_variables(args: Namespace) -> Dict[str, str]:
     return variables
 
 
-def collect_json_variables(args: Namespace) -> Dict[str, Any]:
+def collect_json_variables(args: CLIParams) -> Dict[str, Any]:
     """Collect JSON variables from --json-var arguments.
 
     Args:
-        args: Parsed command line arguments
+        args: Command line arguments
 
     Returns:
         Dictionary mapping variable names to parsed JSON values
@@ -963,53 +944,52 @@ def collect_json_variables(args: Namespace) -> Dict[str, Any]:
     variables: Dict[str, Any] = {}
     all_names: Set[str] = set()
 
-    if args.json_var:
-        for mapping in args.json_var:
+    if args.get("json_var"):
+        for mapping in args["json_var"]:
             try:
-                name, json_str = mapping.split("=", 1)
+                # Handle both tuple format and string format
+                if isinstance(mapping, tuple):
+                    name, value = (
+                        mapping  # Value is already parsed by Click validator
+                    )
+                else:
+                    try:
+                        name, json_str = mapping.split("=", 1)
+                    except ValueError:
+                        raise VariableNameError(
+                            f"Invalid JSON variable mapping format: {mapping}. Expected name=json"
+                        )
+                    try:
+                        value = json.loads(json_str)
+                    except json.JSONDecodeError as e:
+                        raise InvalidJSONError(
+                            f"Invalid JSON value for variable '{name}': {json_str}",
+                            context={"variable_name": name},
+                        ) from e
+
                 if not name.isidentifier():
                     raise VariableNameError(f"Invalid variable name: {name}")
                 if name in all_names:
                     raise VariableNameError(f"Duplicate variable name: {name}")
-                try:
-                    value = json.loads(json_str)
-                    variables[name] = value
-                    all_names.add(name)
-                except json.JSONDecodeError as e:
-                    raise InvalidJSONError(
-                        f"Error parsing JSON for variable '{name}': {str(e)}. Input was: {json_str}"
-                    )
-            except ValueError:
-                raise VariableNameError(
-                    f"Invalid JSON variable mapping format: {mapping}. Expected name=json"
-                )
+
+                variables[name] = value
+                all_names.add(name)
+            except (VariableNameError, InvalidJSONError):
+                raise
 
     return variables
 
 
 def create_template_context(
-    files: Optional[Dict[str, FileInfoList]] = None,
+    files: Optional[
+        Dict[str, Union[FileInfoList, str, List[str], Dict[str, str]]]
+    ] = None,
     variables: Optional[Dict[str, str]] = None,
     json_variables: Optional[Dict[str, Any]] = None,
     security_manager: Optional[SecurityManager] = None,
     stdin_content: Optional[str] = None,
 ) -> Dict[str, Any]:
-    """Create template context from direct inputs.
-
-    Args:
-        files: Optional dictionary mapping names to FileInfoList objects
-        variables: Optional dictionary of simple string variables
-        json_variables: Optional dictionary of JSON variables
-        security_manager: Optional security manager for path validation
-        stdin_content: Optional content to use for stdin
-
-    Returns:
-        Template context dictionary
-
-    Raises:
-        PathSecurityError: If any file paths violate security constraints
-        VariableError: If variable mappings are invalid
-    """
+    """Create template context from files and variables."""
     context: Dict[str, Any] = {}
 
     # Add file variables
@@ -1032,14 +1012,14 @@ def create_template_context(
     return context
 
 
-def create_template_context_from_args(
-    args: "Namespace",
+async def create_template_context_from_args(
+    args: CLIParams,
     security_manager: SecurityManager,
 ) -> Dict[str, Any]:
     """Create template context from command line arguments.
 
     Args:
-        args: Parsed command line arguments
+        args: Command line arguments
         security_manager: Security manager for path validation
 
     Returns:
@@ -1052,50 +1032,13 @@ def create_template_context_from_args(
     """
     try:
         # Collect files from arguments
-        files = None
-        if any([args.file, args.files, args.dir]):
-            files = collect_files(
-                file_mappings=args.file,
-                pattern_mappings=args.files,
-                dir_mappings=args.dir,
-                dir_recursive=args.dir_recursive,
-                dir_extensions=(
-                    args.dir_ext.split(",") if args.dir_ext else None
-                ),
-                security_manager=security_manager,
-            )
+        files = collect_template_files(args, security_manager)
 
         # Collect simple variables
-        try:
-            variables = collect_simple_variables(args)
-        except VariableNameError as e:
-            raise VariableError(str(e))
+        variables = collect_simple_variables(args)
 
         # Collect JSON variables
-        json_variables = {}
-        if args.json_var:
-            for mapping in args.json_var:
-                try:
-                    name, value = mapping.split("=", 1)
-                    if not name.isidentifier():
-                        raise VariableNameError(
-                            f"Invalid variable name: {name}"
-                        )
-                    try:
-                        json_value = json.loads(value)
-                    except json.JSONDecodeError as e:
-                        raise InvalidJSONError(
-                            f"Error parsing JSON for variable '{name}': {str(e)}. Input was: {value}"
-                        )
-                    if name in json_variables:
-                        raise VariableNameError(
-                            f"Duplicate variable name: {name}"
-                        )
-                    json_variables[name] = json_value
-                except ValueError:
-                    raise VariableNameError(
-                        f"Invalid JSON variable mapping format: {mapping}. Expected name=json"
-                    )
+        json_variables = collect_json_variables(args)
 
         # Get stdin content if available
         stdin_content = None
@@ -1106,7 +1049,7 @@ def create_template_context_from_args(
             # Skip stdin if it can't be read
             pass
 
-        return create_template_context(
+        context = create_template_context(
             files=files,
             variables=variables,
             json_variables=json_variables,
@@ -1114,6 +1057,11 @@ def create_template_context_from_args(
             stdin_content=stdin_content,
         )
 
+        # Add current model to context
+        context["current_model"] = args["model"]
+
+        return context
+
     except PathSecurityError:
         # Let PathSecurityError propagate without wrapping
         raise
@@ -1235,7 +1183,8 @@ def parse_json_var(var_str: str) -> Tuple[str, Any]:
             value = json.loads(json_str)
         except json.JSONDecodeError as e:
             raise InvalidJSONError(
-                f"Error parsing JSON for variable '{name}': {str(e)}. Input was: {json_str}"
+                f"Error parsing JSON for variable '{name}': {str(e)}. Input was: {json_str}",
+                context={"variable_name": name},
             )
 
         return name, value
@@ -1284,41 +1233,96 @@ def _create_enum_type(values: List[Any], field_name: str) -> Type[Enum]:
 
 
 def handle_error(e: Exception) -> None:
-    """Handle errors by printing appropriate message and exiting with status code."""
+    """Handle CLI errors and display appropriate messages.
+
+    Maintains specific error type handling while reducing duplication.
+    Provides enhanced debug logging for CLI errors.
+    """
+    # 1. Determine error type and message
     if isinstance(e, click.UsageError):
-        # For UsageError, preserve the original message format
-        if hasattr(e, "param") and e.param:
-            # Missing parameter error
-            msg = f"Missing option '--{e.param.name}'"
-            click.echo(msg, err=True)
-        else:
-            # Other usage errors (like conflicting options)
-            click.echo(str(e), err=True)
-        sys.exit(ExitCode.USAGE_ERROR)
-    elif isinstance(e, InvalidJSONError):
-        # Use the original error message if available
-        msg = str(e) if str(e) != "None" else "Invalid JSON"
-        click.secho(msg, fg="red", err=True)
-        sys.exit(ExitCode.DATA_ERROR)
-    elif isinstance(e, FileNotFoundError):
-        # Use the original error message if available
-        msg = str(e) if str(e) != "None" else "File not found"
-        click.secho(msg, fg="red", err=True)
-        sys.exit(ExitCode.SCHEMA_ERROR)
-    elif isinstance(e, TaskTemplateSyntaxError):
-        # Use the original error message if available
-        msg = str(e) if str(e) != "None" else "Template syntax error"
-        click.secho(msg, fg="red", err=True)
-        sys.exit(ExitCode.INTERNAL_ERROR)
+        msg = f"Usage error: {str(e)}"
+        exit_code = ExitCode.USAGE_ERROR
+    elif isinstance(e, SchemaFileError):
+        # Preserve specific schema error handling
+        msg = str(e)  # Use existing __str__ formatting
+        exit_code = ExitCode.SCHEMA_ERROR
+    elif isinstance(e, (InvalidJSONError, json.JSONDecodeError)):
+        msg = f"Invalid JSON error: {str(e)}"
+        exit_code = ExitCode.DATA_ERROR
+    elif isinstance(e, SchemaValidationError):
+        msg = f"Schema validation error: {str(e)}"
+        exit_code = ExitCode.VALIDATION_ERROR
     elif isinstance(e, CLIError):
-        # Use the show method for CLIError and its subclasses
-        e.show()
-        sys.exit(
-            e.exit_code if hasattr(e, "exit_code") else ExitCode.INTERNAL_ERROR
+        msg = str(e)  # Use existing __str__ formatting
+        exit_code = ExitCode(e.exit_code)  # Convert int to ExitCode
+    else:
+        msg = f"Unexpected error: {str(e)}"
+        exit_code = ExitCode.INTERNAL_ERROR
+
+    # 2. Debug logging
+    if isinstance(e, CLIError) and logger.isEnabledFor(logging.DEBUG):
+        # Format context fields with lowercase keys and simple values
+        context_str = ""
+        if hasattr(e, "context"):
+            for key, value in sorted(e.context.items()):
+                if key not in {
+                    "timestamp",
+                    "host",
+                    "version",
+                    "python_version",
+                }:
+                    context_str += f"{key.lower()}: {value}\n"
+
+        logger.debug(
+            "Error details:\n"
+            f"Type: {type(e).__name__}\n"
+            f"{context_str.rstrip()}"
         )
+    elif not isinstance(e, click.UsageError):
+        logger.error(msg, exc_info=True)
     else:
-        click.secho(f"Unexpected error: {str(e)}", fg="red", err=True)
-        sys.exit(ExitCode.INTERNAL_ERROR)
+        logger.error(msg)
+
+    # 3. User output
+    click.secho(msg, fg="red", err=True)
+    sys.exit(exit_code)
+
+
+def validate_model_parameters(model: str, params: Dict[str, Any]) -> None:
+    """Validate model parameters against model capabilities.
+
+    Args:
+        model: The model name to validate parameters for
+        params: Dictionary of parameter names and values to validate
+
+    Raises:
+        CLIError: If any parameters are not supported by the model
+    """
+    try:
+        capabilities = ModelRegistry().get_capabilities(model)
+        for param_name, value in params.items():
+            try:
+                capabilities.validate_parameter(param_name, value)
+            except OpenAIClientError as e:
+                logger.error(
+                    "Validation failed for model %s: %s", model, str(e)
+                )
+                raise CLIError(
+                    str(e),
+                    exit_code=ExitCode.VALIDATION_ERROR,
+                    context={
+                        "model": model,
+                        "param": param_name,
+                        "value": value,
+                    },
+                )
+    except (ModelNotSupportedError, ModelVersionError) as e:
+        logger.error("Model validation failed: %s", str(e))
+        raise CLIError(
+            str(e),
+            exit_code=ExitCode.VALIDATION_ERROR,
+            context={"model": model},
+        )
 
 
 async def stream_structured_output(
@@ -1329,91 +1333,103 @@ async def stream_structured_output(
     output_schema: Type[BaseModel],
     output_file: Optional[str] = None,
     **kwargs: Any,
-) -> None:
+) -> AsyncGenerator[BaseModel, None]:
     """Stream structured output from OpenAI API.
 
     This function follows the guide's recommendation for a focused async streaming function.
     It handles the core streaming logic and resource cleanup.
-    """
-    try:
-        # Base models that don't support streaming
-        non_streaming_models = {"o1", "o3"}
 
-        # Check if model supports streaming
-        # o3-mini and o3-mini-high support streaming, base o3 does not
-        use_streaming = model not in non_streaming_models and (
-            not model.startswith("o3") or model.startswith("o3-mini")
-        )
+    Args:
+        client: The OpenAI client to use
+        model: The model to use
+        system_prompt: The system prompt to use
+        user_prompt: The user prompt to use
+        output_schema: The Pydantic model to validate responses against
+        output_file: Optional file to write output to
+        **kwargs: Additional parameters to pass to the API
 
-        # All o1 and o3 models (base and variants) have fixed settings
-        stream_kwargs = {}
-        if not (model.startswith("o1") or model.startswith("o3")):
-            stream_kwargs = kwargs
-
-        if use_streaming:
-            async for chunk in async_openai_structured_stream(
-                client=client,
-                model=model,
-                output_schema=output_schema,
-                system_prompt=system_prompt,
-                user_prompt=user_prompt,
-                **stream_kwargs,
-            ):
-                if not chunk:
-                    continue
-
-                # Process and output the chunk
-                dumped = chunk.model_dump(mode="json")
-                json_str = json.dumps(dumped, indent=2)
-
-                if output_file:
-                    with open(output_file, "a", encoding="utf-8") as f:
-                        f.write(json_str)
-                        f.write("\n")
-                        f.flush()  # Ensure immediate flush to file
-                else:
-                    # Print directly to stdout with immediate flush
-                    print(json_str, flush=True)
-        else:
-            # For non-streaming models, use regular completion
-            response = await client.chat.completions.create(
-                model=model,
-                messages=[
-                    {"role": "system", "content": system_prompt},
-                    {"role": "user", "content": user_prompt},
-                ],
-                stream=False,
-                **stream_kwargs,
+    Returns:
+        An async generator yielding validated model instances
+
+    Raises:
+        ValueError: If the model does not support structured output or parameters are invalid
+        StreamInterruptedError: If the stream is interrupted
+        APIResponseError: If there is an API error
+    """
+    try:
+        # Check if model supports structured output using openai_structured's function
+        if not supports_structured_output(model):
+            raise ValueError(
+                f"Model {model} does not support structured output with json_schema response format. "
+                "Please use a model that supports structured output."
             )
 
-            # Process the single response
-            content = response.choices[0].message.content
-            if content:
-                try:
-                    # Parse and validate against schema
-                    result = output_schema.model_validate_json(content)
-                    json_str = json.dumps(
-                        result.model_dump(mode="json"), indent=2
-                    )
+        # Extract non-model parameters
+        on_log = kwargs.pop("on_log", None)
 
-                    if output_file:
-                        with open(output_file, "w", encoding="utf-8") as f:
-                            f.write(json_str)
-                            f.write("\n")
-                    else:
-                        print(json_str, flush=True)
-                except ValidationError as e:
-                    raise InvalidResponseFormatError(
-                        f"Response validation failed: {e}"
-                    )
+        # Handle model-specific parameters
+        stream_kwargs = {}
+        registry = ModelRegistry()
+        capabilities = registry.get_capabilities(model)
+
+        # Validate and include supported parameters
+        for param_name, value in kwargs.items():
+            if param_name in capabilities.supported_parameters:
+                # Validate the parameter value
+                capabilities.validate_parameter(param_name, value)
+                stream_kwargs[param_name] = value
             else:
-                raise EmptyResponseError("Model returned empty response")
+                logger.warning(
+                    f"Parameter {param_name} is not supported by model {model} and will be ignored"
+                )
 
+        # Log the API request details
+        logger.debug("Making OpenAI API request with:")
+        logger.debug("Model: %s", model)
+        logger.debug("System prompt: %s", system_prompt)
+        logger.debug("User prompt: %s", user_prompt)
+        logger.debug("Parameters: %s", json.dumps(stream_kwargs, indent=2))
+        logger.debug("Schema: %s", output_schema.model_json_schema())
+
+        # Use the async generator from openai_structured directly
+        async for chunk in async_openai_structured_stream(
+            client=client,
+            model=model,
+            system_prompt=system_prompt,
+            user_prompt=user_prompt,
+            output_schema=output_schema,
+            on_log=on_log,  # Pass non-model parameters directly to the function
+            **stream_kwargs,  # Pass only validated model parameters
+        ):
+            yield chunk
+
+    except APIResponseError as e:
+        if "Invalid schema for response_format" in str(
+            e
+        ) and 'type: "array"' in str(e):
+            error_msg = (
+                "OpenAI API Schema Error: The schema must have a root type of 'object', not 'array'. "
+                "To fix this:\n"
+                "1. Wrap your array in an object property, e.g.:\n"
+                "   {\n"
+                '     "type": "object",\n'
+                '     "properties": {\n'
+                '       "items": {\n'
+                '         "type": "array",\n'
+                '         "items": { ... your array items schema ... }\n'
+                "       }\n"
+                "     }\n"
+                "   }\n"
+                "2. Make sure to update your template to handle the wrapper object."
+            )
+            logger.error(error_msg)
+            raise InvalidResponseFormatError(error_msg)
+        logger.error(f"API error: {e}")
+        raise
     except (
         StreamInterruptedError,
         StreamBufferError,
         StreamParseError,
-        APIResponseError,
         EmptyResponseError,
         InvalidResponseFormatError,
     ) as e:
@@ -1424,149 +1440,457 @@ async def stream_structured_output(
         await client.close()
 
 
-async def run_cli_async(args: Namespace) -> ExitCode:
-    """Async wrapper for CLI operations.
+@click.group()
+@click.version_option(version=__version__)
+def cli() -> None:
+    """ostruct CLI - Make structured OpenAI API calls.
+
+    ostruct allows you to invoke OpenAI Structured Output to produce structured JSON
+    output using templates and JSON schemas. It provides support for file handling, variable
+    substitution, and output validation.
+
+    For detailed documentation, visit: https://ostruct.readthedocs.io
+
+    Examples:
+
+        # Basic usage with a template and schema
+
+        ostruct run task.j2 schema.json -V name=value
 
-    This function prepares everything needed for streaming and then calls
-    the focused streaming function.
+        # Process files with recursive directory scanning
+
+        ostruct run template.j2 schema.json -f code main.py -d src ./src -R
+
+        # Use JSON variables and custom model parameters
+
+        ostruct run task.j2 schema.json -J config='{"env":"prod"}' -m o3-mini
+    """
+    pass
+
+
+@cli.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 a structured task with template and schema.
+
+    TASK_TEMPLATE is the path to your Jinja2 template file that defines the task.
+    SCHEMA_FILE is the path to your JSON schema file that defines the expected output structure.
+
+    The command supports various options for file handling, variable definition,
+    model configuration, and output control. Use --help to see all available options.
+
+    Examples:
+        # Basic usage
+        ostruct run task.j2 schema.json
+
+        # Process multiple files
+        ostruct run task.j2 schema.json -f code main.py -f test tests/test_main.py
+
+        # Scan directories recursively
+        ostruct run task.j2 schema.json -d src ./src -R
+
+        # Define variables
+        ostruct run task.j2 schema.json -V debug=true -J config='{"env":"prod"}'
+
+        # Configure model
+        ostruct run task.j2 schema.json -m gpt-4 --temperature 0.7 --max-output-tokens 1000
+
+        # Control output
+        ostruct run task.j2 schema.json --output-file result.json --verbose
     """
     try:
-        # Validate and prepare all inputs
-        security_manager = validate_security_manager(
-            base_dir=args.base_dir,
-            allowed_dirs=args.allowed_dir,
-            allowed_dir_file=args.allowed_dir_file,
+        # Convert Click parameters to typed dict
+        params: CLIParams = {
+            "task_file": task_template,
+            "task": None,
+            "schema_file": schema_file,
+        }
+        # Add only valid keys from kwargs
+        valid_keys = set(CLIParams.__annotations__.keys())
+        for k, v in kwargs.items():
+            if k in valid_keys:
+                params[k] = v  # type: ignore[literal-required]
+
+        # 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))
+        finally:
+            loop.close()
+
+    except (
+        CLIError,
+        InvalidJSONError,
+        SchemaFileError,
+        SchemaValidationError,
+    ) 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)
+
+
+# Remove the old @create_click_command() decorator and cli function definition
+# Keep all the other functions and code below this point
+
+
+async def validate_model_params(args: CLIParams) -> Dict[str, Any]:
+    """Validate model parameters and return a dictionary of valid parameters.
+
+    Args:
+        args: Command line arguments
+
+    Returns:
+        Dictionary of validated model parameters
+
+    Raises:
+        CLIError: If model parameters are invalid
+    """
+    params = {
+        "temperature": args.get("temperature"),
+        "max_output_tokens": args.get("max_output_tokens"),
+        "top_p": args.get("top_p"),
+        "frequency_penalty": args.get("frequency_penalty"),
+        "presence_penalty": args.get("presence_penalty"),
+        "reasoning_effort": args.get("reasoning_effort"),
+    }
+    # Remove None values
+    params = {k: v for k, v in params.items() if v is not None}
+    validate_model_parameters(args["model"], params)
+    return params
+
+
+async def validate_inputs(
+    args: CLIParams,
+) -> Tuple[
+    SecurityManager, str, Dict[str, Any], Dict[str, Any], jinja2.Environment
+]:
+    """Validate all input parameters and return validated components.
+
+    Args:
+        args: Command line arguments
+
+    Returns:
+        Tuple containing:
+        - SecurityManager instance
+        - Task template string
+        - Schema dictionary
+        - Template context dictionary
+        - Jinja2 environment
+
+    Raises:
+        CLIError: For various validation errors
+    """
+    logger.debug("=== Input Validation Phase ===")
+    security_manager = validate_security_manager(
+        base_dir=args.get("base_dir"),
+        allowed_dirs=args.get("allowed_dirs"),
+        allowed_dir_file=args.get("allowed_dir_file"),
+    )
+
+    task_template = validate_task_template(
+        args.get("task"), args.get("task_file")
+    )
+    logger.debug("Validating schema from %s", args["schema_file"])
+    schema = validate_schema_file(
+        args["schema_file"], args.get("verbose", False)
+    )
+    template_context = await create_template_context_from_args(
+        args, security_manager
+    )
+    env = create_jinja_env()
+
+    return security_manager, task_template, schema, template_context, env
+
+
+async def process_templates(
+    args: CLIParams,
+    task_template: str,
+    template_context: Dict[str, Any],
+    env: jinja2.Environment,
+) -> Tuple[str, str]:
+    """Process system prompt and user prompt templates.
+
+    Args:
+        args: Command line arguments
+        task_template: Validated task template
+        template_context: Template context dictionary
+        env: Jinja2 environment
+
+    Returns:
+        Tuple of (system_prompt, user_prompt)
+
+    Raises:
+        CLIError: For template processing errors
+    """
+    logger.debug("=== Template Processing Phase ===")
+    system_prompt = process_system_prompt(
+        task_template,
+        args.get("system_prompt"),
+        args.get("system_prompt_file"),
+        template_context,
+        env,
+        args.get("ignore_task_sysprompt", False),
+    )
+    user_prompt = render_template(task_template, template_context, env)
+    return system_prompt, user_prompt
+
 
-        task_template = validate_task_template(args.task, args.task_file)
-        logger.debug("Validating schema from %s", args.schema_file)
-        schema = validate_schema_file(args.schema_file, args.verbose)
-        template_context = create_template_context_from_args(
-            args, security_manager
+async def validate_model_and_schema(
+    args: CLIParams,
+    schema: Dict[str, Any],
+    system_prompt: str,
+    user_prompt: str,
+) -> Tuple[Type[BaseModel], List[Dict[str, str]], int, ModelRegistry]:
+    """Validate model compatibility and schema, and check token limits.
+
+    Args:
+        args: Command line arguments
+        schema: Schema dictionary
+        system_prompt: Processed system prompt
+        user_prompt: Processed user prompt
+
+    Returns:
+        Tuple of (output_model, messages, total_tokens, registry)
+
+    Raises:
+        CLIError: For validation errors
+        ModelCreationError: When model creation fails
+        SchemaValidationError: When schema is invalid
+    """
+    logger.debug("=== Model & Schema Validation Phase ===")
+    try:
+        output_model = create_dynamic_model(
+            schema,
+            show_schema=args.get("show_model_schema", False),
+            debug_validation=args.get("debug_validation", False),
         )
-        env = create_jinja_env()
-
-        # Process system prompt and render task
-        system_prompt = process_system_prompt(
-            task_template,
-            args.system_prompt,
-            args.system_prompt_file,
-            template_context,
-            env,
-            args.ignore_task_sysprompt,
+        logger.debug("Successfully created output model")
+    except (
+        SchemaFileError,
+        InvalidJSONError,
+        SchemaValidationError,
+        ModelCreationError,
+    ) as e:
+        logger.error("Schema error: %s", str(e))
+        raise
+
+    if not supports_structured_output(args["model"]):
+        msg = f"Model {args['model']} does not support structured output"
+        logger.error(msg)
+        raise ModelNotSupportedError(msg)
+
+    messages = [
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": user_prompt},
+    ]
+
+    total_tokens = estimate_tokens_with_encoding(messages, args["model"])
+    registry = ModelRegistry()
+    capabilities = registry.get_capabilities(args["model"])
+    context_limit = capabilities.context_window
+
+    if total_tokens > context_limit:
+        msg = f"Total tokens ({total_tokens}) exceeds model context limit ({context_limit})"
+        logger.error(msg)
+        raise CLIError(
+            msg,
+            context={
+                "total_tokens": total_tokens,
+                "context_limit": context_limit,
+            },
         )
-        rendered_task = render_template(task_template, template_context, env)
-        logger.info("Rendered task template: %s", rendered_task)
 
-        if args.dry_run:
-            logger.info("DRY RUN MODE")
-            return ExitCode.SUCCESS
+    return output_model, messages, total_tokens, registry
 
-        # Create output model
-        logger.debug("Creating output model")
-        try:
-            output_model = create_dynamic_model(
-                schema,
-                base_name="OutputModel",
-                show_schema=args.show_model_schema,
-                debug_validation=args.debug_validation,
-            )
-            logger.debug("Successfully created output model")
-        except (
-            SchemaFileError,
-            InvalidJSONError,
-            SchemaValidationError,
-            ModelCreationError,
-        ) as e:
-            logger.error("Schema error: %s", str(e))
-            raise  # Let the error propagate with its context
-
-        # Validate model support and token usage
-        try:
-            supports_structured_output(args.model)
-        except (ModelNotSupportedError, ModelVersionError) as e:
-            logger.error("Model validation error: %s", str(e))
-            raise  # Let the error propagate with its context
-
-        messages = [
-            {"role": "system", "content": system_prompt},
-            {"role": "user", "content": rendered_task},
-        ]
-        total_tokens = estimate_tokens_for_chat(messages, args.model)
-        context_limit = get_context_window_limit(args.model)
-        if total_tokens > context_limit:
-            msg = f"Total tokens ({total_tokens}) exceeds model context limit ({context_limit})"
-            logger.error(msg)
-            raise CLIError(
-                msg,
-                context={
-                    "total_tokens": total_tokens,
-                    "context_limit": context_limit,
-                },
-            )
 
-        # Get API key and create client
-        api_key = args.api_key or os.getenv("OPENAI_API_KEY")
-        if not api_key:
-            msg = "No OpenAI API key provided (--api-key or OPENAI_API_KEY env var)"
-            logger.error(msg)
-            raise CLIError(msg)
+async def execute_model(
+    args: CLIParams,
+    params: Dict[str, Any],
+    output_model: Type[BaseModel],
+    system_prompt: str,
+    user_prompt: str,
+) -> ExitCode:
+    """Execute the model and handle the response.
 
-        client = AsyncOpenAI(api_key=api_key, timeout=args.timeout)
+    Args:
+        args: Command line arguments
+        params: Validated model parameters
+        output_model: Generated Pydantic model
+        system_prompt: Processed system prompt
+        user_prompt: Processed user prompt
 
-        # Create detailed log callback
-        def log_callback(
-            level: int, message: str, extra: dict[str, Any]
-        ) -> None:
-            if args.debug_openai_stream:
-                if extra:
-                    extra_str = json.dumps(extra, indent=2)
-                    message = f"{message}\nDetails:\n{extra_str}"
-                logger.log(level, message, extra=extra)
+    Returns:
+        Exit code indicating success or failure
 
-        # Stream the output
-        try:
-            await stream_structured_output(
-                client=client,
-                model=args.model,
-                system_prompt=system_prompt,
-                user_prompt=rendered_task,
-                output_schema=output_model,
-                output_file=args.output_file,
-                temperature=args.temperature,
-                max_tokens=args.max_tokens,
-                top_p=args.top_p,
-                frequency_penalty=args.frequency_penalty,
-                presence_penalty=args.presence_penalty,
-                timeout=args.timeout,
-                on_log=log_callback,
+    Raises:
+        CLIError: For execution errors
+    """
+    logger.debug("=== Execution Phase ===")
+    api_key = args.get("api_key") or os.getenv("OPENAI_API_KEY")
+    if not api_key:
+        msg = "No API key provided. Set OPENAI_API_KEY environment variable or use --api-key"
+        logger.error(msg)
+        raise CLIError(msg, exit_code=ExitCode.API_ERROR)
+
+    client = AsyncOpenAI(api_key=api_key, timeout=args.get("timeout", 60.0))
+
+    # Create detailed log callback
+    def log_callback(level: int, message: str, extra: dict[str, Any]) -> None:
+        if args.get("debug_openai_stream", False):
+            if extra:
+                extra_str = LogSerializer.serialize_log_extra(extra)
+                if extra_str:
+                    logger.debug("%s\nExtra:\n%s", message, extra_str)
+                else:
+                    logger.debug("%s\nExtra: Failed to serialize", message)
+            else:
+                logger.debug(message)
+
+    try:
+        # Create output buffer
+        output_buffer = []
+
+        # Stream the response
+        async for response in stream_structured_output(
+            client=client,
+            model=args["model"],
+            system_prompt=system_prompt,
+            user_prompt=user_prompt,
+            output_schema=output_model,
+            output_file=args.get("output_file"),
+            on_log=log_callback,
+        ):
+            output_buffer.append(response)
+
+        # Handle final output
+        output_file = args.get("output_file")
+        if output_file:
+            with open(output_file, "w") as f:
+                if len(output_buffer) == 1:
+                    f.write(output_buffer[0].model_dump_json(indent=2))
+                else:
+                    # Build complete JSON array as a single string
+                    json_output = "[\n"
+                    for i, response in enumerate(output_buffer):
+                        if i > 0:
+                            json_output += ",\n"
+                        json_output += "  " + response.model_dump_json(
+                            indent=2
+                        ).replace("\n", "\n  ")
+                    json_output += "\n]"
+                    f.write(json_output)
+        else:
+            # Write to stdout when no output file is specified
+            if len(output_buffer) == 1:
+                print(output_buffer[0].model_dump_json(indent=2))
+            else:
+                # Build complete JSON array as a single string
+                json_output = "[\n"
+                for i, response in enumerate(output_buffer):
+                    if i > 0:
+                        json_output += ",\n"
+                    json_output += "  " + response.model_dump_json(
+                        indent=2
+                    ).replace("\n", "\n  ")
+                json_output += "\n]"
+                print(json_output)
+
+        return ExitCode.SUCCESS
+
+    except (
+        StreamInterruptedError,
+        StreamBufferError,
+        StreamParseError,
+        APIResponseError,
+        EmptyResponseError,
+        InvalidResponseFormatError,
+    ) as e:
+        logger.error("Stream error: %s", str(e))
+        raise CLIError(str(e), exit_code=ExitCode.API_ERROR)
+    except Exception as e:
+        logger.exception("Unexpected error during streaming")
+        raise CLIError(str(e), exit_code=ExitCode.UNKNOWN_ERROR)
+    finally:
+        await client.close()
+
+
+async def run_cli_async(args: CLIParams) -> ExitCode:
+    """Async wrapper for CLI operations.
+
+    Returns:
+        Exit code to return from the CLI
+
+    Raises:
+        CLIError: For various error conditions
+        KeyboardInterrupt: When operation is cancelled by user
+    """
+    try:
+        # 0. Model Parameter Validation
+        logger.debug("=== Model Parameter Validation ===")
+        params = await validate_model_params(args)
+
+        # 1. Input Validation Phase
+        security_manager, task_template, schema, template_context, env = (
+            await validate_inputs(args)
+        )
+
+        # 2. Template Processing Phase
+        system_prompt, user_prompt = await process_templates(
+            args, task_template, template_context, env
+        )
+
+        # 3. Model & Schema Validation Phase
+        output_model, messages, total_tokens, registry = (
+            await validate_model_and_schema(
+                args, schema, system_prompt, user_prompt
             )
+        )
+
+        # 4. Dry Run Output Phase
+        if args.get("dry_run", False):
+            logger.info("\n=== Dry Run Summary ===")
+            logger.info("✓ Template rendered successfully")
+            logger.info("✓ Schema validation passed")
+            logger.info("✓ Model compatibility validated")
+            logger.info(
+                f"✓ Token count: {total_tokens}/{registry.get_capabilities(args['model']).context_window}"
+            )
+
+            if args.get("verbose", False):
+                logger.info("\nSystem Prompt:")
+                logger.info("-" * 40)
+                logger.info(system_prompt)
+                logger.info("\nRendered Template:")
+                logger.info("-" * 40)
+                logger.info(user_prompt)
+
             return ExitCode.SUCCESS
-        except (
-            StreamInterruptedError,
-            StreamBufferError,
-            StreamParseError,
-            APIResponseError,
-            EmptyResponseError,
-            InvalidResponseFormatError,
-        ) as e:
-            logger.error("Stream error: %s", str(e))
-            raise  # Let stream errors propagate
-        except (APIConnectionError, InternalServerError) as e:
-            logger.error("API connection error: %s", str(e))
-            raise APIResponseError(str(e))  # Convert to our error type
-        except RateLimitError as e:
-            logger.error("Rate limit exceeded: %s", str(e))
-            raise APIResponseError(str(e))  # Convert to our error type
-        except (BadRequestError, AuthenticationError, OpenAIClientError) as e:
-            logger.error("API client error: %s", str(e))
-            raise APIResponseError(str(e))  # Convert to our error type
-        finally:
-            await client.close()
+
+        # 5. Execution Phase
+        return await execute_model(
+            args, params, output_model, system_prompt, user_prompt
+        )
 
     except KeyboardInterrupt:
         logger.info("Operation cancelled by user")
-        return ExitCode.INTERRUPTED
+        raise
     except Exception as e:
         if isinstance(e, CLIError):
             raise  # Let our custom errors propagate
@@ -1580,65 +1904,35 @@ def create_cli() -> click.Command:
     Returns:
         click.Command: The CLI command object
     """
-
-    @create_click_command()
-    def cli(**kwargs: Any) -> None:
-        """CLI entry point for structured OpenAI API calls."""
-        try:
-            args = Namespace(**kwargs)
-
-            # Validate required arguments first
-            if not args.task and not args.task_file:
-                raise click.UsageError(
-                    "Must specify either --task or --task-file"
-                )
-            if not args.schema_file:
-                raise click.UsageError("Missing option '--schema-file'")
-            if args.task and args.task_file:
-                raise click.UsageError(
-                    "Cannot specify both --task and --task-file"
-                )
-            if args.system_prompt and args.system_prompt_file:
-                raise click.UsageError(
-                    "Cannot specify both --system-prompt and --system-prompt-file"
-                )
-
-            # Run the async function synchronously
-            exit_code = asyncio.run(run_cli_async(args))
-
-            if exit_code != ExitCode.SUCCESS:
-                error_msg = f"Command failed with exit code {exit_code}"
-                if hasattr(ExitCode, exit_code.name):
-                    error_msg = f"{error_msg} ({exit_code.name})"
-                raise CLIError(error_msg, context={"exit_code": exit_code})
-
-        except click.UsageError:
-            # Let Click handle usage errors directly
-            raise
-        except InvalidJSONError:
-            # Let InvalidJSONError propagate directly
-            raise
-        except CLIError:
-            # Let our custom errors propagate with their context
-            raise
-        except Exception as e:
-            # Convert other exceptions to CLIError
-            logger.exception("Unexpected error")
-            raise CLIError(str(e), context={"error_type": type(e).__name__})
-
-    return cli
+    return cli  # The decorator already returns a Command
 
 
 def main() -> None:
     """Main entry point for the CLI."""
-    cli = create_cli()
-    cli(standalone_mode=False)
+    try:
+        cli(standalone_mode=False)
+    except (
+        CLIError,
+        InvalidJSONError,
+        SchemaFileError,
+        SchemaValidationError,
+    ) 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)
 
 
 # Export public API
 __all__ = [
     "ExitCode",
-    "estimate_tokens_for_chat",
+    "estimate_tokens_with_encoding",
     "parse_json_var",
     "create_dynamic_model",
     "validate_path_mapping",
@@ -1656,26 +1950,23 @@ def create_dynamic_model(
     """Create a Pydantic model from a JSON schema.
 
     Args:
-        schema: JSON schema dict, can be wrapped in {"schema": ...} format
-        base_name: Base name for the model
-        show_schema: Whether to show the generated schema
-        debug_validation: Whether to enable validation debugging
+        schema: JSON schema to create model from
+        base_name: Name for the model class
+        show_schema: Whether to show the generated model schema
+        debug_validation: Whether to show detailed validation errors
 
     Returns:
-        Generated Pydantic model class
+        Type[BaseModel]: The generated Pydantic model class
 
     Raises:
-        ModelCreationError: When model creation fails
-        SchemaValidationError: When schema is invalid
+        ModelValidationError: If the schema is invalid
+        SchemaValidationError: If the schema violates OpenAI requirements
     """
     if debug_validation:
         logger.info("Creating dynamic model from schema:")
         logger.info(json.dumps(schema, indent=2))
 
     try:
-        # Extract required fields
-        required: Set[str] = set(schema.get("required", []))
-
         # Handle our wrapper format if present
         if "schema" in schema:
             if debug_validation:
@@ -1698,32 +1989,15 @@ def create_dynamic_model(
                 logger.info(json.dumps(inner_schema, indent=2))
             schema = inner_schema
 
-        # Ensure schema has type field
-        if "type" not in schema:
-            if debug_validation:
-                logger.info("Schema missing type field, assuming object type")
-            schema["type"] = "object"
+        # Validate against OpenAI requirements
+        from .schema_validation import validate_openai_schema
 
-        # For non-object root schemas, create a wrapper model
-        if schema["type"] != "object":
-            if debug_validation:
-                logger.info(
-                    "Converting non-object root schema to object wrapper"
-                )
-            schema = {
-                "type": "object",
-                "properties": {"value": schema},
-                "required": ["value"],
-            }
+        validate_openai_schema(schema)
 
         # Create model configuration
         config = ConfigDict(
             title=schema.get("title", base_name),
-            extra=(
-                "forbid"
-                if schema.get("additionalProperties") is False
-                else "allow"
-            ),
+            extra="forbid",  # OpenAI requires additionalProperties: false
             validate_default=True,
             use_enum_values=True,
             arbitrary_types_allowed=True,
@@ -1758,18 +2032,17 @@ def create_dynamic_model(
                 "  JSON Schema Extra: %s", config.get("json_schema_extra")
             )
 
-        # Create field definitions
-        field_definitions: Dict[str, FieldDefinition] = {}
+        # Process schema properties into fields
         properties = schema.get("properties", {})
+        required = schema.get("required", [])
 
+        field_definitions: Dict[str, Tuple[Type[Any], FieldInfoType]] = {}
         for field_name, field_schema in properties.items():
-            try:
-                if debug_validation:
-                    logger.info("Processing field %s:", field_name)
-                    logger.info(
-                        "  Schema: %s", json.dumps(field_schema, indent=2)
-                    )
+            if debug_validation:
+                logger.info("Processing field %s:", field_name)
+                logger.info("  Schema: %s", json.dumps(field_schema, indent=2))
 
+            try:
                 python_type, field = _get_type_with_constraints(
                     field_schema, field_name, base_name
                 )
@@ -1804,22 +2077,24 @@ def create_dynamic_model(
                 raise ModelValidationError(base_name, [str(e)])
 
         # Create the model with the fields
-        model = create_model(
-            base_name,
-            __config__=config,
-            **{
-                name: (
-                    (
-                        cast(Type[Any], field_type)
-                        if is_container_type(field_type)
-                        else field_type
-                    ),
-                    field,
-                )
-                for name, (field_type, field) in field_definitions.items()
-            },
+        field_defs: Dict[str, Any] = {
+            name: (
+                (
+                    cast(Type[Any], field_type)
+                    if is_container_type(field_type)
+                    else field_type
+                ),
+                field,
+            )
+            for name, (field_type, field) in field_definitions.items()
+        }
+        model: Type[BaseModel] = create_model(
+            base_name, __config__=config, **field_defs
         )
 
+        # Set the model config after creation
+        model.model_config = config
+
         if debug_validation:
             logger.info("Successfully created model: %s", model.__name__)
             logger.info("Model config: %s", dict(model.model_config))
@@ -1832,28 +2107,38 @@ def create_dynamic_model(
         try:
             model.model_json_schema()
         except ValidationError as e:
-            if debug_validation:
-                logger.error("Schema validation failed:")
-                logger.error("  Error type: %s", type(e).__name__)
-                logger.error("  Error message: %s", str(e))
-                if hasattr(e, "errors"):
-                    logger.error("  Validation errors:")
-                    for error in e.errors():
-                        logger.error("    - %s", error)
             validation_errors = (
                 [str(err) for err in e.errors()]
                 if hasattr(e, "errors")
                 else [str(e)]
             )
+            if debug_validation:
+                logger.error("Schema validation failed:")
+                logger.error("  Error type: %s", type(e).__name__)
+                logger.error("  Error message: %s", str(e))
             raise ModelValidationError(base_name, validation_errors)
 
-        return cast(Type[BaseModel], model)
+        return model
+
+    except SchemaValidationError as e:
+        # Always log basic error info
+        logger.error("Schema validation error: %s", str(e))
+
+        # Log additional debug info if requested
+        if debug_validation:
+            logger.error("  Error type: %s", type(e).__name__)
+            logger.error("  Error details: %s", str(e))
+        # Always raise schema validation errors directly
+        raise
 
     except Exception as e:
+        # Always log basic error info
+        logger.error("Model creation error: %s", str(e))
+
+        # Log additional debug info if requested
         if debug_validation:
-            logger.error("Failed to create model:")
             logger.error("  Error type: %s", type(e).__name__)
-            logger.error("  Error message: %s", str(e))
+            logger.error("  Error details: %s", str(e))
             if hasattr(e, "__cause__"):
                 logger.error("  Caused by: %s", str(e.__cause__))
             if hasattr(e, "__context__"):
@@ -1865,9 +2150,11 @@ def create_dynamic_model(
                     "  Traceback:\n%s",
                     "".join(traceback.format_tb(e.__traceback__)),
                 )
+        # Always wrap other errors as ModelCreationError
         raise ModelCreationError(
-            f"Failed to create model '{base_name}': {str(e)}"
-        )
+            f"Failed to create model {base_name}",
+            context={"error": str(e)},
+        ) from e
 
 
 # Validation functions