@hazeljs/cli 0.4.1 → 0.5.1

package/@template-ai-native/src/agent/agent.controller.ts

@@ -0,0 +1,170 @@
+import { Controller, Post, Body, Service, Res } from '@hazeljs/core';
+import type { HazelResponse } from '@hazeljs/core';
+import { Agent, Tool, AgentService } from '@hazeljs/agent';
+
+// AI Agent with tools — 3 tools: getWeather, getForecast, convertTemperature
+// The agent autonomously picks the right tool(s) at runtime based on the request.
+@Agent({
+  name: 'WeatherAgent',
+  description: 'AI assistant that can provide weather information',
+  systemPrompt: 'You are a helpful assistant that can provide weather information for any city.',
+})
+@Service()
+export class WeatherAgent {
+  constructor(private readonly agentService: AgentService) {}
+
+  @Tool({
+    description: 'Get current weather conditions for a city',
+    parameters: [
+      {
+        name: 'city',
+        type: 'string',
+        description: 'The city to get weather for',
+        required: true,
+      },
+    ],
+  })
+  async getWeather(input: { city: string }) {
+    // In real app, call a real weather API
+    return {
+      city: input.city,
+      temperature: '72°F',
+      condition: 'sunny',
+      humidity: '45%',
+      windSpeed: '10 mph',
+    };
+  }
+
+  @Tool({
+    description: 'Get a multi-day weather forecast for a city',
+    parameters: [
+      {
+        name: 'city',
+        type: 'string',
+        description: 'The city to get forecast for',
+        required: true,
+      },
+      {
+        name: 'days',
+        type: 'number',
+        description: 'Number of days to forecast (1-7)',
+        required: true,
+      },
+    ],
+  })
+  async getForecast(input: { city: string; days: number }) {
+    // In real app, call a real forecast API
+    const forecast = Array.from({ length: input.days }, (_, i) => ({
+      day: i + 1,
+      condition: ['sunny', 'cloudy', 'rainy', 'sunny', 'partly cloudy', 'sunny', 'windy'][i % 7],
+      high: `${68 + i}°F`,
+      low: `${52 + i}°F`,
+    }));
+    return { city: input.city, days: input.days, forecast };
+  }
+
+  @Tool({
+    description: 'Convert a temperature value between Celsius, Fahrenheit, and Kelvin',
+    parameters: [
+      {
+        name: 'value',
+        type: 'number',
+        description: 'The temperature value to convert',
+        required: true,
+      },
+      {
+        name: 'fromUnit',
+        type: 'string',
+        description: 'The unit to convert from: celsius, fahrenheit, or kelvin',
+        required: true,
+      },
+      {
+        name: 'toUnit',
+        type: 'string',
+        description: 'The unit to convert to: celsius, fahrenheit, or kelvin',
+        required: true,
+      },
+    ],
+  })
+  async convertTemperature(input: { value: number; fromUnit: string; toUnit: string }) {
+    const { value, fromUnit, toUnit } = input;
+    let celsius: number;
+
+    switch (fromUnit.toLowerCase()) {
+      case 'fahrenheit': celsius = (value - 32) * (5 / 9); break;
+      case 'kelvin':     celsius = value - 273.15; break;
+      default:           celsius = value;
+    }
+
+    let result: number;
+    switch (toUnit.toLowerCase()) {
+      case 'fahrenheit': result = celsius * (9 / 5) + 32; break;
+      case 'kelvin':     result = celsius + 273.15; break;
+      default:           result = celsius;
+    }
+
+    return {
+      original: `${value}°${fromUnit.charAt(0).toUpperCase()}`,
+      converted: `${Math.round(result * 10) / 10}°${toUnit.charAt(0).toUpperCase()}`,
+    };
+  }
+
+  async execute(input: string) {
+    const result = await this.agentService.execute('WeatherAgent', input);
+    return result.response;
+  }
+
+  // Returns the full reasoning trace: every step the agent took, which tool
+  // was called, what the input/output was, and how long each step took.
+  async executeWithTrace(input: string) {
+    const result = await this.agentService.execute('WeatherAgent', input);
+    const steps = result.steps.map((step) => ({
+      step: step.stepNumber,
+      state: step.state,
+      tool: step.action?.toolName ?? null,
+      toolInput: step.action?.toolInput ?? null,
+      toolOutput: step.result?.output ?? null,
+      duration: step.duration ?? null,
+    }));
+    return { response: result.response, steps, totalDuration: result.duration };
+  }
+}
+
+@Controller('agent')
+export class AgentController {
+  constructor(
+    private readonly agent: WeatherAgent,
+    private readonly agentService: AgentService,
+  ) {}
+
+  @Post()
+  async askAgent(@Body() body: { message: string }) {
+    const response = await this.agent.execute(body.message);
+    return { response };
+  }
+
+  // Feature: Execution trace — see every reasoning step the agent took
+  @Post('trace')
+  async traceAgent(@Body() body: { message: string }) {
+    return await this.agent.executeWithTrace(body.message);
+  }
+
+  // Feature: Streaming — token-by-token SSE stream of the agent's response
+  @Post('stream')
+  async streamAgent(@Body() body: { message: string }, @Res() res: HazelResponse) {
+    res.setHeader('Content-Type', 'text/event-stream');
+    res.setHeader('Cache-Control', 'no-cache');
+    res.setHeader('Connection', 'keep-alive');
+
+    for await (const chunk of this.agentService.executeStream('WeatherAgent', body.message)) {
+      if (chunk.type === 'token') {
+        res.write(`data: ${JSON.stringify({ type: 'token', content: chunk.content })}\n\n`);
+      } else if (chunk.type === 'step') {
+        res.write(`data: ${JSON.stringify({ type: 'step', state: chunk.step.state, tool: chunk.step.action?.toolName ?? null })}\n\n`);
+      } else if (chunk.type === 'done') {
+        res.write(`data: ${JSON.stringify({ type: 'done', response: chunk.result.response })}\n\n`);
+      }
+    }
+    res.end();
+  }
+}

