@dewtech/dare-cli 3.11.0 → 3.13.0

package/skills/dare-llm-integration/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@dewtech/dare-llm-integration",
+  "version": "1.0.0",
+  "description": "dare-llm-integration — LLM integration patterns skill for DARE Method v3.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "skill.yml"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.41",
+    "typescript": "^5.9.3",
+    "vitest": "^1.6.1"
+  },
+  "keywords": [
+    "dare",
+    "dare-method",
+    "dare-llm-integration",
+    "llm",
+    "openai",
+    "anthropic",
+    "caching",
+    "rate-limit"
+  ],
+  "author": "Dewtech Technologies",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dewtech-technologies/dare-method.git",
+    "directory": "packages/skills/dare-llm-integration"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/skills/dare-llm-integration/prompts/prompt_loader.ts

@@ -0,0 +1,258 @@
+/**
+ * dare-llm-integration — PromptLoader
+ * Loads and renders versioned Jinja2 prompt templates.
+ * Uses the same token-based engine as dare-ax/generator.ts.
+ * License: MIT
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+export interface PromptLoaderConfig {
+  /** Directory where .jinja2 template files live. */
+  templatesDir: string;
+}
+
+type Token =
+  | { type: 'text'; value: string }
+  | { type: 'var'; name: string }
+  | { type: 'for'; varName: string; listName: string }
+  | { type: 'endfor' }
+  | { type: 'if'; condName: string }
+  | { type: 'else' }
+  | { type: 'endif' };
+
+export class PromptLoader {
+  private readonly templatesDir: string;
+  private readonly templateCache: Map<string, string> = new Map();
+
+  constructor(config: PromptLoaderConfig) {
+    this.templatesDir = config.templatesDir;
+  }
+
+  /**
+   * Load and render a versioned template.
+   * File resolved as: <templatesDir>/<name>_<version>.jinja2
+   *
+   * @param name    - Template name, e.g. "summarize"
+   * @param version - Version string, e.g. "v1"
+   * @param vars    - Variables to interpolate into the template
+   * @returns Rendered prompt string
+   */
+  load(name: string, version: string, vars: Record<string, string>): string {
+    const filename = `${name}_${version}.jinja2`;
+    const filepath = path.join(this.templatesDir, filename);
+
+    let content = this.templateCache.get(filepath);
+    if (!content) {
+      if (!fs.existsSync(filepath)) {
+        throw new Error(`PromptLoader: template not found: ${filepath}`);
+      }
+      content = fs.readFileSync(filepath, 'utf-8');
+      this.templateCache.set(filepath, content);
+    }
+
+    return renderTemplate(content, vars);
+  }
+
+  /**
+   * Render a template string directly (without reading a file).
+   */
+  render(templateContent: string, vars: Record<string, string>): string {
+    return renderTemplate(templateContent, vars);
+  }
+
+  /**
+   * List all available template names and versions in the templates directory.
+   */
+  listTemplates(): Array<{ name: string; version: string; filename: string }> {
+    if (!fs.existsSync(this.templatesDir)) return [];
+
+    return fs
+      .readdirSync(this.templatesDir)
+      .filter((f) => f.endsWith('.jinja2'))
+      .map((filename) => {
+        const base = filename.replace('.jinja2', '');
+        const lastUnderscore = base.lastIndexOf('_');
+        if (lastUnderscore < 0) return null;
+        return {
+          name: base.slice(0, lastUnderscore),
+          version: base.slice(lastUnderscore + 1),
+          filename,
+        };
+      })
+      .filter((x): x is { name: string; version: string; filename: string } => x !== null);
+  }
+
+  /**
+   * Clear the template file cache (useful in tests).
+   */
+  clearCache(): void {
+    this.templateCache.clear();
+  }
+}
+
+// --- Jinja2-style template engine (same logic as dare-ax/generator.ts) ---
+
+function renderTemplate(content: string, vars: Record<string, unknown>): string {
+  const tokens = tokenize(content);
+  return evaluate(tokens, vars, 0).output;
+}
+
+function tokenize(template: string): Token[] {
+  const tokens: Token[] = [];
+  let pos = 0;
+
+  while (pos < template.length) {
+    const varStart = template.indexOf('{{', pos);
+    const tagStart = template.indexOf('{%', pos);
+
+    let next: number;
+    let isVar: boolean;
+
+    if (varStart === -1 && tagStart === -1) {
+      tokens.push({ type: 'text', value: template.slice(pos) });
+      break;
+    } else if (varStart === -1) {
+      next = tagStart;
+      isVar = false;
+    } else if (tagStart === -1) {
+      next = varStart;
+      isVar = true;
+    } else {
+      next = Math.min(varStart, tagStart);
+      isVar = varStart < tagStart;
+    }
+
+    if (next > pos) {
+      tokens.push({ type: 'text', value: template.slice(pos, next) });
+    }
+
+    if (isVar) {
+      const end = template.indexOf('}}', next + 2);
+      if (end === -1) {
+        tokens.push({ type: 'text', value: template.slice(next) });
+        break;
+      }
+      const name = template.slice(next + 2, end).trim();
+      tokens.push({ type: 'var', name });
+      pos = end + 2;
+    } else {
+      const end = template.indexOf('%}', next + 2);
+      if (end === -1) {
+        tokens.push({ type: 'text', value: template.slice(next) });
+        break;
+      }
+      const inner = template.slice(next + 2, end).trim();
+      pos = end + 2;
+
+      if (inner.startsWith('for ')) {
+        const m = /^for\s+(\w+)\s+in\s+([\w.]+)$/.exec(inner);
+        if (m) tokens.push({ type: 'for', varName: m[1], listName: m[2] });
+      } else if (inner === 'endfor') {
+        tokens.push({ type: 'endfor' });
+      } else if (inner.startsWith('if ')) {
+        tokens.push({ type: 'if', condName: inner.slice(3).trim() });
+      } else if (inner === 'else') {
+        tokens.push({ type: 'else' });
+      } else if (inner === 'endif') {
+        tokens.push({ type: 'endif' });
+      }
+    }
+  }
+
+  return tokens;
+}
+
+function evaluate(
+  tokens: Token[],
+  context: Record<string, unknown>,
+  startIdx: number
+): { output: string; nextIdx: number } {
+  let output = '';
+  let i = startIdx;
+
+  while (i < tokens.length) {
+    const token = tokens[i];
+
+    if (token.type === 'text') {
+      output += token.value;
+      i++;
+    } else if (token.type === 'var') {
+      const val = getNestedValue(context, token.name);
+      if (val !== undefined && val !== null) output += String(val);
+      i++;
+    } else if (token.type === 'for') {
+      const bodyStart = i + 1;
+      let depth = 1;
+      let j = bodyStart;
+      while (j < tokens.length && depth > 0) {
+        if (tokens[j].type === 'for') depth++;
+        if (tokens[j].type === 'endfor') depth--;
+        if (depth > 0) j++;
+        else break;
+      }
+      const bodyTokens = tokens.slice(bodyStart, j);
+      const list = getNestedValue(context, token.listName);
+      if (Array.isArray(list)) {
+        for (const item of list) {
+          const itemCtx: Record<string, unknown> = { ...context };
+          if (typeof item === 'object' && item !== null) {
+            itemCtx[token.varName] = item;
+            for (const [k, v] of Object.entries(item as Record<string, unknown>)) {
+              itemCtx[`${token.varName}.${k}`] = v;
+            }
+          } else {
+            itemCtx[token.varName] = item;
+          }
+          output += evaluate(bodyTokens, itemCtx, 0).output;
+        }
+      }
+      i = j + 1;
+    } else if (token.type === 'if') {
+      const bodyStart = i + 1;
+      let depth = 1;
+      let j = bodyStart;
+      let elseIdx = -1;
+      while (j < tokens.length && depth > 0) {
+        if (tokens[j].type === 'if') depth++;
+        if (tokens[j].type === 'endif') depth--;
+        if (depth === 1 && tokens[j].type === 'else') elseIdx = j;
+        if (depth > 0) j++;
+        else break;
+      }
+      const endifIdx = j;
+      const thenTokens = elseIdx >= 0 ? tokens.slice(bodyStart, elseIdx) : tokens.slice(bodyStart, endifIdx);
+      const elseTokens = elseIdx >= 0 ? tokens.slice(elseIdx + 1, endifIdx) : [];
+      const condValue = getNestedValue(context, token.condName);
+      if (isTruthy(condValue)) {
+        output += evaluate(thenTokens, context, 0).output;
+      } else {
+        output += evaluate(elseTokens, context, 0).output;
+      }
+      i = endifIdx + 1;
+    } else if (token.type === 'else' || token.type === 'endif' || token.type === 'endfor') {
+      break;
+    } else {
+      i++;
+    }
+  }
+
+  return { output, nextIdx: i };
+}
+
+function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+  return path.split('.').reduce((current: unknown, key: string) => {
+    if (current !== null && typeof current === 'object') {
+      return (current as Record<string, unknown>)[key];
+    }
+    return undefined;
+  }, obj as unknown);
+}
+
+function isTruthy(value: unknown): boolean {
+  if (Array.isArray(value)) return value.length > 0;
+  if (value === null || value === undefined) return false;
+  if (typeof value === 'string') return value.length > 0;
+  return Boolean(value);
+}

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

