> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mellea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# mellea.core.base

> Foundational data structures for mellea's generative programming model.

export const SidebarFix = () => <script dangerouslySetInnerHTML={{
  __html: `
        (function () {
          const INTERVAL_MS = 500;

          const upgradeSidebar = () => {
            const links = document.querySelectorAll('a[href^="#"]');

            links.forEach((link) => {
              if (link.dataset.badged === "true") return;

              const rawText = (link.textContent || "").trim();

              // ========== FUNC ==========
              if (rawText.startsWith("FUNC ")) {
                const label = rawText.replace(/^FUNC\\s+/, "").trim();

                while (link.firstChild) link.removeChild(link.firstChild);

                // 👉 Make the whole link a single flex row & prevent wrapping
                link.style.display = "flex";
                link.style.alignItems = "center";
                link.style.whiteSpace = "nowrap";
                link.style.columnGap = "0.5rem";

                const badge = document.createElement("span");
                badge.style.marginRight = "0.5rem";
                badge.style.display = "inline-flex";
                badge.style.alignItems = "center";
                badge.style.borderRadius = "9999px";
                badge.style.padding = "0rem 0.6rem";
                badge.style.fontSize = "0.5rem";
                badge.style.fontWeight = "700";
                badge.style.letterSpacing = "0.05em";
                badge.style.backgroundColor = "rgba(48, 100, 227, 0.20)";
                badge.style.color = "#1D4ED8";

                badge.textContent = "FUNC";

                link.appendChild(badge);
                link.appendChild(document.createTextNode(label));
                link.dataset.badged = "true";
                return;
              }

              // ========== CLASS ==========
              if (rawText.startsWith("CLASS ")) {
                const label = rawText.replace(/^CLASS\\s+/, "").trim();

                while (link.firstChild) link.removeChild(link.firstChild);

                // 👉 Same flex / nowrap treatment for class links
                link.style.display = "flex";
                link.style.alignItems = "center";
                link.style.whiteSpace = "nowrap";
                link.style.columnGap = "0.5rem";

                const badge = document.createElement("span");
                badge.style.marginRight = "0.5rem";
                badge.style.display = "inline-flex";
                badge.style.alignItems = "center";
                badge.style.borderRadius = "9999px";
                badge.style.padding = "0rem 0.6rem";
                badge.style.fontSize = "0.5rem";
                badge.style.fontWeight = "700";
                badge.style.letterSpacing = "0.05em";
                badge.style.backgroundColor = "rgba(74, 222, 128, 0.20)";
                badge.style.color = "#15803D";

                badge.textContent = "CLASS";

                link.appendChild(badge);
                link.appendChild(document.createTextNode(label));
                link.dataset.badged = "true";
                return;
              }
            });
          };

          upgradeSidebar();
          setInterval(upgradeSidebar, INTERVAL_MS);
        })();
      `
}} />;

<SidebarFix />

Foundational data structures for mellea's generative programming model.

Defines the building blocks that flow through every layer of the library: `CBlock`
(a content block wrapping a string value), `Component` (an abstract composable
generative unit), `ModelOutputThunk` (a lazily-evaluated model response),
`Context` and `ContextTurn` (stateful conversation history containers),
`TemplateRepresentation` (the structured rendering of a component for prompt
templates), `ImageBlock`, and `ModelToolCall`. Understanding these types is
the starting point for building custom components or sampling strategies.

## Functions

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `blockify` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L1213" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
blockify(s: str | CBlock | Component) -> CBlock | Component
```

Turn a raw string into a `CBlock`, leaving `CBlock` and `Component` objects unchanged.

**Args:**

* `s`: A plain string, `CBlock`, or `Component` to normalise.

**Returns:**

* A `CBlock` wrapping `s` if it was a string; otherwise `s` unchanged.

**Raises:**

* `Exception`: If `s` is not a `str`, `CBlock`, or `Component`.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `get_images_from_component` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L1237" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
get_images_from_component(c: Component) -> None | list[ImageBlock]
```

Return the images attached to a `Component`, or `None` if absent or empty.

**Args:**

* `c`: The `Component` whose `images` attribute is inspected.

**Returns:**

* A non-empty list of `ImageBlock` objects if the component has an
* `images` attribute with at least one element; `None` otherwise.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

## Classes

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#4ADE8033]/20 text-[#15803D]">CLASS</span> `CBlock` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L42" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A `CBlock` is a block of content that can serve as input to or output from an LLM.

