# smallest-inc/smallest-python-sdk architecture

> Architecture diagram of the GitHub repository smallest-inc/smallest-python-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/smallest-inc/smallest-python-sdk
- Repository: https://github.com/smallest-inc/smallest-python-sdk

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Application Layer
    subgraph "User Application Layer"
        direction TB
        UserApp["User Application"]:::boundary
        SampleScript["sample_scripts/atoms-script.py"]:::boundary
    end

    %% SDK Core
    subgraph "SDK Core" 
        direction TB
        %% Atoms Module
        subgraph "Atoms Module" 
            direction TB
            AtomsConfig["configuration"]:::internal
            AtomsClient["AtomsClient"]:::internal
            AtomsAPIs["api (per-endpoint)"]:::internal
            AtomsModels["models (DTOs)"]:::internal
            AtomsExceptions["exceptions"]:::internal
        end

        %% Transport Layer for Atoms
        subgraph "Atoms Transport" 
            direction TB
            APIClient["api_client"]:::internal
            RestClient["rest"]:::internal
            APIResponse["api_response"]:::internal
        end

        %% Waves Module
        subgraph "Waves Module"
            direction TB
            WavesClient["WavesClient (sync)"]:::internal
            AsyncWavesClient["AsyncWavesClient (async)"]:::internal
            StreamTTS["TextToAudioStream"]:::internal
            WavesModels["models"]:::internal
            WavesUtils["utils"]:::internal
            WavesExceptions["exceptions"]:::internal
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        AtomsAPI["Smallest AI Atoms API"]:::external
        WavesAPI_HTTP["Smallest AI Waves API (HTTP)"]:::external
        WavesAPI_WS["Smallest AI Waves API (WebSocket)"]:::external
    end

    %% Relationships
    UserApp -->|"import SDK / calls create_agent"| AtomsClient
    UserApp -->|"runs script"| SampleScript
    SampleScript -->|"calls synthesize"| WavesClient
    SampleScript -->|"calls synthesize async"| AsyncWavesClient

    AtomsClient -->|"uses config"| AtomsConfig
    AtomsClient -->|"invokes endpoints"| AtomsAPIs
    AtomsClient -->|"serializes/deserializes"| AtomsModels
    AtomsClient -->|"handles errors"| AtomsExceptions
    AtomsClient -->|"calls transport"| APIClient

    APIClient -->|"REST request/response"| RestClient
    RestClient -->|"parses response"| APIResponse
    APIClient -->|"HTTP POST/GET"| AtomsAPI

    WavesClient -->|"HTTP Request"| WavesAPI_HTTP
    WavesClient -->|"serializes/deserializes"| WavesModels
    WavesClient -->|"handles errors"| WavesExceptions
    WavesClient -->|"uses utils"| WavesUtils

    AsyncWavesClient -->|".async WebSocket"| WavesAPI_WS
    AsyncWavesClient -->|"streams to"| StreamTTS
    StreamTTS -->|"audio chunks"| UserApp

    %% Click Events
    click AtomsClient "https://github.com/smallest-inc/smallest-python-sdk/blob/main/smallestai/atoms/atoms_client.py"
    click AtomsAPIs "https://github.com/smallest-inc/smallest-python-sdk/tree/main/smallestai/atoms/api/"
    click AtomsModels "https://github.com/smallest-inc/smallest-python-sdk/tree/main/smallestai/atoms/models/"
    click AtomsConfig "https://github.com/smallest-inc/smallest-python-sdk/blob/main/smallestai/atoms/configuration.py"
    click AtomsExceptions "https://github.com/smallest-inc/smallest-python-sdk/blob/main/smallestai/atoms/exceptions.py"
    click APIClient "https://github.com/smallest-inc/smallest-python-sdk/blob/main/smallestai/atoms/api_client.py"
    click RestClient "https://github.com/smallest-inc/smallest-python-sdk/blob/main/smallestai/atoms/rest.py"
    click APIResponse "https://github.com/smallest-inc/smallest-python-sdk/blob/main/smallestai/atoms/api_response.py"
    click WavesClient "https://github.com/smallest-inc/smallest-python-sdk/blob/main/smallestai/waves/waves_client.py"
    click AsyncWavesClient "https://github.com/smallest-inc/smallest-python-sdk/blob/main/smallestai/waves/async_waves_client.py"
    click StreamTTS "https://github.com/smallest-inc/smallest-python-sdk/blob/main/smallestai/waves/stream_tts.py"
    click WavesModels "https://github.com/smallest-inc/smallest-python-sdk/blob/main/smallestai/waves/models.py"
    click WavesUtils "https://github.com/smallest-inc/smallest-python-sdk/blob/main/smallestai/waves/utils.py"
    click WavesExceptions "https://github.com/smallest-inc/smallest-python-sdk/blob/main/smallestai/waves/exceptions.py"
    click SampleScript "https://github.com/smallest-inc/smallest-python-sdk/blob/main/sample_scripts/atoms-script.py"

    %% Styles
    classDef internal fill:#D6E4FF,stroke:#4D6AFF,color:#000
    classDef external fill:#D4FFD6,stroke:#2E8B2E,color:#000
    classDef boundary fill:#FFF5CC,stroke:#CCA300,color:#000
```
