# Plasma — Apache Superset Agent Automation

Фреймворк для программного управления Apache Superset через REST API. Создавай датасеты, визуализации и дашборды автоматически.

## 🚀 Быстрый старт

### 1. Установка

```bash
pip install -r requirements.txt
```

### 2. Конфигурация

Создай `.env` файл:

```env
SUPERSET_URL=http://localhost:8088
SUPERSET_USERNAME=admin
SUPERSET_PASSWORD=admin
SUPERSET_DATABASE_ID=1
```

### 3. Простой пример

```python
from src.superset_client import SupersetClient
from src.data_loader import DataLoader
from src.dashboard_composer import DashboardComposer

# Подключиться к Superset
client = SupersetClient(
    url="http://localhost:8088",
    username="admin",
    password="admin"
)

# Загрузить данные
loader = DataLoader()
df = loader.load_csv("data/sales.csv")

# Создать датасет
dataset = client.create_dataset(
    name="sales_data",
    database_id=1,
    table_name="sales",
    columns=df.columns.tolist()
)

# Создать чарты
bar_chart = client.create_chart(
    name="Sales by Region",
    dataset_id=dataset['id'],
    viz_type="bar",
    dimensions=["region"],
    metrics=["total_sales"]
)

# Собрать дашборд
dashboard = client.create_dashboard(
    name="Sales Dashboard",
    charts=[bar_chart]
)

print(f"Dashboard created: {dashboard['url']}")
```

## 📚 Документация

- [CONCEPT.md](./CONCEPT.md) — Полная концепция и архитектура
- [API_REFERENCE.md](./docs/API_REFERENCE.md) — Справка по API
- [EXAMPLES.md](./docs/EXAMPLES.md) — Примеры использования

## 🔧 Компоненты

| Модуль | Назначение |
|--------|-----------|
| `superset_client.py` | REST API клиент для Superset |
| `data_loader.py` | Загрузка данных (CSV, JSON, SQL) |
| `schema_builder.py` | Построение схемы датасета |
| `viz_templates.py` | Шаблоны визуализаций |
| `dashboard_composer.py` | Сборка дашбордов |
| `agent.py` | Оркестратор для OpenClaw |

## 🎯 Основные операции

### Создание датасета

```python
dataset = client.create_dataset(
    name="my_dataset",
    database_id=1,
    table_name="my_table",
    columns=["id", "date", "value"]
)
```

### Создание чарта

```python
chart = client.create_chart(
    name="My Chart",
    dataset_id=dataset['id'],
    viz_type="bar",  # bar, line, pie, table, scatter, heatmap
    dimensions=["category"],
    metrics=["sum__value"]
)
```

### Создание дашборда

```python
dashboard = client.create_dashboard(
    name="My Dashboard",
    charts=[chart1, chart2, chart3],
    layout={
        chart1['id']: {"x": 0, "y": 0, "w": 6, "h": 4},
        chart2['id']: {"x": 6, "y": 0, "w": 6, "h": 4},
        chart3['id']: {"x": 0, "y": 4, "w": 12, "h": 4}
    }
)
```

## ⚙️ Конфигурация

### Переменные окружения

```env
# Superset
SUPERSET_URL=http://localhost:8088
SUPERSET_USERNAME=admin
SUPERSET_PASSWORD=admin

# Database
SUPERSET_DATABASE_ID=1
SUPERSET_DATABASE_NAME=postgres

# API
SUPERSET_API_TIMEOUT=30
SUPERSET_API_RETRIES=3

# Logging
LOG_LEVEL=INFO
```

## 🐛 Troubleshooting

### Ошибка: "401 Unauthorized"
- Проверь username и password
- Убедись, что Superset доступен по URL
- Проверь права пользователя (должен быть Editor или Admin)

### Ошибка: "400 Bad Request"
- Проверь структуру JSON в запросе
- Убедись, что dataset_id существует
- Проверь типы данных (dimensions должны быть строки, metrics — числа)

### Ошибка: "404 Not Found"
- Проверь, что датасет/чарт/дашборд существует
- Убедись, что используешь правильный ID

## 📖 Примеры

### Пример 1: Простой дашборд с одним чартом

```python
from src.superset_client import SupersetClient

client = SupersetClient()
client.login()

# Создать датасет из существующей таблицы
dataset = client.create_dataset(
    name="users",
    database_id=1,
    table_name="users"
)

# Создать pie chart
chart = client.create_chart(
    name="Users by Status",
    dataset_id=dataset['id'],
    viz_type="pie",
    dimensions=["status"],
    metrics=["count"]
)

# Создать дашборд
dashboard = client.create_dashboard(
    name="User Analytics",
    charts=[chart]
)
```

### Пример 2: Дашборд с фильтрами

```python
# Создать дашборд с native filter
dashboard = client.create_dashboard(
    name="Sales Dashboard",
    charts=[chart1, chart2],
    filters=[
        {
            "name": "Region",
            "column": "region",
            "type": "select"
        }
    ]
)
```

### Пример 3: Загрузка CSV и создание дашборда

```python
from src.data_loader import DataLoader

loader = DataLoader()
df = loader.load_csv("sales.csv")

# Загрузить в Superset
dataset = client.create_dataset_from_dataframe(
    name="sales_data",
    dataframe=df,
    database_id=1
)

# Создать чарты
charts = [
    client.create_chart(
        name="Sales by Month",
        dataset_id=dataset['id'],
        viz_type="line",
        dimensions=["month"],
        metrics=["total_sales"]
    ),
    client.create_chart(
        name="Top Products",
        dataset_id=dataset['id'],
        viz_type="bar",
        dimensions=["product"],
        metrics=["quantity"]
    )
]

# Собрать дашборд
dashboard = client.create_dashboard(
    name="Sales Analytics",
    charts=charts
)
```

## 🔗 Полезные ссылки

- [Apache Superset Docs](https://superset.apache.org/)
- [Superset REST API](https://superset.apache.org/docs/api-documentation)
- [Preset.io (Managed Superset)](https://preset.io/)

## 📝 Лицензия

MIT

## 👤 Автор

Шакал (OpenClaw Agent)