# liquidmetal-ai/lm-raindrop-python-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/liquidmetal-ai/lm-raindrop-python-sdk
- Repository: https://github.com/liquidmetal-ai/lm-raindrop-python-sdk

## Overview

##### Project Type and Purpose
- This is a Python SDK/library (“lm-raindrop”) that provides both synchronous and asynchronous clients to interact with the Raindrop REST API.
- It targets Python ≥3.8, wrapping HTTP calls (via httpx) and exposing typed request/response models (TypedDict + Pydantic) for ease of use.

##### High-Level Components
- Client Layer:
- Raindrop (sync) – defined in `_client.py`, built on top of `_base_client.py`.
- AsyncRaindrop – extends the same base client for asynchronous use.
- HTTP Transport:
- DefaultHttpxClient – wrapper around httpx.Client / httpx.AsyncClient; configurable per-request or globally.
- Endpoint/Resource Modules:
- Each resource (search, chunk_search, document_query, storage_object, summarize_page) lives under `src/lm_raindrop/resources/*.py`.
- They expose methods `.find()`, `.retrieve()`, `.create()`, etc., delegating to the client.
- Models & Types:
- `src/lm_raindrop/types/` – TypedDict definitions for all request parameters and responses.
- `_models.py` – Pydantic models for parsing and validation of JSON responses.
- Utilities:
- `src/lm_raindrop/_utils/` – logging, proxy handling, streaming helpers, reflection.
- Error Handling:
- `_exceptions.py` – custom exceptions (APIError, APIStatusError, RateLimitError, etc.).
- Streaming & Raw Response:
- `_streaming.py` / `_response.py` – support for `.with_streaming_response` and `.with_raw_response`.
- Support Code:
- `scripts/`, `bin/` and GitHub Actions workflows for CI, linting, formatting, testing, and publishing to PyPI.
- External Service:
- Raindrop REST API (base_url configurable via client or environment variable).

##### Relationships & Data Flow
1. User code imports Raindrop or AsyncRaindrop.
2. User invokes `client.<resource>.<method>(...)`.
3. The resource module constructs the HTTP path, query/body payload using type definitions.
4. BaseClient calls into DefaultHttpxClient, issuing an HTTP request.
5. httpx receives the HTTP response from the Raindrop API.
6. BaseClient reads response:
- On normal calls, response body is parsed and instantiated as Pydantic model (or iterator of models for streaming/pagination).
- On `.with_raw_response` or `.with_streaming_response`, underlying httpx.Response is exposed.
7. Exceptions are raised if status codes ≠2xx or on connection/time-out errors.
8. Parsed model or raw/streaming response returns to user code.

##### Architectural Patterns & Design Principles
- Layered design: separation of client logic, transport, resources, models, and utilities.
- Dependency injection: allows swapping httpx client, base_url, retries, timeouts.
- Code generation: consistent patterns across resources (via Stainless).
- Async/Synchronous duality: share logic via base classes, minimize duplication.
- Typed interfaces: TypedDict for requests, Pydantic models for responses, improving IDE support.

