spaik-sdk 0.6.3__tar.gz → 0.6.4__tar.gz

{spaik_sdk-0.6.3 → spaik_sdk-0.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spaik-sdk
-Version: 0.6.3
+Version: 0.6.4
 Summary: Python SDK for building AI agents with multi-LLM support, streaming, and production-ready infrastructure
 Project-URL: Homepage, https://github.com/siilisolutions/spaik-sdk
 Project-URL: Repository, https://github.com/siilisolutions/spaik-sdk

{spaik_sdk-0.6.3 → spaik_sdk-0.6.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spaik-sdk"
-version = "0.6.3"
+version = "0.6.4"
 description = "Python SDK for building AI agents with multi-LLM support, streaming, and production-ready infrastructure"
 readme = "README.md"
 license = "MIT"

{spaik_sdk-0.6.3 → spaik_sdk-0.6.4}/spaik_sdk/agent/base_agent.py

@@ -1,4 +1,5 @@
 import asyncio
+import uuid
 from abc import ABC
 from typing import Any, AsyncGenerator, Dict, List, Optional, Type, TypeVar
 
@@ -57,9 +58,16 @@ class BaseAgent(ABC):
         cost_provider: Optional[CostProvider] = None,
     ):
         logger.debug("Initializing BaseAgent")
+        # Generate unique instance ID for trace correlation
+        self.agent_instance_id: str = str(uuid.uuid4())
         self.prompt_loader = prompt_loader or get_prompt_loader(prompt_loader_mode)
         self.system_prompt = system_prompt or self._get_system_prompt(system_prompt_args, system_prompt_version)
-        self.trace = trace or AgentTrace(self.system_prompt, self.__class__.__name__, trace_sink=trace_sink)
+        self.trace = trace or AgentTrace(
+            self.system_prompt,
+            self.__class__.__name__,
+            trace_sink=trace_sink,
+            agent_instance_id=self.agent_instance_id,
+        )
         self.thread_container = thread_container or ThreadContainer(self.system_prompt)
         self.tools = tools or self._create_tools(tool_providers)
         self.llm_config = llm_config or self.create_llm_config(llm_model, reasoning)

{spaik_sdk-0.6.3 → spaik_sdk-0.6.4}/spaik_sdk/config/env.py

@@ -1,5 +1,6 @@
 import os
 from typing import Dict
+from typing import Optional as OptionalType
 
 from spaik_sdk.models.llm_model import LLMModel
 from spaik_sdk.models.model_registry import ModelRegistry
@@ -46,8 +47,16 @@ class EnvConfig:
     def get_prompt_loader_mode(self) -> PromptLoaderMode:
         return PromptLoaderMode.from_name(self.get_key("PROMPT_LOADER_MODE", "local"))
 
-    def get_trace_sink_mode(self) -> TraceSinkMode:
-        return TraceSinkMode.from_name(self.get_key("TRACE_SINK_MODE", "local"))
+    def get_trace_sink_mode(self) -> OptionalType[TraceSinkMode]:
+        """Get the trace sink mode from environment variable.
+
+        Returns:
+            TraceSinkMode.LOCAL if TRACE_SINK_MODE=local,
+            TraceSinkMode.NOOP if TRACE_SINK_MODE=noop,
+            None if TRACE_SINK_MODE is not set or empty (allows global/default behavior).
+        """
+        mode_str = self.get_key("TRACE_SINK_MODE", "", required=False)
+        return TraceSinkMode.from_name(mode_str)
 
     def get_credentials_provider_type(self) -> str:
         return self.get_key("CREDENTIALS_PROVIDER_TYPE", "env")

{spaik_sdk-0.6.3 → spaik_sdk-0.6.4}/spaik_sdk/models/factories/google_factory.py

@@ -22,6 +22,11 @@ class GoogleModelFactory(BaseModelFactory):
         if config.reasoning:
             model_config["thinking_budget"] = config.reasoning_budget_tokens
             model_config["include_thoughts"] = True
+        else:
+            # Gemini models have thinking enabled by default, so we must explicitly
+            # set thinking_budget=0 to disable it (omitting the parameter doesn't work)
+            model_config["thinking_budget"] = 0
+            model_config["include_thoughts"] = False
 
         # Handle streaming - Google models use disable_streaming instead of streaming
         if not config.streaming:

{spaik_sdk-0.6.3 → spaik_sdk-0.6.4}/spaik_sdk/models/factories/openai_factory.py

@@ -36,15 +36,21 @@ class OpenAIModelFactory(BaseModelFactory):
         if config.tool_usage:
             model_config["model_kwargs"] = {"parallel_tool_calls": True}
 
-        # Add model-specific configurations for reasoning models
+        # Handle reasoning configuration based on user preference (config.reasoning)
+        # and model capability (config.model.reasoning)
         if config.model.reasoning:
-            # Enable Responses API for reasoning models
+            # Model supports reasoning - check user preference
             model_config["use_responses_api"] = True
 
-            # Configure reasoning through model_kwargs as per LangChain docs
-            if config.reasoning_summary:
-                model_config["model_kwargs"] = {"reasoning": {"effort": config.reasoning_effort, "summary": config.reasoning_summary}}
+            if config.reasoning:
+                # User wants reasoning enabled - use configured effort
+                if config.reasoning_summary:
+                    model_config["model_kwargs"] = {"reasoning": {"effort": config.reasoning_effort, "summary": config.reasoning_summary}}
+            else:
+                # User wants reasoning disabled - use model's minimum effort level
+                model_config["model_kwargs"] = {"reasoning": {"effort": config.model.reasoning_min_effort}}
         else:
+            # Model doesn't support reasoning
             model_config["temperature"] = config.temperature
 
         return model_config

{spaik_sdk-0.6.3 → spaik_sdk-0.6.4}/spaik_sdk/models/llm_model.py

@@ -8,6 +8,7 @@ class LLMModel:
     family: str
     name: str
     reasoning: bool = True
+    reasoning_min_effort: str = "none"  # Minimum reasoning effort: 'none' or 'minimal'
     prompt_caching: bool = False
 
     def __str__(self) -> str:

{spaik_sdk-0.6.3 → spaik_sdk-0.6.4}/spaik_sdk/models/model_registry.py

@@ -25,9 +25,9 @@ class ModelRegistry:
     GPT_4O = LLMModel(family=LLMFamilies.OPENAI, name="gpt-4o", reasoning=False, prompt_caching=True)
     O4_MINI = LLMModel(family=LLMFamilies.OPENAI, name="o4-mini")
     O4_MINI_APRIL_2025 = LLMModel(family=LLMFamilies.OPENAI, name="o4-mini-2025-04-16")
-    GPT_5 = LLMModel(family=LLMFamilies.OPENAI, name="gpt-5", reasoning=True, prompt_caching=True)
-    GPT_5_MINI = LLMModel(family=LLMFamilies.OPENAI, name="gpt-5-mini", reasoning=True, prompt_caching=True)
-    GPT_5_NANO = LLMModel(family=LLMFamilies.OPENAI, name="gpt-5-nano", reasoning=True, prompt_caching=True)
+    GPT_5 = LLMModel(family=LLMFamilies.OPENAI, name="gpt-5", reasoning=True, reasoning_min_effort="minimal", prompt_caching=True)
+    GPT_5_MINI = LLMModel(family=LLMFamilies.OPENAI, name="gpt-5-mini", reasoning=True, reasoning_min_effort="minimal", prompt_caching=True)
+    GPT_5_NANO = LLMModel(family=LLMFamilies.OPENAI, name="gpt-5-nano", reasoning=True, reasoning_min_effort="minimal", prompt_caching=True)
     GPT_5_1 = LLMModel(family=LLMFamilies.OPENAI, name="gpt-5.1", reasoning=True, prompt_caching=True)
     GPT_5_1_CODEX = LLMModel(family=LLMFamilies.OPENAI, name="gpt-5.1-codex", reasoning=True, prompt_caching=True)
     GPT_5_1_CODEX_MINI = LLMModel(family=LLMFamilies.OPENAI, name="gpt-5.1-codex-mini", reasoning=True, prompt_caching=True)

{spaik_sdk-0.6.3 → spaik_sdk-0.6.4}/spaik_sdk/tracing/__init__.py

@@ -1,6 +1,7 @@
 from spaik_sdk.tracing.agent_trace import AgentTrace
-from spaik_sdk.tracing.get_trace_sink import get_trace_sink
+from spaik_sdk.tracing.get_trace_sink import configure_tracing, get_trace_sink
 from spaik_sdk.tracing.local_trace_sink import LocalTraceSink
+from spaik_sdk.tracing.noop_trace_sink import NoOpTraceSink
 from spaik_sdk.tracing.trace_sink import TraceSink
 from spaik_sdk.tracing.trace_sink_mode import TraceSinkMode
 
@@ -8,6 +9,8 @@ __all__ = [
     "AgentTrace",
     "TraceSink",
     "LocalTraceSink",
+    "NoOpTraceSink",
     "TraceSinkMode",
+    "configure_tracing",
     "get_trace_sink",
 ]

{spaik_sdk-0.6.3 → spaik_sdk-0.6.4}/spaik_sdk/tracing/agent_trace.py

@@ -1,5 +1,6 @@
 import json
 import time
+import uuid
 from typing import Optional, Type
 
 from pydantic import BaseModel
@@ -15,12 +16,15 @@ class AgentTrace:
         system_prompt: str,
         save_name: Optional[str] = None,
         trace_sink: Optional[TraceSink] = None,
+        agent_instance_id: Optional[str] = None,
     ):
         self.system_prompt: str = system_prompt
         self._start_time_monotonic: float = time.monotonic()
         self._steps: list[tuple[float, str]] = []
         self.save_name: Optional[str] = save_name
         self._trace_sink: TraceSink = trace_sink or get_trace_sink()
