[!IMPORTANT] Work in progress - internal code refactor.

📦 Description

A small toolkit for generative models, with practical conveniences built in: such as caching, fast imports, syntactic sugars, opinionated architecture, curated providers, and more.

• Message classes with type-safe structured output generics, auto validation (chat)
• Modular: Easily write your implementations or modify existing ones.
• Minimal: Avoids the complexity and commitment of a full framework.

📦 Usage

Simply add the delusion PyPI package to your project and use it:

[project]
dependencies = ["delusion"]

Chat

from delusion.chat.router.ollamax import Ollama
from pydantic import BaseModel, Field

class Country(BaseModel):
    name: str
    capital: str
    languages: set[str] = Field(
        description="Officially recognized languages"
    )

chat = Ollama().serve()
chat.gemma4("e2b").pull()
chat.send("Tell me about Canada, its capital and spoken languages.")

# Your linter should properly point to the class
canada = chat.generate(schema=Country)
print(canada.model)

assert (canada.model.name == "Canada")
assert (canada.model.capital == "Ottawa")
assert (canada.model.languages == {"English", "French"})

📦 Standards

In an effort to minimize xkcd 927, Delusion only introduces abstractions that provide clear value or represent shared semantics across providers, using provider-native packages whenever available.

For example, the Options class for ollama models shall only apply to itself:

import ollama

local = Ollama(model="gemma4:e2b")
cloud = OpenAI(model="gpt-whatever")

isinstance(local.options, ollama.Options) # True
isinstance(cloud.options, ollama.Options) # False

Although both support .temperature = 0.0, the intended use is:

# Individual settings
if os.getenv("PRODUCTION", None):
    chat = OpenAI(model=...)
    chat.options.temperature = 0.0
else:
    chat = Ollama(model=...)
    chat.options.temperature = 0.0

# Shared interface
chat.send(...)
chat.generate(schema=...)

Same for models: rather than over-abstracting capabilities, quantization, names, variants, and other provider-specific details, some code duplication is natural to keep it minimal and decoupled.

Conversely, Message[T] is abstracted because it represents a common semantic across providers.