NaturalLanguageBIViewerAgent

Versions

• 0.1.0

v0.1.0

Basic Information

Class Name: NaturalLanguageBIViewerAgent

Title: Natural Language BI Viewer Agent

Version: 0.1.0

Author: Dennis Towns

Organization: OneStream

Creation Date: 2026-01-22

Default Routine Memory Capacity: 2.0 GB

Tags

Agent, LLM, Data Analysis

Description

Short Description

Create and edit OneStream BI Viewer dashboards using natural language.

Long Description

The Natural Language BI Viewer Agent accelerates BI Viewer dashboard creation and editing by translating a user's natural language requests into BI Viewer dashboard structure changes. Given the current BI Viewer dashboard structure, the connected data adapter context (e.g., column definitions), and prior conversation history, the agent can generate new BI Viewer components (charts/visuals) or refine existing ones. This enables an interactive, chat-driven authoring experience where users can iteratively collaborate with an LLM while keeping the underlying dashboard definition as the source of truth.

Use Cases

1. BI Viewer Dashboard Creation

Create BI Viewer dashboards and charts from natural language. The agent uses the connected data adapter context (such as column definitions) plus the current BI Viewer dashboard structure to propose and apply changes that build new visuals, adjust existing visuals, and organize content into a coherent story. Users can describe what they want to see (metrics, breakdowns, time periods, comparisons, filters, and layout preferences) in plain language, and the agent responds by updating the dashboard structure to match. This is intended to speed up dashboard authoring, reduce trial-and-error, and help non-technical users reach a useful dashboard without needing to understand how BI Viewer dashboards are assembled behind the scenes.

2. BI Viewer Dashboard Editing (Interactive Refinement)

Iteratively refine an existing BI Viewer dashboard through a chat-style workflow. Users can ask for changes such as swapping measures, changing chart types, adding or removing series, adjusting sorting, updating titles, tweaking formatting, or re-arranging visuals on the page. The agent updates the underlying dashboard structure while preserving the existing intent and keeping prior context in mind, enabling an efficient back-and-forth that feels like collaborating with an analyst. This is especially useful when a dashboard is close to correct but needs incremental improvements, when stakeholders request quick edits, or when a user wants to explore multiple alternative views of the same data without rebuilding the dashboard from scratch.

3. Administrator-Driven Dashboard Configuration

Enable administrators to configure a BI Viewer dashboard via natural language and then publish a static dashboard for end users. In this workflow, an administrator describes the audience, the key questions the dashboard should answer, and any required views (for example: executive summary, trend view, variance view, and regional breakdown). The agent then helps the administrator shape the dashboard structure so it is ready for broad consumption. This supports a 'build once, consume broadly' approach where the admin can rapidly iterate during setup, then deliver a consistent, high-quality dashboard experience for many users who may only need to view and interact with the finished result.

Routine Methods

1. Init (Constructor)

• Method: __init__

  • Type: Constructor

  • Allow In-Memory Execution: No

  • Read Only: No

  • Method Limits: There are no method limits for the constructor as it simply sets the member variables.

  • Outputs Dynamic Artifacts: No

  • Short Description:

    • Initialize the NLBI Viewer Agent.

  • Detailed Description:

    • This constructor is used to initialize the NLBI Viewer Agent with the dashboard and workspace IDs (GUIDs) selected by the user.

  • Inputs:

    • Required Input
      • Workspace: The OneStream workspace selected by the user.
        • Name: workspace_id
        • Tooltip:
          • Validation Constraints:
            • This input may be subject to other validation constraints at runtime.
        • Type: str
      • BI Dashboard: The BI Viewer Dashboard component selected by the user.
        • Name: bi_dashboard_id
        • Tooltip:
          • Validation Constraints:
            • This input may be subject to other validation constraints at runtime.
        • Type: str
      • Agent Memory Capacity: Optional memory (in GB) to reserve for each agent run, overriding the routine default. Leave blank to use the default.
        • Name: agent_memory_capacity
        • Tooltip:
          • Validation Constraints:
            • The input must be greater than or equal to 1.
            • This input may be subject to other validation constraints at runtime.
        • Type: Optional[int]

  • Artifacts: No artifacts are returned by this method

2. Restore To Checkpoint (Method)

