# truefoundry/truefoundry-python-sdk architecture

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

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

## Overview

##### Project type and purpose
- This is a Python SDK (client library) for the Truefoundry API.
- It provides a sync (`TrueFoundry`) and async (`AsyncTrueFoundry`) facade over HTTP calls to Truefoundry’s REST endpoints.
- It auto-generates per-resource “client” and “raw_client” modules plus Pydantic-style request/response types for every API surface.

##### File structure
- Top-level:
- pyproject.toml, requirements.txt, .github/workflows/ci.yml – build/test CI
- src/truefoundry_sdk – the entire SDK codebase
- tests – unit/integration tests
- src/truefoundry_sdk:
- client.py & base_client.py – entry points (TrueFoundry, AsyncTrueFoundry)
- _wrapped_clients.py – helper to wire raw & typed calls
- core/ – HTTP abstraction, error handling, serialization, pagination, retries
- <resource>/client.py & raw_client.py – typed vs raw response clients per resource (e.g., applications, clusters, jobs…)
- types/ – Pydantic-style models for request & response schemas
- internal/ – same structure under “internal”, used for private endpoints
- version.py – SDK version
- tests/ – verify http client logic, serialization, query-encoding, and high-level behavior.

##### README insights
- Outlines use of `TrueFoundry(api_key, base_url)` and `AsyncTrueFoundry`.
- Describes advanced features: raw response access (`.with_raw_response`), retries, timeouts, custom HTTPX client.
- Indicates that code is generated and strongly typed.

##### Main components
a. Public API Layer
- TrueFoundry (sync)
- AsyncTrueFoundry (async)
b. Resource Client Layer
- Typed clients: applications.client, clusters.client, jobs.client, …
- Raw clients: applications.raw_client, clusters.raw_client, …
c. Core Layer
- BaseClient, ClientWrapper
- HTTP abstraction: http_client.py (built on httpx), retries, pagination logic, JSON serialization
d. Model Layer
- types/ request & response models
- internal/types for private endpoints
e. External Dependencies
- httpx (HTTP transport)
- pydantic (data validation/serialization)
- fern (code generation, implied)
f. External System
- Truefoundry REST API (hosted service)

##### Relationships and interactions
- Public API Layer calls Resource Client Layer.
- Resource Client uses Core Layer to perform HTTP requests.
- Core Layer serializes Pydantic models into JSON, sends via httpx, handles retries/timeouts.
- HTTPX sends requests to Truefoundry REST API and returns raw responses.
- Core Layer parses HTTP response into Python objects via Pydantic models from the Model Layer.
- `.with_raw_response` bridges typed clients and raw HTTP data.
- Tests invoke both Core and Resource Client layers, verifying correct behavior.