**Args:**

* `value`: The underlying string content of the block.
* `meta`: Optional metadata about this block (e.g., the inference engine's
  completion object). Defaults to an empty dict.
* `cache`: If `True`, the inference engine may store the KV cache for this block. Experimental.

<div className="h-8" />

**Methods:**

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `value` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L70" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
value(self) -> str | None
```

Gets the value of the block.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `value` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L75" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
value(self, v: str) -> None
```

Sets the value of the block.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#4ADE8033]/20 text-[#15803D]">CLASS</span> `ImageBlock` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L88" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A `ImageBlock` represents an image (as base64 PNG).

**Args:**

* `value`: A valid base64-encoded PNG string (with or without a data URI prefix).
* `meta`: Optional metadata to associate with this image block.

<div className="h-8" />

**Methods:**

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `is_valid_base64_png` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L109" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
is_valid_base64_png(s: str) -> bool
```

Checks whether a string is a valid base64-encoded PNG image.

Strips any data URI prefix before decoding. Adds padding characters if
necessary to make the base64 string a valid length.

**Args:**

* `s`: The string to validate, optionally prefixed with a data URI header.

**Returns:**

* `True` if the string decodes to a PNG image, `False` otherwise.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `pil_to_base64` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L148" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
pil_to_base64(image: PILImage.Image) -> str
```

Converts a PIL image to a base64-encoded PNG string.

**Args:**

* `image`: The PIL image to encode.

**Returns:**

* A base64-encoded string of the image serialised as PNG.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `from_pil_image` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L162" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
from_pil_image(cls, image: PILImage.Image, meta: dict[str, Any] | None = None) -> ImageBlock
```

Creates an `ImageBlock` from a PIL image object.

Converts the image to a base64-encoded PNG string and wraps it in a new
`ImageBlock` instance.

**Args:**

* `image`: The PIL image to encode.
* `meta`: Optional metadata to associate with the block.

**Returns:**

* A new `ImageBlock` containing the base64-encoded PNG.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#4ADE8033]/20 text-[#15803D]">CLASS</span> `ComponentParseError` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L192" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Raised by `Component.parse()` when the underlying parsing method throws an exception.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#4ADE8033]/20 text-[#15803D]">CLASS</span> `Component` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L197" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A `Component` is a composite data structure that is intended to be represented to an LLM.

<div className="h-8" />

**Methods:**

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `parts` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L200" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
parts(self) -> list[Component | CBlock]
```

Returns the set of all constituent sub-components and content blocks of this `Component`.

**Returns:**

* list\[Component | CBlock]: A list of child `Component` or `CBlock` objects that make
* up this component. The list may be empty for leaf components.

**Raises:**

* `NotImplementedError`: If the concrete subclass has not overridden this method.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `format_for_llm` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L212" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
format_for_llm(self) -> TemplateRepresentation | str
```

Formats the `Component` into a `TemplateRepresentation` or plain string for LLM consumption.

**Returns:**

* TemplateRepresentation | str: A structured `TemplateRepresentation` (for components
* with tools, fields, or templates) or a plain string for simple components.

**Raises:**

* `NotImplementedError`: If the concrete subclass has not overridden this method.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `parse` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L224" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
parse(self, computed: ModelOutputThunk) -> S
```

Parses the expected type `S` from a given `ModelOutputThunk`.

Delegates to the component's underlying `_parse` method and wraps any
exception in a `ComponentParseError` for uniform error handling.

**Args:**

* `computed`: The model output thunk whose value should be parsed.

**Returns:**

* The parsed result produced by `_parse`, typed according to the component's type parameter.

**Raises:**

* `ComponentParseError`: If the underlying `_parse` call raises any exception.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#4ADE8033]/20 text-[#15803D]">CLASS</span> `GenerateType` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L249" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Used to track what functions can be used to extract a value from a ModelOutputThunk.

**Attributes:**

* `NONE`: No generation function has been set; the thunk is either already computed or uninitialized.
* `ASYNC`: The generation function is async-compatible; `avalue`/`astream` may be used.
* `SYNC`: The generation function is synchronous only; async extraction methods are unavailable.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#4ADE8033]/20 text-[#15803D]">CLASS</span> `GenerationMetadata` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L264" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Backend execution metadata attached to every ModelOutputThunk.

Fields are populated as generation progresses; see individual field docstrings for timing.

**Args:**

