Skip to content

About

An agent you can trust with money — agentic commerce with quotes-before-orders, idempotent payments and exactly-once price alerts, on an engine that also delivers cited RAG customer service. FastAPI + LangGraph + MCP.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

335 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Agent Store

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.

Live Demo Release CI GitHub stars License: MIT

Python FastAPI LangGraph Docker

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

Agent Store landing page: confirmation-gated buying and support flows, with quotes before orders and every irreversible action behind an explicit user confirmation

(the landing page of the bundled frontend — live demo; the UI is bilingual, following the visitor's language)

Agent Store demo: a gift-shopping chat turn beside its execution trace

(a live turn with its execution trace — full demo below)


📌 Table of Contents


💡 Why This Project

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.

Enterprise architecture and delivery

  • 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.

Similar projects

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.


✨ Key Highlights

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


🔄 How It Works

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
Loading

Turn-level walkthrough

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)

Intent Switch & Resume — the killer feature

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.

🚀 Quick Start

Requirements

  • 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 keeps 8000 for the reverse proxy), PostgreSQL 5432, Redis 6379, Qdrant 6333/6334, Neo4j 7474/7687; the monitoring profile adds Prometheus 9090 and Grafana 3001. Everything binds to 127.0.0.1 — nothing is exposed off-host.
  • One LLM provider key — GLM_API_KEY by 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.example default; the API image ships without the torch stack). Keyless offline BGE-M3 is available via pip 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.

Option 1: Docker Compose (recommended)

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/ready

Want 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:3000

Prefer make? make install, make compose-up, make test, make lint wrap the same commands — run make help for the full list.

Option 2: Try the Live Demo first

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.

Option 3: Local development

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

Optional: expose the store as an MCP server

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.


🌐 Live Demo

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.

Live demo: a gift-shopping turn with its full execution trace

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

🏗️ Architecture

Tech Stack

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

System Components

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
Loading

Embeddings run in-process (local BGE-M3) — no external embedding service in the default deployment.

LangGraph Dialogue Graph

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
Loading

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.

Project Structure

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

⚙️ Configuration

Core Environment Variables

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 ❌

Pluggable Strategies

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=true

See .env.example for the full list.


Document ingestion for support knowledge

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.


🧪 Testing & Quality

# 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.yml

Answer 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.

Code Quality Gates

# 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.

Public visitor chat and Agent text commerce (current)

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.

Historical button reliability milestone (2026-10-28)

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)

Measured evaluation baselines (offline, deterministic)

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

🗺️ Roadmap

  • 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

🤝 Contributing

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.


📜 License

MIT — free for personal and commercial use.

If this project helped you, please ⭐ star the repo — it helps others discover it.


📬 Contact


🇨🇳 中文说明

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。

About

An agent you can trust with money — agentic commerce with quotes-before-orders, idempotent payments and exactly-once price alerts, on an engine that also delivers cited RAG customer service. FastAPI + LangGraph + MCP.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages