# parallel-web/parallel-sdk-python architecture

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

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

## Overview

##### Project Type and Purpose
- This is a Python SDK (“parallel-web”) that provides both synchronous and asynchronous clients for accessing the Parallel REST API.
- It’s a library/tool, not a standalone web application. Users import `Parallel` or `AsyncParallel`, call its methods, and under the hood HTTP requests are made via httpx, responses are parsed into typed Pydantic models.

##### File‐Structure Analysis
- Top‐Level / Project Configuration
- Packaging & metadata: pyproject.toml, README.md, LICENSE, CHANGELOG.md, api.md
- CI/CD: .github/workflows (linting, tests, publish to PyPI)
- Dev containers & IDE: .devcontainer/, .vscode/
- Scripts & automation: bin/, scripts/ (bootstrap, lint, test, release helpers)
- Source Code Layout (`src/parallel/`)
- _base_client.py, _client.py – core sync/async client implementations
- _resource.py – generic resource handling (e.g., task_run, task_group)
- _response.py – APIResponse & AsyncAPIResponse abstractions
- _models.py & types/ – Pydantic definitions for all request params and responses
- _utils/ – helpers (logging, datetime parsing, streaming, reflection)
- resources/ & types/ – namespaced API endpoints (stable vs beta)
- Tests (`tests/`) mirror resource modules to validate client behavior, request-building, response parsing, streaming, retries, timeouts

##### README Insights
- Emphasizes both sync and async clients powered by httpx
- Strong typing via Pydantic
- Support for raw/streaming responses, retries, timeouts, logging
- Extensibility: undocumented endpoints via low-level client methods

##### Main Components & Interactions (
A. User Layer
- Your Python code imports `Parallel` or `AsyncParallel` → initiates Client instance
B. Client Layer
- Sync/Async client classes (`_client.py`)
- Configuration (api_key, base_url, max_retries, timeout)
C. HTTP Layer
- httpx.Client / httpx.AsyncClient (DefaultHttpxClient)
- Retry & backoff logic (configured in client)
D. APIResource Layer
- Resource proxy objects (`client.task_run`, `client.beta.task_group`, etc.)
- Methods: create(), result(), list(), events()
E. Serialization Layer
- Body serialization: Pydantic models from `types/`
- Querystring builder (`_qs.py`)
- Header injection (API key, beta flags)
F. Network Boundary
- Outgoing HTTP requests to Parallel REST API
G. Deserialization Layer
- `_response.py`: wrap raw httpx.Response, parse JSON
- JSON → Pydantic response models (`_models.py`, `types/`)
- Optional streaming or raw access
H. Utility Layer
- Logging, compatibility shims, datetime parsing, reflection, transforms

##### Architectural Patterns and Principles
- Layered / Onion architecture: User → Client → HTTP → APIResource → Models
- Adapter pattern: httpx adapted into a generic API client interface
- Factory/Proxy: resource objects proxy calls to client methods
- Separation of concerns:
- Transport (httpx) vs serialization (Pydantic) vs business API (task_run, task_group)
- Sync vs Async share most code via base classes and compatibility modules

##### Technologies and Frameworks
- httpx (sync & async HTTP transport)
- Pydantic (typed request/response models)
- Stainless (code generation)
- nox (test automation)
- GitHub Actions (CI/CD)
- Docker dev container