* `usage`: Token usage dict with 'prompt\_tokens', 'completion\_tokens', 'total\_tokens'.
* `model`: Model identifier that generated the output.
* `provider`: Provider name (e.g. 'openai', 'ollama', 'huggingface', 'watsonx').
* `ttfb_ms`: Time to first token in milliseconds; None for non-streaming.
* `streaming`: Whether this generation used streaming mode.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#4ADE8033]/20 text-[#15803D]">CLASS</span> `ModelOutputThunk` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L306" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A `ModelOutputThunk` is a special type of `CBlock` that we know came from a model's output. It is possible to instantiate one without the output being computed yet.

**Args:**

* `value`: The raw model output string, or `None` if not yet computed.
* `meta`: Optional metadata from the inference engine (e.g., completion object).
* `parsed_repr`: An already-parsed representation to attach; set when re-wrapping existing output.
* `tool_calls`: Tool calls returned by the model alongside the text output.

<div className="h-8" />

**Methods:**

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `cancel_generation` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L385" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
cancel_generation(self, error: Exception | None = None) -> None
```

Cancel an in-progress streaming generation, drain the queue, and close any open telemetry span.

Safe to call at any point during streaming. After this method returns,
`is_computed()` is `True` and `value` contains whatever text was
accumulated before cancellation.  Calling on an already-computed MOT
is a no-op.

Draining the internal queue after cancellation is necessary to release
any `asyncio.Queue.put()` call that the generation task was blocked on
(queue maxsize=20).

**Args:**

* `error`: Optional cause attributed to the open telemetry span.  When
  provided, this exception is recorded via `set_span_error` so
  the span reflects the actual reason for cancellation (e.g. the
  requirement failure or an unhandled exception from a streaming
  validator).  When `None`, a generic
  `RuntimeError("Generation cancelled")` is recorded.

**Raises:**

* `asyncio.CancelledError`: Re-raised when the *calling* task itself is
  being cancelled (`asyncio.current_task().cancelling() > 0`).
  This prevents external cancellation (e.g. `asyncio.wait_for`
  timeout) from being silently absorbed while awaiting the inner
  generation task.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `cancelled` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L484" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
cancelled(self) -> bool
```

`True` if :meth:`cancel_generation` ran to completion on this MOT.

A normally-completed MOT leaves this `False`; only an actual
cancellation via :meth:`cancel_generation` flips it.  Consumers holding
a computed MOT can use this to distinguish a genuine result from one
cut short (for example by a streaming requirement failure).

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `is_computed` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L513" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
is_computed(self) -> bool
```

Returns true only if this Thunk has already been filled.

**Returns:**

* `True` if the thunk value has been set, `False` otherwise.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `value` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L522" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
value(self) -> str | None
```

Gets the value of the block.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `value` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L529" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
value(self, v: str) -> None
```

Sets the value of the block.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `avalue` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L533" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
avalue(self) -> str
```

Returns the fully resolved value of the ModelOutputThunk, awaiting generation if necessary.

Can be used for both async streaming and async non-streaming backends. If the
thunk is already computed the value is returned immediately.

**Returns:**

* The complete text output from the model.

**Raises:**

* `Exception`: Propagates any errors from the underlying inference engine api request.
* `RuntimeError`: If called when the ModelOutputThunk's generate function is not async compatible.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `astream` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L562" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
astream(self) -> str
```

Returns only the NEW text fragment (delta) received since the last call.

This method is designed for streaming consumption where you want incremental
updates. Each call returns only the newly received content, not the accumulated
text. When streaming is complete, subsequent calls will raise RuntimeError.

**Note**: Be careful with calling this function. Only call it from one location at a time. This means you shouldn't pass a ModelOutputThunk to
multiple coroutines/tasks and call astream from those coroutines/tasks simultaneously. We have considered solutions to this but are waiting until
we see this error happen in a real use case.

**Returns:**

* Only the new text fragment received since the last call (delta), not the
  accumulated text. Returns empty string if no new content is available yet.

**Raises:**

* `Exception`: Propagates any errors from the underlying inference engine api request.
* `RuntimeError`: If called when the ModelOutputThunk's generate function is not async compatible,
  or if called after the thunk is already computed.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#4ADE8033]/20 text-[#15803D]">CLASS</span> `ComputedModelOutputThunk` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L786" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A `ComputedModelOutputThunk` is a `ModelOutputThunk` that is guaranteed to be computed.

This subclass provides a clear type distinction between thunks that may need awaiting
and those that are already computed. It should be returned from synchronous functions
and sampling strategies to indicate that no awaiting is needed.

Uses zero-copy class reassignment: calling `ComputedModelOutputThunk(thunk)` reassigns
the thunk's `__class__` to `ComputedModelOutputThunk` without creating a new object.

**Args:**

* `thunk`: A fully-computed `ModelOutputThunk` whose class will be reassigned.

<div className="h-8" />

**Methods:**

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `avalue` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L819" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
avalue(self) -> str
```

