adonis-ai-kit 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IvanGlazyrin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,326 @@
-# Temporary Holding Version
+# adonis-ai
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Production-grade AI & Agentic workflow toolkit for AdonisJS 7**, powered by Vercel AI SDK v7, multi-provider cascading fallback, circuit breakers, tool security guardrails, token budget tracking, models.dev live catalog, and ACP (Agent Client Protocol) coding agents.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![npm](https://img.shields.io/npm/v/adonis-ai-kit.svg)](https://www.npmjs.com/package/adonis-ai-kit)
+[![AdonisJS](https://img.shields.io/badge/AdonisJS-7.x-5A45FF.svg)](https://adonisjs.com)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ES2022%20%2F%20NodeNext-blue.svg)](https://www.typescriptlang.org)
+[![Vercel AI SDK](https://img.shields.io/badge/Vercel%20AI%20SDK-v7.x-black.svg)](https://sdk.vercel.ai)
+[![Node](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org)
+
+---
+
+## Highlights & Architectural Comparison
+
+While frameworks like **Laravel AI** and **Prism** bring basic prompt-level abstractions to PHP, enterprise production systems require strict SRE resilience, tool execution guardrails, cost guarantees, and streaming protocol integrity. **`adonis-ai`** is built from the ground up for high-concurrency Node.js microservices:
+
+| Feature | `adonis-ai` (AdonisJS 7) | Laravel AI / Prism (PHP) |
+| :--- | :--- | :--- |
+| **Foundation Engine** | **Vercel AI SDK v7** (native Node.js async streams & tool calls) | Custom cURL/Guzzle wrappers |
+| **Circuit Breaker** | **Per `provider:model` key** (isolated half-open state, probe limits) | Global or none |
+| **Cascading Fallbacks** | **Safe**: never replays side-effects if tool calls already started | Retries from scratch (risk of double actions) |
+| **Tool Security (Guardrails)** | **Fail-closed** with Human-in-the-Loop (HITL), concurrent slots | Basic parameter mapping |
+| **Token Budget & Cost** | **Live USD pricing**, ring-buffer memory, cache-read & reasoning tokens | Raw token count or static tables |
+| **Catalog Auto-Discovery** | **models.dev integration** with TTL cache & atomic writes | Static configuration files |
+| **Agent Protocols** | **ACP (Agent Client Protocol)** for Claude Code, opencode & subagents | Basic prompt templates |
+| **HTTP Streaming** | **`response.streamAI()` macro** with heartbeats, SSE frames & client-abort hook | PHP chunked response buffers |
+
+---
+
+## Architecture Overview
+
+```mermaid
+flowchart TD
+    UserApp["AdonisJS Controller / Service"] --> AiManager["AiManager (Singleton Service)"]
+    
+    subgraph SRE_Resilience ["SRE Resilience & Fallback Layer"]
+        AiManager --> CircuitBreaker["Circuit Breaker (provider:model)"]
+        CircuitBreaker --> FallbackCascade["Cascading Provider Fallback"]
+    end
+    
+    subgraph Execution_Layer ["Execution & Agent Layer"]
+        FallbackCascade --> Providers["LLM Drivers (OpenAI, Anthropic, Google, Groq, ACP)"]
+        FallbackCascade --> AgentRunner["AgentRunner (Manifest + Skills)"]
+        AgentRunner --> ToolRegistry["Tool Registry (PolicyGuard)"]
+        ToolRegistry --> HITL["ConfirmationService (Human-in-the-Loop)"]
+    end
+
+    subgraph Observability_Cost ["Observability & Governance"]
+        Providers --> CostTracker["CostTracker (Ring Buffer)"]
+        Providers --> BudgetEnforcer["BudgetEnforcer (Atomic Reservations)"]
+        AiManager -.-> ModelsDev["models.dev Catalog (Live Pricing & Limits)"]
+    end
+
+    subgraph Transport_Layer ["Transport Layer"]
+        AiManager --> SSE["response.streamAI() Macro (SSE / Heartbeats / Abort)"]
+    end
+```
+
+---
+
+## Installation
+
+```bash
+npm install adonis-ai-kit
+# or
+pnpm add adonis-ai-kit
+```
+
+> Package name on npm is `adonis-ai-kit` (the `adonis-ai` name on npm is taken by another project).
+> The source repository is [github.com/IvanGlazyrin/adonis-ai-kit](https://github.com/IvanGlazyrin/adonis-ai-kit).
+
+Add the provider to `adonisrc.ts`:
+
+```ts
+export default defineConfig({
+  providers: [
+    // ...
+    () => import('adonis-ai-kit/providers/ai_provider')
+  ]
+})
+```
+
+Configure your providers in `config/ai.ts`:
+
+```ts
+import env from '#start/env'
+import { defineConfig } from 'adonis-ai-kit'
+
+export default defineConfig({
+  default: 'openai',
+  providers: {
+    openai: {
+      driver: 'openai',
+      apiKey: env.get('OPENAI_API_KEY'),
+      defaultModel: 'gpt-4o',
+    },
+    anthropic: {
+      driver: 'anthropic',
+      apiKey: env.get('ANTHROPIC_API_KEY'),
+      defaultModel: 'claude-3-7-sonnet-20250219',
+    },
+  },
+  // Automatically fallback to Anthropic if OpenAI is throttled (429) or down (5xx)
+  fallbackCascade: ['anthropic'],
+  circuitBreaker: {
+    failureThreshold: 5,
+    recoveryTimeoutMs: 30_000,
+    halfOpenMaxAttempts: 2,
+  },
+})
+```
+
+---
+
+## Core Capabilities
+
+### 1. Basic Generation & Multi-Provider Fallback
+
+Generate text with automatic token usage tracking and USD calculation:
+
+```ts
+import ai from 'adonis-ai-kit/services/main'
+
+const result = await ai.generateText({
+  prompt: 'Explain vector indexing in 3 sentences',
+})
+
+console.log(result.text)
+console.log(`Duration: ${result.durationMs}ms, Cost: $${result.costUsd}`)
+console.log(`Tokens: in=${result.usage.inputTokens}, out=${result.usage.outputTokens}, cached=${result.usage.cacheReadTokens}`)
+```
+
+If OpenAI returns `429 Rate Limit` or `503 Service Unavailable`, `adonis-ai` automatically routes the request to `anthropic` with its configured model, recording circuit breaker metrics.
+
+---
+
+### 2. Structured Output with Zod Schema
+
+```ts
+import { z } from 'zod'
+import ai from 'adonis-ai-kit/services/main'
+
+const resumeSchema = z.object({
+  fullName: z.string(),
+  skills: z.array(z.string()),
+  yearsOfExperience: z.number(),
+})
+
+const { object } = await ai.generateObject({
+  prompt: 'Extract candidate details: Ivan Glazyrin, 9 years in TS and Go',
+  schema: resumeSchema,
+})
+
+console.log(object.skills) // ['TypeScript', 'Go', ...]
+```
+
+---
+
+### 3. Server-Sent Events (SSE) Streaming in AdonisJS Controllers
+
+Use the built-in `response.streamAI()` macro:
+
+```ts
+import type { HttpContext } from '@adonisjs/core/http'
+import ai from 'adonis-ai-kit/services/main'
+
+export default class ChatController {
+  async stream({ request, response }: HttpContext) {
+    const stream = await ai.streamText({
+      prompt: request.input('message'),
+      model: 'gpt-4o',
+    })
+
+    // Sets 'Content-Type: text/event-stream', sends heartbeat pings,
+    // and automatically calls stream.abort() if the client disconnects!
+    return response.streamAI(stream, {
+      heartbeatMs: 15_000,
+      mode: 'sse',
+    })
+  }
+}
+```
+
+---
+
+### 4. Tool Security Guardrails & Human-in-the-Loop (HITL)
+
+Prevent untrusted AI models from executing destructive operations:
+
+```ts
+import { ToolRegistry, ConfirmationService, PolicyGuard } from 'adonis-ai-kit/guard'
+import { tool } from 'ai'
+import { z } from 'zod'
+
+const confirmationService = new ConfirmationService({ timeoutMs: 60_000 })
+const registry = new ToolRegistry(confirmationService)
+
+// Define tools
+registry.register(
+  'deploy_service',
+  tool({
+    description: 'Deploy service to cluster',
+    parameters: z.object({ cluster: z.string(), service: z.string() }),
+    execute: async ({ cluster, service }) => `Deployed ${service} to ${cluster}`,
+  }),
+  { permission: 'ask', maxCallsPerSession: 1 } // Requires human confirmation!
+)
+
+// When the model calls 'deploy_service', confirmationService pauses execution,
+// emits a confirmation request event, and resumes only when approved!
+```
+
+---
+
+### 5. Cost Tracking & Atomic Token Budget Enforcement
+
+```ts
+import { CostTracker, BudgetEnforcer } from 'adonis-ai-kit/budget'
+
+const tracker = new CostTracker({ maxRecords: 10_000 })
+const enforcer = new BudgetEnforcer({
+  maxCostUsd: 100.0,
+  maxInputTokens: 5_000_000,
+  maxOutputTokens: 1_000_000,
+})
+
+// Atomic pre-flight reservation prevents concurrent race conditions
+const reservation = enforcer.reserve('user-session-42', { estimatedCostUsd: 0.05 })
+if (!reservation.allowed) {
+  throw new Error('Budget exceeded')
+}
+
+try {
+  // run LLM request...
+  enforcer.settle(reservation.reservationId, { costUsd: 0.038 })
+} catch (e) {
+  enforcer.release(reservation.reservationId)
+}
+```
+
+---
+
+### 6. ACP (Agent Client Protocol) Coding Agents
+
+Run subagents using local CLI tools like **Claude Code**, **opencode**, or custom ACP binaries with sanitized environments:
+
+```ts
+import { AgentRunner, AgentLoader } from 'adonis-ai-kit/agents'
+
+const loader = new AgentLoader({
+  configsDir: './resources/agent-configs',
+  skillsDir: './resources/agent-skills',
+})
+
+const runner = new AgentRunner(aiManager, registry, loader)
+const execution = await runner.run({
+  agentId: 'code-reviewer',
+  userPrompt: 'Audit packages/adonis-ai for race conditions',
+})
+```
+
+---
+
+## Ace CLI Commands
+
+`adonis-ai` registers helpful Ace commands:
+
+```bash
+# Test connectivity, latency, and model availability across configured providers
+node ace ai:test
+
+# Scaffold a new production agent prompt and schema
+node ace make:ai-agent backend-architect --mode=primary
+```
+
+---
+
+## Testing & Quality
+
+The package includes a comprehensive regression test suite with 100% pass rate:
+
+```bash
+npm run test:regression
+```
+
+- **Token Budget**: Rate calculations, cache-read discounts, reasoning token surcharges, ring-buffer bounded memory.
+- **Tool Guard**: Policy enforcement (`allow`, `ask`, `deny`), concurrency slots, fail-closed handlers, session validation.
+- **Adonis AI Core**: Cascading failovers without duplicate side-effects, SSE keepalive frames, models.dev live discovery & TTL, ACP command sanitization.
+
+---
+
+## Development & Release
+
+```bash
+git clone https://github.com/IvanGlazyrin/adonis-ai-kit.git
+cd adonis-ai-kit
+npm install
+npm run build
+npm run test:regression
+```
+
+Consume the local build from an AdonisJS app without publishing:
+
+```bash
+# in the app
+npm install ../path/to/adonis-ai-kit   # file: dependency
+# or globally
+cd ../adonis-ai-kit && npm link
+cd ../my-app && npm link adonis-ai-kit
+```
+
+Releases are published to npm by pushing a version tag:
+
+```bash
+npm version patch            # bumps package.json + tag v1.1.1
+git push --follow-tags       # .github/workflows/release.yml runs npm publish
+```
+
+The workflow requires an `NPM_TOKEN` secret in the repository settings.
+
+---
+
+## License
+
+MIT © [Ivan Glazyrin](https://github.com/IvanGlazyrin) (glazrus97@gmail.com)

package/dist/commands/ai_test.d.ts

@@ -0,0 +1,12 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+import type { CommandOptions } from '@adonisjs/core/types/ace';
+export default class AiTestCommand extends BaseCommand {
+    static commandName: string;
+    static description: string;
+    static options: CommandOptions;
+    provider?: string;
+    model?: string;
+    testPrompt: string;
+    run(): Promise<void>;
+}
+//# sourceMappingURL=ai_test.d.ts.map

package/dist/commands/ai_test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai_test.d.ts","sourceRoot":"","sources":["../../commands/ai_test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAS,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAE9D,MAAM,CAAC,OAAO,OAAO,aAAc,SAAQ,WAAW;IACpD,MAAM,CAAC,WAAW,SAAY;IAC9B,MAAM,CAAC,WAAW,SAA4E;IAE9F,MAAM,CAAC,OAAO,EAAE,cAAc,CAE7B;IAGO,QAAQ,CAAC,EAAE,MAAM,CAAA;IAGjB,KAAK,CAAC,EAAE,MAAM,CAAA;IAOd,UAAU,EAAE,MAAM,CAAA;IAEpB,GAAG;CA4EV"}

package/dist/commands/ai_test.js

@@ -0,0 +1,98 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { BaseCommand, flags } from '@adonisjs/core/ace';
+export default class AiTestCommand extends BaseCommand {
+    static commandName = 'ai:test';
+    static description = 'Test connectivity, latency, and generation with configured AI providers';
+    static options = {
+        startApp: true,
+    };
+    async run() {
+        const ai = await this.app.container.make('ai');
+        this.ui.logger.info('🤖 Testing Adonis AI Provider Connectivity...\n');
+        const config = ai.getConfig();
+        const providersToTest = this.provider ? [this.provider] : Object.keys(config.providers);
+        if (providersToTest.length === 0) {
+            this.ui.logger.error('No AI providers configured in config/ai.ts!');
+            return;
+        }
+        const table = this.ui.table();
+        table.head(['Provider', 'Model', 'Status', 'Latency', 'Circuit Breaker', 'Cost ($)']);
+        for (const pName of providersToTest) {
+            const pConfig = config.providers[pName];
+            if (!pConfig) {
+                this.ui.logger.error(`Provider "${pName}" not found in config!`);
+                continue;
+            }
+            const testModel = this.model ?? pConfig.defaultModel ?? 'default';
+            const start = Date.now();
+            try {
+                const response = await ai.generateText({
+                    provider: pName,
+                    model: this.model,
+                    prompt: this.testPrompt || "Respond with PONG and your model identity in 10 words or less.",
+                    maxOutputTokens: 50,
+                    agentName: 'ace-ai-test',
+                });
+                const latency = Date.now() - start;
+                const stats = ai.getCircuitBreaker().getStats(`${response.provider}:${response.model}`);
+                // A fallback provider answering is NOT a pass for the provider under test
+                const answeredByFallback = response.provider !== pName;
+                table.row([
+                    this.colors.cyan(pName),
+                    response.model,
+                    answeredByFallback
+                        ? this.colors.yellow(`⚠ FALLBACK (${response.provider})`)
+                        : this.colors.green('✔ OK'),
+                    `${latency}ms`,
+                    this.colors.green(stats.state.toUpperCase()),
+                    response.costUsd !== undefined ? `$${response.costUsd.toFixed(6)}` : 'N/A',
+                ]);
+                this.ui.logger.info(`[${pName}] Output: "${response.text.trim()}"`);
+            }
+            catch (err) {
+                const latency = Date.now() - start;
+                const stats = ai.getCircuitBreaker().getStats(`${pName}:${testModel}`);
+                table.row([
+                    this.colors.cyan(pName),
+                    testModel,
+                    this.colors.red('✖ FAILED'),
+                    `${latency}ms`,
+                    this.colors.red(stats.state.toUpperCase()),
+                    'N/A',
+                ]);
+                this.ui.logger.error(`[${pName}] Error: ${err.message}`);
+            }
+        }
+        this.ui.logger.log('');
+        table.render();
+        this.ui.logger.log('');
+        const totalCost = ai.getCostTracker().getTotalCost();
+        const totalTokens = ai.getCostTracker().getTotalTokens();
+        this.ui.logger.info(`Total session cost: ${totalCost.toFixed(6)} | Tokens: ${totalTokens}`);
+    }
+}
+__decorate([
+    flags.string({ description: 'Specific provider to test (e.g. openai, anthropic, gemini, groq, ollama)' }),
+    __metadata("design:type", String)
+], AiTestCommand.prototype, "provider", void 0);
+__decorate([
+    flags.string({ description: 'Model to test with' }),
+    __metadata("design:type", String)
+], AiTestCommand.prototype, "model", void 0);
+__decorate([
+    flags.string({
+        name: 'prompt',
+        description: 'Test prompt to send',
+        default: 'Respond with "PONG" and your model identity in 10 words or less.',
+    }),
+    __metadata("design:type", String)
+], AiTestCommand.prototype, "testPrompt", void 0);
+//# sourceMappingURL=ai_test.js.map

package/dist/commands/ai_test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai_test.js","sourceRoot":"","sources":["../../commands/ai_test.ts"],"names":[],"mappings":"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"}

package/dist/commands/main.d.ts

@@ -0,0 +1,14 @@
+import type { CommandMetaData } from '@adonisjs/core/types/ace';
+import type { BaseCommand } from '@adonisjs/core/ace';
+type CommandClass = typeof BaseCommand;
+/**
+ * Ace command loader contract: returns metadata of every command in this package.
+ * Metadata is derived from the command classes themselves, so no generated `commands.json` is needed.
+ */
+export declare function getMetaData(): Promise<CommandMetaData[]>;
+/**
+ * Ace command loader contract: resolves the command class for the given metadata.
+ */
+export declare function getCommand(metaData: Pick<CommandMetaData, 'commandName'>): Promise<CommandClass | null>;
+export {};
+//# sourceMappingURL=main.d.ts.map

package/dist/commands/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../commands/main.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAErD,KAAK,YAAY,GAAG,OAAO,WAAW,CAAA;AActC;;;GAGG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC,CAM9D;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,IAAI,CAAC,eAAe,EAAE,aAAa,CAAC,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAG7G"}

package/dist/commands/main.js

@@ -0,0 +1,31 @@
+const loaders = [
+    () => import('./ai_test.js'),
+    () => import('./make_agent.js'),
+];
+let cachedMetaData;
+const cachedCommands = new Map();
+async function loadAll() {
+    return Promise.all(loaders.map(async (load) => (await load()).default));
+}
+/**
+ * Ace command loader contract: returns metadata of every command in this package.
+ * Metadata is derived from the command classes themselves, so no generated `commands.json` is needed.
+ */
+export async function getMetaData() {
+    if (cachedMetaData)
+        return cachedMetaData;
+    const commands = await loadAll();
+    for (const command of commands)
+        cachedCommands.set(command.commandName, command);
+    cachedMetaData = commands.map((command) => command.serialize());
+    return cachedMetaData;
+}
+/**
+ * Ace command loader contract: resolves the command class for the given metadata.
+ */
+export async function getCommand(metaData) {
+    if (cachedCommands.size === 0)
+        await getMetaData();
+    return cachedCommands.get(metaData.commandName) ?? null;
+}
+//# sourceMappingURL=main.js.map

package/dist/commands/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../commands/main.ts"],"names":[],"mappings":"AAKA,MAAM,OAAO,GAAoD;IAC/D,GAAG,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC;IAC5B,GAAG,EAAE,CAAC,MAAM,CAAC,iBAAiB,CAAC;CAChC,CAAA;AAED,IAAI,cAA6C,CAAA;AACjD,MAAM,cAAc,GAAG,IAAI,GAAG,EAAwB,CAAA;AAEtD,KAAK,UAAU,OAAO;IACpB,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAA;AACzE,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,IAAI,cAAc;QAAE,OAAO,cAAc,CAAA;IACzC,MAAM,QAAQ,GAAG,MAAM,OAAO,EAAE,CAAA;IAChC,KAAK,MAAM,OAAO,IAAI,QAAQ;QAAE,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;IAChF,cAAc,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAA;IAC/D,OAAO,cAAc,CAAA;AACvB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAA8C;IAC7E,IAAI,cAAc,CAAC,IAAI,KAAK,CAAC;QAAE,MAAM,WAAW,EAAE,CAAA;IAClD,OAAO,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,IAAI,CAAA;AACzD,CAAC"}

package/dist/commands/make_agent.d.ts

@@ -0,0 +1,13 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+import type { CommandOptions } from '@adonisjs/core/types/ace';
+export default class MakeAiAgentCommand extends BaseCommand {
+    static commandName: string;
+    static description: string;
+    static options: CommandOptions;
+    name: string;
+    provider: string;
+    model: string;
+    maxTokens: number;
+    run(): Promise<void>;
+}
+//# sourceMappingURL=make_agent.d.ts.map

package/dist/commands/make_agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make_agent.d.ts","sourceRoot":"","sources":["../../commands/make_agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAe,MAAM,oBAAoB,CAAA;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAI9D,MAAM,CAAC,OAAO,OAAO,kBAAmB,SAAQ,WAAW;IACzD,MAAM,CAAC,WAAW,SAAkB;IACpC,MAAM,CAAC,WAAW,SAAqD;IAEvE,MAAM,CAAC,OAAO,EAAE,cAAc,CAE7B;IAGO,IAAI,EAAE,MAAM,CAAA;IAGZ,QAAQ,EAAE,MAAM,CAAA;IAGhB,KAAK,EAAE,MAAM,CAAA;IAGb,SAAS,EAAE,MAAM,CAAA;IAEnB,GAAG;CAqFV"}

package/dist/commands/make_agent.js

@@ -0,0 +1,116 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { BaseCommand, args, flags } from '@adonisjs/core/ace';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+export default class MakeAiAgentCommand extends BaseCommand {
+    static commandName = 'make:ai-agent';
+    static description = 'Scaffold a production-grade typed AI Agent class';
+    static options = {
+        startApp: false,
+    };
+    async run() {
+        const rawName = this.name.replace(/Agent$/i, '');
+        const className = rawName.charAt(0).toUpperCase() + rawName.slice(1) + 'Agent';
+        const fileName = rawName.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase() + '_agent.ts';
+        const targetDir = path.join(this.app.makePath('app/ai/agents'));
+        await fs.mkdir(targetDir, { recursive: true });
+        const targetFile = path.join(targetDir, fileName);
+        const exists = await fs
+            .access(targetFile)
+            .then(() => true)
+            .catch(() => false);
+        if (exists) {
+            this.ui.logger.error(`Agent file already exists: ${targetFile}`);
+            return;
+        }
+        const template = `import ai from 'adonis-ai-kit/services/main'
+import type { GenerateTextResult, StreamTextResult } from 'adonis-ai-kit/types'
+
+export interface ${className}Input {
+  prompt: string
+  context?: Record<string, unknown>
+}
+
+/**
+ * ${className}
+ * Production-ready AI agent with token budgeting and structured execution.
+ */
+export class ${className} {
+  public readonly agentName = '${rawName.toLowerCase()}-agent'
+  public readonly defaultProvider = ${this.provider ? `'${this.provider}'` : 'undefined'}
+  public readonly defaultModel = ${this.model ? `'${this.model}'` : 'undefined'}
+  public readonly maxOutputTokens = ${this.maxTokens}
+
+  /**
+   * System prompt establishing role, instructions, and guardrails.
+   */
+  protected getSystemPrompt(): string {
+    return [
+      'You are ${className}, an expert AI assistant.',
+      'Provide concise, accurate, and actionable answers.',
+      'Always follow system security guidelines.',
+    ].join('\\n')
+  }
+
+  /**
+   * Executes synchronous text generation.
+   */
+  async run(input: ${className}Input): Promise<GenerateTextResult> {
+    return ai.generateText({
+      agentName: this.agentName,
+      provider: this.defaultProvider,
+      model: this.defaultModel,
+      maxOutputTokens: this.maxOutputTokens,
+      system: this.getSystemPrompt(),
+      prompt: input.prompt,
+      metadata: input.context,
+    })
+  }
+
+  /**
+   * Streams response in real time (e.g. for Server-Sent Events or WebSockets).
+   */
+  async stream(input: ${className}Input): Promise<StreamTextResult> {
+    return ai.streamText({
+      agentName: this.agentName,
+      provider: this.defaultProvider,
+      model: this.defaultModel,
+      maxOutputTokens: this.maxOutputTokens,
+      system: this.getSystemPrompt(),
+      prompt: input.prompt,
+      metadata: input.context,
+    })
+  }
+}
+
+export default new ${className}()
+`;
+        await fs.writeFile(targetFile, template.trim() + '\n', 'utf8');
+        this.ui.logger.success(`Created AI Agent: ${targetFile}`);
+    }
+}
+__decorate([
+    args.string({ description: 'Name of the AI Agent class (e.g. MarketAnalysis, SupportChat, Coder)' }),
+    __metadata("design:type", String)
+], MakeAiAgentCommand.prototype, "name", void 0);
+__decorate([
+    flags.string({ description: 'AI provider to use (default: app default)', default: '' }),
+    __metadata("design:type", String)
+], MakeAiAgentCommand.prototype, "provider", void 0);
+__decorate([
+    flags.string({ description: 'Model to use (e.g. gpt-4o, claude-3-7-sonnet-latest)', default: '' }),
+    __metadata("design:type", String)
+], MakeAiAgentCommand.prototype, "model", void 0);
+__decorate([
+    flags.number({ description: 'Max token budget per request', default: 2048 }),
+    __metadata("design:type", Number)
+], MakeAiAgentCommand.prototype, "maxTokens", void 0);
+//# sourceMappingURL=make_agent.js.map

package/dist/commands/make_agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"make_agent.js","sourceRoot":"","sources":["../../commands/make_agent.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAE7D,OAAO,EAAE,MAAM,kBAAkB,CAAA;AACjC,OAAO,IAAI,MAAM,WAAW,CAAA;AAE5B,MAAM,CAAC,OAAO,OAAO,kBAAmB,SAAQ,WAAW;IACzD,MAAM,CAAC,WAAW,GAAG,eAAe,CAAA;IACpC,MAAM,CAAC,WAAW,GAAG,kDAAkD,CAAA;IAEvE,MAAM,CAAC,OAAO,GAAmB;QAC/B,QAAQ,EAAE,KAAK;KAChB,CAAA;IAcD,KAAK,CAAC,GAAG;QACP,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAA;QAChD,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,OAAO,CAAA;QAC9E,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC,WAAW,EAAE,GAAG,WAAW,CAAA;QAE3F,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAA;QAC/D,MAAM,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;QAEjD,MAAM,MAAM,GAAG,MAAM,EAAE;aACpB,MAAM,CAAC,UAAU,CAAC;aAClB,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC;aAChB,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAA;QAErB,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,8BAA8B,UAAU,EAAE,CAAC,CAAA;YAChE,OAAM;QACR,CAAC;QAED,MAAM,QAAQ,GAAG;;;mBAGF,SAAS;;;;;;KAMvB,SAAS;;;eAGC,SAAS;iCACS,OAAO,CAAC,WAAW,EAAE;sCAChB,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,WAAW;mCACrD,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,WAAW;sCACzC,IAAI,CAAC,SAAS;;;;;;;iBAOnC,SAAS;;;;;;;;;qBASL,SAAS;;;;;;;;;;;;;;;wBAeN,SAAS;;;;;;;;;;;;;qBAaZ,SAAS;CAC7B,CAAA;QAEG,MAAM,EAAE,CAAC,SAAS,CAAC,UAAU,EAAE,QAAQ,CAAC,IAAI,EAAE,GAAG,IAAI,EAAE,MAAM,CAAC,CAAA;QAC9D,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,qBAAqB,UAAU,EAAE,CAAC,CAAA;IAC3D,CAAC;;AA/FO;IADP,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,sEAAsE,EAAE,CAAC;;gDACjF;AAGZ;IADP,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,2CAA2C,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;;oDAChE;AAGhB;IADP,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,sDAAsD,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;;iDAC9E;AAGb;IADP,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,8BAA8B,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;;qDACpD"}