mellea.stdlib.components.genslot

Functions

FUNC `create_response_format`

create_response_format(func: Callable[..., R]) -> type[FunctionResponse[R]]

Create a Pydantic response format class for a given function. Args:

func: A function with exactly one argument

Returns:

A Pydantic model class that inherits from FunctionResponse[T]

FUNC `describe_function`

describe_function(func: Callable) -> FunctionDict

Generates a FunctionDict given a function. Args:

func : Callable function that needs to be passed to generative slot.

Returns:

Function dict of the passed function.

FUNC `get_argument`

get_argument(func: Callable, key: str, val: Any) -> Argument

Returns an argument given a parameter. Note: Performs additional formatting for string objects, putting them in quotes. Args:

func : Callable Function
key : Arg key
val : Arg value

Returns:

an argument object representing the given parameter.

FUNC `bind_function_arguments`

bind_function_arguments(func: Callable[P, R], *args: P.args, **kwargs: P.kwargs) -> dict[str, Any]

Bind arguments to function parameters and return as dictionary. Args:

func: The function to bind arguments for.
*args: Positional arguments to bind.
**kwargs: Keyword arguments to bind.

Returns:

Dictionary mapping parameter names to bound values with defaults applied.

FUNC `generative`

generative(func: Callable[P, R]) -> GenerativeSlot[P, R]

Convert a function into an AI-powered function. This decorator transforms a regular Python function into one that uses an LLM to generate outputs. The function’s entire signature - including its name, parameters, docstring, and type hints - is used to instruct the LLM to imitate that function’s behavior. The output is guaranteed to match the return type annotation using structured outputs and automatic validation. Notes:

Works with async functions as well.
Must pass all parameters for the original function as keyword args.
Most python type-hinters will not show the default values but will correctly infer them; this means that you can set default values in the decorated function and the only necessary values will be a session or a (context, backend).

Tip: Write the function and docstring in the most Pythonic way possible, not like a prompt. This ensures the function is well-documented, easily understood, and familiar to any Python developer. The more natural and conventional your function definition, the better the AI will understand and imitate it. The requirements and validation for the generative function operate over a textual representation of the arguments / outputs (not their python objects). Args:

func: Function with docstring and type hints. Implementation can be empty (…).

Returns:

An AI-powered function that generates responses using an LLM based on the
original function’s signature and docstring.

Raises:

ValueError: (raised by @generative) if the decorated function has a parameter name used by generative slots
ValidationError: (raised when calling the generative slot) if the generated output cannot be parsed into the expected return type. Typically happens when the token limit for the generated output results in invalid json.
TypeError: (raised when calling the generative slot) if any of the original function’s parameters were passed as positional args
PreconditionException: (raised when calling the generative slot) if the precondition validation of the args fails; catch the exception to get the validation results

Examples:

>>> from mellea import generative, start_session
>>> session = start_session()
>>> @generative
... def summarize_text(text: str, max_words: int = 50) -> str:
...     '''Generate a concise summary of the input text.'''
...     ...
>>>
>>> summary = summarize_text(session, text="Long text...", max_words=30)

>>> from typing import List
>>> from dataclasses import dataclass
>>>
>>> @dataclass
... class Task:
...     title: str
...     priority: str
...     estimated_hours: float
>>>
>>> @generative
... async def create_project_tasks(project_desc: str, count: int) -> List[Task]:
...     '''Generate a list of realistic tasks for a project.
...
...     Args:
...         project_desc: Description of the project
...         count: Number of tasks to generate
...
...     Returns:
...         List of tasks with titles, priorities, and time estimates
...     '''
...     ...
>>>
>>> tasks = await create_project_tasks(session, project_desc="Build a web app", count=5)

