spaik-sdk 0.6.2__py3-none-any.whl

spaik_sdk/tools/tool_provider.py

@@ -0,0 +1,131 @@
+from abc import ABC, abstractmethod
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
+
+from langchain_core.tools import BaseTool, StructuredTool, tool
+from pydantic import BaseModel, Field, create_model
+
+
+class ToolProvider(ABC):
+    """
+    Abstract class for tool providers.
+    """
+
+    @abstractmethod
+    def get_tools(self) -> List[BaseTool]:
+        """
+        Returns a Langchain BaseTool implementation.
+
+        Returns:
+            BaseTool: A Langchain tool
+        """
+        pass
+
+    @staticmethod
+    def create_tool(
+        func: Callable[..., Any], name: str, description: str, args_schema: Optional[type[BaseModel]] = None, **kwargs
+    ) -> BaseTool:
+        """
+        Create a tool with customizable name and description.
+
+        Args:
+            func: The function to wrap as a tool
+            name: The tool name
+            description: The tool description (overrides docstring)
+            args_schema: Optional Pydantic model for argument validation
+            **kwargs: Additional arguments passed to StructuredTool.from_function
+
+        Returns:
+            BaseTool: A configured langchain tool
+
+        Example:
+            def my_func(text: str) -> str:
+                return f"Processed: {text}"
+
+            # Basic usage
+            tool = create_tool(my_func, "process", "Process text input")
+
+            # With custom schema
+            class MyArgs(BaseModel):
+                text: str = Field(description="Text to process")
+
+            tool = create_tool(my_func, "process", "Process text", MyArgs)
+        """
+        return StructuredTool.from_function(func=func, name=name, description=description, args_schema=args_schema, **kwargs)
+
+    @staticmethod
+    def create_dynamic_tool(
+        func: Callable[..., Any], name: str, description: str, args: Optional[Dict[str, Union[type, Tuple[type, str]]]] = None, **kwargs
+    ) -> BaseTool:
+        """
+        Create a tool with dynamic argument schema.
+
+        Args:
+            func: The function to wrap as a tool
+            name: The tool name
+            description: The tool description
+            args: Dict mapping arg names to types or (type, description) tuples
+            **kwargs: Additional arguments passed to StructuredTool.from_function
+
+        Returns:
+            BaseTool: A configured langchain tool
+
+        Example:
+            def search(query: str, limit: int = 10) -> str:
+                return f"Found results for {query}"
+
+            tool = create_dynamic_tool(
+                search,
+                "search_tool",
+                "Search for information",
+                args={
+                    "query": (str, "The search query"),
+                    "limit": (int, "Max results (default: 10)")
+                }
+            )
+        """
+        args_schema = None
+        if args:
+            # Build field definitions for dynamic schema
+            fields = {}
+            for arg_name, arg_spec in args.items():
+                if isinstance(arg_spec, tuple):
+                    arg_type, arg_desc = arg_spec
+                    fields[arg_name] = (arg_type, Field(description=arg_desc))
+                else:
+                    fields[arg_name] = (arg_spec, Field())
+
+            # Create dynamic Pydantic model
+            args_schema = create_model(f"{name}Args", **fields)  # type: ignore
+
+        return StructuredTool.from_function(func=func, name=name, description=description, args_schema=args_schema, **kwargs)
+
+    @staticmethod
+    def create_simple_tool(func: Callable[..., Any], name: str, description: str, **kwargs) -> BaseTool:
+        """
+        Create a simple tool without argument validation.
+
+        Args:
+            func: The function to wrap as a tool
+            name: The tool name
+            description: The tool description
+            **kwargs: Additional arguments passed to StructuredTool.from_function
+
+        Returns:
+            BaseTool: A configured langchain tool
+
+        Example:
+            def get_time() -> str:
+                import datetime
+                return datetime.datetime.now().isoformat()
+
+            tool = create_simple_tool(
+                get_time,
+                "current_time",
+                "Get current timestamp"
+            )
+        """
+        return StructuredTool.from_function(func=func, name=name, description=description, **kwargs)
+
+
+# Re-export langchain tools for convenience
+__all__ = ["ToolProvider", "BaseTool", "tool"]

spaik_sdk/tracing/__init__.py

