ostruct-cli 0.4.0__tar.gz → 0.5.0__tar.gz

{ostruct_cli-0.4.0 → ostruct_cli-0.5.0}/PKG-INFO

@@ -1,12 +1,11 @@
 Metadata-Version: 2.3
 Name: ostruct-cli
-Version: 0.4.0
+Version: 0.5.0
 Summary: CLI for OpenAI Structured Output
 Author: Yaniv Golan
 Author-email: yaniv@golan.name
-Requires-Python: >=3.9,<4.0
+Requires-Python: >=3.10,<4.0
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -17,10 +16,10 @@ Requires-Dist: click (>=8.1.7,<9.0.0)
 Requires-Dist: ijson (>=3.2.3,<4.0.0)
 Requires-Dist: jsonschema (>=4.23.0,<5.0.0)
 Requires-Dist: openai (>=1.0.0,<2.0.0)
-Requires-Dist: openai-structured (>=1.3.0,<2.0.0)
+Requires-Dist: openai-structured (>=2.0.0,<3.0.0)
 Requires-Dist: pydantic (>=2.6.3,<3.0.0)
 Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
-Requires-Dist: tiktoken (>=0.8.0,<0.9.0)
+Requires-Dist: tiktoken (>=0.9.0,<0.10.0)
 Requires-Dist: tomli (>=2.0.1,<3.0.0) ; python_version < "3.11"
 Requires-Dist: typing-extensions (>=4.9.0,<5.0.0)
 Requires-Dist: werkzeug (>=3.1.3,<4.0.0)
@@ -91,7 +90,16 @@ Extract information about the person: {{ stdin }}
 4. Run the CLI:
 
 ```bash
-echo "John Smith is a 35 year old software engineer" | ostruct --task @task.j2 --schema schema.json
+ostruct run task.j2 schema.json
+```
+
+Or with more options:
+
+```bash
+ostruct run task.j2 schema.json \
+  -f content input.txt \
+  -m gpt-4o \
+  --sys-prompt "You are an expert content analyzer"
 ```
 
 Output:
@@ -112,15 +120,56 @@ Template files use the `.j2` extension to indicate they contain Jinja2 template
 - Makes it clear the file contains template logic
 - Follows industry standards for Jinja2 templates
 
-While the CLI accepts templates with any extension (when prefixed with `@`), we recommend using `.j2` for better tooling support and clarity.
+## CLI Options
+
+The CLI revolves around a single subcommand called `run`. Basic usage:
+
+```bash
+ostruct run <TASK_TEMPLATE> <SCHEMA_FILE> [OPTIONS]
+```
+
+Common options include:
+
+- File & Directory Inputs:
+  - `-f <NAME> <PATH>`: Map a single file to a variable name
+  - `-d <NAME> <DIR>`: Map a directory to a variable name
+  - `-p <NAME> <PATTERN>`: Map files matching a glob pattern to a variable name
+  - `-R, --recursive`: Enable recursive directory/pattern scanning
+
+- Variables:
+  - `-V name=value`: Define a simple string variable
+  - `-J name='{"key":"value"}'`: Define a JSON variable
+
+- Model Parameters:
+  - `-m, --model MODEL`: Select the OpenAI model (supported: gpt-4o, o1, o3-mini)
+  - `--temperature FLOAT`: Set sampling temperature (0.0-2.0)
+  - `--max-output-tokens INT`: Set maximum output tokens
+  - `--top-p FLOAT`: Set top-p sampling parameter (0.0-1.0)
+  - `--frequency-penalty FLOAT`: Adjust frequency penalty (-2.0-2.0)
+  - `--presence-penalty FLOAT`: Adjust presence penalty (-2.0-2.0)
+  - `--reasoning-effort [low|medium|high]`: Control model reasoning effort
+
+- System Prompt:
+  - `--sys-prompt TEXT`: Provide system prompt directly
+  - `--sys-file FILE`: Load system prompt from file
+  - `--ignore-task-sysprompt`: Ignore system prompt in template frontmatter
+
+- API Configuration:
+  - `--api-key KEY`: OpenAI API key (defaults to OPENAI_API_KEY env var)
+  - `--timeout FLOAT`: API timeout in seconds (default: 60.0)
 
 ## Debug Options
 
-- `--show-model-schema`: Display the generated Pydantic model schema
 - `--debug-validation`: Show detailed schema validation debugging
