┌─────────────────────────────────────────────────────────────┐
│                        Web App (Next.js)                     │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │                   AI Chat Widget                         │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │ │
│  │  │ MessageList │  │ InputField  │  │ ToolResultCards │  │ │
│  │  └─────────────┘  └─────────────┘  └─────────────────┘  │ │
│  └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ POST /api/ai/chat
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      NestJS API Gateway                      │
│                 (proxies to AI Service)                      │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ Internal HTTP
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   AI Service (Express:3002)                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐   │
│  │ Chat Handler │  │ Tool Registry│  │ RAG Query Engine │   │
│  └──────────────┘  └──────────────┘  └──────────────────┘   │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐   │
│  │ Chunking Svc │  │ Embedding Svc│  │ Vector Store Svc │   │
│  └──────────────┘  └──────────────┘  └──────────────────┘   │
└─────────────────────────────────────────────────────────────┘
         │                    │
         │                    │ OpenAI API
         ▼                    ▼
┌──────────────┐    ┌──────────────────┐
│   MongoDB    │    │  OpenAI (GPT-4)  │
│  (Embeddings)│    │  (Embeddings +   │
│              │    │   Completions)   │
└──────────────┘    └──────────────────┘

mkdir -p apps/ai/src/{services,routes,tools,types,middleware}
cd apps/ai

{
  "name": "@hrms/ai",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js",
    "lint": "eslint src --ext .ts"
  },
  "dependencies": {
    "express": "^4.18.2",
    "cors": "^2.8.5",
    "helmet": "^7.1.0",
    "dotenv": "^16.3.1",
    "zod": "^3.22.4"
  },
  "devDependencies": {
    "@types/express": "^4.17.21",
    "@types/cors": "^2.8.17",
    "@types/node": "^20.10.0",
    "tsx": "^4.6.2",
    "typescript": "^5.7.3"
  }
}

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2022"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

# AI Service Configuration
PORT=3002
NODE_ENV=development

# MongoDB
MONGODB_URI=mongodb://localhost:27017/hrms_ai

# OpenAI
OPENAI_API_KEY=sk-your-key-here

# HRMS API (for tool callbacks)
HRMS_API_URL=http://localhost:3001
HRMS_API_SECRET=shared-secret-for-service-auth

import { z } from 'zod';
import dotenv from 'dotenv';

dotenv.config();

const envSchema = z.object({
  PORT: z.string().default('3002'),
  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
  MONGODB_URI: z.string(),
  OPENAI_API_KEY: z.string(),
  HRMS_API_URL: z.string().default('http://localhost:3001'),
  HRMS_API_SECRET: z.string(),
});

const parsed = envSchema.safeParse(process.env);

if (!parsed.success) {
  console.error('❌ Invalid environment variables:', parsed.error.flatten().fieldErrors);
  process.exit(1);
}

export const config = parsed.data;

import { Request, Response, NextFunction } from 'express';

export class AppError extends Error {
  constructor(
    public statusCode: number,
    public code: string,
    message: string,
  ) {
    super(message);
    this.name = 'AppError';
  }
}

export function errorHandler(
  err: Error,
  _req: Request,
  res: Response,
  _next: NextFunction,
): void {
  console.error('Error:', err);

  if (err instanceof AppError) {
    res.status(err.statusCode).json({
      data: null,
      error: {
        code: err.code,
        message: err.message,
      },
    });
    return;
  }

  res.status(500).json({
    data: null,
    error: {
      code: 'INTERNAL_ERROR',
      message: 'An unexpected error occurred',
    },
  });
}

import { Request, Response, NextFunction } from 'express';
import { AppError } from './error-handler';

export interface AuthenticatedRequest extends Request {
  tenantId: string;
  userId: string;
}

export function authMiddleware(
  req: Request,
  _res: Response,
  next: NextFunction,
): void {
  const tenantId = req.headers['x-tenant-id'] as string;
  const userId = req.headers['x-user-id'] as string;

  if (!tenantId) {
    throw new AppError(401, 'UNAUTHORIZED', 'Missing tenant ID');
  }

  if (!userId) {
    throw new AppError(401, 'UNAUTHORIZED', 'Missing user ID');
  }

  (req as AuthenticatedRequest).tenantId = tenantId;
  (req as AuthenticatedRequest).userId = userId;

  next();
}

import { Router } from 'express';

const router = Router();

router.get('/health', (_req, res) => {
  res.json({
    status: 'ok',
    service: 'ai',
    timestamp: new Date().toISOString(),
  });
});

export const healthRouter = router;

import express from 'express';
import cors from 'cors';
import helmet from 'helmet';
import { config } from './config';
import { errorHandler } from './middleware/error-handler';
import { healthRouter } from './routes/health';

const app = express();

// Middleware
app.use(helmet());
app.use(cors({
  origin: ['http://localhost:3000', 'http://localhost:3001'],
  credentials: true,
}));
app.use(express.json({ limit: '10mb' }));

// Routes
app.use(healthRouter);

// Error handling
app.use(errorHandler);

// Start server
const port = parseInt(config.PORT, 10);
app.listen(port, () => {
  console.log(`🤖 AI Service running on http://localhost:${port}`);
  console.log(`   Environment: ${config.NODE_ENV}`);
});

