lumen-ai

What this skill does

# Lumen AI Skill

## Overview

Lumen AI is an open-source, agent-based framework for conversational data exploration. Users ask questions in plain English and receive visualizations, SQL queries, and insights automatically generated by large language models.

### What is Lumen AI?

Lumen AI translates natural language queries into:
- SQL queries for database exploration
- Interactive visualizations
- Statistical summaries
- Custom domain-specific analyses
- Data-driven insights

### Key Features

- **Natural Language Interface**: Ask questions in plain English
- **Multi-LLM Support**: OpenAI, Anthropic, Google, Mistral, local models
- **Agent Architecture**: Specialized agents for SQL, charts, analyses
- **Extensible**: Custom agents, tools, and analyses
- **Privacy-Focused**: Full local deployment option
- **No Vendor Lock-in**: Switch LLM providers with configuration change

### Lumen AI vs Lumen Dashboards

| Feature | Lumen AI | Lumen Dashboards |
|---------|----------|------------------|
| **Interface** | Conversational, natural language | Declarative YAML |
| **Use Case** | Ad-hoc exploration, varying questions | Fixed dashboards, repeated views |
| **Users** | Non-technical users, self-service | Developers, dashboard builders |
| **Cost** | LLM API costs | No LLM costs |
| **Flexibility** | High - generates any query | Fixed - predefined views |

**Use Lumen AI when**:
- Users need ad-hoc data exploration
- Questions vary and aren't predictable
- Enabling self-service analytics
- Reducing analyst backlog

**Use Lumen Dashboards when**:
- Dashboard structure is fixed
- Same visualizations needed repeatedly
- No LLM costs desired
- Full control over outputs needed

## Quick Start

### Installation

```bash
# Install Lumen with AI support
pip install lumen[ai]

# Install LLM provider (choose one or more)
pip install openai        # OpenAI
pip install anthropic     # Anthropic Claude
```

### Launch Built-in Interface

```bash
# Set API key
export OPENAI_API_KEY="sk-..."

# Launch with dataset
lumen-ai serve data/sales.csv

# Or with database
lumen-ai serve "postgresql://user:pass@localhost/mydb"
```

### Python API - Basic Example

```python
import lumen.ai as lmai
import panel as pn
from lumen.sources.duckdb import DuckDBSource

pn.extension()

# Configure LLM
lmai.llm.llm_type = "anthropic"
lmai.llm.model = "claude-3-5-sonnet-20241022"

# Load data
source = DuckDBSource(
    tables=["./data/sales.csv", "./data/customers.csv"]
)

# Create UI
ui = lmai.ExplorerUI(
    source=source,
    title="Sales Analytics AI"
)

ui.servable()
```

### Example Queries

Once running, try queries like:
- "What tables are available?"
- "Show me total sales by region"
- "Create a scatter plot of price vs quantity"
- "What were the top 10 products last month?"
- "Calculate average order value per customer"

## Core Concepts

### 1. Agents

Specialized components that handle specific tasks:

- **TableListAgent**: Shows available tables and schemas
- **ChatAgent**: General conversation and summaries
- **SQLAgent**: Generates and executes SQL queries
- **hvPlotAgent**: Creates interactive visualizations
- **VegaLiteAgent**: Publication-quality charts
- **AnalysisAgent**: Custom domain-specific analyses

**See**: [Built-in Agents Reference](../../resources/lumen-ai/agents-reference.md) for complete agent documentation.

### 2. LLM Providers

Lumen AI works with multiple LLM providers:

**Cloud Providers**:
- OpenAI (GPT-4o, GPT-4o-mini)
- Anthropic (Claude 3.5 Sonnet, Claude 3 Opus/Haiku)
- Google (Gemini 1.5 Pro/Flash)
- Mistral (Mistral Large/Medium/Small)

**Local Models**:
- Ollama (Llama 3.1, Mistral, CodeLlama)
- LlamaCPP (custom models)

**See**: [LLM Provider Configuration](../../resources/lumen-ai/llm-providers.md) for setup details and provider comparison.

### 3. Memory and Context

Agents share a memory system:
- Query results persist across interactions
- Agents can build on previous work
- Context maintained throughout conversation

### 4. Tools

