Zhengxuan Yuan
Menu
Back to Personal Products

08

AI-BI

Personal / Conversational BI / Agent Systems

A conversational business-intelligence platform built around a stateful LangGraph ReAct assistant and deterministic retail analytics.

Python unit and state-machine tests passing
59 / 59
Node.js artifact and ECharts tests passing
21 / 21

LangGraph control plane

A stateful ReAct loop with bounded analytical tools

AgentStatemessagescontextquestion
ENTRYSTARTquestion + dashboard context
LLM NODEanswerreason, bind tools, emit calls
ROUTERtools_conditiontool call present?
NO TOOL CALLENDSSE answer + rich artifacts
CHECKPOINTERMemorySaverthread-isolated history and state recovery
TOOL CALL DETECTEDToolNode
structured result or exception fallback
fetch_pospal_datacross-period data retrieval
  • forecastweighted trend
  • weathersales elasticity
  • basketattachment and lift
  • hourlytraffic tides
  • abcproduct Pareto
  • rechargecashflow health

ToolMessage returns to answer for the next reasoning pass

RESILIENT DATA PATHFour-tier fallback
  1. L1Memory
  2. L2Parquet
  3. L3Prewarmed
  4. L4SQLite
BROWSER OUTPUTECharts / metrics / compare / checklist / callout
The model decides when to call deterministic domain tools. State persists by thread, while observations cycle back into the answer node before token streaming begins.

In brief

A full-stack retail BI system that combines a live dashboard, LangGraph tool orchestration, structured analytical artifacts, and a four-tier offline-capable data layer.

A sanitized public reconstruction with offline-ready data and no production credentials.

AI-BI turns operational retail data into an interactive decision workspace. The dashboard exposes more than 20 business dimensions, while the assistant can move from a natural-language question to a validated domain analysis without generating arbitrary runtime code.

The public repository is a sanitized, architecturally refactored version of a production system. Prewarmed datasets and synthetic SQLite databases make the dashboard runnable without a live POS account or customer credentials.

Retail operators need conversational analysis that preserves context, selects reliable statistical tools, survives upstream API limits, and returns decisions as usable visual artifacts rather than prose alone.

What it includes

  1. 01LangGraph StateGraph ReAct loop with thread-isolated MemorySaver checkpoints
  2. 02Six deterministic retail analysis skills for forecasting, weather, basket, hourly, ABC, and recharge analysis
  3. 03Native ECharts, metric, comparison, checklist, and callout artifacts streamed into the conversation
  4. 04Four-tier cache path from in-memory and Parquet data to prewarmed and synthetic fallbacks

How it works

  1. 01Assemble state

    Combine the user question, message history, and compressed dashboard context in AgentState.

  2. 02Reason and route

    The answer node decides whether the available context is enough or a domain tool is needed.

  3. 03Run bounded tools

    ToolNode dispatches cross-period data retrieval or one of six parameterized analyses.

  4. 04Observe and iterate

    Structured results or exception fallbacks return as ToolMessages for the next reasoning pass.

  5. 05Stream decisions

    The final response streams to the browser with native charts, metrics, comparisons, checklists, and warnings.

Build notes

Note 01

Use an explicit state graph for non-linear analysis

LangGraph ReAct
Context
Business questions often require the assistant to inspect an observation and decide whether more evidence is needed.
Approach
Model the assistant as a cyclic StateGraph with answer, tools_condition, ToolNode, and END transitions, plus thread-scoped checkpoints.
What it enables
The assistant can preserve multi-turn context and make additional bounded tool calls before committing to a final answer.
Note 02

Prefer parameterized domain skills to generated code

bounded tools
Context
Unbounded code generation introduces statistical inconsistency, execution risk, and unpredictable latency.
Approach
Expose six deterministic retail analyses through a compact tool registry with validated arguments and structured outputs.
What it enables
Forecasting, weather, basket, hourly, ABC, and recharge questions use repeatable analytical methods instead of ad hoc code.
Note 03

Treat offline resilience as part of the product

four-tier cache
Context
Live POS APIs have quotas and can be unavailable, while a public demo cannot include customer credentials or PII.
Approach
Cascade reads through memory, Parquet disk cache, sanitized prewarmed packages, and synthetic SQLite data.
What it enables
The dashboard starts with useful data, protects API quota, and remains demonstrable without external account configuration.

At a glance

59 / 59
Python unit and state-machine tests passing

Evaluation basisPublic repository test suite

21 / 21
Node.js artifact and ECharts tests passing

Evaluation basisPublic repository test suite

Compatibility

  • The public data package is sanitized and synthetic; it demonstrates system behavior rather than production business performance.
  • The dashboard runs offline, but live LLM responses require a configured DeepSeek API key.
  • MemorySaver is process-local in the showcase build; a multi-instance production deployment should use a durable external checkpointer.
Next project09ds-monPersonal / macOS Utility

Project image

Interactive demo