cd apps/ai
npm install

# Create .env from example (with dummy values for now)
cp .env.example .env
# Edit .env to add: MONGODB_URI=mongodb://localhost:27017/hrms_ai
# Edit .env to add: OPENAI_API_KEY=sk-dummy-for-testing
# Edit .env to add: HRMS_API_SECRET=test-secret

npm run dev &
sleep 3
curl http://localhost:3002/health
# Should return: {"status":"ok","service":"ai","timestamp":"..."}

# Kill the dev server
pkill -f "tsx watch"

rm -rf apps/ai

apps/ai/package.json
apps/ai/tsconfig.json
apps/ai/src/index.ts
apps/ai/src/config.ts
apps/ai/src/middleware/error-handler.ts
apps/ai/src/middleware/auth.ts

# Local MongoDB with Docker
docker run -d --name hrms-mongo -p 27017:27017 mongo:7

# Or use MongoDB Atlas connection string

cd apps/ai
npm install mongodb
npm install -D @types/mongodb

import { MongoClient, Db, Collection } from 'mongodb';
import { config } from '../config';

let client: MongoClient | null = null;
let db: Db | null = null;

export interface DocumentRecord {
  _id: string;
  tenantId: string;
  sourceType: 'document' | 'employee' | 'policy';
  sourceId: string;
  title: string;
  content: string;
  metadata: Record<string, unknown>;
  createdAt: Date;
  updatedAt: Date;
}

export interface ChunkRecord {
  _id: string;
  tenantId: string;
  documentId: string;
  content: string;
  embedding: number[];
  chunkIndex: number;
  metadata: {
    sourceType: string;
    sourceId: string;
    title: string;
  };
  createdAt: Date;
}

export async function connectMongo(): Promise<Db> {
  if (db) return db;

  client = new MongoClient(config.MONGODB_URI);
  await client.connect();

  db = client.db('hrms_ai');

  // Create indexes
  const chunks = db.collection<ChunkRecord>('chunks');
  await chunks.createIndex({ tenantId: 1, documentId: 1 });
  await chunks.createIndex({ tenantId: 1 });

  const documents = db.collection<DocumentRecord>('documents');
  await documents.createIndex({ tenantId: 1, sourceType: 1, sourceId: 1 }, { unique: true });

  console.log('✅ MongoDB connected');
  return db;
}

export async function getDb(): Promise<Db> {
  if (!db) {
    await connectMongo();
  }
  return db!;
}

export async function getDocumentsCollection(): Promise<Collection<DocumentRecord>> {
  const database = await getDb();
  return database.collection<DocumentRecord>('documents');
}

export async function getChunksCollection(): Promise<Collection<ChunkRecord>> {
  const database = await getDb();
  return database.collection<ChunkRecord>('chunks');
}

export async function closeMongo(): Promise<void> {
  if (client) {
    await client.close();
    client = null;
    db = null;
  }
}

import express from 'express';
import cors from 'cors';
import helmet from 'helmet';
import { config } from './config';
import { errorHandler } from './middleware/error-handler';
import { healthRouter } from './routes/health';
import { connectMongo } from './services/mongodb';

const app = express();

// Middleware
app.use(helmet());
app.use(cors({
  origin: ['http://localhost:3000', 'http://localhost:3001'],
  credentials: true,
}));
app.use(express.json({ limit: '10mb' }));

// Routes
app.use(healthRouter);

// Error handling
app.use(errorHandler);

// Start server
async function start(): Promise<void> {
  try {
    await connectMongo();

    const port = parseInt(config.PORT, 10);
    app.listen(port, () => {
      console.log(`🤖 AI Service running on http://localhost:${port}`);
      console.log(`   Environment: ${config.NODE_ENV}`);
    });
  } catch (error) {
    console.error('Failed to start server:', error);
    process.exit(1);
  }
}

start();

import { Router } from 'express';
import { getDb } from '../services/mongodb';

const router = Router();

router.get('/health', async (_req, res) => {
  try {
    const db = await getDb();
    await db.command({ ping: 1 });

    res.json({
      status: 'ok',
      service: 'ai',
      mongodb: 'connected',
      timestamp: new Date().toISOString(),
    });
  } catch (error) {
    res.status(503).json({
      status: 'degraded',
      service: 'ai',
      mongodb: 'disconnected',
      timestamp: new Date().toISOString(),
    });
  }
});

export const healthRouter = router;

# Ensure MongoDB is running
docker ps | grep hrms-mongo

cd apps/ai
npm run dev &
sleep 5

curl http://localhost:3002/health
# Should return: {"status":"ok","service":"ai","mongodb":"connected",...}

pkill -f "tsx watch"

# Remove MongoDB service file
rm apps/ai/src/services/mongodb.ts
# Revert index.ts changes

apps/ai/src/services/mongodb.ts

cd apps/ai
npm install openai @langchain/openai @langchain/core langchain

import OpenAI from 'openai';
import { config } from '../config';

let openaiClient: OpenAI | null = null;

export function getOpenAI(): OpenAI {
  if (!openaiClient) {
    openaiClient = new OpenAI({
      apiKey: config.OPENAI_API_KEY,
    });
  }
  return openaiClient;
}

