Building an Adaptive-RAG E-Commerce Customer Service Agent from Scratch: Adaptive Retrieval, Intent Recognition, and Order Tools

Project Overview

Adaptive-RAG E-commerce Customer Service is an intelligent customer service project for handling policy inquiries with multiple conditions. It focuses on addressing insufficient evidence, unsupported answers, and complex questions that cannot be fully answered in a single retrieval. The backend is powered by FastAPI and LangGraph, while the frontend uses React. Based on user intent and question complexity, the system dynamically selects among direct answering, knowledge retrieval, supplementary retrieval, tool execution, human confirmation, and refusal.

The project is suitable for local demonstrations, learning Adaptive RAG workflows, and engineering validation. It supports policy source citations, demo order queries, pending confirmations, conversation memory, and SSE responses. However, its order and logistics data are not real business data.

The current API directly accepts the user_id supplied by the client and does not yet verify the user's identity. Do not deploy the project directly to the public internet without integrating trusted identity authentication, TLS, and access controls.

How the System Processes a Request

After a user submits a question through the web page or HTTP API, the request passes through an input guardrail, intent recognition, and complexity routing in sequence. The system then selects the appropriate processing branch and completes answer generation, faithfulness checking, conversation memory updates, and citation return.

User → Web / HTTP API → Input guardrail
     → Intent recognition → Complexity routing
       ├─ Direct answer
       ├─ Retrieval → Reranking → Supplementary retrieval when needed
       ├─ Planning → Tool execution / Human confirmation
       └─ Refusal
     → Generation and faithfulness check → Conversation memory → Answer and citations

Intent recognition can use the default DeepSeek or switch to TypeSafe Jev. Note that Jev only replaces the intent classification node; all other LLM nodes, including complexity assessment, query rewriting, task planning, answer generation, faithfulness checking, and memory summarization, are still handled by DeepSeek.

Core Capabilities

• Adaptive routing: Combines business intent and question complexity to select direct answers, single-round retrieval, multi-round retrieval, tool execution, or refusal.
• Hybrid retrieval: Combines BM25 and dense vector retrieval, fuses results with RRF, and can enable Cross-Encoder reranking.
• Evidence enhancement: Supports query rewriting, supplementary retrieval when evidence is insufficient, answer faithfulness checks, and self-correction.
• Dual intent backends: Uses DeepSeek by default and can also use Jev's structured choice interface to identify 14 predefined business intent categories.
• Document processing: Supports Markdown directly. After optional dependencies and system tools are installed, it can parse PDF, Office, and OCR documents.
• Structured chunking: Ordinary text uses a 500-character window and 60-character overlap by default. Detected tables are chunked separately while preserving metadata such as titles, sections, and sources.
• Business tools: Provides demo order tools with permission checks, fallback handling, human confirmation, and idempotency mechanisms. MCP tools can also be integrated.
• Engineering capabilities: Includes conversation memory compression, structured logging, Prometheus metrics, health checks, and automated testing.

Prepare the Runtime Environment

Requirements

• Python 3.11 or later.
• For the web frontend, Node.js 20.19+ or 22.12+, plus npm.
• Local mode uses SQLite and in-memory retrieval components by default, so Docker does not need to be started in advance.

Windows PowerShell Installation

After cloning the repository and entering the project root, create a virtual environment, install the development dependencies, copy the configuration file, and generate demo data:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
Copy-Item .env.example .env
.\.venv\Scripts\python.exe -m scripts.seed_demo

If .env already exists in the project root, keep the existing file and skip the copy command. Then start FastAPI:

.\.venv\Scripts\python.exe -m uvicorn app.asgi:app --reload --host 127.0.0.1 --port 8000

macOS and Linux

On macOS or Linux, create and activate a virtual environment, then run the corresponding installation commands:

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
python -m scripts.seed_demo
python -m uvicorn app.asgi:app --reload --host 127.0.0.1 --port 8000

Configure Models and Local Services

Open .env in the project root. The following settings are the most important to check first:

• DEEPSEEK_API_KEY: Enables the DeepSeek workflow and default intent classification. Real API calls may incur charges.
• INTENT_BACKEND: Can be set to the default deepseek or the optional jev.
• JEV_API_KEY: Required when enabling Jev intent classification.
• JEV_MODEL: The current project default is jev-1.13.0.
• DATABASE_URL: Uses sqlite+aiosqlite:///./data/local/app.db by default.
• KNOWLEDGE_DIR: Defaults to knowledge. Knowledge documents in this directory are loaded at startup.
• LOCAL_EMBEDDING_ENABLED: Controls local semantic vector functionality.
• CROSS_ENCODER_ENABLED: Controls local reranking.
• REDIS_URL and QDRANT_URL: Configure optional external cache and vector services.

