mellea.stdlib.session

MelleaSession: the primary entry point for running generative programs. MelleaSession wraps a [Backend](../core/backend#class-backend) and a [Context](../core/base#class-context) and exposes high-level methods (act, instruct, sample) that drive the generate-validate-repair loop. It also manages a global context variable (accessible via get_session()) so that nested components can reach the current session without explicit threading. Use start_session(...) as a context manager to create and automatically clean up a session.

Functions

FUNC `get_session`

get_session() -> MelleaSession

Get the current session from context. Returns:

The currently active MelleaSession.

Raises:

RuntimeError: If no session is currently active.

FUNC `backend_name_to_class`

backend_name_to_class(name: str) -> Any

Resolves backend names to Backend classes. Args:

name: Short backend name, e.g. "ollama", "hf", "openai", "watsonx", or "litellm".

Returns:

The corresponding [Backend](../core/backend#class-backend) class, or None if the name is unrecognised.

Raises:

ImportError: If the requested backend has optional dependencies that are not installed (e.g. mellea[hf], mellea[watsonx], or mellea[litellm]).

FUNC `start_session`

start_session(backend_name: Literal['ollama', 'hf', 'openai', 'watsonx', 'litellm'] = 'ollama', model_id: str | ModelIdentifier = IBM_GRANITE_4_MICRO_3B, ctx: Context | None = None, **backend_kwargs) -> MelleaSession

Start a new Mellea session. Can be used as a context manager or called directly. This function creates and configures a new Mellea session with the specified backend and model. When used as a context manager (with with statement), it automatically sets the session as the current active session for use with convenience functions like instruct(), chat(), query(), and transform(). When called directly, it returns a session object that can be used directly. Args:

backend_name: The backend to use. Options are:
“ollama”: Use Ollama backend for local models
“hf” or “huggingface”: Use HuggingFace transformers backend
“openai”: Use OpenAI API backend
“watsonx”: Use IBM WatsonX backend
“litellm”: Use the LiteLLM backend
model_id: Model identifier or name. Can be a ModelIdentifier from mellea.backends.model_ids or a string model name.
ctx: Context manager for conversation history. Defaults to SimpleContext(). Use ChatContext() for chat-style conversations.
model_options: Additional model configuration options that will be passed to the backend (e.g., temperature, max_tokens, etc.).
plugins: Optional list of plugins scoped to this session. Accepts @hook-decorated functions, @plugin-decorated class instances, MelleaPlugin instances, or [PluginSet](../plugins/pluginset#class-pluginset) instances.
**backend_kwargs: Additional keyword arguments passed to the backend constructor.

Returns:

A session object that can be used as a context manager
or called directly with session methods.

Raises:

Exception: If backend_name is not one of the recognised backend identifiers.
ImportError: If the requested backend requires optional dependencies that are not installed.

Examples:

# Basic usage with default settings
with start_session() as session:
    response = session.instruct("Explain quantum computing")

# Using OpenAI with custom model options
with start_session("openai", "gpt-4", model_options={{"temperature": 0.7}}):
    response = session.chat("Write a poem")

# Using HuggingFace with ChatContext for conversations
from mellea.stdlib.base import ChatContext
with start_session("hf", "microsoft/DialoGPT-medium", ctx=ChatContext()):
    session.chat("Hello!")
    session.chat("How are you?")  # Remembers previous message

# Direct usage.
session = start_session()
response = session.instruct("Explain quantum computing")
session.cleanup()

Classes

CLASS `MelleaSession`

Mellea sessions are a THIN wrapper around m convenience functions with NO special semantics. Using a Mellea session is not required, but it does represent the “happy path” of Mellea programming. Some nice things about ussing a MelleaSession:

In most cases you want to keep a Context together with the Backend from which it came.
You can directly run an instruction or a send a chat, instead of first creating the Instruction or Chat object and then later calling backend.generate on the object.
The context is “threaded-through” for you, which allows you to issue a sequence of commands instead of first calling backend.generate on something and then appending it to your context.

These are all relatively simple code hygiene and state management benefits, but they add up over time. If you are doing complicating programming (e.g., non-trivial inference scaling) then you might be better off forgoing MelleaSessions and managing your Context and Backend directly. Note: we put the instruct, validate, and other convenience functions here instead of in Context or Backend to avoid import resolution issues. Args:

backend: The backend to use for all model inference in this session.
ctx: The conversation context. Defaults to a new SimpleContext if None.

Attributes:

ctx: The active conversation context; never None (defaults to a fresh SimpleContext when None is passed). Updated after every call that produces model output.
id: Unique session UUID assigned at construction.

Methods:

FUNC `clone`

clone(self)

Useful for running multiple generation requests while keeping the context at a given point in time. Returns:

a copy of the current session. Keeps the context, backend, and session logger.

Examples:

>>> from mellea import start_session
>>> m = start_session()
>>> m.instruct("What is 2x2?")
>>>
>>> m1 = m.clone()
>>> out = m1.instruct("Multiply that by 2")
>>> print(out)
... 8
>>>
>>> m2 = m.clone()
>>> out = m2.instruct("Multiply that by 3")
>>> print(out)
... 12

FUNC `reset`

reset(self)

Reset the context state to a fresh, empty context of the same type. Fires the SESSION_RESET plugin hook if any plugins are registered, then replaces self.ctx with the result of ctx.reset_to_new(), discarding all accumulated conversation history.

FUNC `cleanup`

cleanup(self) -> None

Clean up session resources and deregister session-scoped plugins.

FUNC `act`

act(self, action: Component[S]) -> ModelOutputThunk[S]

FUNC `act`

act(self, action: Component[S]) -> SamplingResult[S]

FUNC `act`

act(self, action: Component[S]) -> ModelOutputThunk[S] | SamplingResult

Runs a generic action, and adds both the action and the result to the context. Args:

action: the Component from which to generate.
requirements: used as additional requirements when a sampling strategy is provided
strategy: a SamplingStrategy that describes the strategy for validating and repairing/retrying for the instruct-validate-repair pattern. None means that no particular sampling strategy is used.
return_sampling_results: attach the (successful and failed) sampling attempts to the results.
format: if set, the BaseModel to use for constrained decoding.
model_options: additional model options, which will upsert into the model/backend’s defaults.
tool_calls: if true, tool calling is enabled.

Returns:

A ModelOutputThunk if return_sampling_results is False, else returns a SamplingResult.

FUNC `instruct`

instruct(self, description: str) -> ModelOutputThunk[str]

FUNC `instruct`

instruct(self, description: str) -> SamplingResult[str]

FUNC `instruct`

instruct(self, description: str) -> ModelOutputThunk[str] | SamplingResult

Generates from an instruction. Args:

description: The description of the instruction.
requirements: A list of requirements that the instruction can be validated against.
icl_examples: A list of in-context-learning examples that the instruction can be validated against.
grounding_context: A list of grounding contexts that the instruction can use. They can bind as variables using a (key: str, value: str | ContentBlock) tuple.
user_variables: A dict of user-defined variables used to fill in Jinja placeholders in other parameters. This requires that all other provided parameters are provided as strings.
prefix: A prefix string or ContentBlock to use when generating the instruction.
output_prefix: A string or ContentBlock that defines a prefix for the output generation. Usually you do not need this.
strategy: A SamplingStrategy that describes the strategy for validating and repairing/retrying for the instruct-validate-repair pattern. None means that no particular sampling strategy is used.
return_sampling_results: attach the (successful and failed) sampling attempts to the results.
format: If set, the BaseModel to use for constrained decoding.
model_options: Additional model options, which will upsert into the model/backend’s defaults.
tool_calls: If true, tool calling is enabled.
images: A list of images to be used in the instruction or None if none.

Returns:

A [ModelOutputThunk](../core/base#class-modeloutputthunk) if return_sampling_results is False,
else a [SamplingResult](../core/sampling#class-samplingresult).

FUNC `chat`

chat(self, content: str, role: Message.Role = 'user') -> Message

Sends a simple chat message and returns the response. Adds both messages to the Context. Args:

content: The message text to send.
role: The role for the outgoing message (default "user").
images: Optional list of images to include in the message.
user_variables: Optional Jinja variable substitutions applied to content.
format: Optional Pydantic model for constrained decoding of the response.
model_options: Additional model options to merge with backend defaults.
tool_calls: If true, tool calling is enabled.

Returns:

The assistant Message response.

FUNC `validate`

validate(self, reqs: Requirement | list[Requirement]) -> list[ValidationResult]

Validates a set of requirements over the output (if provided) or the current context (if the output is not provided). Args:

reqs: A single [Requirement](../core/requirement#class-requirement) or a list of them to validate.
output: Optional model output [CBlock](../core/base#class-cblock) to validate against instead of the context.
format: Optional Pydantic model for constrained decoding.
model_options: Additional model options to merge with backend defaults.
generate_logs: Optional list to append generation logs to.
input: Optional input [CBlock](../core/base#class-cblock) to include alongside output when validating.

Returns:

List of [ValidationResult](../core/requirement#class-validationresult) objects, one per requirement.

FUNC `query`

query(self, obj: Any, query: str) -> ModelOutputThunk

Query method for retrieving information from an object. Args:

obj : The object to be queried. It should be an instance of MObject or can be converted to one if necessary.
query: The string representing the query to be executed against the object.
format: format for output parsing.
model_options: Model options to pass to the backend.
tool_calls: If true, the model may make tool calls. Defaults to False.

Returns:

The result of the query as processed by the backend.

FUNC `transform`

transform(self, obj: Any, transformation: str) -> ModelOutputThunk | Any

Transform method for creating a new object with the transformation applied. Args:

obj : The object to be queried. It should be an instance of MObject or can be converted to one if necessary.
transformation: The string representing the query to be executed against the object.
format: format for output parsing; usually not needed with transform.
model_options: Model options to pass to the backend.

Returns:

ModelOutputThunk|Any: The result of the transformation as processed by the backend. If no tools were called,
the return type will be always be ModelOutputThunk. If a tool was called, the return type will be the return type
of the function called, usually the type of the object passed in.

FUNC `aact`

aact(self, action: Component[S]) -> ModelOutputThunk[S]

FUNC `aact`

aact(self, action: Component[S]) -> SamplingResult[S]

FUNC `aact`

aact(self, action: Component[S]) -> ModelOutputThunk[S] | SamplingResult

Runs a generic action, and adds both the action and the result to the context. Args:

action: the Component from which to generate.
requirements: used as additional requirements when a sampling strategy is provided
strategy: a SamplingStrategy that describes the strategy for validating and repairing/retrying for the instruct-validate-repair pattern. None means that no particular sampling strategy is used.
return_sampling_results: attach the (successful and failed) sampling attempts to the results.
format: if set, the BaseModel to use for constrained decoding.
model_options: additional model options, which will upsert into the model/backend’s defaults.
tool_calls: if true, tool calling is enabled.

Returns:

A ModelOutputThunk if return_sampling_results is False, else returns a SamplingResult.

FUNC `ainstruct`

ainstruct(self, description: str) -> ModelOutputThunk[str]

FUNC `ainstruct`

ainstruct(self, description: str) -> SamplingResult[str]

FUNC `ainstruct`

ainstruct(self, description: str) -> ModelOutputThunk[str] | SamplingResult[str]

Generates from an instruction. Args:

description: The description of the instruction.
requirements: A list of requirements that the instruction can be validated against.
icl_examples: A list of in-context-learning examples that the instruction can be validated against.
grounding_context: A list of grounding contexts that the instruction can use. They can bind as variables using a (key: str, value: str | ContentBlock) tuple.
user_variables: A dict of user-defined variables used to fill in Jinja placeholders in other parameters. This requires that all other provided parameters are provided as strings.
prefix: A prefix string or ContentBlock to use when generating the instruction.
output_prefix: A string or ContentBlock that defines a prefix for the output generation. Usually you do not need this.
strategy: A SamplingStrategy that describes the strategy for validating and repairing/retrying for the instruct-validate-repair pattern. None means that no particular sampling strategy is used.
return_sampling_results: attach the (successful and failed) sampling attempts to the results.
format: If set, the BaseModel to use for constrained decoding.
model_options: Additional model options, which will upsert into the model/backend’s defaults.
tool_calls: If true, tool calling is enabled.
images: A list of images to be used in the instruction or None if none.

Returns:

A [ModelOutputThunk](../core/base#class-modeloutputthunk) if return_sampling_results is False,
else a [SamplingResult](../core/sampling#class-samplingresult).

FUNC `achat`

achat(self, content: str, role: Message.Role = 'user') -> Message

Sends a simple chat message and returns the response. Adds both messages to the Context. Args:

content: The message text to send.
role: The role for the outgoing message (default "user").
images: Optional list of images to include in the message.
user_variables: Optional Jinja variable substitutions applied to content.
format: Optional Pydantic model for constrained decoding of the response.
model_options: Additional model options to merge with backend defaults.
tool_calls: If true, tool calling is enabled.

Returns:

The assistant Message response.

FUNC `avalidate`

avalidate(self, reqs: Requirement | list[Requirement]) -> list[ValidationResult]

Validates a set of requirements over the output (if provided) or the current context (if the output is not provided). Args:

reqs: A single [Requirement](../core/requirement#class-requirement) or a list of them to validate.
output: Optional model output [CBlock](../core/base#class-cblock) to validate against instead of the context.
format: Optional Pydantic model for constrained decoding.
model_options: Additional model options to merge with backend defaults.
generate_logs: Optional list to append generation logs to.
input: Optional input [CBlock](../core/base#class-cblock) to include alongside output when validating.

Returns:

List of [ValidationResult](../core/requirement#class-validationresult) objects, one per requirement.

FUNC `aquery`

aquery(self, obj: Any, query: str) -> ModelOutputThunk

Query method for retrieving information from an object. Args:

obj : The object to be queried. It should be an instance of MObject or can be converted to one if necessary.
query: The string representing the query to be executed against the object.
format: format for output parsing.
model_options: Model options to pass to the backend.
tool_calls: If true, the model may make tool calls. Defaults to False.

Returns:

The result of the query as processed by the backend.

FUNC `atransform`

atransform(self, obj: Any, transformation: str) -> ModelOutputThunk | Any

Transform method for creating a new object with the transformation applied. Args:

obj: The object to be queried. It should be an instance of MObject or can be converted to one if necessary.
transformation: The string representing the query to be executed against the object.
format: format for output parsing; usually not needed with transform.
model_options: Model options to pass to the backend.

Returns:

ModelOutputThunk|Any: The result of the transformation as processed by the backend. If no tools were called,
the return type will be always be ModelOutputThunk. If a tool was called, the return type will be the return type
of the function called, usually the type of the object passed in.

FUNC `powerup`

powerup(cls, powerup_cls: type)

Appends methods in a class object powerup_cls to MelleaSession. Iterates over all functions defined on powerup_cls and attaches each one as a method on the MelleaSession class, effectively extending the session with domain-specific helpers at runtime. Args:

powerup_cls: A class whose functions should be added to MelleaSession as instance methods.

FUNC `last_prompt`

last_prompt(self) -> str | list[dict] | None

Returns the last prompt that has been called from the session context. Returns:

A string if the last prompt was a raw call to the model OR a list of messages (as role-msg-dicts). Is None if none could be found.

mellea

cli

​Functions

​FUNC get_session

​FUNC backend_name_to_class

​FUNC start_session

​Classes

​CLASS MelleaSession

​FUNC clone

​FUNC reset

​FUNC cleanup

​FUNC act

​FUNC act

​FUNC act

​FUNC instruct

​FUNC instruct

​FUNC instruct

​FUNC chat

​FUNC validate

​FUNC query

​FUNC transform

​FUNC aact

​FUNC aact

​FUNC aact

​FUNC ainstruct

​FUNC ainstruct

​FUNC ainstruct

​FUNC achat

​FUNC avalidate

​FUNC aquery

​FUNC atransform

​FUNC powerup

​FUNC last_prompt

Functions

FUNC `get_session`

FUNC `backend_name_to_class`

FUNC `start_session`

Classes

CLASS `MelleaSession`

FUNC `clone`

FUNC `reset`

FUNC `cleanup`

FUNC `act`

FUNC `act`

FUNC `act`

FUNC `instruct`

FUNC `instruct`

FUNC `instruct`

FUNC `chat`

FUNC `validate`

FUNC `query`

FUNC `transform`

FUNC `aact`

FUNC `aact`

FUNC `aact`

FUNC `ainstruct`

FUNC `ainstruct`

FUNC `ainstruct`

FUNC `achat`

FUNC `avalidate`

FUNC `aquery`

FUNC `atransform`

FUNC `powerup`

FUNC `last_prompt`