How smallest-inc/smallest-python-sdk works
Project Type and Purpose
• This is an open-source Python SDK (client library) for interacting with Smallest AI’s “Atoms” and “Waves” services.
• AtomsClient: high-level orchestration of voice agents (create agents, knowledge bases, campaigns, outbound calls, workflows).
• WavesClient & AsyncWavesClient: low-level Text-to-Speech (TTS) synthesis (sync, async, streaming, LLM-to-speech).
• Provides model classes, API clients, configuration & error handling. Meant to be embedded in user applications.
File Structure Analysis
• Top-Level
• pyproject.toml, requirements.txt – build and dependency metadata
• sample_scripts/ – end-user example usage
• tests/ – unit tests for both atoms and waves modules
• docs/ – generated API reference documentation for Atoms
• smallestai/ – core SDK package
• atoms/ – AtomsClient subtree
– api/ (per-endpoint modules: agents_api.py, calls_api.py, …)
– api_client.py, atoms_client.py, configuration.py, exceptions.py, api_response.py, rest.py
– models/ – data classes for requests/responses
• waves/ – WavesClient subtree
– waves_client.py, async_waves_client.py – synchronous & asynchronous clients
– stream_tts.py, utils.py, models.py, exceptions.py
Key Architecture Insights from README
• Two parallel service clients (Atoms vs Waves) share similar patterns:
• Configuration (API key, endpoint)
• API calls → HTTP/REST (synchronous or streaming WebSockets for Waves)
• Model serialization/deserialization
• Asynchronous support for TTS and streaming pipelines (TextToAudioStream).
• Sample UIs: scripts show typical flows.
a. Main Components
1. User Application – imports smallestai SDK
2. AtomsClient Module
• Configuration
• AtomsClient façade
• Per-endpoint API modules
• Models for DTOs
3. WavesClient Module
• WavesClient (sync)
• AsyncWavesClient
• TextToAudioStream (streaming adapter)
4. HTTP / WebSocket Transport
• REST client (requests or httpx)
• WebSocket client for streaming
5. External Services
• Smallest AI Atoms API (HTTP)
• Smallest AI Waves API (HTTP & WS)
b. Relationships & Data Flows
• User App → (calls) → AtomsClient.create_agent / start_outbound_call
• AtomsClient → (uses) → api_client → HTTP POST/GET to Atoms API → response → models → return to app
• User App → (calls) → WavesClient.synthesize → HTTP → binary WAV data → saved/streamed
• Async path: User App → AsyncWavesClient → WebSockets for streaming chunks → TextToAudioStream → audio chunks
c. Architectural Patterns & Principles
• Facade Pattern: AtomsClient & WavesClient hide low-level HTTP details
• Layered Architecture: Presentation (sample app), Client layer, Transport layer, External API
• Adapter/Strategy: sync vs async clients, streaming vs batch synthesis
• Strong typing & data modeling via Pydantic-style or dataclass models
d. Key Technologies & Frameworks
• Python 3.9+
• HTTP library (requests/httpx)
• Asyncio + websockets
• Packaging (pyproject.toml)
• Automated tests (pytest)
Detailed Checklist
• Config object flowing into both clients
• REST client & error handling layer beneath both clients
• Distinguish synchronous vs asynchronous paths in Waves
• Sample usage entry points (sample_scripts) as examples of the “User App” invoking the SDK