nakul-bhai/group-chat

Crazy Ones Group Chat

A Hugging Face Space where 4 AI characters (Hakuo, Chika, Hyouka, Tomoko) independently decide whether to reply to user messages in a shared Discord group channel.

Architecture

Simple decentralized design — no central orchestrator, no complex framework. Just 4 independent "brains" that each make their own yes/no decision in parallel.

[Discord Group Channel]
    ↓ User sends message
[Discord Relay Bot] → POST /group-chat
    ↓
[HF Space Group Chat Server]
    ├─→ Agent 1 (Hakuo) — decides: reply? yes/no
    ├─→ Agent 2 (Chika) — decides: reply? yes/no
    ├─→ Agent 3 (Hyouka) — decides: reply? yes/no
    └─→ Agent 4 (Tomoko) — decides: reply? yes/no
    ↓
[SSE Stream] → replies back to Relay → posted to Discord

Tech Stack

• —Python 3.11
• —FastAPI (HTTP server)
• —asyncio (parallel agent decisions)
• —aiohttp (Qwen API client)
• —SQLite (conversation history per agent)
• —SSE (Server-Sent Events for real-time replies)

Quick Start

1. 1.Copy .env.example to .env and set your QWEN_API_KEY:

   cp .env.example .env

1. 1.Install dependencies:

   pip install -r requirements.txt

1. 1.Run the server:

   uvicorn main:app --host 0.0.0.0 --port 7860

API Endpoints

POST /group-chat

Receive a message from the Discord relay bot. Agents decide in parallel and replies stream via SSE.

{
  "message_id": "uuid",
  "user_id": "123456789",
  "username": "user",
  "message": "Hey everyone, what are you all up to?",
  "channel_id": "discord-channel-id",
  "timestamp": "2026-05-16T06:30:00Z"
}

GET /events

SSE stream for real-time agent replies. Connect your Discord relay bot here.

GET /health

Health check endpoint.

Deployment

Hugging Face Spaces (Docker)

1. 1.Create a new HF Space with Docker template
2. 2.Push all files to the space
3. 3.Set QWEN_API_KEY in Space secrets
4. 4.The space will build and start automatically

Environment Variables

File Structure

crazyones-group-hf/
├── main.py                    # FastAPI app, endpoints
├── config.py                  # Settings, Qwen API key
├── agents/
│   ├── hakuo.py              # Hakuo agent
│   ├── chika.py              # Chika agent
│   ├── hyouka.py             # Hyouka agent
│   ├── tomoko.py             # Tomoko agent
│   └── base_agent.py         # Shared Agent class
├── database/
│   └── db.py                 # SQLite + queries
├── services/
│   └── qwen_client.py        # Async OpenAI-compatible client
├── prompts/
│   ├── hakuo.xml
│   ├── chika.xml
│   ├── hyouka.xml
│   └── tomoko.xml
├── data/
│   └── group.db              # SQLite database (auto-created)
├── requirements.txt
├── Dockerfile
└── README.md

How It Works

1. 1.Parallel Decision Making: All 4 agents receive the message simultaneously and independently decide whether to reply using the Qwen API.
2. 2.Priority System: Each agent has a priority (Hakuo=8, Tomoko=7, Hyouka=6, Chika=5). Higher priority agents reply first.
3. 3.Cooldown: Agents won't reply again within 30 seconds of their last reply.
4. 4.Max Replies: Maximum 3 agents can reply to a single message to avoid spam.
5. 5.Staggered Delivery: Replies are staggered by 2-second delays based on priority order.
6. 6.Force Reply: If a message mentions an agent (e.g., @Hakuo, @Chika Ono, @Tomoko), that agent bypasses the decision and replies directly. Supports multiple name forms: @hakuo, @hyouka natsume, @natsume, @chika ono, @ono, etc.
7. 7.Shared History: All agents see the same last 12 messages, enabling them to react to what others said.
8. 8.Agent-to-Agent Replies: Agents can naturally reply to each other's messages in the chat history. This creates organic group chat dynamics where characters react to one another.
9. 9.Loop Prevention: Multiple safeguards prevent endless agent-to-agent chains:
10. 10.After 2+ consecutive agent replies, priority is reduced by 2
11. 11.After 3+ consecutive agent replies, agents are strongly told to stay silent unless directly addressed
12. 12.After 4+ consecutive agent replies, agents skip entirely (hard cutoff)
13. 13.The decision prompt explicitly instructs agents to let the user respond first when agents have been talking
14. 14.Messages are tagged with source: user or source: agent so the system tracks reply chains