ZeroAgent

AI community leader for the CloudForet-io open-source project. Responds to member questions on Discord, welcomes new members, and routes people to the right resources.

Development methodology: AIDLC (AI-Driven Development Lifecycle)

Features

Bolt 001 ✅

• Discord mention and keyword-based auto-replies
• Per-channel response policies (active / passive / readonly)
• Escalation guidance for security, bugs, and complex questions
• Welcome messages for new members
• Docker deployment support

Bolt 002 ✅

• RAG pipeline (local Markdown + GitHub README)
• Vector search for relevant context injection
• Automatic source citations in responses
• Index build via zeroagent-index CLI
• Static KB fallback when the index is missing

Bolt 003 ✅

• Auto-posted channel guide messages (guide_enabled)
• FAQ embed creation and pinning (faq_enabled)
• Duplicate-post prevention via state file
• Automatic recovery of deleted guides and FAQs

Bolt 004 ✅

• Prometheus metrics (/metrics)
• Health checks (/health, /ready)
• Helm chart (Kubernetes deployment)
• ServiceMonitor (Prometheus Operator)

Architecture

knowledge/*.md ──┐
config/sources ──├──▶ zeroagent-index ──▶ .zeroagent/index.json
                 │
Discord ──▶ ZeroAgentBot ──▶ ResponseAgent ──▶ RAG Retriever ──▶ LLM

Quick Start

1. Create a Discord Bot

1. Create an application in the Discord Developer Portal
2. Bot tab → copy the token
3. Enable Privileged Gateway Intents: MESSAGE CONTENT INTENT, SERVER MEMBERS INTENT
4. OAuth2 → URL Generator → bot scope → invite to your server

2. Configure Environment

cp .env.example .env

Edit .env:

DISCORD_BOT_TOKEN=your_token
LLM_API_KEY=your_openai_key          # optional when using a local LLM
LLM_BASE_URL=http://localhost:11434/v1  # Ollama example
LLM_MODEL=llama3.2

Local LLM (Ollama, etc.)

Local servers that expose an OpenAI-compatible API work without LLM_API_KEY.

# After starting Ollama
ollama pull llama3.2
ollama pull nomic-embed-text

# .env
DISCORD_BOT_TOKEN=...
LLM_API_KEY=
LLM_BASE_URL=http://localhost:11434/v1
LLM_MODEL=llama3.2
EMBEDDING_MODEL=nomic-embed-text
RAG_ENABLED=true

3. Channel Policies

Register Discord channel IDs in config/channels.yaml:

channels:
  "1234567890":
    mode: active
    persona: support          # see config/personas.yaml
  "2345678901":
    mode: active
    persona: general
    guide_enabled: true
    guide_template: welcome
    faq_enabled: true
    description: "#general"

Channel Personas

Each channel can have a different purpose. Define personas in config/personas.yaml and reference them with the persona key in channels.yaml.

Available personas: default, support, general, welcome, announcements, alpha, contributors

# config/channels.yaml
channels:
  "1234567890":
    mode: active
    persona: general
    description: "#general"
  "2345678901":
    mode: active
    persona: alpha
    description: "#alpha"

Override persona instructions per channel with persona_instructions:

persona: support
persona_instructions: |
  This channel is for enterprise customers. Keep a polite and formal tone.

FAQ content is managed in config/faq.yaml.

4. Build RAG Index

pip install -e ".[dev]"
zeroagent-index

Configure local document paths and GitHub README sources in config/sources.yaml.

5. Run

Docker:

docker compose up -d

Local:

pip install -e ".[dev]"
zeroagent

Kubernetes (Helm)

# Build and push image
docker build -t your-registry/zeroagent:0.4.0 .
docker push your-registry/zeroagent:0.4.0

# Install
helm install zeroagent deploy/helm/zeroagent \
  --set image.repository=your-registry/zeroagent \
  --set secrets.discordBotToken=$DISCORD_BOT_TOKEN \
  --set secrets.llmApiKey=$LLM_API_KEY \
  --set metrics.serviceMonitor.enabled=true

Observability Endpoints

Endpoint	Purpose
GET /health	Liveness probe
GET /ready	Readiness (Discord connected)
GET /metrics	Prometheus metrics

Key metrics: zeroagent_messages_received_total, zeroagent_responses_sent_total, zeroagent_llm_requests_total, zeroagent_response_duration_seconds

AIDLC Artifacts

This project was planned and built using the AIDLC methodology.

Phase	Artifact	Path
Inception	Intent	aidlc/inception/intent.md
Inception	Units	aidlc/inception/units.md
Inception	Stories	aidlc/inception/stories.md
Inception	Bolt Plan 001	aidlc/inception/bolt-plan-001.md
Inception	Bolt Plan 002	aidlc/inception/bolt-plan-002.md
Inception	Bolt Plan 003	aidlc/inception/bolt-plan-003.md
Inception	Bolt Plan 004	aidlc/inception/bolt-plan-004.md
Construction	Domain Model	aidlc/construction/domain-model.md
Operations	Runbook	aidlc/operations/runbook.md

Project Structure

zeroagent/
├── aidlc/                  # AIDLC artifacts
├── config/                 # Channel policy configuration
├── knowledge/              # Static knowledge base
├── src/zeroagent/
│   ├── domain/             # Domain models and services
│   ├── application/        # Use cases and agent logic
│   ├── infrastructure/     # Discord and LLM adapters
│   └── prompts/            # System prompts
├── tests/
├── Dockerfile
└── docker-compose.yml

Testing

pip install -e ".[dev]"
pytest

Roadmap

Bolt	Feature
001 ✅	MVP Discord bot, static KB, channel policies
002 ✅	RAG pipeline (local docs + GitHub README)
003 ✅	Auto channel guide, FAQ pinning
004 ✅	K8s Helm chart, Prometheus metrics

License

Apache 2.0 — CloudForet Community