ostruct-cli 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

ostruct/cli/template_validation.py

@@ -67,7 +67,7 @@ from jinja2 import meta
 from jinja2.nodes import For, Name, Node
 
 from . import template_filters
-from .errors import TemplateValidationError
+from .errors import TaskTemplateVariableError, TemplateValidationError
 from .template_env import create_jinja_env
 from .template_schema import (
     DictProxy,
@@ -160,7 +160,8 @@ def validate_template_placeholders(
         template_context: Optional context to validate against
 
     Raises:
-        TemplateValidationError: If any placeholders are invalid
+        TaskTemplateVariableError: If any variables are undefined
+        TemplateValidationError: If template validation fails for other reasons
     """
     logger = logging.getLogger(__name__)
 
@@ -309,10 +310,15 @@ def validate_template_placeholders(
         }
 
         if missing:
-            raise TemplateValidationError(
-                f"Task template uses undefined variables: {', '.join(sorted(missing))}. "
-                f"Available variables: {', '.join(sorted(available_vars))}"
+            # Create a more user-friendly error message
+            error_msg = (
+                f"Missing required template variable(s): {', '.join(sorted(missing))}\n"
+                f"Available variables: {', '.join(sorted(available_vars))}\n"
+                "To fix this, please provide the missing variable(s) using:\n"
             )
+            for var in sorted(missing):
+                error_msg += f"  -V {var}='value'\n"
+            raise TaskTemplateVariableError(error_msg)
 
         logger.debug(
             "Before create_validation_context - available_vars type: %s, value: %s",
@@ -336,8 +342,17 @@ def validate_template_placeholders(
         try:
             env.from_string(template).render(validation_context)
         except jinja2.UndefinedError as e:
-            # Convert Jinja2 undefined errors to our own ValueError
-            raise TemplateValidationError(str(e))
+            # Convert Jinja2 undefined errors to TaskTemplateVariableError with helpful message
+            var_name = str(e).split("'")[
+                1
+            ]  # Extract variable name from error message
+            error_msg = (
+                f"Missing required template variable: {var_name}\n"
+                f"Available variables: {', '.join(sorted(available_vars))}\n"
+                "To fix this, please provide the variable using:\n"
+                f"  -V {var_name}='value'"
+            )
+            raise TaskTemplateVariableError(error_msg) from e
         except ValueError as e:
             # Convert validation errors from template_schema to TemplateValidationError
             raise TemplateValidationError(str(e))
@@ -348,10 +363,13 @@ def validate_template_placeholders(
             raise
 
     except jinja2.TemplateSyntaxError as e:
-        # Convert Jinja2 syntax errors to our own ValueError
+        # Convert Jinja2 syntax errors to TemplateValidationError
         raise TemplateValidationError(
             f"Invalid task template syntax: {str(e)}"
         )
+    except (TaskTemplateVariableError, TemplateValidationError):
+        # Re-raise these without wrapping
+        raise
     except Exception as e:
         logger.error("Unexpected error during template validation: %s", str(e))
         raise

ostruct/cli/token_utils.py

@@ -0,0 +1,43 @@
+"""Token estimation utilities."""
+
+from typing import Any, Dict, List, Union
+
+import tiktoken
+
+
+def estimate_tokens_with_encoding(
+    messages: Union[str, Dict[str, str], List[Dict[str, str]]],
+    model: str,
+    encoder: Any = None,
+) -> int:
+    """Estimate the number of tokens in a chat completion.
+
+    Args:
+        messages: Message content - can be string, single message dict, or list of messages
+        model: Model name
+        encoder: Optional tiktoken encoder for testing
+
+    Returns:
+        int: Estimated token count
+    """
+    if encoder is None:
+        # Use o200k_base for gpt-4o and o1 models
+        if model.startswith(("gpt-4o", "o1", "o3")):
+            encoder = tiktoken.get_encoding("o200k_base")
+        else:
+            encoder = tiktoken.get_encoding("cl100k_base")
+
+    if isinstance(messages, str):
+        return len(encoder.encode(messages))
+    elif isinstance(messages, dict):
+        return len(encoder.encode(str(messages.get("content", ""))))
+    else:
+        num_tokens = 0
+        for message in messages:
+            num_tokens += 4  # message overhead
+            for key, value in message.items():
+                num_tokens += len(encoder.encode(str(value)))
+                if key == "name":
+                    num_tokens -= 1  # role is omitted
+        num_tokens += 2  # reply priming
+        return num_tokens

ostruct/cli/validators.py

@@ -0,0 +1,109 @@
+"""Validators for CLI options and arguments."""
+
+import json
+from pathlib import Path
+from typing import Any, List, Optional, Tuple, Union
+
+import click
+
+from .errors import InvalidJSONError, VariableNameError
+
+
+def validate_name_path_pair(
+    ctx: click.Context,
+    param: click.Parameter,
+    value: List[Tuple[str, Union[str, Path]]],
+) -> List[Tuple[str, Union[str, Path]]]:
+    """Validate name/path pairs for files and directories.
+
+    Args:
+        ctx: Click context
+        param: Click parameter
+        value: List of (name, path) tuples
+
+    Returns:
+        List of validated (name, Path) tuples
+
+    Raises:
+        click.BadParameter: If validation fails
+    """
+    if not value:
+        return value
+
+    result: List[Tuple[str, Union[str, Path]]] = []
+    for name, path in value:
+        if not name.isidentifier():
+            raise click.BadParameter(f"Invalid variable name: {name}")
+        result.append((name, Path(path)))
+    return result
+
+
+def validate_variable(
+    ctx: click.Context, param: click.Parameter, value: Optional[List[str]]
+) -> Optional[List[Tuple[str, str]]]:
+    """Validate name=value format for simple variables.
+
+    Args:
+        ctx: Click context
+        param: Click parameter
+        value: List of "name=value" strings
+
+    Returns:
+        List of validated (name, value) tuples
+
+    Raises:
+        click.BadParameter: If validation fails
+    """
+    if not value:
+        return None
+
+    result = []
+    for var in value:
+        if "=" not in var:
+            raise click.BadParameter(
+                f"Variable must be in format name=value: {var}"
+            )
+        name, val = var.split("=", 1)
+        if not name.isidentifier():
+            raise click.BadParameter(f"Invalid variable name: {name}")
+        result.append((name, val))
+    return result
+
+
+def validate_json_variable(
+    ctx: click.Context, param: click.Parameter, value: Optional[List[str]]
+) -> Optional[List[Tuple[str, Any]]]:
+    """Validate JSON variable format.
+
+    Args:
+        ctx: Click context
+        param: Click parameter
+        value: List of "name=json_string" values
+
+    Returns:
+        List of validated (name, parsed_json) tuples
+
+    Raises:
+        click.BadParameter: If validation fails
+    """
+    if not value:
+        return None
+
+    result = []
+    for var in value:
+        if "=" not in var:
+            raise InvalidJSONError(
+                f'JSON variable must be in format name=\'{"json":"value"}\': {var}'
+            )
+        name, json_str = var.split("=", 1)
+        if not name.isidentifier():
+            raise VariableNameError(f"Invalid variable name: {name}")
+        try:
+            json_value = json.loads(json_str)
+            result.append((name, json_value))
+        except json.JSONDecodeError as e:
+            raise InvalidJSONError(
+                f"Invalid JSON value for variable {name!r}: {json_str!r}",
+                context={"variable_name": name},
+            ) from e
+    return result

{ostruct_cli-0.3.0.dist-info → ostruct_cli-0.5.0.dist-info}/METADATA

@@ -1,12 +1,11 @@
 Metadata-Version: 2.3
 Name: ostruct-cli
-Version: 0.3.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
@@ -16,10 +15,11 @@ Requires-Dist: chardet (>=5.0.0,<6.0.0)
 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-structured (>=1.0.0,<2.0.0)
+Requires-Dist: openai (>=1.0.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)
@@ -28,8 +28,8 @@ Description-Content-Type: text/markdown
 # ostruct-cli
 
 [![PyPI version](https://badge.fury.io/py/ostruct-cli.svg)](https://badge.fury.io/py/ostruct-cli)
-[![Python Versions](https://img.shields.io/pypi/pyversions/ostruct-cli.svg)](https://pypi.org/project/ostruct-cli/)
-[![Documentation Status](https://readthedocs.org/projects/ostruct-cli/badge/?version=latest)](https://ostruct-cli.readthedocs.io/en/latest/?badge=latest)
+[![Python Versions](https://img.shields.io/pypi/pyversions/ostruct-cli.svg)](https://pypi.org/project/ostruct-cli)
+[![Documentation Status](https://readthedocs.org/projects/ostruct/badge/?version=latest)](https://ostruct.readthedocs.io/en/latest/?badge=latest)
 [![CI](https://github.com/yaniv-golan/ostruct/actions/workflows/ci.yml/badge.svg)](https://github.com/yaniv-golan/ostruct/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
@@ -90,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:
@@ -111,22 +120,63 @@ 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:
 
 - `~/.ostruct/logs/ostruct.log`: General application logs
 - `~/.ostruct/logs/openai_stream.log`: OpenAI streaming operations logs
 
-For more detailed documentation and examples, visit our [documentation](https://ostruct-cli.readthedocs.io/).
+For more detailed documentation and examples, visit our [documentation](https://ostruct.readthedocs.io/).
 
 ## Development
 
@@ -173,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.5.0.dist-info/RECORD

@@ -0,0 +1,42 @@
+ostruct/__init__.py,sha256=X6zo6V7ZNMv731Wi388aTVQngD1410ExGwGx4J6lpyo,187
+ostruct/cli/__init__.py,sha256=sYHKT6o1kFy1acbXejzAvVm8Cy8U91Yf1l4DlzquHKg,409
+ostruct/cli/base_errors.py,sha256=S1cQxoiALbXKPxzgLo6XdSWpzPRb7RKz0QARmu9Zt4g,5987
+ostruct/cli/cache_manager.py,sha256=ej3KrRfkKKZ_lEp2JswjbJ5bW2ncsvna9NeJu81cqqs,5192
+ostruct/cli/cli.py,sha256=R9k4eHpREmvQJb-JLY1VRiWZJO8fJcer1QgnaDX0RrY,74011
+ostruct/cli/click_options.py,sha256=WbRJdB9sO63ChN3fnCP7XWs73DHKl0C1ervfwL11am0,11371
+ostruct/cli/errors.py,sha256=Muc4PygxON7M4bdZJ7-apztK9MrF252PXLPVNEogUv0,13322
+ostruct/cli/exit_codes.py,sha256=uNjvQeUGwU1mlUJYIDrExAn7YlwOXZo603yLAwpqIwk,338
+ostruct/cli/file_info.py,sha256=ilpT8IuckfhadLF1QQAPLXJp7p8kVpffDEEJ2erHPZU,14485
+ostruct/cli/file_list.py,sha256=jLuCd1ardoAXX8FNwPgIqEM-ixzr1xP5ZSqXo2lmrj0,11270
+ostruct/cli/file_utils.py,sha256=J3-6fbEGQ7KD_bU81pAxueHLv9XV0X7f8FSMt_0AJGQ,22537
+ostruct/cli/path_utils.py,sha256=j44q1OoLkqMErgK-qEuhuIZ1VyzqRIvNgxR1et9PoXA,4813
+ostruct/cli/progress.py,sha256=rj9nVEco5UeZORMbzd7mFJpFGJjbH9KbBFh5oTE5Anw,3415
+ostruct/cli/security/__init__.py,sha256=CQpkCgTFYlA1p6atpQeNgIKtE4LZGUKt4EbytbGKpCs,846
+ostruct/cli/security/allowed_checker.py,sha256=N5UXlpjdj5zAbKk-lRDlHiHV3KtQHtJNhtZI_qGB4zw,1638
+ostruct/cli/security/base.py,sha256=q9YUdHEj2eg5w8GEw5403E9OQKIjZbEiaWsvYFnCGLw,1359
+ostruct/cli/security/case_manager.py,sha256=I_ZJSyntLuGx5qVzze559CI-OxsaNPSibkAN8zZ7PvE,2345
+ostruct/cli/security/errors.py,sha256=VZDOGGD-jYLf6E5gCkKxrE34RJXJP_CPWGOF5jV_r4I,5230
+ostruct/cli/security/normalization.py,sha256=qevvxW3hHDtD1cVvDym8LJEQD1AKenVB-0ZvjCYjn5E,5242
+ostruct/cli/security/safe_joiner.py,sha256=PHowCeBAkfHfPqRwuO5Com0OemGuq3cHkdu2p9IYNT0,7107
+ostruct/cli/security/security_manager.py,sha256=R54CgE7eG_0VybvjXj4fNn1jB-RHMUlnJ6Yw8BOtKKc,13512
+ostruct/cli/security/symlink_resolver.py,sha256=wtZdJ_T_0FOy6B1P5ty1odEXQk9vr8BzlWeAFD4huJE,16744
+ostruct/cli/security/types.py,sha256=15yuG_T4CXyAFFFdSWLjVS7ACmDGIPXhQpZ8awcDwCQ,2991
+ostruct/cli/security/windows_paths.py,sha256=qxC2H2kLwtmQ7YePYde3UrmOJcGnsLEebDLh242sUaI,13453
+ostruct/cli/serialization.py,sha256=ec0UswDE2onwtZVUoZaMCsGv6zW_tSKdBng2qVo6Ucs,704
+ostruct/cli/template_env.py,sha256=S2ZvxuMQMicodSVqUhrw0kOzbNmlpQjSHtWlOwjXCms,1538
+ostruct/cli/template_extensions.py,sha256=tJN3HGAS2yzGI8Up6STPday8NVL0VV6UCClBrtDKYr0,1623
+ostruct/cli/template_filters.py,sha256=SjuQxlM5S283TS2El_AbrzETGnYoQeTpmA9sv5et3QI,19222
+ostruct/cli/template_io.py,sha256=yUWO-8rZnSdX97DTMSEX8fG9CP1ISsOhm2NZN3Fab9A,8821
+ostruct/cli/template_rendering.py,sha256=vp_4gvrYLd_kbQi3TYrYNniXLTeLmTaitGVBQManXvo,13342
+ostruct/cli/template_schema.py,sha256=ckH4rUZnEgfm_BHS9LnMGr8LtDxRmZ0C6UBVrSp8KTc,19604
+ostruct/cli/template_utils.py,sha256=Lf1TvonlRA835nxyevEBSPTEbKiz_momvQYM0ZoZDZU,8034
+ostruct/cli/template_validation.py,sha256=AXa2zmsws1j-0CTFlp7fMiZR43iNLnj4h467up2JdgU,12693
+ostruct/cli/token_utils.py,sha256=r4KPEO3Sec18Q6mU0aClK6XGShvusgUggXEQgEPPlaA,1369
+ostruct/cli/utils.py,sha256=1UCl4rHjBWKR5EKugvlVGHiHjO3XXmqvkgeAUSyIPDU,831
+ostruct/cli/validators.py,sha256=BYFZeebCPZObTUjO1TaAMpsD6h7ROkYAFn9C7uf1Q68,2992
+ostruct/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ostruct_cli-0.5.0.dist-info/LICENSE,sha256=QUOY6QCYVxAiH8vdrUTDqe3i9hQ5bcNczppDSVpLTjk,1068
+ostruct_cli-0.5.0.dist-info/METADATA,sha256=1SaOOVJvTKEqaheLw2MZzdwtinTgw2x_ms3xerwuCKA,6533
+ostruct_cli-0.5.0.dist-info/WHEEL,sha256=7dDg4QLnNKTvwIDR9Ac8jJaAmBC_owJrckbC0jjThyA,88
+ostruct_cli-0.5.0.dist-info/entry_points.txt,sha256=NFq9IuqHVTem0j9zKjV8C1si_zGcP1RL6Wbvt9fUDXw,48
+ostruct_cli-0.5.0.dist-info/RECORD,,

{ostruct_cli-0.3.0.dist-info → ostruct_cli-0.5.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.0.1
+Generator: poetry-core 2.1.0
 Root-Is-Purelib: true
 Tag: py3-none-any