@@ -0,0 +1,159 @@
+/**
+ * dare-llm-integration — AnthropicProvider
+ * Calls Anthropic Messages API 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 AnthropicProviderConfig {
+  apiKey: string;
+  cache?: LLMCache;
+  rateLimiter?: TokenBucket;
+  defaultCacheTtlMs?: number;
+  defaultTimeoutMs?: number;
+  anthropicVersion?: string;
+  onTokenUsage?: (model: string, input: number, output: number) => void;
+}
+
+export class AnthropicProvider 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 anthropicVersion: string;
+  private readonly onTokenUsage: ((model: string, input: number, output: number) => void) | null;
+
+  constructor(config: AnthropicProviderConfig) {
+    this.apiKey = config.apiKey;
+    this.cache = config.cache ?? null;
+    this.rateLimiter = config.rateLimiter ?? null;
+    this.defaultCacheTtlMs = config.defaultCacheTtlMs ?? 24 * 60 * 60 * 1000;
+    this.defaultTimeoutMs = config.defaultTimeoutMs ?? 30_000;
+    this.anthropicVersion = config.anthropicVersion ?? '2023-06-01';
+    this.onTokenUsage = config.onTokenUsage ?? null;
+  }
+
+  async complete(request: CompletionRequest): Promise<CompletionResponse> {
+    const cacheKey = this.buildCacheKey('complete', request.model, request.prompt);
+
+    if (this.cache) {
+      const cached = this.cache.get(cacheKey);
+      if (cached) {
+        return cached.value as CompletionResponse;
+      }
+    }
+
+    if (this.rateLimiter) {
+      await this.rateLimiter.acquire();
+    }
+
+    const start = Date.now();
+    const result = await this.callMessagesAPI(request);
+    const latencyMs = Date.now() - start;
+
+    const response: CompletionResponse = { ...result, cached: false, latencyMs };
+
+    if (this.onTokenUsage) {
+      this.onTokenUsage(request.model, response.tokensUsed.input, response.tokensUsed.output);
+    }
+
+    if (this.cache) {
+      this.cache.set(cacheKey, response, this.defaultCacheTtlMs);
+    }
+
+    return response;
+  }
+
+  async embed(_request: EmbedRequest): Promise<EmbeddingResponse> {
+    // Anthropic does not provide an embeddings API (as of v1.0).
+    // Return empty embeddings to satisfy interface; callers should use OpenAI for embeddings.
+    throw new Error(
+      'AnthropicProvider: embed() is not supported. Use OpenAIProvider for embeddings.'
+    );
+  }
+
+  private buildCacheKey(op: string, model: string, content: string): string {
+    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:anthropic:${op}:${model}:${Math.abs(hash).toString(16)}`;
+  }
+
+  private async callMessagesAPI(request: CompletionRequest): Promise<CompletionResponse> {
+    const timeoutMs = request.timeoutMs ?? this.defaultTimeoutMs;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+    let data: unknown;
+    try {
+      const body: Record<string, unknown> = {
+        model: request.model,
+        max_tokens: request.maxTokens ?? 1024,
+        messages: [{ role: 'user', content: request.prompt }],
+      };
+
+      if (request.systemPrompt) {
+        body['system'] = request.systemPrompt;
+      }
+
+      if (request.temperature !== undefined) {
+        body['temperature'] = request.temperature;
+      }
+
+      const response = await fetch('https://api.anthropic.com/v1/messages', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-api-key': this.apiKey,
+          'anthropic-version': this.anthropicVersion,
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        throw new Error(`Anthropic API error: ${response.status} ${response.statusText}`);
+      }
+
+      data = await response.json();
+    } finally {
+      clearTimeout(timer);
+    }
+
+    const d = data as {
+      content: Array<{ type: string; text: string }>;
+      usage: { input_tokens: number; output_tokens: number };
+      model: string;
+    };
+
+    const textContent = d.content.find((c) => c.type === 'text');
+    const text = textContent?.text ?? '';
+    const inputTokens = d.usage.input_tokens;
+    const outputTokens = d.usage.output_tokens;
+
+    return {
+      text,
+      tokensUsed: {
+        input: inputTokens,
+        output: outputTokens,
+        total: inputTokens + outputTokens,
+      },
+      cached: false,
+      model: d.model,
+    };
+  }
+}

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

@@ -0,0 +1,113 @@
+/**
+ * dare-llm-integration — DummyProvider
+ * Returns configurable responses without any network call.
+ * Use in tests and offline development.
+ * License: MIT
+ */
+
+import type {
+  LLMProvider,
+  CompletionRequest,
+  CompletionResponse,
+  EmbedRequest,
+  EmbeddingResponse,
+} from '../types.js';
+
+export interface DummyProviderConfig {
+  /** Fixed text to return from complete(). Default: "dummy response" */
+  completionText?: string;
+  /** Fixed embedding vector. Default: [0.1, 0.2, 0.3] */
+  embedding?: number[];
+  /** Simulated latency in ms. Default: 0 */
+  latencyMs?: number;
+  /** If set, complete() will throw this error */
+  throwError?: Error;
+  /** Token counts to report */
+  tokenCounts?: { input: number; output: number };
+  /** Called every time complete() is invoked (for spy assertions) */
+  onComplete?: (request: CompletionRequest) => void;
+  /** Called every time embed() is invoked */
+  onEmbed?: (request: EmbedRequest) => void;
+}
+
+export class DummyProvider implements LLMProvider {
+  private readonly completionText: string;
+  private readonly embedding: number[];
+  private readonly latencyMs: number;
+  private readonly throwError: Error | null;
+  private readonly tokenCounts: { input: number; output: number };
+  private readonly onComplete: ((req: CompletionRequest) => void) | null;
+  private readonly onEmbed: ((req: EmbedRequest) => void) | null;
+
+  /** Tracks all requests received (useful for assertions) */
+  public readonly completionHistory: CompletionRequest[] = [];
+  public readonly embedHistory: EmbedRequest[] = [];
+
+  constructor(config: DummyProviderConfig = {}) {
+    this.completionText = config.completionText ?? 'dummy response';
+    this.embedding = config.embedding ?? [0.1, 0.2, 0.3];
+    this.latencyMs = config.latencyMs ?? 0;
+    this.throwError = config.throwError ?? null;
+    this.tokenCounts = config.tokenCounts ?? { input: 10, output: 20 };
+    this.onComplete = config.onComplete ?? null;
+    this.onEmbed = config.onEmbed ?? null;
+  }
+
+  async complete(request: CompletionRequest): Promise<CompletionResponse> {
+    this.completionHistory.push(request);
+
+    if (this.onComplete) {
+      this.onComplete(request);
+    }
+
+    if (this.latencyMs > 0) {
+      await delay(this.latencyMs);
+    }
+
+    if (this.throwError) {
+      throw this.throwError;
+    }
+
+    return {
+      text: this.completionText,
+      tokensUsed: {
+        input: this.tokenCounts.input,
+        output: this.tokenCounts.output,
+        total: this.tokenCounts.input + this.tokenCounts.output,
+      },
+      cached: false,
+      model: request.model,
+      latencyMs: this.latencyMs,
+    };
+  }
+
+  async embed(request: EmbedRequest): Promise<EmbeddingResponse> {
+    this.embedHistory.push(request);
+
+    if (this.onEmbed) {
+      this.onEmbed(request);
+    }
+
+    if (this.latencyMs > 0) {
+      await delay(this.latencyMs);
+    }
+
+    if (this.throwError) {
+      throw this.throwError;
+    }
+
+    const inputs = Array.isArray(request.input) ? request.input : [request.input];
+    const embeddings = inputs.map(() => [...this.embedding]);
+
+    return {
+      embeddings,
+      tokensUsed: inputs.length * 5,
+      model: request.model,
+      cached: false,
+    };
+  }
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

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

@@ -0,0 +1,6 @@
+/**
+ * dare-llm-integration — LLMProvider interface
+ * License: MIT
+ */
+
+export type { LLMProvider } from '../types.js';