+        # Generate UUID if not provided (backward compatibility)
+        self.agent_instance_id: str = agent_instance_id or str(uuid.uuid4())
 
     def add_step(self, step_content: str) -> None:
         current_time_monotonic: float = time.monotonic()
@@ -69,4 +73,6 @@ class AgentTrace:
 
     def save(self, name: str) -> None:
         trace_content = self.to_string(include_system_prompt=False)
-        self._trace_sink.save_trace(name, trace_content, self.system_prompt)
+        self._trace_sink.save_trace(
+            name, trace_content, self.system_prompt, self.agent_instance_id
+        )

spaik_sdk-0.6.4/spaik_sdk/tracing/get_trace_sink.py

@@ -0,0 +1,77 @@
+from typing import Optional
+
+from spaik_sdk.tracing.local_trace_sink import LocalTraceSink
+from spaik_sdk.tracing.noop_trace_sink import NoOpTraceSink
+from spaik_sdk.tracing.trace_sink import TraceSink
+from spaik_sdk.tracing.trace_sink_mode import TraceSinkMode
+
+# Module-level storage for globally configured trace sink
+_global_trace_sink: Optional[TraceSink] = None
+
+
+def configure_tracing(sink: Optional[TraceSink]) -> None:
+    """Configure the global trace sink used by all agents.
+
+    Call this once at application startup to set a custom trace sink
+    that will be used by all subsequently created agents.
+
+    Resolution order:
+    1. TRACE_SINK_MODE=local env var -> LocalTraceSink (escape hatch)
+    2. TRACE_SINK_MODE=noop env var -> NoOpTraceSink
+    3. Global sink set via this function -> the configured sink
+    4. No configuration -> NoOpTraceSink (silent default)
+
+    Args:
+        sink: The TraceSink to use globally, or None to clear the global
+              configuration (reverts to default no-op behavior).
+
+    Example:
+        from spaik_sdk.tracing import configure_tracing, LocalTraceSink
+
+        # At application startup
+        configure_tracing(LocalTraceSink(traces_dir="my_traces"))
+
+        # Or with a custom sink for observability
+        configure_tracing(MyDatadogTraceSink())
+
+        # Clear global config
+        configure_tracing(None)
+    """
+    global _global_trace_sink
+    _global_trace_sink = sink
+
+
+def get_trace_sink(mode: Optional[TraceSinkMode] = None) -> TraceSink:
+    """Get the appropriate trace sink based on configuration.
+
+    Resolution order:
+    1. If mode parameter is provided, use that mode
+    2. Check TRACE_SINK_MODE env var (LOCAL or NOOP override everything)
+    3. Check for globally configured sink via configure_tracing()
+    4. Default to NoOpTraceSink (silent no-op)
+
+    Args:
+        mode: Optional explicit mode to use (overrides all other config).
+
+    Returns:
+        The appropriate TraceSink instance.
+    """
+    # Lazy import to avoid circular dependency with env.py
+    from spaik_sdk.config.env import env_config
+
+    # If explicit mode parameter provided, use it
+    if mode is None:
+        mode = env_config.get_trace_sink_mode()
+
+    # Step 1-2: Check env var mode (LOCAL or NOOP)
+    if mode == TraceSinkMode.LOCAL:
+        return LocalTraceSink()
+    if mode == TraceSinkMode.NOOP:
+        return NoOpTraceSink()
+
+    # Step 3: Check global sink
+    if _global_trace_sink is not None:
+        return _global_trace_sink
+
+    # Step 4: Default to no-op
+    return NoOpTraceSink()

