Open-source foundations · Python 3.11+

Build AI systems
you can reason about.

LuckyBrain gives you small, typed building blocks for models, retrieval, and agents—without hiding the seams or pretending the hard parts are solved.

Get started Explore the API

Early-stage project · Clear about what works today

quickstart.pyPY
from luckybrain.core.models import (
    OpenaiBrain,
)

brain = OpenaiBrain(
    model="gpt-4o-mini",
    system_prompt="Be clear and precise.",
)

answer = brain.think(
    "Explain vector search."
)
print(answer)
Small surface area.Real Python.No hidden pipeline.
Provider-awareOpenAI and Groq clients
ComposableTyped extension contracts
InspectableExplicit boundaries and limits
Honest by designAlpha, with scope clearly stated

A toolkit, not a black box

Use the pieces you need.
Keep control of the rest.

Start with the supported interfaces. Add your own providers, stores, and orchestration when your application calls for them.

01 / MODELS

Talk to chat models

Use synchronous OpenAI and Groq clients with explicit prompts, options, and conversation history.

Read the model guide 02 / CONTRACTS

Build against interfaces

Implement small async protocols for retrieval, reranking, generation, and agent tools.

Explore the contracts 03 / SEARCH

Improve a query

Optionally rewrite or expand a search query through a chat model you already provide.

See the query guide

A useful distinction

Foundations today.
Room to grow tomorrow.

LuckyBrain is an alpha package—not a finished RAG platform. Its contracts are extension points, not built-in databases or orchestration. Open the docs to see what is implemented, how to use it, and what you still own.

Read production-readiness notes

Build in the open

Have an idea or a better way?

Read the contribution guide, open a focused issue, or help make the interfaces clearer.

Connect with the project