// Model constants
export const EMBEDDING_MODEL = 'text-embedding-3-small';
export const CHAT_MODEL = 'gpt-4o-mini';
export const EMBEDDING_DIMENSIONS = 1536;

export interface ChatMessage {
  role: 'user' | 'assistant' | 'system';
  content: string;
}

export interface ChatContext {
  tenantId: string;
  userId: string;
  employeeId?: string;
}

export interface ToolCall {
  id: string;
  name: string;
  arguments: Record<string, unknown>;
}

export interface ToolResult {
  toolCallId: string;
  name: string;
  result: unknown;
}

export interface ChatRequest {
  message: string;
  conversationHistory?: ChatMessage[];
  context: ChatContext;
}

export interface ChatResponse {
  message: string;
  toolCalls?: ToolCall[];
  toolResults?: ToolResult[];
}

cd apps/ai
npm run build
# Should complete without errors

# Verify imports work
cat > /tmp/test-imports.ts << 'EOF'
import OpenAI from 'openai';
import { ChatOpenAI } from '@langchain/openai';
console.log('Imports OK');
EOF

npx tsx /tmp/test-imports.ts
# Should print: Imports OK

rm /tmp/test-imports.ts

npm uninstall openai @langchain/openai @langchain/core langchain

apps/ai/src/services/openai.ts
apps/ai/src/types/index.ts

import { RecursiveCharacterTextSplitter } from 'langchain/text_splitter';

export interface ChunkInput {
  content: string;
  metadata: {
    documentId: string;
    sourceType: 'document' | 'employee' | 'policy';
    sourceId: string;
    title: string;
  };
}

export interface ChunkOutput {
  content: string;
  chunkIndex: number;
  metadata: ChunkInput['metadata'];
}

const splitter = new RecursiveCharacterTextSplitter({
  chunkSize: 1000,
  chunkOverlap: 200,
  separators: ['\n\n', '\n', '. ', ' ', ''],
});

export async function chunkDocument(input: ChunkInput): Promise<ChunkOutput[]> {
  const { content, metadata } = input;

  if (!content || content.trim().length === 0) {
    return [];
  }

  const chunks = await splitter.splitText(content);

  return chunks.map((chunkContent, index) => ({
    content: chunkContent,
    chunkIndex: index,
    metadata,
  }));
}

export async function chunkDocuments(inputs: ChunkInput[]): Promise<ChunkOutput[]> {
  const results: ChunkOutput[] = [];

  for (const input of inputs) {
    const chunks = await chunkDocument(input);
    results.push(...chunks);
  }

  return results;
}

cd apps/ai

# Create test file
cat > /tmp/test-chunking.ts << 'EOF'
import { chunkDocument } from './src/services/chunking';

async function test() {
  const result = await chunkDocument({
    content: 'This is paragraph one.\n\nThis is paragraph two with more content that goes on for a while to test the chunking behavior.\n\nParagraph three.',
    metadata: {
      documentId: 'doc-1',
      sourceType: 'document',
      sourceId: 'src-1',
      title: 'Test Doc',
    },
  });

  console.log('Chunks created:', result.length);
  console.log('First chunk:', result[0]?.content.substring(0, 50));

  if (result.length > 0 && result[0].metadata.documentId === 'doc-1') {
    console.log('✅ Chunking test passed');
  } else {
    console.error('❌ Chunking test failed');
    process.exit(1);
  }
}

test();
EOF

npx tsx /tmp/test-chunking.ts
# Should print: ✅ Chunking test passed

rm /tmp/test-chunking.ts

rm apps/ai/src/services/chunking.ts

apps/ai/src/services/chunking.ts

import { getOpenAI, EMBEDDING_MODEL, EMBEDDING_DIMENSIONS } from './openai';

export interface EmbeddingInput {
  text: string;
  id?: string;
}

export interface EmbeddingOutput {
  embedding: number[];
  id?: string;
}

const MAX_BATCH_SIZE = 100;

export async function generateEmbedding(text: string): Promise<number[]> {
  const openai = getOpenAI();

  const response = await openai.embeddings.create({
    model: EMBEDDING_MODEL,
    input: text,
    dimensions: EMBEDDING_DIMENSIONS,
  });

  return response.data[0].embedding;
}

export async function generateEmbeddings(
  inputs: EmbeddingInput[],
): Promise<EmbeddingOutput[]> {
  const openai = getOpenAI();
  const results: EmbeddingOutput[] = [];

  // Process in batches
  for (let i = 0; i < inputs.length; i += MAX_BATCH_SIZE) {
    const batch = inputs.slice(i, i + MAX_BATCH_SIZE);
    const texts = batch.map((input) => input.text);

    const response = await openai.embeddings.create({
      model: EMBEDDING_MODEL,
      input: texts,
      dimensions: EMBEDDING_DIMENSIONS,
    });

    for (let j = 0; j < response.data.length; j++) {
      results.push({
        embedding: response.data[j].embedding,
        id: batch[j].id,
      });
    }
  }

  return results;
}

