casual-llm

Lightweight LLM provider abstraction with standardized message models.

Part of the "casual" ecosystem of lightweight AI tools.

Upgrading from v0.4.x? See the Migration Guide for breaking changes.

Features

• Client/Model Separation - Configure API connections once, create multiple models
• Protocol-based - Uses typing.Protocol, no inheritance required
• Multi-provider - Works with OpenAI, Anthropic (Claude), Ollama, or your custom provider
• Lightweight - Minimal dependencies (pydantic, httpx)
• Async-first - Built for modern async Python
• Type-safe - Full type hints with py.typed marker
• OpenAI-compatible - Standard message format used across the industry
• Tool calling - First-class support for function/tool calling
• Per-model usage tracking - Track token usage per model for cost monitoring
• Vision support - Send images to vision-capable models
• Streaming - Stream responses in real-time with AsyncIterator

Installation

# Core only (pydantic + httpx)
uv add casual-llm

# With specific providers
uv add casual-llm[ollama]
uv add casual-llm[openai]
uv add casual-llm[anthropic]

# With all providers
uv add casual-llm[ollama,openai,anthropic]

# Or using pip
pip install casual-llm[openai,anthropic]

Quick Start

from casual_llm import OpenAIClient, Model, UserMessage

# Create client (works with OpenAI, OpenRouter, LM Studio, etc.)
client = OpenAIClient(
    api_key="sk-...",  # or set OPENAI_API_KEY env var
    base_url="https://openrouter.ai/api/v1",  # optional, omit for OpenAI
)

# Create model
model = Model(client, "gpt-4o-mini")

# Generate response
response = await model.chat([UserMessage(content="Hello!")])
print(response.content)

More examples:

• Quick Start Guide - Ollama, Anthropic, and more
• Vision Guide - Send images to models
• Streaming Guide - Real-time responses
• Advanced Usage - Custom clients, configuration classes
• API Reference - Full API documentation
• Examples Directory - Complete working examples

Message Models

casual-llm provides OpenAI-compatible message models that work with any provider:

from casual_llm import (
    UserMessage,
    AssistantMessage,
    SystemMessage,
    ToolResultMessage,
    TextContent,
    ImageContent,
)

# System message (sets behavior)
system_msg = SystemMessage(content="You are a helpful assistant.")

# User message (simple text)
user_msg = UserMessage(content="Hello!")

# User message (multimodal - text + image)
vision_msg = UserMessage(
    content=[
        TextContent(text="What's in this image?"),
        ImageContent(source="https://example.com/image.jpg"),
    ]
)

# Assistant message (response from LLM)
assistant_msg = AssistantMessage(content="I'll help you with that.")

# Tool result message (after executing a tool)
tool_msg = ToolResultMessage(
    name="get_weather",
    tool_call_id="call_123",
    content='{"temp": 20, "condition": "sunny"}'
)

Why casual-llm?

Use casual-llm when you want:

• Lightweight, focused library (not a framework)
• Protocol-based design (no inheritance)
• Standard message models shared across your codebase
• Efficient multi-model usage with shared connections
• Simple, predictable API

Use LangChain when you need:

• Full-featured framework with chains, agents, RAG
• Massive ecosystem of integrations
• Higher-level abstractions

Part of the casual-* Ecosystem

• casual-mcp - MCP server orchestration and tool calling
• casual-llm (this library) - LLM provider abstraction
• casual-memory - Memory intelligence with conflict detection

All casual-* libraries share the same philosophy: lightweight, protocol-based, easy to use.

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Links

• GitHub: https://github.com/casualgenius/casual-llm
• PyPI: https://pypi.org/project/casual-llm/
• Issues: https://github.com/casualgenius/casual-llm/issues
• Migration Guide: MIGRATION-0.5.0.md
• casual-mcp: https://github.com/casualgenius/casual-mcp