• Method: restore_to_checkpoint

  • Type: Method

  • Memory Capacity: 1.0 GB

  • Allow In-Memory Execution: No

  • Read Only: No

  • Method Limits: Lightweight -- one Dataflow fetch, in-memory truncation, no LLM call. Should complete in well under a second in normal conditions.

  • Outputs Dynamic Artifacts: No

  • Short Description:

    • Rewind the dashboard layout and conversation history to a past post-state checkpoint.

  • Detailed Description:

    • The target checkpoint is the post-state of an earlier assistant reply -- the layout the user saw rendered alongside that reply. Restoring leaves the assistant reply visible as the new tip of the chat thread; the user prompt that triggered the next (now-undone) run is returned so the chat adapter can place it back in the input textarea. Sequences the destructive restore in this order: 1. fetch_dashboard + apply_layout. Captures any concurrent external edit that landed between when the user clicked Restore and when this rmethod ran. If such an edit sits AFTER the target checkpoint, step 2 will refuse to drop it (external edits are immutable). 2. truncate_after_checkpoint(target). Raises RestoreWouldDestroyExternalEditError if any external-origin checkpoint sits past the target. 3. load_checkpoint(target). Sets the target XML as live and recomputes report_layout_bytes_base64 (utf-8-sig) so the next apply_layout no-ops. 4. truncate_conversation_at_checkpoint. Slices conversation_history to end at (and INCLUDE) the assistant turn carrying the target post-state checkpoint id, and extracts the immediate-next user turn's content as the recovered prompt. This rmethod does NOT save to Dataflow. The chat adapter is responsible for renewing the dashboard lock and calling save_dashboard_layout with the modified_xml carried in the returned artifact.

  • Inputs:

    • Required Input
      • Checkpoint Id: UUID of the layout checkpoint to restore to.
        • Name: checkpoint_id
        • Tooltip:
          • Validation Constraints:
            • The input must have a minimum length of 1.
            • The input must have a maximum length of 200.
            • This input may be subject to other validation constraints at runtime.
        • Type: str

  • Artifacts:

    • NLBI Viewer Agent Checkpoint Restore Result: The XML and checkpoint id produced by a restore_to_checkpoint run.
      • Qualified Key Annotation: result
      • Aggregate Artifact: False
      • In-Memory Json Accessible: True
      • File Annotations:
        • artifacts_/@result/data_/data.json
          • Stored json data.
        • artifacts_/@result/data_/schema.json
          • The json schema of the json object stored in the 'data.json' file

3. Run (Method)

• Method: run

  • Type: Method

  • Memory Capacity: 4.0 GB

  • Allow In-Memory Execution: No

  • Read Only: No

  • Method Limits: Fetches a single dashboard row and one varbinary column from Dataflow. LLM latency dominates; typical runtime is a few seconds to under a minute depending on request complexity and the number of tool calls issued by the agent.

  • Outputs Dynamic Artifacts: No

  • Short Description:

    • Run the NLBI Viewer Agent.

  • Detailed Description:

    • Fetches the latest dashboard layout and adapter column definitions, refreshes the embedding vector store for any changed adapters, then invokes the NLBIV agent to satisfy the user's natural language request. The agent mutates self.dashboard in-place via its tool calls; the before/after XML and the agent's plain-language summary are returned in the artifact.

  • Inputs:

    • Required Input
      • Natural Language Request: Natural language request to modify the dashboard (XML) for the selected BI Dashboard.
        • Name: user_request
        • Tooltip:
          • Validation Constraints:
            • The input must have a minimum length of 1.
            • The input must have a maximum length of 1000.
            • This input may be subject to other validation constraints at runtime.
        • Type: str

  • Artifacts:

    • NLBI Viewer Agent Result: A basic JSON response from the NLBI Viewer Agent routine.
      • Qualified Key Annotation: result
      • Aggregate Artifact: False
      • In-Memory Json Accessible: True
      • File Annotations:
        • artifacts_/@result/data_/data.json
          • Stored json data.
        • artifacts_/@result/data_/schema.json
          • The json schema of the json object stored in the 'data.json' file

Interface Definitions

No interface definitions found for this routine

Developer Docs

Routine Typename: NaturalLanguageBIViewerAgent

Method Name	Artifact Keys
__init__	N/A
restore_to_checkpoint	result
run	result