##### Architectural patterns & design principles
- Layered architecture: clear separation of concerns (Facade → Domain clients → HTTP core → network).
- Adapter pattern: wrapping httpx client in your own HTTP client with retry & pagination adapters.
- Code generation for consistency across dozens of endpoints.
- Type-safe models with Pydantic/“types” folder.
- Sync vs Async dual API using the same core logic via wrappers.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Public API Layer
    subgraph "Public API Layer"
        direction TB
        TF["TrueFoundry (sync)"]:::public
        ATF["AsyncTrueFoundry (async)"]:::public
        WC["_wrapped_clients (raw vs typed)"]:::public
    end

    %% Resource Client Layer
    subgraph "Resource Client Layer"
        direction TB
        subgraph "Applications"
            direction TB
            APP_C["applications.client"]:::impl
            APP_RC["applications.raw_client"]:::impl
        end
        subgraph "Clusters"
            direction TB
            CLU_C["clusters.client"]:::impl
            CLU_RC["clusters.raw_client"]:::impl
        end
        subgraph "Jobs"
            direction TB
            JOB_C["jobs.client"]:::impl
            JOB_RC["jobs.raw_client"]:::impl
        end
    end

    %% Core Layer
    subgraph "Core Layer"
        direction TB
        HC["http_client"]:::impl
        HR["http_response"]:::impl
        JE["jsonable_encoder"]:::impl
        QE["query_encoder"]:::impl
        SER["serialization"]:::impl
        PAG["pagination"]:::impl
        ERR["api_error"]:::impl
        CW["client_wrapper"]:::impl
        DT["datetime_utils"]:::impl
        RN["remove_none_from_dict"]:::impl
        MP["force_multipart"]:::impl
        RO["request_options"]:::impl
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        PDM["types/*.py"]:::model
        APP_T["applications/types/*.py"]:::model
        CLU_T["clusters/types/*.py"]:::model
        JOB_T["jobs/types/*.py"]:::model
        INT_T["internal/*/types/*.py"]:::model
    end

    %% Internal (Private API) Layer
    subgraph "Internal API Layer"
        direction TB
        ICLI["internal/client"]:::impl
        subgraph "Internal Applications"
            direction TB
            IAPP_C["internal/applications/client"]:::impl
            IAPP_RC["internal/applications/raw_client"]:::impl
        end
    end

    %% External Dependencies & API
    subgraph "External"
        direction TB
        HTTPX["httpx"]:::external
        PD["pydantic"]:::external
        FERN["fern (codegen)"]:::external
        TFAPI["Truefoundry REST API"]:::external
    end

    %% Relationships
    TF -->|uses| APP_C
    ATF -->|uses async| APP_C
    TF -->|uses| CLU_C
    ATF -->|uses async| CLU_C
    TF -->|uses| JOB_C
    ATF -->|uses async| JOB_C

    APP_C -->|calls| HC
    APP_C -->|serializes via| JE
    APP_C -->|parses via| HR
    APP_RC -->|calls| HC

    HC -->|HTTP requests| HTTPX
    HTTPX -->|HTTP responses| HC
    HC -->|deserializes| PDM
    HC -->|error handling| ERR
    HC -->|pagination| PAG

    CW -.-> APP_C
    WC --> CW

    HC -->|datetime utils| DT
    HC -->|remove none| RN
    HC -->|multipart| MP
    HC -->|options| RO

    PD -->|validates models| PDM
    FERN -->|generates code| APP_C

    HC -->|connects to| TFAPI

    %% Click Events
    click TF "https://github.com/truefoundry/truefoundry-python-sdk/blob/main/src/truefoundry_sdk/client.py"
    click ATF "https://github.com/truefoundry/truefoundry-python-sdk/blob/main/src/truefoundry_sdk/base_client.py"
    click WC "https://github.com/truefoundry/truefoundry-python-sdk/blob/main/src/truefoundry_sdk/_wrapped_clients.py"
    click APP_C "https://github.com/truefoundry/truefoundry-python-sdk/blob/main/src/truefoundry_sdk/applications/client.py"
    click APP_RC "https://github.com/truefoundry/truefoundry-python-sdk/blob/main/src/truefoundry_sdk/applications/raw_client.py"
    click CLU_C "https://github.com/truefoundry/truefoundry-python-sdk/blob/main/src/truefoundry_sdk/clusters/client.py"
    click CLU_RC "https://github.com/truefoundry/truefoundry-python-sdk/blob/main/src/truefoundry_sdk/clusters/raw_client.py"
    click JOB_C "https://github.com/truefoundry/truefoundry-python-sdk/blob/main/src/truefoundry_sdk/jobs/client.py"
    click JOB_RC "https://github.com/truefoundry/truefoundry-python-sdk/blob/main/src/truefoundry_sdk/jobs/raw_client.py"
    click HC "https://github.com/truefoundry/truefoundry-python-sdk/blob/main/src/truefoundry_sdk/core/http_client.py"
    click HR "https://github.com/truefoundry/truefoundry-python-sdk/blob/main/src/truefoundry_sdk/core/http_response.py"
    click JE "https://github.com/truefoundry/truefoundry-python-sdk/blob/main/src/truefoundry_sdk/core/jsonable_encoder.py"
    click QE "https://github.com/truefoundry/truefoundry-python-sdk/blob/main/src/truefoundry_sdk/core/query_encoder.py"
    click SER "https://github.com/truefoundry/truefoundry-python-sdk/blob/main/src/truefoundry_sdk/core/serialization.py"
    click PAG "https://github.com/truefoundry/truefoundry-python-sdk/blob/main/src/truefoundry_sdk/core/pagination.py"
    click ERR "https://github.com/truefoundry/truefoundry-python-sdk/blob/main/src/truefoundry_sdk/core/api_error.py"
    click CW "https://github.com/truefoundry/truefoundry-python-sdk/blob/main/src/truefoundry_sdk/core/client_wrapper.py"
    click DT "https://github.com/truefoundry/truefoundry-python-sdk/blob/main/src/truefoundry_sdk/core/datetime_utils.py"
    click RN "https://github.com/truefoundry/truefoundry-python-sdk/blob/main/src/truefoundry_sdk/core/remove_none_from_dict.py"
    click MP "https://github.com/truefoundry/truefoundry-python-sdk/blob/main/src/truefoundry_sdk/core/force_multipart.py"
    click RO "https://github.com/truefoundry/truefoundry-python-sdk/blob/main/src/truefoundry_sdk/core/request_options.py"

    %% Styles
    classDef public fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef impl fill:#E6FFEA,stroke:#28A745,color:#28A745
    classDef model fill:#FFF8DC,stroke:#DAA520,color:#DAA520
    classDef external fill:#FFEFD5,stroke:#FF8C00,color:#FF8C00
```
