ai-pipeline-core 0.1.12__py3-none-any.whl → 0.4.1__py3-none-any.whl

ai_pipeline_core/__init__.py

@@ -1,96 +1,45 @@
-"""AI Pipeline Core - Production-ready framework for building AI pipelines with LLMs.
+"""AI Pipeline Core - Production-ready framework for building AI pipelines with LLMs."""
 
-@public
+import os
+import sys
 
-AI Pipeline Core is a high-performance async framework for building type-safe AI pipelines.
-It combines document processing, LLM integration, and workflow orchestration into a unified
-system designed for production use.
+from prefect.context import refresh_global_settings_context
+from prefect.settings import get_current_settings
 
-The framework enforces best practices through strong typing (Pydantic), automatic retries,
-cost tracking, and distributed tracing. All I/O operations are async for maximum throughput.
+# Disable Prefect's built-in OpenTelemetry spans to prevent duplicates.
+# All tracing is handled by our @trace decorator and Laminar SDK.
+# Must be set before Prefect is imported by submodules below.
+os.environ.setdefault("PREFECT_CLOUD_ENABLE_ORCHESTRATION_TELEMETRY", "false")
 
-**CRITICAL IMPORT RULE**:
-    Always import from the top-level package:
-        **CORRECT**:
-        from ai_pipeline_core import llm, pipeline_flow, FlowDocument, DocumentList
-
-        **WRONG** - Never import from submodules:
-        from ai_pipeline_core.llm import generate  # NO!
-        from ai_pipeline_core.documents import FlowDocument  # NO!
-
-FRAMEWORK RULES (90% Use Cases):
-    1. Decorators: Use @trace, @pipeline_task, @pipeline_flow WITHOUT parameters
-    2. Logging: Use get_pipeline_logger(__name__) - NEVER print() or logging module
-    3. LLM calls: Use AIMessages or str. Wrap Documents in AIMessages; do not call .text yourself
-    4. Options: Omit ModelOptions unless specifically needed (defaults are optimal)
-    5. Documents: Create with just name and content - skip description
-    6. FlowConfig: OUTPUT_DOCUMENT_TYPE must differ from all INPUT_DOCUMENT_TYPES
-    7. Initialization: PromptManager and logger at module scope, not in functions
-    8. DocumentList: Use default constructor - no validation flags needed
-    9. setup_logging(): Only in application main(), never at import time
-
-Messages parameter type: AIMessages or str. Do not pass Document or DocumentList directly.
-
-Core Capabilities:
-    - **Document Processing**: Type-safe handling of text, JSON, YAML, PDFs, and images
-    - **LLM Integration**: Unified interface to any model via LiteLLM with caching
-    - **Structured Output**: Type-safe generation with Pydantic model validation
-    - **Workflow Orchestration**: Prefect-based flows and tasks with retries
-    - **Observability**: Distributed tracing via Laminar (LMNR) for debugging
-    - **Local Development**: Simple runner for testing without infrastructure
-
-Quick Start:
-    >>> from ai_pipeline_core import (
-    ...     pipeline_flow, FlowDocument, DocumentList, FlowOptions, llm, AIMessages
-    ... )
-    >>>
-    >>> class OutputDoc(FlowDocument):
-    ...     '''Analysis result document.'''
-    >>>
-    >>> @pipeline_flow
-    >>> async def analyze_flow(
-    ...     project_name: str,
-    ...     documents: DocumentList,
-    ...     flow_options: FlowOptions
-    ... ) -> DocumentList:
-    ...     # Messages accept AIMessages or str. Wrap documents: AIMessages([doc])
-    ...     response = await llm.generate(
-    ...         model="gpt-5",
-    ...         messages=AIMessages([documents[0]])
-    ...     )
-    ...     result = OutputDoc.create(
-    ...         name="analysis.txt",
-    ...         content=response.content
-    ...     )
-    ...     return DocumentList([result])
-
-Environment Variables (when using LiteLLM proxy):
-    - OPENAI_BASE_URL: LiteLLM proxy endpoint (e.g., http://localhost:4000)
-    - OPENAI_API_KEY: API key for LiteLLM proxy
-
-    Note: LiteLLM proxy uses OpenAI-compatible API format, hence the OPENAI_*
-    variable names are correct regardless of which LLM provider you're using.
-
-Optional Environment Variables:
-    - PREFECT_API_URL: Prefect server for orchestration
-    - PREFECT_API_KEY: Prefect API authentication key
-    - LMNR_PROJECT_API_KEY: Laminar (LMNR) API key for tracing
-    - LMNR_DEBUG: Set to "true" to enable debug-level traces
-    - LMNR_SESSION_ID: Default session ID for traces
-    - LMNR_USER_ID: Default user ID for traces
-"""
+# If Prefect was already imported (user imported it before us), refresh its cached settings.
+if "prefect" in sys.modules and get_current_settings().cloud.enable_orchestration_telemetry:
+    refresh_global_settings_context()
 
 from . import llm
