Others
======

Utility components for annotation, date/time, conversation history, and structured output parsing.

----

.. _component-ref-notes:

Notes
-----

A non-executable annotation node. Use it to add comments, labels, or documentation to sections of the canvas without affecting flow execution.

**Use in a flow**

1. Add a **Notes** node anywhere on the canvas.
2. Click the pencil icon on the node to edit its description.
3. Write your notes using plain text or Markdown.

Notes do not accept inputs, produce outputs, or run during flow execution.

**Markdown support**

The description field supports Markdown: headings (``#``), bold (``**text**``), italic (``*text*``), bullet lists (``- item``), and links (``[text](url)``).

**Parameters, inputs, and outputs**

Notes has no configurable parameters, inputs, or outputs. All content lives in the editable description on the node.

**Limitations**

- **Non-executable** — Notes never run and cannot be wired to other components.
- **Canvas-only** — Content is visible on the flow canvas; it is not passed to agents or downstream steps.

----

.. _component-ref-current-date:

Current Date
------------

Outputs the current date and time in a selected timezone. Wire the result into Prompt components, conditions, or agents that need time-aware context.

**Use in a flow**

1. Add a **Current Date** node to the canvas.
2. Select a **Timezone** (defaults to UTC).
3. Connect **Current Date** output to a Prompt, If-Else, Agent, or other downstream component.

.. code-block:: text

   Current Date (Current Date) ──► Prompt ──► Agent

**Parameters**

.. list-table::
   :widths: 30 10 10 50
   :header-rows: 1

   * - Parameter
     - Default
     - Hidden
     - Description
   * - Timezone
     - UTC
     - No
     - Timezone used when formatting the current date and time.

**Outputs**

.. list-table::
   :widths: 25 75
   :header-rows: 1

   * - Output
     - Description
   * - Current Date
     - A message with the current date and time in the selected timezone.

**Limitations**

- **Runtime value** — The timestamp is generated when the node runs, not when the flow is saved.
- **Message format** — Output is a single text message; use a Parser or downstream logic for different formats.

----

.. _component-ref-message-history:

Message History
---------------

Retrieves stored conversation messages for the current or specified session. Use it to inject chat history into Prompt templates, provide context to an Agent, or pass prior turns to downstream steps.

**Use in a flow**

1. Add a **Message History** node to the canvas.
2. Optionally connect an **External Memory** component; if left empty, messages are read from the platform's session storage.
3. Adjust filters (sender type, message count, order) as needed.
4. Connect **Data**, **Message**, or **DataFrame** output to the next step.

.. code-block:: text

   Message History (Message) ──► Prompt ──► Agent

**Parameters**

.. list-table::
   :widths: 30 10 10 50
   :header-rows: 1

   * - Parameter
     - Default
     - Hidden
     - Description
   * - External Memory
     - —
     - No
     - Optional memory component to read from. When empty, uses platform session message storage.
   * - Sender Type
     - Machine and User
     - Yes
     - Filter by ``Machine``, ``User``, or both.
   * - Sender Name
     - —
     - Yes
     - Filter messages by a specific sender name.
   * - Number of Messages
     - 20
     - Yes
     - Maximum number of messages to retrieve. Set to ``0`` to return none.
   * - Session ID
     - —
     - Yes
     - Session to read from. When empty, uses the current session.
   * - Order
     - Descending
     - Yes
     - ``Ascending`` (oldest first) or ``Descending`` (newest first).
   * - Template
     - {sender_name}: {text}
     - Yes
     - Format for the **Message** output. Supports ``{text}``, ``{sender}``, ``{sender_name}``, and other message fields.

**Outputs**

.. list-table::
   :widths: 25 75
   :header-rows: 1

   * - Output
     - Description
   * - Data
     - Retrieved messages as a list of message objects.
   * - Message
     - Messages formatted as a single text string using the **Template**.
   * - DataFrame
     - Messages as a table for filtering or further processing.

**Limitations**

- **Session scope** — Without **Session ID**, only messages from the active session are returned.
- **Storage dependency** — History depends on messages being stored during the conversation (e.g., **Store Messages** enabled on **Input**).

----

.. _component-ref-structured-output:

Structured Output
-----------------

Parses text into a defined JSON schema using a connected language model. Use it to extract fields from agent responses, normalize LLM output, or produce consistent data objects for downstream steps.

**Use in a flow**

1. Add a **Structured Output** node to the canvas.
2. Connect a **Language Model** component to **Language Model**.
3. Wire the text to parse into **Input Message** (for example, from an **Agent** or **Input**).
4. Define fields in **Output Schema** (name, type, description per field).
5. Connect **Structured Output** or **DataFrame** to the next step.

.. code-block:: text

   Agent (response) ──► Structured Output ◄── Language Model
   Structured Output (Structured Output) ──► Data Operations / Output

**Parameters**

.. list-table::
   :widths: 30 10 10 50
   :header-rows: 1

   * - Parameter
     - Default
     - Hidden
     - Description
   * - Language Model
     - —
     - No
     - LLM used to extract and format structured data. Must support structured output. Required.
   * - Input Message
     - —
     - No
     - Text to parse into the defined schema. Required.
   * - Output Schema
     - one ``field`` row
     - No
     - Table defining output fields: **Name**, **Description**, and **Type** (``str``, ``int``, ``float``, ``bool``, ``dict``). Required.
   * - Format Instructions
     - built-in default
     - Yes
     - System instructions telling the model how to extract and format values.
   * - Schema Name
     - —
     - Yes
     - Name for the output schema model (defaults to ``OutputModel`` when empty).

**Output Schema fields**

Each row in **Output Schema** defines one property on the output object:

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Column
     - Description
   * - Name
     - Key in the resulting JSON object.
   * - Description
     - What the field represents; guides the model during extraction.
   * - Type
     - Data type: ``str``, ``int``, ``float``, ``bool``, or ``dict``.

**Outputs**

.. list-table::
   :widths: 25 75
   :header-rows: 1

   * - Output
     - Description
   * - Structured Output
     - Parsed results as Data (JSON objects under ``results``).
   * - DataFrame
     - Parsed results as a table; multiple objects become multiple rows.

**Limitations**

- **Model support** — The connected **Language Model** must support structured output.
- **Schema required** — **Output Schema** cannot be empty.
- **Extraction quality** — Accuracy depends on the model, **Format Instructions**, and input text clarity.