# Plasma — Apache Superset Agent Automation Framework

**Дата:** 2026-04-27  
**Статус:** Концепция  
**Цель:** Автоматизированное создание датасетов, визуализаций и дашбордов в Apache Superset через REST API с помощью агентов OpenClaw.

---

## 🎯 Общая идея

Plasma — это фреймворк для программного управления Superset через API. Вместо ручного кликания в UI, агент:
1. Загружает данные (CSV, JSON, SQL)
2. Регистрирует датасеты
3. Создаёт визуализации (чарты)
4. Собирает их в дашборды
5. Публикует и управляет доступом

**Ключевое преимущество:** Воспроизводимость, версионирование, масштабируемость.

---

## 📋 Архитектура

```
Plasma Framework
├── API Client (superset_client.py)
│   ├── Authentication (JWT tokens)
│   ├── Database management
│   ├── Dataset CRUD
│   ├── Chart CRUD
│   └── Dashboard CRUD
├── Data Loader (data_loader.py)
│   ├── CSV/JSON parser
│   ├── SQL query executor
│   └── Data validation
├── Schema Builder (schema_builder.py)
│   ├── Column type detection
│   ├── Metric definitions
│   └── Filter configuration
├── Visualization Templates (viz_templates.py)
│   ├── Time series
│   ├── Bar charts
│   ├── Pie charts
│   ├── Tables
│   └── Custom viz configs
├── Dashboard Composer (dashboard_composer.py)
│   ├── Layout grid management
│   ├── Filter linking
│   └── Responsive design
└── Agent Orchestrator (agent.py)
    ├── Workflow automation
    ├── Error handling
    └── Logging & monitoring
```

---

## 🔄 Workflow (Пошаговый процесс)

### Фаза 1: Подготовка
1. **Подключение к Superset**
   - Получить JWT токен (логин/пароль или API key)
   - Проверить доступность API
   - Получить список доступных БД

2. **Подготовка данных**
   - Загрузить CSV/JSON или подключиться к SQL
   - Валидировать структуру
   - Определить типы колонок (dimension, metric, temporal)

### Фаза 2: Регистрация датасета
1. **Создать датасет в Superset**
   - POST `/api/v1/dataset/` с метаданными
   - Получить dataset_id
   - Настроить column properties (temporal, filterable, dimensional)

2. **Определить метрики**
   - Создать virtual metrics (SUM, COUNT, AVG)
   - Создать calculated columns (если нужны)

### Фаза 3: Создание визуализаций
1. **Для каждого чарта:**
   - Выбрать тип визуализации (bar, line, pie, table)
   - Определить dimensions (группировка)
   - Определить metrics (значения)
   - Настроить фильтры и сортировку
   - POST `/api/v1/chart/` с конфигом
   - Получить chart_id

### Фаза 4: Сборка дашборда
1. **Создать дашборд**
   - POST `/api/v1/dashboard/` с title и description
   - Получить dashboard_id

2. **Добавить чарты на дашборд**
   - Определить layout (grid positions)
   - Связать фильтры между чартами
   - PUT `/api/v1/dashboard/{id}` с position_json

3. **Публикация**
   - Установить published=true
   - Настроить permissions (RBAC)
   - Сгенерировать public URL (если нужен)

---

## 📚 Глоссарий (Правильная терминология)

