Lumen Agent Framework

Lumen is an open-source, extensible agent-based framework designed for chatting with data and Retrieval Augmented Generation (RAG). It uses a declarative data model that allows LLMs to generate data transformation pipelines, visualizations, and dashboards.

Key Features:

• SQL Generation: Create pipelines for local/remote files, SQL databases, or data lakes.
• Context & Embeddings: Provide document access to LLMs for RAG.
• Data Visualization: Generate charts, tables, and dashboards via natural language.
• Inspection & Editing: Manually inspect, validate, and refine LLM outputs.
• Summarization: Extract insights and summarize results.
• Extensibility: Build custom agents, tools, and analyses tailored to specific domains.

Lumen is built on Panel, enabling it to render diverse output types with minimal effort.

The NYC Taxi dashboard is designed for million-row taxi trip analysis and includes the following capabilities:

• Large dataset handling: Efficiently processes millions of taxi trips.
• Geographic maps: Visualizes pickup and dropoff locations.
• Fare analysis: Displays the distribution of trip costs.
• Time filtering: Allows users to filter data by pickup time.

The Wind Turbines dashboard demonstrates several Lumen capabilities for visualizing performance metrics and geographic distribution:

• Geographic distribution: Visualizing turbine locations across the US.
• Performance metrics: Analyzing capacity and output.
• Manufacturer comparison: Comparing different turbine makers.
• Interactive filtering: Using filters for state, manufacturer, and capacity.

Lumen provides a suite of core AI components designed for building LLM-powered applications. The AI functionality is organized into four primary modules:

1. lumen.ai.llm: Interfaces for interacting with Large Language Models (LLMs).
2. lumen.ai.embeddings: Tools for generating and managing vector embeddings.
3. lumen.ai.vector_store: Interfaces and implementations for storing and querying vector data.
4. lumen.ai.utils: General utility functions supporting AI workflows.

Use these modules to orchestrate context management, model interaction, and retrieval-augmented generation (RAG) patterns within your application.

Lumen's API is organized into several functional modules. Depending on your task, you should refer to the following module documentation:

• AI Module: For working with AI-powered agents and analysis.
• Pipeline: For building and managing data pipeline components.
• Sources: For using data source connectors to ingest data.
• Transforms: For applying data transformation utilities.
• Views: For utilizing visualization components.

Lumen automatically provides several tools to agents to facilitate data discovery and searching. You do not need to configure these manually.

Automatic Tools:

• MetadataLookup: Finds relevant tables in your data.
• SourceLookup: Finds relevant external data source actions (added when a SourceAgent is present).
• list_indexed_documents and search_document_chunks: Used to search uploaded documents when a document vector store is present.

Manual Tool:

• DbtslLookup: Queries dbt Semantic Layer metrics. This is not automatic; you must explicitly pass it via the tools= argument in ExplorerUI to enable it.

The Precipitation dashboard demonstrates the following capabilities of Lumen:

• Geographic visualization: Visualizing precipitation patterns across the US.
• Time series: Analyzing historical precipitation trends.
• Regional analysis: Comparing data across different geographic areas.

The Python API mirrors the YAML structure using specific classes. Use these classes to build your dashboard programmatically:

Lumen allows you to create reproducible dashboards using YAML. A specification defines sources (data locations), pipelines (data transformations and filters), and layouts (the visual arrangement of views).

Example YAML structure:

sources:
  penguins:
    type: file
    tables:
      data: https://datasets.holoviz.org/penguins/v1/penguins.csv

pipelines:
  filtered:
    source: penguins
    table: data
    filters:
      - type: widget
        field: species
      - type: widget
        field: island

layouts:
  - title: Palmer Penguins Dashboard
    pipeline: filtered
    views:
      - type: hvplot
        kind: scatter
        x: bill_length_mm
        y: bill_depth_mm
        color: species
      - type: hvplot
        kind: hist
        y: body_mass_g
      - type: table

Lumen organizes work into Explorations, which act as saved workspaces for specific datasets or analysis threads.

An Exploration automatically captures:

• Conversation history
• Generated SQL queries
• Charts and visualizations
• Resulting data tables

Behavioral Rules:

• Context Retention: Follow-up questions (e.g., "Can you make that chart show only the top 5?") stay within the same exploration.
• Automatic Separation: Asking about a different dataset or an unrelated topic triggers the creation of a new exploration.
• Persistence: Explorations can be returned to later or exported as Jupyter notebooks.