Without a DeepSeek key, the system can still use offline demo logic, but its answer quality will differ from real model mode. See the configuration reference and example environment file for the complete list of variables.

Start the React Chat Interface

Keep the backend process running and enter the frontend directory in another terminal:

cd frontend
npm ci
npm run dev

Visit http://127.0.0.1:5173 to open the chat page. The development server proxies /api requests to port 8000 on the local machine.

The frontend supports source citations, a local conversation list, and operation confirmation cards. After validating the answer, the backend sends the content in segments through SSE. If you run npm run build to generate frontend/dist, FastAPI will serve the frontend page from the root path when it detects that directory.

Basic Usage: Ask About Return and Exchange Policies

First, check the service status:

• Interactive API documentation
• Process health check
• Dependency readiness check

Use PowerShell below to submit a question containing multiple policy conditions to the chat endpoint:

$payload = @{
    message = "It has been more than seven days since I received the custom mug, but it has a quality issue. Can I return it?"
    user_id = "u_demo"
} | ConvertTo-Json

Invoke-RestMethod `
    -Uri "http://127.0.0.1:8000/api/v1/chat" `
    -Method Post `
    -ContentType "application/json; charset=utf-8" `
    -Body ([System.Text.Encoding]::UTF8.GetBytes($payload))

The system first identifies the return and exchange intent, then decides whether to retrieve policy documents based on question complexity. If the initial evidence is insufficient, the workflow can rewrite the query and perform supplementary retrieval. After generating the answer, it also checks whether the answer is faithful to the retrieved evidence and returns available source citations.

In addition to the HTTP API, you can run the following command during backend operation to use the terminal client:

python -m app.cli

Basic Usage: Query and Operate on Demo Orders

scripts.seed_demo explicitly creates the demo orders. Starting the API does not automatically write this data, so do not skip data initialization on the first run. The demo user is u_demo, with the following available orders:

• ORD10001: Shipped; product: noise-canceling headphones.
• ORD10002: Delivered; product: custom mug.
• ORD10003: Paid but not shipped; product: T-shirt.

For example, enter Cancel order ORD10003 on the chat page. When executing an operation that requires confirmation, the system may return pending_action. The confirmation request must include the session_id from the response and put pending_action.action_id in confirm_action_id. The web page uses a confirmation card to help complete this process.

Pending operations awaiting confirmation are stored in the server process for 15 minutes by default. After a service restart or when a request is routed to another process, the operation may need to be initiated again. See the API reference for the specific fields and interface format.

Advanced Configuration: Enable Jev Intent Recognition

To switch the intent classification node to TypeSafe Jev, add or update the following settings in the local .env file:

INTENT_BACKEND=jev
JEV_API_KEY=your_jev_api_key
JEV_ENDPOINT=https://api.typesafe.ai/v1/systemone
JEV_MODEL=jev-1.13.0
JEV_TIMEOUT_SECONDS=10
JEV_MAX_RETRIES=2
JEV_INTENT_APPLY_OVERLAY=true

DEEPSEEK_API_KEY=your_deepseek_api_key

Restart the backend after saving. Jev is integrated through an HTTP interface and does not require a dedicated SDK. The returned result is validated with Pydantic and then converted into a unified classification result.

When the Jev key is missing, the request fails, or the response is invalid, the system falls back to the existing IntentClassifier. The fallback chain uses the configured DeepSeek first; when offline or when model invocation fails, it continues with rule-based classification. Retryable errors use exponential backoff, and JEV_MAX_RETRIES represents the maximum number of attempts in the current implementation.

JEV_INTENT_APPLY_OVERLAY controls rule-based correction after successful Jev classification and is enabled by default. This option does not control the overlay of the fallback classifier itself. To restore the default intent classification, simply change INTENT_BACKEND back to deepseek.

Advanced Configuration: Enhanced Retrieval and Document Parsing

Install Local Vector and Reranking Dependencies

.\.venv\Scripts\python.exe -m pip install -e ".[rerank]"

The rerank dependencies are used for local dense vector models and the Cross-Encoder. The default vector model is BAAI/bge-small-zh-v1.5, and the default reranking model is BAAI/bge-reranker-base. Model weights may be downloaded on first load. When a model is unavailable, the system falls back, so results may not match a complete model configuration.

Install Extended Document Parsing Dependencies

.\.venv\Scripts\python.exe -m pip install -e ".[docs]"

