<img width="2559" height="1552" alt="image" src="https://github.com/user-attachments/assets/f0068e7f-0b49-4545-9e8f-704f2e69f0d5" /> <img width="2546" height="1489" alt="image" src="https://github.com/user-attachments/assets/8cd57f84-36e4-4bf2-94e6-1210fa54ad70" /> <img width="2535" height="1380" alt="image" src="https://github.com/user-attachments/assets/6e2cb138-213b-448a-9613-bd04770906d9" /> <img width="2559" height="1464" alt="image" src="https://github.com/user-attachments/assets/258aeb40-3bf5-41c0-8533-e9bd3930fd0b" />

AI Demand Intelligence Platform

A production-grade, multi-agent demand forecasting and supply chain intelligence platform built on a modern AI stack. All components run locally via Docker Compose — no cloud account required to start.

---

What It Does

Supply chain planners ask questions in plain English — "Why is P001 increasing next month?", "What is the current reorder situation for P003?" — and the platform returns a structured, evidence-grounded answer in seconds. Every number is verified against real ML forecasts, live inventory data, graph relationships and policy documents before the LLM explains it.

---

Architecture at a Glance

User → React UI → .NET Middleware (JWT · audit · rate limit)
                       → Python FastAPI → SupervisorAgent
                                               → ForecastAgent      (PostgreSQL + ML models)
                                               → SeasonalityAgent   (60-month sales history)
                                               → GraphRAGAgent      (Neo4j knowledge graph)
                                               → InventoryAgent     (safety-stock calculator)
                                               → VectorRAGAgent     (Qdrant policy search)
                                               → RecommendationAgent
                                               → LLM Explanation    (Groq llama-3.3-70b)

Full architecture diagrams are in architecture.md.

---

Technology Stack

| Layer | Technology | Why | |---|---|---| | Frontend | React 18 + TypeScript + Tailwind CSS | Type-safe, fast UI with real-time agent trace | | API Gateway | ASP.NET Core 8 | JWT auth, RBAC, rate limiting, audit logging, correlation IDs | | Agent Service | Python 3.11 + FastAPI | Async agents, typed tool calls, structured outputs | | ML Forecasting | scikit-learn + XGBoost | LinearRegression and XGBoost ensemble, per-product models | | Graph Intelligence | Neo4j | Knowledge graph of products, customers, contracts, suppliers, events | | Vector Search | Qdrant + sentence-transformers | Policy document retrieval, semantic search | | LLM Reasoning | Groq (llama-3.3-70b-versatile) | Fast inference, question-aware explanations | | Cache | Redis | Forecast TTL cache, session state | | Database | PostgreSQL | Sales history, inventory, recommendations, audit logs | | Container | Docker Compose | One-command local deployment |

Why Groq instead of Azure OpenAI?

Groq runs llama-3.3-70b on dedicated LPU hardware. For this workload it delivers:

• Sub-2-second inference on standard prompts (vs 4–8 s on Azure GPT-4o)
• Free tier with generous limits — zero cost to run the full platform locally
• OpenAI-compatible API — drop-in replacement, no SDK changes required
• Same answer quality for structured data explanation tasks at 4× lower latency

Azure OpenAI is the right choice when your org already has an Azure tenant, needs SOC-2/HIPAA compliance, or requires GPT-4-class reasoning on unstructured free text. For a supply chain explanation service where numbers come from code and the LLM only explains them, Groq's speed and cost profile win clearly.

Why Neo4j for demand intelligence?

Relational databases answer "what" questions well. Graph databases answer "why" questions naturally. In demand forecasting:

• A PRODUCT → ORDERED_BY → CUSTOMER → HAS_CONTRACT → CONTRACT path reveals demand multipliers in one traversal that would need 3 JOINs in SQL
• Supplier risk chains (PRODUCT → USES → MATERIAL → SUPPLIED_BY → SUPPLIER) surface multi-tier disruption risk
• Demand events, promotions, and seasonal patterns attach as relationships, not denormalised columns
• Graph queries return insights[] — human-readable driver strings — that go directly into the LLM prompt

The result: the GraphRAGAgent answers "why is this product's demand increasing?" with factual, cited evidence from real relationships rather than LLM hallucination.

---

Quick Start

Prerequisites

• Docker Desktop (Windows/Mac/Linux)
• Git

1. Clone and configure

git clone <repo-url>
cd buckman-demand-platform
copy .env.example .env

Edit .env and fill in:

GROQ_API_KEY=gsk_...    # Free at https://console.groq.com
JWT_SECRET=<any 64-char random string>

Everything else works with the defaults.

2. Start all services

docker compose up -d

First start takes 3–5 minutes (downloads images, seeds the database, loads ML models).

3. Open the app

