spaik-sdk 0.6.2__tar.gz

spaik_sdk-0.6.2/.cursor/rules/global.mdc

@@ -0,0 +1,32 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# General
+
+this project is a helper SDK for building various kinds of agentic + ai solutions
+
+main goal is to give good DX and make it fast and easy to build POCs that also are of good quality
+and something you can easily get to production as well
+
+
+# style stuff:
+
+- use absolute imports
+- comments are a code smell, avoid docstrings too if not adding anything
+- empty __init__.py unless otherwise specified
+- no star imports
+- always use types
+- use uv and ruff
+
+
+# logging
+
+this is the way to obtain the logger:
+
+```
+from spaik_sdk.utils.init_logger import init_logger
+
+logger = init_logger(__name__)
+```

spaik_sdk-0.6.2/.cursor/rules/post_run.mdc

@@ -0,0 +1,14 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+
+After you have done something substantial (eg. touching multiple files):
+
+First, take a look at the code you wrote. Does it look clean an elegant with good separation of concerns and small files and small methods. If not, go clean it up. Also make sure you don't have any inline imports etc smelly stuff.
+
+Then run this command to make sure everything is ok:
+
+`make lint-fix && make typecheck && make test-unit`
+

spaik_sdk-0.6.2/.cursor/rules/repo_overview.mdc

@@ -0,0 +1,84 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# Agent SDK - Repository Overview
+
+This is a Python-based Agent SDK for building various kinds of agentic + AI solutions. The main goal is to provide good DX (Developer Experience) and make it fast and easy to build POCs that are also of good quality and can easily transition to production.
+
+## Core Purpose & Philosophy
+
+- **Helper SDK** for building agentic + AI solutions
+- **Fast POC Development** that scales to production quality
+- **Good DX** with clean abstractions and patterns
+- **Multi-LLM Support** with unified interface
+- **Streaming & Interactive** capabilities built-in
+
+## Project Structure & Key Components
+
+### Entry Points
+- **[main.py](mdc:main.py)** - Main application entry point, demonstrates DemoAgent and MinimalAgent usage
+- **[setup.sh](mdc:setup.sh)** - Development environment setup script
+
+### Core Architecture Modules
+
+#### **Agent System** (`app/agent/`)
+- **[app/agent/base_agent.py](mdc:app/agent/base_agent.py)** - BaseAgent class providing foundation for all agents
+- **[app/demo_agents/](mdc:app/demo_agents)** - Example agent implementations (DemoAgent, MinimalAgent)
+
+#### **LLM Integration** (`app/models/`)
+Multi-provider LLM support with factory pattern:
+- **Supported Providers**: Anthropic (Claude), OpenAI (GPT), Google (Gemini), Azure AI Foundry
+- **[app/models/llm_types.py](mdc:app/models/llm_types.py)** - Model enums and provider types
+- **[app/models/llm_config.py](mdc:app/models/llm_config.py)** - LLM configuration dataclass
+- **[app/models/factories/](mdc:app/models/factories)** - Model factory implementations per provider
+- **[app/models/providers/](mdc:app/models/providers)** - Provider-specific API integrations
+
+#### **LangChain Service Layer** (`app/llm/`)
+- **[app/llm/langchain_service.py](mdc:app/llm/langchain_service.py)** - Core service wrapping LangChain functionality
+- **[app/llm/message_handler.py](mdc:app/llm/message_handler.py)** - Conversation history and message processing
+- **[app/llm/streaming/](mdc:app/llm/streaming)** - Streaming response handling components
+
+#### **Thread Management** (`app/thread/`)
+- **[app/thread/thread_container.py](mdc:app/thread/thread_container.py)** - Core conversation state management
+- **[app/thread/models.py](mdc:app/thread/models.py)** - Message, block, and event data models
+- **[app/thread/adapters/](mdc:app/thread/adapters)** - Different interaction interfaces (sync, CLI)
+
+#### **Tool System** (`app/tools/`)
+- **[app/tools/tool_provider.py](mdc:app/tools/tool_provider.py)** - Abstract base for creating agent tools
+- Supports LangChain BaseTool integration with Pydantic schemas
+
+#### **Configuration & Infrastructure**
+- **[config/env.py](mdc:config/env.py)** - Environment variable management
+- **[app/prompt/prompt_loader.py](mdc:app/prompt/prompt_loader.py)** - Static prompt loading from markdown
+- **[app/tracing/agent_trace.py](mdc:app/tracing/agent_trace.py)** - Execution tracing for debugging
+- **[app/utils/init_logger.py](mdc:app/utils/init_logger.py)** - Logging utilities
+
+## Key Technologies & Dependencies
+
+- **Python 3.10+** with modern async/await patterns
+- **LangChain** - Primary framework for LLM orchestration
+- **LangGraph** - For stateful, multi-actor applications
+- **FastAPI** - Web framework for API endpoints
+- **Pydantic** - Data validation and settings management
+- **uv** - Fast Python package manager and runner
+- **ruff** - Fast Python linter and formatter
+
+## Architectural Patterns
+
+1. **Agent-Based Architecture** - BaseAgent foundation with concrete implementations
+2. **Factory Pattern** - For LLM provider instantiation
+3. **Provider Pattern** - Unified interface across different LLM APIs
+4. **Event-Driven** - ThreadContainer publishes events for real-time updates
+5. **Streaming-First** - Built-in support for streaming responses
+6. **Tool Integration** - LangChain tool ecosystem integration
+7. **Modular Design** - Clear separation of concerns across modules
+
+## Development Standards
+
+- **Absolute imports** - No relative imports
+- **Type annotations** - Always use types
+- **Minimal comments** - Code should be self-documenting
+- **Empty `__init__.py`** - Unless otherwise specified
+- **uv + ruff** - Package management and linting

