Metadata-Version: 2.4
Name: generative-agent-assistant
Version: 0.1.0
Summary: A general-purpose generative agent runtime: ReAct loop, sessions, SSE streaming, MCP tool registry, charts and approvals, served by FastAPI with a built-in web UI.
Author-email: Albert Xu <xualbert83@outlook.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: aiosqlite>=0.22.1
Requires-Dist: anyio>=4.14.1
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: langfuse<3,>=2
Requires-Dist: mammoth>=1.12.0
Requires-Dist: markdownify>=1.2.3
Requires-Dist: mcp<2,>=1.28.1
Requires-Dist: minio>=7.2.20
Requires-Dist: nacos-sdk-python==3.2.0
Requires-Dist: pillow>=12.3.0
Requires-Dist: pwdlib[argon2]>=0.3.0
Requires-Dist: pyjwt>=2.13.0
Requires-Dist: pymupdf4llm>=1.28.0
Requires-Dist: python-multipart>=0.0.32
Requires-Dist: pyyaml>=6.0
Requires-Dist: taskiq-redis>=1.2.3
Requires-Dist: taskiq>=0.12.4
Requires-Dist: uvicorn[standard]>=0.30.0
Description-Content-Type: text/markdown

# generative-agent-assistant

**通用 ReAct agent 运行时** —— 会话持久化 / SSE 流式输出 / 工具注册 / 图表渲染 / 人工审批 /
子代理派发，自带一套开箱可用的 Web 界面，由 FastAPI 承载。
`pip install` 之后跑一次配置向导填上你自己的模型与中间件地址，一条命令起完整服务。

> A general-purpose ReAct agent runtime (sessions, SSE streaming, tool registry, charts,
> human approval, sub-agents) with a built-in web UI, served by FastAPI.

- 许可：MIT（随包的第三方前端库另有各自许可，见 `gca/static/THIRD_PARTY_NOTICES.md`）
- Python：**>= 3.12**

---

## 安装

```bash
pip install generative-agent-assistant
```

装完即有 `gca` 命令（`init` / `doctor` / `serve`）与 `import gca` 库入口。

---

## 60 秒上手

### 1. `gca init` —— 配置向导（只有 3 项必填）

```
$ gca init
GCA 配置向导 · 配置将写入 /Users/you/.gca/.env（权限 600）

[1/3] 大模型（必填，3 项）
  API Base URL    OpenAI 兼容端点                   : http://127.0.0.1:18111/v1
  模型名称        如 qwen-plus / glm-4.6            : qwen-plus
  API Key         （输入不回显）:
       ✓ 端点连通（50 ms）

[2/3] 中间件（可选，直接回车跳过）
  Redis URL       redis://[:密码@]host:port/db      :
       – 已跳过：「异步任务·run_bash」不可用
  MinIO Endpoint  host:port                         :
       – 已跳过：「文件上传·文档解析」不可用

[3/3] 服务
  监听端口        [8001]:

自动处理（不问你）：
  · JWT_SECRET  已生成 48 字节随机密钥（唯一的启动阻断项，不用你操心）
  · AGENT_BASH_SANDBOX  自动判定 = on（当前平台 Darwin）
  · AGENT_WORKSPACE  /Users/you/.gca/workspace（已创建）
  · DB_PATH  db/chat.db（相对 /Users/you/.gca，SQLite 首启自建）

降级清单（现在跳过，随时重跑 gca init 补上）：
  · 已跳过 Redis     → 「异步任务·run_bash」不可用
  · 已跳过 MinIO     → 「文件上传·文档解析」不可用

默认跳过：Langfuse 可观测 / SoMark OCR / 配置中心（要配请跑 gca init --advanced）

✓ 已写入 /Users/you/.gca/.env（权限 600）
  ⚠ 该文件含明文密钥，勿提交 git、勿贴聊天窗。

下一步：gca doctor 自检  →  gca serve 启动
```

> 上面是一次真机实跑的原样输出。其中大模型端点用的是本地 stub（`127.0.0.1:18111`），
> 所以你会看到本地地址 —— 换成你自己的服务商端点即可。

### 2. `gca doctor` —— 起服前自检

