teleportation-cli 1.0.0

package/lib/router/classifier.js

@@ -0,0 +1,251 @@
+/**
+ * Task Classifier
+ * 
+ * Classifies coding tasks into tiers (cheap/mid/best) based on:
+ * - Prompt content (keywords, complexity indicators)
+ * - Context metadata (file count, diff size, etc.)
+ * 
+ * This is a heuristic-based classifier. For more sophisticated classification,
+ * use the /v1/models/recommend endpoint from llms.mechdna.net.
+ */
+
+// Tier constants
+export const TIERS = {
+  CHEAP: 'cheap',
+  MID: 'mid',
+  BEST: 'best',
+};
+
+// Tier ordering for escalation
+export const TIER_ORDER = ['cheap', 'mid', 'best'];
+
+// Keywords that suggest different complexity levels
+const COMPLEXITY_KEYWORDS = {
+  // Best tier - complex reasoning, planning, architecture
+  best: [
+    'architect', 'architecture', 'design', 'redesign',
+    'plan', 'planning', 'strategy', 'roadmap',
+    'migrate', 'migration', 'rewrite', 'rebuild',
+    'from scratch', 'greenfield', 'new system',
+    'complex', 'complicated', 'tricky', 'difficult',
+    'optimize', 'performance', 'scalability',
+    'security', 'audit', 'review thoroughly',
+    'think through', 'reason about', 'analyze deeply'
+  ],
+  
+  // Mid tier - substantial but bounded work
+  mid: [
+    'refactor', 'reorganize', 'restructure',
+    'implement', 'build', 'create', 'develop',
+    'fix bug', 'debug', 'troubleshoot',
+    'add feature', 'new feature', 'enhance',
+    'test', 'testing', 'write tests',
+    'multiple files', 'across files', 'several',
+    'integrate', 'integration', 'connect',
+    'update', 'upgrade', 'modify'
+  ],
+  
+  // Cheap tier - simple, bounded tasks (default)
+  cheap: [
+    'explain', 'what is', 'how does', 'why',
+    'simple', 'quick', 'small', 'minor',
+    'typo', 'rename', 'format', 'lint',
+    'comment', 'document', 'readme',
+    'list', 'show', 'find', 'search', 'grep',
+    'one file', 'single file', 'this file',
+    'variable', 'function name', 'import'
+  ]
+};
+
+// Context thresholds
+const THRESHOLDS = {
+  // File count thresholds
+  MANY_FILES: 5,      // > 5 files = likely mid or best
+  FEW_FILES: 2,       // <= 2 files = likely cheap
+  
+  // Diff/change size thresholds (lines)
+  LARGE_DIFF: 500,    // > 500 lines = likely best
+  MEDIUM_DIFF: 100,   // > 100 lines = likely mid
+  SMALL_DIFF: 30,     // <= 30 lines = likely cheap
+  
+  // Prompt length thresholds (characters)
+  LONG_PROMPT: 2000,  // Long prompts often indicate complex tasks
+  SHORT_PROMPT: 200   // Short prompts often indicate simple tasks
+};
+
+/**
+ * Classify a task based on prompt and context
+ * 
+ * @param {string} prompt - The user's prompt/request
+ * @param {Object} context - Optional context metadata
+ * @param {number} context.fileCount - Number of files involved
+ * @param {number} context.diffLines - Number of lines changed/affected
+ * @param {string[]} context.fileTypes - Types of files involved
+ * @param {boolean} context.isNewProject - Whether this is a new project
+ * @param {string} context.previousAttemptFailed - If a previous attempt failed
+ * @returns {{ tier: string, reason: string, confidence: number }}
+ */
+export function classifyTask(prompt, context = {}) {
+  const text = prompt.toLowerCase();
+  const {
+    fileCount = 1,
+    diffLines = 0,
+    isNewProject = false,
+    previousAttemptFailed = false
+  } = context;
+
+  // Track scoring
+  let scores = { cheap: 0, mid: 0, best: 0 };
+  let reasons = [];
+
+  // 1. Check for explicit tier keywords
+  for (const [tier, keywords] of Object.entries(COMPLEXITY_KEYWORDS)) {
+    for (const keyword of keywords) {
+      if (text.includes(keyword)) {
+        scores[tier] += 2;
+        if (scores[tier] === 2) { // First match for this tier
+          reasons.push(`keyword "${keyword}"`);
+        }
+      }
+    }
+  }
+
+  // 2. Context-based scoring
+  
+  // File count
+  if (fileCount > THRESHOLDS.MANY_FILES) {
+    scores.best += 2;
+    scores.mid += 1;
+    reasons.push(`${fileCount} files involved`);
+  } else if (fileCount > THRESHOLDS.FEW_FILES) {
+    scores.mid += 2;
+    reasons.push(`${fileCount} files involved`);
+  } else {
+    scores.cheap += 1;
+  }
+
+  // Diff size
+  if (diffLines > THRESHOLDS.LARGE_DIFF) {
+    scores.best += 3;
+    reasons.push(`large diff (${diffLines} lines)`);
+  } else if (diffLines > THRESHOLDS.MEDIUM_DIFF) {
+    scores.mid += 2;
+    reasons.push(`medium diff (${diffLines} lines)`);
+  } else if (diffLines > THRESHOLDS.SMALL_DIFF) {
+    scores.mid += 1;
+  } else {
+    scores.cheap += 1;
+  }
+
+  // New project = more complex
+  if (isNewProject) {
+    scores.best += 2;
+    scores.mid += 1;
+    reasons.push('new project');
+  }
+
+  // Previous attempt failed = escalate
+  if (previousAttemptFailed) {
+    scores.best += 2;
+    scores.mid += 1;
+    reasons.push('previous attempt failed');
+  }
+
+  // Prompt length heuristic
+  if (prompt.length > THRESHOLDS.LONG_PROMPT) {
+    scores.mid += 1;
+    scores.best += 1;
+  } else if (prompt.length < THRESHOLDS.SHORT_PROMPT) {
+    scores.cheap += 1;
+  }
+
+  // 3. Determine winner
+  const maxScore = Math.max(scores.cheap, scores.mid, scores.best);
+  let tier;
+  
+  if (scores.best === maxScore && scores.best > 0) {
+    tier = 'best';
+  } else if (scores.mid === maxScore && scores.mid > 0) {
+    tier = 'mid';
+  } else {
+    tier = 'cheap';
+  }
+
+  // Calculate confidence (0-1)
+  const totalScore = scores.cheap + scores.mid + scores.best;
+  const confidence = totalScore > 0 ? maxScore / totalScore : 0.5;
+
+  // Build reason string
+  const reasonStr = reasons.length > 0 
+    ? reasons.slice(0, 3).join(', ')
+    : 'default (no strong signals)';
+
+  return {
+    tier,
+    reason: reasonStr,
+    confidence: Math.round(confidence * 100) / 100,
+    scores // Include raw scores for debugging
+  };
+}
+
+/**
+ * Build a use-case string for the /v1/models/recommend API
+ * 
+ * @param {string} prompt - The user's prompt
+ * @param {Object} context - Context metadata
+ * @returns {string} A concise use-case description
+ */
+export function buildUseCaseString(prompt, context = {}) {
+  const { tier, reason } = classifyTask(prompt, context);
+  
+  // Truncate prompt for API
+  const truncatedPrompt = prompt.length > 300 
+    ? prompt.slice(0, 300) + '...'
+    : prompt;
+
+  // Build context description
+  const contextParts = [];
+  if (context.fileCount) contextParts.push(`${context.fileCount} files`);
+  if (context.diffLines) contextParts.push(`${context.diffLines} lines changed`);
+  if (context.isNewProject) contextParts.push('new project');
+  
+  const contextStr = contextParts.length > 0 
+    ? ` Context: ${contextParts.join(', ')}.`
+    : '';
+
+  return `Coding task (${tier} complexity): ${truncatedPrompt}${contextStr}`;
+}
+
+/**
+ * Extract context from a coding environment
+ * Helper to build context object from various sources
+ * 
+ * @param {Object} options
+ * @returns {Object} Context object for classifyTask
+ */
+export function extractContext(options = {}) {
+  const {
+    files = [],           // Array of file paths
+    diff = '',            // Git diff or similar
+    isNew = false,        // New project flag
+    failedBefore = false  // Previous attempt failed
+  } = options;
+
+  return {
+    fileCount: files.length,
+    diffLines: diff ? diff.split('\n').length : 0,
+    fileTypes: [...new Set(files.map(f => f.split('.').pop()))],
+    isNewProject: isNew,
+    previousAttemptFailed: failedBefore
+  };
+}
+
+export default {
+  classifyTask,
+  buildUseCaseString,
+  extractContext,
+  TIERS,
+  TIER_ORDER,
+  COMPLEXITY_KEYWORDS,
+  THRESHOLDS
+};