>>> @generative
... def analyze_code_quality(code: str) -> Dict[str, Any]:
...     '''Analyze code quality and provide recommendations.
...
...     Args:
...         code: Source code to analyze
...
...     Returns:
...         Dictionary containing:
...         - score: Overall quality score (0-100)
...         - issues: List of identified problems
...         - suggestions: List of improvement recommendations
...         - complexity: Estimated complexity level
...     '''
...     ...
>>>
>>> analysis = analyze_code_quality(
...     session,
...     code="def factorial(n): return n * factorial(n-1)",
...     model_options={"temperature": 0.3}
... )

>>> @dataclass
... class Thought:
...     title: str
...     body: str
>>>
>>> @generative
... def generate_chain_of_thought(problem: str, steps: int = 5) -> List[Thought]:
...     '''Generate a step-by-step chain of thought for solving a problem.
...
...     Args:
...         problem: The problem to solve or question to answer
...         steps: Maximum number of reasoning steps
...
...     Returns:
...         List of reasoning steps, each with a title and detailed body
...     '''
...     ...
>>>
>>> reasoning = generate_chain_of_thought(session, problem="How to optimize a slow database query?")

Classes

CLASS `FunctionResponse`

Generic base class for function response formats.

CLASS `FunctionDict`

Return Type for a Function Component.

CLASS `ArgumentDict`

Return Type for a Argument Component.

CLASS `Argument`

An Argument.

CLASS `Arguments`

CLASS `ArgPreconditionRequirement`

Specific requirement with template for validating precondition requirements against a set of args.

CLASS `PreconditionException`

Exception raised when validation fails for a generative slot’s arguments.

CLASS `Function`

A Function.

CLASS `ExtractedArgs`

Used to extract the mellea args and original function args. See @generative decorator for additional notes on these fields. These args must match those allowed by any overload of GenerativeSlot.call.

CLASS `GenerativeSlot`

A generative slot component.

Methods:

FUNC `extract_args_and_kwargs`

extract_args_and_kwargs(*args, **kwargs) -> ExtractedArgs

Takes a mix of args and kwargs for both the generative slot and the original function and extracts them. Ensures the original function’s args are all kwargs. Returns:

a dataclass of the required args for mellea and the original function.
Either session or (backend, context) will be non-None.

Raises:

TypeError: if any of the original function’s parameters were passed as positional args

FUNC `parts`

parts(self) -> list[Component | CBlock]

Parts of Genslot.

FUNC `format_for_llm`

format_for_llm(self) -> TemplateRepresentation

Formats the instruction for Formatter use.

CLASS `SyncGenerativeSlot`

CLASS `AsyncGenerativeSlot`

A generative slot component that generates asynchronously and returns a coroutine.

mellea

cli

​Functions

​FUNC create_response_format

​FUNC describe_function

​FUNC get_argument

​FUNC bind_function_arguments

​FUNC generative

​Classes

​CLASS FunctionResponse

​CLASS FunctionDict

​CLASS ArgumentDict

​CLASS Argument

​CLASS Arguments

​CLASS ArgPreconditionRequirement

​CLASS PreconditionException

​CLASS Function

​CLASS ExtractedArgs

​CLASS GenerativeSlot

​FUNC extract_args_and_kwargs

​FUNC parts

​FUNC format_for_llm

​CLASS SyncGenerativeSlot

​CLASS AsyncGenerativeSlot

Functions

FUNC `create_response_format`

FUNC `describe_function`

FUNC `get_argument`

FUNC `bind_function_arguments`

FUNC `generative`

Classes

CLASS `FunctionResponse`

CLASS `FunctionDict`

CLASS `ArgumentDict`

CLASS `Argument`

CLASS `Arguments`

CLASS `ArgPreconditionRequirement`

CLASS `PreconditionException`

CLASS `Function`

CLASS `ExtractedArgs`

CLASS `GenerativeSlot`

FUNC `extract_args_and_kwargs`

FUNC `parts`

FUNC `format_for_llm`

CLASS `SyncGenerativeSlot`

CLASS `AsyncGenerativeSlot`