The langsmith.schemas module contains Pydantic models and type definitions for LangSmith data structures.
Core types
Run
Represents a single execution trace (span).
from langsmith.schemas import Run
# Accessing run properties
def my_evaluator(run: Run, example):
print(f"Run ID: {run.id}")
print(f"Name: {run.name}")
print(f"Type: {run.run_type}")
print(f"Inputs: {run.inputs}")
print(f"Outputs: {run.outputs}")
print(f"Error: {run.error}")
print(f"Start: {run.start_time}")
print(f"End: {run.end_time}")
Unique identifier for the run.
Name of the run/operation.
Type: "llm", "chain", "tool", "retriever", or "prompt".
Output data from the run.
Error message if the run failed.
ID of the parent run for nested traces.
Hierarchical position in trace tree.
Tags attached to the run.
Metadata attached to the run.
Example
Represents a dataset example (record).
from langsmith.schemas import Example
def my_evaluator(run, example: Example):
print(f"Example ID: {example.id}")
print(f"Dataset: {example.dataset_id}")
print(f"Inputs: {example.inputs}")
print(f"Outputs: {example.outputs}") # Ground truth
print(f"Metadata: {example.metadata}")
Unique identifier for the example.
ID of the dataset this example belongs to.
Input data for the example.
Expected output data (ground truth).
When the example was created.
When the example was last modified.
ID of the run this example was created from.
URL to view the example in the LangSmith UI.
Dataset
Represents a dataset collection.
from langsmith.schemas import Dataset
client = Client()
dataset: Dataset = client.read_dataset(dataset_name="my-dataset")
print(f"Name: {dataset.name}")
print(f"ID: {dataset.id}")
print(f"Examples: {dataset.example_count}")
print(f"URL: {dataset.url}")
Unique identifier for the dataset.
Description of the dataset.
Type of data: "kv", "llm", or "chat".
Number of examples in the dataset.
When the dataset was created.
When the dataset was last modified.
URL to view the dataset in the LangSmith UI.
Create/Update types
ExampleCreate
Used for creating new examples.
from langsmith.schemas import ExampleCreate
example = ExampleCreate(
inputs={"question": "What is LangSmith?"},
outputs={"answer": "A platform for LLM development"},
metadata={"source": "docs"},
split=["train"]
)
client.create_example(
dataset_id=dataset.id,
**example.dict()
)
Dataset splits (e.g., "train", "test").
attachments
dict[str, Attachment] | None
File attachments.
Custom ID for the example.
ExampleUpdate
Used for updating existing examples.
from langsmith.schemas import ExampleUpdate
update = ExampleUpdate(
id=example.id,
inputs={"question": "Updated question"},
metadata={"revised": True}
)
client.update_example(**update.dict())
Attachment handling
Attachment
For uploading files with examples or runs.
from langsmith.schemas import Attachment
from pathlib import Path
# From bytes
attachment = Attachment(
mime_type="text/plain",
data=b"file contents"
)
# From file path
attachment = Attachment(
mime_type="image/png",
data=Path("image.png")
)
# Use in examples
example = client.create_example(
dataset_id=dataset.id,
inputs={"query": "Analyze this image"},
attachments={
"input_image": attachment
}
)
MIME type of the attachment (e.g., "text/plain", "image/png").
File contents as bytes or path to file.
Enums
DataType
Dataset types.
from langsmith.schemas import DataType
DataType.kv # Key-value pairs
DataType.llm # LLM completion format
DataType.chat # Chat message format
Score types
SCORE_TYPE
Valid score types for feedback.
from langsmith.schemas import SCORE_TYPE
# Union of: StrictBool | StrictInt | StrictFloat | None
score: SCORE_TYPE = 0.95
score: SCORE_TYPE = 1
score: SCORE_TYPE = True
VALUE_TYPE
Valid value types for non-numeric feedback.
from langsmith.schemas import VALUE_TYPE
# Union of: dict | str | StrictBool | StrictInt | StrictFloat | None
value: VALUE_TYPE = "good"
value: VALUE_TYPE = {"category": "excellent", "details": "..."}
from langsmith.schemas import UsageMetadata, InputTokenDetails
usage = UsageMetadata(
input_tokens=100,
output_tokens=50,
total_tokens=150,
input_token_details=InputTokenDetails(
cache_read=20
)
)
Total tokens (input + output).
Detailed breakdown of input tokens (cache hits, etc.).
output_token_details
OutputTokenDetails | None
Detailed breakdown of output tokens (reasoning tokens, etc.).
Working with schemas
Type annotations
from langsmith.schemas import Run, Example
from langsmith.evaluation import EvaluationResult
def my_evaluator(run: Run, example: Example | None) -> EvaluationResult:
"""Type-safe evaluator function."""
prediction = run.outputs.get("answer")
reference = example.outputs.get("answer") if example else None
return EvaluationResult(
key="accuracy",
score=1.0 if prediction == reference else 0.0
)
Serialization
All schema types are Pydantic models and support standard serialization:
from langsmith import Client
client = Client()
dataset = client.read_dataset(dataset_name="my-dataset")
# To dict
data = dataset.dict()
# To JSON
import json
json_str = dataset.json()
parsed = json.loads(json_str)
# From dict
from langsmith.schemas import Dataset
dataset = Dataset(**data)