​

mellea.stdlib.session

​

Functions

​

get_session

get_session() -> MelleaSession

• RuntimeError: If no session is currently active.

​

backend_name_to_class

backend_name_to_class(name: str) -> Any

​

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

• 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.).
• **backend_kwargs: Additional keyword arguments passed to the backend constructor.

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

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

# Using OpenAI with custom model options
with start_session("openai", "gpt-4", model_options={"temperature": 0.7}):
    response = 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()):
    chat("Hello!")
    chat("How are you?")  # Remembers previous message

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

​

Classes

​

MelleaSession

1. In most cases you want to keep a Context together with the Backend from which it came.
2. 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.
3. 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.

​

reset

reset(self)

​

cleanup

cleanup(self) -> None

​

act

act(self, action: Component) -> ModelOutputThunk

​

act

act(self, action: Component) -> SamplingResult

​

act

act(self, action: Component, **kwargs) -> ModelOutputThunk | SamplingResult

• 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.

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

​

instruct

instruct(self, description: str) -> ModelOutputThunk

​

instruct

instruct(self, description: str) -> SamplingResult

​

instruct

instruct(self, description: str, **kwargs) -> ModelOutputThunk | SamplingResult

• 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.

​

chat

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

​

validate

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

​

query

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

• 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.

• The result of the query as processed by the backend.

​

transform

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

• 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.

• 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.

​

last_prompt

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

• 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.