HsienW/chat-gun
HsienW/chat-gun has 141 GitHub stars and 22 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-16 18:49 UTC. Last push 2026-11-15.
Measured star growth
- in 24h
- 0
- in 7 days
- Collecting history
- in 15 days
- Collecting history
- in 1 month
- Collecting history
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
🤖 Full-stack AI agent app built with React, TypeScript and LangGraph JS. Streaming, multimodal input, human-in-the-loop, native + MCP tools, Qwen/OpenAI-compatible LLM gateway. Ships an after-sales support agent: cited RAG with abstention, human-approved refunds, idempotent execution. OpenTelemetry + reproducible evals.
AIREADME.en.md
OriginalChat Gun
Feature Demo · Capabilities · Quick Start · Business Scenario · Architecture · Evaluation · Security and Limitations · Documentation Guide
Chat Gun is a full-stack agent application composed of a Frontend, a BFF, and a LangGraph Runtime.
- Agent platform: the underlying capabilities handle unified tool dispatch, make retrieved answers traceable, require human approval before operations that change external state, and use a logical idempotency key to ensure duplicate submissions take effect only once.
- AI business scenarios: the application features built on top of the platform capabilities. There are currently two entry points: Gun Chat handles general conversation and deep research, and Gun Shop is an AI customer service chain that runs from product lookup and policy Q&A to refund approval.
- All model calls, tool executions, and credential resolution happen on the server; the frontend communicates with the Runtime only through the BFF. The corpus and order data used by the business scenarios are synthetic, and the order tools are simulated; the mechanisms are real, while the business context used to demonstrate them is simulated.
Feature Demo
Screens for other operations are in Operation Screens (Traditional Chinese).
Capabilities
Agent Platform: Harness
- Agent-workflows: five Graphs share the same Runtime.
- Deep Researcher performs multi-step research and citation verification.
- Chat Assistant handles general conversation.
- Shopping Assistant routes by intent across product lookup, policy Q&A, and order operations.
- Math Solver evaluates expressions and performs numerical calculations.
- MCP Agent uses native and MCP tools through Tool Calling.
- Streaming: answers and execution activity stream in real time, runs can be cancelled midway, and errors are presented as explicit states.
- HITL: Human-in-the-loop operations require human approval. When a location is ambiguous, the user confirms one of the suggested locations before the conversation resumes.
- Multimodal input: accepts PNG, JPEG, and WebP images, which are analyzed by a vision model and incorporated into the answer or research flow.
- Model providers: supports Qwen, OpenAI-compatible, and CC-compatible endpoints; the LLM Gateway handles model capability checks and calls in one place.
- Native Tools and MCP: built-in calculation, web search (Tavily), web page extraction, weather, knowledge base retrieval, and simulated order operations; Filesystem and Brave Search MCP Servers can optionally be loaded. See Tools and MCP (Traditional Chinese).
- Agent / Tool SDK: a versioned manifest declares inputs and outputs, side-effect class, required permissions, and execution conditions; a tool is granted only to the Agent that declares it. See
@gun-ai/harness-sdk.
Agent Platform: Runtime Governance
- Retrieval and refusal: PostgreSQL + pgvector provides the vector index; citations are bound after
qwen3-rerankand evidence thresholds, with explicit refusal when evidence is insufficient. For Recall@5, MRR, and the false refusal rate, see knowledge base retrieval (Traditional Chinese) and evaluation (Traditional Chinese). - Side effects: external state changes require persistable human approval first; the model can request approval but cannot record it. See the Gun Shop flow walkthrough (Traditional Chinese).
- Idempotency and outcomes: the idempotency key is derived from the business operation, and concurrent duplicate submissions take effect only once. For details, see concurrency and regression verification (Traditional Chinese).
- Trust boundary: the BFF maps API keys to trusted identities, centralizes CORS, rate limiting, timeouts, and cancellation propagation, and rejects direct client writes to conversation state. See BFF (Traditional Chinese).
- Observability and evaluation: provides Metrics, OpenTelemetry, and Opik tracing; evaluation has two layers, deterministic (verifying runtime guarantees) and live (measuring model quality), each recording its dataset, model, and prompt versions. Human reviewers checked the model's scores on 10 questions. For details on the review, see Evaluation (Traditional Chinese).
Business Scenario: Gun Shop AI Customer Service
A business scenario built with the Agent platform's capabilities, adding no new Runtime mechanisms. Its numbers also serve as end-to-end verification of the platform guarantees.
- After-sales customer service chain: intent routing → product cards → policy Q&A (with citations) → refund request → human approval → idempotent execution → status card. For intent routing accuracy and prohibited outcomes, see the flow walkthrough (Traditional Chinese) and flow evaluation (Traditional Chinese).
- Order operation states: awaiting approval, executing, confirmed, deduplicated, failed, cancelled before taking effect, outcome unknown, approval rejected, and approval expired — nine states that are mutually distinguishable in the interface; undo is not provided. Deterministic test 10 / 10 (including approval rejected, expired, and cancelled before taking effect). See operation states (Traditional Chinese) and the order idempotency integration test.
- Simulation boundary: product and policy answers come only from the synthetic corpus and carry citations; refunds and cancellations act on a simulated order system and never touch real transactions. See Scope and Limitations (Traditional Chinese).
Quick Start
📌 The current defaults are for local development only. Before any public deployment, enable Authentication, configure an explicit CORS allowlist, manage Secrets and database credentials properly, and configure shared Rate limiting, TLS, and a Reverse Proxy according to your deployment architecture. If Agent runs need to resume across restarts or multiple instances, switch to a durable checkpointer.
- Node >= 22
- npm >= 10.8.x
- Docker and Docker Compose
- Fill in
QWEN_API_KEY,TAVILY_API_KEY, and aLANGSMITH_API_KEYwith LangGraph Cloud access in the root.env - For alternative authorization methods, see the full installation guide (Traditional Chinese).
git clone https://github.com/HsienW/chat-gun.git
cd chat-gun
npm --prefix backend ci
cp backend/.env.example backend/.env
# Fill in QWEN_API_KEY in backend/.env and set the following host connections:
# DATABASE_URL=postgresql://postgres:postgres@localhost:5433/postgres
# KNOWLEDGE_DATABASE_URL=postgresql://postgres:postgres@localhost:5434/knowledge
docker compose up -d langgraph-postgres knowledge-postgres
npm --prefix backend run migrations:up
npm --prefix backend run knowledge:corpus
npm --prefix backend run knowledge:ingest
docker compose up --build
Open http://localhost:8123/app/; the home page shows the two entry points, Gun Chat and Gun Shop. Enter a refund request in Gun Shop to see the approval card and the status card that follows.
Local ingestion uses host ports
5433/5434; the knowledge base connection inside containers must useknowledge-postgres:5432, so do not pass the hostKNOWLEDGE_DATABASE_URLinto the container. For the local three-terminal startup, PowerShell commands, and test entry points, see Quick Start (Traditional Chinese).
Business Scenario
When AI enters a business scenario, what matters most is often what happens after a Tool is called.
Taking the Gun Shop AI customer service as an example, the table below compares it with the approach of "executing a tool call as soon as the model outputs it":
| Situation | Execute the tool call directly | Chat Gun |
|---|---|---|
| The model outputs a refund call | Executes immediately | Enters awaiting_approval and submits only after approval |
| The same refund is submitted repeatedly or concurrently | May execute multiple times | Takes effect only once; later submissions return deduplicated and point to the original operation |
| The connection drops after submission | Retries or reports failure | Enters outcome_unknown and creates a reconciliation task; does not retry and does not report success |
| The client rewrites conversation state to fake an approval | Depends on the implementation | The BFF rejects the state write; approval is verified against server-side records |
| The corpus has no answer | May answer from the model's own knowledge instead | Explicitly refuses |
| Source of the answer | A text description | Every citation resolves to a stored chunk and its source version |
1. The model produces a request, not a side effect: Tool calls for refunds and cancellations first stop at approval; the approval record is stored on the server, bound to the conversation, and can be consumed only once. Tool Dispatch performs the submission after approval and writes the result to the side-effect ledger.
2. The idempotency key describes a business operation, not a single call: The key is derived from the operation kind, the order, and the normalized line items, and excludes the retry count and call identifiers, so concurrent or repeated submissions converge into the same operation. When a response is lost after submission, the system admits it "does not know" instead of guessing an outcome.
3. Answers must trace back to the corpus: Candidate chunks must still pass the evidence threshold after rerank, and every citation is bound to a stored chunk and its source version; if no chunk meets the threshold, the system explicitly refuses.
Architecture
- Frontend: handles the entry points, streaming, and card rendering, and holds no model, tool, or database credentials.
- BFF: the only external boundary: verifies identity, rate limits, propagates timeouts and cancellation, and rejects client writes to conversation state.
- LangGraph Runtime: hosts the five Graphs; the entry point decides which Graph is used, so no extra model routing is needed.
- Tool Registry: dispatches all tools through a single path; tools that change external state first go through human approval and write to the ledger after submission.
The diagram below shows which layers a Chat Gun request passes through from the frontend to the model Provider, where tools and side effects converge, and where observability is attached.
flowchart LR
B["Frontend"]
F["Frontend<br/>Vite + React 19"]
G["BFF<br/>Auth · CORS · Rate limiting · Timeouts · State write guard"]
L["LangGraph Agent Server"]
A1["deep_researcher"]
A2["chatbot"]
A3["math_agent"]
A4["mcp_agent"]
A5["shopping_assistant"]
GW["LLM Gateway"]
Q["Qwen"]
O["OpenAI-compatible"]
C["CCR"]
TR["Tool Registry<br/>Unified Tool Dispatch"]
NT["Native tools"]
KB["kb_search"]
OD["Order tools<br/>External state changes"]
MT["MCP servers"]
EM["Embedding · Rerank"]
KS["Knowledge base<br/>PostgreSQL + pgvector"]
HI["Human approval<br/>Persistable"]
LG["Side-effect Ledger"]
OT["OpenTelemetry"]
OP["Opik"]
B --> F
F -->|"/api/langgraph/*"| G
G --> L
L --> A1
L --> A2
L --> A3
L --> A4
L --> A5
A1 --> GW
A2 --> GW
A3 --> GW
A4 --> GW
A5 --> GW
GW --> Q
GW --> O
GW --> C
A1 --> TR
A3 --> TR
A4 --> TR
A5 --> TR
TR --> NT
TR --> KB
TR --> OD
TR --> MT
KB --> EM
KB --> KS
EM --> Q
OD --> HI
OD --> LG
L -.->|"spans"| OT
L -.->|"traces / evals"| OP
| Directory | Purpose | Local default port |
|---|---|---|
frontend/ |
Entry home page, Chat UI, streaming states, tool results, product and approval cards, image input | 5173 |
bff/ |
API gateway, validation, proxying, timeouts, rate limiting, and state write guard | 8787 |
backend/ |
LangGraph agents, model integration, Tools, knowledge base, and MCP | 2024 |
For how entry points map to Graphs, see Entry Points and Agents (Traditional Chinese).
Evaluation
Retrieval quality (platform capability):
- Dataset
kb-eval-v1(40 questions, including refusal questions), corpuskb-v1(synthetic), Embeddingtext-embedding-v4(1024 dimensions), Rerankqwen3-rerank, answer generationqwen-plus.
Only the test split is listed below
| Configuration | Recall@5 | MRR | Citation accuracy | Correct refusal rate | False refusal rate |
|---|---|---|---|---|---|
vector_only |
0.863 | 0.796 | 1.000 | 1.000 | 0.300 |
vector_rerank |
1.000 | 0.917 | 1.000 | 1.000 | 0.100 |
Flow evaluation (business implementation):
- Deterministic test 10 / 10; live test 10 / 10, intent routing accuracy 1.000, prohibited outcomes 0.
Known limitations: the order request Golden largely passes; live citation accuracy is about 0.380.
For full results, run counts, the dev split, latency, metric definitions, why faithfulness is not published, methodology, and how to rerun, see Evaluation (Traditional Chinese).
CI scope: the Backend CI badge covers only backend lint, default tests, and build, including the deterministic Weather Golden Eval, scorer unit tests, and mock integration; it excludes integration tests that need a database or model and live evaluations, does not cover frontend or BFF, and does not represent the evaluation numbers in this section.
Security and Limitations
Tools run in-process: OS-level sandboxing has not shipped yet; tools declared to run in a separate process are explicitly rejected at registration or dispatch time and do not fall back to in-process execution. Read the security settings (Traditional Chinese) before connecting MCP.
Scope:
- The corpus and order data are synthetic and do not represent real products or operating rules.
- The order tools are simulated, with no real transactions, payments, or external vendor integrations.
- Undo is not provided; an operation can only be cancelled before its side effect takes place.
- Evaluation is offline regression; the numbers reflect method effectiveness on controlled synthetic datasets, not production performance.
For the operation history projection, automatic reconciliation, and model selection mechanisms that are not yet implemented, see Scope and Limitations (Traditional Chinese).
Documentation Guide
| I want to… | Start here |
|---|---|
| Run it locally and run the tests | Quick Start (Traditional Chinese) |
| Configure models, the knowledge base, BFF, and Frontend | Configuration (Traditional Chinese) |
| See the Gun Shop flow walkthrough and operation states | Gun Shop (Traditional Chinese) |
| Understand the retrieval pipeline, chunking, thresholds, and resumable ingestion | Knowledge Base Retrieval (Traditional Chinese) |
| See full evaluation data or rerun the evaluation | Evaluation (Traditional Chinese) |
| Understand the request flow, State, and checkpoints | Runtime Architecture (Traditional Chinese) · TypeScript + LangGraph (Traditional Chinese) |
| Check trusted identity, rate limiting, and state protection | BFF (Traditional Chinese) |
| Add a tool or connect MCP | Tools and MCP (Traditional Chinese) · Security Settings (Traditional Chinese) |
| Connect OpenTelemetry or Opik | Observability (Traditional Chinese) |
| Troubleshoot common errors | Troubleshooting (Traditional Chinese) |
| See the full list of limitations | Scope and Limitations (Traditional Chinese) |
License
Apache License 2.0. See LICENSE.