export function cosineSimilarity(a: number[], b: number[]): number {
  if (a.length !== b.length) {
    throw new Error('Vectors must have same length');
  }

  let dotProduct = 0;
  let normA = 0;
  let normB = 0;

  for (let i = 0; i < a.length; i++) {
    dotProduct += a[i] * b[i];
    normA += a[i] * a[i];
    normB += b[i] * b[i];
  }

  return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
}

cd apps/ai

# Test requires valid OPENAI_API_KEY
# If you have a valid key in .env:
cat > /tmp/test-embedding.ts << 'EOF'
import { generateEmbedding, cosineSimilarity } from './src/services/embedding';

async function test() {
  try {
    const embedding = await generateEmbedding('Hello world');
    console.log('Embedding length:', embedding.length);
    console.log('First 5 values:', embedding.slice(0, 5));

    if (embedding.length === 1536) {
      console.log('✅ Embedding test passed');
    } else {
      console.log('⚠️ Unexpected embedding length');
    }
  } catch (error: any) {
    if (error.message?.includes('API key')) {
      console.log('⏭️ Skipped: No valid API key');
    } else {
      throw error;
    }
  }
}

test();
EOF

npx tsx /tmp/test-embedding.ts
rm /tmp/test-embedding.ts

# Test cosine similarity (no API needed)
cat > /tmp/test-cosine.ts << 'EOF'
import { cosineSimilarity } from './src/services/embedding';

const a = [1, 0, 0];
const b = [1, 0, 0];
const c = [0, 1, 0];

const simAB = cosineSimilarity(a, b);
const simAC = cosineSimilarity(a, c);

console.log('Same vectors:', simAB); // Should be 1
console.log('Orthogonal vectors:', simAC); // Should be 0

if (simAB === 1 && simAC === 0) {
  console.log('✅ Cosine similarity test passed');
} else {
  console.error('❌ Cosine similarity test failed');
  process.exit(1);
}
EOF

npx tsx /tmp/test-cosine.ts
rm /tmp/test-cosine.ts

rm apps/ai/src/services/embedding.ts

apps/ai/src/services/embedding.ts

import { ObjectId } from 'mongodb';
import { getChunksCollection, getDocumentsCollection, ChunkRecord, DocumentRecord } from './mongodb';
import { chunkDocument } from './chunking';
import { generateEmbedding, generateEmbeddings, cosineSimilarity } from './embedding';

export interface IndexDocumentInput {
  tenantId: string;
  sourceType: 'document' | 'employee' | 'policy';
  sourceId: string;
  title: string;
  content: string;
  metadata?: Record<string, unknown>;
}

export interface SearchResult {
  documentId: string;
  sourceType: string;
  sourceId: string;
  title: string;
  content: string;
  score: number;
}

export async function indexDocument(input: IndexDocumentInput): Promise<string> {
  const { tenantId, sourceType, sourceId, title, content, metadata = {} } = input;

  const documents = await getDocumentsCollection();
  const chunks = await getChunksCollection();

  // Check for existing document first (MongoDB doesn't allow changing _id)
  const existing = await documents.findOne({ tenantId, sourceType, sourceId });
  let documentId: string;

  if (existing) {
    // Update existing document
    documentId = existing._id.toString();
    await documents.updateOne(
      { _id: existing._id },
      {
        $set: {
          title,
          content,
          metadata,
          updatedAt: new Date(),
        },
      },
    );
  } else {
    // Insert new document
    const result = await documents.insertOne({
      tenantId,
      sourceType,
      sourceId,
      title,
      content,
      metadata,
      createdAt: new Date(),
      updatedAt: new Date(),
    });
    documentId = result.insertedId.toString();
  }

  // Delete old chunks
  await chunks.deleteMany({ tenantId, documentId });

  // Chunk the document
  const docChunks = await chunkDocument({
    content,
    metadata: { documentId, sourceType, sourceId, title },
  });

  if (docChunks.length === 0) {
    return documentId;
  }

  // Generate embeddings for all chunks
  const embeddings = await generateEmbeddings(
    docChunks.map((chunk, i) => ({
      text: chunk.content,
      id: String(i),
    })),
  );

  // Store chunks with embeddings
  const chunkRecords: ChunkRecord[] = docChunks.map((chunk, i) => ({
    _id: new ObjectId().toString(),
    tenantId,
    documentId,
    content: chunk.content,
    embedding: embeddings[i].embedding,
    chunkIndex: chunk.chunkIndex,
    metadata: chunk.metadata,
    createdAt: new Date(),
  }));

  await chunks.insertMany(chunkRecords);

  return documentId;
}

export async function searchSimilar(
  tenantId: string,
  query: string,
  topK: number = 5,
): Promise<SearchResult[]> {
  const chunks = await getChunksCollection();

  // Generate query embedding
  const queryEmbedding = await generateEmbedding(query);

  // Get all chunks for tenant
  // NOTE: This is O(n) - acceptable for MVP but for production use
  // MongoDB Atlas Vector Search or a dedicated vector database
  const allChunks = await chunks.find({ tenantId }).toArray();

  if (allChunks.length === 0) {
    return [];
  }

  // Calculate similarities
  const scored = allChunks.map((chunk) => ({
    chunk,
    score: cosineSimilarity(queryEmbedding, chunk.embedding),
  }));

  // Sort by score and take top-k
  scored.sort((a, b) => b.score - a.score);
  const topResults = scored.slice(0, topK);

  return topResults.map(({ chunk, score }) => ({
    documentId: chunk.documentId,
    sourceType: chunk.metadata.sourceType,
    sourceId: chunk.metadata.sourceId,
    title: chunk.metadata.title,
    content: chunk.content,
    score,
  }));
}

