docs: Add comprehensive DAARWIZZ documentation
Complete guide for DAARWIZZ AI agent: - Personality and behavior guidelines - Technical implementation details - Message flow diagrams - Example interactions (Ukrainian) - Testing instructions - Customization guide - Future enhancements roadmap Includes curl examples, Docker config, and monitoring metrics.
This commit is contained in:
Ivan Tytar
342
docs/DAARWIZZ.md
Normal file
342
docs/DAARWIZZ.md
Normal file
@@ -0,0 +1,342 @@
|
|||||||
|
# DAARWIZZ - AI Agent for DAARION.city
|
||||||
|
|
||||||
|
**DAARWIZZ** is the official AI agent for the DAARION.city ecosystem, designed to help community members navigate microDAO processes, understand roles, and interact with the DAGI Stack.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 What is DAARWIZZ?
|
||||||
|
|
||||||
|
DAARWIZZ is an intelligent agent that:
|
||||||
|
- **Guides users** through microDAO operations
|
||||||
|
- **Explains roles** and permissions (RBAC)
|
||||||
|
- **Answers questions** about DAO processes
|
||||||
|
- **Provides onboarding** for new members
|
||||||
|
- **Enforces security** by respecting user entitlements
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🧠 Personality & Behavior
|
||||||
|
|
||||||
|
### Core Traits
|
||||||
|
- **Helpful**: Provides practical, actionable guidance
|
||||||
|
- **Concise**: Avoids unnecessary explanations
|
||||||
|
- **Security-aware**: Respects RBAC permissions
|
||||||
|
- **Honest**: Admits when it doesn't know something
|
||||||
|
- **Professional yet friendly**: Approachable but not casual
|
||||||
|
|
||||||
|
### Style Guidelines
|
||||||
|
- Short paragraphs, no fluff
|
||||||
|
- Step-by-step instructions when needed
|
||||||
|
- Uses numbered lists for procedures
|
||||||
|
- Always considers user's role and permissions
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📋 System Prompt
|
||||||
|
|
||||||
|
DAARWIZZ's behavior is defined by its system prompt located at:
|
||||||
|
```
|
||||||
|
gateway-bot/daarwizz_prompt.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
**Key elements:**
|
||||||
|
1. Identity: Official DAARION.city AI agent
|
||||||
|
2. Role: Help with microDAO, roles, processes
|
||||||
|
3. Context awareness: Uses dao_id, user_id, RBAC data
|
||||||
|
4. Limitations: No legal/financial/medical advice
|
||||||
|
5. Knowledge boundaries: Only DAARION/microDAO topics
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔄 How DAARWIZZ Works
|
||||||
|
|
||||||
|
### Message Flow
|
||||||
|
|
||||||
|
```
|
||||||
|
User (Telegram)
|
||||||
|
↓ "Привіт! Що це за DAO?"
|
||||||
|
Gateway (:9300)
|
||||||
|
↓ Load daarwizz_prompt.txt
|
||||||
|
↓ Build request with agent="daarwizz"
|
||||||
|
Router (:9102)
|
||||||
|
↓ Fetch RBAC context
|
||||||
|
RBAC (:9200)
|
||||||
|
↓ role: member, entitlements: [chat, vote, comment]
|
||||||
|
Router
|
||||||
|
↓ Inject RBAC + system_prompt
|
||||||
|
LLM Provider (Ollama/OpenAI)
|
||||||
|
↓ Generate response with full context
|
||||||
|
Gateway
|
||||||
|
↓ Send to Telegram
|
||||||
|
User receives answer
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🛠️ Technical Implementation
|
||||||
|
|
||||||
|
### Gateway Integration
|
||||||
|
|
||||||
|
**File**: `gateway-bot/http_api.py`
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Load DAARWIZZ prompt on startup
|
||||||
|
DAARWIZZ_SYSTEM_PROMPT = load_daarwizz_prompt()
|
||||||
|
|
||||||
|
# Build request to Router
|
||||||
|
router_request = {
|
||||||
|
"prompt": text,
|
||||||
|
"mode": "chat",
|
||||||
|
"agent": "daarwizz", # Agent identifier
|
||||||
|
"metadata": {
|
||||||
|
"dao_id": "greenfood-dao",
|
||||||
|
"user_id": "tg:12345",
|
||||||
|
...
|
||||||
|
},
|
||||||
|
"context": {
|
||||||
|
"agent_name": "DAARWIZZ",
|
||||||
|
"system_prompt": DAARWIZZ_SYSTEM_PROMPT,
|
||||||
|
# RBAC injected by Router
|
||||||
|
},
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### LLM Provider Support
|
||||||
|
|
||||||
|
**File**: `providers/llm_provider.py`
|
||||||
|
|
||||||
|
```python
|
||||||
|
def _get_system_prompt(self, req: RouterRequest) -> Optional[str]:
|
||||||
|
# 1. Check context.system_prompt (from Gateway)
|
||||||
|
context = req.payload.get("context") or {}
|
||||||
|
if "system_prompt" in context:
|
||||||
|
return context["system_prompt"]
|
||||||
|
|
||||||
|
# 2. Agent-specific fallback
|
||||||
|
if req.agent == "daarwizz":
|
||||||
|
return "Ти — DAARWIZZ, AI-агент DAARION.city..."
|
||||||
|
|
||||||
|
return None
|
||||||
|
```
|
||||||
|
|
||||||
|
### Docker Configuration
|
||||||
|
|
||||||
|
**File**: `gateway-bot/Dockerfile`
|
||||||
|
|
||||||
|
```dockerfile
|
||||||
|
# Copy DAARWIZZ prompt
|
||||||
|
COPY gateway-bot/daarwizz_prompt.txt /app/gateway-bot/daarwizz_prompt.txt
|
||||||
|
|
||||||
|
ENV DAARWIZZ_NAME=DAARWIZZ
|
||||||
|
ENV DAARWIZZ_PROMPT_PATH=/app/gateway-bot/daarwizz_prompt.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📖 Example Interactions
|
||||||
|
|
||||||
|
### Basic Greeting
|
||||||
|
|
||||||
|
**User**: `Привіт! Хто ти?`
|
||||||
|
|
||||||
|
**DAARWIZZ**:
|
||||||
|
```
|
||||||
|
Привіт! Я — DAARWIZZ, AI-агент екосистеми DAARION.city.
|
||||||
|
|
||||||
|
Я допомагаю учасникам розібратися з:
|
||||||
|
• microDAO та їх структурою
|
||||||
|
• Ролями і правами доступу (RBAC)
|
||||||
|
• Процесами голосування та пропозиціями
|
||||||
|
• Завданнями та винагородами
|
||||||
|
|
||||||
|
Чим можу допомогти?
|
||||||
|
```
|
||||||
|
|
||||||
|
### Role Information
|
||||||
|
|
||||||
|
**User**: `Які у мене права в цьому DAO?`
|
||||||
|
|
||||||
|
**DAARWIZZ** (with RBAC context):
|
||||||
|
```
|
||||||
|
У greenfood-dao ти маєш роль: member
|
||||||
|
|
||||||
|
Твої права (entitlements):
|
||||||
|
1. chat_access - писати в чат
|
||||||
|
2. read_proposals - читати пропозиції
|
||||||
|
3. vote - голосувати за пропозиції
|
||||||
|
4. comment - коментувати
|
||||||
|
|
||||||
|
Для більших прав (наприклад, створення пропозицій) потрібна роль contributor або вища.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Onboarding
|
||||||
|
|
||||||
|
**User**: `Як розпочати роботу в DAO?`
|
||||||
|
|
||||||
|
**DAARWIZZ**:
|
||||||
|
```
|
||||||
|
Ласкаво просимо! Ось кроки для старту:
|
||||||
|
|
||||||
|
1. Ознайомся з документацією DAO (команда /docs)
|
||||||
|
2. Переглянь активні пропозиції (/proposals)
|
||||||
|
3. Познайомся з командою в чаті
|
||||||
|
4. Виконай перше завдання (/tasks)
|
||||||
|
5. Накопичуй репутацію для підвищення ролі
|
||||||
|
|
||||||
|
Твоя поточна роль: guest
|
||||||
|
Наступна роль: member (після 1 виконаного завдання)
|
||||||
|
|
||||||
|
Є питання? Запитуй!
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎛️ Customization
|
||||||
|
|
||||||
|
### Updating System Prompt
|
||||||
|
|
||||||
|
1. **Edit prompt file**:
|
||||||
|
```bash
|
||||||
|
nano gateway-bot/daarwizz_prompt.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Rebuild Gateway**:
|
||||||
|
```bash
|
||||||
|
docker-compose build gateway
|
||||||
|
docker-compose restart gateway
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Verify loading**:
|
||||||
|
```bash
|
||||||
|
docker-compose logs gateway | grep "DAARWIZZ system prompt loaded"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Environment Variables
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# .env
|
||||||
|
DAARWIZZ_NAME=DAARWIZZ
|
||||||
|
DAARWIZZ_PROMPT_PATH=/app/gateway-bot/daarwizz_prompt.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🧪 Testing DAARWIZZ
|
||||||
|
|
||||||
|
### Local Test (curl)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -X POST http://localhost:9300/telegram/webhook \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{
|
||||||
|
"message": {
|
||||||
|
"message_id": 1,
|
||||||
|
"from": {"id": 12345, "username": "testuser"},
|
||||||
|
"chat": {"id": 12345, "type": "private"},
|
||||||
|
"text": "Привіт! Хто ти?"
|
||||||
|
}
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
### Telegram Bot
|
||||||
|
|
||||||
|
1. **Set up webhook**:
|
||||||
|
```bash
|
||||||
|
curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
|
||||||
|
-d "url=https://your-domain.com/telegram/webhook"
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Send message** to bot in Telegram
|
||||||
|
|
||||||
|
3. **Check logs**:
|
||||||
|
```bash
|
||||||
|
docker-compose logs -f gateway router
|
||||||
|
```
|
||||||
|
|
||||||
|
### Expected Log Output
|
||||||
|
|
||||||
|
```
|
||||||
|
gateway | INFO: DAARWIZZ system prompt loaded (1243 chars)
|
||||||
|
gateway | INFO: Telegram message from testuser (tg:12345): Привіт! Хто ти?
|
||||||
|
gateway | INFO: Sending to Router: agent=daarwizz, dao=greenfood-dao
|
||||||
|
router | INFO: Received request: mode=chat, agent=daarwizz
|
||||||
|
router | INFO: RBAC context: role=member, entitlements=4
|
||||||
|
router | INFO: Routing to llm_local_qwen3_8b
|
||||||
|
router | INFO: Response generated (345 chars, 2.3s)
|
||||||
|
gateway | INFO: Telegram message sent to chat 12345
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 Metrics & Monitoring
|
||||||
|
|
||||||
|
### Health Check
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl http://localhost:9300/health
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "healthy",
|
||||||
|
"agent": "DAARWIZZ",
|
||||||
|
"system_prompt_loaded": true,
|
||||||
|
"timestamp": "2024-11-15T14:30:00Z"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Performance Targets
|
||||||
|
|
||||||
|
| Metric | Target | Notes |
|
||||||
|
|--------|--------|-------|
|
||||||
|
| Prompt loading | < 100ms | On startup |
|
||||||
|
| Request enrichment | < 50ms | Gateway processing |
|
||||||
|
| End-to-end response | < 5s | Including LLM generation |
|
||||||
|
| RBAC lookup | < 100ms | From RBAC service |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 Future Enhancements
|
||||||
|
|
||||||
|
### Phase 4 Roadmap
|
||||||
|
|
||||||
|
1. **Knowledge Base Integration**
|
||||||
|
- Connect to microdao-daarion docs
|
||||||
|
- RAG (Retrieval-Augmented Generation)
|
||||||
|
- Contextual answers from official docs
|
||||||
|
|
||||||
|
2. **Multi-language Support**
|
||||||
|
- Ukrainian (default)
|
||||||
|
- English
|
||||||
|
- Auto-detect user language
|
||||||
|
|
||||||
|
3. **Workflow Triggers**
|
||||||
|
- User: "Onboard me" → triggers CrewAI workflow
|
||||||
|
- User: "Review proposal #123" → triggers multi-agent review
|
||||||
|
|
||||||
|
4. **Analytics**
|
||||||
|
- Track common questions
|
||||||
|
- Identify knowledge gaps
|
||||||
|
- Improve prompt iteratively
|
||||||
|
|
||||||
|
5. **Personalization**
|
||||||
|
- Remember user context across sessions
|
||||||
|
- Adapt responses based on user role
|
||||||
|
- Suggest relevant actions
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔗 Related Documentation
|
||||||
|
|
||||||
|
- [Gateway Bot](../gateway-bot/README.md)
|
||||||
|
- [RBAC Service](../microdao/README.md)
|
||||||
|
- [LLM Providers](../providers/README.md)
|
||||||
|
- [Router Configuration](../router-config.yml)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Version**: 0.2.0
|
||||||
|
**Agent**: DAARWIZZ
|
||||||
|
**Status**: Production-ready ✅
|
||||||
|
**Last Updated**: 2024-11-15
|
||||||
Reference in New Issue
Block a user