# AIF (Agent Information Field)

基于组织符号学的 LLM Agent 协作治理基础设施。

## 项目状态

当前已包含可运行的 Normbase / EDA / MCP 适配层，并已提供发布形态：
- Python: `aif-normbase`（通过 `uvx --from aif-normbase aif-mcp` 调用）
- Node wrapper: `@langxai/aif-mcp`（通过 `npx -y @langxai/aif-mcp` 调用）

## 项目结构

```
aif/
├── normbase/              # 规范库核心模块
│   ├── models/            # 数据模型 (Norm, NormVersion, Schemas)
│   ├── api/               # API 路由 (norms, retrieve)
│   ├── services/          # 业务逻辑 (retrieval)
│   ├── db/                # 数据库 (schema.sql, connection)
│   └── prompts/           # 提示词模板
├── eda_agent/             # EDA Agent 模块
│   ├── state.py           # EDA 状态管理 (Belief, NormBinding, ValueWeight)
│   ├── engine.py          # 推理引擎 (E/D/A 组件)
│   └── api/               # Agent API
├── llm/                   # LLM 模块 (providers)
├── integrations/mcp/      # MCP 适配层 + npm wrapper
├── scripts/               # 构建/发布/运维脚本
├── tests/                 # 测试 & 种子数据
│   └── tmp/               # 种子脚本 (EU AI Act, 交通法规等)
├── docker-compose.yml     # 本地开发环境
├── pyproject.toml         # Python 包配置 (aif-normbase)
├── requirements.txt       # 依赖
└── README.md
```

## 模块说明

### normbase

规范库核心，提供：
- ✅ 规范 CRUD 操作 (obligation/prohibition/permission)
- ✅ 检索：agent_role + field_ids 双通道 (RRF融合)
- ✅ 向量语义检索 (Qdrant)
- ✅ 版本管理 (norm_versions)
- ✅ 规范关系 (norm_relations)
- ⬜ Redis 缓存
- ⬜ 规范萃取流水线
- ✅ MCP 适配（通过 `integrations/mcp` 暴露工具）

### eda_agent

EDA Agent 运行时 (Phase 6 完成)：
- ✅ E（认识论）信念管理 (Belief)
- ✅ D（义务论）规范绑定 (NormBinding)
- ✅ A（价值论）权重推理 (ValueWeight)
- ✅ 合规校验基础
- ⬜ 完整推理流程

## 技术栈

- FastAPI + PostgreSQL 16 + JSONB
- SQLAlchemy 2.0 (async)
- Qdrant (向量检索)
- Redis (缓存 - 集成中)
- LLM: OpenAI / Anthropic

## 快速开始

```bash
# 创建并激活 conda 虚拟环境（首次）
conda create -n aif python=3.11 -y
conda activate aif

# （可选）使用 venv 而不是 conda
# python -m venv .venv
# .venv\Scripts\activate

# 启动本地开发环境 (PostgreSQL + Qdrant + Redis)
docker-compose up -d

# 安装依赖
pip install -r requirements.txt
```

### MCP（本地开发）

```bash
# 直接启动 MCP 适配器（stdio）
python -m integrations.mcp.server --transport stdio
```

### MCP（分发调用）

```bash
# Python 入口（推荐）
uvx --from aif-normbase aif-mcp --transport stdio

# Node 包装入口
npx -y @langxai/aif-mcp
```

### 启动 API Server

```bash
# Normbase API 端口 8001
python -m normbase.main
```

API 文档：http://localhost:8001/docs

### 启动 EDA Agent Server

```bash
# EDA Agent API 端口 8002
python -m eda_agent.main
```

EDA API 文档：http://localhost:8002/docs

### 启动 Web 管理界面（Dashboard）

```bash
# Unified Dashboard（默认端口 8010）
python -m dashboard.main
```

管理界面：http://localhost:8010

如需使用轻量旧版 Normbase Admin（仅规范管理）：

```bash
python -m normbase.admin
```

旧版地址：http://localhost:8000

## 开发计划

详见 [background/plan.md](background/plan.md)

### 阶段进度

| Phase | 内容 | 状态 |
|-------|------|------|
| Phase 1 | 基础骨架 + CRUD + 管理UI | ✅ |
| Phase 2 | 检索核心 + 向量库 + 缓存 | ✅ |
| Phase 3 | 萃取流水线 + 审核UI | ⬜ |
| Phase 4 | MCP集成 + API鉴权 | ⬜ |
| Phase 5 | 打磨验证 + Demo | ⬜ |
| Phase 6 | EDA状态管理 + 持久化 | ✅ |
| Phase 7 | EDA推理引擎核心 | ⬜ |
| Phase 8 | 价值排序 + 合规校验 | ⬜ |
| Phase 9 | EDA端到端集成 | ⬜ |

## API 端点

- `GET /` - 健康检查
- `GET /api/v1/norms` - 规范列表
- `POST /api/v1/norms` - 创建规范
- `GET /api/v1/norms/{id}` - 规范详情
- `PUT /api/v1/norms/{id}` - 更新规范
- `DELETE /api/v1/norms/{id}` - 删除规范
- `GET /api/v1/retrieve` - 规范检索

## 测试数据

测试种子脚本位于 `tests/tmp/`:
- `seed_eu_ai_act.py` - EU AI Act 规范
- `seed_zh.py` / `seed_en.py` - 中英文测试规范
- `seed_traffic_laws.py` - 交通法规