export async function deleteDocument(
  tenantId: string,
  sourceType: string,
  sourceId: string,
): Promise<boolean> {
  const documents = await getDocumentsCollection();
  const chunks = await getChunksCollection();

  const doc = await documents.findOne({ tenantId, sourceType, sourceId });
  if (!doc) return false;

  await chunks.deleteMany({ tenantId, documentId: doc._id });
  await documents.deleteOne({ _id: doc._id });

  return true;
}

cd apps/ai

# Start MongoDB if not running
docker start hrms-mongo 2>/dev/null || true

# Test requires valid OPENAI_API_KEY for embeddings
cat > /tmp/test-vector-store.ts << 'EOF'
import { connectMongo, closeMongo } from './src/services/mongodb';
import { indexDocument, searchSimilar, deleteDocument } from './src/services/vector-store';

async function test() {
  try {
    await connectMongo();

    // Index a test document
    const docId = await indexDocument({
      tenantId: 'test-tenant',
      sourceType: 'document',
      sourceId: 'test-doc-1',
      title: 'Employee Handbook',
      content: 'All employees must follow the code of conduct. Vacation policy allows 20 days per year.',
    });

    console.log('Indexed document:', docId);

    // Search for similar content
    const results = await searchSimilar('test-tenant', 'vacation days', 3);
    console.log('Search results:', results.length);

    if (results.length > 0) {
      console.log('Top result score:', results[0].score.toFixed(3));
      console.log('✅ Vector store test passed');
    }

    // Cleanup
    await deleteDocument('test-tenant', 'document', 'test-doc-1');
    await closeMongo();
  } catch (error: any) {
    if (error.message?.includes('API key')) {
      console.log('⏭️ Skipped: No valid API key');
    } else {
      throw error;
    }
  }
}

test();
EOF

npx tsx /tmp/test-vector-store.ts
rm /tmp/test-vector-store.ts

rm apps/ai/src/services/vector-store.ts

apps/ai/src/services/vector-store.ts

import { Router } from 'express';
import { z } from 'zod';
import { authMiddleware, AuthenticatedRequest } from '../middleware/auth';
import { searchSimilar, indexDocument } from '../services/vector-store';
import { AppError } from '../middleware/error-handler';

const router = Router();

const querySchema = z.object({
  query: z.string().min(1).max(1000),
  topK: z.number().min(1).max(20).optional().default(5),
});

const indexSchema = z.object({
  sourceType: z.enum(['document', 'employee', 'policy']),
  sourceId: z.string(),
  title: z.string(),
  content: z.string(),
  metadata: z.record(z.unknown()).optional(),
});

// Query for similar documents
router.post('/query', authMiddleware, async (req, res, next) => {
  try {
    const authReq = req as AuthenticatedRequest;
    const parsed = querySchema.safeParse(req.body);

    if (!parsed.success) {
      throw new AppError(400, 'VALIDATION_ERROR', parsed.error.message);
    }

    const { query, topK } = parsed.data;
    const results = await searchSimilar(authReq.tenantId, query, topK);

    res.json({
      data: {
        results,
        query,
        count: results.length,
      },
    });
  } catch (error) {
    next(error);
  }
});

// Index a document
router.post('/index', authMiddleware, async (req, res, next) => {
  try {
    const authReq = req as AuthenticatedRequest;
    const parsed = indexSchema.safeParse(req.body);

    if (!parsed.success) {
      throw new AppError(400, 'VALIDATION_ERROR', parsed.error.message);
    }

    const documentId = await indexDocument({
      tenantId: authReq.tenantId,
      ...parsed.data,
    });

    res.json({
      data: {
        documentId,
        indexed: true,
      },
    });
  } catch (error) {
    next(error);
  }
});

export const ragRouter = router;

import express from 'express';
import cors from 'cors';
import helmet from 'helmet';
import { config } from './config';
import { errorHandler } from './middleware/error-handler';
import { healthRouter } from './routes/health';
import { ragRouter } from './routes/rag';
import { connectMongo } from './services/mongodb';

const app = express();

// Middleware
app.use(helmet());
app.use(cors({
  origin: ['http://localhost:3000', 'http://localhost:3001'],
  credentials: true,
}));
app.use(express.json({ limit: '10mb' }));

// Routes
app.use(healthRouter);
app.use('/ai', ragRouter);

// Error handling
app.use(errorHandler);

// Start server
async function start(): Promise<void> {
  try {
    await connectMongo();

    const port = parseInt(config.PORT, 10);
    app.listen(port, () => {
      console.log(`🤖 AI Service running on http://localhost:${port}`);
      console.log(`   Environment: ${config.NODE_ENV}`);
    });
  } catch (error) {
    console.error('Failed to start server:', error);
    process.exit(1);
  }
}

start();

cd apps/ai
npm run dev &
sleep 5

