The client

Celeste v1 is namespace-first, but this page focuses on the client pattern. The client API is modality-first, meaning you choose the output type you want.

Create a client (advanced)

Use create_client when you want explicit control or reuse a configured client. This is modality-first, so you specify the output type and (optionally) the operation.

import celeste

client = celeste.create_client(
    modality="text",
    provider="openai",
    model="gpt-4o",
)

Arguments

• modality (str | Modality): The modality to use (e.g., "text", "images").
• operation (str | Operation, optional): Optional operation filter.
• provider (str | Provider, optional): The provider to use (e.g., "openai", "anthropic").
• model (str | Model, optional): Specific model to use.
• api_key (str, optional): API key override.
• auth (Authentication, optional): Custom authentication override (advanced).

Execution modes

Celeste supports three execution modes to handle different use cases:

Async (default)

Async operation methods return a complete typed output object. Best for production applications.

response = await client.generate(prompt="Hello world", temperature=0.7)
print(response.content)

Streaming (client.stream.<operation>())

Streaming returns chunks as they are generated. Best for UIs requiring real-time feedback.

stream = client.stream.generate(prompt="Count from 1 to 5")

async for chunk in stream:
    print(chunk.content, end="")

final_response = stream.output
print(final_response.content)

Sync (client.sync.<operation>())

Sync methods are blocking calls. Best for scripts, notebooks, and testing.

response = client.sync.generate(prompt="Hello world")
print(response.content)

Sync streaming is also supported:

stream = client.sync.stream.generate(prompt="Hello world")
for chunk in stream:
    print(chunk.content, end="")
print(stream.output.content)

Type Safety

Clients are generic over their Input, Output, and Parameters. This means your IDE can provide autocomplete and type checking for:

• Parameters: temperature, max_tokens, etc.
• Response: response.content, response.usage, etc.

# IDE knows this is a TextOutput (for text modality)
response = await client.generate(prompt="...")

# IDE knows this is int
tokens = response.usage.total_tokens