ai-pipeline-core 0.1.7__py3-none-any.whl → 0.1.10__py3-none-any.whl

ai_pipeline_core/prompt_manager.py

@@ -5,7 +5,7 @@ import jinja2
 
 from ai_pipeline_core.logging import get_pipeline_logger
 
-from .exceptions import PromptNotFoundError, PromptRenderError
+from .exceptions import PromptError, PromptNotFoundError, PromptRenderError
 
 logger = get_pipeline_logger(__name__)
 
@@ -28,6 +28,12 @@ class PromptManager:
 
         # Start from the directory containing the calling file
         current_path = Path(current_dir).resolve()
+        if not current_path.exists():
+            raise PromptError(
+                f"PromptManager expected __file__ (a valid file path), "
+                f"but got {current_dir!r}. Did you pass __name__ instead?"
+            )
+
         if current_path.is_file():
             current_path = current_path.parent
 

ai_pipeline_core/simple_runner/cli.py

@@ -1,15 +1,21 @@
 from __future__ import annotations
 
 import asyncio
+import os
+import sys
+from contextlib import ExitStack
 from pathlib import Path
 from typing import Callable, Type, TypeVar, cast
 
 from lmnr import Laminar
+from pydantic import ValidationError
 from pydantic_settings import CliPositionalArg, SettingsConfigDict
 
 from ai_pipeline_core.documents import DocumentList
 from ai_pipeline_core.flow.options import FlowOptions
 from ai_pipeline_core.logging import get_pipeline_logger, setup_logging
+from ai_pipeline_core.prefect import disable_run_logger, prefect_test_harness
+from ai_pipeline_core.settings import settings
 
 from .simple_runner import ConfigSequence, FlowSequence, run_pipelines, save_documents_to_directory
 
@@ -28,12 +34,18 @@ def _initialize_environment() -> None:
         logger.warning(f"Failed to initialize LMNR tracing: {e}")
 
 
+def _running_under_pytest() -> bool:  # NEW
+    """Return True when invoked by pytest (so fixtures will supply test contexts)."""
+    return "PYTEST_CURRENT_TEST" in os.environ or "pytest" in sys.modules
+
+
 def run_cli(
     *,
     flows: FlowSequence,
     flow_configs: ConfigSequence,
     options_cls: Type[TOptions],
     initializer: InitializerFunc = None,
+    trace_name: str | None = None,
 ) -> None:
     """
     Parse CLI+env into options, then run the pipeline.
@@ -43,13 +55,20 @@ def run_cli(
     - --start/--end: optional, 1-based step bounds
     - all other flags come from options_cls (fields & Field descriptions)
     """
+    # Check if no arguments provided before initialization
+    if len(sys.argv) == 1:
+        # Add --help to show usage
+        sys.argv.append("--help")
+
     _initialize_environment()
 
     class _RunnerOptions(  # type: ignore[reportRedeclaration]
         options_cls,
         cli_parse_args=True,
         cli_kebab_case=True,
-        cli_exit_on_error=False,
+        cli_exit_on_error=True,  # Let it exit normally on error
+        cli_prog_name="ai-pipeline",
+        cli_use_class_docs_for_groups=True,
     ):
         working_directory: CliPositionalArg[Path]
         project_name: str | None = None
