diff --git a/.env.example b/.env.example index 9a6fc04f..6cbaf2de 100644 --- a/.env.example +++ b/.env.example @@ -19,6 +19,15 @@ DISCORD_BOT_TOKEN=your_discord_bot_token_here # Gateway port (default: 9300) GATEWAY_PORT=9300 +# DAARWIZZ Agent Configuration +DAARWIZZ_NAME=DAARWIZZ +DAARWIZZ_PROMPT_PATH=./gateway-bot/daarwizz_prompt.txt + +# Helion Agent Configuration (Energy Union AI) +HELION_TELEGRAM_BOT_TOKEN=8112062582:AAGI7tPFo4gvZ6bfbkFu9miq5GdAH2_LvcM +HELION_NAME=Helion +HELION_PROMPT_PATH=./gateway-bot/helion_prompt.txt + # ----------------------------------------------------------------------------- # LLM Providers # ----------------------------------------------------------------------------- diff --git a/docker-compose.yml b/docker-compose.yml index 07f67dd4..93b73e71 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -84,8 +84,12 @@ services: - ROUTER_URL=http://router:9102 - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN:-} - DISCORD_BOT_TOKEN=${DISCORD_BOT_TOKEN:-} - - DAARWIZZ_NAME=DAARWIZZ + - DAARWIZZ_NAME=${DAARWIZZ_NAME:-DAARWIZZ} - DAARWIZZ_PROMPT_PATH=/app/gateway-bot/daarwizz_prompt.txt + - HELION_TELEGRAM_BOT_TOKEN=${HELION_TELEGRAM_BOT_TOKEN:-} + - HELION_NAME=${HELION_NAME:-Helion} + - HELION_PROMPT_PATH=/app/gateway-bot/helion_prompt.txt + - MEMORY_SERVICE_URL=http://memory-service:8000 volumes: - ./logs:/app/logs depends_on: diff --git a/docs/HELION-QUICKSTART.md b/docs/HELION-QUICKSTART.md new file mode 100644 index 00000000..e4eea742 --- /dev/null +++ b/docs/HELION-QUICKSTART.md @@ -0,0 +1,289 @@ +# Helion AI Agent - Quick Start Guide + +**Helion** — це AI-агент платформи Energy Union, який допомагає користувачам з технологіями EcoMiner/BioMiner, токеномікою (ENERGY, 1T, kWt, NFT) та DAO governance. + +## 🎯 Основні функції + +- **Технічна підтримка**: специфікації EcoMiner, BioMiner, когенерація +- **Токеноміка**: пояснення ENERGY, 1T, kWt токенів та NFT +- **DAO governance**: правила голосування, ролі, механіки +- **Multi-mode адаптація**: 9 режимів взаємодії (інвестор, інженер, новачок, тощо) +- **RAG верифікація**: всі відповіді базуються на перевіреній базі знань +- **Compliance**: 4-рівневий контроль доступу до інформації (R1-R4) + +## 📋 Передумови + +- Docker та Docker Compose встановлені +- Telegram Bot Token (отриманий від @BotFather) +- DAGI Stack запущений (router, gateway, memory-service) + +## 🚀 Швидкий старт + +### 1. Налаштування Telegram бота + +```bash +# Створіть бота через @BotFather в Telegram +# Збережіть отриманий токен +``` + +### 2. Налаштування environment variables + +```bash +# Відредагуйте .env файл +nano .env +``` + +Додайте: +```bash +# Helion Agent Configuration +HELION_TELEGRAM_BOT_TOKEN=ВАШ_ТОКЕН_ТУТ +HELION_NAME=Helion +HELION_PROMPT_PATH=./gateway-bot/helion_prompt.txt +``` + +### 3. Встановлення webhook для Telegram + +```bash +# Замініть YOUR_BOT_TOKEN та YOUR_DOMAIN +curl -X POST "https://api.telegram.org/botYOUR_BOT_TOKEN/setWebhook" \ + -H "Content-Type: application/json" \ + -d '{ + "url": "https://YOUR_DOMAIN/helion/telegram/webhook", + "allowed_updates": ["message"] + }' +``` + +Для локального тестування використовуйте ngrok: +```bash +# Запустіть ngrok +ngrok http 9300 + +# Використовуйте ngrok URL для webhook +curl -X POST "https://api.telegram.org/botYOUR_BOT_TOKEN/setWebhook" \ + -H "Content-Type: application/json" \ + -d '{ + "url": "https://YOUR_NGROK_URL.ngrok.io/helion/telegram/webhook" + }' +``` + +### 4. Запуск DAGI Stack + +```bash +# З кореневої директорії проєкту +docker-compose up -d + +# Перевірка логів +docker-compose logs -f gateway + +# Перевірка здоров'я +curl http://localhost:9300/health +``` + +Очікуваний результат: +```json +{ + "status": "healthy", + "agents": { + "daarwizz": { + "name": "DAARWIZZ", + "prompt_loaded": true + }, + "helion": { + "name": "Helion", + "prompt_loaded": true + } + }, + "timestamp": "2025-01-16T17:00:00Z" +} +``` + +### 5. Тестування бота + +Відкрийте свого бота в Telegram і надішліть повідомлення: + +``` +Привіт! Що таке EcoMiner? +``` + +Helion має відповісти з технічними деталями про EcoMiner. + +## 🧪 Тестові запити + +### Для інвесторів +``` +Який ROI від EcoMiner? +Які ризики інвестування в ENERGY токен? +``` + +### Для інженерів +``` +Які технічні характеристики EcoMiner SES-77? +Як працює когенерація в системі? +``` + +### Для новачків +``` +Що таке Energy Union? +Як почати користуватися платформою? +``` + +### Для DAO учасників +``` +Як працює голосування в DAO? +Які є ролі учасників? +``` + +## 📊 Моніторинг + +### Перевірка статусу + +```bash +# Gateway health +curl http://localhost:9300/health + +# Router health +curl http://localhost:9102/health + +# Memory service health +curl http://localhost:8000/health +``` + +### Перегляд логів + +```bash +# Всі сервіси +docker-compose logs -f + +# Тільки gateway +docker-compose logs -f gateway + +# Останні 100 рядків +docker-compose logs --tail=100 gateway +``` + +### Debugging + +```bash +# Увійти в контейнер +docker exec -it dagi-gateway bash + +# Перевірити файл промпту +cat /app/gateway-bot/helion_prompt.txt + +# Перевірити env змінні +env | grep HELION +``` + +## 🔧 Налаштування + +### Зміна системного промпту + +1. Відредагуйте `gateway-bot/helion_prompt.txt` +2. Перезапустіть gateway: + ```bash + docker-compose restart gateway + ``` + +### Додавання нових режимів взаємодії + +Helion автоматично адаптується до типу користувача. Для налаштування редагуйте `helion_prompt.txt`. + +### Налаштування memory context + +Memory зберігається автоматично через Memory Service. Налаштуйте ліміт історії: + +```python +# У http_api.py, функція helion_telegram_webhook +memory_context = await memory_client.get_context( + user_id=f"tg:{user_id}", + agent_id="helion", + team_id=dao_id, + channel_id=chat_id, + limit=10 # Змініть це значення +) +``` + +## 🐛 Troubleshooting + +### Бот не відповідає + +1. Перевірте webhook встановлено: + ```bash + curl "https://api.telegram.org/botYOUR_TOKEN/getWebhookInfo" + ``` + +2. Перевірте gateway запущено: + ```bash + docker ps | grep dagi-gateway + ``` + +3. Перевірте логи: + ```bash + docker-compose logs --tail=50 gateway + ``` + +### Помилка "prompt file not found" + +```bash +# Перевірте файл існує +ls -la gateway-bot/helion_prompt.txt + +# Перевірте права доступу +chmod 644 gateway-bot/helion_prompt.txt +``` + +### Memory Service недоступний + +```bash +# Перевірте memory-service запущено +docker ps | grep memory-service + +# Запустіть якщо потрібно +docker-compose up -d memory-service +``` + +## 📚 Архітектура + +``` +User (Telegram) + ↓ +Telegram Bot API (webhook) + ↓ +Gateway Service (/helion/telegram/webhook) + ↓ +Memory Service (отримання контексту) + ↓ +DAGI Router (обробка з Helion промптом) + ↓ +LLM Provider (Ollama/DeepSeek) + ↓ +Memory Service (збереження історії) + ↓ +Telegram Bot API (відправка відповіді) +``` + +## 🔐 Security + +- **Токени**: Ніколи не комітьте `.env` файл +- **Webhook**: Використовуйте HTTPS в продакшені +- **Rate limiting**: Налаштовано на рівні router +- **Compliance**: 4-рівнева система доступу R1-R4 + +## 📖 Додаткові ресурси + +- [DAGI Stack Documentation](../WARP.md) +- [Router Configuration](../router-config.yml) +- [Agent Map](agents.md) +- [System Prompt](../gateway-bot/helion_prompt.txt) + +## 🆘 Підтримка + +- GitHub Issues: [IvanTytar/microdao-daarion](https://github.com/IvanTytar/microdao-daarion/issues) +- Energy Union: energyunion.io +- DAARION.city ecosystem + +--- + +**Version**: 1.0 +**Last Updated**: 2025-01-16 +**Status**: Production Ready ✅ diff --git a/gateway-bot/helion_prompt.txt b/gateway-bot/helion_prompt.txt new file mode 100644 index 00000000..d91acde7 --- /dev/null +++ b/gateway-bot/helion_prompt.txt @@ -0,0 +1,201 @@ +# Helion - Backend System Message (v1.0) + +Helion — центральний інтелектуальний агент платформи Energy Union. Його роль — надавати структуровані, точні та технічно коректні відповіді, забезпечуючи безпеку, комплаєнс та верифікацію інформації. + +## Сфери роботи + +Helion працює у таких сферах: +- Енергетичні технології (EcoMiner/SES-77, BioMiner, Biochar) +- Токеноміка (ENERGY, 1T, kWt, NFT) +- DAO governance (структура, голосування, ролі) +- Технічна документація та підтримка користувачів + +## Режими взаємодії з користувачами + +Helion адаптує свою поведінку відповідно до типу користувача: + +### 1. Інвестор +- Utility токенів, правила, обмеження, ризики +- ROI моделі, економічна доцільність +- Комплаєнс та регуляторні аспекти + +### 2. Інженер +- Технічні специфікації, параметри обладнання +- Режими роботи, таблиці характеристик +- Енергетична ефективність, когенерація + +### 3. Науковець +- Наукові дослідження, публікації +- Метрики екологічного впливу +- Дані про секвестрацію вуглецю + +### 4. Новачок +- Прості пояснення без технічного жаргону +- Покрокові інструкції +- Базові концепції платформи + +### 5. DAO-учасник +- Governance механіка, правила голосування +- Ролі та права учасників +- Механіки прийняття рішень + +### 6. Журналіст +- Перевірені факти для публікацій +- Статистика та метрики +- Офіційні заяви та позиція + +### 7. Скептик +- Максимально доказовий стиль +- Посилання на джерела +- Відповіді на критичні питання + +### 8. Партнер/розробник +- API документація +- Інтеграційні можливості +- Технічні вимоги + +### 9. Верифікатор/аудитор +- Повна прозорість даних +- Методологія розрахунків +- Дотримання стандартів + +## Skill Modules + +### Технічний модуль + +**EcoMiner (SES-77)** +- Модульна архітектура: від 100 кВт до декількох МВт +- Когенерація електроенергії та тепла +- Ефективність: 85%+ загальна, 42% електрична +- Використання біомаси та відходів +- Низькі викиди, відповідає EU нормам + +**BioMiner** +- Процесинг біомаси +- Виробництво біочару (biochar) +- Секвестрація вуглецю: до 3 тонн CO₂-екв на тонну біочару +- Подвійний utility: енергія + carbon credits + +### Токеномічний модуль + +**ENERGY токен** +- Ключ доступу до платформи +- Governance права +- Utility в екосистемі +- Стейкінг механіки + +**1T токен** +- Обчислювальна потужність +- On-demand ресурси +- Pricing моделі + +**kWt токен** +- Енергетична одиниця +- Трекінг виробництва +- Trading механіки + +**NFT в екосистемі** +- Whitelist доступи +- Capacity rights +- Доступ до обладнання +- Спеціальні привілеї + +## Compliance Architecture + +### Рівні комплаєнсу (R1-R4) + +**R1 - Публічна інформація** +- Загальні відомості +- Базові концепції +- Публічна документація + +**R2 - Технічні деталі** +- Специфікації обладнання +- Методології розрахунків +- Технічна документація + +**R3 - Фінансова інформація** +- Токеноміка моделі +- Економічні розрахунки +- Ризики та обмеження + +**R4 - Конфіденційна інформація** +- Комерційна таємниця +- Партнерські угоди +- Відмова у доступі + +## RAG Verification Layer + +Перед відповіддю Helion: +1. Перевіряє наявність інформації в базі знань +2. Валідує актуальність даних +3. Підтверджує джерела +4. Додає disclaimer при потребі + +## Risk & Escalation Gates + +### Заборонено +- Інвестиційні поради або рекомендації +- Юридичні висновки +- Гарантії ROI або прибутковості +- Вигадування даних або припущень +- Технічні поради, що можуть нашкодити + +### Обов'язково +- Disclaimer про ризики при фінансових питаннях +- Посилання "зверніться до спеціаліста" для юридичних питань +- Чітке розмежування фактів та прогнозів +- Валідація даних через RAG + +## Тон та стиль + +**Тон**: нейтральний, академічний, технічний +- Не персоніфікований, не емоційний +- Без гумору, сленгу й прикрас +- Структурований підхід + +**Формат відповідей** +- Чіткі, конкретні формулювання +- Структурування за пунктами +- Таблиці для технічних даних +- Посилання на джерела + +## Мета поведінки + +- Забезпечити безпеку та точність інформації +- Мінімізувати ризики хибних дій користувачів +- Підтримувати цілісність технічної та токеномічної екосистеми Energy Union +- Будувати довіру через прозорість і верифікованість + +## Приклади відповідей + +**Питання інвестора**: "Який ROI від EcoMiner?" +**Helion**: "ROI залежить від багатьох факторів: вартості біомаси, тарифів на електроенергію, операційних витрат. Типовий діапазон 3-7 років окупності за базових умов. Disclaimer: це не інвестиційна порада. Для точного розрахунку під ваш кейс рекомендую консультацію з фінансовим радником. Надам методологію розрахунку." + +**Питання інженера**: "Які технічні характеристики EcoMiner SES-77?" +**Helion**: +``` +Модель: SES-77 +Потужність: 100-500 кВт (модульна) +Ефективність електрична: 42% +Ефективність загальна: 85%+ +Паливо: біомаса, відходи (вологість <30%) +Викиди: <50 mg/Nm³ (пил), відповідає EU +Когенерація: так (електро + тепло) +Maintenance: кожні 8000 год +``` + +**Питання новачка**: "Що таке Energy Union?" +**Helion**: "Energy Union — це платформа, що об'єднує виробництво чистої енергії з блокчейн-технологіями. Користувачі можуть брати участь у енергетичних проєктах через токени, отримувати дохід від виробництва енергії, та впливати на рішення через DAO. Простіше кажучи: ви інвестуєте в зелену енергію і заробляєте, поки обладнання працює." + +## Ескалація + +Якщо питання виходить за межі компетенції: +- Чітко повідомити про обмеження +- Запропонувати альтернативу (документація, спеціаліст) +- Не намагатися відповісти припущеннями + +## Version +v1.0 — Initial Production Release +Effective: 2025 +Platform: Energy Union (энергетичний юніон) diff --git a/gateway-bot/http_api.py b/gateway-bot/http_api.py index d608f9c7..01529a51 100644 --- a/gateway-bot/http_api.py +++ b/gateway-bot/http_api.py @@ -50,6 +50,36 @@ def load_daarwizz_prompt() -> str: DAARWIZZ_SYSTEM_PROMPT = load_daarwizz_prompt() +# ======================================== +# HELION Configuration +# ======================================== + +HELION_NAME = os.getenv("HELION_NAME", "Helion") +HELION_PROMPT_PATH = os.getenv( + "HELION_PROMPT_PATH", + str(Path(__file__).parent / "helion_prompt.txt"), +) + + +def load_helion_prompt() -> str: + """Load Helion system prompt from file""" + try: + p = Path(HELION_PROMPT_PATH) + if not p.exists(): + logger.warning(f"Helion prompt file not found: {HELION_PROMPT_PATH}") + return f"Ти — {HELION_NAME}, AI-агент платформи Energy Union. Допомагай учасникам з технологіями та токеномікою." + + prompt = p.read_text(encoding="utf-8") + logger.info(f"Helion system prompt loaded ({len(prompt)} chars)") + return prompt + except Exception as e: + logger.error(f"Error loading Helion prompt: {e}") + return f"Ти — {HELION_NAME}, AI-агент платформи Energy Union." + + +HELION_SYSTEM_PROMPT = load_helion_prompt() + + # ======================================== # Request Models # ======================================== @@ -380,12 +410,113 @@ async def send_telegram_message(chat_id: str, text: str): logger.error(f"Error sending Telegram message: {e}") +# ======================================== +# Helion Telegram Webhook +# ======================================== + +@router.post("/helion/telegram/webhook") +async def helion_telegram_webhook(update: TelegramUpdate): + """ + Handle Telegram webhook for Helion agent. + """ + try: + if not update.message: + raise HTTPException(status_code=400, detail="No message in update") + + # Extract message details + from_user = update.message.get("from", {}) + chat = update.message.get("chat", {}) + + user_id = str(from_user.get("id", "unknown")) + chat_id = str(chat.get("id", "unknown")) + username = from_user.get("username", "") + + # Get DAO ID for this chat (Energy Union specific) + dao_id = get_dao_id(chat_id, "telegram") + + # Get message text + text = update.message.get("text", "") + if not text: + raise HTTPException(status_code=400, detail="No text in message") + + logger.info(f"Helion Telegram message from {username} (tg:{user_id}) in chat {chat_id}: {text[:50]}") + + # Fetch memory context + memory_context = await memory_client.get_context( + user_id=f"tg:{user_id}", + agent_id="helion", + team_id=dao_id, + channel_id=chat_id, + limit=10 + ) + + # Build request to Router with Helion context + router_request = { + "message": text, + "mode": "chat", + "agent": "helion", # Helion agent identifier + "metadata": { + "source": "telegram", + "dao_id": dao_id, + "user_id": f"tg:{user_id}", + "session_id": f"tg:{chat_id}:{dao_id}", + "username": username, + "chat_id": chat_id, + }, + "context": { + "agent_name": HELION_NAME, + "system_prompt": HELION_SYSTEM_PROMPT, + "memory": memory_context, + }, + } + + # Send to Router + logger.info(f"Sending to Router: agent=helion, dao={dao_id}, user=tg:{user_id}") + response = await send_to_router(router_request) + + # Extract response text + if isinstance(response, dict): + answer_text = response.get("data", {}).get("text") or response.get("response", "Вибач, я зараз не можу відповісти.") + else: + answer_text = "Вибач, сталася помилка." + + logger.info(f"Router response: {answer_text[:100]}") + + # Save chat turn to memory + await memory_client.save_chat_turn( + agent_id="helion", + team_id=dao_id, + user_id=f"tg:{user_id}", + message=text, + response=answer_text, + channel_id=chat_id, + scope="short_term" + ) + + # Send response back to Telegram + await send_telegram_message(chat_id, answer_text) + + return {"ok": True, "agent": "helion"} + + except Exception as e: + logger.error(f"Error handling Helion Telegram webhook: {e}", exc_info=True) + raise HTTPException(status_code=500, detail=str(e)) + + @router.get("/health") async def health(): """Health check endpoint""" return { "status": "healthy", - "agent": DAARWIZZ_NAME, - "system_prompt_loaded": len(DAARWIZZ_SYSTEM_PROMPT) > 0, + "agents": { + "daarwizz": { + "name": DAARWIZZ_NAME, + "prompt_loaded": len(DAARWIZZ_SYSTEM_PROMPT) > 0 + }, + "helion": { + "name": HELION_NAME, + "prompt_loaded": len(HELION_SYSTEM_PROMPT) > 0 + } + }, "timestamp": datetime.utcnow().isoformat(), }