# langchain-ai/langsmith-python architecture

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

- Interactive diagram: https://gitdiagram.com/langchain-ai/langsmith-python
- Repository: https://github.com/langchain-ai/langsmith-python

## Overview

LangSmith’s Python SDK records and manages traces from LLM applications, sends them to the LangSmith platform, and supports follow-on dataset and evaluation workflows. The graph also preserves documented tracing integrations and the sandbox API. The README establishes the main workflow; source-index references and excerpts support the client, model, and transport layers. Some capability modules were not sampled, so their internal calls are not asserted.

Main entry points: [`src/langsmith/client.py`](https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/client.py) (API client), [`src/langsmith/_base_client.py`](https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/_base_client.py) (HTTP API layer), [`src/langsmith/run_helpers.py`](https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/run_helpers.py) (Trace decorator), [`src/langsmith/run_trees.py`](https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/run_trees.py) (Run tree)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tracing["Tracing"]
  node_traceable["Trace decorator<br/>[run_helpers.py]"]
  node_run_tree["Run tree<br/>[run_trees.py]"]
  node_trace_client["Trace client<br/>[client.py]"]
  node_trace_data["Trace schemas<br/>[schemas.py]"]
  node_addressing["Trace addressing<br/>[address.py]"]
end

subgraph group_platform["Platform API"]
  node_sdk_client["API client<br/>[client.py]"]
  node_resources["API resources"]
  node_prompt_webhooks["Prompt webhooks<br/>[prompt_webhooks.py]"]
  node_sandbox["Sandbox clients<br/>[_client.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_datasets["Datasets and runs<br/>[datasets.py]"]
  node_evaluation_sdk["Evaluation runners"]
  node_online_evaluators["Online evaluators"]
end

subgraph group_integrations["Integrations"]
  node_wrappers["LLM wrappers"]
  node_integrations["Agent integrations"]
  node_otel["OTel exporter<br/>[_otel_exporter.py]"]
end

subgraph group_runtime["SDK Runtime"]
  node_base_client["HTTP API layer<br/>[_base_client.py]"]
  node_http_backend["HTTP backend<br/>[_httpx.py]"]
  node_models["Model serialization<br/>[_models.py]"]
  node_types["Request types<br/>[_types.py]"]
  node_compat["Compatibility utilities<br/>[_compat.py]"]
  node_uuid["Run identifiers<br/>[uuid.py]"]
end

node_developer(("Application developer"))
node_llm_app["LLM application"]
node_langsmith_service["LangSmith platform"]

node_developer -->|"runs"| node_llm_app
node_llm_app -->|"wraps LLM calls"| node_wrappers
node_llm_app -->|"decorates functions"| node_traceable
node_traceable -->|"manages traces"| node_run_tree
node_run_tree -->|"posts runs"| node_trace_client
node_trace_client -->|"sends traces"| node_sdk_client
node_sdk_client -->|"calls API"| node_langsmith_service
node_sdk_client -->|"uses HTTP layer"| node_base_client
node_base_client -->|"uses backend"| node_http_backend
node_base_client -->|"serializes responses"| node_models
node_base_client -->|"uses request types"| node_types
node_models -->|"uses compatibility helpers"| node_compat
node_trace_client -->|"uses schemas"| node_trace_data
node_trace_client -->|"resolves trace projects"| node_addressing
node_trace_client -->|"uses identifiers"| node_uuid
node_sdk_client -.->|"exposes resources"| node_resources
node_sdk_client -.->|"manages webhooks"| node_prompt_webhooks
node_sdk_client -.->|"manages sandboxes"| node_sandbox
node_sdk_client -->|"creates datasets"| node_datasets
node_datasets -.->|"feeds evaluation"| node_evaluation_sdk
node_sdk_client -.->|"manages evaluators"| node_online_evaluators
node_integrations -.->|"instruments agents"| node_traceable
node_otel -.->|"exports telemetry"| node_langsmith_service

click node_traceable "https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/run_helpers.py"
click node_run_tree "https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/run_trees.py"
click node_trace_client "https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/client.py"
click node_trace_data "https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/schemas.py"
click node_addressing "https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/address.py"
click node_sdk_client "https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/client.py"
click node_resources "https://github.com/langchain-ai/langsmith-python/tree/main/src/langsmith/resources"
click node_prompt_webhooks "https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/resources/prompt_webhooks.py"
click node_sandbox "https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/sandbox/_client.py"
click node_datasets "https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/resources/datasets/datasets.py"
click node_evaluation_sdk "https://github.com/langchain-ai/langsmith-python/tree/main/src/langsmith/evaluation"
click node_online_evaluators "https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/resources/online_evaluators.py"
click node_wrappers "https://github.com/langchain-ai/langsmith-python/tree/main/src/langsmith/wrappers"
click node_integrations "https://github.com/langchain-ai/langsmith-python/tree/main/src/langsmith/integrations"
click node_otel "https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/_internal/otel/_otel_exporter.py"
click node_base_client "https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/_base_client.py"
click node_http_backend "https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/_httpx.py"
click node_models "https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/_models.py"
click node_types "https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/_types.py"
click node_compat "https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/_compat.py"
click node_uuid "https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/uuid.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_traceable,node_run_tree,node_trace_client,node_trace_data,node_addressing toneBlue
class node_sdk_client,node_resources,node_prompt_webhooks,node_sandbox toneAmber
class node_datasets,node_evaluation_sdk,node_online_evaluators toneMint
class node_wrappers,node_integrations,node_otel toneRose
class node_base_client,node_http_backend,node_models,node_types,node_compat,node_uuid,node_developer,node_llm_app,node_langsmith_service toneIndigo
```

## Components

### Tracing

- [Trace decorator](https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/run_helpers.py): `src/langsmith/run_helpers.py`
- [Run tree](https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/run_trees.py): `src/langsmith/run_trees.py`
- [Trace client](https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/client.py): `src/langsmith/client.py`
- [Trace schemas](https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/schemas.py): `src/langsmith/schemas.py`
- [Trace addressing](https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/address.py): `src/langsmith/address.py`

### Platform API

- [API client](https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/client.py): `src/langsmith/client.py`
- [API resources](https://github.com/langchain-ai/langsmith-python/tree/main/src/langsmith/resources): `src/langsmith/resources`
- [Prompt webhooks](https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/resources/prompt_webhooks.py): `src/langsmith/resources/prompt_webhooks.py`
- [Sandbox clients](https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/sandbox/_client.py): `src/langsmith/sandbox/_client.py`

### Evaluation

- [Datasets and runs](https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/resources/datasets/datasets.py): `src/langsmith/resources/datasets/datasets.py`
- [Evaluation runners](https://github.com/langchain-ai/langsmith-python/tree/main/src/langsmith/evaluation): `src/langsmith/evaluation`
- [Online evaluators](https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/resources/online_evaluators.py): `src/langsmith/resources/online_evaluators.py`

### Integrations

- [LLM wrappers](https://github.com/langchain-ai/langsmith-python/tree/main/src/langsmith/wrappers): `src/langsmith/wrappers`
- [Agent integrations](https://github.com/langchain-ai/langsmith-python/tree/main/src/langsmith/integrations): `src/langsmith/integrations`
- [OTel exporter](https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/_internal/otel/_otel_exporter.py): `src/langsmith/_internal/otel/_otel_exporter.py`

### SDK Runtime

- [HTTP API layer](https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/_base_client.py): `src/langsmith/_base_client.py`
- [HTTP backend](https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/_httpx.py): `src/langsmith/_httpx.py`
- [Model serialization](https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/_models.py): `src/langsmith/_models.py`
- [Request types](https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/_types.py): `src/langsmith/_types.py`
- [Compatibility utilities](https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/_compat.py): `src/langsmith/_compat.py`
- [Run identifiers](https://github.com/langchain-ai/langsmith-python/blob/main/src/langsmith/uuid.py): `src/langsmith/uuid.py`

### Other components

- **Application developer**
- **LLM application**
- **LangSmith platform**

## Connections

- Application developer → LLM application: runs
- LLM application → LLM wrappers: wraps LLM calls
- LLM application → Trace decorator: decorates functions
- Trace decorator → Run tree: manages traces (evidence: `src/langsmith/run_helpers.py`)
- Run tree → Trace client: posts runs
- Trace client → API client: sends traces (evidence: `src/langsmith/client.py`)
- API client → LangSmith platform: calls API
- API client → HTTP API layer: uses HTTP layer (evidence: `src/langsmith/client.py`)
- HTTP API layer → HTTP backend: uses backend (evidence: `src/langsmith/_base_client.py`)
- HTTP API layer → Model serialization: serializes responses (evidence: `src/langsmith/_base_client.py`)
- HTTP API layer → Request types: uses request types (evidence: `src/langsmith/_base_client.py`)
- Model serialization → Compatibility utilities: uses compatibility helpers (evidence: `src/langsmith/_models.py`)
- Trace client → Trace schemas: uses schemas (evidence: `src/langsmith/client.py`)
- Trace client → Trace addressing: resolves trace projects (evidence: `src/langsmith/client.py`)
- Trace client → Run identifiers: uses identifiers (evidence: `src/langsmith/client.py`)
- API client → API resources: exposes resources (evidence: `src/langsmith/client.py`)
- API client → Prompt webhooks: manages webhooks
- API client → Sandbox clients: manages sandboxes (evidence: `src/langsmith/sandbox/_client.py`)
- API client → Datasets and runs: creates datasets (evidence: `src/langsmith/client.py`)
- Datasets and runs → Evaluation runners: feeds evaluation
- API client → Online evaluators: manages evaluators (evidence: `src/langsmith/client.py`)
- Agent integrations → Trace decorator: instruments agents (evidence: `src/langsmith/integrations/claude_agent_sdk/_client.py`)
- OTel exporter → LangSmith platform: exports telemetry