@@ -58,7 +77,49 @@ def run_cli(
 
         model_config = SettingsConfigDict(frozen=True, extra="ignore")
 
-    opts = cast(FlowOptions, _RunnerOptions())  # type: ignore[reportCallIssue]
+    try:
+        opts = cast(FlowOptions, _RunnerOptions())  # type: ignore[reportCallIssue]
+    except ValidationError as e:
+        print("\nError: Invalid command line arguments\n", file=sys.stderr)
+        for error in e.errors():
+            field = " -> ".join(str(loc) for loc in error["loc"])
+            msg = error["msg"]
+            value = error.get("input", "")
+
+            # Format the field name nicely (convert from snake_case to kebab-case for CLI)
+            cli_field = field.replace("_", "-")
+
+            print(f"  --{cli_field}: {msg}", file=sys.stderr)
+            if value:
+                print(f"    Provided value: '{value}'", file=sys.stderr)
+
+            # Add helpful hints for common errors
+            if error["type"] == "float_parsing":
+                print("    Hint: Please provide a valid number (e.g., 0.7)", file=sys.stderr)
+            elif error["type"] == "int_parsing":
+                print("    Hint: Please provide a valid integer (e.g., 10)", file=sys.stderr)
+            elif error["type"] == "literal_error":
+                ctx = error.get("ctx", {})
+                expected = ctx.get("expected", "valid options")
+                print(f"    Hint: Valid options are: {expected}", file=sys.stderr)
+            elif error["type"] in [
+                "less_than_equal",
+                "greater_than_equal",
+                "less_than",
+                "greater_than",
+            ]:
+                ctx = error.get("ctx", {})
+                if "le" in ctx:
+                    print(f"    Hint: Value must be ≤ {ctx['le']}", file=sys.stderr)
+                elif "ge" in ctx:
+                    print(f"    Hint: Value must be ≥ {ctx['ge']}", file=sys.stderr)
+                elif "lt" in ctx:
+                    print(f"    Hint: Value must be < {ctx['lt']}", file=sys.stderr)
+                elif "gt" in ctx:
+                    print(f"    Hint: Value must be > {ctx['gt']}", file=sys.stderr)
+
+        print("\nRun with --help to see all available options\n", file=sys.stderr)
+        sys.exit(1)
 
     wd: Path = cast(Path, getattr(opts, "working_directory"))
     wd.mkdir(parents=True, exist_ok=True)
@@ -82,14 +143,28 @@ def run_cli(
         if getattr(opts, "start", 1) == 1 and initial_documents:
             save_documents_to_directory(wd, initial_documents)
 
-    asyncio.run(
-        run_pipelines(
-            project_name=project_name,
-            output_dir=wd,
-            flows=flows,
-            flow_configs=flow_configs,
-            flow_options=opts,
-            start_step=getattr(opts, "start", 1),
-            end_step=getattr(opts, "end", None),
+    # Setup context stack with optional test harness and tracing
+
+    with ExitStack() as stack:
+        if trace_name:
+            stack.enter_context(
+                Laminar.start_as_current_span(
+                    name=f"{trace_name}-{project_name}", input=[opts.model_dump_json()]
+                )
+            )
+
+        if not settings.prefect_api_key and not _running_under_pytest():
+            stack.enter_context(prefect_test_harness())
+            stack.enter_context(disable_run_logger())
+
+        asyncio.run(
+            run_pipelines(
+                project_name=project_name,
+                output_dir=wd,
+                flows=flows,
+                flow_configs=flow_configs,
+                flow_options=opts,
+                start_step=getattr(opts, "start", 1),
+                end_step=getattr(opts, "end", None),
+            )
         )
-    )

ai_pipeline_core/simple_runner/simple_runner.py

@@ -77,7 +77,9 @@ async def run_pipeline(
 ) -> DocumentList:
     """Execute a single pipeline flow."""
     if flow_name is None:
-        flow_name = getattr(flow_func, "name", getattr(flow_func, "__name__", "flow"))
+        # For Prefect Flow objects, use their name attribute
+        # For regular functions, fall back to __name__
+        flow_name = getattr(flow_func, "name", None) or getattr(flow_func, "__name__", "flow")
 
     logger.info(f"Running Flow: {flow_name}")
 
@@ -126,7 +128,10 @@ async def run_pipelines(
     for i in range(start_index, end_index + 1):
         flow_func = flows[i]
         config = flow_configs[i]
-        flow_name = getattr(flow_func, "name", getattr(flow_func, "__name__", f"flow_{i + 1}"))
+        # For Prefect Flow objects, use their name attribute; for functions, use __name__
+        flow_name = getattr(flow_func, "name", None) or getattr(
+            flow_func, "__name__", f"flow_{i + 1}"
+        )
 
         logger.info(f"--- [Step {i + 1}/{num_steps}] Running Flow: {flow_name} ---")
 

{ai_pipeline_core-0.1.7.dist-info → ai_pipeline_core-0.1.10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-pipeline-core
-Version: 0.1.7
+Version: 0.1.10
 Summary: Core utilities for AI-powered processing pipelines using prefect
 Project-URL: Homepage, https://github.com/bbarwik/ai-pipeline-core
 Project-URL: Repository, https://github.com/bbarwik/ai-pipeline-core
@@ -151,7 +151,7 @@ async def process_document(doc: Document):
     return response.parsed
 ```
 
-### Enhanced Pipeline Decorators (New in v0.1.7)
+### Enhanced Pipeline Decorators
 ```python
 from ai_pipeline_core import pipeline_flow, pipeline_task
 from ai_pipeline_core.flow import FlowOptions
@@ -182,7 +182,7 @@ async def my_pipeline(
     return DocumentList(results)
 ```
 
-### Simple Runner Utility (New in v0.1.7)
+### Simple Runner Utility
 ```python
 from ai_pipeline_core.simple_runner import run_cli, run_pipeline
 from ai_pipeline_core.flow import FlowOptions
@@ -206,7 +206,7 @@ async def main():
     )
 ```
 
-### Clean Prefect Decorators (New in v0.1.7)
+### Clean Prefect Decorators
 ```python
 # Import clean Prefect decorators without tracing
 from ai_pipeline_core.prefect import flow, task
@@ -214,12 +214,12 @@ from ai_pipeline_core.prefect import flow, task
 # Or use pipeline decorators with tracing
 from ai_pipeline_core import pipeline_flow, pipeline_task
 
-@task  # Clean Prefect task
+@task  # Clean Prefect task (supports both sync and async)
 def compute(x: int) -> int:
     return x * 2
 
-@pipeline_task(trace_level="always")  # With tracing
-def compute_traced(x: int) -> int:
+@pipeline_task(trace_level="always")  # With tracing (async only)
+async def compute_traced(x: int) -> int:
     return x * 2
 ```
 
@@ -246,12 +246,12 @@ docs = DocumentList([doc1, doc2])
 Managed AI interactions with built-in retry logic, cost tracking, and structured outputs.
 
 **Supported Models** (via LiteLLM proxy):
-- OpenAI: GPT-4, GPT-5 series
-- Anthropic: Claude 3 series
-- Google: Gemini 2.5 series
-- xAI: Grok models
-- Perplexity: Sonar models (with search capabilities)
-- And many more through LiteLLM compatibility
+- OpenAI: gpt-5
+- Anthropic: claude-4
+- Google: gemini-2.5
+- xAI: grok-3, grok-4
+- Perplexity: sonar-pro-search
+- And many more through LiteLLM compatibility. Every model from openrouter should work.
 
 ```python
 from ai_pipeline_core.llm import generate_structured, AIMessages, ModelOptions
@@ -328,13 +328,13 @@ ai_pipeline_core/
 │   └── model_options.py # Configuration models
 ├── flow/              # Prefect flow utilities
 │   ├── config.py      # Type-safe flow configuration
-│   └── options.py     # FlowOptions base class (v0.1.7)
-├── simple_runner/     # Pipeline execution utilities (v0.1.7)
+│   └── options.py     # FlowOptions base class
+├── simple_runner/     # Pipeline execution utilities
 │   ├── cli.py         # CLI interface
 │   └── simple_runner.py # Core runner logic
 ├── logging/           # Structured logging
-├── pipeline.py        # Enhanced decorators (v0.1.7)
-├── prefect.py         # Clean Prefect exports (v0.1.7)
+├── pipeline.py        # Enhanced decorators
+├── prefect.py         # Clean Prefect exports
 ├── tracing.py         # Observability decorators
 └── settings.py        # Centralized configuration
 ```
@@ -345,6 +345,7 @@ ai_pipeline_core/
 ```bash
 make test           # Run all tests
 make test-cov      # Run with coverage report
+make test-showcase # Test the showcase.py CLI example
 pytest tests/test_documents.py::TestDocument::test_creation  # Single test
 ```
 
@@ -481,6 +482,22 @@ For learning purposes, see [CLAUDE.md](CLAUDE.md) for our comprehensive coding s
 
 - [CLAUDE.md](CLAUDE.md) - Detailed coding standards and architecture guide
 
+## Examples
+
+### In This Repository
+- [showcase.py](examples/showcase.py) - Complete example demonstrating all core features including the CLI runner
+  ```bash
+  # Run the showcase example with CLI
+  python examples/showcase.py ./output --temperature 0.7 --batch-size 5
+
+  # Show help
+  python examples/showcase.py --help
+  ```
+- [showcase.jinja2](examples/showcase.jinja2) - Example Jinja2 prompt template
+
+### Real-World Application
+- [AI Documentation Writer](https://github.com/bbarwik/ai-documentation-writer) - Production-ready example showing how to build sophisticated AI pipelines for automated documentation generation. See [examples/ai-documentation-writer.md](examples/ai-documentation-writer.md) for a detailed overview.
+
 ### dependencies_docs/ Directory
 > [!NOTE]
 > The `dependencies_docs/` directory contains guides for AI assistants (like Claude Code) on how to interact with the project's external dependencies and tooling, NOT user documentation for ai-pipeline-core itself. These files are excluded from repository listings to avoid confusion.
@@ -511,29 +528,9 @@ Built with:
 - [LiteLLM](https://litellm.ai/) - LLM proxy
 - [Pydantic](https://pydantic-docs.helpmanual.io/) - Data validation
 
-## What's New in v0.1.7
-
-### Major Additions
-- **Enhanced Pipeline Decorators**: New `pipeline_flow` and `pipeline_task` decorators combining Prefect functionality with automatic LMNR tracing
-- **FlowOptions Base Class**: Extensible configuration system for flows with type-safe inheritance
-- **Simple Runner Module**: CLI and programmatic utilities for easy pipeline execution
-- **Clean Prefect Exports**: Separate imports for Prefect decorators with and without tracing
-- **Expanded Exports**: All major components now accessible from top-level package import
-
-### API Improvements
-- Better type inference for document flows with custom options
-- Support for custom FlowOptions inheritance in pipeline flows
-- Improved error messages for invalid flow signatures
-- Enhanced document utility functions (`canonical_name_key`, `sanitize_url`)
-
-### Developer Experience
-- Simplified imports - most components available from `ai_pipeline_core` directly
-- Better separation of concerns between clean Prefect and traced pipeline decorators
-- More intuitive flow configuration with `FlowOptions` inheritance
-
 ## Stability Notice
 
-**Current Version**: 0.1.7
+**Current Version**: 0.1.10
 **Status**: Internal Preview
 **API Stability**: Unstable - Breaking changes expected
 **Recommended Use**: Learning and reference only

{ai_pipeline_core-0.1.7.dist-info → ai_pipeline_core-0.1.10.dist-info}/RECORD

@@ -1,25 +1,26 @@
-ai_pipeline_core/__init__.py,sha256=INcTtHr2TFY8bR0eCg7RwvIRYY6px8knCgjyIvSSKP4,1602
+ai_pipeline_core/__init__.py,sha256=qKdAEzvFaIG3FgMh-90X825rcL4vqshSM2xI_WIeiq0,1711
 ai_pipeline_core/exceptions.py,sha256=_vW0Hbw2LGb5tcVvH0YzTKMff7QOPfCRr3w-w_zPyCE,968
-ai_pipeline_core/pipeline.py,sha256=GOrPC53j756Xhpg_CShnkAKxSdkC16XHEoPeIhkjLIA,16569
+ai_pipeline_core/pipeline.py,sha256=f-pEDwrEhMLfcSEvPP2b74xb0WzFI05IQcl-NDFzH7w,16565
 ai_pipeline_core/prefect.py,sha256=VHYkkRcUmSpdwyWosOOxuExVCncIQgT6MypqGdjcYnM,241
-ai_pipeline_core/prompt_manager.py,sha256=XmNUdMIC0WrE9fF0LIcfozAKOGrlYwj8AfXvCndIH-o,4693
+ai_pipeline_core/prompt_manager.py,sha256=e6i9xOpgmyj-0FoJQg4Y4ZgnYSOUbCARU4UYNk_rT-0,4938
 ai_pipeline_core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ai_pipeline_core/settings.py,sha256=Zl2BPa6IHzh-B5V7cg5mtySr1dhWZQYYKxXz3BwrHlQ,615
 ai_pipeline_core/tracing.py,sha256=T-3fTyA37TejXxotkVzTNqL2a5nOfZ0bcHg9TClLvmg,9471
-ai_pipeline_core/documents/__init__.py,sha256=TLW8eOEmthfDHOTssXjyBlqhgrZe9ZIyxlkd0LBJ3_s,340
-ai_pipeline_core/documents/document.py,sha256=e3IBr0TThucBAaOHvdqv0X--iCcBrqh2jzFTyaOp7O0,12418
+ai_pipeline_core/documents/__init__.py,sha256=a5fdAZxlIX5j-BEcawFnBN3jwyR1nHuvy5iw5G1MwC8,415
+ai_pipeline_core/documents/document.py,sha256=3X1u78If77UqoHgl1uTiwqCc5QdQ9kbGmkL6LFoJVUM,16405
 ai_pipeline_core/documents/document_list.py,sha256=HOG_uZDazA9CJB7Lr_tNcDFzb5Ff9RUt0ELWQK_eYNM,4940
 ai_pipeline_core/documents/flow_document.py,sha256=qsV-2JYOMhkvAj7lW54ZNH_4QUclld9h06CoU59tWww,815
 ai_pipeline_core/documents/mime_type.py,sha256=sBhNRoBJQ35JoHWhJzBGpp00WFDfMdEX0JZKKkR7QH0,3371
 ai_pipeline_core/documents/task_document.py,sha256=WjHqtl1d60XFBBqewNRdz1OqBErGI0jRx15oQYCTHo8,907
+ai_pipeline_core/documents/temporary_document.py,sha256=qaJYNza9EyvgBh7uch8Oic6DDk3QL0OEXGF-zuvhK_4,358
 ai_pipeline_core/documents/utils.py,sha256=BdE4taSl1vrBhxnFbOP5nDA7lXIcvY__AMRTHoaNb5M,2764
 ai_pipeline_core/flow/__init__.py,sha256=54DRfZnjXQVrimgtKEVEm5u5ErImx31cjK2PpBvHjU4,116
-ai_pipeline_core/flow/config.py,sha256=crbe_OvNE6qulIKv1D8yKoe8xrEsIlvICyxjhqHHBxQ,2266
+ai_pipeline_core/flow/config.py,sha256=j2FP56gTNqNrxrtUnkfn-mUnIs1Cayy2ge4TzoDqj8E,3856
 ai_pipeline_core/flow/options.py,sha256=WygJEwjqOa14l23a_Hp36hJX-WgxHMq-YzSieC31Z4Y,701
 ai_pipeline_core/llm/__init__.py,sha256=3XVK-bSJdOe0s6KmmO7PDbsXHfjlcZEG1MVBmaz3EeU,442
 ai_pipeline_core/llm/ai_messages.py,sha256=DwJJe05BtYdnMZeHbBbyEbDCqrW63SRvprxptoJUCn4,4586
 ai_pipeline_core/llm/client.py,sha256=VMs1nQKCfoxbcvE2mypn5QF19u90Ua87-5IiZxWOj98,7784
-ai_pipeline_core/llm/model_options.py,sha256=TvAAlDFZN-TP9-J-RZBuU_dpSocskf6paaQMw1XY9UE,1321
+ai_pipeline_core/llm/model_options.py,sha256=7O5y-qtYtmTXzIUS7vxKOQlRAM3TTggqHw2_dOnS_a8,1441
 ai_pipeline_core/llm/model_response.py,sha256=fIWueaemgo0cMruvToMZyKsRPzKwL6IlvUJN7DLG710,5558
 ai_pipeline_core/llm/model_types.py,sha256=rIwY6voT8-xdfsKPDC0Gkdl2iTp9Q2LuvWGSRU9Mp3k,342
 ai_pipeline_core/logging/__init__.py,sha256=DOO6ckgnMVXl29Sy7q6jhO-iW96h54pCHQDzgA2Pu6I,272
@@ -27,9 +28,9 @@ ai_pipeline_core/logging/logging.yml,sha256=YTW48keO_K5bkkb-KXGM7ZuaYKiquLsjsURe
 ai_pipeline_core/logging/logging_config.py,sha256=6MBz9nnVNvqiLDoyy9-R3sWkn6927Re5hdz4hwTptpI,4903
 ai_pipeline_core/logging/logging_mixin.py,sha256=RDaR2ju2-vKTJRzXGa0DquGPT8_UxahWjvKJnaD0IV8,7810
 ai_pipeline_core/simple_runner/__init__.py,sha256=OPbTCZvqpnYdwi1Knnkj-MpmD0Nvtg5O7UwIdAKz_AY,384
-ai_pipeline_core/simple_runner/cli.py,sha256=TjiSh7lr1VnTbO1jA2DuVzC2AA6V_5sA5Z8XSuldQmc,3054
-ai_pipeline_core/simple_runner/simple_runner.py,sha256=70BHT1iz-G368H2t4tsWAVni0jw2VkWVdnKICuVtLPw,5009
-ai_pipeline_core-0.1.7.dist-info/METADATA,sha256=2Pi815TCTBlKnTp2duTaUJiKaextafqZ5yfPZdD_--o,18361
-ai_pipeline_core-0.1.7.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-ai_pipeline_core-0.1.7.dist-info/licenses/LICENSE,sha256=kKj8mfbdWwkyG3U6n7ztB3bAZlEwShTkAsvaY657i3I,1074
-ai_pipeline_core-0.1.7.dist-info/RECORD,,
+ai_pipeline_core/simple_runner/cli.py,sha256=vRB10SiBFCHD9eqjqSDNZkXYrL3oIQsxNUrHi6L7hu4,6310
+ai_pipeline_core/simple_runner/simple_runner.py,sha256=TVFFVWAt2pxIJdMqVgxXJ1wHn1Xf_-N1fSMVNQH-Hqo,5253
+ai_pipeline_core-0.1.10.dist-info/METADATA,sha256=HGRwvKh5XDGW7ufmmZ3lIwqVnZVr3eb8hLxYFCXhEbc,18010
+ai_pipeline_core-0.1.10.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+ai_pipeline_core-0.1.10.dist-info/licenses/LICENSE,sha256=kKj8mfbdWwkyG3U6n7ztB3bAZlEwShTkAsvaY657i3I,1074
+ai_pipeline_core-0.1.10.dist-info/RECORD,,