Odin - Thorlabs Support Agent

A Next.js-based conversational AI agent that helps users discover, research, and purchase Thorlabs photonics products. The system uses a filesystem-first retrieval approach with PageIndex Cloud and the Vercel AI SDK to provide accurate product information and enable e-commerce functionality.

🎯 Overview

Odin is an intelligent support agent that combines:

• Documentation Search: Query product manuals and datasheets using structured document trees
• Inventory Management: Real-time stock checking and product availability
• Shopping Cart: Full e-commerce functionality with account-based discounts
• Delivery Visualization: Animated map showing delivery routes from Berlin warehouse to customer

The system demonstrates a retrieval-first approach where the AI agent uses structured document nodes (from PageIndex Cloud) to answer questions, reducing hallucination and improving accuracy compared to traditional RAG systems.

✨ Features

Core Capabilities

• Product Discovery: Search across product documentation using natural language queries
• Technical Specifications: Get detailed specs, parameters, and technical data from product manuals
• Inventory Checking: Real-time stock levels and pricing for all products
• Documentation Navigation: Browse product documentation in a hierarchical sidebar (toggle with Cmd+B / Ctrl+B)
• Source Citations: Clickable links to specific document sections with popup previews

E-Commerce Features

• Shopping Cart: Add products to cart with quantity management
• Account-Based Discounts: Automatic discount calculation (Academic 15%, Government 12%, Commercial 10%)
• Checkout Flow: Order processing with inventory validation
• Delivery Animation: Visual map showing delivery route from Berlin warehouse to destination
• Order History: Track orders in order-sessions.json

Product Management

• PDF Upload: Upload product PDFs via web interface
• Automatic Processing: Python scripts automatically extract document trees and generate summaries
• Tree Structure: Documents stored as hierarchical JSON trees with node IDs, titles, and summaries

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Frontend (Next.js)                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Chat UI    │  │  Cart Sidebar│  │ Docs Sidebar │      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
└─────────┼──────────────────┼──────────────────┼──────────────┘
          │                  │                  │
          ▼                  ▼                  ▼
┌─────────────────────────────────────────────────────────────┐
│              API Gateway (/api/chat)                         │
│  ┌──────────────────────────────────────────────────────┐   │
│  │         Vercel AI SDK Agent (ToolLoopAgent)           │   │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐     │   │
│  │  │ queryDoc   │  │ checkInv   │  │ addToCart   │     │   │
│  │  │ querySum   │  │ purchase   │  │ estimate   │     │   │
│  │  └────────────┘  └────────────┘  └────────────┘     │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
          │                  │                  │
          ▼                  ▼                  ▼
┌─────────────────────────────────────────────────────────────┐
│                    Data Layer                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ Documentation│  │  Inventory    │  │ User Accounts│      │
│  │  (JSON trees)│  │  (JSON)       │  │  (JSON)      │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘

Key Components

• Frontend: Next.js App Router with React components
• Agent Runtime: Vercel AI SDK ToolLoopAgent with OpenAI GPT-4o
• Retrieval: PageIndex Cloud for document processing and tree extraction
• Tools: TypeScript functions for document querying, inventory, cart management
• State Management: Zustand for cart state
• Maps: Mapbox GL for delivery visualization

🚀 Getting Started

Prerequisites

• Node.js 18+ and pnpm (or npm/yarn)
• Python 3.8+ (for document processing scripts)
• OpenAI API key
• PageIndex API key (for PDF processing)
• Mapbox access token (for delivery map - optional)

Installation

1. Clone the repository

   git clone https://github.com/OwnerOfJK/odin.git
   cd odin

2. Install dependencies

   pnpm install

3. Set up Python environment (for document processing)

   cd app/python
   python3 -m venv .venv
   source .venv/bin/activate 
   pip install -r requirements.txt

4. Configure environment variables

   Create a .env.local file in the root directory:

   # Required
   OPENAI_API_KEY=sk-your-openai-key
   PAGEINDEX_API_KEY=your-pageindex-key
   
   # Optional (for delivery map)
   NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN=pk.your-mapbox-token

5. Start the development server

   pnpm dev

6. Open your browser Navigate to http://localhost:3000

📁 Project Structure