# Test query endpoint (should return empty results initially)
curl -X POST http://localhost:3002/ai/query \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: test-tenant" \
  -H "x-user-id: test-user" \
  -d '{"query": "vacation policy", "topK": 5}'
# Should return: {"data":{"results":[],"query":"vacation policy","count":0}}

# Test validation
curl -X POST http://localhost:3002/ai/query \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: test-tenant" \
  -H "x-user-id: test-user" \
  -d '{"query": ""}'
# Should return validation error

pkill -f "tsx watch"

rm apps/ai/src/routes/rag.ts

apps/ai/src/routes/rag.ts

import { z, ZodSchema } from 'zod';
import { ChatContext } from '../types';

export interface ToolDefinition {
  name: string;
  description: string;
  parameters: ZodSchema;
  handler: (args: unknown, context: ChatContext) => Promise<unknown>;
}

export interface OpenAITool {
  type: 'function';
  function: {
    name: string;
    description: string;
    parameters: {
      type: 'object';
      properties: Record<string, unknown>;
      required: string[];
    };
  };
}

class ToolRegistry {
  private tools: Map<string, ToolDefinition> = new Map();

  register(tool: ToolDefinition): void {
    this.tools.set(tool.name, tool);
    console.log(`📦 Registered tool: ${tool.name}`);
  }

  get(name: string): ToolDefinition | undefined {
    return this.tools.get(name);
  }

  getAll(): ToolDefinition[] {
    return Array.from(this.tools.values());
  }

  async execute(
    name: string,
    args: unknown,
    context: ChatContext,
  ): Promise<unknown> {
    const tool = this.tools.get(name);
    if (!tool) {
      throw new Error(`Tool not found: ${name}`);
    }

    // Validate arguments
    const parsed = tool.parameters.safeParse(args);
    if (!parsed.success) {
      throw new Error(`Invalid arguments for ${name}: ${parsed.error.message}`);
    }

    return tool.handler(parsed.data, context);
  }

  toOpenAITools(): OpenAITool[] {
    return this.getAll().map((tool) => ({
      type: 'function' as const,
      function: {
        name: tool.name,
        description: tool.description,
        parameters: this.zodToJsonSchema(tool.parameters),
      },
    }));
  }

  private zodToJsonSchema(schema: ZodSchema): {
    type: 'object';
    properties: Record<string, unknown>;
    required: string[];
  } {
    // Simple conversion for our use case
    // In production, use zod-to-json-schema package
    const shape = (schema as z.ZodObject<any>).shape;
    const properties: Record<string, unknown> = {};
    const required: string[] = [];

    for (const [key, value] of Object.entries(shape)) {
      const zodType = value as z.ZodTypeAny;
      properties[key] = this.zodTypeToJsonSchema(zodType);

      if (!zodType.isOptional()) {
        required.push(key);
      }
    }

    return {
      type: 'object',
      properties,
      required,
    };
  }

  private zodTypeToJsonSchema(zodType: z.ZodTypeAny): unknown {
    if (zodType instanceof z.ZodString) {
      return { type: 'string', description: zodType.description };
    }
    if (zodType instanceof z.ZodNumber) {
      return { type: 'number', description: zodType.description };
    }
    if (zodType instanceof z.ZodBoolean) {
      return { type: 'boolean', description: zodType.description };
    }
    if (zodType instanceof z.ZodOptional) {
      return this.zodTypeToJsonSchema(zodType.unwrap());
    }
    return { type: 'string' };
  }
}

export const toolRegistry = new ToolRegistry();

export { toolRegistry } from './registry';
export type { ToolDefinition, OpenAITool } from './registry';

cd apps/ai

cat > /tmp/test-registry.ts << 'EOF'
import { z } from 'zod';
import { toolRegistry } from './src/tools/registry';

// Register a test tool
toolRegistry.register({
  name: 'test_tool',
  description: 'A test tool',
  parameters: z.object({
    message: z.string().describe('The message to echo'),
  }),
  handler: async (args: { message: string }) => {
    return { echo: args.message };
  },
});

// Test tool retrieval
const tool = toolRegistry.get('test_tool');
console.log('Tool found:', !!tool);

// Test OpenAI format
const openaiTools = toolRegistry.toOpenAITools();
console.log('OpenAI tools:', JSON.stringify(openaiTools, null, 2));

// Test execution
async function testExec() {
  const result = await toolRegistry.execute(
    'test_tool',
    { message: 'Hello' },
    { tenantId: 't1', userId: 'u1' },
  );
  console.log('Execution result:', result);
  console.log('✅ Registry test passed');
}

testExec();
EOF

npx tsx /tmp/test-registry.ts
rm /tmp/test-registry.ts

rm -rf apps/ai/src/tools

apps/ai/src/tools/registry.ts
apps/ai/src/tools/index.ts

import { config } from '../config';

interface HrmsRequestOptions {
  tenantId: string;
  method?: 'GET' | 'POST' | 'PATCH' | 'DELETE';
  body?: unknown;
}

