freemodel-claude 0.2.0

Lightweight client for FreeModel's Claude endpoint with retry logic, graceful error handling, and extended thinking support.

freemodel-claude

Lightweight Python client for FreeModel's Claude endpoint. Use Anthropic Claude models (Opus, Sonnet, Haiku) with just a FreeModel API key.

Install

pip install freemodel-claude

Quick start

from freemodel_claude import ClaudeClient

client = ClaudeClient("your-api-key-here")

# Simple ask
response = client.ask("What is 2+2?")
print(response.text)  # "4"

# Pick a model
response = client.ask("Write a haiku", model="claude-opus-4-8")
print(response.text)

# Streaming
for chunk in client.stream("Tell me a story"):
    print(chunk, end="", flush=True)

# System prompt
response = client.ask("Debug this", system="You are a senior Python developer.")

# Full metadata
response = client.ask("Explain quantum computing")
print(response.text)
print(response.usage)     # token counts, model, stop reason

Models

Model	Description
claude-opus-4-8	Opus 4.8 — most capable
claude-opus-4-7	Opus 4.7
claude-sonnet-4-6	Sonnet 4.6 — balanced (default)
claude-opus-4-6	Opus 4.6
claude-haiku-4-5-20251001	Haiku 4.5 — fastest

client.models()  # tuple of available model names

Invalid model names raise ValueError.

Thinking

Extended thinking is enabled by default (thinking_budget=4095). The upstream API redacts thinking output — response.thinking will always be empty, but response.usage.thinking_tokens reports the count.

Disable thinking to save tokens:

response = client.ask("Hi", thinking_budget=None)

Error handling

All errors raise subclasses of FreeModelError:

Exception	When
AuthError	Invalid API key (401/403)
RateLimitError	Rate limited (429)
APIError	Other HTTP errors (status + body)
ConnectionError	Network failure (timeout, DNS, etc.)

from freemodel_claude import ClaudeClient, AuthError, RateLimitError

client = ClaudeClient("bad-key")
try:
    client.ask("Hi")
except AuthError:
    print("Invalid key")
except RateLimitError:
    print("Slow down")

Context manager

Reuses the underlying HTTP connection across requests:

with ClaudeClient("your-api-key") as client:
    r1 = client.ask("Hello")
    r2 = client.ask("Goodbye")

API key

Get one at freemodel.dev. Pass it to the constructor or set FREEMODEL_API_KEY:

import os
client = ClaudeClient(os.environ["FREEMODEL_API_KEY"])

Requirements

• Python >= 3.10
• httpx >= 0.27