API reference

This reference is generated from the Python source on every documentation build. Signatures and source docstrings stay connected to the implementation; use the guides for complete examples, parameter explanations, and operational advice.

Public data models

luckybrain.core.models.Document(id: str, content: str, metadata: Mapping[str, object] = dict()) dataclass

A source document or passage with stable identity and metadata.

luckybrain.core.models.RetrievalResult(document: Document, score: float) dataclass

A document returned by retrieval with its provider-defined relevance score.

Chat models

luckybrain.core.models.ChatMessage

Bases: TypedDict

A text-based chat message accepted by the built-in clients.

luckybrain.core.models.ChatInput = str | Sequence[Mapping[str, str]] module-attribute

luckybrain.core.models.BaseChatModel(model: str, api_key: str | None = None, temperature: float | None = None, system_prompt: str = 'You are a helpful assistant.', max_tokens: int | None = None, top_p: float | None = None, **additional_params: Any)

Bases: ABC

Shared conversation handling for synchronous chat model providers.

Methods:

Name	Description
clear_history	Clear conversation turns while preserving the initial system prompt.
stream	Stream a response and add the completed exchange to conversation history.
think	Send a prompt or sequence of text messages and return the model's answer.

clear_history() -> None

Clear conversation turns while preserving the initial system prompt.

stream(messages: ChatInput) -> Iterator[str]

Stream a response and add the completed exchange to conversation history.

think(messages: ChatInput) -> str

Send a prompt or sequence of text messages and return the model's answer.

luckybrain.core.models.ChatModelProtocol

Bases: Protocol

Common public interface implemented by synchronous chat models.

luckybrain.core.models.OpenaiBrain(model: str = 'gpt-4o-mini', temperature: float | None = None, api_key: str | None = None, system_prompt: str = 'You are a helpful assistant.', max_tokens: int | None = None, top_p: float | None = None, base_url: str | None = None, **additional_params: Any)

Bases: BaseChatModel

Synchronous chat client for OpenAI-compatible chat completion models.

Methods:

Name	Description
clear_history	Clear conversation turns while preserving the initial system prompt.
stream	Stream a response and add the completed exchange to conversation history.
think	Send a prompt or sequence of text messages and return the model's answer.

clear_history() -> None

Clear conversation turns while preserving the initial system prompt.

stream(messages: ChatInput) -> Iterator[str]

Stream a response and add the completed exchange to conversation history.

think(messages: ChatInput) -> str

Send a prompt or sequence of text messages and return the model's answer.

luckybrain.core.models.GroqBrain(model: str = 'llama-3.3-70b-versatile', temperature: float | None = None, api_key: str | None = None, system_prompt: str = 'You are a helpful assistant.', max_tokens: int | None = None, top_p: float | None = None, **additional_params: Any)

Bases: BaseChatModel

Synchronous chat client for Groq chat completion models.

Methods:

Name	Description
clear_history	Clear conversation turns while preserving the initial system prompt.
stream	Stream a response and add the completed exchange to conversation history.
think	Send a prompt or sequence of text messages and return the model's answer.

clear_history() -> None

Clear conversation turns while preserving the initial system prompt.

stream(messages: ChatInput) -> Iterator[str]

Stream a response and add the completed exchange to conversation history.

think(messages: ChatInput) -> str

Send a prompt or sequence of text messages and return the model's answer.

Retrieval and generation protocols

luckybrain.rag.protocols.Retriever

Bases: Protocol

Retrieve ranked source documents for a text query.

luckybrain.rag.protocols.Reranker

Bases: Protocol

Reorder candidate documents for a text query.

luckybrain.rag.protocols.Generator

Bases: Protocol

Generate text from a prompt assembled by a calling component.

Agent tools

luckybrain.agents.protocols.AgentTool

Bases: Protocol

A named capability an agent can invoke with structured input.

Query rewriting

QueryRewriting is experimental and available from luckybrain.query_imp; it is not re-exported from the package root.

luckybrain.query_imp.queryimproval.QueryRewriting(model: ChatModelProtocol, style: str | None = 'search')

Rewrite search queries using a synchronous chat-model implementation.

The model must provide think(prompt: str) -> str. This helper delegates every rewrite to that model and does not perform retrieval itself.

Create a rewriter.

Parameters:

Name	Type	Description	Default
model	ChatModelProtocol	Chat model used to generate rewrites; it must implement think(prompt: str) -> str.	required
style	str | None	Use search-focused wording for "search". Any other value uses question-focused wording.	'search'

Methods:

Name	Description
improve	Return one rewritten query, or an empty string for blank input.
variants	Return up to n alternative query rewrites, one per model line.

improve(query: str) -> str

Return one rewritten query, or an empty string for blank input.

Parameters:

Name	Type	Description	Default
query	str	User-provided search text.	required

Returns:

Type	Description
str	The model's rewritten text with surrounding whitespace and quote
str	characters removed.

variants(query: str, n: int | None = 3) -> list[str]

Return up to n alternative query rewrites, one per model line.

Parameters:

Name	Type	Description	Default
query	str	User-provided search text.	required
n	int | None	Maximum number of lines to return. None returns all non-empty lines supplied by the model.	3

Returns:

Type	Description
list[str]	Non-empty model response lines with common list markers removed.
list[str]	The result can contain fewer than n variants when the model
list[str]	returns fewer usable lines.

Re-exported names

The package root exports Document and RetrievalResult. The luckybrain.rag module exports Retriever, Reranker, and Generator; luckybrain.agents exports AgentTool. Provider clients and experimental query rewriting must be imported from the module paths shown above.