The docs dependencies are used for Unstructured document parsing. Processing PDF, OCR, and Office files may also require Poppler, Tesseract with Chinese language packs, and LibreOffice. See Parsing and Retrieval Guide for detailed requirements.

Knowledge chunk IDs are generated from the document path and chunk sequence number. When the path and chunking results remain unchanged, repeated ingestion can preserve the same IDs. After files are moved, content is edited, or chunking strategies change, historical references are not guaranteed to point to the same content.

Start the Full Service with Docker

To run the API, PostgreSQL, Redis, Qdrant, and the built Web frontend together, first prepare a local .env, then run:

docker compose up --build

After startup, visit http://127.0.0.1:8000. The database password and port mappings in Compose are intended only for local demonstrations. Before public deployment, you must replace the demo password, restrict database and cache ports, enable trusted authentication and TLS, and design a reliable persistence and operations solution.

Testing, Static Checks, and Evaluation

Run backend tests and quality checks from the project root:

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check app eval tests
.\.venv\Scripts\python.exe -m mypy
.\.venv\Scripts\python.exe -m eval.runner --task retrieval

Frontend tests and build commands must be run from the frontend directory:

npm test
npm run build

The test configuration isolates local model keys and uses a test database. Before running real-model evaluations separately, check the model and network configuration, because calls to external models may incur charges.

Compare Jev and DeepSeek Intent Classification

After configuring local keys for both models, you can run a comparison with the same samples and overlay conditions:

.\.venv\Scripts\python.exe -m eval.compare_intent --backend both --limit 10 --no-overlay --output data/local/intent-comparison.json

The report includes accuracy, P50 and P95 latency, fallback counts, and rule-coverage counts. --no-overlay disables rule-based correction for both classifiers, making it easier to observe the models' own classification results. Removing this parameter compares performance with the overlay enabled.

The current intent dataset is a development set. Its accuracy includes fallback samples and cannot be treated directly as the generalization ability of the standalone Jev model. Historical evaluations also do not indicate that the current version has been revalidated, nor do they guarantee real-world business performance.

Practical Engineering Recommendations

1. Validate the workflow in the default local mode first: SQLite and in-memory retrieval components are sufficient for a basic demonstration, so there is no need to deploy external databases and vector services from the beginning.
2. Distinguish the intent model from workflow models: Switching to Jev does not replace other DeepSeek nodes. DeepSeek must still be configured to run the complete online workflow.
3. Use health endpoints for troubleshooting: /api/v1/health checks the process, while /api/v1/ready is better for confirming that dependencies are ready.
4. Change chunking strategies carefully: Changes to the path, text content, or chunking parameters may affect chunk IDs and historical references.
5. Do not rely on in-process confirmation state: Pending confirmation operations are valid for only 15 minutes by default and may be lost after a restart or when switching between processes.
6. Protect sensitive data: Do not commit .env, real keys, local databases, logs, user-uploaded documents, or private materials to GitHub.
7. Review external data transfers: Before using external models or remote MCP, confirm that requests do not contain user information that should not be transmitted externally.
8. Plan knowledge-base updates: The current system ingests all data at startup and does not yet provide a complete incremental deletion workflow.

Project Directory at a Glance

• app/api: HTTP API and SSE.
• app/agents: LangGraph execution graphs and workflow nodes.
• app/retrieval: Parsing, chunking, retrieval, fusion, and reranking.
• app/providers: Model and vector service adapters.
• app/tools: Business tools, tool registration, and permission controls.
• app/mcp: MCP tool integration.
• app/memory: Conversation memory and compression.
• app/guardrails: Input and response checks.
• app/observability: Logs and metrics.
• frontend: React and TypeScript chat interface.
• knowledge: Policy knowledge documents.
• tests and eval: Automated tests, evaluation data, and runners.

Summary

Adaptive-RAG e-commerce customer service demonstrates a relatively complete intelligent customer service engineering workflow: it first identifies intent and assesses complexity, then combines hybrid retrieval, multi-turn evidence supplementation, tool calls, human confirmation, and faithfulness checks as needed. You can start with SQLite, demo orders, and offline logic for a quick experience, then gradually enable DeepSeek, Jev, local vector models, the Cross-Encoder, extended document parsing, and Docker services.

Before entering real-world business use, identity authentication, integration with a real order system, persistent confirmation state, incremental knowledge-base maintenance, key management, and production-grade network security still need to be completed. The project is licensed under the MIT License. For further architecture and limitation details, see Architecture and Runtime Flow, Retrieval Design, and Limitations and Roadmap.