@hazeljs/cli 0.5.0 → 0.5.2

package/@template-ai-native/README.md

@@ -0,0 +1,286 @@
+# HazelJS AI-Native Application
+
+A complete AI-native backend application with HazelJS, featuring:
+
+- 🤖 **AI Chat Service** - OpenAI-powered chat endpoints
+- 🧠 **AI Agents** - Agents with tools and capabilities  
+- 📚 **RAG System** - Document ingestion and semantic search
+- 🏥 **Health Checks** - Application monitoring
+- 📊 **Inspector** - Development tools and debugging
+- 🐳 **Docker Support** - Containerized deployment
+- 📮 **Postman Collection** - Ready-to-use API tests
+
+## Quick Start
+
+1. **Install dependencies**
+   ```bash
+   npm install
+   ```
+
+2. **Configure environment**
+   ```bash
+   cp .env.example .env
+   # Add your OpenAI API key to .env
+   ```
+
+3. **Start development server**
+   ```bash
+   npm run dev
+   ```
+
+4. **Visit the application**
+   - App: http://localhost:3000
+   - Inspector: http://localhost:3000/__hazel
+   - Health: http://localhost:3000/health
+
+## Available Endpoints
+
+### AI Chat
+```bash
+curl -X POST http://localhost:3000/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message": "What is HazelJS?"}'
+```
+
+### AI Agent (with tools)
+```bash
+curl -X POST http://localhost:3000/agent \
+  -H "Content-Type: application/json" \
+  -d '{"message": "What is the weather in Tokyo?"}'
+```
+
+### RAG Document Ingestion
+```bash
+curl -X POST http://localhost:3000/rag/ingest \
+  -H "Content-Type: application/json" \
+  -d '{"content": "HazelJS is a TypeScript framework for AI-native backends"}'
+```
+
+### RAG Search
+```bash
+curl -X POST http://localhost:3000/rag/search \
+  -H "Content-Type: application/json" \
+  -d '{"query": "What is HazelJS?"}'
+```
+
+## Docker Deployment
+
+### Using Docker Compose (Recommended)
+
+1. **Configure environment**
+   ```bash
+   cp .env.example .env
+   # Add your OpenAI API key
+   ```
+
+2. **Start all services**
+   ```bash
+   docker-compose up -d
+   ```
+
+3. **View logs**
+   ```bash
+   docker-compose logs -f hazeljs-ai-app
+   ```
+
+4. **Stop services**
+   ```bash
+   docker-compose down
+   ```
+
+### Using Docker (Standalone)
+
+1. **Build the image**
+   ```bash
+   docker build -t hazeljs-ai-app .
+   ```
+
+2. **Run the container**
+   ```bash
+   docker run -p 3000:3000 --env-file .env hazeljs-ai-app
+   ```
+
+### Docker Services
+
+The `docker-compose.yml` includes:
+
+- **hazeljs-ai-app** - Main application (port 3000)
+- **redis** - Caching and queues (port 6379) 
+- **postgres** - Database with pgvector extension (port 5432)
+
+## API Testing with Postman
+
+1. **Import the collection**
+   ```bash
+   # Import HazelJS-AI-Native.postman_collection.json into Postman
+   ```
+
+2. **Set environment variable**
+   - Create a Postman environment
+   - Set `baseUrl` to `http://localhost:3000`
+
+3. **Test the endpoints**
+   - Health & Status - Check application health
+   - AI Chat - Test chat functionality
+   - AI Agent - Test agent with weather tools
+   - RAG - Test document ingestion and search
+
+```
+src/
+├── app.module.ts          # Main application module
+├── index.ts               # Application bootstrap
+├── health.controller.ts   # Health check endpoints
+├── ai/
+│   └── chat.controller.ts # AI chat service
+├── agent/
+│   └── agent.controller.ts # AI agent with tools
+└── rag/
+    └── rag.controller.ts  # RAG service
+
+prisma/
+├── schema.prisma          # Database schema with vector embeddings
+└── seed.ts               # Database seeding script
+
+docker/
+└── init-db.sql           # Database initialization (pgvector extension)
+
+HazelJS-AI-Native.postman_collection.json  # API tests
+Dockerfile                    # Container configuration
+docker-compose.yml           # Multi-service deployment
+```
+
+## Database Setup with Prisma
+
+This template uses Prisma for database management. Follow these steps to set up your database:
+
+### 1. Configure Database URL
+
+```bash
+# Add to your .env file
+DATABASE_URL="postgresql://hazeljs:hazeljs123@localhost:5432/hazeljs"
+```
+
+### 2. Initialize Database
+
+```bash
+# Generate Prisma client
+npm run db:generate
+
+# Push schema to database (for development)
+npm run db:push
+
+# Seed with sample data
+npm run db:seed
+```
+
+### 2.1 Vector Indexes
+
+The template uses the `pgvector/pgvector` Docker image which includes the vector extension. Prisma automatically handles the vector indexes when you run `db:push`. The schema includes:
+
+- **Vector embeddings** stored as `Float[]` for RAG search
+- **Full-text search index** on the `content` field  
+- **JSONB index** on the `metadata` field
+
+No manual SQL required - Prisma handles everything!
+
+### 3. Database Management
+
+```bash
+# View and edit data
+npm run db:studio
+
+# Reset database
+npm run db:reset
+
+# Generate client after schema changes
+npm run db:generate
+```
+
+### Database Schema
+
+The template includes:
+
+- **Documents** - RAG document storage with vector embeddings
+- **AgentConversations** - AI agent interaction history  
+- **ChatHistory** - AI chat session logs
+
+### Using Docker with Database
+
+```bash
+# Start PostgreSQL with Docker
+docker-compose up postgres -d
+
+# Run database setup
+npm run db:push
+npm run db:seed
+
+# Start the application
+npm run dev
+```
+
+## Environment Variables
+
+- `OPENAI_API_KEY` - Your OpenAI API key (required)
+- `PORT` - Server port (default: 3000)
+- `LOG_LEVEL` - Logging level (default: info)
+- `DATABASE_URL` - Database connection (optional, for PostgreSQL)
+- `REDIS_HOST` - Redis host (default: localhost)
+- `REDIS_PORT` - Redis port (default: 6379)
+
+## Development
+
+```bash
+# Development mode with hot reload
+npm run dev
+
+# Build for production
+npm run build
+
+# Start production server
+npm start
+
+# Run tests
+npm test
+
+# Lint code
+npm run lint
+
+# Format code
+npm run format
+```
+
+## Production Deployment
+
+### Environment Setup
+
+1. **Set production variables**
+   ```bash
+   export NODE_ENV=production
+   export OPENAI_API_KEY=your_production_key
+   export DATABASE_URL=postgresql://user:pass@host:5432/db
+   ```
+
+2. **Deploy with Docker**
+   ```bash
+   docker-compose -f docker-compose.yml up -d
+   ```
+
+3. **Monitor health**
+   ```bash
+   curl http://localhost:3000/health
+   ```
+
+### Scaling
+
+- **Horizontal scaling**: Deploy multiple instances behind a load balancer
+- **Database scaling**: Use managed PostgreSQL with connection pooling
+- **Caching**: Redis cluster for distributed caching
+- **Monitoring**: Add Prometheus/Grafana for metrics
+
+## Learn More
+
+- [HazelJS Documentation](https://hazeljs.ai/docs)
+- [HazelJS Playground](https://github.com/hazel-js/hazeljs-playground)
+- [AI Agents Guide](https://hazeljs.ai/docs/agents)
+- [RAG Guide](https://hazeljs.ai/docs/rag)
+- [Docker Guide](https://hazeljs.ai/docs/docker)

package/@template-ai-native/docker/enable-pgvector.sql

@@ -0,0 +1,6 @@
+-- Enable pgvector extension for vector similarity search
+CREATE EXTENSION IF NOT EXISTS vector;
+
+-- Create index for vector similarity search (cosine distance)
+-- This will be created after running prisma migrate
+CREATE INDEX IF NOT EXISTS documents_embedding_idx ON documents USING ivfflat (embedding vector_cosine_ops);

package/@template-ai-native/docker/init-db.sql

@@ -0,0 +1,8 @@
+-- Initialize database for HazelJS AI-Native application
+-- This script runs when the PostgreSQL container starts for the first time
+
+-- Enable pgvector extension for vector embeddings
+CREATE EXTENSION IF NOT EXISTS vector;
+
+-- Create vector index for similarity search (will be used by Prisma)
+-- This ensures the vector extension is ready when Prisma creates indexes

package/@template-ai-native/docker-compose.yml

@@ -0,0 +1,64 @@
+version: '3.8'
+
+services:
+  hazeljs-ai-app:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+      - PORT=3000
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - LOG_LEVEL=info
+    volumes:
+      - ./logs:/app/logshazeljs-playground/docker-compose.yml
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+
+  # Optional: Redis for caching and queue operations
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    command: redis-server --appendonly yes
+    volumes:
+      - redis_data:/data
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  # Optional: PostgreSQL for database operations
+  postgres:
+    image: pgvector/pgvector:pg15
+    ports:
+      - "5432:5432"
+    environment:
+      - POSTGRES_DB=hazeljs
+      - POSTGRES_USER=hazeljs
+      - POSTGRES_PASSWORD=hazeljs123
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+      - ./docker/init-db.sql:/docker-entrypoint-initdb.d/init-db.sql
+      - ./docker/enable-pgvector.sql:/docker-entrypoint-initdb.d/enable-pgvector.sql
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U hazeljs"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  redis_data:
+  postgres_data:
+
+networks:
+  default:
+    name: hazeljs-ai-network

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

@@ -0,0 +1,53 @@
+{
+  "name": "hazeljs-ai-native-app",
+  "version": "0.5.2",
+  "description": "A HazelJS AI-native application with agents, RAG, and chat",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "ts-node-dev --respawn --transpile-only src/index.ts",
+    "test": "jest",
+    "lint": "eslint \"src/**/*.ts\"",
+    "lint:fix": "eslint \"src/**/*.ts\" --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "db:generate": "prisma generate",
+    "db:push": "prisma db push",
+    "db:migrate": "prisma migrate dev",
+    "db:seed": "ts-node prisma/seed.ts",
+    "db:reset": "prisma migrate reset --force",
+    "db:studio": "prisma studio"
+  },
+  "prisma": {
+    "seed": "ts-node prisma/seed.ts"
+  },
+  "dependencies": {
+    "@hazeljs/core": "latest",
+    "@hazeljs/ai": "latest",
+    "@hazeljs/agent": "latest",
+    "@hazeljs/rag": "latest",
+    "@hazeljs/config": "latest",
+    "@hazeljs/cache": "latest",
+    "@hazeljs/inspector": "latest",
+    "@hazeljs/prisma": "latest",
+    "@prisma/client": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.18.2",
+    "@typescript-eslint/parser": "^8.18.2",
+    "eslint": "^8.56.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.1.3",
+    "jest": "^29.7.0",
+    "prettier": "^3.2.5",
+    "prisma": "^5.0.0",
+    "ts-jest": "^29.1.2",
+    "ts-node": "^10.9.0",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.3.3"
+  },
+  "author": "",
+  "license": "Apache-2.0"
+}

package/@template-ai-native/prisma/schema.prisma

@@ -0,0 +1,52 @@
+// This is your Prisma schema file,
+// learn more about it in the docs: https://pris.ly/d/prisma-schema
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model Document {
+  id        String   @id @default(cuid())
+  content   String
+  metadata  Json?
+  embedding Float[]  // Vector embedding for RAG
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@map("documents")
+  // Vector indexes will be created by Prisma when pgvector extension is available
+  @@index([content])   // Full-text search
+  @@index([metadata])  // JSONB search
+}
+
+model AgentConversation {
+  id           String   @id @default(cuid())
+  agentName    String   @map("agent_name")
+  sessionId    String?  @map("session_id")
+  userMessage  String?  @map("user_message")
+  agentResponse String? @map("agent_response")
+  metadata     Json?
+  createdAt    DateTime @default(now()) @map("created_at")
+
+  @@map("agent_conversations")
+  @@index([sessionId])
+  @@index([agentName])
+}
+
+model ChatHistory {
+  id          String   @id @default(cuid())
+  sessionId   String?  @map("session_id")
+  userMessage String?  @map("user_message")
+  aiResponse  String?  @map("ai_response")
+  model       String?
+  tokensUsed  Int?     @map("tokens_used")
+  createdAt   DateTime @default(now()) @map("created_at")
+
+  @@map("chat_history")
+  @@index([sessionId])
+}

package/@template-ai-native/prisma/seed.ts

@@ -0,0 +1,168 @@
+import { PrismaClient } from '@prisma/client';
+import { OpenAIEmbeddings } from '@hazeljs/rag';
+
+const prisma = new PrismaClient();
+
+async function main() {
+  console.log('🌱 Starting database seed...');
+
+  // Initialize OpenAI embeddings for sample documents
+  const embeddings = new OpenAIEmbeddings({
+    apiKey: process.env.OPENAI_API_KEY!,
+    model: 'text-embedding-3-small',
+  });
+
+  // Sample documents for RAG demonstration
+  const sampleDocuments = [
+    {
+      content: 'HazelJS is a TypeScript framework for building AI-native backend applications. It provides built-in support for AI agents, RAG (Retrieval-Augmented Generation), and seamless integration with LLM providers like OpenAI, Anthropic, and Ollama.',
+      metadata: {
+        source: 'documentation',
+        type: 'introduction',
+        category: 'framework',
+        tags: ['hazeljs', 'typescript', 'ai', 'backend'],
+      },
+    },
+    {
+      content: 'TypeScript decorators provide a way to add metadata and modify the behavior of classes, methods, and properties. In HazelJS, decorators like @Controller, @Get, @Post, @Service, and @Agent are used to define the application structure and routing.',
+      metadata: {
+        source: 'typescript-guide',
+        type: 'tutorial',
+        category: 'decorators',
+        tags: ['typescript', 'decorators', 'hazeljs', 'patterns'],
+      },
+    },
+    {
+      content: 'AI agents in HazelJS can use tools to perform actions like API calls, database queries, or external service integrations. The @Agent decorator defines an agent, and @Tool decorator defines its capabilities.',
+      metadata: {
+        source: 'agent-guide',
+        type: 'tutorial',
+        category: 'agents',
+        tags: ['agents', 'tools', 'ai', 'automation'],
+      },
+    },
+    {
+      content: 'RAG (Retrieval-Augmented Generation) combines document retrieval with LLM generation to provide more accurate and context-aware responses. HazelJS provides built-in RAG services with vector similarity search.',
+      metadata: {
+        source: 'rag-guide',
+        type: 'tutorial',
+        category: 'rag',
+        tags: ['rag', 'search', 'vectors', 'llm'],
+      },
+    },
+    {
+      content: 'The HazelJS Inspector is a development dashboard available at /__hazel that provides real-time insights into your application, including module dependencies, request metrics, and AI agent performance.',
+      metadata: {
+        source: 'development-guide',
+        type: 'tutorial',
+        category: 'tools',
+        tags: ['inspector', 'development', 'debugging', 'metrics'],
+      },
+    },
+  ];
+
+  console.log('📚 Creating sample documents...');
+  for (const doc of sampleDocuments) {
+    try {
+      // Generate embedding for the document
+      const embedding = await embeddings.embed(doc.content);
+      
+      // Create document with embedding
+      await prisma.document.create({
+        data: {
+          content: doc.content,
+          metadata: doc.metadata,
+          embedding: embedding,
+        },
+      });
+      
+      console.log(`✅ Created document: ${doc.metadata.source}`);
+    } catch (error) {
+      console.error(`❌ Failed to create document: ${doc.metadata.source}`, error);
+    }
+  }
+
+  // Sample agent conversations
+  console.log('🤖 Creating sample agent conversations...');
+  const sampleConversations = [
+    {
+      agentName: 'WeatherAgent',
+      sessionId: 'demo-session-1',
+      userMessage: 'What is the weather like in Tokyo?',
+      agentResponse: 'The weather in Tokyo is 72°F and sunny with 45% humidity.',
+      metadata: {
+        toolsUsed: ['getWeather'],
+        responseTime: 1.2,
+      },
+    },
+    {
+      agentName: 'WeatherAgent',
+      sessionId: 'demo-session-2',
+      userMessage: 'Tell me about the weather in New York and London',
+      agentResponse: 'New York: 65°F and cloudy. London: 58°F and rainy.',
+      metadata: {
+        toolsUsed: ['getWeather'],
+        responseTime: 2.1,
+      },
+    },
+  ];
+
+  for (const conv of sampleConversations) {
+    try {
+      await prisma.agentConversation.create({
+        data: conv,
+      });
+      console.log(`✅ Created conversation for ${conv.agentName}`);
+    } catch (error) {
+      console.error(`❌ Failed to create conversation`, error);
+    }
+  }
+
+  // Sample chat history
+  console.log('💬 Creating sample chat history...');
+  const sampleChatHistory = [
+    {
+      sessionId: 'chat-session-1',
+      userMessage: 'What is HazelJS?',
+      aiResponse: 'HazelJS is a TypeScript framework for building AI-native backend applications with built-in support for AI agents, RAG, and LLM integration.',
+      model: 'gpt-4',
+      tokensUsed: 156,
+    },
+    {
+      sessionId: 'chat-session-1',
+      userMessage: 'How do I create an AI agent?',
+      aiResponse: 'You can create an AI agent in HazelJS using the @Agent decorator and defining tools with @Tool decorator. Here\'s an example: @Agent({name: "MyAgent"}) class MyAgent { @Tool({description: "My tool"}) async myTool() { return "result"; } }',
+      model: 'gpt-4',
+      tokensUsed: 234,
+    },
+  ];
+
+  for (const chat of sampleChatHistory) {
+    try {
+      await prisma.chatHistory.create({
+        data: chat,
+      });
+      console.log(`✅ Created chat entry for session ${chat.sessionId}`);
+    } catch (error) {
+      console.error(`❌ Failed to create chat entry`, error);
+    }
+  }
+
+  console.log('🎉 Database seeding completed!');
+  console.log('');
+  console.log('📊 Summary:');
+  console.log(`   Documents: ${sampleDocuments.length}`);
+  console.log(`   Agent Conversations: ${sampleConversations.length}`);
+  console.log(`   Chat History: ${sampleChatHistory.length}`);
+  console.log('');
+  console.log('🚀 Your HazelJS AI-Native app is ready to use!');
+}
+
+main()
+  .catch((e) => {
+    console.error('❌ Seeding failed:', e);
+    process.exit(1);
+  })
+  .finally(async () => {
+    await prisma.$disconnect();
+  });