Extend agent capabilities:
- **DocumentLookup**: RAG for document context
- **TableLookup**: Schema and metadata access
- **Custom Tools**: External APIs, calculations, etc.

**See**: [Custom Tools Guide](../../resources/lumen-ai/custom-tools.md) for building tools.

## Common Patterns

### Pattern 1: Basic Analytics Interface

```python
import lumen.ai as lmai
from lumen.sources.duckdb import DuckDBSource

# Configure LLM
lmai.llm.llm_type = "openai"
lmai.llm.model = "gpt-4o"

# Load data
source = DuckDBSource(tables=["sales.csv"])

# Create UI
ui = lmai.ExplorerUI(
    source=source,
    title="Business Analytics"
)

ui.servable()
```

### Pattern 2: With Document Context (RAG)

```python
source = DuckDBSource(
    tables=["sales.csv", "products.parquet"],
    documents=[
        "./docs/data_dictionary.pdf",
        "./docs/business_rules.md"
    ]
)

ui = lmai.ExplorerUI(
    source=source,
    tools=[lmai.tools.DocumentLookup]
)
```

Agents will automatically search documents for context when needed.

### Pattern 3: Custom Agent

```python
from lumen.ai.agents import Agent
import param

class SentimentAgent(Agent):
    """Analyze sentiment in text data."""

    requires = param.List(default=["current_source"])
    provides = param.List(default=["sentiment_analysis"])

    purpose = """
    Analyzes sentiment in text columns.
    Use when user asks about sentiment, emotions, or tone.
    Keywords: sentiment, emotion, positive, negative, tone
    """

    async def respond(self, query: str):
        # Agent implementation
        source = self.memory["current_source"]
        # ... analyze sentiment ...
        yield "Sentiment analysis results..."

# Use custom agent
ui = lmai.ExplorerUI(
    source=source,
    agents=[SentimentAgent, lmai.agents.ChatAgent]
)
```

**See**: [Custom Agents Guide](../../resources/lumen-ai/custom-agents.md) for detailed development guide.

### Pattern 4: Custom Analysis

```python
from lumen.ai.analyses import Analysis
from lumen.pipeline import Pipeline
import param

class CohortAnalysis(Analysis):
    """Customer cohort retention analysis."""

    columns = param.List(default=[
        'customer_id', 'signup_date', 'purchase_date'
    ])

    def __call__(self, pipeline: Pipeline):
        # Cohort analysis logic
        df = pipeline.data
        # ... calculate cohorts ...
        return results

# Register analysis
ui = lmai.ExplorerUI(
    source=source,
    agents=[
        lmai.agents.AnalysisAgent(analyses=[CohortAnalysis])
    ]
)
```

**See**: [Custom Analyses Guide](../../resources/lumen-ai/custom-analyses.md) for examples.

### Pattern 5: Multi-Source Data

```python
from lumen.sources.duckdb import DuckDBSource

source = DuckDBSource(
    tables={
        "sales": "./data/sales.parquet",
        "customers": "./data/customers.csv",
        "products": "https://data.company.com/products.csv"
    }
)

ui = lmai.ExplorerUI(source=source)
```

## Configuration

### LLM Selection

Quick reference for choosing LLM:

| Use Case | Provider | Model | Why |
|----------|----------|-------|-----|
| Production analytics | OpenAI | gpt-4o | Best balance |
| Complex SQL | Anthropic | claude-3-5-sonnet | Superior reasoning |
| High volume | OpenAI | gpt-4o-mini | Cost-effective |
| Sensitive data | Ollama | llama3.1 | Local only |
| Development | OpenAI | gpt-4o-mini | Fast, cheap |

**See**: [LLM Provider Configuration](../../resources/lumen-ai/llm-providers.md) for complete setup.

### Agent Selection

```python
# Use only specific agents
agents = [
    lmai.agents.TableListAgent,
    lmai.agents.SQLAgent,
    lmai.agents.hvPlotAgent,
    # Exclude VegaLiteAgent if not needed
]

ui = lmai.ExplorerUI(source=source, agents=agents)
```

### Coordinator Types

**DependencyResolver** (default): Recursively resolves agent dependencies
```python
ui = lmai.ExplorerUI(source=source, coordinator="dependency")
```

**Planner**: Creates execution plan upfront
```python
ui = lmai.ExplorerU