| Термин | Определение | Пример |
|--------|------------|---------|
| **Database** | Подключение к источнику данных (PostgreSQL, MySQL, BigQuery и т.д.) | `postgres_prod`, `bigquery_analytics` |
| **Dataset** (Slice в старых версиях) | Таблица или SQL query, зарегистрированная в Superset для анализа | `sales_data`, `user_metrics` |
| **Column** | Поле в датасете | `date`, `revenue`, `region` |
| **Dimension** | Категориальная колонка для группировки (не агрегируется) | `product_category`, `region`, `date` |
| **Metric** | Числовая колонка для агрегации (SUM, COUNT, AVG) | `total_sales`, `user_count`, `avg_price` |
| **Virtual Metric** | Вычисляемая метрика (SQL выражение) | `SUM(revenue) / COUNT(orders)` |
| **Calculated Column** | Вычисляемая колонка (SQL выражение) | `CAST(price AS FLOAT)`, `UPPER(name)` |
| **Chart** (Slice) | Визуализация одного датасета с конкретной конфигурацией | Bar chart по регионам, Time series по дням |
| **Visualization Type** | Тип отображения данных | `bar`, `line`, `pie`, `table`, `scatter`, `heatmap` |
| **Dashboard** | Коллекция чартов на одной странице с фильтрами | `Sales Dashboard`, `KPI Monitor` |
| **Filter** | Ограничение данных по значению колонки | `region = 'Moscow'`, `date >= 2026-01-01` |
| **Native Filter** | Фильтр на уровне дашборда (связывает несколько чартов) | Dropdown с выбором региона |
| **Adhoc Filter** | Временный фильтр, добавленный пользователем в UI | Фильтр, добавленный при просмотре |
| **Position JSON** | JSON с координатами чартов на дашборде (x, y, width, height) | `{"CHART-1": {"x": 0, "y": 0, "w": 6, "h": 4}}` |
| **Slice** | Старое название для Chart (в некоторых API ещё используется) | Синоним Chart |
| **Explore** | UI для создания чартов (no-code builder) | Интерфейс Superset для визуализации |
| **SQL Lab** | IDE для написания SQL queries | Место для подготовки данных |
| **Certification** | Отметка датасета/метрики как проверенной | Значок ✓ рядом с названием |
| **Owner** | Пользователь, создавший объект (датасет, чарт, дашборд) | Может редактировать и удалять |
| **Permission** | Права доступа (view, edit, delete) | RBAC (Role-Based Access Control) |
| **RBAC** | Role-Based Access Control — управление доступом по ролям | admin, editor, viewer |
| **JWT Token** | JSON Web Token для аутентификации в API | Bearer token для запросов |
| **API Endpoint** | URL для API запроса | `/api/v1/dataset/`, `/api/v1/chart/` |

---

## 🛠️ Требуемые компоненты

### 1. **Superset Instance**
- Версия: 3.0+ (с полноценным REST API v1)
- Доступ: HTTP/HTTPS с аутентификацией
- Требования: БД для хранения метаданных (PostgreSQL рекомендуется)

### 2. **API Credentials**
- Username & Password (или API key)
- JWT токен (получается при логине)
- Права: минимум Editor или Admin

### 3. **Data Source**
- CSV файлы
- JSON API
- SQL БД (PostgreSQL, MySQL, BigQuery и т.д.)
- Parquet, Excel и т.д.

### 4. **Python Libraries**
```
requests          # HTTP клиент
pandas            # Работа с данными
sqlalchemy        # SQL queries
pydantic          # Валидация данных
python-dotenv     # Конфиг из .env
```

### 5. **OpenClaw Integration**
- Skill для управления Superset
- Агент для оркестрации workflow
- Хранилище конфигов (YAML/JSON)

---

## ⚠️ Возможные сложности

### 1. **Аутентификация**
- **Проблема:** JWT токены имеют TTL (обычно 1 час)
- **Решение:** Автоматический refresh токена перед истечением
- **Код:** Сохранять refresh_token, использовать для получения нового access_token

### 2. **Типизация данных**
- **Проблема:** Superset может неправильно определить тип колонки (дата как строка)
- **Решение:** Явно указывать `is_dttm=true` для datetime колонок
- **Код:** При создании датасета передавать column_types

### 3. **Производительность больших датасетов**
- **Проблема:** Загрузка 1GB+ данных может зависнуть
- **Решение:** Использовать SQL query вместо загрузки файла, или батчить данные
- **Код:** Создавать датасет как `SELECT * FROM table` вместо CSV upload

### 4. **Связь фильтров между чартами**
- **Проблема:** Native filters требуют правильной конфигурации target_slice_id
- **Решение:** Сначала создать все чарты, потом добавлять фильтры
- **Код:** Использовать dashboard_filters с правильными mapping'ами

### 5. **Layout и responsive дизайн**
- **Проблема:** Position JSON может не масштабироваться на мобильных
- **Решение:** Использовать grid-based layout (12 колонок), тестировать на разных размерах
- **Код:** Стандартные размеры: 6x4 (half-width), 12x4 (full-width)

### 6. **Версионирование конфигов**
- **Проблема:** Если изменить чарт в UI, API конфиг устаревает
- **Решение:** Хранить конфиги в Git, использовать export/import
- **Код:** Регулярно экспортировать дашборды через API

### 7. **Ошибки валидации**
- **Проблема:** API возвращает 400 с неясным сообщением об ошибке
- **Решение:** Логировать полный request/response, использовать Postman для отладки
- **Код:** Добавить verbose logging для всех API запросов

### 8. **Кэширование**
- **Проблема:** Чарты кэшируются, изменения видны не сразу
- **Решение:** Использовать `cache_timeout=0` для dev, или вручную очищать кэш
- **Код:** При обновлении датасета вызывать refresh endpoint

---

## 🚀 Фазы реализации

### Phase 1: MVP (Неделя 1)
- [ ] Базовый API клиент (auth, CRUD для dataset/chart/dashboard)
- [ ] Загрузка CSV в датасет
- [ ] Создание простого bar chart
- [ ] Сборка дашборда с одним чартом