spaik_sdk-0.6.2/.cursor/rules/testing-structure.mdc

@@ -0,0 +1,54 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# Testing Structure
+
+## Unit Tests
+- Location: `tests/unit/{folder path to file being tested}/test_{filename}.py`
+- Example: For `spaik_sdk/agent/base_agent.py` → `tests/unit/spaik_sdk/agent/test_base_agent.py`
+- Use `@pytest.mark.unit` decorator
+- Mock external dependencies
+
+## Integration Tests  
+- Location: `tests/integration/` (freeform structure)
+- Use `@pytest.mark.integration` decorator
+- Test complete workflows and component interactions
+
+## Test Configuration
+- Main config in [pyproject.toml](mdc:pyproject.toml) under `[tool.pytest.ini_options]`
+- Shared fixtures in [tests/conftest.py](mdc:tests/conftest.py)
+- Test utilities in [tests/utils.py](mdc:tests/utils.py)
+
+## Running Tests
+- Use [Makefile](mdc:Makefile) commands: `make test`, `make test-unit`, `make test-integration`
+- Or directly: `uv run pytest`
+
+
+## Philosophy
+- test the public interface, not the implementation and how its coded
+- don't add stupid do-nothing tests that just check completely trivial aspects
+
+Example offender:
+```
+def test_valid_config_creation(self):
+        """Test creating a valid LLMConfig."""
+        config = LLMConfig(
+            model=LLMModel.CLAUDE_3_HAIKU,
+            provider_type=ProviderType.ANTHROPIC,
+            reasoning=True,
+            tool_usage=False
+        )
+        
+        assert config.model == LLMModel.CLAUDE_3_HAIKU
+        assert config.provider_type == ProviderType.ANTHROPIC
+        assert config.reasoning is True
+        assert config.tool_usage is False
+```    
+
+The above is 100% pollution in the codebase and gives us absolutely no guarantees of things working.
+
+Focus on corner cases and things that might actually break. Do NOT aim for 100% coverage or any such nonsense. 
+
+We want to test things that might actually break and test them well (not just the happy paths)

spaik_sdk-0.6.2/.gitignore