@@ -0,0 +1,13 @@
+from spaik_sdk.tracing.agent_trace import AgentTrace
+from spaik_sdk.tracing.get_trace_sink import get_trace_sink
+from spaik_sdk.tracing.local_trace_sink import LocalTraceSink
+from spaik_sdk.tracing.trace_sink import TraceSink
+from spaik_sdk.tracing.trace_sink_mode import TraceSinkMode
+
+__all__ = [
+    "AgentTrace",
+    "TraceSink",
+    "LocalTraceSink",
+    "TraceSinkMode",
+    "get_trace_sink",
+]

spaik_sdk/tracing/agent_trace.py

@@ -0,0 +1,72 @@
+import json
+import time
+from typing import Optional, Type
+
+from pydantic import BaseModel
+
+from spaik_sdk.thread.models import MessageBlock, MessageBlockType
+from spaik_sdk.tracing.get_trace_sink import get_trace_sink
+from spaik_sdk.tracing.trace_sink import TraceSink
+
+
+class AgentTrace:
+    def __init__(
+        self,
+        system_prompt: str,
+        save_name: Optional[str] = None,
+        trace_sink: Optional[TraceSink] = 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()
+
+    def add_step(self, step_content: str) -> None:
+        current_time_monotonic: float = time.monotonic()
+        elapsed_time: float = current_time_monotonic - self._start_time_monotonic
+        self._steps.append((elapsed_time, step_content))
+        if self.save_name is not None:
+            self.save(self.save_name)
+
+    def add_structured_response_input(self, input: str, model: Type[BaseModel]) -> None:
+        self.add_step(f"📄: {input} \n {json.dumps(model.model_json_schema(), indent=2)}")
+
+    def add_structured_response_output(self, output: BaseModel) -> None:
+        self.add_step(f"```json\n{json.dumps(output.model_dump(), indent=2)}\n```")
+
+    def add_input(self, input: Optional[str] = None) -> None:
+        if input is None:
+            return
+        self.add_step(f"👤: {input}")
+
+    def add_block(self, block: MessageBlock) -> None:
+        if block.type == MessageBlockType.PLAIN:
+            self.add_step(f"🤖: {block.content}")
+        elif block.type == MessageBlockType.REASONING:
+            self.add_step(f"🧠: {block.content}")
+        elif block.type == MessageBlockType.TOOL_USE:
+            self.add_step(f"🔧: {block.tool_name} {json.dumps(block.tool_call_args, indent=2)}")
+        elif block.type == MessageBlockType.ERROR:
+            self.add_step(f"🚨: {block.content}")
+        else:
+            self.add_step(f"❓: {block.content}")
+
+    def to_string(self, include_system_prompt: bool = True) -> str:
+        lines: list[str] = []
+        if include_system_prompt:
+            lines.append("[system prompt]")
+            lines.append("")
+            lines.append(self.system_prompt)
+
+        for elapsed_seconds, content in self._steps:
+            lines.append("")
+            lines.append(f"[{elapsed_seconds:.1f}s]")
+            lines.append("")
+            lines.append(content)
+
+        return "\n".join(lines)
+
+    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)

spaik_sdk/tracing/get_trace_sink.py

@@ -0,0 +1,15 @@
+from typing import Optional
+
+from spaik_sdk.tracing.local_trace_sink import LocalTraceSink
+from spaik_sdk.tracing.trace_sink import TraceSink
+from spaik_sdk.tracing.trace_sink_mode import TraceSinkMode
+
+
+def get_trace_sink(mode: Optional[TraceSinkMode] = None) -> TraceSink:
+    # Lazy import to avoid circular dependency with env.py
+    from spaik_sdk.config.env import env_config
+
+    mode = mode or env_config.get_trace_sink_mode()
+    if mode == TraceSinkMode.LOCAL:
+        return LocalTraceSink()
+    raise ValueError(f"Unknown TraceSinkMode: {mode}")

spaik_sdk/tracing/local_trace_sink.py

@@ -0,0 +1,23 @@
+import os
+from typing import Optional
+
+from spaik_sdk.tracing.trace_sink import TraceSink
+
+
+class LocalTraceSink(TraceSink):
+    """TraceSink implementation that writes traces to the local filesystem."""
+
+    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:
+        os.makedirs(self.traces_dir, exist_ok=True)
+
+        trace_path = os.path.join(self.traces_dir, f"{name}.txt")
+        system_prompt_path = os.path.join(self.traces_dir, f"{name}_system_prompt.txt")
+
+        with open(trace_path, "w", encoding="utf-8") as f:
+            f.write(trace_content)
+
+        with open(system_prompt_path, "w", encoding="utf-8") as f:
+            f.write(system_prompt)