{spaik_sdk-0.6.3 → spaik_sdk-0.6.4}/spaik_sdk/tracing/local_trace_sink.py

@@ -10,7 +10,14 @@ class LocalTraceSink(TraceSink):
     def __init__(self, traces_dir: Optional[str] = None):
         self.traces_dir = traces_dir or "traces"
 
-    def save_trace(self, name: str, trace_content: str, system_prompt: str) -> None:
+    def save_trace(
+        self,
+        name: str,
+        trace_content: str,
+        system_prompt: str,
+        agent_instance_id: Optional[str] = None,
+    ) -> None:
+        # agent_instance_id is accepted but intentionally ignored - file naming is unchanged
         os.makedirs(self.traces_dir, exist_ok=True)
 
         trace_path = os.path.join(self.traces_dir, f"{name}.txt")

spaik_sdk-0.6.4/spaik_sdk/tracing/noop_trace_sink.py

@@ -0,0 +1,21 @@
+from typing import Optional
+
+from spaik_sdk.tracing.trace_sink import TraceSink
+
+
+class NoOpTraceSink(TraceSink):
+    """TraceSink implementation that does nothing.
+
+    Used as the default when no tracing is configured, ensuring traces
+    are silently discarded without any side effects.
+    """
+
+    def save_trace(
+        self,
+        name: str,
+        trace_content: str,
+        system_prompt: str,
+        agent_instance_id: Optional[str] = None,
+    ) -> None:
+        """Do nothing - silently discard the trace."""
+        pass