##### Diagramming Recommendations
- From User → Client → HTTP → API → HTTP response → Deserializer → User
- Side‐flows for retry/backoff, streaming, raw responses
- Blue for user‐facing components (Parallel, AsyncParallel)
- Green for transport (httpx layer)
- Yellow for serialization (Pydantic models in types/)
- Gray for utilities (logging, compat)
- Clear labels: methods (create, result), data flows (JSON request/response), configuration knobs (timeout, retries)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    subgraph "User Layer"
        direction TB
        User["User Code"]:::user
    end

    %% Client Layer
    subgraph "Client Layer"
        direction TB
        BaseClient["BaseClient"]:::client
        SyncClient["Parallel / AsyncParallel"]:::client
    end

    %% HTTP Layer
    subgraph "HTTP Layer"
        direction TB
        Constants["Retry & Backoff Config"]:::config
        HttpxAdapter["DefaultHttpxClient Adapter"]:::transport
    end

    %% APIResource Layer
    subgraph "APIResource Layer"
        direction TB
        ResourceProxy["APIResource Proxy"]:::client
        StableTaskRun["resources/task_run"]:::client
        BetaTaskRun["beta/task_run"]:::client
        BetaTaskGroup["beta/task_group"]:::client
    end

    %% Serialization Layer
    subgraph "Serialization Layer"
        direction TB
        QsBuilder["Querystring Builder"]:::serialization
        PydanticModels["Pydantic Models (_models.py)"]:::serialization
        PydanticTypes["Pydantic Types (types/)"]:::serialization
    end

    %% Network Boundary
    subgraph "Network Boundary"
        direction TB
        ExternalAPI["Parallel REST API"]:::external
    end

    %% Deserialization Layer
    subgraph "Deserialization Layer"
        direction TB
        ResponseWrapper["Response Wrapper & Deserialization"]:::serialization
    end

    %% Utility Layer
    subgraph "Utility Layer"
        direction TB
        LoggingUtil["Logging"]:::utils
        DateUtil["Datetime Parsing"]:::utils
        ReflectionUtil["Reflection & Proxy Helpers"]:::utils
        SyncCompat["Sync/Async Compatibility"]:::utils
        Exceptions["Exceptions & Error Handling"]:::utils
        VersionInfo["Version Info"]:::utils
    end

    %% Connections
    User -->|"imports"| SyncClient
    SyncClient -->|"inherits/composes"| BaseClient
    BaseClient -->|"uses"| HttpxAdapter
    BaseClient -->|"reads"| Constants
    HttpxAdapter -->|"executes requests"| ExternalAPI
    Constants --> HttpxAdapter
    BaseClient -->|"creates"| ResourceProxy
    ResourceProxy --> StableTaskRun
    ResourceProxy --> BetaTaskRun
    ResourceProxy --> BetaTaskGroup
    ResourceProxy -->|"serializes request"| QsBuilder
    QsBuilder --> PydanticModels
    QsBuilder --> PydanticTypes
    HttpxAdapter -->|"returns raw response"| ResponseWrapper
    ResponseWrapper --> PydanticModels
    ResponseWrapper --> PydanticTypes
    BaseClient --> LoggingUtil
    BaseClient --> DateUtil
    BaseClient --> ReflectionUtil
    BaseClient --> SyncCompat
    BaseClient --> Exceptions
    BaseClient --> VersionInfo

    %% Click Events
    click SyncClient "https://github.com/parallel-web/parallel-sdk-python/blob/main/src/parallel/_client.py"
    click BaseClient "https://github.com/parallel-web/parallel-sdk-python/blob/main/src/parallel/_base_client.py"
    click HttpxAdapter "https://github.com/parallel-web/parallel-sdk-python/blob/main/src/parallel/_client.py"
    click Constants "https://github.com/parallel-web/parallel-sdk-python/blob/main/src/parallel/_constants.py"
    click ResourceProxy "https://github.com/parallel-web/parallel-sdk-python/blob/main/src/parallel/_resource.py"
    click StableTaskRun "https://github.com/parallel-web/parallel-sdk-python/blob/main/src/parallel/resources/task_run.py"
    click BetaTaskRun "https://github.com/parallel-web/parallel-sdk-python/blob/main/src/parallel/resources/beta/task_run.py"
    click BetaTaskGroup "https://github.com/parallel-web/parallel-sdk-python/blob/main/src/parallel/resources/beta/task_group.py"
    click PydanticModels "https://github.com/parallel-web/parallel-sdk-python/blob/main/src/parallel/_models.py"
    click PydanticTypes "https://github.com/parallel-web/parallel-sdk-python/tree/main/src/parallel/types/"
    click QsBuilder "https://github.com/parallel-web/parallel-sdk-python/blob/main/src/parallel/_qs.py"
    click ResponseWrapper "https://github.com/parallel-web/parallel-sdk-python/blob/main/src/parallel/_response.py"
    click LoggingUtil "https://github.com/parallel-web/parallel-sdk-python/blob/main/src/parallel/_utils/_logs.py"
    click DateUtil "https://github.com/parallel-web/parallel-sdk-python/blob/main/src/parallel/_utils/_datetime_parse.py"
    click ReflectionUtil "https://github.com/parallel-web/parallel-sdk-python/blob/main/src/parallel/_utils/_reflection.py"
    click SyncCompat "https://github.com/parallel-web/parallel-sdk-python/blob/main/src/parallel/_utils/_sync.py"
    click SyncCompat "https://github.com/parallel-web/parallel-sdk-python/blob/main/src/parallel/_compat.py"
    click Exceptions "https://github.com/parallel-web/parallel-sdk-python/blob/main/src/parallel/_exceptions.py"
    click VersionInfo "https://github.com/parallel-web/parallel-sdk-python/blob/main/src/parallel/_version.py"

    %% Styles
    classDef user fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef client fill:#E8F4FF,stroke:#1E4E8C,color:#1E4E8C
    classDef transport fill:#E6F9E6,stroke:#28A745,color:#28A745
    classDef serialization fill:#FFF4CC,stroke:#D4A017,color:#D4A017
    classDef utils fill:#F0F0F0,stroke:#6A6A6A,color:#333333
    classDef config fill:#FFEEE5,stroke:#D73A49,color:#D73A49
    classDef external fill:#FFFFFF,stroke-dasharray: 5 5,stroke:#999999,color:#999999
```