-- `--verbose-schema`: Enable verbose schema debugging output
-- `--debug-openai-stream`: Enable low-level debug output for OpenAI streaming (very verbose)
-- `--progress-level {none,basic,detailed}`: Set progress reporting level (default: basic)
+- `--debug-openai-stream`: Enable low-level debug output for OpenAI streaming
+- `--progress-level {none,basic,detailed}`: Set progress reporting level
+  - `none`: No progress indicators
+  - `basic`: Show key operation steps (default)
+  - `detailed`: Show all steps with additional info
+- `--show-model-schema`: Display the generated Pydantic model schema
+- `--verbose`: Enable verbose logging
+- `--dry-run`: Validate and render template without making API calls
+- `--no-progress`: Disable all progress indicators
 
 All debug and error logs are written to:
 
@@ -174,13 +223,3 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 This project is licensed under the MIT License - see the LICENSE file for details.
 
-## Migration from openai-structured
-
-If you were previously using the CLI bundled with openai-structured (pre-1.0.0), this is its new home. The migration is straightforward:
-
-1. Update openai-structured to version 1.0.0 or later
-2. Install ostruct-cli
-3. Replace any `openai-structured` CLI commands with `ostruct`
-
-The functionality remains the same, just moved to a dedicated package for better maintenance and focus.
-

{ostruct_cli-0.4.0 → ostruct_cli-0.5.0}/README.md

@@ -63,7 +63,16 @@ Extract information about the person: {{ stdin }}
 4. Run the CLI:
 
 ```bash
-echo "John Smith is a 35 year old software engineer" | ostruct --task @task.j2 --schema schema.json
+ostruct run task.j2 schema.json
+```
+
+Or with more options:
+
+```bash
+ostruct run task.j2 schema.json \
+  -f content input.txt \
+  -m gpt-4o \
+  --sys-prompt "You are an expert content analyzer"
 ```
 
 Output:
@@ -84,15 +93,56 @@ Template files use the `.j2` extension to indicate they contain Jinja2 template
 - Makes it clear the file contains template logic
 - Follows industry standards for Jinja2 templates
 
-While the CLI accepts templates with any extension (when prefixed with `@`), we recommend using `.j2` for better tooling support and clarity.
+## CLI Options
+
+The CLI revolves around a single subcommand called `run`. Basic usage:
+
+```bash
+ostruct run <TASK_TEMPLATE> <SCHEMA_FILE> [OPTIONS]
+```
+
+Common options include:
+
+- File & Directory Inputs:
+  - `-f <NAME> <PATH>`: Map a single file to a variable name
+  - `-d <NAME> <DIR>`: Map a directory to a variable name
+  - `-p <NAME> <PATTERN>`: Map files matching a glob pattern to a variable name
+  - `-R, --recursive`: Enable recursive directory/pattern scanning
+
+- Variables:
+  - `-V name=value`: Define a simple string variable
+  - `-J name='{"key":"value"}'`: Define a JSON variable
+
+- Model Parameters:
+  - `-m, --model MODEL`: Select the OpenAI model (supported: gpt-4o, o1, o3-mini)
+  - `--temperature FLOAT`: Set sampling temperature (0.0-2.0)
+  - `--max-output-tokens INT`: Set maximum output tokens
+  - `--top-p FLOAT`: Set top-p sampling parameter (0.0-1.0)
+  - `--frequency-penalty FLOAT`: Adjust frequency penalty (-2.0-2.0)
+  - `--presence-penalty FLOAT`: Adjust presence penalty (-2.0-2.0)
+  - `--reasoning-effort [low|medium|high]`: Control model reasoning effort
+
+- System Prompt:
+  - `--sys-prompt TEXT`: Provide system prompt directly
+  - `--sys-file FILE`: Load system prompt from file
+  - `--ignore-task-sysprompt`: Ignore system prompt in template frontmatter
+
+- API Configuration:
+  - `--api-key KEY`: OpenAI API key (defaults to OPENAI_API_KEY env var)
+  - `--timeout FLOAT`: API timeout in seconds (default: 60.0)
 
 ## Debug Options
 
-- `--show-model-schema`: Display the generated Pydantic model schema
 - `--debug-validation`: Show detailed schema validation debugging
-- `--verbose-schema`: Enable verbose schema debugging output
-- `--debug-openai-stream`: Enable low-level debug output for OpenAI streaming (very verbose)
-- `--progress-level {none,basic,detailed}`: Set progress reporting level (default: basic)
+- `--debug-openai-stream`: Enable low-level debug output for OpenAI streaming
+- `--progress-level {none,basic,detailed}`: Set progress reporting level
+  - `none`: No progress indicators
+  - `basic`: Show key operation steps (default)
+  - `detailed`: Show all steps with additional info
+- `--show-model-schema`: Display the generated Pydantic model schema
+- `--verbose`: Enable verbose logging
+- `--dry-run`: Validate and render template without making API calls
+- `--no-progress`: Disable all progress indicators
 
 All debug and error logs are written to:
 