```
$ gca doctor
配置文件   /Users/you/.gca/.env               ✓  (权限 600)
JWT_SECRET 已配置（64 字符）                       ✓
大模型     http://127.0.0.1:18111/v1  model=qwen-plus ✓  11 ms
Redis      未配置（可选）                          –  跳过 → 「异步任务·run_bash」不可用
MinIO      未配置（可选）                          –  跳过 → 「文件上传·文档解析」不可用
配置中心   未配置（可选）                          –  跳过
SQLite     /Users/you/.gca/db/chat.db         ✓  可写

结论：可启动（2 项功能降级）
  · Redis 未配置 → 「异步任务·run_bash」不可用
  · MinIO 未配置 → 「文件上传·文档解析」不可用
```

退出码语义：**必填项不通过 → 1**（不该起服）；**只有可选项降级 → 0**（可以起）。

### 3. `gca serve` —— 一键启动（含界面）

```
$ gca serve --port 18101
GCA 0.1.0 · home=/Users/you/.gca · 降级：Redis 未配 → 「异步任务·run_bash」不可用、MinIO 未配 → 「文件上传·文档解析」不可用
GCA 启动中 …  http://127.0.0.1:18101   (GCA_HOME=/Users/you/.gca)
停止：Ctrl-C
INFO:     Started server process [55650]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:18101 (Press CTRL+C to quit)
```

中间件都配齐时，第一行横幅变成：

```
GCA 0.1.0 · home=/…/home_full · 全部功能可用
```

启动后：

```bash
curl http://127.0.0.1:18101/health     # {"status":"ok"}
open  http://127.0.0.1:18101/          # 完整 Web 界面（89 KB HTML，静态资源随包发）
```

### 4. 首次使用：先注册一个账号

界面是带鉴权的，**首次打开需要注册**（本地 SQLite 存用户，无外部依赖）。
在界面上按提示注册即可；也可以直接调接口：

```bash
curl -X POST http://127.0.0.1:18101/api/auth/register \
     -H 'Content-Type: application/json' \
     -d '{"username":"yourname","password":"your-password"}'
# → 返回 access_token（注册即登录）；登录走 /api/auth/login
```

---

## 配置说明

配置文件落在 **`$GCA_HOME/.env`（默认 `~/.gca/.env`，权限 600）**，
`gca init` 负责生成，你也可以直接手改。

### 必填：只有大模型三件套

| 键 | 说明 |
|---|---|
| `LLM_BASE_URL` | OpenAI 兼容端点，如 `https://…/v1` |
| `LLM_DEFAULT_MODEL` | 默认模型名，如 `qwen-plus` |
| `LLM_API_KEY` | 你的 API Key（明文落盘，权限 600） |

不填这三项就没法对话；其余全部可自动生成、用默认值，或跳过后降级运行。

### 自动生成：`JWT_SECRET`

它是**唯一会让服务起不来的必配项**（空值或占位值直接 fail-fast），
所以向导用 48 字节随机数直接生成，不问你。
重跑 `gca init` 会**沿用已有值**，已签发的 token 不会失效。

### 可选：跳过之后具体哪些功能不可用

| 中间件 | 键 | 跳过后**不可用**的功能 | 其余功能 |
|---|---|---|---|
| Redis | `REDIS_HOST` / `PORT` / `PASSWORD` / `DB` | 异步任务队列、`run_bash` 工具 | 照常可用 |
| MinIO | `MINIO_ENDPOINT` / `ACCESS_KEY` / `SECRET_KEY` / `BUCKET_*` | 文件上传、文档解析（PDF/Word 转 Markdown） | 照常可用 |

**对话、SSE 流式、会话历史、图表渲染、审批、子代理都不依赖这两个中间件** ——
只填大模型三件套就能起服并正常聊天（这一点有实测：三个外部服务全指死端口仍启动成功）。
SQLite 会在 `$GCA_HOME/db/chat.db` 自建，无需你准备数据库。

`gca init --advanced` 还会追问：第二个模型 provider、文档 OCR、可观测平台、外部配置中心 —— 都可留空。

### 配置解析优先级

```
真实环境变量（shell export / 容器 -e）   ← 最高，CI 与容器友好
  > $GCA_HOME/.env
  > 外部配置中心（仅当你显式配了地址才会尝试，失败自动回退 .env）
  > 代码内默认值
```

### 非交互 / CI / 容器

```bash
gca init --non-interactive \
  --set LLM_BASE_URL=https://your-endpoint/v1 \
  --set LLM_MODEL=qwen-plus \
  --set LLM_API_KEY=sk-xxx \
  --set REDIS_URL=redis://:password@127.0.0.1:6379/0 \
  --set MINIO_ENDPOINT=127.0.0.1:9000
```