odin/
├── app/
│   ├── actions/              # Server actions
│   │   ├── getAllDocuments.ts    # Fetch all documentation files
│   │   └── getNode.ts            # Get specific document node
│   ├── api/                  # API routes
│   │   ├── chat/             # Main chat endpoint
│   │   ├── checkout/         # Order processing
│   │   ├── accounts/         # User account management
│   │   └── upload-product/   # PDF upload & processing
│   ├── components/           # React components
│   │   ├── cart/             # Shopping cart components
│   │   ├── map/              # Map visualization
│   │   ├── modals/           # Modal dialogs
│   │   ├── Message.tsx       # Chat message display
│   │   ├── ChatInput.tsx     # Message input
│   │   ├── NodesSidebar.tsx  # Documentation browser
│   │   └── ShoppingCart.tsx  # Cart container
│   ├── data/                 # Data files
│   │   ├── documentation/    # Product PDFs and JSON trees
│   │   ├── inventory.json    # Product inventory
│   │   ├── user-accounts.json # Customer accounts
│   │   ├── order-sessions.json # Order history
│   │   └── summary.json      # Product summaries
│   ├── hooks/                # React hooks
│   │   ├── useCart.ts        # Cart operations
│   │   ├── useCheckout.ts    # Checkout logic
│   │   └── useMapAnimation.ts # Map animation
│   ├── python/               # Python scripts
│   │   └── scripts/
│   │       ├── build-tree-from-pdf.py  # Extract document tree
│   │       ├── append-summary.py       # Generate summaries
│   │       └── summarize_tree.py      # Summary generation
│   ├── stores/               # State management
│   │   └── cartStore.ts      # Zustand cart store
│   ├── tools/                # AI agent tools
│   │   ├── search-product-documentation.ts      # Product documentation search
│   │   ├── search-product-summary.ts   # Product summary search
│   │   ├── check-inventory.ts # Stock checking
│   │   ├── add-to-cart.ts    # Add items to cart
│   │   ├── purchase-product.ts # Process purchases
│   │   └── estimate-delivery.ts # Delivery estimates
│   └── utils/                # Utility functions
│       ├── cartValidation.ts  # Cart validation
│       ├── discountCalculator.ts # Discount logic
│       └── stateCoordinates.ts # US state coordinates
├── PRODUCT.md                 # Product specification
├── SHOPPING_CART_README.md    # Shopping cart documentation
└── README.md                  # This file

🛠️ Available Tools

The AI agent has access to the following tools:

Tool	Description	Use Case
searchProductDocumentationTool	Search within specific product documentation	"What are the specifications for the DFB15TK laser?"
searchProductSummariesTool	Search product summaries to find relevant products	"What lasers do you have?"
checkInventoryTool	Check stock levels and pricing	"Is APD130A in stock?"
addToCartTool	Add products to shopping cart	"Add 2 APD130A to my cart"
purchaseProductTool	Process a purchase (usually via checkout UI)	Checkout flow
estimateDeliveryTool	Get delivery time estimates	"How long will delivery take?"
manageAccountTool	Manage user account information	Account operations

📊 Data Structure

Documentation Files

Documentation is stored as hierarchical JSON trees in app/data/documentation/:

[
  {
    "title": "Chapter 1: Introduction",
    "node_id": "0001",
    "page_index": 1,
    "summary": "Brief summary of the chapter",
    "text": "Full chapter text...",
    "nodes": [
      {
        "title": "1.1 Overview",
        "node_id": "0002",
        "page_index": 2,
        "summary": "...",
        "text": "..."
      }
    ]
  }
]

Inventory

Products are stored in app/data/inventory.json:

{
  "products": [
    {
      "productCode": "APD130A",
      "name": "Avalanche Photodetector, Si, 400-1000 nm",
      "category": "APD130x-Avalanche-Photodetectors",
      "stock": 45,
      "price": 2499.00,
      "currency": "USD",
      "location": "Berlin Warehouse",
      "restockDate": null
    }
  ]
}

💬 Usage Examples

Product Discovery

User: "What lasers do you have available?"
Agent: [Searches summaries, checks inventory, presents table]

Technical Questions

User: "What is the wavelength range of the DFB15TK laser?"
Agent: [Queries documentation, returns specs with source links]

Shopping

User: "Add 2 APD130A detectors to my cart"
Agent: [Adds to cart, shows confirmation]

Documentation Browsing

• Press Cmd+B (Mac) or Ctrl+B (Windows/Linux) to toggle documentation sidebar
• Click on any node to view its content in a popup
• Navigate hierarchical structure with dropdowns

🔧 Development

Adding a New Tool

1. Create a new tool file in app/tools/:

   import { tool } from 'ai';
   import { z } from 'zod';
   
   export const myTool = tool({
     description: 'Tool description',
     inputSchema: z.object({
       param: z.string(),
     }),
     execute: async ({ param }) => {
       // Tool logic
       return { result: '...' };
     },
   });

2. Export it from app/tools/index.ts

3. Add it to the agent in app/api/chat/route.ts

Adding Product Documentation

1. Upload PDF via the web interface (Admin → Upload Product)
2. Or manually:
   • Place PDF in app/data/documentation/
   • Run: python app/python/scripts/build-tree-from-pdf.py <pdf_path> <product_name> <output_dir>
   • Run: python app/python/scripts/append-summary.py <product_name> <tree_json_path> <summary_json_path>

Adding Products to Inventory

Edit app/data/inventory.json and add product entries following the existing structure.

🚢 Deployment

Vercel (Recommended)

1. Push code to GitHub
2. Import project in Vercel
3. Add environment variables in Vercel dashboard
4. Deploy

Manual Deployment

pnpm build
pnpm start

📝 Environment Variables

Variable	Required	Description
OPENAI_API_KEY	Yes	OpenAI API key for the AI agent
PAGEINDEX_API_KEY	Yes	PageIndex Cloud API key for PDF processing
NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN	No	Mapbox token for delivery map visualization

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is private and proprietary.

🙏 Acknowledgments

• Built with Next.js
• AI powered by Vercel AI SDK
• Document processing by PageIndex Cloud
• Maps by Mapbox

---

For detailed shopping cart documentation, see SHOPPING_CART_README.md

For product specifications, see PRODUCT.md