Return the value of the thunk. Use .value instead.

**Returns:**

* The computed string value.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `astream` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L828" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
astream(self) -> str
```

Cannot astream from ComputedModelOutputThunks. Use .value instead.

**Returns:**

* Never returns; always raises.

**Raises:**

* `RuntimeError`: Always, because computed thunks do not support streaming.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `value` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L843" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
value(self) -> str
```

Gets the value of the block.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `value` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L848" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
value(self, v: str)
```

Sets the value of the block.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `is_computed` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L852" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
is_computed(self) -> Literal[True]
```

Returns `True` since thunk is always computed.

**Returns:**

* Always `True`.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#4ADE8033]/20 text-[#15803D]">CLASS</span> `ContextTurn` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L862" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A turn of model input and model output.

**Args:**

* `model_input`: The input component or content block for this turn,
  or `None` for an output-only partial turn.
* `output`: The model's output thunk for this turn,
  or `None` for an input-only partial turn.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#4ADE8033]/20 text-[#15803D]">CLASS</span> `Context` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L880" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A `Context` is used to track the state of a `MelleaSession`.

A context is immutable. Every alteration leads to a new context.

**Attributes:**

* `is_root_node`: `True` when this context is the root (empty) node of the linked list.
* `previous_node`: The context node from which this one was created,
  or `None` for the root node.
* `node_data`: The data associated with this context node,
  or `None` for the root node.
* `is_chat_context`: Whether this context operates in chat (multi-turn) mode.

<div className="h-8" />

**Methods:**

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `from_previous` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L908" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
from_previous(cls: type[ContextT], previous: Context, data: Component | CBlock) -> ContextT
```

Constructs a new context node linked to an existing context node.

**Args:**

* `previous`: The existing context to extend.
* `data`: The component or content block to associate with the new node.

**Returns:**

* A new context instance whose `previous_node` is `previous`.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `reset_to_new` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L933" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
reset_to_new(cls: type[ContextT]) -> ContextT
```

Returns a new empty (root) context.

**Returns:**

* A freshly initialised root context with no data or history.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `is_root_node` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L944" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
is_root_node(self) -> bool
```

Returns whether this context is the root context node.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `previous_node` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L949" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
previous_node(self) -> Context | None
```

Returns the context node from which this context node was created.

Internal use: Users should not need to use this property.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `node_data` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L957" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
node_data(self) -> Component | CBlock | None
```

Returns the data associated with this context node.

Internal use: Users should not need to use this property.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `is_chat_context` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L965" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
is_chat_context(self) -> bool
```

Returns whether this context is a chat context.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `as_list` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L971" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
as_list(self, last_n_components: int | None = None) -> list[Component | CBlock]
```

Returns a list of context components sorted from earliest (first) to most recent (last).

If `last_n_components` is `None`, then all components are returned.

**Args:**

* `last_n_components`: Maximum number of most-recent components to include.
  Pass `None` to return the full history.

**Returns:**

* list\[Component | CBlock]: Components in chronological order (oldest first).

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `actions_for_available_tools` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L1006" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
actions_for_available_tools(self) -> list[Component | CBlock] | None
```

Provides a list of actions to extract tools from for use during generation.

Returns `None` if it is not possible to construct such a list. Can be used to make
the available tools differ from the tools of all the actions in the context. Can be
overridden by subclasses.

**Returns:**

* list\[Component | CBlock] | None: The list of actions whose tools should be made
* available during generation, or `None` if unavailable.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `last_output` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L1019" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
last_output(self, check_last_n_components: int = 3) -> ModelOutputThunk | None
```

Returns the most recent `ModelOutputThunk` found within the last N context components.

**Args:**

* `check_last_n_components`: Number of most-recent components to search through.
  Defaults to 3.

**Returns:**

* ModelOutputThunk | None: The most recent output thunk, or `None` if none is found
* within the searched components.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `last_turn` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L1035" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
last_turn(self) -> ContextTurn | None
```