@@ -0,0 +1,41 @@
+# Dependencies
+node_modules
+.pnp
+.pnp.js
+
+# Production
+# dist
+build
+
+# Testing
+coverage
+
+# Misc
+.DS_Store
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Editor
+.vscode/*
+!.vscode/extensions.json
+.idea
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw? 
+venv
+__pycache__
+.aider*
+
+traces/*
+data/*
+recordings/*

spaik_sdk-0.6.2/Makefile

@@ -0,0 +1,92 @@
+# Makefile for Agent SDK Testing
+
+.PHONY: test test-unit test-integration test-watch test-cov test-fast help clean lint lint-fix typecheck
+
+# Default target
+help:
+	@echo "Available targets:"
+	@echo "  test         - Run all tests"
+	@echo "  test-unit    - Run only unit tests" 
+	@echo "  test-unit-single - Run single unit test by pattern"
+	@echo "  test-integration - Run only integration tests"
+	@echo "  test-fast    - Run fast tests (exclude slow tests)"
+	@echo "  test-watch   - Run tests in watch mode"
+	@echo "  test-cov     - Run tests with coverage report"
+	@echo "  test-html    - Run tests with HTML coverage report"
+	@echo "  lint         - Run linting checks"
+	@echo "  lint-fix     - Run linting with auto-fix"
+	@echo "  typecheck    - Run type checking with mypy"
+	@echo "  clean        - Clean test artifacts"
+
+# Run all tests
+test:
+	uv run python3 -m pytest tests/
+
+# Run only unit tests
+test-unit:
+	uv run python3 -m pytest tests/unit/ -m "unit" --no-cov
+
+# Run single unit test by pattern
+test-unit-single:
+	@if [ -z "$(PATTERN)" ]; then echo "Usage: make test-unit-single PATTERN=test_name_pattern"; exit 1; fi
+	LOG_LEVEL=DEBUG uv run python3 -m pytest tests/unit/ -m "unit" --no-cov -k "$(PATTERN)" -v
+
+# Run only integration tests  
+test-integration:
+	uv run python3 -m pytest tests/integration/ -m "integration"
+
+# Run fast tests (exclude slow ones)
+test-fast:
+	uv run python3 -m pytest tests/ -m "not slow"
+
+# Run tests in watch mode (requires pytest-watch)
+test-watch:
+	uv run pytest-watch --clear
+
+# Run tests with coverage
+test-cov:
+	uv run python3 -m pytest --cov=spaik_sdk --cov-report=term-missing
+
+# Run tests with HTML coverage report
+test-html:
+	uv run python3 -m pytest --cov=spaik_sdk --cov-report=html
+	@echo "Coverage report generated in htmlcov/index.html"
+
+# Run specific test file
+test-file:
+	@if [ -z "$(FILE)" ]; then echo "Usage: make test-file FILE=path/to/test_file.py"; exit 1; fi
+	uv run python3 -m pytest $(FILE) -v
+
+# Run tests matching a pattern
+test-pattern:
+	@if [ -z "$(PATTERN)" ]; then echo "Usage: make test-pattern PATTERN=test_name_pattern"; exit 1; fi
+	uv run python3 -m pytest -k "$(PATTERN)" -v
+
+# Run linting checks
+lint:
+	uv run ruff check .
+
+# Run linting with auto-fix
+lint-fix:
+	uv run ruff check --fix --unsafe-fixes .
+	uv run ruff format .
+
+# Run type checking
+typecheck:
+	uv run ty check spaik_sdk tests
+
+# Clean test artifacts
+clean:
+	rm -rf .pytest_cache/
+	rm -rf htmlcov/
+	rm -rf .coverage
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+
+# Debug tests (run with verbose output and no capture)
+test-debug:
+	uv run python3 -m pytest tests/ -v -s --tb=long
+
+# Run tests and generate JUnit XML (for CI)
+test-ci:
+	uv run python3 -m pytest tests/ --junitxml=test-results.xml --cov=spaik_sdk --cov-report=xml 

spaik_sdk-0.6.2/PKG-INFO

@@ -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