// NOTE: Service-to-service auth requires a ServiceSecretGuard in NestJS API
// that validates x-service-secret header. Add to @nestjs/api guards:
//
// @Injectable()
// export class ServiceSecretGuard implements CanActivate {
//   canActivate(context: ExecutionContext): boolean {
//     const request = context.switchToHttp().getRequest();
//     const secret = request.headers['x-service-secret'];
//     return secret === process.env.SERVICE_SECRET;
//   }
// }
//
// Apply to endpoints that AI service calls (employee search, org structure, etc.)
export async function hrmsRequest<T>(
  path: string,
  options: HrmsRequestOptions,
): Promise<T> {
  const { tenantId, method = 'GET', body } = options;

  const response = await fetch(`${config.HRMS_API_URL}${path}`, {
    method,
    headers: {
      'Content-Type': 'application/json',
      'x-tenant-id': tenantId,
      'x-service-secret': config.HRMS_API_SECRET,
    },
    body: body ? JSON.stringify(body) : undefined,
  });

  if (!response.ok) {
    const error = await response.json().catch(() => ({}));
    throw new Error(`HRMS API error: ${response.status} - ${error.message || 'Unknown error'}`);
  }

  const result = await response.json();
  return result.data;
}

import { z } from 'zod';
import { toolRegistry } from './registry';
import { hrmsRequest } from '../services/hrms-client';
import { ChatContext } from '../types';

const parametersSchema = z.object({
  query: z.string().describe('Search query for employee name, email, or job title'),
  limit: z.number().min(1).max(10).optional().default(5).describe('Maximum results to return'),
});

interface EmployeeSearchResult {
  id: string;
  firstName: string;
  lastName: string;
  email: string;
  jobTitle: string | null;
  department: string | null;
}

interface EmployeesResponse {
  items: Array<{
    id: string;
    firstName: string;
    lastName: string;
    email: string;
    jobTitle: string | null;
    departments: Array<{ department: { name: string }; isPrimary: boolean }>;
  }>;
}

async function handler(
  args: z.infer<typeof parametersSchema>,
  context: ChatContext,
): Promise<EmployeeSearchResult[]> {
  const { query, limit } = args;

  try {
    const response = await hrmsRequest<EmployeesResponse>(
      `/api/v1/employees?search=${encodeURIComponent(query)}&limit=${limit}`,
      { tenantId: context.tenantId },
    );

    return response.items.map((emp) => ({
      id: emp.id,
      firstName: emp.firstName,
      lastName: emp.lastName,
      email: emp.email,
      jobTitle: emp.jobTitle,
      department: emp.departments.find((d) => d.isPrimary)?.department.name || null,
    }));
  } catch (error) {
    console.error('Employee search failed:', error);
    return [];
  }
}

export function registerEmployeeSearchTool(): void {
  toolRegistry.register({
    name: 'employee_search',
    description: 'Search for employees by name, email, or job title. Use this to find people in the organization.',
    parameters: parametersSchema,
    handler,
  });
}

cd apps/ai

cat > /tmp/test-employee-tool.ts << 'EOF'
import { toolRegistry } from './src/tools/registry';
import { registerEmployeeSearchTool } from './src/tools/employee-search';

registerEmployeeSearchTool();

const tool = toolRegistry.get('employee_search');
console.log('Tool registered:', !!tool);
console.log('Tool name:', tool?.name);
console.log('Tool description:', tool?.description);

// Check OpenAI format
const openaiTools = toolRegistry.toOpenAITools();
const employeeTool = openaiTools.find(t => t.function.name === 'employee_search');
console.log('OpenAI format:', JSON.stringify(employeeTool, null, 2));

console.log('✅ Employee search tool test passed');
EOF

npx tsx /tmp/test-employee-tool.ts
rm /tmp/test-employee-tool.ts

rm apps/ai/src/tools/employee-search.ts
rm apps/ai/src/services/hrms-client.ts

apps/ai/src/tools/employee-search.ts
apps/ai/src/services/hrms-client.ts

import { z } from 'zod';
import { toolRegistry } from './registry';
import { searchSimilar } from '../services/vector-store';
import { ChatContext } from '../types';

const parametersSchema = z.object({
  query: z.string().describe('Search query for finding relevant documents'),
  limit: z.number().min(1).max(10).optional().default(5).describe('Maximum results to return'),
});

interface DocumentSearchResult {
  title: string;
  content: string;
  sourceType: string;
  relevanceScore: number;
}

async function handler(
  args: z.infer<typeof parametersSchema>,
  context: ChatContext,
): Promise<DocumentSearchResult[]> {
  const { query, limit } = args;

  const results = await searchSimilar(context.tenantId, query, limit);

  return results.map((result) => ({
    title: result.title,
    content: result.content,
    sourceType: result.sourceType,
    relevanceScore: Math.round(result.score * 100) / 100,
  }));
}

export function registerDocumentSearchTool(): void {
  toolRegistry.register({
    name: 'document_search',
    description: 'Search company documents, policies, and knowledge base using semantic search. Use this to find information about company policies, procedures, or any documented knowledge.',
    parameters: parametersSchema,
    handler,
  });
}

cd apps/ai

cat > /tmp/test-doc-tool.ts << 'EOF'
import { toolRegistry } from './src/tools/registry';
import { registerDocumentSearchTool } from './src/tools/document-search';

registerDocumentSearchTool();

const tool = toolRegistry.get('document_search');
console.log('Tool registered:', !!tool);
console.log('Tool name:', tool?.name);

