Python — full guide
Everything you need to integrate Meridian into your Python application — from pip install to production-grade error handling with streaming and tool calling.
Installation
Install the Meridian SDK via pip. Requires Python 3.9 or later.
The SDK pulls in httpx and pydantic as dependencies. For async streaming support, install with the optional [stream] extra.
Environment Setup
Set your API key as an environment variable. Never hardcode credentials.
Initialize the client. It reads MERIDIAN_API_KEY automatically.
client = Meridian()
You can also pass the key explicitly: Meridian(api_key="..."). The client is thread-safe and designed to be reused across requests.
First API Call
Send a completion request to the Meridian API. The response contains the model output and usage metadata.
client = Meridian()
response = client.completions.create(
model="meridian-pro",
messages=[
{role: "user", content: "Explain quantum entanglement in one sentence."}
]
)
print(response.choices[0].message.content)
The response object includes usage.prompt_tokens, usage.completion_tokens, and id for tracing.
Streaming Responses
Enable streaming to receive tokens as they are generated. Ideal for chat interfaces and real-time output.
model="meridian-pro",
messages=[{role: "user", content: "Write a haiku about recursion."}],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
For async streaming, use AsyncMeridian with async for. The async client requires the [stream] extra.
Tool Calling
Define tools as JSON schemas. Meridian will decide when to invoke them and return structured arguments.
{
type: "function",
function: {
name: "get_weather",
description: "Get current weather for a city",
parameters: {
type: "object",
properties: {
city: {type: "string"}
},
required: ["city"]
}
}
}
]
response = client.completions.create(
model="meridian-pro",
messages=[{role: "user", content: "What's the weather in Tokyo?"}],
tools=tools
)
When the model returns finish_reason: "tool_calls", extract arguments from message.tool_calls[0].function.arguments, execute your function, and feed the result back in a message with role: "tool".
Error Handling
The SDK raises typed exceptions. Catch them to handle rate limits, auth failures, and server errors gracefully.
from meridian.exceptions import (
RateLimitError,
AuthenticationError,
APIError
)
try:
response = client.completions.create(
model="meridian-pro",
messages=[{role: "user", content: "Hello"}]
)
except RateLimitError as e:
print(f"Rate limited. Retry after {e.retry_after} seconds.")
except AuthenticationError:
print("Invalid API key. Check MERIDIAN_API_KEY.")
except APIError as e:
print(f"API error {e.status_code}: {e.message}")
For production, implement exponential backoff with jitter on RateLimitError. The SDK includes a built-in retry helper: client.with_retry(max_retries=3).
Ready to build? Browse the full API reference →