{spaik_sdk-0.6.3 → spaik_sdk-0.6.4}/spaik_sdk/tracing/trace_sink.py

@@ -1,4 +1,5 @@
 from abc import ABC, abstractmethod
+from typing import Optional
 
 
 class TraceSink(ABC):
@@ -8,12 +9,21 @@ class TraceSink(ABC):
     """
 
     @abstractmethod
-    def save_trace(self, name: str, trace_content: str, system_prompt: str) -> None:
+    def save_trace(
+        self,
+        name: str,
+        trace_content: str,
+        system_prompt: str,
+        agent_instance_id: Optional[str] = None,
+    ) -> None:
         """Save a trace with its system prompt.
 
         Args:
             name: Identifier for the trace (e.g., agent class name)
             trace_content: The formatted trace content (without system prompt)
             system_prompt: The system prompt used for the agent
+            agent_instance_id: Optional UUID identifying the agent instance for correlation.
+                              Custom sinks can use this to correlate traces in observability
+                              backends (e.g., Datadog, OpenTelemetry).
         """
         pass

spaik_sdk-0.6.4/spaik_sdk/tracing/trace_sink_mode.py

@@ -0,0 +1,28 @@
+from enum import Enum
+from typing import Optional
+
+
+class TraceSinkMode(Enum):
+    LOCAL = "local"
+    NOOP = "noop"
+
+    @classmethod
+    def from_name(cls, name: Optional[str]) -> Optional["TraceSinkMode"]:
+        """Convert a string name to a TraceSinkMode.
+
+        Args:
+            name: The mode name ("local", "noop") or None/empty string.
+
+        Returns:
+            The corresponding TraceSinkMode, or None if name is empty/None.
+            Returns None for unrecognized values (silent fallthrough to default behavior).
+        """
+        if not name:
+            return None
+
+        for mode in cls:
+            if mode.value == name.lower():
+                return mode
+
+        # Unknown values fall through to None (let get_trace_sink handle default)
+        return None

{spaik_sdk-0.6.3 → spaik_sdk-0.6.4}/tests/unit/spaik_sdk/agent/test_base_agent.py

@@ -1,4 +1,5 @@
 import time
+import uuid
 from typing import List, Optional
 
 import pytest
@@ -275,3 +276,62 @@ class TestBaseAgent:
         # Verify cost estimation works
         cost = BuiltinCostProvider().get_cost_estimate(ModelRegistry.CLAUDE_4_SONNET, total_consumption)
         assert cost.cost > 0
+
+
+@pytest.mark.unit
+class TestBaseAgentInstanceId:
+    """Tests for BaseAgent agent_instance_id."""
+
+    def test_base_agent_has_agent_instance_id(self):
+        """BaseAgent has an agent_instance_id attribute that is a UUID."""
+        agent = ConcreteTestAgent(
+            recording_name="test_instance_id_has_id",
+            llm_model=ModelRegistry.CLAUDE_4_SONNET,
+        )
+
+        assert hasattr(agent, "agent_instance_id")
+        assert agent.agent_instance_id is not None
+        assert isinstance(agent.agent_instance_id, str)
+
+        # Should be a valid UUID format
+        parsed_uuid = uuid.UUID(agent.agent_instance_id)
+        assert str(parsed_uuid) == agent.agent_instance_id
+
+    def test_two_agents_have_different_instance_ids(self):
+        """Two BaseAgent instances have different instance IDs."""
+        agent1 = ConcreteTestAgent(
+            recording_name="test_instance_id_unique_1",
+            llm_model=ModelRegistry.CLAUDE_4_SONNET,
+        )
+        agent2 = ConcreteTestAgent(
+            recording_name="test_instance_id_unique_2",
+            llm_model=ModelRegistry.CLAUDE_4_SONNET,
+        )
+
+        assert agent1.agent_instance_id != agent2.agent_instance_id
+
+    def test_same_agent_class_different_instance_ids(self):
+        """Two agents created from same class have different instance IDs."""
+        # Create two agents of the exact same type with same parameters
+        agent1 = ConcreteTestAgent(
+            recording_name="test_same_class_different_id_1",
+            system_prompt="Same prompt",
+            llm_model=ModelRegistry.CLAUDE_4_SONNET,
+        )
+        agent2 = ConcreteTestAgent(
+            recording_name="test_same_class_different_id_2",
+            system_prompt="Same prompt",
+            llm_model=ModelRegistry.CLAUDE_4_SONNET,
+        )
+
+        assert agent1.agent_instance_id != agent2.agent_instance_id
+
+    def test_agent_instance_id_passed_to_trace(self):
+        """The agent_instance_id is passed to AgentTrace during construction."""
+        agent = ConcreteTestAgent(
+            recording_name="test_instance_id_in_trace",
+            llm_model=ModelRegistry.CLAUDE_4_SONNET,
+        )
+
+        # The agent's instance ID should match the trace's instance ID
+        assert agent.agent_instance_id == agent.trace.agent_instance_id

spaik_sdk-0.6.4/tests/unit/spaik_sdk/models/factories/test_google_factory.py

@@ -0,0 +1,144 @@
+"""Unit tests for GoogleModelFactory reasoning configuration."""
+
+import pytest
+
+from spaik_sdk.models.factories.google_factory import GoogleModelFactory
+from spaik_sdk.models.llm_config import LLMConfig
+from spaik_sdk.models.model_registry import ModelRegistry
+
+
+@pytest.mark.unit
+class TestGoogleModelFactoryReasoning:
+    """Tests for GoogleModelFactory reasoning configuration."""
+
+    @pytest.fixture
+    def factory(self):
+        return GoogleModelFactory()
+
+    @pytest.fixture
+    def gemini_model(self):
+        return ModelRegistry.GEMINI_2_5_FLASH
+
+    def test_reasoning_true_sets_thinking_budget(self, factory, gemini_model):
+        """When config.reasoning is True, thinking_budget is set to configured value."""
+        config = LLMConfig(
+            model=gemini_model,
+            reasoning=True,
+            reasoning_budget_tokens=8192,
+        )
+
+        model_config = factory.get_model_specific_config(config)
+
+        assert model_config["thinking_budget"] == 8192
+
+    def test_reasoning_true_sets_include_thoughts(self, factory, gemini_model):
+        """When config.reasoning is True, include_thoughts is set to True."""
+        config = LLMConfig(
+            model=gemini_model,
+            reasoning=True,
+        )
+
+        model_config = factory.get_model_specific_config(config)
+
+        assert model_config["include_thoughts"] is True
+
+    def test_reasoning_false_sets_thinking_budget_to_zero(self, factory, gemini_model):
+        """When config.reasoning is False, thinking_budget is explicitly set to 0."""
+        config = LLMConfig(
+            model=gemini_model,
+            reasoning=False,
+        )
+
+        model_config = factory.get_model_specific_config(config)
+
+        assert model_config["thinking_budget"] == 0
+
+    def test_reasoning_false_sets_include_thoughts_to_false(self, factory, gemini_model):
+        """When config.reasoning is False, include_thoughts is set to False."""
+        config = LLMConfig(
+            model=gemini_model,
+            reasoning=False,
+        )
+
+        model_config = factory.get_model_specific_config(config)
+
+        assert model_config["include_thoughts"] is False
+
+    @pytest.mark.parametrize(
+        "model",
+        [
+            ModelRegistry.GEMINI_2_5_FLASH,
+            ModelRegistry.GEMINI_2_5_PRO,
+            ModelRegistry.GEMINI_3_FLASH,
+            ModelRegistry.GEMINI_3_PRO,
+        ],
+    )
+    def test_reasoning_false_works_for_all_gemini_models(self, factory, model):
+        """When reasoning is False, all Gemini models get thinking_budget=0."""
+        config = LLMConfig(
+            model=model,
+            reasoning=False,
+        )
+
+        model_config = factory.get_model_specific_config(config)
+
+        assert model_config["thinking_budget"] == 0
+        assert model_config["include_thoughts"] is False
+
+    @pytest.mark.parametrize(
+        "model",
+        [
+            ModelRegistry.GEMINI_2_5_FLASH,
+            ModelRegistry.GEMINI_2_5_PRO,
+            ModelRegistry.GEMINI_3_FLASH,
+            ModelRegistry.GEMINI_3_PRO,
+        ],
+    )
+    def test_reasoning_true_works_for_all_gemini_models(self, factory, model):
+        """When reasoning is True, all Gemini models get the configured budget."""
+        budget = 4096
+        config = LLMConfig(
+            model=model,
+            reasoning=True,
+            reasoning_budget_tokens=budget,
+        )
+
+        model_config = factory.get_model_specific_config(config)
+
+        assert model_config["thinking_budget"] == budget
+        assert model_config["include_thoughts"] is True
+
+    def test_config_includes_model_name(self, factory, gemini_model):
+        """Model config always includes the model name."""
+        config_false = LLMConfig(model=gemini_model, reasoning=False)
+        config_true = LLMConfig(model=gemini_model, reasoning=True)
+
+        model_config_false = factory.get_model_specific_config(config_false)
+        model_config_true = factory.get_model_specific_config(config_true)
+
+        assert model_config_false["model"] == gemini_model.name
+        assert model_config_true["model"] == gemini_model.name
+
+    def test_config_includes_temperature(self, factory, gemini_model):
+        """Model config always includes temperature."""
+        config = LLMConfig(model=gemini_model, reasoning=False, temperature=0.7)
+
+        model_config = factory.get_model_specific_config(config)
+
+        assert model_config["temperature"] == 0.7
+
+    def test_streaming_disabled_adds_disable_streaming_flag(self, factory, gemini_model):
+        """When streaming is False, disable_streaming is set to True."""
+        config = LLMConfig(model=gemini_model, streaming=False)
+
+        model_config = factory.get_model_specific_config(config)
+
+        assert model_config["disable_streaming"] is True
+
+    def test_streaming_enabled_no_disable_streaming_flag(self, factory, gemini_model):
+        """When streaming is True, disable_streaming is not in config."""
+        config = LLMConfig(model=gemini_model, streaming=True)
+
+        model_config = factory.get_model_specific_config(config)
+
+        assert "disable_streaming" not in model_config