##### Essential Elements
- Clear component labels and boundaries.
- Core library code vs utils vs external vs CI.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User Application"]:::user

    %% Client Layer
    subgraph "Client Layer"
        direction TB
        SyncClient["_client.py: Raindrop (sync)"]:::sync
        AsyncClient["_client.py: AsyncRaindrop (async)"]:::async
        BaseClient["_base_client.py: BaseClient"]:::core
        SyncClient -->|uses| BaseClient
        AsyncClient -->|uses| BaseClient
    end

    %% Transport Layer
    subgraph "HTTP Transport"
        direction TB
        HttpTransport["_client.py: DefaultHttpxClient"]:::core
        BaseClient -->|calls| HttpTransport
    end

    %% Resources
    subgraph "Resource Modules"
        direction TB
        Search["search.py"]:::core
        ChunkSearch["chunk_search.py"]:::core
        DocumentQuery["document_query.py"]:::core
        StorageObject["storage_object.py"]:::core
        SummarizePage["summarize_page.py"]:::core
        SyncClient -->|invokes| Search
        SyncClient -->|invokes| ChunkSearch
        SyncClient -->|invokes| DocumentQuery
        SyncClient -->|invokes| StorageObject
        SyncClient -->|invokes| SummarizePage
        AsyncClient -->|invokes| Search
        AsyncClient -->|invokes| ChunkSearch
        AsyncClient -->|invokes| DocumentQuery
        AsyncClient -->|invokes| StorageObject
        AsyncClient -->|invokes| SummarizePage
    end

    %% Models & Types
    subgraph "Model Layer"
        direction TB
        Types["types/*.py"]:::core
        PydanticModels["_models.py"]:::core
        Search -->|builds payload / parses| Types
        ChunkSearch -->|builds payload / parses| Types
        DocumentQuery -->|builds payload / parses| Types
        StorageObject -->|builds payload / parses| Types
        SummarizePage -->|builds payload / parses| Types
        HttpTransport -->|parses| PydanticModels
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        Logs["_logs.py"]:::core
        Proxy["_proxy.py"]:::core
        Reflection["_reflection.py"]:::core
        ResourcesProxy["_resources_proxy.py"]:::core
        Streams["_streams.py"]:::core
        SyncUtils["_sync.py"]:::core
        Transform["_transform.py"]:::core
        Typing["_typing.py"]:::core
        Utils["_utils.py"]:::core

        BaseClient -->|uses| Logs
        BaseClient -->|uses| Proxy
        BaseClient -->|uses| Reflection
        BaseClient -->|uses| ResourcesProxy
        BaseClient -->|uses| SyncUtils
        BaseClient -->|uses| Streams
        BaseClient -->|uses| Transform
        BaseClient -->|uses| Typing
        BaseClient -->|uses| Utils
    end

    %% Error Handling
    Exceptions["_exceptions.py"]:::core
    BaseClient -->|raises| Exceptions
    HttpTransport -->|raises| Exceptions

    %% Response Support
    Streaming["_streaming.py"]:::core
    RawResponse["_response.py"]:::core
    BaseClient -->|with_streaming_response| Streaming
    BaseClient -->|with_raw_response| RawResponse

    %% Other Core Modules
    QS["_qs.py"]:::core
    Constants["_constants.py"]:::core
    Compat["_compat.py"]:::core
    Files["_files.py"]:::core
    Pagination["pagination.py"]:::core
    Version["_version.py"]:::core
    BaseClient --> QS
    BaseClient --> Constants
    BaseClient --> Compat
    BaseClient --> Files
    BaseClient --> Pagination
    BaseClient --> Version

    %% External API
    RaindropAPI("Raindrop REST API"):::external
    HttpTransport -->|HTTP request| RaindropAPI
    RaindropAPI -->|HTTP response| HttpTransport

    %% CI/CD Pipeline
    subgraph "CI/CD & Tooling"
        direction TB
        CI[".github/workflows/*.yml"]:::pipeline
        Nox["noxfile.py"]:::pipeline
        Scripts["scripts/"]:::pipeline
        PublishBin["bin/publish-pypi"]:::pipeline
        DevContainer[".devcontainer/"]:::pipeline
        CI -->|runs| Nox
        CI -->|runs| Scripts
        CI -->|publishes| PublishBin
    end

    %% Flows
    User -->|imports| SyncClient
    User -->|imports| AsyncClient
    PydanticModels -->|returns| User

    %% Click events
    click SyncClient "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/_client.py"
    click AsyncClient "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/_client.py"
    click BaseClient "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/_base_client.py"
    click HttpTransport "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/_client.py"
    click Search "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/resources/search.py"
    click ChunkSearch "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/resources/chunk_search.py"
    click DocumentQuery "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/resources/document_query.py"
    click StorageObject "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/resources/storage_object.py"
    click SummarizePage "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/resources/summarize_page.py"
    click Types "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/tree/main/src/lm_raindrop/types/"
    click PydanticModels "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/_models.py"
    click Logs "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/_utils/_logs.py"
    click Proxy "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/_utils/_proxy.py"
    click Reflection "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/_utils/_reflection.py"
    click ResourcesProxy "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/_utils/_resources_proxy.py"
    click Streams "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/_utils/_streams.py"
    click SyncUtils "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/_utils/_sync.py"
    click Transform "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/_utils/_transform.py"
    click Typing "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/_utils/_typing.py"
    click Utils "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/_utils/_utils.py"
    click Exceptions "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/_exceptions.py"
    click Streaming "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/_streaming.py"
    click RawResponse "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/_response.py"
    click QS "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/_qs.py"
    click Constants "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/_constants.py"
    click Compat "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/_compat.py"
    click Files "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/_files.py"
    click Pagination "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/pagination.py"
    click Version "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/src/lm_raindrop/_version.py"
    click CI "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/.github/workflows/ci.yml"
    click Nox "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/blob/main/noxfile.py"
    click Scripts "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/tree/main/scripts/"
    click PublishBin "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/tree/main/bin/publish-pypi"
    click DevContainer "https://github.com/liquidmetal-ai/lm-raindrop-python-sdk/tree/main/.devcontainer/"

    %% Styles
    classDef sync fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef async fill:#E6FFED,stroke:#28a745,color:#22863a
    classDef core fill:#F0F0F0,stroke:#666666,color:#333333
    classDef external fill:#FFEFD5,stroke:#FF8C00,color:#FF8C00
    classDef pipeline fill:#EEEEEE,stroke:#999999,color:#555555
    classDef user fill:#FFF4E5,stroke:#D58512,color:#D58512
```