package/@template-ai-native/src/agent/travel.controller.ts

@@ -0,0 +1,124 @@
+import { Controller, Post, Body, Service } from '@hazeljs/core';
+import { Agent, Tool, Delegate, AgentService } from '@hazeljs/agent';
+
+// ─── FactsAgent ───────────────────────────────────────────────────────────────
+// A standalone specialist agent the Supervisor can route to.
+// It knows fun facts and travel tips about cities.
+@Agent({
+  name: 'FactsAgent',
+  description: 'Provides fun facts, cultural highlights, and travel tips about cities',
+  systemPrompt: 'You are a knowledgeable travel guide. Use your tools to provide interesting facts and tips about cities.',
+})
+@Service()
+export class FactsAgent {
+  @Tool({
+    description: 'Get fun facts, cultural highlights, and travel tips for a city',
+    parameters: [
+      {
+        name: 'city',
+        type: 'string',
+        description: 'The city to get facts and travel tips for',
+        required: true,
+      },
+    ],
+  })
+  async getCityFacts(input: { city: string }) {
+    // In real app, call a travel/facts API or use a knowledge base
+    const facts: Record<string, { fact: string; tip: string; bestTime: string }> = {
+      paris:   { fact: 'Paris has more than 470 parks and gardens.', tip: 'Buy a Paris Museum Pass to skip long queues.', bestTime: 'April–June or September–November' },
+      tokyo:   { fact: 'Tokyo has the world\'s busiest pedestrian crossing at Shibuya.', tip: 'Get a Suica card for seamless transit across the city.', bestTime: 'March–May (cherry blossom) or October–November' },
+      london:  { fact: 'London has over 170 museums, most of which are free.', tip: 'The Oyster card gives the cheapest fares on public transport.', bestTime: 'May–September for mild weather' },
+      newyork: { fact: 'New York City has 468 subway stations — the most in the world.', tip: 'Walk the High Line for great views and free art installations.', bestTime: 'April–June or September–November' },
+    };
+
+    const key = input.city.toLowerCase().replace(/\s+/g, '');
+    const data = facts[key] ?? {
+      fact: `${input.city} is a fascinating city with a rich history and culture.`,
+      tip: `Explore local neighborhoods and try the street food in ${input.city}.`,
+      bestTime: 'Spring and autumn are generally pleasant for travel.',
+    };
+
+    return { city: input.city, ...data };
+  }
+}
+
+// ─── TravelAgent ──────────────────────────────────────────────────────────────
+// An orchestrator agent that delegates to WeatherAgent via @Delegate.
+// The LLM sees each @Delegate method as a tool — agent-to-agent calls are
+// completely transparent to the model.
+@Agent({
+  name: 'TravelAgent',
+  description: 'Travel planning assistant that checks weather and provides itinerary advice',
+  systemPrompt: 'You are a travel planner. Use your tools to check weather and forecasts for cities, then provide helpful travel advice based on the conditions.',
+})
+@Service()
+export class TravelAgent {
+  constructor(private readonly agentService: AgentService) {}
+
+  // @Delegate transparently routes this tool call to WeatherAgent at runtime.
+  // The LLM sees it as a regular tool — agent-to-agent is completely transparent.
+  @Delegate({
+    agent: 'WeatherAgent',
+    description: 'Check weather conditions and forecasts for a city to inform travel recommendations',
+    inputField: 'input',
+  })
+  async checkWeather(input: string): Promise<string> {
+    return ''; // body replaced at runtime by AgentRuntime
+  }
+
+  // @Delegate to a different specialist agent — FactsAgent
+  @Delegate({
+    agent: 'FactsAgent',
+    description: 'Get travel tips, cultural highlights, and fun facts about a city',
+    inputField: 'input',
+  })
+  async checkFacts(input: string): Promise<string> {
+    return ''; // body replaced at runtime by AgentRuntime
+  }
+
+  async execute(input: string) {
+    const result = await this.agentService.execute('TravelAgent', input);
+    return result.response;
+  }
+}
+
+// ─── TravelController ─────────────────────────────────────────────────────────
+@Controller('travel')
+export class TravelController {
+  constructor(
+    private readonly travelAgent: TravelAgent,
+    private readonly agentService: AgentService,
+  ) {}
+
+  // Feature: Agent Delegation — TravelAgent delegates to WeatherAgent via @Delegate
+  // Try: "Plan a 3-day trip to Tokyo"
+  @Post()
+  async planTrip(@Body() body: { message: string }) {
+    const response = await this.travelAgent.execute(body.message);
+    return { response };
+  }
+
+  // Feature: Supervisor — LLM router routes between WeatherAgent and FactsAgent
+  // at runtime based on which specialist is most relevant to the request.
+  // Try: "What should I pack for a trip to London?" or "Tell me about Paris"
+  @Post('supervisor')
+  async supervisorRoute(@Body() body: { message: string }) {
+    const runtime = this.agentService.getRuntime();
+    const supervisor = runtime.createSupervisor({
+      name: 'travel-supervisor',
+      workers: ['WeatherAgent', 'FactsAgent'],
+      systemPrompt: 'You are a travel planning supervisor. Route requests to WeatherAgent for weather/forecast questions and to FactsAgent for city facts, tips, and general travel advice. Combine results when both are relevant.',
+      maxRounds: 6,
+    });
+
+    const result = await supervisor.run(body.message);
+    return {
+      response: result.response,
+      rounds: result.rounds.map((r) => ({
+        round: r.round,
+        worker: r.decision.worker ?? 'supervisor',
+        thought: r.decision.thought ?? null,
+      })),
+    };
+  }
+}

