ai-pipeline-core 0.2.2__tar.gz → 0.2.3__tar.gz

{ai_pipeline_core-0.2.2 → ai_pipeline_core-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-pipeline-core
-Version: 0.2.2
+Version: 0.2.3
 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
@@ -20,12 +20,12 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: jinja2>=3.1.6
-Requires-Dist: lmnr>=0.7.13
-Requires-Dist: openai>=1.108.1
+Requires-Dist: lmnr>=0.7.17
+Requires-Dist: openai>=1.109.1
 Requires-Dist: prefect-gcp[cloud-storage]>=0.6.10
-Requires-Dist: prefect>=3.4.19
+Requires-Dist: prefect>=3.4.21
 Requires-Dist: pydantic-settings>=2.10.1
-Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pydantic>=2.11.9
 Requires-Dist: python-magic>=0.4.27
 Requires-Dist: ruamel-yaml>=0.18.14
 Requires-Dist: tiktoken>=0.11.0

{ai_pipeline_core-0.2.2 → ai_pipeline_core-0.2.3}/ai_pipeline_core/__init__.py

@@ -118,7 +118,7 @@ from .prompt_manager import PromptManager
 from .settings import Settings
 from .tracing import TraceInfo, TraceLevel, set_trace_cost, trace
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 
 __all__ = [
     # Config/Settings

{ai_pipeline_core-0.2.2 → ai_pipeline_core-0.2.3}/ai_pipeline_core/documents/document.py

@@ -302,7 +302,7 @@ class Document(BaseModel, ABC):
         name: str,
         content: bytes,
         description: str | None = None,
-        sources: list[str] = [],
+        sources: list[str] | None = None,
     ) -> Self: ...
 
     @overload
@@ -313,7 +313,7 @@ class Document(BaseModel, ABC):
         name: str,
         content: str,
         description: str | None = None,
-        sources: list[str] = [],
+        sources: list[str] | None = None,
     ) -> Self: ...
 
     @overload
@@ -324,7 +324,7 @@ class Document(BaseModel, ABC):
         name: str,
         content: dict[str, Any],
         description: str | None = None,
-        sources: list[str] = [],
+        sources: list[str] | None = None,
     ) -> Self: ...
 
     @overload
@@ -335,7 +335,7 @@ class Document(BaseModel, ABC):
         name: str,
         content: list[Any],
         description: str | None = None,
-        sources: list[str] = [],
+        sources: list[str] | None = None,
     ) -> Self: ...
 
     @overload
@@ -346,7 +346,7 @@ class Document(BaseModel, ABC):
         name: str,
         content: BaseModel,
         description: str | None = None,
-        sources: list[str] = [],
+        sources: list[str] | None = None,
     ) -> Self: ...
 
     @classmethod
@@ -356,7 +356,7 @@ class Document(BaseModel, ABC):
         name: str,
         content: str | bytes | dict[str, Any] | list[Any] | BaseModel,
         description: str | None = None,
-        sources: list[str] = [],
+        sources: list[str] | None = None,
     ) -> Self:
         r"""Create a Document with automatic content type conversion (recommended).
 
@@ -469,7 +469,7 @@ class Document(BaseModel, ABC):
         name: str,
         content: bytes,
         description: str | None = None,
-        sources: list[str] = [],
+        sources: list[str] | None = None,
     ) -> None:
         """Initialize a Document instance with raw bytes content.
 
@@ -509,7 +509,11 @@ class Document(BaseModel, ABC):
         if type(self) is Document:
             raise TypeError("Cannot instantiate abstract Document class directly")
 
-        super().__init__(name=name, content=content, description=description, sources=sources)
+        # Only pass sources if not None to let Pydantic's default_factory handle it
+        if sources is not None:
+            super().__init__(name=name, content=content, description=description, sources=sources)
+        else:
+            super().__init__(name=name, content=content, description=description)
 
     name: str
     description: str | None = None

{ai_pipeline_core-0.2.2 → ai_pipeline_core-0.2.3}/ai_pipeline_core/documents/flow_document.py