`REDIS_URL` 会自动拆成代码消费的四个键；`MINIO_ENDPOINT` 带 scheme 也会归一成 `host:port`。
非交互模式下**只从环境变量捡默认面的键**，不会把你 shell 里其它同名变量烤进配置文件。

---

## ⚠ `--home` 是「粘」的

一旦你用了自定义目录：

```bash
gca init --home /srv/gca      # 配置写到 /srv/gca/.env
```

那么**后续每条命令都必须带上同样的 `--home`**，否则会去默认的 `~/.gca` 找配置：

```bash
gca doctor --home /srv/gca
gca serve  --home /srv/gca
```

等价写法是导出环境变量 `export GCA_HOME=/srv/gca`，之后三条命令都不用再带 `--home`。
**不带且默认目录没配置时**，`gca serve` 会打印引导文案让你先跑 `gca init`（不会甩 traceback）。

`$GCA_HOME` 同时是数据锚点：SQLite 库、agent 工作区、`mcp.json` 都按它解析。
换 home = 换一套数据。

---

## 接入你自己的 MCP 工具

本包只内置 5 个通用工具：`read_file` / `write_file` / `list_dir` / `run_bash` / `dispatch_agent`。
**领域能力（数据库、检索、内部系统…）请通过 MCP 自行接入** —— 在
`$GCA_HOME/mcp.json` 放一份配置即可：

```json
{
  "servers": [
    {
      "id": "my-tools",
      "name": "My Tools",
      "enabled": true,
      "transport": "streamable-http",
      "url": "http://127.0.0.1:9000/mcp",
      "headers": {},
      "toolPrefix": "auto",
      "modes": ["agent"]
    }
  ]
}
```

字段语义：

- `enabled` 必须是 JSON 布尔 `true`（字符串 `"false"` 是 truthy，这里严格判定，避免「以为下线了其实在线」）
- `modes` 要包含 `"agent"` 才会在对话轮次里被装载
- `toolPrefix`：`"auto"`（缺省）→ 工具名前缀为 `mcp__my_tools__`；给空串 `""` 则用裸名
- 环境变量 `GCA_MCP_URL_<ID大写下划线>` 可覆盖 `url`（容器内换内线地址用），不影响工具名与路由

**没有 `mcp.json` 是完全正常的初始态**：配置加载返回空列表、不抛异常，
agent 直接走内置工具集，服务照常可用。
（只有**写坏了 JSON** 才会报错 —— 那是真错误，静默吞掉比报错更糟。）

---

## 作为库使用

```python
from gca.main import app                 # ASGI 应用，直接交给 uvicorn
from gca.agent.loop import run_loop, run_loop_stream, dispatch
from gca.agent.tools import DEFAULT_TOOLS
from gca.agent.mcp_client import load_mcp_config
```

```bash
uvicorn gca.main:app --host 0.0.0.0 --port 8001
```

`import gca` 期间**零网络、零拨号**：不读包外路径、不连配置中心，配置与连接全部下沉到显式入口。

---

## 边界与已知限制

- **本包不含任何自然语言取数 / Text-to-SQL 能力**，也不含任何业务数据字典或行业口径。
  它是一个纯粹的通用 agent 基座；这类能力请以 MCP 工具的形式自行接入。
- **`gca init` 的模型校验只发 `GET {base_url}/models` 探活，不发 chat 请求** ——
  不替你烧配额。代价是：只开放 chat 接口、不实现 `/models` 的端点会被标成「可达但 HTTP 404」，
  这属正常，可以直接继续。
- **Python `>= 3.12`**，3.11 及以下装不了。
- **API Key 明文落盘**在 `$GCA_HOME/.env`。文件权限已钉死 600、目录 700，
  但仍请**勿提交 git、勿贴进聊天窗**。
- Redis / MinIO 需要你自备（向导只问 URL，不代管安装）。
- 默认监听 `127.0.0.1`（仅本机）。要对外提供服务请显式 `--host 0.0.0.0`，
  并自行处理反向代理与 TLS。

---

## 第三方组件

随包的 `gca/static/` 内含三个 vendored 前端库，版权归各自作者，按各自许可分发：

| 库 | 版本 | 许可 |
|---|---|---|
| Apache ECharts | 5.6.1 | Apache-2.0 |
| marked | 12.0.2 | MIT |
| DOMPurify | 3.4.11 | Apache-2.0 OR MPL-2.0 |

完整版权行与许可声明见包内 **`gca/static/THIRD_PARTY_NOTICES.md`**。

---

## 许可

MIT © Albert Xu
