ai-pipeline-core 0.2.2__py3-none-any.whl → 0.2.4__py3-none-any.whl

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.4"
 
 __all__ = [
     # Config/Settings

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/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/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/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/llm/client.py

@@ -187,7 +187,7 @@ async def _generate_with_retry(
         **options.to_openai_completion_kwargs(),
     }
 
-    if context:
+    if context and options.cache_ttl:
         completion_kwargs["prompt_cache_key"] = context.get_prompt_cache_key(options.system_prompt)
 
     for attempt in range(options.retries):
@@ -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/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/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.dist-info → ai_pipeline_core-0.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-pipeline-core
-Version: 0.2.2
+Version: 0.2.4
 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.dist-info → ai_pipeline_core-0.2.4.dist-info}/RECORD

@@ -1,26 +1,26 @@
-ai_pipeline_core/__init__.py,sha256=LH0lGm02zWS9l7b3uzvvzOfSh7eDPok7RjVTP2_-Mv0,5720
+ai_pipeline_core/__init__.py,sha256=PFhuubQ9Tw2CIRMxMpX0JLkK9CWIjIzMe9aIttzFE5k,5720
 ai_pipeline_core/exceptions.py,sha256=vx-XLTw2fJSPs-vwtXVYtqoQUcOc0JeI7UmHqRqQYWU,1569
 ai_pipeline_core/pipeline.py,sha256=_00Qctqd7QibyXaetZv6KfyWoW9KZIRdndkYItNHWWI,28921
 ai_pipeline_core/prefect.py,sha256=91ZgLJHsDsRUW77CpNmkKxYs3RCJuucPM3pjKmNBeDg,2199
 ai_pipeline_core/prompt_manager.py,sha256=FAtb1yK7bGuAeuIJ523LOX9bd7TrcHG-TqZ7Lz4RJC0,12087
 ai_pipeline_core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ai_pipeline_core/settings.py,sha256=-a9jVGg77xifj2SagCR9shXfzXUd-2MlrlquEu4htG8,5035
-ai_pipeline_core/tracing.py,sha256=9RaJaAX5Vp2C8t73TaY-a9gpVy6a_VtSY0JPohIoQsc,31460
+ai_pipeline_core/tracing.py,sha256=mmK64s1lw18EE_7PQgfZb0sJhAuhkVDxXw_wBpR7UGE,31530
 ai_pipeline_core/documents/__init__.py,sha256=WHStvGZiSyybOcMTYxSV24U6MA3Am_0_Az5p-DuMFrk,738
-ai_pipeline_core/documents/document.py,sha256=L3S_bfOiViMZLYRcmbV4-s3qO8HoGmqJ5g3bXNVs_3Q,67082
+ai_pipeline_core/documents/document.py,sha256=LVUJXr3TyFHQZalWNuoHzFpoVAch3AEZoKxyh27qVAY,67361
 ai_pipeline_core/documents/document_list.py,sha256=Y_NCjfM_CjkIwHRD2iyGgYBuIykN8lT2IIH_uWOiGis,16254
-ai_pipeline_core/documents/flow_document.py,sha256=g9wlRJRJgy4RsrrZ_P5Qu6kj0FuUFfhfUsRFgtq4NIM,3918
+ai_pipeline_core/documents/flow_document.py,sha256=vSPzE4kGuDjGUfFykfpPaSfMuIO9_kDfTvdc8kZaE8U,4144
 ai_pipeline_core/documents/mime_type.py,sha256=DkW88K95el5nAmhC00XLS0G3WpDXgs5IRsBWbKiqG3Y,7995