package/lib/router/example.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * Router Example / Test Script
+ * 
+ * Run: node lib/router/example.js
+ * 
+ * Requires: MECH_API_KEY environment variable
+ */
+
+import { createRouter, classifyTask } from './index.js';
+
+async function main() {
+  console.log('=== Teleportation Router Example ===\n');
+
+  // Check for API key
+  if (!process.env.MECH_API_KEY) {
+    console.log('⚠️  MECH_API_KEY not set. Classification will work but completions will fail.\n');
+  }
+
+  // ============================================
+  // 1. Test Task Classification
+  // ============================================
+  console.log('--- Task Classification Examples ---\n');
+
+  const testCases = [
+    { prompt: 'What is a variable?', context: {} },
+    { prompt: 'Rename this function to getUserById', context: { fileCount: 1 } },
+    { prompt: 'Refactor the authentication module to use JWT', context: { fileCount: 5, diffLines: 200 } },
+    { prompt: 'Design the architecture for a new microservices system', context: { isNewProject: true } },
+    { prompt: 'Fix the bug where users can\'t login', context: { fileCount: 3, diffLines: 50 } },
+    { prompt: 'Migrate the database from MySQL to PostgreSQL', context: { fileCount: 20, diffLines: 1000 } },
+  ];
+
+  for (const { prompt, context } of testCases) {
+    const result = classifyTask(prompt, context);
+    console.log(`Prompt: "${prompt.slice(0, 50)}${prompt.length > 50 ? '...' : ''}"`);
+    console.log(`  → Tier: ${result.tier} (confidence: ${result.confidence})`);
+    console.log(`  → Reason: ${result.reason}`);
+    console.log();
+  }
+
+  // ============================================
+  // 2. Test Router (if API key available)
+  // ============================================
+  if (process.env.MECH_API_KEY) {
+    console.log('--- Router Test ---\n');
+
+    const router = createRouter({ verbose: true });
+
+    try {
+      // Simple question (should use cheap model)
+      console.log('Test 1: Simple question\n');
+      const result1 = await router.route({
+        prompt: 'What is the capital of France?',
+        messages: [{ role: 'user', content: 'What is the capital of France?' }]
+      });
+      
+      console.log(`Response: ${result1.content}`);
+      console.log(`Model: ${result1.model}`);
+      console.log(`Cost: $${result1.cost?.toFixed(6) || 'unknown'}`);
+      console.log(`Escalations: ${result1.escalations}`);
+      console.log();
+
+      // Coding task (should use mid model)
+      console.log('Test 2: Coding task\n');
+      const result2 = await router.route({
+        prompt: 'Write a function to reverse a string in JavaScript',
+        messages: [{ role: 'user', content: 'Write a function to reverse a string in JavaScript' }],
+        context: { fileCount: 1 }
+      });
+      
+      console.log(`Response: ${result2.content.slice(0, 200)}...`);
+      console.log(`Model: ${result2.model}`);
+      console.log(`Cost: $${result2.cost?.toFixed(6) || 'unknown'}`);
+      console.log(`Escalations: ${result2.escalations}`);
+      console.log();
+
+      // Get usage summary
+      console.log('--- Usage Summary ---\n');
+      const usage = await router.getUsageSummary();
+      console.log(`Today: ${usage.today?.totalRequests || 0} requests, $${usage.today?.totalCost?.toFixed(4) || '0.0000'}`);
+      console.log(`This month: ${usage.thisMonth?.totalRequests || 0} requests, $${usage.thisMonth?.totalCost?.toFixed(4) || '0.0000'}`);
+
+    } catch (err) {
+      console.error('Router test failed:', err.message);
+    }
+  }
+
+  console.log('\n=== Done ===');
+}
+
+main().catch(console.error);

