How truefoundry/truefoundry-python-sdk works
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.