@dewtech/dare-cli 3.11.0 → 3.12.0

package/skills/dare-llm-integration/providers/openai_provider.ts

@@ -0,0 +1,215 @@
+/**
+ * dare-llm-integration — OpenAIProvider
+ * Real implementation using fetch (no external SDK).
+ * License: MIT
+ */
+
+import type {
+  LLMProvider,
+  CompletionRequest,
+  CompletionResponse,
+  EmbedRequest,
+  EmbeddingResponse,
+} from '../types.js';
+import { LLMCache } from '../cache/llm_cache.js';
+import { TokenBucket } from '../rate_limit/token_bucket.js';
+
+export interface OpenAIProviderConfig {
+  apiKey: string;
+  cache?: LLMCache;
+  rateLimiter?: TokenBucket;
+  defaultCacheTtlMs?: number;
+  defaultTimeoutMs?: number;
+  onTokenUsage?: (model: string, input: number, output: number) => void;
+}
+
+export class OpenAIProvider implements LLMProvider {
+  private readonly apiKey: string;
+  private readonly cache: LLMCache | null;
+  private readonly rateLimiter: TokenBucket | null;
+  private readonly defaultCacheTtlMs: number;
+  private readonly defaultTimeoutMs: number;
+  private readonly onTokenUsage: ((model: string, input: number, output: number) => void) | null;
+
+  constructor(config: OpenAIProviderConfig) {
+    this.apiKey = config.apiKey;
+    this.cache = config.cache ?? null;
+    this.rateLimiter = config.rateLimiter ?? null;
+    this.defaultCacheTtlMs = config.defaultCacheTtlMs ?? 24 * 60 * 60 * 1000; // 24h
+    this.defaultTimeoutMs = config.defaultTimeoutMs ?? 30_000;
+    this.onTokenUsage = config.onTokenUsage ?? null;
+  }
+
+  async complete(request: CompletionRequest): Promise<CompletionResponse> {
+    const cacheKey = this.buildCacheKey('complete', request.model, request.prompt);
+
+    // Check cache
+    if (this.cache) {
+      const cached = this.cache.get(cacheKey);
+      if (cached) {
+        return cached.value as CompletionResponse;
+      }
+    }
+
+    // Rate limit
+    if (this.rateLimiter) {
+      await this.rateLimiter.acquire();
+    }
+
+    const start = Date.now();
+    const response = await this.callCompletionAPI(request);
+    const latencyMs = Date.now() - start;
+
+    const result: CompletionResponse = {
+      ...response,
+      cached: false,
+      latencyMs,
+    };
+
+    // Log token usage
+    if (this.onTokenUsage) {
+      this.onTokenUsage(request.model, result.tokensUsed.input, result.tokensUsed.output);
+    }
+
+    // Store in cache
+    if (this.cache) {
+      this.cache.set(cacheKey, result, this.defaultCacheTtlMs);
+    }
+
+    return result;
+  }
+
+  async embed(request: EmbedRequest): Promise<EmbeddingResponse> {
+    const inputStr = Array.isArray(request.input) ? request.input.join('|') : request.input;
+    const cacheKey = this.buildCacheKey('embed', request.model, inputStr);
+
+    if (this.cache) {
+      const cached = this.cache.get(cacheKey);
+      if (cached) {
+        return cached.value as EmbeddingResponse;
+      }
+    }
+
+    if (this.rateLimiter) {
+      await this.rateLimiter.acquire();
+    }
+
+    const result = await this.callEmbedAPI(request);
+
+    if (this.cache) {
+      this.cache.set(cacheKey, result, this.defaultCacheTtlMs);
+    }
+
+    return result;
+  }
+
+  private buildCacheKey(op: string, model: string, content: string): string {
+    // Deterministic hash-like key using a simple digest
+    const combined = `${op}:${model}:${content}`;
+    let hash = 0;
+    for (let i = 0; i < combined.length; i++) {
+      const char = combined.charCodeAt(i);
+      hash = ((hash << 5) - hash) + char;
+      hash |= 0;
+    }
+    return `llm:${op}:${model}:${Math.abs(hash).toString(16)}`;
+  }
+
+  private async callCompletionAPI(request: CompletionRequest): Promise<CompletionResponse> {
+    const timeoutMs = request.timeoutMs ?? this.defaultTimeoutMs;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+    const messages: Array<{ role: string; content: string }> = [];
+    if (request.systemPrompt) {
+      messages.push({ role: 'system', content: request.systemPrompt });
+    }
+    messages.push({ role: 'user', content: request.prompt });
+
+    let data: unknown;
+    try {
+      const response = await fetch('https://api.openai.com/v1/chat/completions', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${this.apiKey}`,
+        },
+        body: JSON.stringify({
+          model: request.model,
+          messages,
+          temperature: request.temperature ?? 0.7,
+          max_tokens: request.maxTokens,
+        }),
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        throw new Error(`OpenAI API error: ${response.status} ${response.statusText}`);
+      }
+
+      data = await response.json();
+    } finally {
+      clearTimeout(timer);
+    }
+
+    const d = data as {
+      choices: Array<{ message: { content: string } }>;
+      usage: { prompt_tokens: number; completion_tokens: number; total_tokens: number };
+      model: string;
+    };
+
+    return {
+      text: d.choices[0].message.content,
+      tokensUsed: {
+        input: d.usage.prompt_tokens,
+        output: d.usage.completion_tokens,
+        total: d.usage.total_tokens,
+      },
+      cached: false,
+      model: d.model,
+    };
+  }
+
+  private async callEmbedAPI(request: EmbedRequest): Promise<EmbeddingResponse> {
+    const timeoutMs = request.timeoutMs ?? this.defaultTimeoutMs;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+    let data: unknown;
+    try {
+      const response = await fetch('https://api.openai.com/v1/embeddings', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${this.apiKey}`,
+        },
+        body: JSON.stringify({
+          model: request.model,
+          input: request.input,
+        }),
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        throw new Error(`OpenAI API error: ${response.status} ${response.statusText}`);
+      }
+
+      data = await response.json();
+    } finally {
+      clearTimeout(timer);
+    }
+
+    const d = data as {
+      data: Array<{ embedding: number[] }>;
+      usage: { total_tokens: number };
+      model: string;
+    };
+
+    return {
+      embeddings: d.data.map((item) => item.embedding),
+      tokensUsed: d.usage.total_tokens,
+      model: d.model,
+      cached: false,
+    };
+  }
+}

