generative-agent-assistant 0.1.0__tar.gz

generative_agent_assistant-0.1.0/.gitignore

@@ -0,0 +1,77 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+venv/
+
+# Node / 前端
+node_modules/
+dist/
+
+# 环境变量与密钥
+.env
+.env.local
+.env.pg-mcp
+# 问数 MCP 迁入后的真实配置（含 PG DSN），只提交 .env.nl2sql.example
+.env.nl2sql
+# standalone 部署的容器视角配置（含真实密钥，只提交 .env.docker.example）
+deploy/.env.docker
+# 语义图谱 Neo4j 实例的密码，只提交 .env.neo4j-gca.example
+.env.neo4j-gca
+
+# Redis
+dump.rdb
+
+# macOS
+.DS_Store
+
+# IDE
+.idea/
+.vscode/
+
+# Claude Code 本地配置
+.claude/settings.local.json
+
+# Claude Code project-level state (personal)
+.claude/TASK.md
+.claude/memory/
+
+# SQLite 数据库文件（不入库，schema.sql 才入库）
+app/db/*.db
+app/db/*.db-*
+
+# db/ 目录下的 SQLite 数据文件
+db/*.db
+db/*.db-*
+
+# Obsidian 编辑器配置
+.obsidian/
+db/_backup_*/
+
+# agent loop 沙箱：模型写盘产物不入库
+agent_workspace/
+
+# Nacos SDK 运行时快照缓存（配置内容含凭据值，绝不入库；P7 引入）
+nacos-data/
+
+# 并行 Codex 会话本地工具链，不入库（含本机绝对路径、指向不存在的 .Codex 死链、
+# tests/test_cors.py 断言旧白名单 CORS 与现通配配置冲突）：保留本机可用、挡在共享仓库外
+/.codex/
+/AGENTS.md
+/tests/test_cors.py
+
+# 开发态脚本日志与 pid（app_start.sh 产物）
+logs/
+
+# 问数 MCP 的 BGE 模型与运行数据（约 110MB，走本地目录/volume，不入库）
+vanna_data/
+
+# 问数 MCP 运行数据目录（run_sql 的 query_results_*.csv 落盘，dev 裸进程态产物）
+nl2sql_data/
+
+# P9.6 复测日志:含 user 名与(旧脚本的)口令长度,不入库;跑测证据在 on_r*.jsonl 与 verdicts_*
+datasets/p9_runs/*.log
+datasets/p10_runs/*.log
+# P12.2 影子对账原始逐条日志(含全部 SQL 文本与取回值);读数结论在 shadow_r*.md
+datasets/p12_runs/*.log

generative_agent_assistant-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Albert Xu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

generative_agent_assistant-0.1.0/PKG-INFO

@@ -0,0 +1,324 @@
+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