package/@template-ai-native/src/ai/chat.controller.ts

@@ -0,0 +1,27 @@
+import { Controller, Post, Body, Service } from '@hazeljs/core';
+import { AIEnhancedService } from '@hazeljs/ai';
+
+@Service()
+export class ChatService {
+  constructor(private readonly ai: AIEnhancedService) {}
+
+  async chat(message: string): Promise<string> {
+    return this.ai
+      .chat(message)
+      .system('You are a helpful assistant specializing in HazelJS and TypeScript development.')
+      .model('gpt-4')
+      .temperature(0.7)
+      .text();
+  }
+}
+
+@Controller('chat')
+export class ChatController {
+  constructor(private readonly chatService: ChatService) {}
+
+  @Post()
+  async sendMessage(@Body() body: { message: string }) {
+    const response = await this.chatService.chat(body.message);
+    return { response };
+  }
+}

package/@template-ai-native/src/app.module.ts

@@ -0,0 +1,44 @@
+import { HazelModule } from '@hazeljs/core';
+import { InspectorModule } from '@hazeljs/inspector';
+import { AIModule } from '@hazeljs/ai';
+import { AgentModule } from '@hazeljs/agent';
+import { RAGModule } from '@hazeljs/rag';
+import { ConfigModule } from '@hazeljs/config';
+import { CacheModule } from '@hazeljs/cache';
+import { ChatController } from './ai/chat.controller';
+import { RAGController } from './rag/rag.controller';
+import { HealthController } from './health.controller';
+
+// Import agent classes BEFORE AgentModule to ensure @Agent decorators run first
+import { AgentController, WeatherAgent } from './agent/agent.controller';
+import { TravelController, TravelAgent, FactsAgent } from './agent/travel.controller';
+
+@HazelModule({
+  imports: [
+    // Inspector - dev tools at /__hazel
+    InspectorModule.forRoot({
+      inspectorBasePath: '/__hazel',
+      developmentOnly: true,
+    }) as any,
+    // Configuration module
+    ConfigModule.forRoot({
+      envFilePath: ['.env', '.env.local'],
+      isGlobal: true,
+    }) as any,
+    // Cache Module
+    CacheModule.forRoot({
+      strategy: 'memory',
+      isGlobal: true,
+    }) as any,
+    // AI Module with OpenAI provider (must come before AgentModule)
+    AIModule,
+    // RAG Module
+    RAGModule,
+    // Agent Module - auto-discovers @Agent decorated classes
+    // LLM provider is auto-configured from AIEnhancedService (via AIModule)
+    AgentModule.forRoot() as any,
+  ],
+  controllers: [ChatController, RAGController, HealthController, AgentController, TravelController],
+  providers: [WeatherAgent, TravelAgent, FactsAgent],
+})
+export class AppModule {}