@@ -46,7 +46,7 @@ class FlowDocument(Document):
         name: str,
         content: bytes,
         description: str | None = None,
-        sources: list[str] = [],
+        sources: list[str] | None = None,
     ) -> None:
         """Initialize a FlowDocument with raw bytes content.
 
@@ -88,7 +88,12 @@ class FlowDocument(Document):
         """
         if type(self) is FlowDocument:
             raise TypeError("Cannot instantiate abstract FlowDocument class directly")
-        super().__init__(name=name, content=content, description=description, sources=sources)
+
+        # Only pass sources if not None to let Pydantic's default_factory handle it
+        if sources is not None:
+            super().__init__(name=name, content=content, description=description, sources=sources)
+        else:
+            super().__init__(name=name, content=content, description=description)
 
     @final
     def get_base_type(self) -> Literal["flow"]:

{ai_pipeline_core-0.2.2 → ai_pipeline_core-0.2.3}/ai_pipeline_core/documents/task_document.py

@@ -51,7 +51,7 @@ class TaskDocument(Document):
         name: str,
         content: bytes,
         description: str | None = None,
-        sources: list[str] = [],
+        sources: list[str] | None = None,
     ) -> None:
         """Initialize a TaskDocument with raw bytes content.
 
@@ -93,7 +93,12 @@ class TaskDocument(Document):
         """
         if type(self) is TaskDocument:
             raise TypeError("Cannot instantiate abstract TaskDocument class directly")
-        super().__init__(name=name, content=content, description=description, sources=sources)
+
+        # Only pass sources if not None to let Pydantic's default_factory handle it
+        if sources is not None:
+            super().__init__(name=name, content=content, description=description, sources=sources)
+        else:
+            super().__init__(name=name, content=content, description=description)
 
     @final
     def get_base_type(self) -> Literal["task"]:

{ai_pipeline_core-0.2.2 → ai_pipeline_core-0.2.3}/ai_pipeline_core/llm/ai_messages.py

@@ -279,8 +279,8 @@ class AIMessages(list[AIMessageType]):
         for message in self:
             if isinstance(message, Document):
                 serialized_document = message.serialize_model()
-                del serialized_document["content"]
-                messages.append(json.dumps(serialized_document, indent=2))
+                filtered_doc = {k: v for k, v in serialized_document.items() if k != "content"}
+                messages.append(json.dumps(filtered_doc, indent=2))
             elif isinstance(message, ModelResponse):
                 messages.append(message.content)
             else:

{ai_pipeline_core-0.2.2 → ai_pipeline_core-0.2.3}/ai_pipeline_core/llm/client.py

