feat: LangGraph integration with observability and startup scripts

.gitignore

@@ -39,3 +39,8 @@ yarn-error.log*
 # typescript
 *.tsbuildinfo
 next-env.d.ts
+
+# test results
+/test-results
+*.test-results.xml
+*.lcov

Makefile

@@ -0,0 +1,141 @@
+# Smart Commerce Agent - Makefile
+#
+# One-command operations for development workflow
+#
+# Prerequisites:
+# - Docker installed and running
+# - pnpm (or npm/pip) for package management
+
+# Colors for output
+GREEN=\033[0;32m
+BLUE=\033[0;34m
+YELLOW=\033[1;33m
+NC=\033[0m
+
+.PHONY: help
+help:
+	@echo ""
+	@echo -e "$(BLUE)Smart Commerce Agent - Available Commands$(NC)"
+	@echo ""
+	@echo "Infrastructure:"
+	@echo "  make infra-up       Start all Docker infrastructure"
+	@echo "  make infra-down     Stop all infrastructure"
+	@echo "  make infra-status   Show status of all services"
+	@echo "  make infra-restart  Restart all infrastructure"
+	@echo ""
+	@echo "Development:"
+	@echo "  make install        Install dependencies (pnpm install)"
+	@echo "  make dev            Start development server"
+	@echo "  make build          Build for production"
+	@echo "  make lint           Run ESLint"
+	@echo "  make typecheck      Run TypeScript type checking"
+	@echo "  make test           Run test suite"
+	@echo "  make test-watch     Run tests in watch mode"
+	@echo ""
+	@echo "Database:"
+	@echo "  make db-migrate     Run database migrations"
+	@echo "  make db-seed        Seed database with sample data"
+	@echo "  make db-reset       Reset database (WARNING: deletes data)"
+	@echo ""
+	@echo "AI Services:"
+	@echo "  make ollama-pull    Pull required Ollama models"
+	@echo "  make qdrant-init    Initialize Qdrant with sample products"
+	@echo ""
+	@echo "Utilities:"
+	@echo "  make clean          Clean build artifacts and caches"
+	@echo "  make docker-prune   Remove unused Docker resources"
+	@echo ""
+
+# Infrastructure targets
+.PHONY: infra-up infra-down infra-status infra-restart
+infra-up:
+	@echo -e "$(YELLOW)Starting infrastructure...$(NC)"
+	@./scripts/start-infrastructure.sh start
+
+infra-down:
+	@echo -e "$(YELLOW)Stopping infrastructure...$(NC)"
+	@./scripts/start-infrastructure.sh stop
+
+infra-status:
+	@./scripts/start-infrastructure.sh status
+
+infra-restart:
+	@echo -e "$(YELLOW)Restarting infrastructure...$(NC)"
+	@./scripts/start-infrastructure.sh restart
+
+# Development targets
+.PHONY: install dev build lint typecheck test test-watch
+install:
+	@echo -e "$(BLUE)Installing dependencies...$(NC)"
+	@pnpm install
+
+dev:
+	@echo -e "$(BLUE)Starting development server...$(NC)"
+	@pnpm dev
+
+build:
+	@echo -e "$(BLUE)Building for production...$(NC)"
+	@pnpm build
+
+lint:
+	@echo -e "$(BLUE)Running ESLint...$(NC)"
+	@pnpm lint
+
+typecheck:
+	@echo -e "$(BLUE)Running TypeScript type check...$(NC)"
+	@pnpm typecheck
+
+test:
+	@echo -e "$(BLUE)Running tests...$(NC)"
+	@pnpm test
+
+test-watch:
+	@echo -e "$(BLUE)Running tests in watch mode...$(NC)"
+	@pnpm test:watch
+
+# Database targets
+.PHONY: db-migrate db-seed db-reset
+db-migrate:
+	@echo -e "$(BLUE)Running database migrations...$(NC)"
+	@npx prisma migrate deploy
+
+db-seed:
+	@echo -e "$(BLUE)Seeding database...$(NC)"
+	@npx tsx prisma/seed.ts
+
+db-reset:
+	@echo -e "$(YELLOW)WARNING: This will delete all data in the database!$(NC)"
+	@read -p "Are you sure? (y/N) " -n 1 -r; echo; if [[ $$REPLY =~ ^[Yy]$$ ]]; then npx prisma migrate reset --force; fi
+
+# AI Services targets
+.PHONY: ollama-pull qdrant-init
+ollama-pull:
+	@echo -e "$(BLUE)Pulling Ollama models...$(NC)"
+	@docker exec sca-ollama ollama pull qwen2.5-coder:3b
+	@docker exec sca-ollama ollama pull nomic-embed-text
+	@echo -e "$(GREEN)Ollama models pulled successfully$(NC)"
+
+qdrant-init:
+	@echo -e "$(BLUE)Initializing Qdrant with sample products...$(NC)"
+	@pnpm tsx scripts/qdrant-seed.ts
+
+# Utility targets
+.PHONY: clean docker-prune quick-start
+clean:
+	@echo -e "$(BLUE)Cleaning build artifacts...$(NC)"
+	@rm -rf .next node_modules/.cache .turbo
+	@echo -e "$(GREEN)Cleaned successfully$(NC)"
+
+docker-prune:
+	@echo -e "$(YELLOW)Pruning unused Docker resources...$(NC)"
+	@docker system prune -f
+	@docker volume prune -f
+	@echo -e "$(GREEN)Docker pruned successfully$(NC)"
+
+# Composite target for quick start
+quick-start: infra-up install db-migrate db-seed
+	@echo ""
+	@echo -e "$(GREEN)========================================$(NC)"
+	@echo -e "$(GREEN)  Quick start complete!$(NC)"
+	@echo -e "$(GREEN)  Run 'make dev' to start the app$(NC)"
+	@echo -e "$(GREEN)========================================$(NC)"

README.md

@@ -79,69 +79,150 @@ This project uses **OpenAI SDK** directly with **Ollama's OpenAI-compatible API*
 
 ## 🚀 Quick Start
 
-### 1. **Clone and install**
+### One-Command Setup
+
+```bash
+# Start all infrastructure + install deps + seed database
+make quick-start
+```
+
+### Manual Setup
+
+#### 1. **Clone and install**
 
 ```bash
 git clone https://github.com/Aparnap2/smart_commerce_agent.git
 cd vercel-ai-sdk
 pnpm install
 ```
 
-### 2. **Start PostgreSQL with pgvector**
+#### 2. **Start Infrastructure**
 
 ```bash
-docker run -d --name postgres \
-  -e POSTGRES_PASSWORD=postgres \
-  -e POSTGRES_DB=smart_commerce \
-  -p 5432:5432 \
-  pgvector/pgvector:pg17
-
-# Initialize Prisma
-npx prisma db push
-npx prisma generate
+# Start all Docker services (PostgreSQL, Redis, Qdrant, Ollama, Netdata, Langfuse)
+make infra-up
+
+# Or manually with the startup script
+./scripts/start-infrastructure.sh start
 ```
 
-### 3. **Start Redis (optional, for LangGraph)**
+#### 3. **Initialize Database**
 
 ```bash
-docker run -d --name redis \
-  -p 6379:6379 \
-  redis:alpine
+make db-migrate
+make db-seed
 ```
 
-### 4. **Configure environment**
+#### 4. **Run the App**
 
 ```bash
-# .env.local
-DATABASE_URL="postgresql://postgres:postgres@localhost:5432/smart_commerce"
-REDIS_URL="redis://localhost:6379"
-OLLAMA_BASE_URL="http://localhost:11434"
-OLLAMA_MODEL="qwen2.5-coder:3b"
+pnpm dev
+```
+
+---
+
+## 🛠️ Infrastructure Management
+
+### Available Make Commands
+
+| Command | Description |
+|---------|-------------|
+| `make infra-up` | Start all Docker containers |
+| `make infra-down` | Stop all containers |
+| `make infra-status` | Show running services |
+| `make infra-restart` | Restart all services |
+| `make quick-start` | Full setup: infra + install + migrate + seed |
+| `make dev` | Start development server |
+| `make build` | Build for production |
+| `make test` | Run test suite |
+
+### Docker Services
+
+| Service | Port | Description |
+|---------|------|-------------|
+| PostgreSQL | 5432 | Primary database with pgvector |
+| Redis | 6379 | State caching & LangGraph checkpoints |
+| Qdrant | 6333 | Vector database for semantic search |
+| Ollama | 11434 | Local LLM inference |
+| Netdata | 19999 | Monitoring dashboard |
+| Langfuse | 3000 | Observability & tracing |
+
+### Startup Script Options
+
+```bash
+./scripts/start-infrastructure.sh start    # Start all services
+./scripts/start-infrastructure.sh stop     # Stop all services
+./scripts/start-infrastructure.sh status   # Show service status
+./scripts/start-infrastructure.sh restart  # Restart services
+./scripts/start-infrastructure.sh logs     # Show logs
+```
+
+---
+
+## 🧠 LangGraph Agent Architecture
+
+The supervisor agent uses LangGraph for workflow orchestration:
+
 ```
+User Message
+    ↓
+Intent Classification (LLM)
+    ↓
+┌─────────────────────────────────────┐
+│  Product Search → Qdrant Vector DB  │
+│  Inventory Check → PostgreSQL       │
+│  Order Lookup → PostgreSQL          │
+│  Refund Request → Human Approval    │
+└─────────────────────────────────────┘
+    ↓
+Response Generation (LLM)
+    ↓
+Langfuse Tracing & Scoring
+```
+
+### Checkpointer Configuration
 
-### 5. **Start Ollama**
+State persistence via configurable checkpointers:
 
 ```bash
-ollama pull qwen2.5-coder:3b
-ollama serve
+# Use Redis (default for production)
+CHECKPOINT_TYPE=redis
+REDIS_URL=redis://localhost:6379
+
+# Use PostgreSQL
+CHECKPOINT_TYPE=postgres
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/smart_commerce
+
+# Use Memory (development only)
+CHECKPOINT_TYPE=memory
 ```
 
-### 6. **Run the app**
+---
+
+## 📊 Observability (Langfuse)
+
+Comprehensive tracing and scoring:
 
 ```bash
-pnpm dev
+# Configure Langfuse
+LANGFUSE_PUBLIC_KEY=your-key
+LANGFUSE_SECRET_KEY=your-secret
+LANGFUSE_BASE_URL=http://localhost:3000
 ```
 
-Open [http://localhost:3000](http://localhost:3000) and try:
+### Scoring Metrics
 
-- "Show me my orders for john@example.com"
-- "What laptops do you have?"
-- "Recommend a laptop for programming"
-- "What's your return policy?"
+| Metric | Description |
+|--------|-------------|
+| Relevance | Does response address the query? |
+| Accuracy | Is information factually correct? |
+| Completeness | Are all necessary details provided? |
+| Coherence | Is the response logically organized? |
+| Helpfulness | Would this satisfy the customer? |
 
 ---
 
-## 🧠 Architecture
+## 📁 Project Structure
 
 ### Chat Flow (MCP-Style Tools)
 

app/api/chat/route.ts

@@ -193,7 +193,7 @@ async function executeWebSearchTool(query: string): Promise<ToolResult> {
 
   try {
     // Use RAG document search instead of simulated web search
-    const { documentSearch } = await import('../../../lib/rag/service.ts');
+    const { documentSearch } = await import('../../../lib/rag/service');
 
     const result = await documentSearch(query, {
       limit: 5,
@@ -245,7 +245,7 @@ async function executeSemanticSearchTool(query: string, userId: string): Promise
 
   try {
     // Use RAG vector search instead of simulated results
-    const { vectorSearch } = await import('../../../lib/rag/service.ts');
+    const { vectorSearch } = await import('../../../lib/rag/service');
 
     const result = await vectorSearch(query, {
       limit: 10,