Metadata-Version: 2.4
Name: qd-evolve
Version: 0.1.0
Summary: Multi-agent AI framework with A2A protocol support, group chat, persistent memory, and extensible tool system
Project-URL: Homepage, https://github.com/juzcn/qd-evolve
Project-URL: Repository, https://github.com/juzcn/qd-evolve
Project-URL: Issues, https://github.com/juzcn/qd-evolve/issues
Author-email: juzcn <zhangjun@cueb.edu.cn>
License-Expression: MIT
License-File: LICENSE
Keywords: a2a,agent,ai,group-chat,llm,mqtt,multi-agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.13
Requires-Dist: aiohttp>=3.13.5
Requires-Dist: aiomqtt>=2.5.1
Requires-Dist: anthropic>=0.104.1
Requires-Dist: basic-open-agent-tools[xml]>=1.3.2
Requires-Dist: coding-open-agent-tools>=0.14.1
Requires-Dist: defusedxml>=0.7.1
Requires-Dist: importlib-metadata>=9.0.0
Requires-Dist: jinja2>=3.1
Requires-Dist: llama-cpp-python>=0.3.23
Requires-Dist: mcp>=1.0
Requires-Dist: numpy>=2.4.4
Requires-Dist: openai>=2.38.0
Requires-Dist: prompt-toolkit>=3.0.52
Requires-Dist: pydantic>=2.11
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: requests>=2.33.1
Requires-Dist: rich>=14.0.0
Requires-Dist: sentence-transformers>=5.5.1
Requires-Dist: serper-toolkit>=0.0.13
Requires-Dist: sqlite-vec>=0.1.9
Requires-Dist: textual>=8.0
Requires-Dist: tomlkit>=0.15.0
Requires-Dist: typer>=0.25.1
Provides-Extra: boat
Requires-Dist: basic-open-agent-tools[all]>=1.3; extra == 'boat'
Description-Content-Type: text/markdown

# QD-Evolve

Multi-agent AI framework with A2A protocol support, group chat, persistent memory, and extensible tool system.

- [DESIGN.md](DESIGN.md) — design philosophy, invariants, architecture, implementation

## Installation

### Prerequisites