@@ -447,10 +447,11 @@ async def generate_structured(
                 Defaults to None (empty AIMessages).
         messages: Dynamic prompts/queries. AIMessages or str ONLY.
                  Do not pass Document or DocumentList directly.
-        options: DEPRECATED - DO NOT USE. Reserved for internal framework usage only.
-                Framework defaults are production-optimized. Configure model behavior
-                centrally via LiteLLM proxy settings, not per API call.
-                The response_format is set automatically from the response_format parameter.
+        options: Optional ModelOptions for configuring temperature, retries, etc.
+                If provided, it will NOT be mutated (a copy is created internally).
+                The response_format field is set automatically from the response_format parameter.
+                In most cases, leave as None to use framework defaults.
+                Configure model behavior centrally via LiteLLM proxy settings when possible.
 
     VISION/PDF MODEL COMPATIBILITY:
         When using Documents with images/PDFs in structured output:
@@ -518,6 +519,9 @@ async def generate_structured(
         context = AIMessages()
     if options is None:
         options = ModelOptions()
+    else:
+        # Create a copy to avoid mutating the caller's options object
+        options = options.model_copy()
 
     options.response_format = response_format
 

{ai_pipeline_core-0.2.2 → ai_pipeline_core-0.2.3}/ai_pipeline_core/llm/model_options.py

@@ -10,7 +10,7 @@ from pydantic import BaseModel
 
 
 class ModelOptions(BaseModel):
-    """Configuration options for LLM generation requests.
+    r"""Configuration options for LLM generation requests.
 
     ModelOptions encapsulates all configuration parameters for model
     generation, including model behavior settings, retry logic, and
@@ -62,11 +62,37 @@ class ModelOptions(BaseModel):
         max_completion_tokens: Maximum tokens to generate.
                               None uses model default.
 
+        stop: Stop sequences that halt generation when encountered.
+             Can be a single string or list of strings.
+             When the model generates any of these sequences, it stops immediately.
+             Maximum of 4 stop sequences supported by most providers.
+
         response_format: Pydantic model class for structured output.
                         Pass a Pydantic model; the client converts it to JSON Schema.
                         Set automatically by generate_structured().
                         Structured output support varies by provider and model.
 
+        verbosity: Controls output verbosity for models that support it.
+                  Literal["low", "medium", "high"] | None
+                  "low": Minimal output
+                  "medium": Standard output
+                  "high": Detailed output
+                  Note: Only some models support verbosity control.
+
+        usage_tracking: Enable token usage tracking in API responses (default: True).
+                       When enabled, adds {"usage": {"include": True}} to extra_body.
+                       Disable for providers that don't support usage tracking.
+
+        user: User identifier for cost tracking and monitoring.
+             A unique identifier representing the end-user, which can help track costs
+             and detect abuse. Maximum length is typically 256 characters.
+             Useful for multi-tenant applications or per-user billing.
+
+        extra_body: Additional provider-specific parameters to pass in request body.
+                   Dictionary of custom parameters not covered by standard options.
+                   Merged with usage_tracking if both are set.
+                   Useful for beta features or provider-specific capabilities.
+
     Example:
         >>> # Basic configuration
         >>> options = ModelOptions(
@@ -103,6 +129,24 @@ class ModelOptions(BaseModel):
         ...     reasoning_effort="high",  # Deep reasoning
         ...     timeout=600  # More time for complex reasoning
         ... )
+        >>>
+        >>> # With stop sequences
+        >>> options = ModelOptions(
+        ...     stop=["STOP", "END", "\n\n"],  # Stop on these sequences
+        ...     temperature=0.7
+        ... )
+        >>>
+        >>> # With custom extra_body parameters
+        >>> options = ModelOptions(
+        ...     extra_body={"custom_param": "value", "beta_feature": True},
+        ...     usage_tracking=True  # Still tracks usage alongside custom params
+        ... )
+        >>>
+        >>> # With user tracking for cost monitoring
+        >>> options = ModelOptions(
+        ...     user="user_12345",  # Track costs per user
+        ...     temperature=0.7
+        ... )
 
     Note:
         - Not all options apply to all models
@@ -110,6 +154,10 @@ class ModelOptions(BaseModel):
         - reasoning_effort only works with models that support explicit reasoning
         - response_format is set internally by generate_structured()
         - cache_ttl accepts formats like "120s", "5m" (default), "1h" or None to disable caching
+        - stop sequences are limited to 4 by most providers
+        - user identifier helps track costs per end-user (max 256 chars)
+        - extra_body allows passing provider-specific parameters
+        - usage_tracking is enabled by default for cost monitoring
     """
 
     temperature: float | None = None
@@ -122,9 +170,12 @@ class ModelOptions(BaseModel):
     cache_ttl: str | None = "5m"
     service_tier: Literal["auto", "default", "flex", "scale", "priority"] | None = None
     max_completion_tokens: int | None = None
+    stop: str | list[str] | None = None
     response_format: type[BaseModel] | None = None
     verbosity: Literal["low", "medium", "high"] | None = None
     usage_tracking: bool = True
+    user: str | None = None
+    extra_body: dict[str, Any] | None = None
 
     def to_openai_completion_kwargs(self) -> dict[str, Any]:
         """Convert options to OpenAI API completion parameters.
@@ -142,10 +193,14 @@ class ModelOptions(BaseModel):
         API parameter mapping:
             - temperature -> temperature
             - max_completion_tokens -> max_completion_tokens
+            - stop -> stop (string or list of strings)
             - reasoning_effort -> reasoning_effort
             - search_context_size -> web_search_options.search_context_size
             - response_format -> response_format
             - service_tier -> service_tier
+            - verbosity -> verbosity
+            - user -> user (for cost tracking)
+            - extra_body -> extra_body (merged with usage tracking)
 
         Web Search Structure:
             When search_context_size is set, creates:
@@ -168,12 +223,18 @@ class ModelOptions(BaseModel):
             "extra_body": {},
         }
 
+        if self.extra_body:
+            kwargs["extra_body"] = self.extra_body
+
         if self.temperature:
             kwargs["temperature"] = self.temperature
 
         if self.max_completion_tokens:
             kwargs["max_completion_tokens"] = self.max_completion_tokens
 
+        if self.stop:
+            kwargs["stop"] = self.stop
+
         if self.reasoning_effort:
             kwargs["reasoning_effort"] = self.reasoning_effort
 
@@ -189,6 +250,9 @@ class ModelOptions(BaseModel):
         if self.verbosity:
             kwargs["verbosity"] = self.verbosity
 
+        if self.user:
+            kwargs["user"] = self.user
+
         if self.usage_tracking:
             kwargs["extra_body"]["usage"] = {"include": True}
 

{ai_pipeline_core-0.2.2 → ai_pipeline_core-0.2.3}/ai_pipeline_core/tracing.py

@@ -15,7 +15,7 @@ from functools import wraps
 from typing import Any, Callable, Literal, ParamSpec, TypeVar, cast, overload
 
 from lmnr import Attributes, Instruments, Laminar, observe
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 # Import for document trimming - needed for isinstance checks
 # These are lazy imports only used when trim_documents is enabled
@@ -226,8 +226,8 @@ class TraceInfo(BaseModel):
 
     session_id: str | None = None
     user_id: str | None = None
-    metadata: dict[str, str] = {}
-    tags: list[str] = []
+    metadata: dict[str, str] = Field(default_factory=dict)
+    tags: list[str] = Field(default_factory=list)
 
     def get_observe_kwargs(self) -> dict[str, Any]:
         """Convert TraceInfo to kwargs for Laminar's observe decorator.
@@ -502,11 +502,10 @@ def trace(
         observe_name = name or f.__name__
         _observe = observe
 
-        # Store the new parameters
         _session_id = session_id
         _user_id = user_id
-        _metadata = metadata or {}
-        _tags = tags or []
+        _metadata = metadata if metadata is not None else {}
+        _tags = tags if tags is not None else []
         _span_type = span_type
         _ignore_input = ignore_input
         _ignore_output = ignore_output

{ai_pipeline_core-0.2.2 → ai_pipeline_core-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ai-pipeline-core"
-version = "0.2.2"
+version = "0.2.3"
 description = "Core utilities for AI-powered processing pipelines using prefect"
 readme = "README.md"
 license = {text = "MIT"}
@@ -22,12 +22,12 @@ classifiers = [
 dependencies = [
     "httpx>=0.28.1",
     "Jinja2>=3.1.6",
-    "lmnr>=0.7.13",
-    "openai>=1.108.1",
-    "prefect>=3.4.19",
+    "lmnr>=0.7.17",
+    "openai>=1.109.1",
+    "prefect>=3.4.21",
     "prefect-gcp[cloud_storage]>=0.6.10",
     "pydantic-settings>=2.10.1",
-    "pydantic>=2.11.7",
+    "pydantic>=2.11.9",
     "python-magic>=0.4.27",
     "ruamel.yaml>=0.18.14",
     "tiktoken>=0.11.0",
@@ -177,7 +177,7 @@ reportIncompatibleVariableOverride = "error"
 reportMissingParameterType = "warning"
 
 [tool.bumpversion]
-current_version = "0.2.2"
+current_version = "0.2.3"
 commit = true
 tag = true
 tag_name = "v{new_version}"