Skip to main content
A method to generate outputs based on python functions and a Generative Slot function.

​
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.
Raises:
  • TypeError: If required parameters from the original function are missing from the provided arguments.

​
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. Attributes:
  • result: The value returned by the generative function.

​
CLASS FunctionDict

Return Type for a Function Component. Attributes:
  • name: The function’s __name__.
  • signature: The function’s parameter signature as a string.
  • docstring: The function’s docstring, or None if absent.

​
CLASS ArgumentDict

Return Type for an Argument Component. Attributes:
  • name: The parameter name.
  • annotation: The parameter’s type annotation as a string.
  • value: The bound value for this parameter as a string.

​
CLASS Argument

A single function argument with its name, type annotation, and value. Args:
  • annotation: The parameter’s type annotation as a string.
  • name: The parameter name.
  • value: The bound value for this parameter as a string.

​
CLASS Arguments

A [CBlock](../../core/base#class-cblock) that renders a list of Argument objects as human-readable text. Each argument is formatted as "- name: value (type: annotation)" and the items are newline-joined into a single string suitable for inclusion in a prompt. Args:
  • arguments: The list of bound function arguments to render.

​
CLASS ArgPreconditionRequirement

Specific requirement with template for validating precondition requirements against a set of args. Args:
  • req: The underlying requirement to wrap. All method calls are delegated to this requirement.

​
CLASS PreconditionException

Exception raised when validation fails for a generative slot’s arguments. Args:
  • message: Human-readable description of the failure.
  • validation_results: The individual validation results from the failed precondition checks.
Attributes:
  • validation: The validation results from the failed precondition checks.

​
CLASS Function

Wraps a callable with its introspected FunctionDict metadata. Stores the original callable alongside its name, signature, and docstring as produced by describe_function, so generative slots can render them into prompts without re-inspecting the function each time. Args:
  • func: The callable to wrap and introspect.

​
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. Attributes:
  • f_args: Positional args from the original function call; used to detect incorrectly passed args to generative slots.
  • f_kwargs: Keyword args intended for the original function.
  • m: The active Mellea session, if provided.

​
CLASS GenerativeSlot

Abstract base class for AI-powered function wrappers produced by @generative. A GenerativeSlot wraps a callable and uses an LLM to generate its output. Subclasses (SyncGenerativeSlot, AsyncGenerativeSlot) implement __call__ for synchronous and asynchronous invocation respectively. The function’s signature, docstring, and type hints are rendered into a prompt so the LLM can imitate the function’s intended behaviour. Args:
  • func: The function whose behaviour the LLM should imitate.
Attributes:
  • precondition_requirements: Requirements validated against the function’s input arguments before generation.
  • requirements: Requirements validated against the LLM’s generated output.
Methods:

​
FUNC extract_args_and_kwargs 

extract_args_and_kwargs(*args, **kwargs) -> ExtractedArgs
Take a mix of args and kwargs for both the generative slot and the original function and extract them. Ensures the original function’s args are all kwargs. Args:
  • args: Positional arguments; the first must be either a MelleaSession or a [Context](../../core/base#class-context) instance.
  • kwargs: Keyword arguments for both the generative slot machinery (e.g. m, context, backend, requirements) and the wrapped function’s own parameters.
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 or if required mellea parameters are missing.

​
FUNC parts 

parts(self) -> list[Component | CBlock]
Return the constituent parts of this generative slot component. Includes the rendered arguments block (if arguments have been bound) and any requirements attached to this slot. Returns:
  • list[Component | CBlock]: List of argument blocks and requirements.

​
FUNC format_for_llm 

format_for_llm(self) -> TemplateRepresentation
Format this generative slot for the language model. Builds a [TemplateRepresentation](../../core/base#class-templaterepresentation) containing the function metadata (name, signature, docstring), the bound arguments, and any requirement descriptions. Returns:
  • The formatted representation ready for the
  • [Formatter](../../core/formatter#class-formatter) to render into a prompt.

​
CLASS SyncGenerativeSlot

A synchronous generative slot that blocks until the LLM response is ready. Returned by @generative when the decorated function is not a coroutine. __call__ returns the parsed result directly (when a session is passed) or a (result, context) tuple (when a context and backend are passed).

​
CLASS AsyncGenerativeSlot

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