package/@template-ai-native/src/health.controller.ts

@@ -0,0 +1,14 @@
+import { Controller, Get } from '@hazeljs/core';
+
+@Controller('/')
+export class HealthController {
+  @Get('health')
+  health() {
+    return { status: 'ok', timestamp: new Date().toISOString() };
+  }
+
+  @Get()
+  root() {
+    return { message: 'HazelJS AI-Native Application', version: '1.0.0' };
+  }
+}

package/@template-ai-native/src/index.ts

@@ -0,0 +1,12 @@
+import { HazelApp } from '@hazeljs/core';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = new HazelApp(AppModule);
+  await app.listen(3000);
+  console.log('🚀 HazelJS AI-Native app running on http://localhost:3000');
+  console.log('📊 Inspector: http://localhost:3000/__hazel');
+  console.log('🏥 Health: http://localhost:3000/health');
+}
+
+bootstrap();

package/@template-ai-native/src/rag/rag.controller.ts

@@ -0,0 +1,161 @@
+import { Controller, Post, Get, Body, Service } from '@hazeljs/core';
+import { OpenAIEmbeddings } from '@hazeljs/rag';
+import { PrismaClient } from '@prisma/client';
+
+@Service()
+export class RAGService {
+  private embeddings: OpenAIEmbeddings;
+  private prisma: PrismaClient;
+
+  constructor() {
+    // Initialize embeddings for generating vectors
+    this.embeddings = new OpenAIEmbeddings({
+      apiKey: process.env.OPENAI_API_KEY!,
+      model: 'text-embedding-3-small',
+    });
+    
+    // Initialize Prisma for PostgreSQL storage
+    this.prisma = new PrismaClient();
+  }
+
+  async onModuleInit() {
+    await this.prisma.$connect();
+    const count = await this.prisma.document.count();
+    console.log(`RAG Service initialized - PostgreSQL vector store ready with ${count} documents`);
+  }
+  
+  async onModuleDestroy() {
+    await this.prisma.$disconnect();
+  }
+
+  async ingestDocument(content: string, metadata?: any) {
+    console.log(`Ingesting document, content length: ${content.length}`);
+    
+    // Generate embedding for the document
+    const embedding = await this.embeddings.embed(content);
+    
+    // Store in PostgreSQL
+    const document = await this.prisma.document.create({
+      data: {
+        content,
+        embedding,
+        metadata: {
+          source: 'user-input',
+          timestamp: new Date().toISOString(),
+          ...metadata,
+        },
+      },
+    });
+    
+    const totalDocuments = await this.prisma.document.count();
+    console.log(`Document ingested successfully. ID: ${document.id}, Total documents: ${totalDocuments}`);
+    
+    return { 
+      id: document.id, 
+      message: 'Document ingested successfully and stored in PostgreSQL',
+      totalDocuments
+    };
+  }
+
+  async search(query: string, topK = 5) {
+    const totalDocuments = await this.prisma.document.count();
+    console.log(`RAG search requested for: "${query}". Total documents: ${totalDocuments}`);
+    
+    // Generate embedding for the query
+    const queryVector = await this.embeddings.embed(query);
+    
+    // Perform vector similarity search using raw SQL for cosine similarity
+    const results = await this.prisma.$queryRaw<Array<{
+      id: string;
+      content: string;
+      metadata: any;
+      embedding: number[];
+      similarity: number;
+    }>>`
+      SELECT 
+        id,
+        content,
+        metadata,
+        embedding,
+        (1 - (embedding <=> ${queryVector}::vector)) as similarity
+      FROM documents
+      ORDER BY embedding <=> ${queryVector}::vector
+      LIMIT ${topK}
+    `;
+    
+    console.log(`RAG search for "${query}" returned ${results.length} results`);
+    
+    return results.map(result => ({
+      id: result.id,
+      content: result.content,
+      score: result.similarity,
+      metadata: result.metadata,
+    }));
+  }
+  
+  async getDocumentCount() {
+    const totalDocuments = await this.prisma.document.count();
+    return { totalDocuments };
+  }
+  
+  async getAllDocuments() {
+    const documents = await this.prisma.document.findMany({
+      select: {
+        id: true,
+        content: true,
+        metadata: true,
+        createdAt: true,
+      },
+      orderBy: {
+        createdAt: 'desc',
+      },
+    });
+    return documents;
+  }
+}
+
+@Controller('rag')
+export class RAGController {
+  constructor(private readonly ragService: RAGService) {}
+
+  @Post('ingest')
+  async ingestDocument(@Body() body: { content: string; metadata?: any }) {
+    const result = await this.ragService.ingestDocument(body.content, body.metadata);
+    return result;
+  }
+
+  @Post('search')
+  async search(@Body() body: { query: string }) {
+    const results = await this.ragService.search(body.query);
+    return { results };
+  }
+
+  @Get('documents')
+  async getDocuments() {
+    const stats = await this.ragService.getDocumentCount();
+    return { 
+      message: 'RAG service is ready - PostgreSQL vector store with persistent storage',
+      ...stats,
+      endpoints: {
+        ingest: 'POST /rag/ingest - Add documents to PostgreSQL',
+        search: 'POST /rag/search - Search documents with vector similarity',
+        stats: 'GET /rag/stats - Get document count',
+        list: 'GET /rag/list - List all documents'
+      }
+    };
+  }
+  
+  @Get('stats')
+  async getStats() {
+    return this.ragService.getDocumentCount();
+  }
+  
+  @Get('list')
+  async listDocuments() {
+    const documents = await this.ragService.getAllDocuments();
+    return { 
+      documents,
+      total: documents.length
+    };
+  }
+}

package/@template-ai-native/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "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", "**/*.test.ts"]
+}