siili-ai-sdk 0.5.0__tar.gz

siili_ai_sdk-0.5.0/.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 siili_ai_sdk.utils.init_logger import init_logger
+
+logger = init_logger(__name__)
+```

siili_ai_sdk-0.5.0/.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`
+

siili_ai_sdk-0.5.0/.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

siili_ai_sdk-0.5.0/.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 `siili_ai_sdk/agent/base_agent.py` → `tests/unit/siili_ai_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)

siili_ai_sdk-0.5.0/.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/*

siili_ai_sdk-0.5.0/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=siili_ai_sdk --cov-report=term-missing
+
+# Run tests with HTML coverage report
+test-html:
+	uv run python3 -m pytest --cov=siili_ai_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 siili_ai_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=siili_ai_sdk --cov-report=xml 

siili_ai_sdk-0.5.0/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: siili-ai-sdk
+Version: 0.5.0
+Summary: Python SDK for building AI agents with multi-LLM support, streaming, and production-ready infrastructure
+Project-URL: Homepage, https://github.com/siilisolutions/siili-ai-sdk
+Project-URL: Repository, https://github.com/siilisolutions/siili-ai-sdk
+Project-URL: Documentation, https://github.com/siilisolutions/siili-ai-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: crawl4ai>=0.7.4
+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
+
+# Siili AI SDK 
+
+A Python SDK for building AI agents with multi-LLM support, streaming capabilities, and production-ready infrastructure.
+
+## Features
+
+- **Multi-LLM Support**: OpenAI, Anthropic, Google, Azure models
+- **Streaming**: Real-time response streaming
+- **Tools**: Custom tool integration with LangChain
+- **Production Ready**: FastAPI server with REST/SSE APIs
+- **Type Safe**: Full type annotations
+
+## Quick Start
+
+### Simple Agent
+
+```python
+from dotenv import load_dotenv
+from siili_ai_sdk.agent.base_agent import BaseAgent
+
+class HelloAgent(BaseAgent):
+    def __init__(self):
+        super().__init__(system_prompt="You're an unhelpful assistant that cant resist constantly talking about cats.")
+
+if __name__ == "__main__":
+    load_dotenv()
+    agent = HelloAgent()
+    print(agent.get_response_text("Hello"))
+```
+
+### Agent with Tools + FastAPI Server
+
+```python
+from typing import List
+import uvicorn
+from dotenv import load_dotenv
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from siili_ai_sdk.agent.base_agent import BaseAgent
+from siili_ai_sdk.tools.tool_provider import ToolProvider, tool, BaseTool
+from siili_ai_sdk.server.api.routers.api_builder import ApiBuilder
+from siili_ai_sdk.models.model_registry import ModelRegistry
+
+load_dotenv()
+
+app = FastAPI(title="Agent SDK Backend Example", version="0.0.1")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+class DemoTool(ToolProvider):
+    def get_tools(self) -> List[BaseTool]:
+        @tool
+        def get_secret_greeting() -> str:
+            """Returns the users secret greeting."""
+            return "kikkelis kokkelis"
+
+        @tool
+        def get_user_name() -> str:
+            """Returns the users name."""
+            return "Seppo Hovi"
+
+        return [get_secret_greeting, get_user_name]
+
+class DemoAgent(BaseAgent):
+    def get_tool_providers(self) -> List[ToolProvider]:
+        return [DemoTool()]
+
+@app.on_event("startup")
+async def startup_event():
+    agent = DemoAgent(llm_model=ModelRegistry.CLAUDE_4_SONNET)
+    api_builder = ApiBuilder.local(agent=agent)
+    thread_router = api_builder.build_thread_router()
+    app.include_router(thread_router)
+
+def run_server():
+    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True, log_level="info")
+
+if __name__ == "__main__":
+    run_server()
+```
+
+## Configuration
+
+Set up your environment variables:
+
+```bash
+# API Keys
+ANTHROPIC_API_KEY=your-anthropic-key
+OPENAI_API_KEY=your-openai-key  
+GOOGLE_API_KEY=your-google-key
+
+# Azure (optional)
+AZURE_API_KEY=your-azure-key
+AZURE_ENDPOINT=https://your-resource.openai.azure.com/
+```
+
+## Available Models
+
+```python
+from siili_ai_sdk.models.model_registry import ModelRegistry
+
+# Use model registry for easy access
+ModelRegistry.CLAUDE_4_SONNET
+ModelRegistry.GPT_4_1
+ModelRegistry.GEMINI_2_5_FLASH
+ModelRegistry.O4_MINI
+
+# Or use aliases
+ModelRegistry.from_name("sonnet")      # -> CLAUDE_4_SONNET
+ModelRegistry.from_name("gpt 4.1")     # -> GPT_4_1
+```
+
+## More Usage Examples
+
+### Streaming Response
+
+```python
+async def stream_example():
+    agent = DemoAgent()
+    async for chunk in agent.get_response_stream("Write a story"):
+        print(chunk.content, end="", flush=True)
+```
+
+### Structured Response
+
+```python
+from pydantic import BaseModel
+
+class Recipe(BaseModel):
+    name: str
+    ingredients: list[str]
+    instructions: list[str]
+
+response = agent.get_structured_response("Create a pasta recipe", Recipe)
+print(f"Recipe: {response.name}")
+```
+
+### Interactive CLI
+
+```python
+agent = DemoAgent()
+agent.run_cli()  # Starts interactive chat
+```
+
+## API Endpoints
+
+When running the FastAPI server:
+
+```bash
+# Health check
+GET /health
+
+# Create thread
+POST /threads
+
+# Send message (streaming)
+POST /threads/{thread_id}/messages/stream
+
+# Get messages
+GET /threads/{thread_id}/messages
+```
+
+## Development
+
+```bash
+# Setup
+./setup.sh
+
+# Run tests
+make test
+
+# Format code
+ruff check --fix
+ruff format
+```
+
+## Project Structure
+
+```
+siili_ai_sdk/
+├── agent/          # Core agent implementations
+├── llm/            # LangChain service and streaming
+├── models/         # LLM providers and configuration
+├── thread/         # Conversation management
+├── tools/          # Tool system
+├── server/         # FastAPI server infrastructure
+└── utils/          # Shared utilities
+```
+