Skip to main content

Explore Celeste

Our approach
Explore the building blocks

01 / The operation

One call.
Reusable parts.

Celeste separates what you ask a model to do from how its provider receives the request.

Follow a text request through the SDK. Each layer has a specific job.

The public interface
Your application
import celeste

response = await celeste.text.generate(
    "Explain an eclipse.",
    model="llama-3.3-70b-versatile",
    max_tokens=1024,
)

print(response.content)
Groq · Text generation
Typed inputTextInput TextOutput

Async Python · Set GROQ_API_KEY

02 / The parameters

One name.
The right format.

Parameter mappers translate your arguments into the fields each API expects.

Declared model limits are checked before the request. Capabilities and supported parameters still depend on the model.

The parameter system
In your Celeste callmax_tokens = 1024
GroqChat Completions API
"max_tokens": 1024View mapping for Groq
OpenAIResponses API
"max_output_tokens": 1024View mapping for OpenAI

Same argument. Two API request fields.

03 / The protocol

One protocol.
Your endpoint.

Set protocol and base_url to connect to any API that follows that format.

Use the endpoint’s own model ID, even outside Celeste’s catalogue. Text supports Chat Completions and OpenResponses.

The compatible API interface
Local server
Your gateway
Hosted API
Connect a compatible API
response = await celeste.text.generate(
    "Explain an eclipse.",
    model="your-model",
    protocol=celeste.Protocol.CHATCOMPLETIONS,
    base_url="https://api.example.com",
    api_key="your-api-key",
)

Example values · Use your endpoint, model ID and key.

04 / The transport

Share the
transport.

Celeste’s HTTP client sends the prepared request to the endpoint. Connections, timeouts, and transient retries live in one place.

The API response is parsed into typed content and usage. Your application decides what happens next.

The transport implementation
Your processAPI endpoint
Shared HTTP clientTransport
response = await self.http_client.post(
    self._build_url(endpoint),
    headers=headers,
    json_body=request_body,
)
Back in your applicationTextOutputresponse.content
response.usage

Request excerpt from the Chat Completions protocol client

Inside the implementation

How a client
fits together.

A provider client combines its API implementation with a modality. Parameter mappers and a model catalogue complete the integration.

API

Anthropic Messages

Endpoints, authentication headers, request and response format.

Modality

Text

Operations, typed inputs, content, usage, and streaming.

The composed clientClass signature
class AnthropicTextClient(
    AnthropicMessagesMixin,
    TextClient,
):
Read the full implementation

Contributing to Celeste

Add a built-in provider.

A compatible endpoint already works with the public call above. Built-in integrations add a model catalogue, credential handling, and provider-specific behavior.

To contribute one, start with a protocol or an API template. Connect it to a modality, declare the models, and test the contract.

The contribution guide

Extend a protocol client

Reuse its request, response, and streaming implementation. Add the provider’s defaults and override its differences.

Explore shared protocols

Implement a provider API

Use the API templates for its wire format and the modality templates to connect it to the SDK.

API templates Modality templates

Open source · MIT licensed

Build on the SDK.

Use the models you need. Keep orchestration, tool execution, and application state in your own code.

Start building Explore the source