-ai_pipeline_core/documents/task_document.py,sha256=40tFavBLX3FhK9-CRsuOH-3gUZ0zvEkqv9XcMFr8ySk,4077
+ai_pipeline_core/documents/task_document.py,sha256=4j94N-hkqXVmzjyUjbA9YW2oR4dqnOhqA3D5OWrmGkw,4303
 ai_pipeline_core/documents/temporary_document.py,sha256=Sam344Mm5AlZTm3_l01YdDWeF26F6pR2tytGRL1doQY,2711
 ai_pipeline_core/documents/utils.py,sha256=ZyJNjFN7ihWno0K7dJZed7twYmmPLA0z40UzFw1A3A8,5465
 ai_pipeline_core/flow/__init__.py,sha256=2BfWYMOPYW5teGzwo-qzpn_bom1lxxry0bPsjVgcsCk,188
 ai_pipeline_core/flow/config.py,sha256=3PCDph2n8dj-txqAvd9Wflbi_6lmfXFR9rUhM-szGSQ,18887
 ai_pipeline_core/flow/options.py,sha256=2rKR2GifhXcyw8avI_oiEDMLC2jm5Qzpw8z56pbxUMo,2285
 ai_pipeline_core/llm/__init__.py,sha256=3B_vtEzxrzidP1qOUNQ4RxlUmxZ2MBKQcUhQiTybM9g,661
-ai_pipeline_core/llm/ai_messages.py,sha256=ML4rSCCEEu9_83Mnfn7r4yx0pUkarvnBsrxRZbO4ulw,13126
-ai_pipeline_core/llm/client.py,sha256=oByE8whI1lvyqYUh6q3tKgXJhDiWiJWGztlfoZswrFE,22776
-ai_pipeline_core/llm/model_options.py,sha256=7J9qt7P1qCnSP_NrBzPwx_P-HwkXDYFxKcYzriIJ3U4,7972
+ai_pipeline_core/llm/ai_messages.py,sha256=dNhVsVVe_tL8IcSficsyEycW6Ibp3ICFMKj8Syb_h-U,13164
+ai_pipeline_core/llm/client.py,sha256=QWpAKYBCkh_7Ui8XrEHW70TtXfLvbTQFocXnB8zQGOE,23010
+ai_pipeline_core/llm/model_options.py,sha256=cfgxCqhaYwxPt_mwACslsFt3XBSEufUkICU7x1Q5ZzQ,10905
 ai_pipeline_core/llm/model_response.py,sha256=iNSKobR3gzZ-CSC8hz8-grgL7jdd2IcnCSX0exdlg7o,15345
 ai_pipeline_core/llm/model_types.py,sha256=2J4Qsb1x21I4eo_VPeaMMOW8shOGPqzJuoGjTLcBFPM,2791
 ai_pipeline_core/logging/__init__.py,sha256=Nz6-ghAoENsgNmLD2ma9TW9M0U2_QfxuQ5DDW6Vt6M0,651
@@ -32,7 +32,7 @@ ai_pipeline_core/simple_runner/cli.py,sha256=yVyuxLY2RZvdNwmwT5LCe-km2nQJzWTPI0v
 ai_pipeline_core/simple_runner/simple_runner.py,sha256=f6cIodYkul-Apu1d63T6kR5DZpiaCWpphUcEPp5XjFo,9102
 ai_pipeline_core/storage/__init__.py,sha256=tcIkjJ3zPBLCyetwiJDewBvS2sbRJrDlBh3gEsQm08E,184
 ai_pipeline_core/storage/storage.py,sha256=ClMr419Y-eU2RuOjZYd51dC0stWQk28Vb56PvQaoUwc,20007
-ai_pipeline_core-0.2.2.dist-info/METADATA,sha256=EbqjpaeIwuScRMLTKdfYdut57O8GMUZ-HWYcioQ9r1A,15159
-ai_pipeline_core-0.2.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-ai_pipeline_core-0.2.2.dist-info/licenses/LICENSE,sha256=kKj8mfbdWwkyG3U6n7ztB3bAZlEwShTkAsvaY657i3I,1074
-ai_pipeline_core-0.2.2.dist-info/RECORD,,
+ai_pipeline_core-0.2.4.dist-info/METADATA,sha256=ltt-6FE3huvKnVDWt-LA2oh2tRcaRHTdU_xI9kloqQw,15159
+ai_pipeline_core-0.2.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+ai_pipeline_core-0.2.4.dist-info/licenses/LICENSE,sha256=kKj8mfbdWwkyG3U6n7ztB3bAZlEwShTkAsvaY657i3I,1074
+ai_pipeline_core-0.2.4.dist-info/RECORD,,