MerchantOps Data Agent

Status: Gate 4A Evidence Foundation complete; Gate 4B planning only next

一个面向 PostgreSQL 电商业务库的 Business Data Agent。

核心目标：

Schema/Semantic Grounding
→ Multi-step Diagnostic Reasoning
→ Evidence Binding
→ Dry-run
→ HITL
→ Transaction
→ Idempotency
→ Audit
→ Verification

---

Current Scope

V1 使用 Olist 电商公开数据作为业务事实底座，并自建最小运营控制面。

V1 优先实现：

• PostgreSQL
• Olist import
• Metric Semantic Layer
• Minimal Agent Runtime
• Schema-aware DB Core
• Multi-step Diagnosis
• Evidence Binding
• Scenario Injection Eval
• Controlled Action Loop
• FastAPI
• Observability

V1 明确不做：

• Multi-Agent
• MCP
• 完整 BIRD / Spider
• 大型 Dashboard
• 复杂 Memory
• 通用 Workflow Engine
• 高风险自动业务写入
• 完整因果推断

---

Development Strategy

本项目采用：

Fresh Repo + Reference Repos + Vertical Slice First

参考：

• simple-long-horizon-agent：Harness / State / Event / Resume
• local-sql-agent：Schema Retrieval / SQL Safety / Error Correction

但正式项目不直接 Fork 二者。

---

Current Gate

查看：

docs/current-status.md

项目总实施方案：

docs/implementation-plan.md

开发 Agent 约束：

docs/development-prompt.md

---

Gate 0 Reproduction

Prerequisites:

• WSL2
• Docker Desktop with Ubuntu integration
• Python 3.12.13
• uv

uv sync --python 3.12.13 --all-groups
docker compose up -d --wait

uv run merchant-ops-db import-olist \
  --data-dir ../datasets/olist

uv run merchant-ops-db create-golden-scenario \
  --scenario-id late_delivery_seller_001 \
  --target-late-rate 0.75 \
  --delay-days 7

docker compose exec -T postgres \
  psql -U merchant_ops_admin -d merchant_ops \
  -f /dev/stdin < sql/verify_golden_scenario.sql

uv run pytest -m integration

Gate 0 所有数据库行为都在真实 PostgreSQL 中验证。WSL 本机 psql 是 optional；必需的 psql 和 pg_isready 由 PostgreSQL 容器提供。

---

Gate 1 Minimal Agent

Gate 1 只证明一个 narrow vertical slice：模型读取第一次数据库 observation 后，自主决定是否执行第二次查询，并最终输出结构化 Diagnosis。

Gate 1 引入的 metric vertical slice 只有：

query_metric
├── seller_delivery_summary
└── seller_delivery_delay_profile

这不代表已经完成通用 MerchantOps 多假设归因。delivery / review / cancellation / order volume / payment 等候选方向将在后续 Semantic / Scenario Eval Gate 按真实需求扩展。

运行固定 Golden Task Contract：

export DEEPSEEK_API_KEY=...  # 只放环境变量，不写入仓库

uv run merchant-ops-agent \
  --seller-id 1f50f920176fa81dab994f9023523100 \
  --window-start 2017-11-01 \
  --window-end 2017-12-01

DeepSeek 请求显式使用：

model: deepseek-v4-flash
base_url: https://api.deepseek.com
thinking: disabled
Gate 1 baseline: 4 model turns / 3 tool calls
Current CLI:     6 model turns / 5 tool calls / 2 SQL repairs

普通测试不会产生付费 API 调用。显式运行真实 E2E：

RUN_REAL_API_TESTS=1 uv run pytest \
  tests/e2e/test_golden_agent.py -q -s

---

Gate 2 Semantic + Schema

Gate 2 将业务指标口径与 Schema Context 从 Prompt 猜测中分离出来：

Business Question
→ Metric Grounding
→ search_schema
→ scoped tables / columns / relationships / metric references
→ query_metric
→ Structured Diagnosis

当前包含 6 个 versioned Metric contracts：

order_count
gmv
delivered_order_count
late_delivery_rate
average_review_score
cancellation_rate

Schema Retrieval 使用 5 条小型 golden set 验证，当前 Recall@2 = 1.0。它只返回相关逻辑表和已选表之间的关系，不向模型暴露 physical scenario schema 或 Ground Truth metadata。

---

Gate 3 Reliability

Gate 3 增加一个受控 raw SQL fallback，不将项目扩展为通用 Text-to-SQL framework：

run_readonly_sql
→ sqlglot AST Guard
→ single SELECT/WITH + logical table allowlist
→ row cap + PostgreSQL statement_timeout
→ explicit read-only transaction + merchant_ops_agent role
→ structured SQLSTATE error
→ bounded observation-driven repair

默认 SQL runtime limits：

row cap:           200
statement timeout: 1000ms
SQL repair budget: 2

真实 PostgreSQL integration 验证 UNKNOWN_COLUMN、TYPE_MISMATCH、AMBIGUOUS_REFERENCE 的“失败 observation → 修正 SQL → 成功”路径。这里的 SQLSTATE 映射是产品层 operational classification，不是严格语义一一对应；例如 42883 undefined_function 在运算符/类型不兼容场景归入 TYPE_MISMATCH。Gate 3 Closeout 默认全量为 123 passed, 2 skipped；两个 skip 都是 opt-in 付费 DeepSeek E2E。Golden metric 路径真实通过；ad-hoc SQL trajectory 的执行与安全边界通过，但 semantic-grain check 证明其 COUNT(*) 是 seller-item join grain，不能解释为严格订单数。

---

Scenario Boundary

Exploratory Natural Case

从原始 Olist 中寻找自然经营异常，用于真实历史数据 Demo。结论只称为 Diagnostic Attribution / Root Cause Hypothesis，不作为严格 Root Cause Accuracy Ground Truth。

Golden Eval Scenario

Gate 0 的正式场景固定为：

目标 seller 在指定时间窗口出现确定性延期履约异常。

具体 seller、时间窗和注入幅度根据数据分布确定。注入只发生在隔离 schema / 测试副本中；原始 CSV 和 raw baseline 不修改；injection metadata 对 Agent 隐藏，由独立 scorer 读取。

---

Planned Tech Stack

• Python 3.12.13
• uv
• FastAPI
• PostgreSQL 16 / Docker Compose
• psycopg 3
• Pydantic
• sqlglot
• pytest
• OpenTelemetry GenAI
• Langfuse
• DeepSeek OpenAI-compatible provider

最终依赖以实际开发为准，不为堆栈而引入组件。

---

Status Rule

README 只记录：

• 项目定位；
• 可公开展示的架构；
• 可复现实验结果；
• 启动方式；
• Demo。

开发过程、暂时问题和未完成事项统一记录在：

docs/current-status.md

重要开发 session 的历史过程 append-only 记录在：

docs/dev-log.md

避免 README 变成开发日志。