+from .deployment import DeploymentContext, DeploymentResult, PipelineDeployment, progress
+from .deployment.remote import remote_deployment
+from .document_store import DocumentStore, SummaryGenerator, create_document_store, get_document_store, set_document_store
 from .documents import (
+    Attachment,
     Document,
-    DocumentList,
-    FlowDocument,
-    TaskDocument,
-    TemporaryDocument,
+    RunContext,
+    TaskDocumentContext,
     canonical_name_key,
+    get_run_context,
+    is_document_sha256,
+    reset_run_context,
     sanitize_url,
+    set_run_context,
+)
+from .images import (
+    ImagePart,
+    ImagePreset,
+    ImageProcessingConfig,
+    ImageProcessingError,
+    ProcessedImage,
+    process_image,
+    process_image_to_documents,
 )
-from .flow import FlowConfig, FlowOptions
 from .llm import (
     AIMessages,
     AIMessageType,
@@ -98,6 +47,8 @@ from .llm import (
     ModelOptions,
     ModelResponse,
     StructuredModelResponse,
+    generate,
+    generate_structured,
 )
 from .logging import (
     LoggerMixin,
@@ -107,53 +58,66 @@ from .logging import (
     setup_logging,
 )
 from .logging import get_pipeline_logger as get_logger
-from .pipeline import pipeline_flow, pipeline_task
-from .prefect import disable_run_logger, prefect_test_harness
+from .observability.tracing import TraceInfo, TraceLevel, set_trace_cost, trace
+from .pipeline import FlowOptions, pipeline_flow, pipeline_task
 from .prompt_manager import PromptManager
 from .settings import Settings
-from .tracing import TraceInfo, TraceLevel, trace
+from .testing import disable_run_logger, prefect_test_harness
 
-__version__ = "0.1.12"
+__version__ = "0.4.1"
 
 __all__ = [
-    # Config/Settings
-    "Settings",
-    # Logging
-    "get_logger",
-    "get_pipeline_logger",
-    "LoggerMixin",
-    "LoggingConfig",
-    "setup_logging",
-    "StructuredLoggerMixin",
-    # Documents
+    "AIMessageType",
+    "AIMessages",
+    "Attachment",
+    "DeploymentContext",
+    "DeploymentResult",
     "Document",
-    "DocumentList",
-    "FlowDocument",
-    "TaskDocument",
-    "TemporaryDocument",
-    "canonical_name_key",
-    "sanitize_url",
-    # Flow/Task
-    "FlowConfig",
+    "DocumentStore",
     "FlowOptions",
-    # Pipeline decorators (with tracing)
-    "pipeline_task",
-    "pipeline_flow",
-    # Prefect decorators (clean, no tracing)
-    "prefect_test_harness",
-    "disable_run_logger",
-    # LLM
-    "llm",
+    "ImagePart",
+    "ImagePreset",
+    "ImageProcessingConfig",
+    "ImageProcessingError",
+    "LoggerMixin",
+    "LoggingConfig",
     "ModelName",
     "ModelOptions",
     "ModelResponse",
+    "PipelineDeployment",
+    "ProcessedImage",
+    "PromptManager",
+    "RunContext",
+    "Settings",
+    "StructuredLoggerMixin",
     "StructuredModelResponse",
-    "AIMessages",
-    "AIMessageType",
-    # Tracing
-    "trace",
-    "TraceLevel",
+    "SummaryGenerator",
+    "TaskDocumentContext",
     "TraceInfo",
-    # Utils
-    "PromptManager",
+    "TraceLevel",
+    "canonical_name_key",
+    "create_document_store",
+    "disable_run_logger",
+    "generate",
+    "generate_structured",
+    "get_document_store",
+    "get_logger",
+    "get_pipeline_logger",
+    "get_run_context",
+    "is_document_sha256",
+    "llm",
+    "pipeline_flow",
+    "pipeline_task",
+    "prefect_test_harness",
+    "process_image",
+    "process_image_to_documents",
+    "progress",
+    "remote_deployment",
+    "reset_run_context",
+    "sanitize_url",
+    "set_document_store",
+    "set_run_context",
+    "set_trace_cost",
+    "setup_logging",
+    "trace",
 ]

ai_pipeline_core/deployment/__init__.py

@@ -0,0 +1,34 @@
+"""Pipeline deployment utilities for unified, type-safe deployments.
+
+This module provides the PipelineDeployment base class and related types
+for creating pipeline deployments that work seamlessly across local testing,
+CLI execution, and production Prefect deployments.
+"""
+
+from .base import DeploymentContext, DeploymentResult, PipelineDeployment
+from .contract import (
+    CompletedRun,
+    DeploymentResultData,
+    FailedRun,
+    PendingRun,
+    ProgressRun,
+    RunResponse,
+)
+from .progress import ProgressContext, flow_context, webhook_worker
+from .progress import update as progress_update
+
+__all__ = [
+    "CompletedRun",
+    "DeploymentContext",
+    "DeploymentResult",
+    "DeploymentResultData",
+    "FailedRun",
+    "PendingRun",
+    "PipelineDeployment",
+    "ProgressContext",
+    "ProgressRun",
+    "RunResponse",
+    "flow_context",
+    "progress_update",
+    "webhook_worker",
+]