@@ -145,13 +195,3 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 ## License
 
 This project is licensed under the MIT License - see the LICENSE file for details.
-
-## Migration from openai-structured
-
-If you were previously using the CLI bundled with openai-structured (pre-1.0.0), this is its new home. The migration is straightforward:
-
-1. Update openai-structured to version 1.0.0 or later
-2. Install ostruct-cli
-3. Replace any `openai-structured` CLI commands with `ostruct`
-
-The functionality remains the same, just moved to a dedicated package for better maintenance and focus.

{ostruct_cli-0.4.0 → ostruct_cli-0.5.0}/pyproject.toml

@@ -4,27 +4,28 @@
 
     [tool.poetry]
     name = "ostruct-cli"
-    version = "0.4.0"
+    version = "0.5.0"
     description = "CLI for OpenAI Structured Output"
     authors = ["Yaniv Golan <yaniv@golan.name>"]
     readme = "README.md"
     packages = [{include = "ostruct", from = "src"}]
+    include = ["py.typed"]
 
     [tool.poetry.dependencies]
-    python = ">=3.9,<4.0"
+    python = ">=3.10,<4.0"
     pydantic = "^2.6.3"
     jsonschema = "^4.23.0"
     chardet = "^5.0.0"
     cachetools = "^5.3.2"
     ijson = "^3.2.3"
     typing-extensions = "^4.9.0"
-    tiktoken = "^0.8.0"
+    tiktoken = "^0.9.0"
     pyyaml = "^6.0.2"
     tomli = {version = "^2.0.1", python = "<3.11"}
     click = "^8.1.7"
     werkzeug = "^3.1.3"
     openai = "^1.0.0"
-    openai-structured = "^1.3.0"
+    openai-structured = "^2.0.0"
 
     [tool.poetry.scripts]
     ostruct = "ostruct.cli.cli:main"
@@ -68,26 +69,31 @@
 
     [tool.mypy]
     plugins = ["pydantic.mypy"]
-    strict = true
-    exclude = [
-        "docs/",
-        "examples/"
-    ]
-    packages = ["ostruct", "tests"]
-    python_version = "3.9"
+    python_version = "3.10"
     warn_unused_configs = true
-    disallow_untyped_defs = true
+    exclude = ["docs/*", "examples/*"]
+    disallow_untyped_defs = false
     check_untyped_defs = true
-    warn_redundant_casts = true
-    warn_unused_ignores = true
-    warn_return_any = true
-    warn_unreachable = true
+    warn_return_any = false
+    warn_unused_ignores = false
     show_error_codes = true
-    ignore_missing_imports = false
+
+    # Stricter settings for source code
+    [[tool.mypy.overrides]]
+    module = "ostruct.*"
+    disallow_untyped_defs = true
+    warn_return_any = true
+    warn_unused_ignores = true
+
+    # Special handling for Click-related code
+    [[tool.mypy.overrides]]
+    module = ["click.*", "ostruct.cli.click_options"]
+    disallow_untyped_decorators = false
+    warn_return_any = false
 
     [tool.black]
     line-length = 79
-    target-version = ["py39"]
+    target-version = ["py310"]
     include = '\.pyi?$'
     preview = false
     required-version = "24.8.0"
@@ -109,7 +115,7 @@
     asyncio_default_fixture_loop_scope = "function"
 
     [tool.ruff]
-    target-version = "py39"
+    target-version = "py310"
 
     [tool.poetry.group.examples]
     optional = true

ostruct_cli-0.5.0/src/ostruct/cli/base_errors.py