package/skills/dare-llm-integration/rate_limit/token_bucket.ts

@@ -0,0 +1,86 @@
+/**
+ * dare-llm-integration — TokenBucket rate limiter
+ * Implements a sliding token bucket for controlling request rate.
+ * License: MIT
+ */
+
+export interface TokenBucketConfig {
+  /** Requests per second */
+  rps: number;
+  /** Maximum burst capacity. Defaults to rps. */
+  maxBurst?: number;
+}
+
+export class TokenBucket {
+  private readonly rps: number;
+  private readonly maxBurst: number;
+  /** Interval in milliseconds between tokens refilling */
+  private readonly refillIntervalMs: number;
+  private tokens: number;
+  private lastRefillTime: number;
+
+  constructor(config: TokenBucketConfig) {
+    if (config.rps <= 0) {
+      throw new Error('TokenBucket: rps must be > 0');
+    }
+    this.rps = config.rps;
+    this.maxBurst = config.maxBurst ?? config.rps;
+    this.refillIntervalMs = 1000 / config.rps;
+    this.tokens = this.maxBurst;
+    this.lastRefillTime = Date.now();
+  }
+
+  /**
+   * Blocking acquire: waits until a token is available, then consumes it.
+   */
+  async acquire(): Promise<void> {
+    while (!this.tryAcquire()) {
+      // Calculate wait time until next token
+      const now = Date.now();
+      const elapsed = now - this.lastRefillTime;
+      const waitMs = Math.max(1, this.refillIntervalMs - elapsed);
+      await delay(waitMs);
+    }
+  }
+
+  /**
+   * Non-blocking attempt: returns true if a token was consumed, false otherwise.
+   */
+  tryAcquire(): boolean {
+    this.refill();
+    if (this.tokens >= 1) {
+      this.tokens -= 1;
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Current available tokens (may be fractional after partial refill).
+   */
+  get availableTokens(): number {
+    this.refill();
+    return this.tokens;
+  }
+
+  /**
+   * Configured requests per second.
+   */
+  get requestsPerSecond(): number {
+    return this.rps;
+  }
+
+  private refill(): void {
+    const now = Date.now();
+    const elapsed = now - this.lastRefillTime;
+    if (elapsed > 0) {
+      const newTokens = (elapsed / 1000) * this.rps;
+      this.tokens = Math.min(this.tokens + newTokens, this.maxBurst);
+      this.lastRefillTime = now;
+    }
+  }
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/skills/dare-llm-integration/skill.yml

@@ -0,0 +1,23 @@
+name: dare-llm-integration
+version: 1.0.0
+license: MIT
+description: >
+  Skill transversal DARE para integração com LLMs (Large Language Models).
+  Fornece LLMProvider abstraction, caching em memória com TTL, rate limiting
+  via token bucket, prompt templates versionados e validação de output via JSON Schema.
+author: Dewtech Technologies
+metrics:
+  - id: M-01
+    description: 100% de chamadas LLM via LLMProvider injetado
+  - id: M-02
+    description: 100% de responses LLM cacheadas (cache configurado)
+  - id: M-03
+    description: 100% de requests LLM com rate limit configurado
+  - id: M-04
+    description: 100% de respostas LLM validadas contra schema antes usar
+antipatterns:
+  - AP-01: LLM SDK direto em Handler
+  - AP-02: Sem cache
+  - AP-03: Prompt em código
+  - AP-04: User input direto em prompt
+  - AP-05: Trusting LLM output sem validação

package/skills/dare-llm-integration/tests/fixtures/greet_v1.jinja2

@@ -0,0 +1 @@
+Hello {{ name }}, welcome to {{ service }}!

package/skills/dare-llm-integration/tests/fixtures/summarize_v1.jinja2

@@ -0,0 +1 @@
+Summarize the following text in 2-3 sentences: {{ text }}

package/skills/dare-llm-integration/tests/fixtures/summarize_v2.jinja2

@@ -0,0 +1,3 @@
+Write a concise summary (max {{ max_words }} words):
+
+{{ text }}