const openaiTools = toolRegistry.toOpenAITools();
const docTool = openaiTools.find(t => t.function.name === 'document_search');
console.log('Has parameters:', !!docTool?.function.parameters);

console.log('✅ Document search tool test passed');
EOF

npx tsx /tmp/test-doc-tool.ts
rm /tmp/test-doc-tool.ts

rm apps/ai/src/tools/document-search.ts

apps/ai/src/tools/document-search.ts

import { z } from 'zod';
import { toolRegistry } from './registry';
import { hrmsRequest } from '../services/hrms-client';
import { ChatContext } from '../types';

const parametersSchema = z.object({
  employeeId: z.string().describe('The employee ID to explain org structure for'),
});

interface OrgSummary {
  employee: {
    id: string;
    name: string;
    jobTitle: string | null;
  };
  primaryManager: {
    id: string;
    name: string;
    jobTitle: string | null;
  } | null;
  dottedLineManagers: Array<{
    id: string;
    name: string;
    jobTitle: string | null;
  }>;
  directReports: number;
  teams: string[];
  departments: string[];
}

interface OrgApiResponse {
  employee: {
    id: string;
    firstName: string;
    lastName: string;
    jobTitle: string | null;
  };
  primaryManager: {
    id: string;
    firstName: string;
    lastName: string;
    jobTitle: string | null;
  } | null;
  dottedLineManagers: Array<{
    id: string;
    firstName: string;
    lastName: string;
    jobTitle: string | null;
  }>;
  directReports: Array<unknown>;
  teams: Array<{ team: { name: string } }>;
  departments: Array<{ department: { name: string } }>;
}

async function handler(
  args: z.infer<typeof parametersSchema>,
  context: ChatContext,
): Promise<OrgSummary> {
  const { employeeId } = args;

  const response = await hrmsRequest<OrgApiResponse>(
    `/api/v1/org/employees/${employeeId}/summary`,
    { tenantId: context.tenantId },
  );

  return {
    employee: {
      id: response.employee.id,
      name: `${response.employee.firstName} ${response.employee.lastName}`,
      jobTitle: response.employee.jobTitle,
    },
    primaryManager: response.primaryManager
      ? {
          id: response.primaryManager.id,
          name: `${response.primaryManager.firstName} ${response.primaryManager.lastName}`,
          jobTitle: response.primaryManager.jobTitle,
        }
      : null,
    dottedLineManagers: response.dottedLineManagers.map((m) => ({
      id: m.id,
      name: `${m.firstName} ${m.lastName}`,
      jobTitle: m.jobTitle,
    })),
    directReports: response.directReports.length,
    teams: response.teams.map((t) => t.team.name),
    departments: response.departments.map((d) => d.department.name),
  };
}

export function registerOrgExplainTool(): void {
  toolRegistry.register({
    name: 'org_explain',
    description: 'Get detailed org structure information for an employee including their manager, dotted line managers, direct reports, teams, and departments.',
    parameters: parametersSchema,
    handler,
  });
}

cd apps/ai

cat > /tmp/test-org-tool.ts << 'EOF'
import { toolRegistry } from './src/tools/registry';
import { registerOrgExplainTool } from './src/tools/org-explain';

registerOrgExplainTool();

const tool = toolRegistry.get('org_explain');
console.log('Tool registered:', !!tool);
console.log('Tool name:', tool?.name);

console.log('✅ Org explain tool test passed');
EOF

npx tsx /tmp/test-org-tool.ts
rm /tmp/test-org-tool.ts

rm apps/ai/src/tools/org-explain.ts

apps/ai/src/tools/org-explain.ts

import { z } from 'zod';
import { toolRegistry } from './registry';
import { hrmsRequest } from '../services/hrms-client';
import { ChatContext } from '../types';

const parametersSchema = z.object({
  employeeId: z.string().optional().describe('The employee ID to check balance for. If not provided, returns the current user\'s balance.'),
});

interface TimeOffBalance {
  policyName: string;
  entitled: number;
  used: number;
  pending: number;
  available: number;
}

// Response shape matches Phase 05 TimeOffBalanceService
interface BalanceApiResponse {
  data: Array<{
    policyName: string;
    entitled: number;
    used: number;
    pending: number;
    available: number;
  }>;
}

async function handler(
  args: z.infer<typeof parametersSchema>,
  context: ChatContext,
): Promise<TimeOffBalance[]> {
  // Use provided employeeId or fall back to current user's employee
  const employeeId = args.employeeId || context.employeeId;

  if (!employeeId) {
    throw new Error('No employee ID provided and current user has no linked employee');
  }

  const response = await hrmsRequest<BalanceApiResponse>(
    `/api/v1/timeoff/balances/${employeeId}`,
    { tenantId: context.tenantId },
  );

  return response.data.map((balance) => ({
    policyName: balance.policyName,
    entitled: balance.entitled,
    used: balance.used,
    pending: balance.pending,
    available: balance.available,
  }));
}

export function registerTimeoffBalanceTool(): void {
  toolRegistry.register({
    name: 'timeoff_balance',
    description: 'Get time-off balance for an employee showing available days, used days, and pending requests for each policy type (vacation, sick leave, etc.).',
    parameters: parametersSchema,
    handler,
  });
}