lumen-ai

# 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.

### 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

### When to Use Lumen AI

| Feature | Lumen AI | Lumen Dashboards |
|---------|----------|------------------|
| **Interface** | Conversational | Declarative YAML |
| **Use Case** | Ad-hoc exploration | Fixed dashboards |
| **Users** | Non-technical | Developers |

**Use Lumen AI when**: Users need ad-hoc exploration, questions vary unpredictably, enabling self-service analytics.

**Use Lumen Dashboards when**: Dashboard structure is fixed, no LLM costs desired.

## Quick Start

### Installation

```bash
pip install lumen[ai]
pip install openai  # or anthropic for Claude
```

### Launch Built-in Interface

```bash
export OPENAI_API_KEY="sk-..."
lumen-ai serve data/sales.csv
# Or with database
lumen-ai serve "postgresql://user:pass@localhost/mydb"
```

### Python API

```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"])

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

### Example Queries

- "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?"

## Core Concepts

### 1. Agents

Specialized components that handle specific ta