The last input/output turn of the context.

This can be partial. If the last event is an input, then the output is None.

**Returns:**

* The most recent turn, or `None` if the context is empty.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `add` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L1062" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
add(self, c: Component | CBlock) -> Context
```

Returns a new context obtained by appending `c` to this context.

**Args:**

* `c`: The component or content block to add to the context.

**Returns:**

* A new context node with `c` as its data and this context as its previous node.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `view_for_generation` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L1075" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
view_for_generation(self) -> list[Component | CBlock] | None
```

Provides a linear list of context components to use for generation.

Returns `None` if it is not possible to construct such a list (e.g., the context
is in an inconsistent state). Concrete subclasses define the ordering and filtering logic.

**Returns:**

* list\[Component | CBlock] | None: An ordered list of components suitable for passing
* to a backend, or `None` if generation is not currently possible.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#4ADE8033]/20 text-[#15803D]">CLASS</span> `AbstractMelleaTool` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L1092" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Abstract base class for Mellea Tool with parameter and return type support.

**Attributes:**

* `name`: The unique name used to identify the tool in JSON descriptions and tool-call dispatch.
* `as_json_tool`: A JSON-serialisable description of the tool, compatible with
  the function-calling schemas expected by supported inference backends.

<div className="h-8" />

**Methods:**

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `run` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L1109" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
run(self, *args: P.args, **kwargs: P.kwargs) -> R
```

Executes the tool with the provided arguments and returns the result.

**Args:**

* `*args`: Positional arguments forwarded to the tool implementation.
* `**kwargs`: Keyword arguments forwarded to the tool implementation.

**Returns:**

* The result produced by the tool; the concrete type depends on the implementation.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `as_json_tool` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L1122" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
as_json_tool(self) -> dict[str, Any]
```

Provides a JSON description for Mellea Tool.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#4ADE8033]/20 text-[#15803D]">CLASS</span> `TemplateRepresentation` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L1127" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Representing a component as a set of important attributes that can be consumed by the formatter.

**Args:**

* `obj`: The original component object being represented.
* `args`: Named arguments extracted from the component for template substitution.
* `tools`: Tools available for this representation,
  keyed by the tool's function name. Defaults to `None`.
* `fields`: An optional ordered list of field values for positional templates.
* `template`: An optional Jinja2 template string to use when rendering.
* `template_order`: An optional ordering hint for template sections/keys.
* `images`: Optional list of image blocks associated with this representation.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#4ADE8033]/20 text-[#15803D]">CLASS</span> `GenerateLog` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L1157" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A dataclass for capturing log entries for a single generation call.

GenerateLog provides a structured way to include various details in log entries, making it useful for maintaining detailed
records of events or operations where context and additional data are significant.

**Args:**

* `date`: Timestamp when the generation was logged.
* `prompt`: The prompt string or chat-message list sent to the model.
* `backend`: Identifier of the inference backend used for this generation.
* `model_options`: Model configuration options applied to this call.
* `model_output`: The raw output returned by the backend API.
* `action`: The component or block that triggered the generation.
* `result`: The `ModelOutputThunk` produced by this generation call.
* `is_final_result`: Whether this log entry corresponds to the definitive final result.
* `extra`: Arbitrary extra metadata to attach to the log entry.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#4ADE8033]/20 text-[#15803D]">CLASS</span> `ModelToolCall` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L1188" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A dataclass for capturing the tool calls a model wants to make.

Provides a unified way to call tools post generation.

**Args:**

* `name`: The name of the tool the model requested to call.
* `func`: The `AbstractMelleaTool` instance that will be invoked.
* `args`: The keyword arguments the model supplied for the tool call.

<div className="h-8" />

**Methods:**

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />

#### <span className="ml-2 inline-flex items-center rounded-full px-2 py-1 text-[0.7rem] font-bold tracking-wide bg-[#3064E3]/20 text-[#1D4ED8]">FUNC</span> `call_func` <sup><a href="https://github.com/generative-computing/mellea/blob/v0.6.0/mellea/core/base.py#L1204" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python theme={null}
call_func(self) -> Any
```

Invokes the tool represented by this object and returns the result.

**Returns:**

* The value returned by `func.run(**args)`; the concrete type depends on the tool.

<div className="w-full h-px bg-gray-200 dark:bg-gray-700 my-4" />