package/lib/router/index.js

@@ -0,0 +1,69 @@
+/**
+ * Teleportation Model Router
+ * 
+ * Cost-aware routing for LLM requests. Automatically selects the cheapest
+ * capable model for each task, with escalation on failure.
+ * 
+ * Usage:
+ * 
+ * ```js
+ * import { createRouter, route } from './lib/router/index.js';
+ * 
+ * // Option 1: Create a router instance
+ * const router = createRouter({ verbose: true });
+ * const result = await router.route({
+ *   prompt: 'Fix the bug in this function',
+ *   messages: [{ role: 'user', content: 'Fix the bug in this function...' }],
+ *   context: { fileCount: 1, diffLines: 20 }
+ * });
+ * console.log(result.content);
+ * console.log(`Cost: $${result.cost.toFixed(4)}, Model: ${result.model}`);
+ * 
+ * // Option 2: Quick one-off routing
+ * const result = await route('Explain this code', messages);
+ * 
+ * // Option 3: Direct completion (no routing)
+ * const result = await router.complete({
+ *   model: 'gpt-4o-mini',
+ *   messages: [{ role: 'user', content: 'Hello' }]
+ * });
+ * ```
+ * 
+ * Environment Variables:
+ * - MECH_API_KEY: API key for llms.mechdna.net
+ * - MECH_LLMS_URL: Override API URL (default: https://llms.mechdna.net)
+ */
+
+// Main router
+export { Router, createRouter, route } from './router.js';
+
+// Task classifier
+export { 
+  classifyTask, 
+  buildUseCaseString, 
+  extractContext
+} from './classifier.js';
+
+// Re-export constants from default export
+import classifierModule from './classifier.js';
+export const COMPLEXITY_KEYWORDS = classifierModule.COMPLEXITY_KEYWORDS;
+export const THRESHOLDS = classifierModule.THRESHOLDS;
+
+// Model registry
+export { 
+  QUALITY_TIERS,
+  TIER_TO_QUALITY,
+  FALLBACK_MODELS,
+  getModelsByQuality,
+  getModelsByTier,
+  getCheapestForTier,
+  getEscalationOrder,
+  getNextTier
+} from './models.js';
+
+// Mech LLMs client
+export { MechLLMsClient, createClient } from './mech-llms-client.js';
+
+// Default export
+import { Router } from './router.js';
+export default Router;