spaik_sdk/tracing/trace_sink.py

@@ -0,0 +1,19 @@
+from abc import ABC, abstractmethod
+
+
+class TraceSink(ABC):
+    """Abstract base class for trace storage backends.
+
+    Implementations can write traces to local files, remote APIs, databases, etc.
+    """
+
+    @abstractmethod
+    def save_trace(self, name: str, trace_content: str, system_prompt: str) -> 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
+        """
+        pass

spaik_sdk/tracing/trace_sink_mode.py

@@ -0,0 +1,14 @@
+from enum import Enum
+
+
+class TraceSinkMode(Enum):
+    LOCAL = "local"
+
+    @classmethod
+    def from_name(cls, name: str) -> "TraceSinkMode":
+        for mode in cls:
+            if mode.value == name:
+                return mode
+
+        available_modes = [mode.value for mode in cls]
+        raise ValueError(f"Unknown TraceSinkMode '{name}'. Available: {', '.join(available_modes)}")

spaik_sdk/utils/init_logger.py

@@ -0,0 +1,24 @@
+import logging
+import os
+from typing import cast
+
+LOG_LEVEL = os.environ.get("LOG_LEVEL", "INFO").upper()
+TRACE_LEVEL = 5
+logging.addLevelName(TRACE_LEVEL, "TRACE")
+
+
+class CustomLogger(logging.Logger):
+    def trace(self, msg, *args, **kwargs):
+        if self.isEnabledFor(TRACE_LEVEL):
+            self._log(TRACE_LEVEL, msg, args, **kwargs)
+
+
+def init_logger(name: str) -> CustomLogger:
+    logging.setLoggerClass(CustomLogger)
+    logging.basicConfig(
+        level=getattr(logging, LOG_LEVEL, logging.INFO if LOG_LEVEL == "INFO" else logging.DEBUG),
+        format="%(asctime)s - %(levelname)s - %(filename)s:%(lineno)d - %(message)s",
+        force=True,  # This ensures we override any existing config
+    )
+    logger = logging.getLogger(name)
+    return cast(CustomLogger, logger)

spaik_sdk-0.6.2.dist-info/METADATA

@@ -0,0 +1,379 @@
+Metadata-Version: 2.4
+Name: spaik-sdk
+Version: 0.6.2
+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
+Project-URL: Documentation, https://github.com/siilisolutions/spaik-sdk#readme
+Author-email: Siili Solutions Oyj <info@siili.com>
+License-Expression: MIT
+Keywords: agents,ai,anthropic,claude,gpt,langchain,llm,openai,streaming
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: aioconsole>=0.8.1
+Requires-Dist: azure-storage-blob
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: dotenv>=0.9.9
+Requires-Dist: fastapi>=0.115.12
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: langchain-anthropic>=1.3.0
+Requires-Dist: langchain-core>=1.2.0
+Requires-Dist: langchain-google-genai>=4.0.0
+Requires-Dist: langchain-mcp-adapters>=0.2.1
+Requires-Dist: langchain-ollama>=0.3.0
+Requires-Dist: langchain-openai>=1.1.0
+Requires-Dist: langchain-tavily>=0.2.15
+Requires-Dist: langchain>=1.2.0
+Requires-Dist: langgraph>=1.0.0
+Requires-Dist: mcp>=1.9.2
+Requires-Dist: pandas-stubs
+Requires-Dist: pandas>=2.0.3
+Requires-Dist: pyjwt>=2.8.0
+Requires-Dist: pytest-asyncio>=0.21.1
+Requires-Dist: pytest-cov>=4.1.0
+Requires-Dist: pytest-mock>=3.11.1
+Requires-Dist: pytest>=7.4.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: restrictedpython>=8.0
+Requires-Dist: rich>=14.0.0
+Requires-Dist: uvicorn>=0.33.0
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Spaik SDK
+
+Python SDK for building AI agents with multi-LLM support, streaming, and production infrastructure.
+
+## Installation
+
+```bash
+pip install spaik-sdk
+```
+
+## Quick Start
+
+```python
+from spaik_sdk.agent.base_agent import BaseAgent
+
+class MyAgent(BaseAgent):
+    pass
+
+agent = MyAgent(system_prompt="You are a helpful assistant.")
+print(agent.get_response_text("Hello!"))
+```
+
+## Features
+
+- **Multi-LLM Support**: OpenAI, Anthropic, Google, Azure, Ollama
+- **Unified API**: Same interface across all providers
+- **Streaming**: Real-time response streaming via SSE
+- **Tools**: Function calling with LangChain integration
+- **Structured Output**: Pydantic model responses
+- **Server**: FastAPI with thread persistence, auth, file uploads
+- **Audio**: Text-to-speech and speech-to-text
+- **Cost Tracking**: Token usage and cost estimation
+
+## Agent API
+
+### Basic Response Methods
+
+```python
+from spaik_sdk.agent.base_agent import BaseAgent
+from spaik_sdk.models.model_registry import ModelRegistry
+
+agent = MyAgent(
+    system_prompt="You are helpful.",
+    llm_model=ModelRegistry.CLAUDE_4_SONNET
+)
+
+# Sync - text only
+text = agent.get_response_text("Hello")
+
+# Sync - full message with blocks
+message = agent.get_response("Hello")
+print(message.get_text_content())
+
+# Async
+message = await agent.get_response_async("Hello")
+```
+
+### Streaming
+
+```python
+# Token stream
+async for chunk in agent.get_response_stream("Write a story"):
+    print(chunk, end="", flush=True)
+
+# Event stream (for SSE)
+async for event in agent.get_event_stream("Write a story"):
+    if event.get_event_type() == "StreamingUpdated":
+        print(event.content, end="")
+```
+
+### Structured Output
+
+```python
+from pydantic import BaseModel
+
+class Recipe(BaseModel):
+    name: str
+    ingredients: list[str]
+    steps: list[str]
+
+recipe = agent.get_structured_response("Give me a pasta recipe", Recipe)
+print(recipe.name)
+```
+
+### Interactive CLI
+
+```python
+agent.run_cli()  # Starts interactive chat in terminal
+```
+
+## Tools
+
+```python
+from spaik_sdk.tools.tool_provider import ToolProvider, BaseTool, tool
+
+class WeatherTools(ToolProvider):
+    def get_tools(self) -> list[BaseTool]:
+        @tool
+        def get_weather(city: str) -> str:
+            """Get current weather for a city."""
+            return f"Sunny, 22°C in {city}"
+        
+        @tool
+        def get_forecast(city: str, days: int = 3) -> str:
+            """Get weather forecast."""
+            return f"{days}-day forecast for {city}: Sunny"
+        
+        return [get_weather, get_forecast]
+
+class WeatherAgent(BaseAgent):
+    def get_tool_providers(self) -> list[ToolProvider]:
+        return [WeatherTools()]
+
+agent = WeatherAgent(system_prompt="You provide weather info.")
+print(agent.get_response_text("What's the weather in Tokyo?"))
+```
+
+### Built-in Tool Providers
+
+```python
+from spaik_sdk.tools.impl.search_tool_provider import SearchToolProvider
+from spaik_sdk.tools.impl.mcp_tool_provider import MCPToolProvider
+
+class MyAgent(BaseAgent):
+    def get_tool_providers(self):
+        return [
+            SearchToolProvider(),      # Web search (Tavily)
+            MCPToolProvider(server),   # MCP server tools
+        ]
+```
+
+## Models
+
+```python
+from spaik_sdk.models.model_registry import ModelRegistry
+
+# Anthropic
+ModelRegistry.CLAUDE_4_SONNET
+ModelRegistry.CLAUDE_4_OPUS
+ModelRegistry.CLAUDE_4_5_SONNET
+ModelRegistry.CLAUDE_4_5_OPUS
+
+# OpenAI
+ModelRegistry.GPT_4_1
+ModelRegistry.GPT_4O
+ModelRegistry.O4_MINI
+
+# Google
+ModelRegistry.GEMINI_2_5_FLASH
+ModelRegistry.GEMINI_2_5_PRO
+
+# Aliases
+ModelRegistry.from_name("sonnet")      # CLAUDE_4_SONNET
+ModelRegistry.from_name("gpt 4.1")     # GPT_4_1
+ModelRegistry.from_name("gemini 2.5")  # GEMINI_2_5_FLASH
+
+# Custom model
+from spaik_sdk.models.llm_model import LLMModel
+from spaik_sdk.models.llm_families import LLMFamilies
+
+custom = LLMModel(
+    family=LLMFamilies.OPENAI,
+    name="gpt-4-custom",
+    reasoning=False
+)
+ModelRegistry.register_custom(custom)
+```
+
+## FastAPI Server
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from spaik_sdk.agent.base_agent import BaseAgent
+from spaik_sdk.server.api.routers.api_builder import ApiBuilder
+
+class MyAgent(BaseAgent):
+    pass
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    agent = MyAgent(system_prompt="You are helpful.")
+    api_builder = ApiBuilder.local(agent=agent)
+    
+    app.include_router(api_builder.build_thread_router())
+    app.include_router(api_builder.build_file_router())
+    app.include_router(api_builder.build_audio_router())
+    yield
+
+app = FastAPI(lifespan=lifespan)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+```
+
+### API Endpoints
+
+Thread management:
+- `POST /threads` - Create thread
+- `GET /threads` - List threads
+- `GET /threads/{id}` - Get thread with messages
+- `POST /threads/{id}/messages/stream` - Send message (SSE)
+- `DELETE /threads/{id}` - Delete thread
+- `POST /threads/{id}/cancel` - Cancel generation
+
+Files:
+- `POST /files` - Upload file
+- `GET /files/{id}` - Download file
+
+Audio:
+- `POST /audio/speech` - Text to speech
+- `POST /audio/transcribe` - Speech to text
+
+### Production Setup
+
+```python
+from spaik_sdk.server.storage.impl.local_file_thread_repository import LocalFileThreadRepository
+from spaik_sdk.server.authorization.base_authorizer import BaseAuthorizer
+
+# Custom repository and auth
+api_builder = ApiBuilder.stateful(
+    repository=LocalFileThreadRepository(base_path="./data"),
+    authorizer=MyAuthorizer(),
+    agent=agent,
+)
+```
+
+## Orchestration
+
+Code-first workflow orchestration without graph DSLs:
+
+```python
+from spaik_sdk.orchestration import BaseOrchestrator, OrchestratorEvent
+from dataclasses import dataclass
+from typing import AsyncIterator
+
+@dataclass
+class State:
+    items: list[str]
+
+@dataclass
+class Result:
+    count: int
+
+class MyOrchestrator(BaseOrchestrator[State, Result]):
+    async def run(self) -> AsyncIterator[OrchestratorEvent[Result]]:
+        state = State(items=[])
+        
+        # Run step with automatic status events
+        async for event in self.step("fetch", "Fetching data", self.fetch, state):
+            yield event
+            if event.result:
+                state = event.result
+        
+        # Progress updates
+        for i, item in enumerate(state.items):
+            yield self.progress("process", i + 1, len(state.items))
+            await self.process(item)
+        
+        yield self.ok(Result(count=len(state.items)))
+    
+    async def fetch(self, state: State) -> State:
+        return State(items=["a", "b", "c"])
+    
+    async def process(self, item: str):
+        pass
+
+# Run
+orchestrator = MyOrchestrator()
+result = orchestrator.run_sync()
+```
+
+## Configuration
+
+Environment variables:
+
+```bash
+# LLM Providers (at least one required)
+ANTHROPIC_API_KEY=sk-ant-...
+OPENAI_API_KEY=sk-...
+GOOGLE_API_KEY=...
+
+# Optional
+AZURE_API_KEY=...
+AZURE_ENDPOINT=https://your-resource.openai.azure.com/
+DEFAULT_MODEL=claude-sonnet-4-20250514
+```
+
+## Development
+
+```bash
+# Setup
+uv sync
+
+# Tests
+make test                           # All
+make test-unit                      # Unit only
+make test-integration               # Integration only
+make test-unit-single PATTERN=name  # Single test
+
+# Quality
+make lint                           # Check linting
+make lint-fix                       # Fix linting
+make typecheck                      # Type check
+```
+
+## Message Structure
+
+Messages contain blocks of different types:
+
+```python
+from spaik_sdk.thread.models import MessageBlockType
+
+# Block types
+MessageBlockType.PLAIN      # Regular text
+MessageBlockType.REASONING  # Chain of thought
+MessageBlockType.TOOL_USE   # Tool call
+MessageBlockType.ERROR      # Error message
+```
+
+## License
+
+MIT - Copyright (c) 2025 Siili Solutions Oyj