Maniac Python SDK

The official Python client for the Maniac Inference Gateway API — an OpenAI-compatible inference gateway with telemetry, containers, evaluation, and optimization.

Installation

pip install maniac

Quick Start

from maniac import Maniac

client = Maniac()  # uses MANIAC_API_KEY env var

completion = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(completion["choices"][0]["message"]["content"])

Chat Completions

Create a completion

completion = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "What is the capital of France?"}],
)

maniac chat completions create \
  --model openai/gpt-4o \
  --messages '[{"role": "user", "content": "What is the capital of France?"}]'

Stream a completion

for chunk in client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Write a haiku."}],
    stream=True,
):
    print(chunk, end="", flush=True)

maniac chat completions create \
  --model openai/gpt-4o \
  --messages '[{"role": "user", "content": "Write a haiku."}]' \
  --stream

List completions

completions = client.chat.completions.list(limit=10, container="my-container")

maniac chat completions list --limit 10 --container my-container

Retrieve a completion

completion = client.chat.completions.retrieve("completion-id")

maniac chat completions retrieve completion-id

Register examples

client.chat.completions.register(
    container="my-container",
    items=[
        {
            "input": {
                "model": "openai/gpt-4o",
                "messages": [{"role": "user", "content": "Hi"}],
            },
            "output": {
                "choices": [{"message": {"role": "assistant", "content": "Hello!"}}],
            },
        }
    ],
)

maniac chat completions register \
  --container my-container \
  --items '[{"input": {"model": "openai/gpt-4o", "messages": [{"role": "user", "content": "Hi"}]}, "output": {"choices": [{"message": {"role": "assistant", "content": "Hello!"}}]}}]'

Containers

Create a container

container = client.containers.create(
    label="my-container",
    initial_model="openai/gpt-4o",
)

maniac containers create --label my-container --initial-model openai/gpt-4o

List containers

containers = client.containers.list()

maniac containers list

Retrieve a container

container = client.containers.retrieve("my-container")

maniac containers retrieve my-container

Delete a container

client.containers.delete("my-container")

maniac containers delete my-container

Models

List models

models = client.models.list()

maniac models list

Add a model to a container

client.models.add(
    container="my-container",
    model="anthropic/claude-sonnet-4.5",
    slug="claude",
)

maniac models add \
  --container my-container \
  --model anthropic/claude-sonnet-4.5 \
  --slug claude

Files

Upload a file

file = client.files.create(file="data.jsonl", purpose="fine-tune")

maniac files create data.jsonl --purpose fine-tune

List files

files = client.files.list()

maniac files list

Retrieve file metadata

file = client.files.retrieve("file-id")

maniac files retrieve file-id

Download file content

content = client.files.content("file-id")

maniac files content file-id

Delete a file

client.files.delete("file-id")

maniac files delete file-id

Evaluators

Create an evaluator

evaluator = client.evaluators.create(
    type="judge",
    model="openai/gpt-4o",
    name="quality-judge",
    prompt="Rate the quality of the response from 1-10.",
    container="my-container",
)

maniac evaluators create \
  --type judge \
  --model openai/gpt-4o \
  --name quality-judge \
  --prompt "Rate the quality of the response from 1-10." \
  --container my-container

List evaluators

evaluators = client.evaluators.list(container="my-container")

maniac evaluators list --container my-container

Retrieve an evaluator

evaluator = client.evaluators.retrieve("evaluator-id")

maniac evaluators retrieve evaluator-id

Update an evaluator

client.evaluators.update("evaluator-id", prompt="New prompt text.")

maniac evaluators update evaluator-id --prompt "New prompt text."

Delete an evaluator

client.evaluators.delete("evaluator-id")

maniac evaluators delete evaluator-id

Evaluation Runs

Create an evaluation run

run = client.evaluation.runs.create(
    container="my-container",
    evaluators=["evaluator-id"],
)

maniac evaluation runs create \
  --container my-container \
  --evaluators '["evaluator-id"]'

List evaluation runs

runs = client.evaluation.runs.list(container="my-container")

maniac evaluation runs list --container my-container

Retrieve an evaluation run

run = client.evaluation.runs.retrieve("run-id")

maniac evaluation runs retrieve run-id

Datasets

Create a dataset

dataset = client.datasets.create(
    name="my-dataset",
    container="my-container",
    size=100,
)

maniac datasets create \
  --name my-dataset \
  --container my-container \
  --size 100

List datasets

datasets = client.datasets.list(container="my-container")

maniac datasets list --container my-container

Retrieve a dataset

dataset = client.datasets.retrieve("dataset-id")

maniac datasets retrieve dataset-id

Optimization Runs

Create an optimization run

run = client.optimization.runs.create(
    container="my-container",
    base_models=["openai/gpt-4o"],
    evals=["evaluator-id"],
    methods=[{"type": "sft"}],
)

maniac optimization runs create \
  --container my-container \
  --base-models '["openai/gpt-4o"]' \
  --evals '["evaluator-id"]' \
  --methods '[{"type": "sft"}]'

OpenAI Compatibility

Maniac's inference endpoint is fully compatible with the OpenAI client. Point it at https://platform.maniac.ai/api/v1 and prefix your container label with maniac::

from openai import OpenAI

client = OpenAI(
    base_url="https://platform.maniac.ai/api/v1",
    api_key=os.getenv("MANIAC_API_KEY"),
)

response = client.chat.completions.create(
    model="maniac:my-container",
    messages=[{"role": "user", "content": "Hello!"}],
)

Async Usage

from maniac import AsyncManiac

async def main():
    async with AsyncManiac() as client:
        completion = await client.chat.completions.create(
            model="openai/gpt-4o",
            messages=[{"role": "user", "content": "Hello!"}],
        )
        print(completion["choices"][0]["message"]["content"])

        # Streaming
        async for chunk in await client.chat.completions.create(
            model="openai/gpt-4o",
            messages=[{"role": "user", "content": "Write a poem."}],
            stream=True,
        ):
            print(chunk, end="", flush=True)

Error Handling

from maniac import Maniac, AuthenticationError, RateLimitError, NotFoundError

client = Maniac()

try:
    client.containers.retrieve("nonexistent")
except NotFoundError:
    print("Container not found")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")

All exceptions inherit from ManiacError. The full hierarchy:

• ManiacError
  • APIError — generic API error (has status_code and code)
  • AuthenticationError — 401/403
  • RateLimitError — 429 (has retry_after)
  • NotFoundError — 404
  • BadRequestError — 400/422
  • APIConnectionError — network failure

CLI Global Options

Every command supports --json for raw JSON output and --api-key / --base-url overrides:

maniac --api-key sk-... containers list --json

Run maniac --help or maniac <command> --help for full option details.