 <div align="center">

# Pretor (执政官)

一款基于 Python 的分布式多 Agent 协作系统

[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/)
[![Ray](https://img.shields.io/badge/Distributed-Ray-0288d1.svg)](https://docs.ray.io/)
[![Pydantic-AI](https://img.shields.io/badge/Framework-Pydantic--AI-ff69b4.svg)](https://ai.pydantic.dev/)
[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)

[**项目架构**](./docs/ARCHITECTURE.md) | [**更新日志**](./changelogs/CHANGELOG.md) | [**未来展望**](./changelogs/ROADMAP.md)

</div>

---
**Pretor** 是一款基于 **Ray** 构建的下一代分布式多 Agent 协作系统。项目采用“中心监管 + 边缘执行”的异构集群模式，通过大参数 MoE 模型进行高层逻辑推理，并协同微调后的轻量化模型高效完成具体任务。借助 **Pydantic-AI** 提供的强类型约束与 FastAPI 异步网关，Pretor 实现了任务从需求拆解、资源调度到自动化执行的全链路闭环，为个人提供可靠的人工智能助手服务。


---
## ✨ 核心特性

### 🧠 异构协作体系
- **多智能体集群**：内置主管 (Supervisory)、意识 (Consciousness)、控制 (Control) 三大核心节点，实现比单 Agent 系统更严谨的决策链。
- **Worker 动态派生**：根据任务需求动态拉起 Ordinary 或 Skill 类型的 Worker Individual，实现资源的按需分配。

### 🚀 分布式性能保障
- **Ray 驱动**：底层基于 Ray 构建，支持跨进程、跨机器的 Actor 通讯，轻松应对高并发任务流。
- **本地化优先**：深度适配 **vLLM**，支持本地私有化模型部署，在保障隐私的同时大幅降低 API 调用成本。

### 🛠️ 工业级工程设计
- **强类型契约**：基于 Pydantic-AI 实现 Tool 与 Agent 的接口定义，确保 AI 输出的确定性与安全性。
- **自动化流**：内置工作流引擎 (Workflow Engine)，实现从需求发现到自动化执行的闭环。

### 📦 Pretor 生态子项目 (Sub-projects)

| 项目名称                                                       | 代号      | 功能定位 | 当前状态 |
|:-----------------------------------------------------------|:--------| :--- | :--- |
| **[pretor-viceroy](https://github.com/zhaoxi826/viceroy)** | **总督**  | **资源管理**：负责系统 Skill 的动态安装、元数据解析与全集群分发。 | ✅ 已发布 |
| **pretor-stardomain**                                      | **星域**  | **安全沙箱**：为 Agent 自动生成的代码提供轻量化的隔离运行环境，防止逃逸。 | 📅 规划中 |
| **pretor-explorer**                                        | **探索者** | **网页感知**：自动化爬虫引擎，赋予智能体实时互联网信息搜索与内容抓取能力。 | 📅 规划中 |
| **pretor-pioneer**                                         | **先驱者** | **知识增强**：RAG 检索增强引擎，管理私有知识库的向量化、索引与精准检索。 | 📅 规划中 |

---
## 🚀 快速开始 (Quick Start)

> **当前版本**：`v0.1.0-alpha` (开发预览版)  
> 本项目目前处于快速迭代阶段，欢迎提交 Issue 或 Pull Request。

### 方式一：使用 Docker Compose (推荐)
这是部署 **Pretor 应用** 及其配套 **PostgreSQL 数据库** 最简单、最完整的方式。

1. **准备配置文件**：在本地创建一个目录，并新建 `docker-compose.yml`：
   ```yaml
   services:
     db:
       image: postgres:16-alpine
       container_name: pretor_db
       environment:
         POSTGRES_USER: postgres
         POSTGRES_PASSWORD: postgrespassword
         POSTGRES_DB: pretor
       healthcheck:
         test: ["CMD-SHELL", "pg_isready -U postgres -d pretor"]
         interval: 5s
         timeout: 5s
         retries: 5

     pretor:
       image: zhaoxi5699/pretor:v0.1.0alpha
       container_name: pretor
       ports:
         - "8000:8000"
         - "8265:8265"
       depends_on:
         db:
           condition: service_healthy
       environment:
         - POSTGRES_USER=postgres
         - POSTGRES_PASSWORD=postgrespassword
         - POSTGRES_HOST=db
         - POSTGRES_PORT=5432
         - POSTGRES_DB=pretor
         - SECRET_KEY=changethiskey12345  # 请在生产环境中修改此密钥
   ```
   
2. **启动服务**
    ```bash
   docker compose up -d
   ```
   
### 方式二：使用 Docker
1. **启动服务**
    ```bash
        docker run -d \
        --name pretor \
        -p 8000:8000 \
        -p 8265:8265 \
        -e POSTGRES_HOST=你的数据库IP \
        -e POSTGRES_USER=postgres \
        -e POSTGRES_PASSWORD=postgrespassword \
        -e POSTGRES_DB=pretor \
        -e SECRET_KEY=your_secret_key \
        zhaoxi5699/pretor:v0.1.0alpha
    ```
   
## 🔍 访问与验证
服务启动后，可以通过以下地址进行操作：
- Web 控制台 / API 文档: http://localhost:8000
- Ray 任务仪表盘: http://localhost:8265