- **Python 3.13+** — required by `requires-python`
- **[uv](https://docs.astral.sh/uv/)** — packaging tool used for dependency management. Install with:
  ```powershell
  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  ```
  Or on macOS/Linux:
  ```bash
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```
- **Mosquitto v5 broker** (MQTT/GChat mode only) — [download](https://mosquitto.org/download/)

### Setup

```bash
# 1. Clone the repository
git clone https://github.com/juzcn/qd-evolve
cd qd-evolve

# 2. Create virtual environment and install all dependencies
uv sync

# Optional: install BOAT bridge extras
uv sync --extra boat

# 3. Configure
#    Copy and edit the example below, or start from scratch.
#    Edit config.json with your API keys and models.
```

### Configuration

Minimal `config.json` for single-agent chat:

```json
{
  "default_provider": "openai",
  "default_model": "gpt-4o",
  "max_iterations": 20,
  "tool_output_limit": 8000,
  "providers": [
    {
      "name": "openai",
      "api_key": "sk-...",
      "base_url": "https://api.openai.com/v1",
      "api": "openai-completions",
      "models": [
        { "name": "gpt-4o", "context_window": 128000, "max_tokens": 4096 }
      ]
    }
  ]
}
```

See [Configuration](#configuration-1) below for full multi-agent, MQTT, and toolbox setup.

### Verify

```bash
# Start single-agent chat — should see the prompt
qd-evolve
```

## Quick Start

```bash
# Single-agent chat
qd-evolve

# Multi-agent A2A chat
qd-evolve a2a

# Run an agent as standalone A2A HTTP server
qd-evolve a2a serve --agent <name>

# Multi-agent MQTT chat (requires Mosquitto v5 broker)
qd-evolve mqtt

# Run an agent as MQTT-accessible server
qd-evolve mqtt serve --agent <name>

# Group chat — WeChat-style multi-agent group (requires Mosquitto v5 broker)
# Supports: AI agents, terminal human agents, WeChat human agents
qd-evolve gchat --agent <name>

# Manage tool enable/disable/preload
qd-evolve toolbox --agent <name>

# Browse and search conversation memories
qd-evolve memory --agent <name>
```

## Four Systems

| System | Entry | Transport | Use Case |
|--------|-------|-----------|----------|
| Chat | `qd-evolve` | In-process only | Single-agent, no network |
| A2A | `qd-evolve a2a` | HTTP + in-proc | Multi-agent over HTTP/SSE |
| MQTT | `qd-evolve mqtt` | MQTT v5 + in-proc | Multi-agent over MQTT |
| GChat | `qd-evolve gchat` | MQTT v5 (group topics) | WeChat-style group chat |

Each system is fully independent — no protocol fallback between them. See [DESIGN.md](DESIGN.md) for the full architecture.

## Configuration

All configuration via `config.json`. No CLI config commands, no `.env` files.

### Provider & Model

```json
{
  "default_provider": "openai",
  "default_model": "gpt-4o",
  "providers": {
    "openai": {
      "api_key": "sk-...",
      "base_url": "https://api.openai.com/v1",
      "api": "openai-completions",
      "models": {
        "gpt-4o": { "context_window": 128000, "cost": { "input": 2.5, "output": 10 } }
      }
    },
    "anthropic": {
      "api_key": "sk-ant-...",
      "api": "anthropic",
      "models": { "claude-sonnet-4-6": { "context_window": 200000 } }
    },
    "deepseek": {
      "api_key": "...",
      "base_url": "https://api.deepseek.com/v1",
      "api": "openai-completions",
      "models": { "deepseek-r1": { "reasoning": true } }
    }
  }
}
```

Three API types: `openai-completions`, `openai-response`, `anthropic`. Set at provider level via `api` field. Streaming is global (`stream` field). Reasoning/thinking is per-model (`reasoning: true`). Per-model cost tracking via `ModelCost`.

### Multi-Agent

```json
{
  "agents_config": {
    "chat_agent": "planner",
    "agents": [
      {
        "name": "planner",
        "description": "Plans and delegates tasks",
        "provider": "openai",
        "model": "gpt-4o",
        "memory_db": "planner.db",
        "server": { "host": "127.0.0.1", "port": 8001 },
        "toolbox": { "tools": {}, "bridge": { "oat:boat": "enabled" } }
      },
      {
        "name": "human",
        "description": "Human for approvals",
        "provider": "human",
        "server": { "host": "127.0.0.1", "port": 8002 }
      },
      {
        "name": "wechat_user",
        "description": "Human via WeChat iLink",
        "provider": "wechat-human",
        "server": { "host": "127.0.0.1", "port": 8003 }
      }
    ],
    "topology": { "relations": [] }
  }
}
```

Per-agent provider/model with global fallback. `provider: "human"` for terminal human agents, `"wechat-human"` for WeChat iLink bridge. Each agent has its own memory DB, server config, and toolbox state. WeChat human agents persist their session token via the `wechat_session` field.

### MQTT Broker

```json
{
  "agents_config": {
    "mqtt_broker": {
      "host": "127.0.0.1",
      "port": 1883,
      "will_delay_interval": 5
    }
  }
}
```

Requires external Mosquitto v5 broker. Per-agent credentials via `MqttConfig` on each `AgentEntry`.

### Toolbox

Tool enable/disable/preload per agent, managed via `qd-evolve toolbox --agent <name>` (Textual TUI) or by editing `config.json` directly.

```json
{
  "agents_config": {
    "agents": [{
      "name": "planner",
      "toolbox": {
        "tools": { "run_shell": "preloaded", "web_search": "enabled" },
        "mcp_servers": { "filesystem": "disabled" },
        "bridge": { "oat:boat": "enabled", "oat:coat": "disabled" },
        "cli": { "git": "preloaded" },
        "skills": { "code-review": "preloaded" }
      }
    }]
  }
}
```

Three states: `enabled` (on-demand schema), `preload` (schema at startup), `disabled` (invisible to agent).

## Runtime Features

### Slash Commands

| Command | Description |
|---------|-------------|
| `/models` | Switch provider/model |
| `/agents` | Switch agent |
| `/tools` | List tools |
| `/load <tool>` | Load tool schema |
| `/memory` | List saved memories with full content |
| `/compress` | Force context compression |
| `/clear` | Clear conversation |
| `/help` | Show help |
| `/quit` | Exit |

### Heartbeat

Agent-managed idle detection. When no activity for `heartbeat_idle_seconds`, sends a heartbeat prompt to the LLM. If LLM responds with `"."`, stays silent. Set `0` to disable. Mode-specific templates selected automatically.

### Replay Mode

`--replay <file>` feeds pre-recorded inputs for automated testing. `--output <file>` captures output.

### Token Stats

Per-turn and cumulative input/output tokens with context window usage percentage.

## A2A Protocol

Full [A2A v1.0](https://google.github.io/A2A/) implementation:

- **Agent discovery**: `/.well-known/agent.json`
- **Methods**: `message/send`, `message/stream`, `tasks/get`, `tasks/cancel`, `tasks/resubscribe`, `tasks/pushNotification`, `agent/getExtendedAgentCard`
- **Task lifecycle**: submitted → working → completed / failed / canceled / input_required
- **SSE streaming**: `message/stream` returns `StreamResponse` events
- **Push notifications**: webhook callbacks on task completion

## Group Chat

WeChat-style multi-agent group via MQTT. All configured agents form a single group.

- **AI agents**: Background loop processes `@mentions`, runs agent in parallel, publishes responses
- **Terminal human agents** (`provider: "human"`): Interactive prompt — type messages, see group activity
- **WeChat human agents** (`provider: "wechat-human"`): Bidirectional WeChat iLink bridge — long-poll for incoming WeChat messages, forward group responses back to WeChat. QR login on startup, session persisted to `config.json`
- `@all` mentions everyone; specific `@agent_name` directs to one agent

## Project Layout

```
qd-evolve/
├── qd_evolve/       # Main package (agent, core, tools, utils, _templates)
├── tools/           # User tools (func, cli, skills, mcp, bridge)
├── templates/       # User Jinja2 template overrides
├── tests/           # pytest suite
├── config.json      # All configuration
├── memory.db        # Conversation memory (SQLite + sqlite-vec)
└── pyproject.toml   # Dependencies and build config
```

See [DESIGN.md](DESIGN.md) for architecture and full module map.

## Requirements

- Python 3.13+
- [uv](https://docs.astral.sh/uv/) for dependency management
- External Mosquitto v5 broker (MQTT/GChat mode only)
- API keys for configured providers

## License

MIT
