{"_id":"@awalsolution/adonis-ai","_rev":"4-34f3076006ddfaca9d0f54bb8f84a2b9","name":"@awalsolution/adonis-ai","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.0":{"name":"@awalsolution/adonis-ai","version":"1.0.0","keywords":["adonisjs","ai","openai","gemini"],"author":{"name":"Awal Solution Team"},"license":"MIT","_id":"@awalsolution/adonis-ai@1.0.0","maintainers":[{"name":"iqbalhassan","email":"iqbal.hassan2584@gmail.com"}],"c8":{"exclude":["tests/**"],"reporter":["text","html"]},"np":{"tag":"latest","branch":"main","message":"chore(release): %s","anyBranch":false},"dist":{"shasum":"0a55d225dbaced496e93a12bc70ad2d1d2261a2f","tarball":"https://registry.npmjs.org/@awalsolution/adonis-ai/-/adonis-ai-1.0.0.tgz","fileCount":24,"integrity":"sha512-lXKC71XDlV3XrQ05Pe25DvKzGdIl9L3nNtbNDtekO0fOHMvtLiAE4NgwjOyYBvxmsiSwfuNMnL+wdX081vzbUw==","signatures":[{"sig":"MEQCIFtHB0TQ6ZxaXrXGHcDX0CvWGfUcl/SznMxAJiHt9b2vAiABTWa/46bpkGHTy1itX0Bc6k7IcxzcQBsuHD3KwCg6Fw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":63871},"type":"module","engines":{"node":">=20.6.0"},"exports":{".":"./build/index.js","./types":"./build/src/types.js","./ai_provider":"./build/providers/ai_provider.js"},"gitHead":"1365990bc99fc1220ad11c27a7951aa1c4f005a2","scripts":{"lint":"eslint .","test":"c8 npm run quick:test","build":"tsc","clean":"del-cli build","format":"prettier --write .","pretest":"npm run lint","release":"np","version":"npm run build","prebuild":"npm run lint && npm run clean","postbuild":"npm run copy:templates","typecheck":"tsc --noEmit","quick:test":"node --import=./tsnode.esm.js --enable-source-maps bin/test.ts","copy:templates":"copyfiles \"stubs/**/**/*.stub\" build","prepublishOnly":"npm run build"},"_npmUser":{"name":"iqbalhassan","email":"iqbal.hassan2584@gmail.com"},"prettier":"@adonisjs/prettier-config","_npmVersion":"10.9.3","description":"AI integration package for AdonisJS v6 with OpenAI and Gemini support","directories":{},"_nodeVersion":"22.20.0","dependencies":{"openai":"^4.57.0","@google/generative-ai":"^0.17.1"},"publishConfig":{"tag":"latest","access":"public"},"_hasShrinkwrap":false,"devDependencies":{"c8":"^10.1.2","np":"^10.0.6","eslint":"^9.15.0","del-cli":"^5.1.0","prettier":"^3.3.2","@swc/core":"^1.6.3","copyfiles":"^2.4.1","typescript":"^5.4.5","@types/node":"^20.14.5","@japa/assert":"^3.0.0","@japa/runner":"^3.1.4","@adonisjs/core":"^6.12.0","@adonisjs/tsconfig":"^1.3.0","ts-node-maintained":"^10.9.4","@adonisjs/assembler":"^7.8.2","@adonisjs/eslint-config":"2.0.0-beta.7","@adonisjs/prettier-config":"^1.4.0"},"peerDependencies":{"@adonisjs/core":"^6.2.0"},"_npmOperationalInternal":{"tmp":"tmp/adonis-ai_1.0.0_1761472244784_0.47385003801687353","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@awalsolution/adonis-ai","version":"1.0.1","keywords":["adonisjs","ai","openai","gemini","adonis ai","adonis openai","adonis gemini","adonisjs ai","adonisjs openai","adonisjs gemini"],"author":{"name":"Awal Solution Team"},"license":"MIT","_id":"@awalsolution/adonis-ai@1.0.1","maintainers":[{"name":"iqbalhassan","email":"iqbal.hassan2584@gmail.com"}],"homepage":"https://github.com/awalsolution/adonis-ai#readme","bugs":{"url":"https://github.com/awalsolution/adonis-ai/issues"},"c8":{"exclude":["tests/**"],"reporter":["text","html"]},"np":{"tag":"latest","branch":"main","message":"chore(release): %s","anyBranch":false},"dist":{"shasum":"8cc8831378af6253433d3e304f2c85e9d57ba511","tarball":"https://registry.npmjs.org/@awalsolution/adonis-ai/-/adonis-ai-1.0.1.tgz","fileCount":36,"integrity":"sha512-GET6mSIuIyr2e0DlUtTR6aPf5xoOsxeHup592TR2BEmKyZXnfS8ZJYJ4ncmPf6XueZMl1rtPE84Jbm/kjd3QEQ==","signatures":[{"sig":"MEUCIF13qI+U1kHwevzlF4J88kziCmK+p558HRI8O9jLGHCJAiEAyBY9yS4VmA1pl7mz6L2X9W4sqVAKQAk2aenZ16h4mqo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":82998},"type":"module","engines":{"node":">=20.6.0"},"exports":{".":"./build/index.js","./types":"./build/src/types.js","./commands":"./build/commands/main.js","./ai_provider":"./build/providers/ai_provider.js","./services/main":"./build/services/main.js","./drivers/gemini":"./build/drivers/gemini/main.js","./drivers/openai":"./build/drivers/openai/main.js","./drivers/gemini/types":"./build/drivers/gemini/types.js","./drivers/openai/types":"./build/drivers/openai/types.js"},"gitHead":"e19a568dc12b8f9b71ca5eb59e19f619fafb0ece","scripts":{"lint":"eslint .","test":"c8 npm run quick:test","build":"tsc","clean":"del-cli build","format":"prettier --write .","pretest":"npm run lint","release":"np","version":"npm run build","prebuild":"npm run lint && npm run clean","postbuild":"npm run copy:templates","typecheck":"tsc --noEmit","quick:test":"node --import=./tsnode.esm.js --enable-source-maps bin/test.ts","copy:templates":"copyfiles \"stubs/**/**/*.stub\" build","prepublishOnly":"npm run build"},"_npmUser":{"name":"iqbalhassan","email":"iqbal.hassan2584@gmail.com"},"prettier":"@adonisjs/prettier-config","repository":{"url":"git+https://github.com/awalsolution/adonis-ai.git","type":"git"},"_npmVersion":"10.9.3","description":"AI integration package for AdonisJS v6 with OpenAI and Gemini support","directories":{},"_nodeVersion":"22.20.0","dependencies":{"openai":"^4.57.0","@google/generative-ai":"^0.17.1"},"publishConfig":{"tag":"latest","access":"public"},"_hasShrinkwrap":false,"devDependencies":{"c8":"^10.1.2","np":"^10.0.6","eslint":"^9.15.0","del-cli":"^5.1.0","prettier":"^3.3.2","@swc/core":"^1.6.3","copyfiles":"^2.4.1","typescript":"^5.4.5","@types/node":"^20.14.5","@japa/assert":"^3.0.0","@japa/runner":"^3.1.4","@adonisjs/core":"^6.12.0","@adonisjs/tsconfig":"^1.3.0","ts-node-maintained":"^10.9.4","@adonisjs/assembler":"^7.8.2","@adonisjs/eslint-config":"2.0.0-beta.7","@adonisjs/prettier-config":"^1.4.0"},"peerDependencies":{"@adonisjs/core":"^6.2.0"},"_npmOperationalInternal":{"tmp":"tmp/adonis-ai_1.0.1_1761473486345_0.4618005048100784","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@awalsolution/adonis-ai","version":"1.0.2","keywords":["adonisjs","ai","openai","gemini","adonis ai","adonis openai","adonis gemini","adonisjs ai","adonisjs openai","adonisjs gemini"],"author":{"name":"Awal Solution Team"},"license":"MIT","_id":"@awalsolution/adonis-ai@1.0.2","maintainers":[{"name":"iqbalhassan","email":"iqbal.hassan2584@gmail.com"}],"homepage":"https://github.com/awalsolution/adonis-ai#readme","bugs":{"url":"https://github.com/awalsolution/adonis-ai/issues"},"c8":{"exclude":["tests/**"],"reporter":["text","html"]},"np":{"tag":"latest","branch":"main","message":"chore(release): %s","anyBranch":false},"dist":{"shasum":"16f7501263908eecaf4fed6492741fcc120ce6ba","tarball":"https://registry.npmjs.org/@awalsolution/adonis-ai/-/adonis-ai-1.0.2.tgz","fileCount":36,"integrity":"sha512-0oarahk+PDMggEHOSaNJ54ybZxRi+ibtAWtpZVaqB+7RtsxY0LnZJtbRZhtW+OgUE/GBi/Yf8MOP0IlyFIx/fg==","signatures":[{"sig":"MEUCIQCco0DWp0whWu/l3sIsasLwkE7xdJkE2CDLET5s7t9j1QIgYSVYkXYpcGCazvzc5o7BBgYmObn66GcM3WjI4dfsdMM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":105938},"type":"module","engines":{"node":">=20.6.0"},"exports":{".":"./build/index.js","./types":"./build/src/types.js","./ai_provider":"./build/providers/ai_provider.js","./services/main":"./build/services/main.js","./drivers/gemini":"./build/drivers/gemini/main.js","./drivers/openai":"./build/drivers/openai/main.js","./drivers/gemini/types":"./build/drivers/gemini/types.js","./drivers/openai/types":"./build/drivers/openai/types.js"},"gitHead":"70019f2872683bcdf0d562011cc7725ac82bf8dc","scripts":{"lint":"eslint .","test":"c8 npm run quick:test","build":"tsc","clean":"del-cli build","format":"prettier --write .","pretest":"npm run lint","release":"np","version":"npm run build","prebuild":"npm run lint && npm run clean","postbuild":"npm run copy:templates","typecheck":"tsc --noEmit","quick:test":"node --import=./tsnode.esm.js --enable-source-maps bin/test.ts","copy:templates":"copyfiles \"stubs/**/**/*.stub\" build","prepublishOnly":"npm run build"},"_npmUser":{"name":"iqbalhassan","email":"iqbal.hassan2584@gmail.com"},"prettier":"@adonisjs/prettier-config","repository":{"url":"git+https://github.com/awalsolution/adonis-ai.git","type":"git"},"_npmVersion":"11.6.1","description":"AI integration package for AdonisJS v6 with OpenAI and Gemini support","directories":{},"_nodeVersion":"24.11.0","dependencies":{"openai":"^4.57.0","@google/generative-ai":"^0.17.1"},"publishConfig":{"tag":"latest","access":"public"},"_hasShrinkwrap":false,"devDependencies":{"c8":"^10.1.2","np":"^10.0.6","eslint":"^9.15.0","del-cli":"^5.1.0","prettier":"^3.3.2","@swc/core":"^1.6.3","copyfiles":"^2.4.1","typescript":"^5.4.5","@types/node":"^20.14.5","@japa/assert":"^3.0.0","@japa/runner":"^3.1.4","@adonisjs/core":"^6.12.0","@adonisjs/tsconfig":"^1.3.0","ts-node-maintained":"^10.9.4","@adonisjs/assembler":"^7.8.2","@adonisjs/eslint-config":"2.0.0-beta.7","@adonisjs/prettier-config":"^1.4.0"},"peerDependencies":{"@adonisjs/core":"^6.2.0"},"_npmOperationalInternal":{"tmp":"tmp/adonis-ai_1.0.2_1761680570138_0.18862638315347358","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@awalsolution/adonis-ai","description":"AI integration package for AdonisJS v6 with OpenAI and Gemini support","version":"1.0.3","engines":{"node":">=20.6.0"},"type":"module","exports":{".":"./build/index.js","./types":"./build/src/types.js","./ai_provider":"./build/providers/ai_provider.js","./services/main":"./build/services/main.js","./drivers/gemini":"./build/drivers/gemini/main.js","./drivers/gemini/types":"./build/drivers/gemini/types.js","./drivers/openai":"./build/drivers/openai/main.js","./drivers/openai/types":"./build/drivers/openai/types.js"},"scripts":{"clean":"del-cli build","copy:templates":"copyfiles \"stubs/**/**/*.stub\" build","typecheck":"tsc --noEmit","lint":"eslint .","format":"prettier --write .","quick:test":"node --import=./tsnode.esm.js --enable-source-maps bin/test.ts","pretest":"npm run lint","test":"c8 npm run quick:test","prebuild":"npm run lint && npm run clean","build":"tsc","postbuild":"npm run copy:templates","release":"np","version":"npm run build","prepublishOnly":"npm run build"},"keywords":["adonisjs","ai","openai","gemini","adonis ai","adonis openai","adonis gemini","adonisjs ai","adonisjs openai","adonisjs gemini"],"author":{"name":"Awal Solution Team"},"license":"MIT","devDependencies":{"@adonisjs/assembler":"^7.8.2","@adonisjs/core":"^6.12.0","@adonisjs/eslint-config":"2.0.0-beta.7","@adonisjs/prettier-config":"^1.4.0","@adonisjs/tsconfig":"^1.3.0","@japa/assert":"^3.0.0","@japa/runner":"^3.1.4","@swc/core":"^1.6.3","@types/node":"^20.14.5","c8":"^10.1.2","copyfiles":"^2.4.1","del-cli":"^5.1.0","eslint":"^9.15.0","np":"^10.0.6","prettier":"^3.3.2","ts-node-maintained":"^10.9.4","typescript":"^5.4.5"},"dependencies":{"openai":"^4.57.0","@google/generative-ai":"^0.17.1"},"peerDependencies":{"@adonisjs/core":"^6.2.0"},"homepage":"https://github.com/awalsolution/adonis-ai#readme","repository":{"type":"git","url":"git+https://github.com/awalsolution/adonis-ai.git"},"bugs":{"url":"https://github.com/awalsolution/adonis-ai/issues"},"publishConfig":{"access":"public","tag":"latest"},"np":{"message":"chore(release): %s","tag":"latest","branch":"main","anyBranch":false},"c8":{"reporter":["text","html"],"exclude":["tests/**"]},"prettier":"@adonisjs/prettier-config","gitHead":"fad180b3b492be3c574a7289f6d5bdf922c1aaab","_id":"@awalsolution/adonis-ai@1.0.3","_nodeVersion":"24.11.0","_npmVersion":"11.6.1","dist":{"integrity":"sha512-DKHIzu1ci+dSVS91pdgpu66bTVayfODetl8cdgiIAb9XZ1DZ9EvvKhKZ8cP7s5BozLyN+ahzmRtyCHPTmrVxWw==","shasum":"f44c5d30e57b55250c66ec790224717027910bc9","tarball":"https://registry.npmjs.org/@awalsolution/adonis-ai/-/adonis-ai-1.0.3.tgz","fileCount":36,"unpackedSize":110306,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDeW6O6BCbSIVS5j4NDWc7C5niCQJ+F23EFpGBD8kgGaQIhAMWa8GJ/lz7T1FRsaPA5UnQL2EaeW50wGA/63JP2Pewb"}]},"_npmUser":{"name":"iqbalhassan","email":"iqbal.hassan2584@gmail.com"},"directories":{},"maintainers":[{"name":"iqbalhassan","email":"iqbal.hassan2584@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/adonis-ai_1.0.3_1761715457538_0.6823469589545295"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-26T09:50:44.484Z","modified":"2025-10-29T05:24:17.925Z","1.0.0":"2025-10-26T09:50:45.007Z","1.0.1":"2025-10-26T10:11:26.559Z","1.0.2":"2025-10-28T19:42:50.380Z","1.0.3":"2025-10-29T05:24:17.721Z"},"bugs":{"url":"https://github.com/awalsolution/adonis-ai/issues"},"author":{"name":"Awal Solution Team"},"license":"MIT","homepage":"https://github.com/awalsolution/adonis-ai#readme","keywords":["adonisjs","ai","openai","gemini","adonis ai","adonis openai","adonis gemini","adonisjs ai","adonisjs openai","adonisjs gemini"],"repository":{"type":"git","url":"git+https://github.com/awalsolution/adonis-ai.git"},"description":"AI integration package for AdonisJS v6 with OpenAI and Gemini support","maintainers":[{"name":"iqbalhassan","email":"iqbal.hassan2584@gmail.com"}],"readme":"# @awalsolution/adonis-ai\n\n> **Powerful AI integration for AdonisJS v6 applications** - Connect to OpenAI and Google Gemini with a unified, easy-to-use interface.\n\n[![npm version](https://img.shields.io/npm/v/@awalsolution/adonis-ai.svg)](https://www.npmjs.com/package/@awalsolution/adonis-ai)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D20.6.0-brightgreen.svg)](https://nodejs.org/)\n\n---\n\n## 🚀 What is @awalsolution/adonis-ai?\n\nThis package brings AI capabilities to your AdonisJS applications with minimal setup. Whether you need to generate text, build chatbots, create embeddings for semantic search, or stream AI responses in real-time - we've got you covered!\n\n### Why Choose This Package?\n\n- **🎯 Simple API** - One unified interface for multiple AI providers\n- **🔌 Plug & Play** - Works seamlessly with AdonisJS v6\n- **⚡ Production Ready** - Built-in timeout, retry logic, and error handling\n- **🔄 Provider Agnostic** - Switch between OpenAI and Gemini without code changes\n- **💪 TypeScript First** - Full type safety and IntelliSense support\n- **🛡️ Robust** - Automatic retries, parallel processing, and input validation\n\n---\n\n## 🚀 Quick Start\n\n```typescript\n// 1. Install\nnpm install @awalsolution/adonis-ai\n\n// 2. Configure\nnode ace configure @awalsolution/adonis-ai\n\n// 3. Use in your code\nimport ai from '@awalsolution/adonis-ai/services/main'\n\n// Generate text (uses default driver from config)\nconst result = await ai.use().generate('Write a poem about TypeScript')\nconsole.log(result.text)\n\n// Chat with default driver\nconst chat = await ai.use().chat([\n  { role: 'user', content: 'Hello!' }\n])\n\n// Use specific provider\nconst openai = await ai.use('openai').generate('Hello from OpenAI')\nconst gemini = await ai.use('gemini').generate('Hello from Gemini')\n```\n\n---\n\n## 📦 Installation\n\n```bash\nnpm install @awalsolution/adonis-ai\n```\n\n### Configure the Package\n\nRun the interactive setup wizard:\n\n```bash\nnode ace configure @awalsolution/adonis-ai\n```\n\nThe wizard will:\n\n- ✅ Ask which AI providers you want to use (OpenAI, Gemini, or both)\n- ✅ Create the configuration file `config/ai.ts`\n- ✅ Set up environment variables in `.env`\n- ✅ Install required dependencies\n- ✅ Register the provider in your app\n\n**Quick setup with flags:**\n\n```bash\n# Install OpenAI and Gemini automatically\nnode ace configure @awalsolution/adonis-ai --services=openai,gemini --install\n```\n\n---\n\n## ⚙️ Configuration\n\n### Step 1: Environment Variables\n\nAdd your API keys to `.env`:\n\n```env\n# Choose your default AI provider\nAI_DRIVER=openai\n\n# Request settings (optional)\nAI_TIMEOUT=30000\nAI_MAX_RETRIES=3\n\n# OpenAI Settings\nOPENAI_API_KEY=sk-your-openai-api-key-here\nOPENAI_MODEL=gpt-3.5-turbo\nOPENAI_EMBEDDING_MODEL=text-embedding-ada-002\nOPENAI_MAX_TOKENS=1000\nOPENAI_TEMPERATURE=0.7\n\n# Google Gemini Settings\nGEMINI_API_KEY=your-gemini-api-key-here\nGEMINI_MODEL=gemini-pro\nGEMINI_EMBEDDING_MODEL=embedding-001\nGEMINI_MAX_TOKENS=1000\nGEMINI_TEMPERATURE=0.7\n```\n\n**Get your API keys:**\n\n- OpenAI: [https://platform.openai.com/api-keys](https://platform.openai.com/api-keys)\n- Google Gemini: [https://makersuite.google.com/app/apikey](https://makersuite.google.com/app/apikey)\n\n### Step 2: Configuration File\n\nThe package creates `config/ai.ts` automatically:\n\n```typescript\nimport env from '#start/env'\nimport { defineConfig, services } from '@awalsolution/adonis-ai'\n\nexport default defineConfig({\n  // Default provider to use\n  default: env.get('AI_DRIVER'),\n\n  // Timeout for API requests (milliseconds)\n  timeout: env.get('AI_TIMEOUT', 30000),\n\n  // Number of retry attempts on failure\n  maxRetries: env.get('AI_MAX_RETRIES', 3),\n\n  // Configure your AI services\n  services: {\n    openai: services.openai({\n      apiKey: env.get('OPENAI_API_KEY'),\n      model: env.get('OPENAI_MODEL'),\n      embeddingModel: env.get('OPENAI_EMBEDDING_MODEL', 'text-embedding-ada-002'),\n    }),\n\n    gemini: services.gemini({\n      apiKey: env.get('GEMINI_API_KEY'),\n      model: env.get('GEMINI_MODEL'),\n      embeddingModel: env.get('GEMINI_EMBEDDING_MODEL', 'embedding-001'),\n    }),\n  },\n})\n```\n\n---\n\n## 🎯 Usage Examples\n\n### Basic Text Generation\n\nGenerate text from a simple prompt:\n\n```typescript\nimport router from '@adonisjs/core/services/router'\nimport ai from '@awalsolution/adonis-ai/services/main'\n\nrouter.post('/generate', async ({ request, response }) => {\n  const prompt = request.input('prompt')\n  const result = await ai.use().generate(prompt)\n\n  return response.json({\n    text: result.text,\n    tokens: result.usage.tokens,\n  })\n})\n```\n\n**Example Request:**\n\n```bash\ncurl -X POST http://localhost:3333/generate \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"prompt\": \"Write a short poem about coding\"}'\n```\n\n---\n\n### Build a Chatbot\n\nCreate conversational AI with message history:\n\n```typescript\nimport ai from '@awalsolution/adonis-ai/services/main'\nimport type { HttpContext } from '@adonisjs/core/http'\n\nexport default class ChatController {\n  async chat({ request, response }: HttpContext) {\n    // Get conversation history from request\n    const messages = request.input('messages', [])\n\n    // Add user's new message\n    messages.push({\n      role: 'user',\n      content: request.input('message'),\n    })\n\n    // Get AI response\n    const result = await ai.use().chat(messages)\n\n    return response.json({\n      messages: result.messages, // Includes history + AI response\n      tokens: result.usage.tokens,\n    })\n  }\n}\n```\n\n**Example Request:**\n\n```bash\ncurl -X POST http://localhost:3333/chat \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"messages\": [\n      {\"role\": \"system\", \"content\": \"You are a helpful assistant\"},\n      {\"role\": \"user\", \"content\": \"What is AdonisJS?\"}\n    ],\n    \"message\": \"Tell me more about its features\"\n  }'\n```\n\n---\n\n### Generate Embeddings\n\nCreate vector embeddings for semantic search:\n\n```typescript\nimport ai from '@awalsolution/adonis-ai/services/main'\nimport type { HttpContext } from '@adonisjs/core/http'\n\nexport default class EmbeddingsController {\n  async embed({ request, response }: HttpContext) {\n    const texts = request.input('texts') // Array of strings\n    const result = await ai.use('openai').embed(texts)\n\n    return response.json({\n      embeddings: result.embeddings, // Array of number arrays\n      tokens: result.usage.tokens,\n    })\n  }\n\n  // Use a specific embedding model\n  async embedWithCustomModel({ request, response }: HttpContext) {\n    const texts = request.input('texts')\n\n    // Use newer OpenAI embedding model\n    const result = await ai.use('openai').embed(texts, {\n      model: 'text-embedding-3-large'\n    })\n\n    return response.json({ embeddings: result.embeddings })\n  }\n\n  // Search similar documents\n  async search({ request, response }: HttpContext) {\n    const query = request.input('query')\n\n    // Generate embedding for search query\n    const queryEmbedding = await ai.use('openai').embed(query)\n\n    // Use the embedding to search in your database\n    // (Requires vector database like PostgreSQL with pgvector)\n\n    return response.json({ embedding: queryEmbedding.embeddings[0] })\n  }\n}\n```\n\n**Available Embedding Models:**\n- **OpenAI**: `text-embedding-ada-002` (default), `text-embedding-3-small`, `text-embedding-3-large`\n- **Gemini**: `embedding-001` (default)\n\n---\n\n### Streaming Responses\n\nStream AI responses in real-time:\n\n```typescript\nimport ai from '@awalsolution/adonis-ai/services/main'\nimport type { HttpContext } from '@adonisjs/core/http'\n\nexport default class StreamController {\n  async stream({ request, response }: HttpContext) {\n    const prompt = request.input('prompt')\n\n    // Set up streaming response\n    response.header('Content-Type', 'text/event-stream')\n    response.header('Cache-Control', 'no-cache')\n    response.header('Connection', 'keep-alive')\n\n    // Get streaming result\n    const result = await ai.use().stream(prompt)\n\n    // Stream chunks to client\n    for await (const chunk of result.stream) {\n      response.stream.write(`data: ${JSON.stringify({ text: chunk })}\\n\\n`)\n    }\n\n    response.stream.end()\n  }\n}\n```\n\n**Frontend Example:**\n\n```javascript\nconst eventSource = new EventSource('/stream?prompt=Tell+me+a+story')\n\neventSource.onmessage = (event) => {\n  const data = JSON.parse(event.data)\n  console.log(data.text) // Each chunk of the response\n}\n```\n\n---\n\n## 🎨 Use Cases & Examples\n\n### 1. Content Generation\n\n```typescript\nimport ai from '@awalsolution/adonis-ai/services/main'\nimport type { HttpContext } from '@adonisjs/core/http'\n\n// Blog post generator\nasync generateBlogPost({ request }: HttpContext) {\n  const topic = request.input('topic')\n  const prompt = `Write a professional blog post about: ${topic}`\n\n  const result = await ai.use().generate(prompt, {\n    max_tokens: 2000,\n    temperature: 0.8, // More creative\n  })\n\n  return { content: result.text }\n}\n```\n\n### 2. Customer Support Bot\n\n```typescript\nimport ai from '@awalsolution/adonis-ai/services/main'\nimport type { HttpContext } from '@adonisjs/core/http'\n\n// Intelligent support assistant\nasync supportChat({ request, auth }: HttpContext) {\n  const messages = [\n    {\n      role: 'system',\n      content: 'You are a helpful customer support agent for our e-commerce platform.'\n    },\n    ...request.input('conversation'),\n  ]\n\n  const result = await ai.use('openai').chat(messages)\n\n  // Log conversation for quality assurance\n  await ConversationLog.create({\n    userId: auth.user.id,\n    messages: result.messages,\n  })\n\n  return result\n}\n```\n\n### 3. Document Analysis\n\n```typescript\nimport ai from '@awalsolution/adonis-ai/services/main'\nimport type { HttpContext } from '@adonisjs/core/http'\n\n// Analyze and summarize documents\nasync analyzeDocument({ request }: HttpContext) {\n  const document = request.input('document')\n  const prompt = `Analyze this document and provide:\n    1. Main topics\n    2. Key insights\n    3. Action items\n\n    Document: ${document}`\n\n  const result = await ai.use().generate(prompt)\n\n  return { analysis: result.text }\n}\n```\n\n### 4. Semantic Search\n\n```typescript\nimport ai from '@awalsolution/adonis-ai/services/main'\nimport db from '@adonisjs/lucid/services/db'\nimport type { HttpContext } from '@adonisjs/core/http'\n\n// Search with natural language\nasync semanticSearch({ request }: HttpContext) {\n  const searchQuery = request.input('query')\n\n  // Generate embedding for search query\n  const embedding = await ai.use('openai').embed(searchQuery)\n  const vector = embedding.embeddings[0]\n\n  // Search in vector database (PostgreSQL with pgvector)\n  const results = await db.rawQuery(`\n    SELECT id, title, content,\n           1 - (embedding <=> ?::vector) as similarity\n    FROM documents\n    ORDER BY embedding <=> ?::vector\n    LIMIT 10\n  `, [JSON.stringify(vector), JSON.stringify(vector)])\n\n  return results\n}\n```\n\n### 5. Language Translation\n\n```typescript\nimport ai from '@awalsolution/adonis-ai/services/main'\nimport type { HttpContext } from '@adonisjs/core/http'\n\n// Translate content\nasync translate({ request }: HttpContext) {\n  const text = request.input('text')\n  const targetLang = request.input('language')\n\n  const result = await ai.use().generate(\n    `Translate the following text to ${targetLang}: \"${text}\"`\n  )\n\n  return { translation: result.text }\n}\n```\n\n### 6. Code Assistant\n\n```typescript\nimport ai from '@awalsolution/adonis-ai/services/main'\nimport type { HttpContext } from '@adonisjs/core/http'\n\n// Help developers with code\nasync codeHelper({ request }: HttpContext) {\n  const code = request.input('code')\n  const task = request.input('task') // 'explain', 'optimize', 'debug'\n\n  const prompts = {\n    explain: `Explain what this code does:\\n\\`\\`\\`\\n${code}\\n\\`\\`\\``,\n    optimize: `Suggest optimizations for:\\n\\`\\`\\`\\n${code}\\n\\`\\`\\``,\n    debug: `Find potential bugs in:\\n\\`\\`\\`\\n${code}\\n\\`\\`\\``\n  }\n\n  const result = await ai.use().generate(prompts[task])\n\n  return { response: result.text }\n}\n```\n\n---\n\n## 🔄 Switching Between Providers\n\nUse specific providers or let the config decide:\n\n```typescript\nimport ai from '@awalsolution/adonis-ai/services/main'\n\n// Use default provider (from AI_DRIVER env)\nawait ai.use().generate('Hello')\n\n// Use specific provider\nawait ai.use('openai').generate('Hello from OpenAI')\nawait ai.use('gemini').generate('Hello from Gemini')\n```\n\n---\n\n## 🛡️ Error Handling\n\nThe package provides detailed error types for better debugging:\n\n```typescript\nimport ai from '@awalsolution/adonis-ai/services/main'\nimport { errors } from '@awalsolution/adonis-ai'\nimport type { HttpContext } from '@adonisjs/core/http'\n\nexport default class AIController {\n  async generate({ request, response }: HttpContext) {\n    try {\n      const result = await ai.use().generate(request.input('prompt'))\n      return result\n    } catch (error) {\n      if (error instanceof errors.AIApiKeyException) {\n        // API key is missing or invalid\n        return response.status(500).json({\n          error: 'AI service not configured properly',\n        })\n      }\n\n      if (error instanceof errors.AIRateLimitException) {\n        // Too many requests\n        return response.status(429).json({\n          error: 'Rate limit exceeded, please try again later',\n        })\n      }\n\n      if (error instanceof errors.AITimeoutException) {\n        // Request took too long\n        return response.status(408).json({\n          error: 'Request timeout, please try again',\n        })\n      }\n\n      if (error instanceof errors.AIServiceException) {\n        // General AI service error\n        return response.status(500).json({\n          error: 'AI service error: ' + error.message,\n        })\n      }\n\n      // Unknown error\n      throw error\n    }\n  }\n}\n```\n\n**Available Error Types:**\n\n- `AIApiKeyException` - Missing or invalid API keys\n- `AIDriverNotFoundException` - Requested provider not configured\n- `AIConfigurationException` - Invalid configuration or empty inputs\n- `AIServiceException` - General AI service errors\n- `AIRateLimitException` - Rate limit exceeded\n- `AITimeoutException` - Request timeout\n\n---\n\n## 🎛️ Advanced Configuration\n\n### Custom Timeout and Retries\n\n```typescript\n// In config/ai.ts\nexport default defineConfig({\n  default: 'openai',\n\n  // Wait up to 60 seconds for responses\n  timeout: 60000,\n\n  // Retry up to 5 times on failure\n  maxRetries: 5,\n\n  services: {\n    openai: services.openai({\n      apiKey: env.get('OPENAI_API_KEY'),\n      model: 'gpt-4', // Use GPT-4\n      timeout: 90000, // Override global timeout\n      maxRetries: 3, // Override global retries\n    }),\n  },\n})\n```\n\n### Per-Request Options\n\nOverride settings for individual requests:\n\n```typescript\nimport ai from '@awalsolution/adonis-ai/services/main'\n\n// Custom temperature and max tokens\nconst creative = await ai.use().generate('Write a poem', {\n  temperature: 0.9, // More creative\n  max_tokens: 500,\n})\n\nconst factual = await ai.use().generate('Explain quantum physics', {\n  temperature: 0.3, // More factual\n  max_tokens: 1000,\n})\n\n// Use different model for this request\nconst result = await ai.use('openai').generate('Hello', {\n  model: 'gpt-4-turbo-preview',\n  temperature: 0.7,\n})\n```\n\n### Using in Services\n\nUse the AI service in your application services:\n\n```typescript\nimport ai from '@awalsolution/adonis-ai/services/main'\n\nexport default class ArticleService {\n  async generateSummary(article: string) {\n    const result = await ai.use().generate(`Summarize this article: ${article}`)\n    return result.text\n  }\n\n  async suggestTags(content: string) {\n    const result = await ai.use().generate(`Suggest 5 relevant tags for: ${content}`)\n    return result.text.split(',').map((tag) => tag.trim())\n  }\n\n  async improveContent(content: string) {\n    const result = await ai\n      .use('openai')\n      .generate(`Improve this content for better readability: ${content}`)\n    return result.text\n  }\n}\n```\n\n### Model Flexibility\n\nThe package supports **any model** from OpenAI and Gemini - you're not limited to the documented ones!\n\n#### Configure Default Models\n\nSet your preferred models in `.env`:\n\n```env\n# Use any OpenAI model\nOPENAI_MODEL=gpt-4-turbo-preview\nOPENAI_EMBEDDING_MODEL=text-embedding-3-large\n\n# Use any Gemini model\nGEMINI_MODEL=gemini-pro-vision\nGEMINI_EMBEDDING_MODEL=embedding-001\n```\n\n#### Override Models Per Request\n\nUse different models for specific requests:\n\n```typescript\nimport ai from '@awalsolution/adonis-ai/services/main'\n\n// Use GPT-4 for complex reasoning\nconst analysis = await ai.use('openai').generate('Analyze this data...', {\n  model: 'gpt-4',\n  temperature: 0.3,\n})\n\n// Use GPT-3.5 Turbo for simple tasks\nconst summary = await ai.use('openai').generate('Summarize...', {\n  model: 'gpt-3.5-turbo',\n  temperature: 0.7,\n})\n\n// Use latest embedding models\nconst embeddings = await ai.use('openai').embed(texts, {\n  model: 'text-embedding-3-large',\n})\n```\n\n#### All Provider Options Supported\n\nThe `options` parameter passes through **all parameters** to the underlying SDK:\n\n**OpenAI Options:**\n- `model`, `temperature`, `max_tokens`, `top_p`, `frequency_penalty`, `presence_penalty`, `stop`, `n`, etc.\n- See [OpenAI API docs](https://platform.openai.com/docs/api-reference/chat/create)\n\n**Gemini Options:**\n- All parameters supported by Google's Generative AI SDK\n- See [Gemini API docs](https://ai.google.dev/api/rest)\n\n**Example with advanced options:**\n```typescript\nconst result = await ai.use('openai').generate('Write a story', {\n  model: 'gpt-4-turbo-preview',\n  temperature: 0.9,\n  max_tokens: 2000,\n  top_p: 0.95,\n  frequency_penalty: 0.5,\n  presence_penalty: 0.2,\n  stop: ['\\n\\n'],\n})\n```\n\n---\n\n## 📊 Response Structure\n\nAll AI operations return structured responses:\n\n### Text Generation Response\n\n```typescript\n{\n  text: string,              // Generated text\n  usage: {\n    tokens: number,          // Total tokens used\n    inputTokens?: number,    // Input tokens (prompt)\n    outputTokens?: number,   // Output tokens (response)\n  },\n  finishReason?: string,     // Why generation stopped\n  model?: string,            // Model used\n}\n```\n\n### Chat Response\n\n```typescript\n{\n  text: string,              // AI's response\n  messages: Array<{          // Full conversation history\n    role: 'user' | 'assistant' | 'system',\n    content: string,\n  }>,\n  usage: { tokens: number },\n  finishReason?: string,\n  model?: string,\n}\n```\n\n### Embedding Response\n\n```typescript\n{\n  embeddings: number[][],    // Array of vector embeddings\n  usage: { tokens: number },\n}\n```\n\n### Streaming Response\n\n```typescript\n{\n  text: string,              // Empty initially\n  stream: AsyncIterable<string>, // Chunks of text\n  usage: { tokens: number }, // Approximate\n}\n```\n\n---\n\n## 📚 Available Models\n\n### OpenAI Models\n\n| Model                      | Use Case                               | Cost |\n| -------------------------- | -------------------------------------- | ---- |\n| `gpt-4-turbo`              | Most capable, best for complex tasks   | $$$  |\n| `gpt-4o`                   | Optimized GPT-4, faster and cheaper    | $$   |\n| `gpt-4`                    | Very capable, good reasoning           | $$$  |\n| `gpt-3.5-turbo`            | Fast, cost-effective, recommended      | $    |\n| `text-embedding-3-large`   | Latest, best embedding quality         | $    |\n| `text-embedding-3-small`   | Faster, good quality embeddings        | $    |\n| `text-embedding-ada-002`   | Legacy embedding model                 | $    |\n\n### Google Gemini Models\n\n| Model               | Use Case                   | Cost |\n| ------------------- | -------------------------- | ---- |\n| `gemini-1.5-pro`    | Latest, best performance   | $$   |\n| `gemini-1.5-flash`  | Fast, cost-effective       | $    |\n| `gemini-pro`        | Text generation and chat   | $    |\n| `gemini-pro-vision` | Multimodal (text + images) | $$   |\n| `embedding-001`     | Embeddings                 | $    |\n\n---\n\n## 🔧 Troubleshooting\n\n### Common Issues\n\n**1. \"API key is missing or invalid\"**\n\n- Check your `.env` file has the correct API key\n- Ensure no extra spaces in the API key\n- Verify the key is active on the provider's dashboard\n\n**2. \"AI driver not found\"**\n\n- Make sure the provider is configured in `config/ai.ts`\n- Run `node ace configure @awalsolution/adonis-ai` again\n- Check that `AI_DRIVER` in `.env` matches a configured service\n\n**3. \"Request timeout\"**\n\n- Increase timeout in config: `timeout: 60000`\n- Check your internet connection\n- Try a simpler prompt to test\n\n**4. \"Rate limit exceeded\"**\n\n- Wait a few minutes before retrying\n- Consider upgrading your API plan\n- Implement request queuing in your app\n\n**5. Empty or undefined responses**\n\n- Check that your prompt is not empty\n- Verify the model supports your request type\n- Look at the `finishReason` in the response\n\n### Debug Mode\n\nEnable debug logging:\n\n```bash\n# In your .env\nNODE_DEBUG=adonis:ai\n```\n\n---\n\n## 🚀 Performance Tips\n\n1. **Cache Responses** - Store common AI responses in Redis\n2. **Use Queues** - Process AI requests in background jobs\n3. **Set Reasonable Limits** - Use `max_tokens` to control costs\n4. **Implement Rate Limiting** - Protect your API keys\n5. **Choose Right Model** - Use GPT-3.5 for speed, GPT-4 for quality\n6. **Parallel Processing** - Batch multiple independent requests\n7. **Stream Long Responses** - Better UX for lengthy generations\n\n```typescript\n// Example: Cache with Redis\nimport redis from '@adonisjs/redis/services/main'\nimport ai from '@awalsolution/adonis-ai/services/main'\n\nconst cacheKey = `ai:summary:${articleId}`\nlet summary = await redis.get(cacheKey)\n\nif (!summary) {\n  const result = await ai.use().generate(`Summarize: ${article}`)\n  summary = result.text\n\n  await redis.setex(cacheKey, 3600, summary) // Cache 1 hour\n}\n\nreturn { summary }\n```\n\n---\n\n## 🔒 Security Best Practices\n\n1. **Never expose API keys** - Keep them in `.env`, never commit\n2. **Validate user inputs** - Sanitize prompts before sending to AI\n3. **Rate limit endpoints** - Prevent abuse of your AI endpoints\n4. **Monitor usage** - Track tokens to avoid unexpected costs\n5. **Implement authentication** - Protect AI endpoints with auth\n6. **Content filtering** - Check for inappropriate content\n7. **Log responsibly** - Don't log sensitive user data\n\n```typescript\n// Example: Rate limiting AI endpoints\nimport { throttle } from '@adonisjs/limiter'\n\nrouter.post('/generate', [\n  throttle({\n    key: (ctx) => ctx.auth.user.id,\n    max: 10, // 10 requests\n    duration: '1 minute',\n  }),\n  async ({ request }) => {\n    // Your AI logic\n  },\n])\n```\n\n---\n\n## 📖 Additional Resources\n\n- **OpenAI Documentation**: [https://platform.openai.com/docs](https://platform.openai.com/docs)\n- **Google Gemini Docs**: [https://ai.google.dev/docs](https://ai.google.dev/docs)\n- **AdonisJS Docs**: [https://docs.adonisjs.com](https://docs.adonisjs.com)\n- **Package Repository**: [https://github.com/awalsolution/adonis-ai](https://github.com/awalsolution/adonis-ai)\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how:\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Commit changes: `git commit -m 'Add amazing feature'`\n4. Push to branch: `git push origin feature/amazing-feature`\n5. Open a Pull Request\n\n---\n\n## 📄 License\n\nMIT License - see [LICENSE.md](LICENSE.md)\n\n---\n\n## 💬 Support\n\nNeed help? Have questions?\n\n- 📧 **Email**: support@awalsolution.com\n- 🐛 **Issues**: [GitHub Issues](https://github.com/awalsolution/adonis-ai/issues)\n- 💬 **Discussions**: [GitHub Discussions](https://github.com/awalsolution/adonis-ai/discussions)\n\n---\n\n## ⭐ Show Your Support\n\nIf this package helps you build amazing AI-powered applications, please give it a star on GitHub! ⭐\n\n---\n\nMade with ❤️ by [Awal Solution Team](https://awalsolution.com)\n","readmeFilename":"README.md"}