@@ -0,0 +1,183 @@
+"""Base error classes for CLI error handling."""
+
+import logging
+import socket
+import sys
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+import click
+
+from .. import __version__
+from .exit_codes import ExitCode
+
+logger = logging.getLogger(__name__)
+
+
+class CLIError(Exception):
+    """Base class for CLI errors.
+
+    Context Dictionary Conventions:
+    - schema_path: Path to schema file (preserved for compatibility)
+    - source: Origin of error (new standard, falls back to schema_path)
+    - path: File or directory path
+    - details: Additional structured error information
+    - timestamp: When the error occurred
+    - host: System hostname
+    - version: Software version
+    """
+
+    def __init__(
+        self,
+        message: str,
+        context: Optional[Dict[str, Any]] = None,
+        exit_code: int = ExitCode.INTERNAL_ERROR,
+        details: Optional[str] = None,
+    ) -> None:
+        """Initialize CLI error.
+
+        Args:
+            message: Error message
+            context: Optional context dictionary following conventions
+            exit_code: Exit code to use (defaults to INTERNAL_ERROR)
+            details: Optional detailed explanation of the error
+        """
+        super().__init__(message)
+        self.message = message
+        self.context = context or {}
+        self.exit_code = exit_code
+
+        # Add standard context fields
+        if details:
+            self.context["details"] = details
+
+        # Add runtime context
+        self.context.update(
+            {
+                "timestamp": datetime.utcnow().isoformat(),
+                "host": socket.gethostname(),
+                "version": __version__,
+                "python_version": sys.version.split()[0],
+            }
+        )
+
+    @property
+    def source(self) -> Optional[str]:
+        """Get error source with backward compatibility."""
+        return self.context.get("source") or self.context.get("schema_path")
+
+    def show(self, file: bool = True) -> None:
+        """Display error message to user.
+
+        Args:
+            file: Whether to write to stderr (True) or stdout (False)
+        """
+        click.secho(str(self), fg="red", err=file)
+
+    def __str__(self) -> str:
+        """Get string representation of error.
+
+        Format:
+        [ERROR_TYPE] Primary Message
+        Details: Explanation
+        Source: Origin
+        Path: /path/to/resource
+        Additional context fields...
+        Troubleshooting:
+        1. First step
+        2. Second step
+        """
+        # Get error type from exit code
+        error_type = ExitCode(self.exit_code).name
+
+        # Start with error type and message
+        lines = [f"[{error_type}] {self.message}"]
+
+        # Add details if present
+        if details := self.context.get("details"):
+            lines.append(f"Details: {details}")
+
+        # Add source and path information
+        if source := self.source:
+            lines.append(f"Source: {source}")
+        if path := self.context.get("path"):
+            lines.append(f"Path: {path}")
+
+        # Add any expanded path information
+        if original_path := self.context.get("original_path"):
+            lines.append(f"Original Path: {original_path}")
+        if expanded_path := self.context.get("expanded_path"):
+            lines.append(f"Expanded Path: {expanded_path}")
+        if base_dir := self.context.get("base_dir"):
+            lines.append(f"Base Directory: {base_dir}")
+        if allowed_dirs := self.context.get("allowed_dirs"):
+            if isinstance(allowed_dirs, list):
+                lines.append(f"Allowed Directories: {allowed_dirs}")
+            else:
+                lines.append(f"Allowed Directory: {allowed_dirs}")
+
+        # Add other context fields (excluding reserved ones)
+        reserved_keys = {
+            "source",
+            "details",
+            "schema_path",
+            "timestamp",
+            "host",
+            "version",
+            "python_version",
+            "troubleshooting",
+            "path",
+            "original_path",
+            "expanded_path",
+            "base_dir",
+            "allowed_dirs",
+        }
+        context_lines = []
+        for k, v in sorted(self.context.items()):
+            if k not in reserved_keys and v is not None:
+                # Convert key to title case and replace underscores with spaces
+                formatted_key = k.replace("_", " ").title()
+                context_lines.append(f"{formatted_key}: {v}")
+
+        if context_lines:
+            lines.extend(["", "Additional Information:"])
+            lines.extend(context_lines)
+
+        # Add troubleshooting tips if available
+        if tips := self.context.get("troubleshooting"):
+            lines.extend(["", "Troubleshooting:"])
+            if isinstance(tips, list):
+                lines.extend(f"  {i+1}. {tip}" for i, tip in enumerate(tips))
+            else:
+                lines.append(f"  1. {tips}")
+
+        return "\n".join(lines)
+
+
+class OstructFileNotFoundError(CLIError):
+    """Raised when a file is not found.
+
+    This is Ostruct's custom error for file not found scenarios, distinct from Python's built-in
+    FileNotFoundError. It provides additional context and troubleshooting information specific to
+    the CLI context.
+    """
+
+    def __init__(self, path: str, context: Optional[Dict[str, Any]] = None):
+        context = context or {}
+        context.update(
+            {
+                "details": "The specified file does not exist or cannot be accessed",
+                "path": path,
+                "troubleshooting": [
+                    "Check if the file exists",
+                    "Verify the path spelling is correct",
+                    "Check file permissions",
+                    "Ensure parent directories exist",
+                ],
+            }
+        )
+        super().__init__(
+            f"File not found: {path}",
+            exit_code=ExitCode.FILE_ERROR,
+            context=context,
+        )