ostruct-cli 0.8.2__tar.gz → 0.8.4__tar.gz

{ostruct_cli-0.8.2 → ostruct_cli-0.8.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ostruct-cli
-Version: 0.8.2
+Version: 0.8.4
 Summary: CLI for OpenAI Structured Output with Multi-Tool Integration
 Author: Yaniv Golan
 Author-email: yaniv@golan.name
@@ -22,6 +22,7 @@ Requires-Dist: chardet (>=5.0.0,<6.0)
 Requires-Dist: click (>=8.1.7,<9.0)
 Requires-Dist: flake8 (>=6.0,<7.0) ; extra == "dev"
 Requires-Dist: flake8-pyproject (>=1.2.3,<2.0) ; extra == "dev"
+Requires-Dist: hypothesis (>=6.0.0,<7.0) ; extra == "dev"
 Requires-Dist: ijson (>=3.2.3,<4.0)
 Requires-Dist: jinja2 (>=3.1.2,<4.0)
 Requires-Dist: jsonschema (>=4.23.0,<5.0)
@@ -37,6 +38,8 @@ Requires-Dist: pygments (>=2.15.0,<3.0)
 Requires-Dist: pytest (>=8.3.4,<9.0) ; extra == "dev"
 Requires-Dist: pytest-asyncio (>=0.25.2,<1.0) ; extra == "dev"
 Requires-Dist: pytest-mock (>=3.14.0,<4.0) ; extra == "dev"
+Requires-Dist: pytest-rerunfailures (>=12.0,<13.0) ; extra == "dev"
+Requires-Dist: python-dotenv (>=1.0.1,<2.0)
 Requires-Dist: python-dotenv (>=1.0.1,<2.0) ; extra == "dev"
 Requires-Dist: pyyaml (>=6.0.2,<7.0)
 Requires-Dist: sphinx (>=7.0,<8.0) ; extra == "dev"
@@ -46,6 +49,7 @@ Requires-Dist: sphinx-rtd-theme (>=1.0,<2.0) ; extra == "docs"
 Requires-Dist: tenacity (>=8.2.3,<9.0) ; extra == "examples"
 Requires-Dist: tiktoken (==0.9.0)
 Requires-Dist: tomli (>=2.0.1,<3.0) ; (python_version < "3.11") and (extra == "docs")
+Requires-Dist: tomli (>=2.0.1,<3.0) ; extra == "dev"
 Requires-Dist: tomli (>=2.0.1,<3.0) ; python_version < "3.11"
 Requires-Dist: twine (>=6.0.1,<7.0) ; extra == "dev"
 Requires-Dist: types-cachetools (>=5.5.0.20240820) ; extra == "dev"
@@ -235,6 +239,8 @@ ostruct-cli respects the following environment variables:
 - `OSTRUCT_DISABLE_REGISTRY_UPDATE_CHECKS`: Set to "1", "true", or "yes" to disable automatic registry update checks
 - `MCP_<NAME>_URL`: Custom MCP server URLs (e.g., `MCP_STRIPE_URL=https://mcp.stripe.com`)
 
+**💡 Tip**: ostruct automatically loads `.env` files from the current directory. Environment variables take precedence over `.env` file values.
+
 <details>
 <summary><strong>Shell Completion Setup</strong> (Click to expand)</summary>
 
@@ -302,7 +308,7 @@ ostruct run analysis.j2 schema.json -fc data.csv
 ostruct run search.j2 schema.json -fs documentation.pdf
 
 # Web Search (real-time information)
-ostruct run research.j2 schema.json --web-search -V topic="latest AI developments"
+ostruct run research.j2 schema.json --enable-tool web-search -V topic="latest AI developments"
 
 # Multiple tools with one file
 ostruct run template.j2 schema.json --file-for code-interpreter shared.json --file-for file-search shared.json
@@ -370,6 +376,7 @@ tools:
   code_interpreter:
     auto_download: true
     output_directory: "./output"
+    download_strategy: "two_pass_sentinel"  # Enable reliable file downloads
 
 mcp:
   custom_server: "https://my-mcp-server.com"
@@ -384,6 +391,35 @@ Load custom configuration:
 ostruct --config my-config.yaml run template.j2 schema.json
 ```
 
+### Code Interpreter File Downloads
+
+**Important**: If you're using Code Interpreter with structured output (JSON schemas), you may need to enable the two-pass download strategy to ensure files are downloaded reliably.
+
+#### Option 1: CLI Flags (Recommended for one-off usage)
+
+```bash
+# Enable reliable file downloads for this run
+ostruct run template.j2 schema.json -fc data.csv --enable-feature ci-download-hack
+
+# Force single-pass mode (override config)
+ostruct run template.j2 schema.json -fc data.csv --disable-feature ci-download-hack
+```
+
+#### Option 2: Configuration File (Recommended for persistent settings)
+
+```yaml
+# ostruct.yaml
+tools:
+  code_interpreter:
+    download_strategy: "two_pass_sentinel"  # Enables reliable file downloads
+    auto_download: true
+    output_directory: "./downloads"
+```
+
+**Why this is needed**: OpenAI's structured output mode can prevent file download annotations from being generated. The two-pass strategy works around this by making two API calls: one to generate files (without structured output), then another to ensure schema compliance. For detailed technical information, see [docs/known-issues/2025-06-responses-ci-file-output.md](docs/known-issues/2025-06-responses-ci-file-output.md).
+
+**Performance**: The two-pass strategy approximately doubles token usage but ensures reliable file downloads when using structured output with Code Interpreter.
+
 ## Get Started Quickly
 
 🚀 **New to ostruct?** Follow our [step-by-step quickstart guide](https://ostruct.readthedocs.io/en/latest/user-guide/quickstart.html) featuring Juno the beagle for a hands-on introduction.
@@ -395,7 +431,11 @@ ostruct --config my-config.yaml run template.j2 schema.json
 1. Set your OpenAI API key:
 
 ```bash
+# Environment variable
 export OPENAI_API_KEY=your-api-key
+
+# Or create a .env file
+echo 'OPENAI_API_KEY=your-api-key' > .env
 ```
 
 ### Example 1: Basic Text Extraction (Simplest)
@@ -628,6 +668,60 @@ The registry file is stored at `~/.openai_structured/config/models.yml` and is a
 
 The update command uses HTTP conditional requests (If-Modified-Since headers) to check if the remote registry has changed before downloading, ensuring efficient updates.
 
+# Testing
+
+## Running Tests
+
+The test suite is divided into two categories:
+
+### Regular Tests (Default)
+
+```bash
+# Run all tests (skips live tests by default)
+pytest
+
+# Run specific test file
+pytest tests/test_config.py
+
+# Run with verbose output
+pytest -v
+```
+
+### Live Tests
+
+Live tests make real API calls to OpenAI and require a valid API key. They are skipped by default.
+
+```bash
+# Run only live tests (requires OPENAI_API_KEY)
+pytest -m live
+
+# Run all tests including live tests
+pytest -m "live or not live"
+
+# Run specific live test
+pytest tests/test_responses_annotations.py -m live
+```
+
+**Live tests include:**
+
+- Tests that make actual OpenAI API calls
+- Tests that run `ostruct` commands via subprocess
+- Tests that verify real API behavior and file downloads
+
+**Requirements for live tests:**
+
+- Valid `OPENAI_API_KEY` environment variable
+- Internet connection
+- May incur API costs
+
+## Test Markers
+
+- `@pytest.mark.live` - Tests that make real API calls or run actual commands
+- `@pytest.mark.no_fs` - Tests that need real filesystem (not pyfakefs)
+- `@pytest.mark.slow` - Performance/stress tests
+- `@pytest.mark.flaky` - Tests that may need reruns
+- `@pytest.mark.mock_openai` - Tests using mocked OpenAI client
+
 <!--
 MAINTAINER NOTE: After editing this README, please test GitHub rendering by:
 1. Creating a draft PR or pushing to a test branch

{ostruct_cli-0.8.2 → ostruct_cli-0.8.4}/README.md

@@ -174,6 +174,8 @@ ostruct-cli respects the following environment variables:
 - `OSTRUCT_DISABLE_REGISTRY_UPDATE_CHECKS`: Set to "1", "true", or "yes" to disable automatic registry update checks
 - `MCP_<NAME>_URL`: Custom MCP server URLs (e.g., `MCP_STRIPE_URL=https://mcp.stripe.com`)
 
+**💡 Tip**: ostruct automatically loads `.env` files from the current directory. Environment variables take precedence over `.env` file values.
+
 <details>
 <summary><strong>Shell Completion Setup</strong> (Click to expand)</summary>
 
@@ -241,7 +243,7 @@ ostruct run analysis.j2 schema.json -fc data.csv
 ostruct run search.j2 schema.json -fs documentation.pdf
 
 # Web Search (real-time information)
-ostruct run research.j2 schema.json --web-search -V topic="latest AI developments"
+ostruct run research.j2 schema.json --enable-tool web-search -V topic="latest AI developments"
 
 # Multiple tools with one file
 ostruct run template.j2 schema.json --file-for code-interpreter shared.json --file-for file-search shared.json
@@ -309,6 +311,7 @@ tools:
   code_interpreter:
     auto_download: true
     output_directory: "./output"
+    download_strategy: "two_pass_sentinel"  # Enable reliable file downloads
 
 mcp:
   custom_server: "https://my-mcp-server.com"
@@ -323,6 +326,35 @@ Load custom configuration:
 ostruct --config my-config.yaml run template.j2 schema.json
 ```
 
+### Code Interpreter File Downloads
+
+**Important**: If you're using Code Interpreter with structured output (JSON schemas), you may need to enable the two-pass download strategy to ensure files are downloaded reliably.
+
+#### Option 1: CLI Flags (Recommended for one-off usage)
+
+```bash
+# Enable reliable file downloads for this run
+ostruct run template.j2 schema.json -fc data.csv --enable-feature ci-download-hack
+
+# Force single-pass mode (override config)
+ostruct run template.j2 schema.json -fc data.csv --disable-feature ci-download-hack
+```
+
+#### Option 2: Configuration File (Recommended for persistent settings)
+
+```yaml
+# ostruct.yaml
+tools:
+  code_interpreter:
+    download_strategy: "two_pass_sentinel"  # Enables reliable file downloads
+    auto_download: true
+    output_directory: "./downloads"
+```
+
+**Why this is needed**: OpenAI's structured output mode can prevent file download annotations from being generated. The two-pass strategy works around this by making two API calls: one to generate files (without structured output), then another to ensure schema compliance. For detailed technical information, see [docs/known-issues/2025-06-responses-ci-file-output.md](docs/known-issues/2025-06-responses-ci-file-output.md).
+
+**Performance**: The two-pass strategy approximately doubles token usage but ensures reliable file downloads when using structured output with Code Interpreter.
+
 ## Get Started Quickly
 
 🚀 **New to ostruct?** Follow our [step-by-step quickstart guide](https://ostruct.readthedocs.io/en/latest/user-guide/quickstart.html) featuring Juno the beagle for a hands-on introduction.
@@ -334,7 +366,11 @@ ostruct --config my-config.yaml run template.j2 schema.json
 1. Set your OpenAI API key:
 
 ```bash
+# Environment variable
 export OPENAI_API_KEY=your-api-key
+
+# Or create a .env file
+echo 'OPENAI_API_KEY=your-api-key' > .env
 ```
 
 ### Example 1: Basic Text Extraction (Simplest)
@@ -567,6 +603,60 @@ The registry file is stored at `~/.openai_structured/config/models.yml` and is a
 
 The update command uses HTTP conditional requests (If-Modified-Since headers) to check if the remote registry has changed before downloading, ensuring efficient updates.
 
+# Testing
+
+## Running Tests
+
+The test suite is divided into two categories:
+
+### Regular Tests (Default)
+
+```bash
+# Run all tests (skips live tests by default)
+pytest
+
+# Run specific test file
+pytest tests/test_config.py
+
+# Run with verbose output
+pytest -v
+```
+
+### Live Tests
+
+Live tests make real API calls to OpenAI and require a valid API key. They are skipped by default.
+
+```bash
+# Run only live tests (requires OPENAI_API_KEY)
+pytest -m live
+
+# Run all tests including live tests
+pytest -m "live or not live"
+
+# Run specific live test
+pytest tests/test_responses_annotations.py -m live
+```
+
+**Live tests include:**
+
+- Tests that make actual OpenAI API calls
+- Tests that run `ostruct` commands via subprocess
+- Tests that verify real API behavior and file downloads
+
+**Requirements for live tests:**
+
+- Valid `OPENAI_API_KEY` environment variable
+- Internet connection
+- May incur API costs
+
+## Test Markers
+
+- `@pytest.mark.live` - Tests that make real API calls or run actual commands
+- `@pytest.mark.no_fs` - Tests that need real filesystem (not pyfakefs)
+- `@pytest.mark.slow` - Performance/stress tests
+- `@pytest.mark.flaky` - Tests that may need reruns
+- `@pytest.mark.mock_openai` - Tests using mocked OpenAI client
+
 <!--
 MAINTAINER NOTE: After editing this README, please test GitHub rendering by:
 1. Creating a draft PR or pushing to a test branch

{ostruct_cli-0.8.2 → ostruct_cli-0.8.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "ostruct-cli"
-version = "0.8.2"
+version = "0.8.4"
 description = "CLI for OpenAI Structured Output with Multi-Tool Integration"
 authors = [{name = "Yaniv Golan", email = "yaniv@golan.name"}]
 readme = "README.md"
@@ -25,6 +25,7 @@ dependencies = [
     "pygments>=2.15.0,<3.0",
     "jinja2>=3.1.2,<4.0",
     "openai-model-registry>=0.7.0,<1.0",
+    "python-dotenv>=1.0.1,<2.0",
 ]
 
 [project.scripts]
@@ -33,6 +34,7 @@ ostruct = "ostruct.cli.cli:main"
 [project.optional-dependencies]
 dev = [
     "pytest>=8.3.4,<9.0",
+    "pytest-rerunfailures>=12.0,<13.0",
     "flake8>=6.0,<7.0",
     "flake8-pyproject>=1.2.3,<2.0",
     "black==24.8.0",
@@ -54,6 +56,8 @@ dev = [
     "types-requests>=2.32.0.20241016",
     "pre-commit>=4.1.0,<5.0",
     "psutil>=7.0.0,<8.0",
+    "hypothesis>=6.0.0,<7.0",
+    "tomli>=2.0.1,<3.0",
 ]
 docs = [
     "sphinx>=7.0,<8.0",
@@ -111,12 +115,16 @@ include = ["py.typed"]
     testpaths = ["tests"]
     python_files = ["test_*.py"]
     markers = [
-        "live: mark test as a live test that should use real API key",
+        "live: mark test as a live test that makes real API calls or runs actual ostruct commands",
         "asyncio: mark test as requiring async loop",
-        "no_pyfakefs: mark test to disable pyfakefs",
-        "slow: mark test as slow performance/stress test"
+        "no_fs: mark test to disable pyfakefs and use real filesystem",
+        "slow: mark test as slow performance/stress test",
+        "flaky: mark test as flaky (may need reruns)",
+        "mock_openai: mark test to use mock OpenAI client"
     ]
     asyncio_default_fixture_loop_scope = "function"
+    # By default, skip live tests unless explicitly requested
+    addopts = "-m 'not live'"
 
     [tool.ruff]
     target-version = "py310"

{ostruct_cli-0.8.2 → ostruct_cli-0.8.4}/src/ostruct/cli/cli.py

@@ -4,6 +4,7 @@ import sys
 from typing import Optional
 
 import click
+from dotenv import load_dotenv
 
 from .. import __version__
 from .commands import create_command_group
@@ -107,6 +108,9 @@ def create_cli() -> click.Command:
 
 def main() -> None:
     """Main entry point for the CLI."""
+    # Load environment variables from .env file
+    load_dotenv()
+
     try:
         cli(standalone_mode=False)
     except (

{ostruct_cli-0.8.2 → ostruct_cli-0.8.4}/src/ostruct/cli/click_options.py

@@ -29,6 +29,56 @@ CommandDecorator = Callable[[F], Command]
 DecoratedCommand = Union[Command, Callable[..., Any]]
 
 
+def parse_feature_flags(
+    enabled_features: tuple[str, ...], disabled_features: tuple[str, ...]
+) -> dict[str, str]:
+    """Parse feature flags from CLI arguments.
+
+    Args:
+        enabled_features: Tuple of feature names to enable
+        disabled_features: Tuple of feature names to disable
+
+    Returns:
+        Dictionary mapping feature names to "on" or "off"
+
+    Raises:
+        click.BadParameter: If flag format is invalid or conflicts exist
+    """
+    parsed = {}
+
+    # Process enabled features
+    for feature in enabled_features:
+        feature = feature.strip()
+        if not feature:
+            raise click.BadParameter("Feature name cannot be empty")
+
+        # Validate known feature flags
+        if feature == "ci-download-hack":
+            parsed[feature] = "on"
+        else:
+            raise click.BadParameter(f"Unknown feature: {feature}")
+
+    # Process disabled features
+    for feature in disabled_features:
+        feature = feature.strip()
+        if not feature:
+            raise click.BadParameter("Feature name cannot be empty")
+
+        # Check for conflicts
+        if feature in parsed:
+            raise click.BadParameter(
+                f"Feature '{feature}' cannot be both enabled and disabled"
+            )
+
+        # Validate known feature flags
+        if feature == "ci-download-hack":
+            parsed[feature] = "off"
+        else:
+            raise click.BadParameter(f"Unknown feature: {feature}")
+
+    return parsed
+
+
 def debug_options(f: Union[Command, Callable[..., Any]]) -> Command:
     """Add debug-related CLI options."""
     # Initial conversion to Command if needed
@@ -442,12 +492,13 @@ def api_options(f: Union[Command, Callable[..., Any]]) -> Command:
         environment variable.""",
     )(cmd)
 
+    # API timeout for OpenAI calls
     cmd = click.option(
         "--timeout",
         type=click.FloatRange(1.0, None),
         default=60.0,
         show_default=True,
-        help="API timeout in seconds.",
+        help="Timeout in seconds for OpenAI API calls.",
     )(cmd)
 
     return cast(Command, cmd)
@@ -573,6 +624,31 @@ def code_interpreter_options(f: Union[Command, Callable[..., Any]]) -> Command:
         help="""Clean up uploaded files after execution to save storage quota.""",
     )(cmd)
 
+    # Feature flags for experimental features
+    cmd = click.option(
+        "--enable-feature",
+        "enabled_features",
+        multiple=True,
+        metavar="<FEATURE>",
+        help="""🔧 [EXPERIMENTAL] Enable experimental features.
+        Available features:
+        • ci-download-hack - Enable two-pass sentinel mode for reliable Code Interpreter
+          file downloads with structured output. Overrides config file setting.
+        Example: --enable-feature ci-download-hack""",
+    )(cmd)
+
+    cmd = click.option(
+        "--disable-feature",
+        "disabled_features",
+        multiple=True,
+        metavar="<FEATURE>",
+        help="""🔧 [EXPERIMENTAL] Disable experimental features.
+        Available features:
+        • ci-download-hack - Force single-pass mode for Code Interpreter downloads.
+          Overrides config file setting.
+        Example: --disable-feature ci-download-hack""",
+    )(cmd)
+
     return cast(Command, cmd)
 
 
@@ -685,13 +761,17 @@ def web_search_options(f: Union[Command, Callable[..., Any]]) -> Command:
         is_flag=True,
         help="""🌐 [WEB SEARCH] Enable OpenAI web search tool for up-to-date information.
         Allows the model to search the web for current events, recent updates, and real-time data.
-        Note: Search queries may be sent to external services via OpenAI.""",
+        Note: Search queries may be sent to external services via OpenAI.
+
+        ⚠️  DEPRECATED: Use --enable-tool web-search instead. Will be removed in v0.9.0.""",
     )(cmd)
 
     cmd = click.option(
         "--no-web-search",
         is_flag=True,
-        help="""Explicitly disable web search even if enabled by default in configuration.""",
+        help="""Explicitly disable web search even if enabled by default in configuration.
+
+        ⚠️  DEPRECATED: Use --disable-tool web-search instead. Will be removed in v0.9.0.""",
     )(cmd)
 
     cmd = click.option(
@@ -725,6 +805,35 @@ def web_search_options(f: Union[Command, Callable[..., Any]]) -> Command:
     return cast(Command, cmd)
 
 
+def tool_toggle_options(f: Union[Command, Callable[..., Any]]) -> Command:
+    """Add universal tool toggle CLI options."""
+    cmd: Any = f if isinstance(f, Command) else f
+
+    cmd = click.option(
+        "--enable-tool",
+        "enabled_tools",
+        multiple=True,
+        metavar="<TOOL>",
+        help="""🔧 [TOOL TOGGLES] Enable a tool for this run (repeatable).
+        Overrides configuration file and implicit activation.
+        Available tools: code-interpreter, file-search, web-search, mcp
+        Example: --enable-tool code-interpreter --enable-tool web-search""",
+    )(cmd)
+
+    cmd = click.option(
+        "--disable-tool",
+        "disabled_tools",
+        multiple=True,
+        metavar="<TOOL>",
+        help="""🔧 [TOOL TOGGLES] Disable a tool for this run (repeatable).
+        Overrides configuration file and implicit activation.
+        Available tools: code-interpreter, file-search, web-search, mcp
+        Example: --disable-tool web-search --disable-tool mcp""",
+    )(cmd)
+
+    return cast(Command, cmd)
+
+
 def debug_progress_options(f: Union[Command, Callable[..., Any]]) -> Command:
     """Add debugging and progress CLI options."""
     cmd: Any = f if isinstance(f, Command) else f
@@ -746,19 +855,6 @@ def debug_progress_options(f: Union[Command, Callable[..., Any]]) -> Command:
         "--verbose", is_flag=True, help="Enable verbose logging"
     )(cmd)
 
-    cmd = click.option(
-        "--debug-openai-stream",
-        is_flag=True,
-        help="Debug OpenAI streaming process",
-    )(cmd)
-
-    cmd = click.option(
-        "--timeout",
-        type=int,
-        default=3600,
-        help="Operation timeout in seconds (default: 3600 = 1 hour)",
-    )(cmd)
-
     return cast(Command, cmd)
 
 
@@ -777,6 +873,7 @@ def all_options(f: Union[Command, Callable[..., Any]]) -> Command:
     cmd = code_interpreter_options(cmd)
     cmd = file_search_options(cmd)
     cmd = web_search_options(cmd)
+    cmd = tool_toggle_options(cmd)
     cmd = debug_options(cmd)
     cmd = debug_progress_options(cmd)