Delusion

✨ The missing conveniences in generative models ✨

📦 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.option.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().cache().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"})

Audio

Example using audio.cpp:

from delusion.audio.cpp import AudioCPP, OmniVoice

# No PyTorch or ONNX required
audio = AudioCPP(
    model=OmniVoice(quant="q8_0").download()
)

# Uses NamedTemporaryFile internally
speak = audio.tts(text="お水はもう一杯もらえますか")
Path("output.wav").write_bytes(speak.wav)

📦 Standards

In an effort to minimize xkcd 927, Delusion only introduces abstractions that provide clear value or represent shared semantics across providers, proxying or extending 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.