An agent you can trust with money: agentic commerce with real transactional guarantees — quotes before orders, idempotent payments, exactly-once price alerts — running on an engine that also delivers enterprise RAG customer service. Built with FastAPI and LangGraph.
commerce: open need → virtual-catalog search → staged quote-confirm → CAS + idempotent order/pay → timeline / price watch
support: intent routing → slot filling / tool call / FAQ fast path / agent loop / hybrid retrieval → claim-gated streaming → handoff
(the landing page of the bundled frontend — live demo; the UI is bilingual, following the visitor's language)
(a live turn with its execution trace — full demo below)
- Why This Project
- Key Highlights
- How It Works
- Quick Start
- Live Demo
- Architecture
- Configuration
- Testing & Quality
- Roadmap
- 中文说明
Most agent demos stop at the tool call and pretend it succeeded. This project asks the harder question: what has to be true before you can hand an LLM agent your wallet? The answer here is a full transactional contract — a quote you confirm before an order exists, expected_version CAS and request_key idempotency on every write, staged registration for order and payment with separate explicit confirmations, reconnects that reconcile instead of double-charging, exactly-once price alerts, and server-authoritative cards that win whenever the model narrates something different.
The same engine solves the customer-service version of that trust problem: resolve business requests while keeping policy answers, task state, and staff handoffs consistent. Users interrupt a refund flow to ask a question; policies change after an answer was sent; human agents need the original context rather than a fresh conversation.
The system connects a 14-node LangGraph dialogue engine with a deterministic virtual-catalog commerce provider (SKU facts projected on demand from a stable 8-digit address space), hybrid retrieval, versioned document ingestion, claim-gated streaming, and assigned-agent handoff. Business actions use a ToolRegistry; completed actions remain terminal so task resumption cannot silently execute them twice.
- Knowledge lifecycle: retain original documents, process immutable revisions asynchronously, recover interrupted ingestion, and preserve the answer-time citation snapshot.
- Access and continuity: private sessions enforce authenticated ownership in both Demo and strict modes; assigned staff can read context and send separate human replies. PostgreSQL checkpoints persist dialogue state.
- Operations: epoch-scoped caches, Redis rate limiting, metrics and alert rules, tracing hooks, replica deployment templates, and a PostgreSQL backup/recovery runbook.
- Integration: five bundled mock business-tool handlers define the refund/return/order/logistics/complaint interface; connect enterprise business APIs through the registry. Multi-tenant knowledge isolation remains on the roadmap.
Deployment commands below start a single API instance. Replica templates, optional GraphRAG and monitoring are configured separately. Recorded verification results and their scope are listed under Testing & Quality.
The RAG space has strong general-purpose engines and platforms. In the agentic-commerce niche, platform MCP servers (Shopify, Stripe, Spree, Medusa) expose store management, and protocol work (ACP, Google's UCP) standardizes discovery and payment. A few reference points:
| Project | Lane | Stack |
|---|---|---|
| RAGFlow | Agent-native RAG engine / context infrastructure | Go / Python |
| Onyx | Enterprise AI chat platform, broad LLM and connector support | Python |
| AnythingLLM | Local-first document chat and agent workspace | JavaScript |
| LightRAG | Simple and fast graph-based RAG (EMNLP 2025) | Python |
| Kotaemon | Document-chat tool with a clean UI | Python |
| Agentic Commerce Protocol | Open standard for agent ↔ merchant commerce interactions | Spec |
| Universal Commerce Protocol | Google-backed open standard for agent-initiated payments with cryptographic proof of user consent | Spec |
This repo sits in a different lane: an end-to-end transactional customer-service and shopping agent — confirmation-gated commerce (quote → order → payment with CAS and idempotency), guardrailed streaming, human handoff with a staff workbench, deterministic evals, and a one-command demo. For general document-QA platforms the projects above are good fits; this project focuses on what it takes for an agent to safely touch orders and money. The ACP and UCP rows are complementary standards rather than competitors — they define how agents and merchants talk; this repo ships a complete store-side implementation (including an MCP server) where that class of protocol could plug in.
| Capability | Implementation | Business purpose |
|---|---|---|
| Transactional shopping agent | Open need → category mapping → tool loop (20 steps / 30 LLM calls), staged quote→order→payment with CAS + idempotency, server-authoritative cards | Let an agent complete purchases without double charges or unconfirmed money movement |
| Proactive price watches | Pre-authorized "SKU X ≤ ¥Y → ask me" rules, event-driven evaluation, exactly-once ask delivery | Notify on real drops without ever ordering on the visitor's behalf |
| Order timeline | Full event chain rebuilt from authoritative purchase/operation/confirmation rows, read-only and owner-scoped | Answer "what happened to my order" from facts, not narration |
| Stateful task execution | 14-node StateGraph, five-way routing, slot collection, task stack, ToolRegistry | Complete requests across interruptions without repeating completed actions |
| Versioned support knowledge | Retained sources, immutable revisions, retryable ingestion, stable passage IDs | Trace an answer back to the policy version used at the time |
| Retrieval and answer control | Vector + BM25 + RRF + reranking, optional GraphRAG, sentence-level claim gates | Retrieve relevant evidence and check curated policy facts before streaming |
| Retrieval resilience | Empty KB answered as honest "no evidence" (not a false outage); embedding-provider switches get dimension-drift detection — empty collections rebuild at the new size, populated ones fail with both dimensions and the fix; a collection deleted at runtime recovers via one latch-reconcile retry per call | Keep first-run trust and survive provider switches and ops mistakes without a process restart |
| Human handoff | Private sign-in workspace, tickets/queue, assigned context, two-way human messages, atomic final reply/closure | Carry context into staff handling and deliver a saved explanation |
| Operational control | Epoch-scoped L0/L1/L2 cache, metrics/alerts, tracing, rate limits | Inspect latency, outcomes, cache consistency and load |
Recorded quality baseline (2026-11-14): 4148 passing tests, 3 opt-in scenarios skipped by default, 4 expected failures, 93.71% coverage. Containment rate measures sessions without handoff or downvote; confirmed resolution, reopen counts and human QA are tracked separately. Failed, completed and latest-failed reply cohorts are also reported independently.
Answer citation contract · Staff handoff context · Backup and recovery · All docs
One conversation thread covers the whole journey — consult, buy, get support, and come back:
flowchart TB
visitor["Anonymous visitor<br/>(cookie identity, no signup)"]
subgraph consult["1 · Consult — grounded answers"]
ask["Ask products, prices, policies"]
grounded["Hybrid retrieval + citations<br/>claim-gated policy numbers"]
ask --> grounded
end
subgraph buy["2 · Buy — transactional agent"]
search["Shopping agent search<br/>154,624-SKU catalog"]
quote["Cart → itemized quote"]
confirm{"Explicit confirmation"}
pay["Order → payment<br/>CAS + idempotency keys"]
search --> quote --> confirm
confirm -- "approve" --> pay
confirm -- "change mind" --> quote
end
subgraph aftersale["3 · After-sale — customer service"]
track["Order timeline<br/>from authoritative rows"]
refund["Refund / return / complaint<br/>confirmation-gated, terminal when done"]
resolved{"Resolved?"}
staff["Human handoff<br/>staff workbench with full context"]
done["Resolution recorded + QA sample"]
track --> refund --> resolved
resolved -- "no" --> staff
resolved -- "yes" --> done
end
visitor --> ask
grounded --> search
pay --> track
staff -. "conversation continues with memory" .-> ask
done -. "cross-session facts" .-> ask
A user says "I want a refund". Here's what happens:
1. guardrail → scan for prompt injection, redact PII
2. detect_intent → classify: refund (task) | policy (rag) | chitchat (direct) ...
3. handle_switch → if intent changed, push current state to stack
4. route_intent → dispatch to the right branch
├── task → collect_slots → execute_tool → generate_response
├── faq → faq_lookup (curated answer, no retrieval hop)
├── rag → rag_lookup → generate_response
├── agent → handle_agent (LLM tool loop)
└── direct → direct_response
5. generate_response → claim-gated streaming (policy numbers verified
sentence-by-sentence before they leave the stream)
6. handle_handoff → emotion/complexity trigger → ticket + queue/AHT info
7. checkpoint → save state by session_id (Postgres checkpointer,
resume on next turn)
User: "我要退款"
→ refund, filled={}, pending=[order_id, reason]
→ "请提供您的订单号"
User: "订单号12345"
→ refund, filled={order_id:"12345"}, pending=[reason]
→ "请问退款原因是什么?"
User: "退货政策是什么" ← 🔄 intent switched!
→ push refund state to stack
→ policy → RAG 检索
→ "退货政策是7天无理由..."
+ "您之前的退款申请需要继续吗?"
User: "继续,原因是质量问题"
→ pop stack → resume refund + filled={order_id:"12345"}
→ filled={order_id:"12345", reason:"质量问题"}, complete
→ execute_tool: refund → {status:success, refund_id:"RF123456"}
→ "退款已受理,退款单号RF123456"
Two safety rules bound the resume feature:
- Executed tasks are terminal. Once a task's tool has actually run (a refund confirmed, an order queried), it is never pushed onto the stack and never auto-resumed — resurrecting it could only re-run an irreversible action (a second refund the user never asked for).
- Unrecognized input is answered, not hijacked. An "unknown" classification never silently resumes a suspended task: the question gets a direct answer plus a visible hint that the suspended task is still there; resume happens only on an explicit "继续" or by restating the task.
- Platform & runtime — macOS or Linux (what CI verifies), Docker with
Compose v2 (
docker compose; the stack relies on profiles and healthchecks). - Loopback ports — API
8000–8003(the first replica keeps8000for the reverse proxy), PostgreSQL5432, Redis6379, Qdrant6333/6334, Neo4j7474/7687; themonitoringprofile adds Prometheus9090and Grafana3001. Everything binds to127.0.0.1— nothing is exposed off-host. - One LLM provider key —
GLM_API_KEYby default; OpenAI, Anthropic, MiniMax, and Kimi are wired as well, and the failover chain uses every key you set. - Embeddings — the quickstart path embeds through your GLM key
(
EMBEDDING_PROVIDER=glm, the.env.exampledefault; the API image ships without the torch stack). Keyless offline BGE-M3 is available viapip install -e ".[local]"(a 6 GB+ torch install) on a host or venv. - Python ≥ 3.11 — for local development, the test suite, and the MCP example.
Copy .env.example before docker compose up: without an .env, Compose
defaults EMBEDDING_PROVIDER to local, which the stock image does not include.
git clone https://github.com/Bensonluo/rag_chatbot.git
cd rag_chatbot
# Configure environment
cp .env.example .env
# Edit .env: set GLM_API_KEY (and optionally MINIMAX/KIMI for speed tiers)
# Start the service stack (API + PostgreSQL + Redis + Qdrant + Neo4j)
docker compose up -d
# Or with monitoring stack (Prometheus + Grafana)
docker compose --profile monitoring up -d
# Verify
curl http://localhost:8000/health
curl http://localhost:8000/readyWant the full product with the bundled UI? The repo ships the standalone
Agent Store page (frontend/) — one command brings up
the page + API + commerce provider + data stores:
docker compose -f docker-compose.fullstack.yml up -d
# Agent Store page: http://localhost:3000Prefer make? make install, make compose-up, make test, make lint wrap the same commands — run make help for the full list.
Don't want to deploy? Try it online → — no signup, runs in your browser.
🔑 Note on API keys: configure at least one supported LLM key. Embeddings default to the local BAAI/bge-m3 model, so the first start downloads model weights and can take several minutes.
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
# Start PostgreSQL + Redis + Qdrant via docker compose
docker compose up -d postgres redis qdrant
# Run migrations & dev server
alembic upgrade head
uvicorn app.main:create_app --factory --reload --host 0.0.0.0 --port 8000📖 API docs (when running): http://localhost:8000/docs
The commerce provider ships a Model Context Protocol surface (Streamable HTTP) — the same authoritative facts and confirmation gates as the REST facade, speakable from any MCP host:
pip install -e ".[mcp]"
python -m app.commerce_provider.mcp_server --host 127.0.0.1 --port 8072 \
--database commerce_provider.sqlite3 --token "$COMMERCE_PROVIDER_AUTH_TOKEN"
# MCP endpoint: http://127.0.0.1:8072/mcp (Bearer token when set; empty token disables auth)Read tools (search_products, get_product, get_categories, discover_catalog) answer directly; write tools (update_cart → prepare_quote → create_order → sandbox_pay) carry an elicitation-style confirmation and derive request_key structurally, so a declined or retried request can never double-charge. Every tool declares spec annotations (readOnlyHint on reads; idempotentHint + explicit destructiveHint on writes) so MCP hosts can risk-classify calls without reading docstrings.
A runnable client is in examples/mcp_shopping_client.py —
it connects over Streamable HTTP with the official mcp SDK, lists the annotated
tool surface, and walks the complete purchase journey — cart → quote → order →
sandbox pay — answering every live elicitation confirmation by hand (or --yes
for scripted demos). It also calls create_order twice on purpose: the second
call replays the same order instead of creating a second one, and declining any
gate aborts with zero mutations.
See it run — terminal capture against a local server (--yes)
$ python examples/mcp_shopping_client.py --yes
connected: 8 tools
create_order destructive_hint=False idempotent_hint=True
discover_catalog read_only_hint=True
get_categories read_only_hint=True
get_product read_only_hint=True
prepare_quote destructive_hint=False idempotent_hint=True
sandbox_pay destructive_hint=False idempotent_hint=True
search_products read_only_hint=True
update_cart destructive_hint=True idempotent_hint=True
search '无线耳机': 3 result(s), total_estimate=998
SKU-00007168 恒锐 Astro A0000 耳机 ¥198.00
SKU-00007169 恒锐 Astro A0000 耳机 ¥198.00
SKU-00007170 恒锐 Astro A0000 耳机 ¥198.00
get_product SKU-00007168: 恒锐 Astro A0000 耳机 (¥198.00, stock=43, max_order_quantity=10)
=== purchase journey — each write needs a live confirmation ===
⟳ server asks: 确认提交购物车变更?
✓ auto-approved (--yes)
cart c_e538cba4380b47c9a7b3179470c68c1c v1 subtotal ¥396.00
⟳ server asks: 确认结算当前购物车并生成报价?
✓ auto-approved (--yes)
quote q_780c263d985d464a84495b163f283623 total ¥396.00 (expires 2026-11-14T16:33:46Z)
⟳ server asks: 确认依据该报价创建订单?
✓ auto-approved (--yes)
order o_8868b71b1c2a41b58d871bb116911166 status=awaiting_payment
⟳ server asks: 确认依据该报价创建订单?
✓ auto-approved (--yes)
retry create_order → o_8868b71b1c2a41b58d871bb116911166 (same order — replayed, nothing doubled)
⟳ server asks: 确认在沙箱中支付该订单?
✓ auto-approved (--yes)
payment pay_c537dab83b8e42449ebae3bf2b275098 status=paid
journey verified: quote → order → replay-safe → paid (sandbox)
Answering n at any gate instead prints the server's refusal —
user_declined: 未执行任何变更 — and nothing is written.
The product's own page is deployed and interactive at:
🎯 benluo.art/store/ — the standalone Agent Store page (this repo's
frontend/, deployed as its own unit); the project write-up lives on the author's portfolio.
A live shopping turn. Left: the agent proposes candidates under budget, adds nothing to the cart, and asks which color and quantity before ordering. Right: the real execution chain of that same turn — intent classification (shopping, 97% confidence), the agent tool loop with product searches and catalog lookups, per-stage latency, and turn metrics (TTFT, chunks, 27 trace events).
Try these scenarios (the demo replies in your language — EN / 中文 both work):
- 🛒 Shop with confirmation gates: Say "Gift: noise-cancelling earbuds under ¥400"(送女友一副降噪耳机,预算 400 以内)— the agent searches the catalog, proposes candidates, prepares a quote, and only orders after you explicitly confirm; payment is a separate confirmation
- 🔔 Pre-authorize a price watch: Say "Tell me when ANC-02 drops under ¥300"(ANC-02 降到 300 以内就来问我)— the next time fresh provider prices satisfy the rule, the agent asks exactly once, and the card's price wins over any narration
- 🧾 Track the order: Ask "Where is my order?"(我的订单怎么样了)— the timeline is rebuilt from authoritative rows (cart versions, quote TTL, order, payment, idempotency receipts)
- 🔄 Intent switch: Ask "I want a refund"(我要退款), partially answer, then ask "What's the return policy?"(退货政策是什么)
- 📚 RAG retrieval: Ask about return policy, shipping, warranty
- 🛠️ Function Calling: Complete a refund/return/order query workflow
| Layer | Choice | Why |
|---|---|---|
| Dialogue orchestration | LangGraph StateGraph | Conditional routing + checkpointing |
| API framework | FastAPI + async | High concurrency, OpenAPI built-in |
| Vector DB | Qdrant | Fast hybrid search, open-source |
| Graph DB (optional) | Neo4j | Knowledge graph for GraphRAG |
| Relational DB | PostgreSQL | Sessions, users, feedback |
| Cache | Redis | Rate limiting + L0/L1/L2 answer/semantic/retrieval caches (epoch-scoped) |
| LLM | GLM / OpenAI / Anthropic | Auto-fallback by API key availability |
| Embeddings | BGE-M3 (local) | Free, multilingual, no API key |
| Observability | OpenTelemetry + Prometheus + Grafana | Inspect demo traces and metrics |
Wiring as deployed by docker-compose.yml (monitoring stack behind the monitoring profile; GraphRAG and the MCP server are opt-in):
flowchart LR
Visitor["Browser<br/>(guest cookie identity)"]
Nginx["nginx reverse proxy<br/>(optional, multi-replica upstream)"]
subgraph app["API container"]
API["FastAPI<br/>SSE streaming · guardrails · rate limits"]
Engine["LangGraph dialogue engine<br/>(14 nodes, Postgres checkpointer)"]
MCP["Commerce MCP server<br/>(optional, mcp extra)"]
end
subgraph stores["State & knowledge"]
PG[("PostgreSQL<br/>sessions · tickets · feedback")]
Redis[("Redis<br/>rate limits · caches")]
Qdrant[("Qdrant<br/>vectors + BM25 hybrid")]
Neo[("Neo4j<br/>(optional GraphRAG)")]
end
Provider["commerce-provider<br/>154,624 SKUs · SQLite WAL<br/>quote → order → pay (CAS + idempotency)"]
subgraph obs["Observability (optional)"]
Prom["Prometheus<br/>dns_sd scrape"]
Graf["Grafana"]
end
Visitor --> Nginx --> API
API --- Engine
API --> PG
API --> Redis
API --> Qdrant
API -.-> Neo
API --> Provider
MCP -.-> Provider
API -.metrics.-> Prom --> Graf
Embeddings run in-process (local BGE-M3) — no external embedding service in the default deployment.
flowchart TD
START(("turn")) --> begin_turn["begin_turn<br/>reset turn state"]
begin_turn --> guardrail["guardrail<br/>injection scan · PII redaction"]
guardrail -- "blocked" --> DONE((end))
guardrail -- "continue" --> CACHE{{"L0 answer cache"}}
CACHE -- "hit" --> DONE
CACHE -- "skip · slots pending" --> collect_slots
CACHE -- "full" --> detect_intent
detect_intent --> handle_switch["handle_switch<br/>push / pop task stack"]
handle_switch --> ROUTE{{"route by intent"}}
ROUTE -- "task" --> collect_slots["collect_slots"]
ROUTE -- "knowledge" --> faq_lookup["faq_lookup<br/>curated fast path"]
ROUTE -- "agent" --> handle_agent["handle_agent<br/>bounded tool loop"]
ROUTE -- "handoff" --> handle_handoff["handle_handoff<br/>ticket + queue"]
ROUTE -- "direct" --> direct_response["direct_response"]
ROUTE -- "meta" --> generate_response
faq_lookup -- "hit" --> DONE
faq_lookup -- "miss" --> rag_lookup["rag_lookup<br/>hybrid + optional GraphRAG"]
handle_agent -- "done" --> DONE
handle_agent -- "fallback" --> collect_slots
collect_slots -- "missing" --> generate_response["generate_response<br/>claim-gated stream"]
collect_slots -- "complete" --> execute_tool["execute_tool"]
execute_tool -- "staged → confirm" --> DONE
execute_tool -- "done" --> generate_response
rag_lookup --> generate_response
generate_response --> DONE
direct_response --> DONE
handle_handoff --> DONE
Three wiring details worth knowing (all enforced by tests):
- A knowledge intent tries the curated FAQ fast path first; only a miss falls through to full RAG retrieval.
- Irreversible tools stage the action and end the turn with a fixed confirmation question — no LLM rewording between the user and the money.
- A failed agent run (provider without function calling, LLM outage) falls back to the deterministic slot pipeline mid-flow, so the user is still served.
rag_chatbot/
├── app/
│ ├── api/v1/ # REST endpoints (chat, auth, feedback, docs)
│ ├── services/
│ │ ├── dialogue/ # 🎯 LangGraph engine
│ │ │ ├── graph.py # StateGraph construction + compile
│ │ │ ├── nodes.py # dialogue node functions + conditional edges (14-node graph)
│ │ │ ├── state.py # DialogueState TypedDict
│ │ │ └── tools.py # ToolRegistry + 5 mock handlers
│ │ ├── agent/ # Agent tool loop (bounded iterations)
│ │ ├── faq/ # Curated FAQ fast path
│ │ ├── facts/ # Claim gate (stream) + curated facts + user_facts memory
│ │ ├── handoff/ # Human handoff tickets, queue/AHT, knowledge gaps
│ │ ├── retrieval/ # Hybrid search + rerank + Qdrant
│ │ ├── graph/ # GraphRAG (Neo4j, extraction, community)
│ │ ├── intent/ # Rule + LLM + hybrid intent detection
│ │ ├── slot_filling/ # Per-intent slot schemas
│ │ ├── guardrails/ # Input/output safety
│ │ ├── memory/ # 4 memory strategies
│ │ └── llm/ # Multi-provider LLM clients + <think> stream filter
│ ├── models/ # ORM + Pydantic schemas
│ ├── repositories/ # Async data access layer
│ └── tests/ # Unit + integration + e2e
├── deploy/deploy-server.sh # One-command service deploy (port-pinned, pre-flight gated)
├── deploy/k8s/ # Kubernetes manifests
├── deploy/prometheus/ # Alert rules (SLA / TTFT / claim gate / handoff queue)
└── docker-compose*.yml
| Variable | Description | Default | Required |
|---|---|---|---|
DATABASE_URL |
PostgreSQL connection string | — | ✅ |
REDIS_URL |
Redis connection string | — | ✅ |
QDRANT_URL |
Qdrant vector DB URL | — | ✅ |
SECRET_KEY |
JWT secret key | — | ✅ |
GLM_API_KEY |
Zhipu AI GLM API key | — | (any primary LLM) |
MINIMAX_API_KEY |
MiniMax generation backup and light-tier primary | — | ❌ |
GLM_LIGHT_MODEL |
GLM fallback for the MiniMax-led light tier | glm-5.3 |
❌ |
KIMI_API_KEY |
Kimi Coding generation fallback provider; optional intent override via INTENT_LLM_PROVIDER=kimi |
— | ❌ |
OPENAI_API_KEY |
OpenAI API key | — | (any primary LLM) |
ANTHROPIC_API_KEY |
Anthropic API key | — | (any primary LLM) |
EMBEDDING_PROVIDER |
Embedding source | local |
❌ |
GRAPH_RAG_ENABLED |
Enable GraphRAG (needs Neo4j) | false |
❌ |
The system is designed for swappable components:
# Intent detection: hybrid | rule_based | llm_based
INTENT_TYPE=hybrid
CONFIDENCE_THRESHOLD=0.7
# Memory: optimized | sliding_window | summarization | hybrid
MEMORY_TYPE=optimized
MEMORY_MAX_RECENT=3
MEMORY_TOKEN_BUDGET=4096
# Retrieval weights
VECTOR_WEIGHT=0.7
USE_RERANKING=true
GRAPH_RAG_FUSION_WEIGHT=0.3 # only if GraphRAG enabled
# Guardrails
GUARDRAILS_ENABLED=true
GUARDRAILS_HARDENING_ENABLED=true
# Authorization posture (review 2026-09-26, #1): DEMO_MODE=true keeps the
# public demo open for unmarked shared sessions. Private sessions always
# require their authenticated owner. Knowledge management and QA require
# active admins in both modes; false enforces token-only chat identity
# and ownership on every session.
DEMO_MODE=trueSee .env.example for the full list.
Chat answers and history include citations: reference snapshots with the
document revision, passage, available page/section location, and an excerpt.
Streaming clients opt in with include_citations: true to receive the final
event: citations frame before [DONE]; existing clients retain the text-only
protocol. Historical references keep their original versions after a document
update. These are references supplied for the answer, not proof of each claim.
See the citation contract for compatibility,
location semantics, cache behavior, and source-deletion boundaries.
Uploads retain the original source in PostgreSQL and return HTTP 202 with
document_id, version_id, revision, and status. Existing clients that
expected a completed upload at HTTP 201 must poll the revision endpoint.
The application worker processes queued revisions outside the upload request;
Postgres document locks serialize replacements across replicas. Interrupted
processing jobs resume after restart using the same chunk IDs.
| Operation | Endpoint |
|---|---|
| Upload text/Markdown | POST /api/v1/documents/upload |
| Upload PDF/TXT/MD | POST /api/v1/documents/upload/file |
| List documents | GET /api/v1/documents |
| List revisions | GET /api/v1/documents/{document_id}/versions |
| Processing status and warnings | GET /api/v1/documents/versions/{version_id} |
| Retry a failed/partial latest revision | POST /api/v1/documents/versions/{version_id}/retry |
| Download retained original | GET /api/v1/documents/versions/{version_id}/source |
| Read normalized text for source offsets | GET /api/v1/documents/versions/{version_id}/text |
| Delete indexes and retained sources | DELETE /api/v1/documents/{document_id} |
| Check registry, vector store, and worker | GET /api/v1/documents/health |
Knowledge lifecycle management requires an active administrator in both Demo and strict modes, including catalog/version inspection, retained originals and normalized text. Open registration grants customer access only; customers may search published evidence but cannot manage shared knowledge. Sensitive document responses and handled auth/validation errors use private,no-store headers. See the knowledge access contract.
Text upload example (with an active administrator bearer token):
{
"document_id": "refund-policy-us",
"title": "Refund policy",
"file_type": "md",
"content": "# Refunds\n\n## Exceptions\nOpened products require review.",
"metadata": {"lang": "en", "topic": "refunds", "product": "physical-goods", "region": "US"}
}Use the same document_id for a replacement. Repeated identical submissions
return the same revision; changes to content, policy scope, or processing
configuration create another revision. Status transitions are
queued → processing → indexed; failures are explicit failed or partial
(the latter means the vector index succeeded but optional graph indexing failed).
Informational OCR/blank-page warnings do not turn a complete index into a partial job.
A failed embedding step preserves the previous index. Qdrant replacement writes
the new points before removing superseded points; it is not a transaction across
Postgres, Qdrant, and Neo4j. New retrieval evidence and cache hits must match the
committed active-version registry; failed/unactivated candidates are withheld.
Publication can temporarily leave no eligible evidence if old points were removed
before a registry failure; retry converges on the retained revision. Existing
active versions remain eligible during a retry attempt. Unregistered raw corpora
must be re-ingested through the durable jobs. Do not run another uncoordinated
writer against the same document IDs. See the
publication contract and migration boundary.
Each Qdrant point stores chunk_id, parent document_id, content, and metadata:
| Metadata | Contract |
|---|---|
document_id, version_id, chunk_id |
Stable policy identity, immutable revision, deterministic passage ID |
index, start_pos, end_pos |
Chunk order and exact character interval in the retained normalized text |
chunk_size, chunking_strategy |
Actual character count and splitter used |
title, original_filename, file_type, source |
Original source identity, never temporary paths |
page_start, page_end |
PDF page range; absent for plain text |
section_path |
Markdown heading hierarchy, excluding code blocks |
lang, topic, product, region, category |
Validated author-supplied support scope, usable as retrieval filters |
content_hash |
SHA-256 of the uploaded bytes, shared by all chunks in that source revision |
pipeline_version, embedding_provider, embedding_model |
Processing provenance |
The design has three identity levels. document_id means a logical policy and
survives edits; supply it explicitly for predictable replacements. version_id
identifies one immutable revision of its source, scope, and processing configuration.
chunk_id identifies one passage within that revision. It is generated deterministically
from the document/revision, splitter, chunk index, start offset, and content. A retry
therefore overwrites the same points, while a new revision cannot accidentally reuse
the previous revision's passage IDs. Identical wording in different policies still
has different IDs because its provenance differs.
Source locations use zero-based Python string positions, with an exclusive end_pos:
chunk.content == normalized_text[start_pos:end_pos]. These are character offsets,
not byte offsets, PDF coordinates, or token counts. Normalized text is retained
alongside the original bytes so this relationship remains inspectable after newline
normalization or OCR. PDF pages are one-based; text files have no invented page
numbers. Markdown section_path describes the heading ancestry at the start of the
passage; an overlapping chunk can also contain material from the adjacent section.
Support scope is copied onto every chunk so the vector and keyword stores can filter
without a database join. Authors supply lang, topic, product, region, and
category; the pipeline does not guess an authoritative policy scope from prose.
For example, a caller can filter a refund query to the relevant product and region.
Choose consistent values when uploading; these are exact filter values, and merely
storing them does not automatically select the customer's region. Scope metadata
is not an access-control boundary. Tenant isolation, permissions, approval state,
and effective-date rules would need explicit validation and enforcement in every
retrieval path before becoming supported policy controls.
Processing provenance answers a different question: how was this evidence built?
content_hash detects identical uploaded bytes; it is not the document's identity.
pipeline_version, the saved chunking configuration, and embedding provider/model
make rebuilds and debugging traceable. Job state, retries, errors, originals, and
uploader identity live in the PostgreSQL revision registry instead of being copied
into every searchable passage. Chunk metadata is intentionally a small retrieval
and citation record, while the registry owns the ingestion lifecycle.
Reserved system fields cannot be overwritten by upload metadata. Uploader identity stays in the registry, outside retrievable chunk payloads. Vector search, keyword search, reranking, and graph fusion keep passage identity separate from parent document identity. Page references remain in retrieval metadata; answer citations retain the parent document IDs, including evidence retrieved through the graph. Curated FAQ and fact-check tables are maintained separately; uploading a policy does not automatically rewrite those reviewed answers or numeric facts.
PDF extraction preserves page boundaries and layout whitespace. Scanned pages use local Poppler + Tesseract OCR with English and Simplified Chinese language packs included in the Docker image. A page requiring unavailable/failed OCR fails the job with an actionable error, rather than silently omitting its evidence. Blank pages are reported; encrypted PDFs require an unlocked source. Complex tables and OCR output still need author review against the retained original.
Run alembic upgrade head before starting a source checkout; the standard container
entrypoint runs migrations. Rebuild the image to install the OCR binaries. Local
hosts also need pdftoppm, tesseract, and the configured language packs to process
scans. DOCUMENT_MAX_BYTES defaults to 50 MiB, chunk size/overlap to 512/50
characters; long documents are no longer silently truncated. Configure these via
.env.example. Original bytes are stored in Postgres, so include them in database
backup/retention sizing. Changing embedding providers/models requires a new vector
collection and re-ingestion; queued jobs with an outdated model configuration fail
explicitly. Pre-existing chunks have no recoverable original source: re-upload
those documents to obtain the new provenance and revision lifecycle.
PostgreSQL backup and new-database recovery are covered by a disposable PostgreSQL 16 drill, including historical citations, document bytes, handoff state, and same-database dialogue checkpoints. Follow the backup and recovery runbook to select the correct Compose stack and verify a restore. Qdrant/Neo4j recovery and separately configured checkpoint databases require their own recovery plans.
# Maintained core suite (70% minimum; currently 4148 passed + 3 opt-in skipped / 93.71%; frontend adds 147)
pytest
# Targeted runs
pytest app/tests/unit/services/dialogue/ -v # LangGraph tests
pytest app/tests/unit/services/intent/ -v # Intent detection
# Legacy audit only (contains superseded contracts; not expected to be all green)
pytest app/tests --no-cov
# Use promtool from the deployed Prometheus 2.47.2 release
promtool check rules deploy/prometheus/alerts.yml
promtool test rules deploy/prometheus/containment-alerts.test.ymlAnswer evaluation separates given-context point coverage from evidence-grounded pipeline grading. The last live run (2026-10-22, operational-evidence rubric) passed 23 judge controls and 14 bilingual turns using GLM generation and MiniMax judging. This remains a synthetic isolated measurement, not overall product acceptance. See the evaluation runbook and recorded results. A separate zero-LLM strict-mode route test now covers owner chat, handoff, claimed staff context with citations, and denial after resolution.
The live probe checks response/session identity, queued-ticket IDs and policy citation anchors. Optional authenticated mode allocates owned sessions and reads their history; a separate staff client can observe ticket/session/owner pairs without claiming tickets. Default anonymous PASS without a staff observer leaves ticket persistence unverified; random IDs provide best-effort session isolation. See the probe runbook for credential configuration, side effects, bounded queue scans and evidence limits.
# Full checks used by CI
ruff check app/
ruff format --check app/
mypy app/Local verification on 2026-10-28: 3720 tests pass, with three opt-in scenarios
skipped by default (PostgreSQL concurrency, assigned-transcript locking, and
the Docker recovery drill);
selected core coverage is 93.57%, not a coverage claim for chat/handoff/API code.
Maintained Ruff lint passes for app/, migrations/, and the three CLI paths
scripts/init_db.py, scripts/document_import.py, and scripts/probe_live.py.
Format checking passes for app/ plus scripts/probe_live.py (496 files);
strict Mypy passes for 495 app/ Python files and those three CLI files.
Authenticated HTTP/SSE regressions cover chat ownership, guarded text and
citations, plus ASGI 2.3/2.4 disconnect persistence; the earlier socket-blocked
run is recorded in the boundary evidence.
The refund-review regression covers 24 socket-blocked cases (22 real service/graph,
2 strict JWT HTTP): high-value review tickets, write failures and retry, cancellation,
order access, single stream emission and low-value controls. See the refund review evidence.
Context-aware L0/L1 replay also passes 12 real service/graph cases plus a separate
14-contrast actual semantic-cache audit using local I/O seams. Anonymous stateless
hits remain available; applicable or unavailable history blocks shared replay and
write. See the cache-context evidence.
Persisted reply failures now remain visible beside containment: 15 real SQLite/JWT HTTP
cases verify cohort counts, latest-reply ordering, Prometheus output and outage handling.
Grafana separates counts, ratios and refresh age; see the metric contract.
The probe revision passes 82 focused cases, including six real route scenarios with
SQLite/FAQ/JWT: owned histories and separate staff ticket observation, database refusal,
uncited answers and denied observer access. No live model or production service was used.
See the probe evidence.
Containment alerts now separate fresh business snapshots, unavailable statistics and
clock skew. Native Prometheus timing tests are required by a dedicated CI job configured with
the same engine version as deployment; see the alert runbook.
Rule evaluation tests do not prove external notification delivery.
The following database checks were verified in earlier iterations and were not
rerun on October 28. All 8 PostgreSQL concurrency tests
and the SQLite/PostgreSQL migration round trips pass in isolated databases.
The new PostgreSQL backup/recovery drill also passes with explicit Docker opt-in.
CI migration/recovery commands were verified locally; remote CI was not triggered.
See the iteration record for evidence
and migration precautions. On October 28, the companion portfolio-fe passed
177 tests (148 Jest + 29 citation/stream protocol tests), lint, strict TypeScript
checks and an 11-page static build after a clean install. Failed or interrupted
chat replies retain their partial text and cannot become canned business replies;
completion requires the stream's explicit terminator. Next and its ESLint config
were upgraded from 16.3.8 to 16.4.3; runtime npm audit reports zero advisories
(development dependencies excluded). Browser visual/interaction verification was
unavailable. This is the round-17 baseline; see the
frontend evidence.
The round-18 iteration passes 227 frontend tests (172 Jest + 55 protocol), lint,
strict TypeScript and the 11-page static build. It carries committed message IDs/status through REST,
opt-in SSE and history, and restricts feedback to completed assistant replies.
The shared Demo page still requires an existing token to rate replies and has
no new sign-in flow in that round. See the
message/feedback contract and
verification results.
The round-20 companion frontend adds /support/ with real sign-in, private customer sessions,
assigned staff messaging and a saved final explanation plus closure. Its complete suite passes
263 tests (208 Jest + 55 protocol), lint, strict TypeScript and a 12-page static build.
That round passed 3232 backend tests, including 83 new default cases. Existing 93.35% coverage
measures the selected core modules; it does not measure chat/coordinator/handoff/API code.
Private sessions also enforce owner checks in Demo mode, private feedback requires ownership,
and QA access requires admin in both modes. Shared legacy tickets have no private human channel.
Round20 introduced migration a31e8d7f6290 and required draining old app instances before
allowing private consultations; current builds require the newer head described below.
Private sessions/human rows/nonzero automation generations block downgrade;
restarting old Demo binaries can bypass privacy. Local SQLite migration round trips and
schema alignment pass. PostgreSQL advisory-lock coordination has a separate bounded pool and
CI-selected independent-connection regression, but was not executed on real PG this round;
both local Docker socket contexts were unavailable. No browser, production or real payment
acceptance is claimed. See the human conversation contract
and round-20 evidence.
Round21 makes customer resolution evidence consistent across AI and human messages. New human customer messages use the existing conservative confirmation/reopen policy in the same transaction as their text; UUID replay cannot overwrite a later result, and staff text/closure is not customer confirmation. Human rows do not increase bot-served cohorts. The workspace also prevents delayed GET/ACK responses from regressing ticket state and rejects invalid JSON enum types. No new outcome API, schema or confirmation buttons were added. Full regression: 3288 backend tests (3 existing opt-in skipped), and 272 frontend tests (217 Jest + 55 protocol), lint/types and 12 static pages. See the followup evidence.
Round22 requires an active administrator for knowledge lifecycle management in both Demo and strict modes, including retained originals and unpublished version metadata. Open registration no longer grants knowledge operator access. Sensitive document responses and handled auth/validation errors are private,no-store; ordinary customer search and shared Demo chat are preserved. New actual JWT/SQLite/jobs/local Qdrant coverage adds 32 cases; the role matrix grows from 3 to 10 (net 7), bringing the full backend suite to 3327. Frontend code is unchanged from the prior 272-test baseline. See the access contract and round22 evidence.
Round23 adds a durable SQL execution ledger for confirmed refund/return and MCP write proposals.
Checkpoint failures and fresh-confirm retries replay the saved result for the same UUID;
unknown outcomes block another dispatch, and cancellation cannot claim an earlier request
was reversed. A saved adapter result is distinct from business success. Production startup
requires migration b42f9c8e7310; drain old instances before enabling this guarantee.
The new124 default cases cover ledger/migration, both graph/AgentService proposal paths,
actual HTTP/SSE/SQL faults, authority, metadata and MCP parameter binding. Local SQLite
full migration round trips pass; real PG, external payment/MCP and browser acceptance remain
unverified. See the durable action contract and
round23 evidence.
Round24 (historical baseline) preserves support drafts and immutable human-send attempts across reload, consultation switches and same-user sign-in recovery. Drafts keep their original AI/human recipient until an explicit move. New customer sends bind expected_ticket_id; old-ticket attempts cannot enter a newer ticket. Closed staff attempts have an explicit saved-work recovery entry. New 13 actual backend cases bring the full suite to 3464; frontend passes 288 Jest + 55 Node = 343, lint, strict types and 12 static pages. Local recovery is bounded and cannot replace server authorization or business idempotency. See the continuity contract and round24 evidence.
Round25 (historical baseline) binds workspace conversation operations and local recovery to a server-generated
session_key, preventing an old draft or retry from entering a replacement consultation
when numeric session/ticket IDs are reused. Private content requests carry the expected key;
clear-history rotates the key and automation epoch before cleanup. Journal v2 includes the
key; legacy v1 recovery requires explicit local discard and is never silently adopted.
The authenticated operator probe also carries and checks the original server key.
Upgrade all clients and backends to migration head c53a7d9e8421 (after b42f9c8e7310),
with old instances drained and SQLite writers stopped during migration.
New 66 backend cases (17 migration, 42 actual lifecycle, 7 operator) bring the full suite
to 3530 passed and 3 opt-in skipped. New 11 frontend cases (7 journal, 4 actual React)
bring its complete suite to 354 (299 Jest + 55 Node), with lint, strict types and 12 static
pages passing. The frozen manifests cover 501 backend Python and 86 frontend source/config
files. These are local SQLite/JWT and controlled-fetch checks; real PG, browser/hydration,
production migration and external commerce remain unverified. The activity-ordering
candidate is deferred, and the purchase integration design remains proposed.
See the session incarnation contract and
round25 evidence.
Round26 binds feedback and QA mutations to the object and evidence actually selected.
Private feedback requires the displayed session key; the server reauthorizes inside the
conversation gate and atomically binds the SQL update to owner, parent, key and a completed
assistant answer. A committed immutable receipt fixes the original message/session/key;
metrics and best-effort cache cleanup run outside the gate so slow cleanup cannot hold
up a later conversation action. QA queue/context now provides a session key and opaque
review version; verdicts require both and reject a proposal made stale by a new question,
feedback, human message or review correction. Explicit GET review permits a fresh correction.
The projection is streamed in batches of 256, but still reads O(N) bot rows; this is not
an audit log, proof of transcript comprehension or a PostgreSQL/capacity acceptance result.
The final complete backend suite passes 3581 cases with 3 opt-in skips and 93.57% selected
core coverage. The earlier 3580-case run is a historical pre-fix result; the final suite
includes the post-commit cleanup regression. New default cases total 51: 15 feedback unit
and 36 actual HTTP/SQLite scenarios. Frontend at that checkpoint passes 367 (312 Jest + 55 Node);
its 13-case increase comprises 7 feedback guards and 6 preserved locale tests from concurrent
workspace changes. Frozen source covers 502 backend Python and 86 frontend source/config
files, with 14 backend and 6 frontend changes versus round25. No new migration is needed;
head remains c53a7d9e8421 and clients must
adopt the new private feedback/QA contract. See the quality mutation contract
and round26 evidence.
The public website uses server-issued HttpOnly session cookies and a private
conversation per browser, without registration. The existing /support/ workspace
is retained; product work focuses on the public experience.
Mock shopping is now an Agent orchestration demo with no purchase buttons. The
bounded Agent queries the existing Neo4j product knowledge graph for use-case
and category semantics, discovers the provider's authoritative category taxonomy,
maps open-ended natural-language needs onto one or more standard categories,
performs structured multi-category search/pagination, understands references and
constraints, updates a multi-line cart, prepares a quote, creates an order and
settles mock payment entirely through chat text. Catalog turns keep at most five
typed candidates, balanced across the searched categories, while the LLM may
compose labeled bundle advice only from that displayed set. commit_checkout and
mock_pay are Agent tools only when the current turn carries a fresh, explicit
authorization for the latest displayed purchase version; handlers recheck owner,
stage, confirmation/payment and generation. The two irreversible steps require
separate confirmations. The live Execution Chain publishes the provider router's
intent and confidence before any business work.
Commerce facts live in the separate internal commerce-provider FastAPI service:
a deterministic 154,624-SKU addressable catalog (151 categories across 18
daily-life domains, each deliberately shallow at 32 brands × 8 models × 4
variants with a per-category variant axis), SQLite-backed multi-line carts,
quotes, stock deltas, orders, payments and
idempotency receipts. The API reaches it only through ExternalCommercePort;
provider failure makes shopping explicitly unavailable and never falls back to a
local or regex planner. PurchaseService keeps only durable safety orchestration —
owner binding, immutable quote confirmations, version CAS, operation idempotency
and recovery. Unknown or processing results only query the original operation;
clearing chat does not delete or repeat a purchase. Catalog turns render the
LLM's labeled bundle advice plus authoritative typed provider facts, while cart,
quote, order and payment stages remain server-rendered and the model cannot
invent success. All commerce is visibly simulated.
Current text-commerce backend gate: Ruff, formatting and strict Mypy pass. For this graph update, the release gate intentionally runs targeted representative suites instead of the 3,800-test full suite at user request: commerce/provider/evaluation checks plus graph/initialization checks pass, and live production canaries below verify the new path. The earlier pre-graph full-suite baseline remains 3,803 passed / 3 skipped / 5 warnings. A real local HTTP smoke drove the external adapter through
search → multi-line cart → quote → order → payment → status, including stable
request-key replay and refusal of a conflicting replay. The production canary
then completed the same text-only journey against the separate internal
provider with three cart lines, one order, one payment and zero purchase-action
A later production browser canary sent the open-ended
“budget ¥1,500 remote-office setup” request and received labeled bundle advice
plus candidates from monitor, keyboard, mouse, headset, webcam and ergonomic
chair categories; persisted metadata recorded planner_mode=provider, one
commerce_discover_catalog call, six category searches and zero model-invented
max_price filters, with no purchase mutation. The reply also disclosed that
facts come from the separate internal virtual storefront API while ordering and
payment remain simulated. See the
external provider deployment record
and the earlier Agent text-commerce record.
New migrations are d64b8c0f9532 (anonymous visitors) and e75c9d1064a3
(commerce framework), following c53a7d9e8421. The 2026-10-29 deployment kept
the database at e75c9d1064a3 and restored no old image or backup.
GUEST_COOKIE_SECURE=true requires HTTPS; disable it only for local HTTP.
Cookie identity represents its browser, with no real-person or cross-device
recovery promise. See the public commerce contract.
The round27 numbers below are the historical button-card baseline:
3709 backend tests, 398 frontend checks, strict types/lint/build and a native
Chrome mock journey passed then. See
round27 evidence.
Neither the historical run nor the current mock deployment verifies real
payments, supplier integration, production concurrency/capacity or a real
commerce rollout.
The preceding button-card implementation committed its conversation task boundary before invoking Agent or business operations. A failed fence blocked the operation; later model errors, cancellation or chat-save failures could not reactivate an earlier refund proposal. Commerce requests waited at most 30 seconds, then required explicit status recovery without resubmission. Its local gate passed 3720 backend and 407 frontend tests plus lint, strict types and a 12-page build. The timeout path used real React and controlled fetch; the prior milestone used real Chrome. These reliability semantics carry forward, while its action-ref UI contract is obsolete. See the milestone record and reliability evidence.
| Metric | Value |
|---|---|
| Maintained test results | 4148 backend passed (3 opt-in skipped, 4 xfailed) + 147 frontend tests |
| Maintained core coverage | 93.71% (70% minimum enforced locally; main dialogue path graph/nodes/tools measured since 2026-10-01) |
| Python files (app/, incl. tests) | 562 (269 source + 293 tests) |
Reproduce the offline gates with python scripts/run_retrieval_eval.py and
python scripts/run_routing_eval.py — both run the real pipeline with deterministic
stubs only at network seams, no model keys needed. The answer-quality gate is
LLM-tier: python scripts/run_answer_eval.py (requires a configured LLM key).
| Evaluation | Scope | Result (2026-11-14) |
|---|---|---|
| Retrieval golden set | 48 bilingual cases | CJK-bigram keyword arm recall@1/3/10 = 0.875 / 0.979 / 1.000, MRR 0.924 (zh 0.917/1.000/1.000; the pre-bigram tokenizer scored 0.000 on zh) |
| Routing golden set | 19 cases / 31 turns over the real compiled graph | 31/31 passed (100%) — confirmation gates, guardrail block, FAQ fast path, no-evidence, handoff, cross-turn |
| Answer quality (LLM-tier) | 20 curated questions | 18/20 passed (90.0%), point coverage 93.8%, zero forbidden hits — given-context generation gate, real model, 0 judge/generation errors (2026-11-14); methodology: docs/operations/answer-quality-evaluation.md |
- LangGraph StateGraph with 14 nodes + conditional routing
- Intent switch & resume via state stack
- Task terminality guard (executed tasks never suspended or auto-resumed)
- Hybrid retrieval (vector + BM25 + rerank)
- GraphRAG with Neo4j (optional)
- OpenTelemetry tracing + Prometheus metrics
- 4,100+ passing tests, 93.5%+ coverage; routing golden-set eval (19 cases / 31 turns over the real compiled graph) + retrieval baseline; runtime dependency lock (requirements-lock.txt) + pip-audit in CI
- Public shopping agent: semantic routing, deterministic virtual-catalog provider, staged quote → order → payment with expected_version CAS + request_key idempotency
- Server-authoritative cards: approval and price-watch cards assembled from durable rows + provider facts, riding the SSE completion receipt; the card wins over narration
- Pre-authorized price watches: "SKU X ≤ ¥Y → ask me" rules with event-driven evaluation and exactly-once ask delivery (notify-only, 5 rules / visitor, 30-day expiry)
- Order timeline: full event chain rebuilt from authoritative purchase/operation/confirmation rows as a read-only owner-scoped tool
- Shopping-agent evals: guest commerce flow suite + prompt-injection red-team corpus
- FAQ fast path (curated answers skip retrieval)
- Agent tool loop with bounded iterations
- Claim-gated streaming (policy numbers verified before release)
- Cross-session user memory (user_facts + TTL recall cache)
- Human handoff: private login workspace, assigned-agent context, bidirectional human messages, atomic final reply/closure and claimed-session automation pause
- Postgres checkpointer (AsyncPostgresSaver, MemorySaver fallback)
- Prometheus alert rules (SLA / TTFT / claim gate / handoff queue)
- Epoch-scoped cache pyramid (L0 answer / L1 semantic / L2 retrieval)
- Containment proxy and reply-status cohorts (separate from confirmed resolution, DB-bridged gauges)
- 2→N scaling readiness (nginx upstream template + dns_sd multi-replica metrics)
- Graceful shutdown choreography (background refreshers stop before pools close)
- Standalone Agent Store page bundled in-repo (
frontend/) and deployed as its own unit — the repository is the complete product, backend to UI - Fine-tuned intent classifier (replace LLM-based with small specialized model)
- A/B testing framework for prompt variants
- Multi-tenant knowledge bases
PRs welcome! Especially:
- 🐛 Bug fixes — please include a failing test
- ✨ New dialogue node types or slot strategies
- 📚 More GraphRAG use cases (currently: customer service KB)
- 🌍 i18n improvements
Setup instructions, quality gates, and commit/PR conventions are in CONTRIBUTING.md. For vulnerabilities, follow SECURITY.md — do not open public issues for security reports. By participating in this project you agree to uphold the Code of Conduct. Notable changes are documented in CHANGELOG.md.
MIT — free for personal and commercial use.
If this project helped you, please ⭐ star the repo — it helps others discover it.
- 💼 Portfolio: benluo.art
- 🐙 GitHub: @Bensonluo
- 💬 Issues: GitHub Issues
Agent Store — 可托付的购物 Agent 与企业级智能客服 — 一套可信 Agent 引擎,两种业务:面向公众的购物 Agent 完成「检索 → 报价确认 → 幂等下单 → 付款确认」全链交易,并带预授权降价提醒与订单时间线;同一引擎支撑企业知识服务与业务办理,连接多轮任务、版本化知识、可追溯回答与人工工单,覆盖对话编排、检索治理、安全门控和运维观测。
- 交易型购物 Agent:开放需求 → 类目映射 → 工具循环(20 步 / 30 次 LLM 调用双预算),报价 → 下单 → 付款分阶段注册并各自显式确认,expected_version CAS + request_key 幂等,断线重连不重复扣款
- 确定性虚拟目录:SKU 事实按纯函数从稳定地址空间按需投影,SQLite 只存交易与 delta;每轮最多呈现 5 个 typed SKU
- 检索韧性三态:空知识库如实回答「未找到」而非假报服务中断;切换 embedding 供应商后维度漂移自动检测——空库按新维度重建、非空库给出含两个维度值与修复路径的明确报错;运行中 collection 被删(卷清/误操作)时,搜索与写入各获得一次闩锁对账重试,无需重启进程
- MCP 服务器:商店事实层内建 Model Context Protocol 面(Streamable HTTP):只读工具(search/详情/类目/目录导览)直答,写工具(加购→报价→下单→沙箱支付)带确认门控,结构化 request_key 幂等——任何 MCP 宿主可直接对话本店
- 预授权降价提醒:「SKU X ≤ ¥Y 就来问我」事件驱动评估,exactly-once 送达,只提醒不代下单(每访客 5 条、30 天过期)
- 服务端权威卡片:审批卡/降价提醒卡字段全部来自持久行 + provider 事实,与模型口述冲突时以卡为准
- 订单时间线:从权威行重建购物车版本、报价 TTL、下单、付款与幂等回执的全链事件,只读且 owner-scoped
- LangGraph StateGraph 对话图:14 节点编排(安全检查 → 意图识别 → 意图切换 → 路由 → 槽位/工具/FAQ/RAG/Agent → 生成 → 转人工)
- 业务意图分类:5 种任务型(退款/退货/订单查询/物流追踪/投诉)+ 知识型 + 对话型 + 元意图
- 五路路由:task → 槽位收集 → 工具执行;faq → 策展命中直出;rag → 检索生成;agent → 工具循环;direct → LLM 直答
- 多轮槽位收集:正则提取 + 短消息回退,缺槽追问
- Function Calling:ToolRegistry + 5 个 Mock 工具 + Agent 工具循环
- 意图切换与恢复:State Stack 推栈保存/弹栈恢复;已执行任务为终态,不再挂起或自动恢复(防止二次执行)
- 声明门控流式输出:句子缓冲 + 策展事实校验,越界声明拦截/改写后才放出
- 跨会话用户记忆:user_facts 长期画像 + TTL 召回缓存
- 人工接续:情绪/复杂度触发工单,登录后私人咨询、客服领取与双向消息、最终说明和关闭同事务;接单后暂停机器人,旧共享 Demo 仅原历史和行政关闭
- GraphRAG:Neo4j 知识图谱 + Text-to-Cypher + 社区发现
- 混合检索:向量 + BM25 → RRF 融合 → Cross-Encoder 重排序
- 全链路可观测:OpenTelemetry + Prometheus 指标(TTFT/时长/结果)+ SLA/策略门控告警规则
- 缓存金字塔:L0 答案缓存 / L1 语义缓存 / L2 检索结果缓存,KB epoch 轮换整体失效,无逐键驱逐
- 自动处理率 KPI(containment rate):北极星指标,无转人工工单且无差评的会话占比;口径是「未升级」,不等同「已解决」;Prometheus DB 桥接 gauge
- 横向扩展就绪:单机即节点模板(compose 端口段 + nginx upstream + dns_sd 多副本抓取),2→N 不重构
- Checkpoint 持久化:LangGraph Postgres Checkpointer(本地降级 MemorySaver)
git clone https://github.com/Bensonluo/rag_chatbot.git
cd rag_chatbot
cp .env.example .env # 填入 GLM_API_KEY
docker compose up -d带界面一条命令起全栈(品牌页 + API + 商城 provider + 数据库):
docker compose -f docker-compose.fullstack.yml up -d
# Agent Store 页面: http://localhost:3000环境要求:macOS / Linux(CI 验证)+ Docker Compose v2;回环端口 API 8000–8003、PostgreSQL 5432、Redis 6379、Qdrant 6333/6334、Neo4j 7474/7687,monitoring profile 追加 Prometheus 9090 与 Grafana 3001(全部只绑 127.0.0.1,不对外暴露);.env 至少一个 LLM key(默认 GLM_API_KEY);快速开始路径用 GLM key 做向量(EMBEDDING_PROVIDER=glm),离线免 key 方案需 pip install -e ".[local]"(6 GB+ torch);本地开发 / 测试 / MCP 示例需 Python ≥ 3.11。请先 cp .env.example .env 再启动 —— 缺省时 Compose 会把 EMBEDDING_PROVIDER 置为 local,而 API 镜像不带 torch。
访问 http://localhost:8000/docs 查看 API 文档。
在线演示:benluo.art/store/ — 无需注册,中英文均可对话。
更新记录:重要变更见 CHANGELOG.md;常用命令 make help 一键查看。
部署与接入:默认启动单 API 实例;企业业务接口通过 ToolRegistry 接入,鉴权、数据留存、监控与副本按部署环境配置。多租户知识隔离列在路线图,当前验证结果见 Testing & Quality。