package/lib/router/mech-llms-client.js

@@ -0,0 +1,277 @@
+/**
+ * Mech LLMs API Client
+ * 
+ * Client for llms.mechdna.net - the unified LLM gateway.
+ * Provides access to:
+ * - Chat completions (multi-provider)
+ * - Model registry with cost/capability data
+ * - Model recommendations
+ * - Usage tracking
+ */
+
+const DEFAULT_BASE_URL = 'https://llms.mechdna.net';
+const DEFAULT_TIMEOUT = 120000; // 2 minutes for LLM calls
+
+/**
+ * Mech LLMs API Client
+ */
+export class MechLLMsClient {
+  /**
+   * @param {Object} options
+   * @param {string} options.apiKey - Mech API key (X-API-Key header)
+   * @param {string} [options.baseUrl] - API base URL
+   * @param {number} [options.timeout] - Request timeout in ms
+   */
+  constructor(options = {}) {
+    this.apiKey = options.apiKey || process.env.MECH_API_KEY;
+    this.baseUrl = options.baseUrl || process.env.MECH_LLMS_URL || DEFAULT_BASE_URL;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT;
+
+    if (!this.apiKey) {
+      console.warn('[MechLLMsClient] No API key provided. Set MECH_API_KEY env var or pass apiKey option.');
+    }
+  }
+
+  /**
+   * Make an authenticated request to the API
+   */
+  async _request(method, path, body = null) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      'Content-Type': 'application/json',
+    };
+    
+    if (this.apiKey) {
+      headers['X-API-Key'] = this.apiKey;
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : null,
+        signal: controller.signal
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const error = await response.json().catch(() => ({ error: { message: response.statusText } }));
+        throw new Error(error.error?.message || `HTTP ${response.status}: ${response.statusText}`);
+      }
+
+      return response.json();
+    } catch (err) {
+      clearTimeout(timeoutId);
+      if (err.name === 'AbortError') {
+        throw new Error(`Request timeout after ${this.timeout}ms`);
+      }
+      throw err;
+    }
+  }
+
+  // ============================================
+  // Chat Completions
+  // ============================================
+
+  /**
+   * Create a chat completion
+   * 
+   * @param {Object} options
+   * @param {string} options.model - Model ID (e.g., 'gpt-4o', 'claude-sonnet-4')
+   * @param {Array} options.messages - Chat messages
+   * @param {number} [options.maxTokens] - Max tokens to generate
+   * @param {number} [options.temperature] - Sampling temperature
+   * @param {boolean} [options.stream] - Enable streaming (not supported in this client yet)
+   * @param {Array} [options.tools] - Tools/functions for function calling
+   * @param {Object} [options.reasoning] - Reasoning/thinking config
+   * @returns {Promise<Object>} Completion response with x_llm_cost
+   */
+  async createCompletion(options) {
+    const {
+      model,
+      messages,
+      maxTokens = 4096,
+      temperature,
+      tools,
+      reasoning,
+      responseFormat,
+      ...rest
+    } = options;
+
+    const body = {
+      model,
+      messages,
+      max_tokens: maxTokens,
+      ...rest
+    };
+
+    if (temperature !== undefined) body.temperature = temperature;
+    if (tools) body.tools = tools;
+    if (reasoning) body.reasoning = reasoning;
+    if (responseFormat) body.response_format = responseFormat;
+
+    return this._request('POST', '/v1/chat/completions', body);
+  }
+
+  // ============================================
+  // Model Registry
+  // ============================================
+
+  /**
+   * List available models
+   * 
+   * @returns {Promise<Object>} List of models
+   */
+  async listModels() {
+    return this._request('GET', '/v1/models');
+  }
+
+  /**
+   * Get model registry with filtering and sorting
+   * 
+   * @param {Object} [filters]
+   * @param {string} [filters.provider] - Filter by provider (anthropic, openai, google)
+   * @param {string} [filters.capability] - Filter by capability
+   * @param {string} [filters.quality] - Filter by quality tier
+   * @param {number} [filters.minCost] - Min cost per 1M tokens
+   * @param {number} [filters.maxCost] - Max cost per 1M tokens
+   * @param {string} [filters.sortBy] - Sort by (cost, speed, quality)
+   * @param {string} [filters.sortOrder] - Sort order (asc, desc)
+   * @returns {Promise<Object>} Model registry response
+   */
+  async getModelRegistry(filters = {}) {
+    const params = new URLSearchParams();
+    
+    if (filters.provider) params.set('provider', filters.provider);
+    if (filters.capability) params.set('capability', filters.capability);
+    if (filters.quality) params.set('quality', filters.quality);
+    if (filters.minCost) params.set('min_cost', filters.minCost);
+    if (filters.maxCost) params.set('max_cost', filters.maxCost);
+    if (filters.sortBy) params.set('sort_by', filters.sortBy);
+    if (filters.sortOrder) params.set('sort_order', filters.sortOrder);
+
+    const query = params.toString();
+    const path = query ? `/v1/models/registry?${query}` : '/v1/models/registry';
+    
+    return this._request('GET', path);
+  }
+
+  /**
+   * Get cheapest model for a quality tier
+   * 
+   * @param {string} quality - Quality tier (flagship, high, standard, fast, budget)
+   * @returns {Promise<Object|null>} Cheapest model or null
+   */
+  async getCheapestModel(quality) {
+    const result = await this.getModelRegistry({
+      quality,
+      sortBy: 'cost',
+      sortOrder: 'asc'
+    });
+    
+    return result.models?.[0] || null;
+  }
+
+  /**
+   * Compare multiple models
+   * 
+   * @param {string[]} models - Array of model IDs to compare
+   * @returns {Promise<Object>} Comparison response
+   */
+  async compareModels(models) {
+    return this._request('POST', '/v1/models/compare', { models });
+  }
+
+  /**
+   * Get model recommendations based on use case
+   * 
+   * @param {Object} options
+   * @param {string} options.useCase - Use case description
+   * @param {Object} [options.requirements] - Requirements
+   * @param {number} [options.requirements.maxCost] - Max cost per 1M tokens
+   * @param {string} [options.requirements.minSpeed] - Min speed (very_fast, fast, medium, slow)
+   * @param {string[]} [options.requirements.capabilities] - Required capabilities
+   * @returns {Promise<Object>} Recommendations response
+   */
+  async getRecommendations(options) {
+    const { useCase, requirements } = options;
+    
+    const body = {
+      use_case: useCase
+    };
+    
+    if (requirements) {
+      body.requirements = {};
+      if (requirements.maxCost) body.requirements.max_cost = requirements.maxCost;
+      if (requirements.minSpeed) body.requirements.min_speed = requirements.minSpeed;
+      if (requirements.capabilities) body.requirements.capabilities = requirements.capabilities;
+    }
+
+    return this._request('POST', '/v1/models/recommend', body);
+  }
+
+  // ============================================
+  // Usage Tracking
+  // ============================================
+
+  /**
+   * Get usage statistics
+   * 
+   * @param {Object} [filters]
+   * @param {string} [filters.userId] - Filter by user ID
+   * @param {string} [filters.projectId] - Filter by project ID
+   * @param {string} [filters.model] - Filter by model
+   * @param {string} [filters.startDate] - Start date (ISO 8601)
+   * @param {string} [filters.endDate] - End date (ISO 8601)
+   * @param {string} [filters.groupBy] - Group by (hour, day, week, month, model, project)
+   * @returns {Promise<Object>} Usage statistics
+   */
+  async getUsage(filters = {}) {
+    const params = new URLSearchParams();
+    
+    if (filters.userId) params.set('userId', filters.userId);
+    if (filters.projectId) params.set('projectId', filters.projectId);
+    if (filters.model) params.set('model', filters.model);
+    if (filters.startDate) params.set('startDate', filters.startDate);
+    if (filters.endDate) params.set('endDate', filters.endDate);
+    if (filters.groupBy) params.set('groupBy', filters.groupBy);
+
+    const query = params.toString();
+    const path = query ? `/v1/usage?${query}` : '/v1/usage';
+    
+    return this._request('GET', path);
+  }
+
+  /**
+   * Get usage summary (today, this month, all time)
+   * 
+   * @param {Object} [filters]
+   * @param {string} [filters.userId] - Filter by user ID
+   * @param {string} [filters.projectId] - Filter by project ID
+   * @returns {Promise<Object>} Usage summary
+   */
+  async getUsageSummary(filters = {}) {
+    const params = new URLSearchParams();
+    
+    if (filters.userId) params.set('userId', filters.userId);
+    if (filters.projectId) params.set('projectId', filters.projectId);
+
+    const query = params.toString();
+    const path = query ? `/v1/usage/summary?${query}` : '/v1/usage/summary';
+    
+    return this._request('GET', path);
+  }
+}
+
+/**
+ * Create a client instance with default configuration
+ */
+export function createClient(options = {}) {
+  return new MechLLMsClient(options);
+}
+
+export default MechLLMsClient;