Dedalus Python Library

By default, the async client uses httpx. For improved concurrency performance, you can use aiohttp as the HTTP backend.

1. Install the extra dependency:

pip install dedalus_labs[aiohttp]

2. Instantiate the client with http_client=DefaultAioHttpClient().

import os
import asyncio
from dedalus_labs import DefaultAioHttpClient
from dedalus_labs import AsyncDedalus


async def main() -> None:
    async with AsyncDedalus(
        api_key=os.environ.get("DEDALUS_API_KEY"),  # This is the default and can be omitted
        http_client=DefaultAioHttpClient(),
    ) as client:
        chat_completion = await client.chat.completions.create(
            model="openai/gpt-5-nano",
            messages=[
                {
                    "role": "system",
                    "content": "You are Stephen Dedalus. Respond in morose Joycean malaise.",
                },
                {
                    "role": "user",
                    "content": "Hello, how are you today?",
                },
            ],
        )
        print(chat_completion.id)


asyncio.run(main())

All errors in the library inherit from dedalus_labs.APIError.

• Connection Errors: If the library cannot connect to the API (network issues, timeouts), it raises a subclass of dedalus_labs.APIConnectionError.
• Status Errors: If the API returns a non-success status code (4xx or 5xx), it raises a subclass of dedalus_labs.APIStatusError. These objects contain status_code and response properties.
• Timeouts: If a request times out, an APITimeoutError is thrown.

import dedalus_labs
from dedalus_labs import Dedalus

client = Dedalus()

try:
    client.chat.completions.create(
        model="openai/gpt-5-nano",
        messages=[{"role": "user", "content": "Hello"}],
    )
except dedalus_labs.APIConnectionError as e:
    print("The server could not be reached")
except dedalus_labs.RateLimitError as e:
    print("A 429 status code was received; we should back off a bit.")
except dedalus_labs.APIStatusError as e:
    print(f"Status: {e.status_code}")

The ChatCompletion object is an OpenAI-compatible response extended with Dedalus-specific features for server-side tool execution tracking, MCP (Model Context Protocol) error reporting, and session management.

Key Dedalus extensions include:

• correlation_id: A stable session ID used for cross-turn handoff. Echo this ID in your next request to resume server-side execution state.
• pending_tools: A list of PendingTool objects representing tool calls that the client must execute. These include id, name, arguments, and an optional dependencies list for ordering.
• mcp_server_errors: A dictionary of MCPServerErrors keyed by server name, providing error messages, codes, and recommendations for MCP server failures.
• mcp_tool_results: Detailed execution logs (inputs, outputs, timing) for MCP tools.
• server_results: Outputs from completed server-side tools, keyed by call ID.
• service_tier: Indicates the processing mode used (e.g., auto, default, flex, scale, priority).
• turns_consumed: The number of internal LLM calls made during the request.
• tools_executed: A list of names of tools that were executed entirely on the server.

When performing transcription tasks, the API returns one of two primary response structures, which can be unified under the TranscriptionCreateResponse type alias:

1. CreateTranscriptionResponseJSON (Standard): A lightweight response containing the transcribed text, optional logprobs (for specific models like gpt-4o-transcribe), and usage statistics.
2. CreateTranscriptionResponseVerboseJSON (Verbose): A detailed response containing the full text, language, duration, and optional granular breakdowns including words (with timestamps), segments (with metadata like avg_logprob and no_speech_prob), and usage statistics.

Use the verbose response when you need precise timing for words or segments, or when you need to analyze the quality of the transcription via logprobs and compression ratios.

from typing import Union
from dedalus_labs.types.audio.transcription_create_response import TranscriptionCreateResponse

# TranscriptionCreateResponse will be either a Verbose or Standard JSON response
response: TranscriptionCreateResponse = await client.audio.transcriptions.create(...)