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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ostruct-cli
-Version: 0.8.2
+Version: 0.8.3
 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,7 @@ 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) ; extra == "dev"
 Requires-Dist: pyyaml (>=6.0.2,<7.0)
 Requires-Dist: sphinx (>=7.0,<8.0) ; extra == "dev"
@@ -302,7 +304,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 +372,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 +387,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.
@@ -628,6 +660,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.3}/README.md

@@ -241,7 +241,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 +309,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 +324,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.
@@ -567,6 +597,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.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "ostruct-cli"
-version = "0.8.2"
+version = "0.8.3"
 description = "CLI for OpenAI Structured Output with Multi-Tool Integration"
 authors = [{name = "Yaniv Golan", email = "yaniv@golan.name"}]
 readme = "README.md"
@@ -33,6 +33,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 +55,7 @@ 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",
 ]
 docs = [
     "sphinx>=7.0,<8.0",
@@ -111,12 +113,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.3}/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
@@ -573,6 +623,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 +760,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 +804,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,12 +854,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,
@@ -777,6 +879,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)