| Service | URL | |---|---| | Frontend | http://localhost:5173 | | .NET API | http://localhost:5000 | | Python Agent | http://localhost:8000 | | Neo4j Browser | http://localhost:7474 | | Qdrant Dashboard | http://localhost:6333/dashboard |

4. Login

Default credentials: admin / Admin123!

---

Updating and Redeploying

Python agent changes (fastest — no rebuild)

# From project root
docker cp python-agent/agents/supervisor.py buckman-python-agent:/app/agents/supervisor.py
docker cp python-agent/services/llm_service.py buckman-python-agent:/app/services/llm_service.py
docker restart buckman-python-agent

Frontend changes

cd frontend
npm run build
cd ..
docker cp frontend/dist/index.html buckman-frontend:/usr/share/nginx/html/index.html
docker cp frontend/dist/assets buckman-frontend:/usr/share/nginx/html/assets

.NET middleware changes

docker compose up -d --build dotnet-middleware
docker start buckman-dotnet    # if it stops after build

Full rebuild

docker compose down
docker compose up -d --build

---

Service Names Reference

| Container | Compose service name | Port | |---|---|---| | buckman-dotnet | dotnet-middleware | 5000 | | buckman-python-agent | python-agent | 8000 | | buckman-frontend | frontend | 5173 | | buckman-postgres | postgres | 5432 | | buckman-neo4j | neo4j | 7474/7687 | | buckman-qdrant | qdrant | 6333 | | buckman-redis | redis | 6379 |

---

Using the AI Assistant

1. Open http://localhost:5173 and log in
2. Go to AI Demand Assistant
3. Select a product from the dropdown or type P002 anywhere in your question
4. Ask any supply chain question:
   • "What is the current inventory situation?"
   • "What is the peak sales season for P002?"
   • "Why is demand expected to increase next month?"
   • "Which suppliers pose the highest risk?"

The response includes:

• A natural-language answer shaped to your actual question (not a fixed template)
• Metric cards with exact verified numbers per product
• Expandable Neo4j graph evidence (customers, contracts, suppliers, events)
• Expandable Qdrant policy evidence (top-5 policy chunks with match scores)
• Agent execution trace with per-agent latency

---

Agent Pipeline

| Agent | Data source | Role | |---|---|---| | DataQualityAgent | PostgreSQL | Validates completeness before forecasting | | ForecastAgent | Pre-trained ML models + Redis | Next-month demand forecast with confidence | | SeasonalityAgent | 60 months of sales history | Computes seasonal indices from real data (not hardcoded) | | GraphRAGAgent | Neo4j | Demand drivers: customers, contracts, events, supplier risk | | InventoryAgent | PostgreSQL | Safety stock, reorder point, open POs | | VectorRAGAgent | Qdrant | Policy search — inventory, procurement, supplier, demand planning | | RecommendationAgent | All above | Assembles structured recommendation with evidence | | LLM (Groq) | All above | Question-aware explanation — answers the question asked, not a template |

---

Environment Variables

| Variable | Required | Description | |---|---|---| | GROQ_API_KEY | Yes | Groq API key (free at console.groq.com) | | GROQ_MODEL | No | Default: llama-3.3-70b-versatile | | JWT_SECRET | Yes | 64-char secret for JWT signing | | POSTGRES_PASSWORD | No | Default: buckman_secret | | NEO4J_PASSWORD | No | Default: buckman_neo4j | | REDIS_PASSWORD | No | Default: redis_secret | | ENVIRONMENT | No | development or production |

---

Logs

docker logs buckman-python-agent --tail 50 -f
docker logs buckman-dotnet --tail 50 -f
docker logs buckman-frontend --tail 20

---

Project Structure

buckman-demand-platform/
├── frontend/                  # React + TypeScript + Tailwind
│   └── src/
│       ├── pages/             # AssistantPage, DashboardPage, ForecastPage…
│       ├── components/        # KpiCard, StatusBadge, Layout…
│       └── services/api.ts    # Typed API client
├── dotnet-middleware/         # ASP.NET Core 8 API gateway
│   ├── Controllers/           # Auth, Chat, Dashboard, Recommendations
│   ├── Services/              # JWT, Audit, UserService, AgentProxy
│   └── Middleware/            # CorrelationId, ErrorHandling, RequestLogging
├── python-agent/              # FastAPI + multi-agent pipeline
│   ├── agents/                # supervisor, forecast, seasonality, graphrag…
│   ├── forecasting/           # ML engine, model loader
│   ├── graph/                 # Neo4j service
│   ├── rag/                   # Qdrant service
│   ├── services/              # LLM (Groq), cache, logging
│   └── tools/                 # data_tools (typed DB accessors)
├── documents/                 # Policy documents indexed into Qdrant
├── data/csv/                  # Seed data
├── docker-compose.yml
├── architecture.md
└── .env.example