### Phase 2: Расширение (Неделя 2)
- [ ] Поддержка всех типов визуализаций
- [ ] Native filters и их связь
- [ ] Virtual metrics и calculated columns
- [ ] Управление permissions

### Phase 3: Автоматизация (Неделя 3)
- [ ] OpenClaw skill для Plasma
- [ ] Агент для оркестрации workflow
- [ ] YAML конфиги для дашбордов
- [ ] Версионирование и export/import

### Phase 4: Оптимизация (Неделя 4)
- [ ] Кэширование и производительность
- [ ] Обработка ошибок и retry logic
- [ ] Документация и примеры
- [ ] Тестирование на больших датасетах

---

## 📖 Лучшие практики (из исследования)

1. **Структурируй данные перед загрузкой**
   - Очисти NULL значения
   - Нормализуй типы данных
   - Удали дубликаты

2. **Используй SQL queries вместо файлов для больших данных**
   - Быстрее
   - Меньше памяти
   - Можно использовать фильтры на уровне БД

3. **Создавай метрики на уровне датасета**
   - Переиспользуй их в разных чартах
   - Гарантирует консистентность
   - Упрощает обновление

4. **Группируй чарты по смыслу на дашборде**
   - Top row: KPI (числа)
   - Middle: Trends (time series)
   - Bottom: Details (tables)

5. **Используй native filters для связи чартов**
   - Лучше UX
   - Меньше API запросов
   - Синхронизация автоматическая

6. **Версионируй конфиги в Git**
   - Export дашборды как YAML
   - Отслеживай изменения
   - Легко откатываться

7. **Тестируй на разных размерах экрана**
   - Desktop: 12 колонок
   - Tablet: 8 колонок
   - Mobile: 4 колонки

8. **Документируй метрики и фильтры**
   - Добавляй description в датасет
   - Используй Markdown widgets на дашборде
   - Помогает новым пользователям

---

## 🔗 API Endpoints (Краткая справка)

```
# Authentication
POST   /api/v1/security/login
POST   /api/v1/security/refresh

# Databases
GET    /api/v1/database/
POST   /api/v1/database/
GET    /api/v1/database/{id}
PUT    /api/v1/database/{id}

# Datasets
GET    /api/v1/dataset/
POST   /api/v1/dataset/
GET    /api/v1/dataset/{id}
PUT    /api/v1/dataset/{id}
DELETE /api/v1/dataset/{id}
GET    /api/v1/dataset/{id}/samples

# Charts
GET    /api/v1/chart/
POST   /api/v1/chart/
GET    /api/v1/chart/{id}
PUT    /api/v1/chart/{id}
DELETE /api/v1/chart/{id}

# Dashboards
GET    /api/v1/dashboard/
POST   /api/v1/dashboard/
GET    /api/v1/dashboard/{id}
PUT    /api/v1/dashboard/{id}
DELETE /api/v1/dashboard/{id}

# Export/Import
GET    /api/v1/dashboard/export/
POST   /api/v1/dashboard/import/
```

---

## 📁 Структура проекта

```
plasma/
├── CONCEPT.md                 # Этот файл
├── README.md                  # Инструкция по использованию
├── requirements.txt           # Python зависимости
├── .env.example              # Пример конфига
├── src/
│   ├── superset_client.py    # API клиент
│   ├── data_loader.py        # Загрузка данных
│   ├── schema_builder.py     # Построение схемы
│   ├── viz_templates.py      # Шаблоны визуализаций
│   ├── dashboard_composer.py # Сборка дашбордов
│   └── agent.py              # Оркестратор
├── examples/
│   ├── simple_dashboard.py   # Простой пример
│   ├── sales_dashboard.py    # Пример с продажами
│   └── configs/
│       ├── dashboard.yaml    # Конфиг дашборда
│       └── charts.yaml       # Конфиги чартов
├── tests/
│   ├── test_client.py
│   ├── test_loader.py
│   └── test_composer.py
└── docs/
    ├── API_REFERENCE.md
    ├── TROUBLESHOOTING.md
    └── EXAMPLES.md
```

---

## 🎓 Следующие шаги

1. **Создать базовый API клиент** (`superset_client.py`)
2. **Написать примеры** (simple_dashboard.py)
3. **Создать OpenClaw skill** для интеграции
4. **Документировать** API и best practices
5. **Тестировать** на реальном Superset инстансе

---

**Автор:** Шакал (OpenClaw Agent)  
**Дата создания:** 2026-04-27  
**Версия:** 0.1 (Концепция)