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

ai_pipeline_core/llm/model_options.py

@@ -1,7 +1,5 @@
 """Configuration options for LLM generation.
 
-@public
-
 Provides the ModelOptions class for configuring model behavior,
 retry logic, and advanced features like web search and reasoning.
 """
@@ -12,9 +10,7 @@ from pydantic import BaseModel
 
 
 class ModelOptions(BaseModel):
-    """Configuration options for LLM generation requests.
-
-    @public
+    r"""Configuration options for LLM generation requests.
 
     ModelOptions encapsulates all configuration parameters for model
     generation, including model behavior settings, retry logic, and
@@ -45,9 +41,13 @@ class ModelOptions(BaseModel):
 
         retries: Number of retry attempts on failure (default: 3).
 
-        retry_delay_seconds: Seconds to wait between retries (default: 10).
+        retry_delay_seconds: Seconds to wait between retries (default: 20).
+
+        timeout: Maximum seconds to wait for response (default: 600).
 
-        timeout: Maximum seconds to wait for response (default: 300).
+        cache_ttl: Cache TTL for context messages (default: "300s").
+                   String format like "60s", "5m", or None to disable caching.
+                   Applied to the last context message for efficient token reuse.
 
         service_tier: API tier selection for performance/cost trade-offs.
                      "auto": Let API choose
@@ -62,40 +62,48 @@ 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(). Provider support varies.
-
-    Example:
-        >>> # Basic configuration
-        >>> options = ModelOptions(
-        ...     temperature=0.7,
-        ...     max_completion_tokens=1000
-        ... )
-        >>>
-        >>> # With system prompt
-        >>> options = ModelOptions(
-        ...     system_prompt="You are a helpful coding assistant",
-        ...     temperature=0.3  # Lower for code generation
-        ... )
-        >>>
-        >>> # For search-enabled models
-        >>> options = ModelOptions(
-        ...     search_context_size="high",  # Get more search results
-        ...     max_completion_tokens=2000
-        ... )
-        >>>
-        >>> # For reasoning models
-        >>> options = ModelOptions(
-        ...     reasoning_effort="high",  # Deep reasoning
-        ...     timeout=600  # More time for complex reasoning
-        ... )
-
-    Note:
-        - Not all options apply to all models
-        - search_context_size only works with search models
-        - reasoning_effort only works with models that support explicit reasoning
-        - response_format is set internally by generate_structured()
+                        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.
+
+        metadata: Custom metadata tags for tracking and observability.
+                 Dictionary of string key-value pairs for tagging requests.
+                 Useful for tracking experiments, versions, or custom attributes.
+                 Maximum of 16 key-value pairs, each key/value max 64 characters.
+                 Passed through to LMNR tracing and API provider metadata.
+
+        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.
+
+    Not all options apply to all models. search_context_size only works with search models,
+    reasoning_effort only works with models that support explicit reasoning, and
+    response_format is set internally by generate_structured(). cache_ttl accepts formats
+    like "120s", "5m", "1h" or None (default: "300s"). Stop sequences are limited to 4 by
+    most providers.
     """
 
     temperature: float | None = None
@@ -103,13 +111,21 @@ class ModelOptions(BaseModel):
     search_context_size: Literal["low", "medium", "high"] | None = None
     reasoning_effort: Literal["low", "medium", "high"] | None = None
     retries: int = 3
-    retry_delay_seconds: int = 10
-    timeout: int = 300
+    retry_delay_seconds: int = 20
+    timeout: int = 600
+    cache_ttl: str | None = "300s"
     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
-
-    def to_openai_completion_kwargs(self) -> dict[str, Any]:
+    verbosity: Literal["low", "medium", "high"] | None = None
+    stream: bool = False
+    usage_tracking: bool = True
+    user: str | None = None
+    metadata: dict[str, str] | None = None
+    extra_body: dict[str, Any] | None = None
+
+    def to_openai_completion_kwargs(self) -> dict[str, Any]:  # noqa: C901
         """Convert options to OpenAI API completion parameters.
 
         Transforms ModelOptions fields into the format expected by
@@ -125,38 +141,42 @@ 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)
+            - metadata -> metadata (for tracking/observability)
+            - extra_body -> extra_body (merged with usage tracking)
 
         Web Search Structure:
             When search_context_size is set, creates:
             {"web_search_options": {"search_context_size": "low|medium|high"}}
             Non-search models silently ignore this parameter.
 
-        Example:
-            >>> options = ModelOptions(temperature=0.5, timeout=60)
-            >>> kwargs = options.to_openai_completion_kwargs()
-            >>> kwargs
-            {'timeout': 60, 'extra_body': {}, 'temperature': 0.5}
-
-        Note:
-            - system_prompt is handled separately in _process_messages()
-            - retries and retry_delay_seconds are used by retry logic
-            - extra_body is always included for potential extensions
+        system_prompt is handled separately in _process_messages().
+        retries and retry_delay_seconds are used by retry logic.
+        extra_body always includes usage tracking for cost monitoring.
         """
         kwargs: dict[str, Any] = {
             "timeout": self.timeout,
             "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
 
@@ -169,4 +189,17 @@ class ModelOptions(BaseModel):
         if self.service_tier:
             kwargs["service_tier"] = self.service_tier
 
+        if self.verbosity:
+            kwargs["verbosity"] = self.verbosity
+
+        if self.user:
+            kwargs["user"] = self.user
+
+        if self.metadata:
+            kwargs["metadata"] = self.metadata
+
+        if self.usage_tracking:
+            kwargs["extra_body"]["usage"] = {"include": True}
+            kwargs["stream_options"] = {"include_usage": True}
+
         return kwargs