@tyvm/knowhow 0.0.104 → 0.0.106

package/src/clients/http.ts

@@ -6,11 +6,29 @@ import {
   EmbeddingOptions,
   EmbeddingResponse,
 } from "./types";
+import { ModelPricing } from "./pricing/types";
 import fs from "fs";
 import path from "path";
 
+export interface HttpClientOptions {
+  headers?: Record<string, string>;
+  timeout?: number;
+  extra_body?: Record<string, any>;
+}
+
 export class HttpClient implements GenericClient {
-  constructor(private baseUrl: string, private headers = {}) {}
+  /** Timeout in milliseconds for HTTP requests. Default: 30000 (30s). Use 0 to disable. */
+  private timeout: number;
+  private headers: Record<string, string>;
+  private extra_body: Record<string, any>;
+  /** Optional pricing table: model id → per-million-token prices */
+  private pricingMap: Record<string, ModelPricing> = {};
+
+  constructor(private baseUrl: string, options: HttpClientOptions = {}) {
+    this.headers = options.headers ?? {};
+    this.timeout = options.timeout ?? 30000;
+    this.extra_body = options.extra_body ?? {};
+  }
 
   private async withRetry<T>(fn: () => Promise<T>, retries = 3): Promise<T> {
     let lastError: any;
@@ -64,6 +82,52 @@ export class HttpClient implements GenericClient {
     this.setJwt(key);
   }
 
+  /**
+   * Supply a pricing map so that createChatCompletion / createEmbedding can
+   * calculate a local usd_cost from usage tokens when the provider does not
+   * return a cost field itself.
+   */
+  setPrices(pricingMap: Record<string, ModelPricing>) {
+    this.pricingMap = pricingMap;
+  }
+
+  /**
+   * Calculate USD cost for a completion/embedding call from token usage.
+   * Returns undefined if no pricing entry exists for the model.
+   */
+  calculateCost(
+    model: string,
+    usage: { prompt_tokens?: number; completion_tokens?: number; prompt_tokens_details?: { cached_tokens?: number } } | undefined
+  ): number | undefined {
+    if (!usage) return undefined;
+    const pricing = this.pricingMap[model];
+    if (!pricing) return undefined;
+
+    const cachedInputTokens =
+      usage.prompt_tokens_details?.cached_tokens ?? 0;
+    const inputTokens = usage.prompt_tokens ?? 0;
+    const outputTokens = usage.completion_tokens ?? 0;
+
+    const cachedInputCost = (cachedInputTokens * (pricing.cache_hit ?? pricing.cached_input ?? 0)) / 1e6;
+    const inputCost = ((inputTokens - cachedInputTokens) * (pricing.input ?? 0)) / 1e6;
+    const outputCost = (outputTokens * (pricing.output ?? 0)) / 1e6;
+
+    return cachedInputCost + inputCost + outputCost;
+  }
+
+  /**
+   * Apply extra options (timeout, headers, extra_body) after construction.
+   * Used by AIClient.resolveClient to honour per-provider config overrides
+   * even when the client is created via a known clientClass (e.g. nvidia, groq).
+   */
+  setOptions(options: Omit<HttpClientOptions, "headers"> & { headers?: Record<string, string> }) {
+    if (options.timeout !== undefined) this.timeout = options.timeout;
+    if (options.extra_body !== undefined) this.extra_body = options.extra_body;
+    if (options.headers) {
+      this.headers = { ...this.headers, ...options.headers };
+    }
+  }
+
   loadJwtFile(filePath: string) {
     try {
       const jwtFile = path.join(process.cwd(), filePath);
@@ -85,7 +149,8 @@ export class HttpClient implements GenericClient {
         ...options,
         model: options.model,
         messages: options.messages,
-        max_tokens: options.max_tokens || 3000,
+        max_tokens: options.max_tokens || 4000,
+        ...this.extra_body,
 
         ...(options.tools && {
           tools: options.tools,
@@ -96,7 +161,7 @@ export class HttpClient implements GenericClient {
       const response = await http.post(
         `${this.baseUrl}/v1/chat/completions`,
         body,
-        { headers: this.headers as Record<string, string> }
+        { headers: this.headers as Record<string, string>, timeout: this.timeout }
       );
 
       const data = response.data;
@@ -116,7 +181,125 @@ export class HttpClient implements GenericClient {
         })),
         model: data.model,
         usage: data.usage,
-        usd_cost: data.usd_cost,
+        usd_cost: data.usd_cost ?? this.calculateCost(options.model, data.usage),
+      };
+    });
+  }
+
+  /**
+   * Creates a completion using the Responses API (/v1/responses).
+   * Compatible with providers that implement the OpenAI Responses API spec
+   * (e.g. xAI at https://api.x.ai/v1/responses).
+   */
+  async createResponse(
+    options: CompletionOptions,
+    store = false
+  ): Promise<CompletionResponse> {
+    return this.withRetry(async () => {
+      // Extract system messages as instructions
+      const systemMessages = options.messages.filter((m) => m.role === "system");
+      const nonSystemMessages = options.messages.filter((m) => m.role !== "system");
+      const instructions = systemMessages
+        .map((m) => (typeof m.content === "string" ? m.content : ""))
+        .join("\n")
+        .trim() || undefined;
+
+      // Convert messages to Responses API input format
+      const input: any[] = nonSystemMessages.map((msg) => {
+        if (msg.role === "tool") {
+          return {
+            type: "function_call_output",
+            call_id: msg.tool_call_id,
+            output: typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content),
+          };
+        }
+        if (msg.role === "assistant" && msg.tool_calls?.length) {
+          return (msg.tool_calls as any[]).map((tc: any) => ({
+            type: "function_call",
+            id: tc.id.startsWith("fc") ? tc.id : `fc_${tc.id}`,
+            call_id: tc.id,
+            name: tc.function.name,
+            arguments: tc.function.arguments,
+          }));
+        }
+        return {
+          role: msg.role,
+          content: typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content),
+        };
+      }).flat();
+
+      const tools = options.tools?.map((tool) => ({
+        type: "function" as const,
+        name: tool.function.name,
+        description: tool.function.description,
+        parameters: tool.function.parameters as Record<string, unknown>,
+        strict: false,
+      }));
+
+      const body = {
+        model: options.model,
+        input,
+        ...(instructions && { instructions }),
+        ...(options.max_tokens && { max_output_tokens: options.max_tokens }),
+        ...(tools?.length && { tools, tool_choice: "auto" }),
+        store,
+        ...this.extra_body,
+      };
+
+      const response = await http.post(
+        `${this.baseUrl}/v1/responses`,
+        body,
+        { headers: this.headers as Record<string, string>, timeout: this.timeout }
+      );
+
+      const data = response.data;
+
+      if (data.error) {
+        throw new Error(JSON.stringify(data.error, null, 2));
+      }
+
+      // Map usage from Responses API format to Chat Completions format
+      const usage = data.usage
+        ? {
+            prompt_tokens: data.usage.input_tokens,
+            completion_tokens: data.usage.output_tokens,
+            total_tokens: data.usage.input_tokens + data.usage.output_tokens,
+          }
+        : undefined;
+
+      // Collect text content and tool calls from output items
+      let textContent: string | null = null;
+      const toolCalls: any[] = [];
+
+      for (const item of data.output ?? []) {
+        if (item.type === "message") {
+          for (const part of item.content ?? []) {
+            if (part.type === "output_text") {
+              textContent = (textContent ?? "") + part.text;
+            }
+          }
+        } else if (item.type === "function_call") {
+          toolCalls.push({
+            id: item.call_id,
+            type: "function",
+            function: { name: item.name, arguments: item.arguments },
+          });
+        }
+      }
+
+      return {
+        choices: [
+          {
+            message: {
+              role: "assistant",
+              content: textContent,
+              ...(toolCalls.length > 0 && { tool_calls: toolCalls }),
+            },
+          },
+        ],
+        model: data.model ?? options.model,
+        usage,
+        usd_cost: data.usd_cost ?? this.calculateCost(options.model, usage),
       };
     });
   }
@@ -129,7 +312,7 @@ export class HttpClient implements GenericClient {
           model: options.model,
           input: options.input,
         },
-        { headers: this.headers as Record<string, string> }
+        { headers: this.headers as Record<string, string>, timeout: this.timeout }
       );
 
       const data = response.data;
@@ -143,7 +326,7 @@ export class HttpClient implements GenericClient {
         data: data.data,
         model: options.model,
         usage: data.usage,
-        usd_cost: data.usd_cost,
+        usd_cost: data.usd_cost ?? this.calculateCost(options.model, data.usage),
       };
     });
   }
@@ -152,6 +335,7 @@ export class HttpClient implements GenericClient {
     return this.withRetry(async () => {
       const response = await http.get(`${this.baseUrl}/v1/models?type=${type}`, {
         headers: this.headers as Record<string, string>,
+        timeout: this.timeout,
       });
 
       const data = response.data?.data;

package/src/clients/index.ts

@@ -30,6 +30,42 @@ import { ModelProvider } from "../types";
 import { getConfig } from "../config";
 import { loadKnowhowJwt, KNOWHOW_API_URL } from "../services/KnowhowClient";
 import { ContextLimits } from "./contextLimits";
+import { OpenAiTextPricing } from "./pricing/openai";
+import { AnthropicTextPricing } from "./pricing/anthropic";
+import { GeminiPricing } from "./pricing/google";
+import {
+  XaiTextPricing,
+  XaiImagePricing,
+  XaiVideoPricing,
+} from "./pricing/xai";
+import type {
+  ModelPricing,
+  ModelType,
+  ModelCatalogEntry,
+} from "./pricing/types";
+import { GenericCerebrasClient } from "./cerebras";
+import { GenericGroqClient } from "./groq";
+import { GenericGitHubModelsClient } from "./github";
+import { GenericNvidiaClient } from "./nvidia";
+import { GenericOpenRouterClient } from "./openrouter";
+import { GenericDeepSeekClient } from "./deepseek";
+import { GenericMistralClient } from "./mistral";
+import { GitHubCopilotClient } from "./copilot";
+import { GenericLlamaClient } from "./llama";
+import { GenericFireworksClient } from "./fireworks";
+export {
+  OpenAiTextPricing,
+  AnthropicTextPricing,
+  GeminiPricing,
+  XaiTextPricing,
+  XaiImagePricing,
+  XaiVideoPricing,
+};
+export type {
+  ModelPricing,
+  ModelType,
+  ModelCatalogEntry,
+} from "./pricing/types";
 
 // ---------------------------------------------------------------------------
 // Built-in provider registry
@@ -49,6 +85,18 @@ const BUILT_IN_PROVIDER_REGISTRY: Record<string, ProviderRegistryEntry> = {
   anthropic: { clientClass: GenericAnthropicClient },
   google: { clientClass: GenericGeminiClient },
   xai: { clientClass: GenericXAIClient },
+  cerebras: {
+    clientClass: GenericCerebrasClient,
+  },
+  groq: { clientClass: GenericGroqClient },
+  github: { clientClass: GenericGitHubModelsClient },
+  nvidia: { clientClass: GenericNvidiaClient },
+  openrouter: { clientClass: GenericOpenRouterClient },
+  deepseek: { clientClass: GenericDeepSeekClient },
+  mistral: { clientClass: GenericMistralClient },
+  "github-copilot": { clientClass: GitHubCopilotClient },
+  llama: { clientClass: GenericLlamaClient },
+  fireworks: { clientClass: GenericFireworksClient },
   knowhow: {
     createClient: (entry: ModelProvider) => {
       const jwt = loadKnowhowJwt();
@@ -68,7 +116,17 @@ const DEFAULT_PROVIDERS: ModelProvider[] = [
   { provider: "anthropic", envKey: "ANTHROPIC_API_KEY" },
   { provider: "google", envKey: "GEMINI_API_KEY" },
   { provider: "xai", envKey: "XAI_API_KEY" },
+  { provider: "cerebras", envKey: "CEREBRAS_API_KEY" },
   { provider: "knowhow" },
+  { provider: "groq", envKey: "GROQ_API_KEY" },
+  { provider: "github", envKey: "GITHUB_TOKEN" },
+  { provider: "nvidia", envKey: "NVIDIA_API_KEY" },
+  { provider: "openrouter", envKey: "OPENROUTER_API_KEY" },
+  { provider: "deepseek", envKey: "DEEPSEEK_API_KEY" },
+  { provider: "mistral", envKey: "MISTRAL_API_KEY" },
+  { provider: "github-copilot", envKey: "GITHUB_COPILOT_TOKEN" },
+  { provider: "llama", envKey: "LLAMA_API_KEY" },
+  { provider: "fireworks", envKey: "FIREWORKS_API_KEY" },
 ];
 
 export class AIClient {
@@ -127,19 +185,45 @@ export class AIClient {
         // envKey-based auth: env var must be present
         const envValue = process.env[effectiveEnvKey];
         if (!envValue) return null;
-        return new reg.clientClass(envValue);
+        const client = new reg.clientClass(envValue);
+        // Apply any extra options (timeout, headers, extra_body) from config
+        if (client instanceof HttpClient) {
+          client.setOptions({
+            timeout: entry.timeout,
+            headers: entry.headers,
+            extra_body: entry.extra_body,
+          });
+          if (entry.pricing) client.setPrices(entry.pricing);
+        }
+        return client;
       }
 
       // No envKey, no url — instantiate with no arg (client uses its own defaults)
-      return new reg.clientClass();
+      const client = new reg.clientClass();
+      // Apply any extra options (timeout, headers, extra_body) from config
+      if (client instanceof HttpClient) {
+        client.setOptions({
+          timeout: entry.timeout,
+          headers: entry.headers,
+          extra_body: entry.extra_body,
+        });
+        if (entry.pricing) client.setPrices(entry.pricing);
+      }
+      return client;
     }
 
     // 3. HTTP provider — requires url, no clientClass in registry
     if (entry.url) {
-      const client = new HttpClient(entry.url, entry.headers);
+      const client = new HttpClient(entry.url, {
+        headers: entry.headers,
+        timeout: entry.timeout,
+        extra_body: entry.extra_body,
+      });
       if (entry.jwtFile) {
         client.loadJwtFile(entry.jwtFile);
       }
+      // For custom HTTP providers, use entry.pricing if available
+      if (entry.pricing) client.setPrices(entry.pricing);
       return client;
     }
 
@@ -219,7 +303,9 @@ export class AIClient {
 
       if (!client) {
         if (entry.provider === "knowhow") {
-          console.warn(`⚠️  Knowhow provider is not logged in. Run 'knowhow login' to enable Knowhow models.`);
+          console.warn(
+            `⚠️  Knowhow provider is not logged in. Run 'knowhow login' to enable Knowhow models.`
+          );
         }
         continue;
       }
@@ -464,6 +550,52 @@ export class AIClient {
     return undefined;
   }
 
+  /**
+   * Normalize a model ID for fuzzy matching:
+   *   - lowercase
+   *   - replace dots with dashes (e.g. "claude-opus-4.7" → "claude-opus-4-7")
+   *   - strip variant suffixes like ":thinking", ":free"
+   *   - strip trailing date suffixes like "-20250514"
+   *   - strip trailing "-beta", "-preview", "-latest"
+   */
+  private static normalizeModelId(id: string): string {
+    return id
+      .toLowerCase()
+      .replace(/\./g, "-")
+      .replace(/:[^:]+$/, "")
+      .replace(/-\d{8}$/, "")
+      .replace(/-(beta|preview|latest|exp|rc\d*)$/i, "");
+  }
+
+  /**
+   * Fuzzy model lookup: given a model name (possibly without date suffix,
+   * with dots instead of dashes, etc.), find the best matching registered model.
+   *
+   * Example: "claude-3.7-sonnet" matches "claude-3-7-sonnet-20250219"
+   *          "gpt-4.1" matches "gpt-4.1" exactly
+   *
+   * @param modelQuery - the model name to search for (can be partial/normalized)
+   * @param provider   - optional provider to restrict search to
+   */
+  findModelFuzzy(modelQuery: string, provider?: string): { provider: string; model: string } | undefined {
+    const queryNorm = AIClient.normalizeModelId(modelQuery);
+    const providers = provider
+      ? [provider]
+      : Object.keys(this.clientModels);
+
+    for (const p of providers) {
+      const models = (this.clientModels[p] as string[]) ?? [];
+      for (const m of models) {
+        const mNorm = AIClient.normalizeModelId(m);
+        // Exact normalized match, OR our model is a dated variant of the query
+        if (mNorm === queryNorm || mNorm.startsWith(queryNorm + "-")) {
+          return { provider: p, model: m };
+        }
+      }
+    }
+    return undefined;
+  }
+
   // detects these formats:
   // "openai", "gpt-5"
   // "knowhow", "openai/gpt-5"
@@ -499,17 +631,22 @@ export class AIClient {
     }
 
     const allModels = this.listAllModels();
-    const hasKnowhowModels =
-      allModels["knowhow"] && allModels["knowhow"].length > 0;
+    const hasKnowhowModels = allModels.knowhow && allModels.knowhow.length > 0;
     const knowhowIsConfigured = Object.keys(allModels).includes("knowhow");
 
-    console.warn(`⚠️  Unable to find model '${model}' for provider '${provider}'.`);
-    console.warn(`   Available providers: ${Object.keys(allModels).join(", ") || "(none)"}`);
+    console.warn(
+      `⚠️  Unable to find model '${model}' for provider '${provider}'.`
+    );
+    console.warn(
+      `   Available providers: ${Object.keys(allModels).join(", ") || "(none)"}`
+    );
 
     if (!hasKnowhowModels && !knowhowIsConfigured) {
       console.warn(`   Tip: Run 'knowhow login' to enable Knowhow models.`);
     } else if (!hasKnowhowModels) {
-      console.warn(`   Tip: The Knowhow provider returned no models. Try running 'knowhow login' to re-authenticate.`);
+      console.warn(
+        `   Tip: The Knowhow provider returned no models. Try running 'knowhow login' to re-authenticate.`
+      );
     }
 
     return { provider, model };
@@ -763,6 +900,66 @@ export class AIClient {
     if (contextLimit === undefined) return undefined;
     return { contextLimit, threshold: contextLimit };
   }
+
+  /**
+   * Returns pricing information for all known models, derived from the
+   * provider pricing maps.
+   *
+   * @param modelId  Optional model id filter (without provider prefix).
+   *                 If omitted, all models across all providers are returned.
+   */
+  getPrices(modelId?: string): ModelCatalogEntry[] {
+    const results: ModelCatalogEntry[] = [];
+
+    const addModels = (
+      models: Record<string, string[]>,
+      type: ModelType,
+      pricingMap: Record<string, ModelPricing>
+    ) => {
+      for (const [provider, ids] of Object.entries(models)) {
+        for (const id of ids) {
+          if (modelId && id !== modelId) continue;
+          if (!pricingMap[id]) continue;
+
+          const p = pricingMap[id];
+          results.push({
+            id,
+            provider,
+            type,
+            pricing: p,
+          });
+        }
+      }
+    };
+
+    // Build a combined pricing map across all providers
+    const allTextPricing: Record<string, ModelPricing> = {
+      ...OpenAiTextPricing,
+      ...AnthropicTextPricing,
+      ...GeminiPricing,
+      ...XaiTextPricing,
+    };
+    const allImagePricing: Record<string, ModelPricing> = {
+      ...XaiImagePricing,
+    };
+    const allVideoPricing: Record<string, ModelPricing> = {
+      ...XaiVideoPricing,
+    };
+
+    addModels(this.completionModels, "completion", allTextPricing);
+    addModels(this.embeddingModels, "embedding", allTextPricing);
+    addModels(this.imageModels, "image", {
+      ...allTextPricing,
+      ...allImagePricing,
+    });
+    addModels(this.audioModels, "audio", allTextPricing);
+    addModels(this.videoModels, "video", {
+      ...allTextPricing,
+      ...allVideoPricing,
+    });
+
+    return results;
+  }
 }
 
 export const Clients = new AIClient();
@@ -777,3 +974,12 @@ export * from "./gemini";
 export * from "./contextLimits";
 export * from "./xai";
 export * from "./knowhowMcp";
+export * from "./groq";
+export * from "./github";
+export * from "./nvidia";
+export * from "./openrouter";
+export * from "./deepseek";
+export * from "./mistral";
+export * from "./llama";
+export * from "./copilot";
+export * from "./fireworks";

package/src/clients/llama.ts

@@ -0,0 +1,16 @@
+import { HttpClient } from "./http";
+import { LlamaTextPricing } from "./pricing/llama";
+
+/**
+ * Meta Llama API client — OpenAI-compatible API
+ * https://llama.developer.meta.com/docs/
+ * Direct from Meta: free Llama 3.x, Llama 4, and Cerebras/Groq-hosted variants.
+ * Set env var LLAMA_API_KEY to enable.
+ */
+export class GenericLlamaClient extends HttpClient {
+  constructor(apiKey = process.env.LLAMA_API_KEY) {
+    super("https://api.llama.com/compat");
+    if (apiKey) this.setJwt(apiKey);
+    this.setPrices(LlamaTextPricing);
+  }
+}

package/src/clients/mistral.ts

@@ -0,0 +1,16 @@
+import { HttpClient } from "./http";
+import { MistralTextPricing } from "./pricing/mistral";
+
+/**
+ * Mistral AI client — OpenAI-compatible API
+ * https://docs.mistral.ai/api/
+ * Top European AI lab with Mistral Large, Codestral, and free Devstral coding model.
+ * Set env var MISTRAL_API_KEY to enable.
+ */
+export class GenericMistralClient extends HttpClient {
+  constructor(apiKey = process.env.MISTRAL_API_KEY) {
+    super("https://api.mistral.ai");
+    if (apiKey) this.setJwt(apiKey);
+    this.setPrices(MistralTextPricing);
+  }
+}

package/src/clients/nvidia.ts

@@ -0,0 +1,16 @@
+import { HttpClient } from "./http";
+import { NvidiaTextPricing } from "./pricing/nvidia";
+
+/**
+ * NVIDIA NIM client — OpenAI-compatible API
+ * https://build.nvidia.com/explore/discover
+ * 76+ free models including Llama, Mistral, Phi, Flux image generation.
+ * Set env var NVIDIA_API_KEY to enable.
+ */
+export class GenericNvidiaClient extends HttpClient {
+  constructor(apiKey = process.env.NVIDIA_API_KEY) {
+    super("https://integrate.api.nvidia.com");
+    if (apiKey) this.setJwt(apiKey);
+    this.setPrices(NvidiaTextPricing);
+  }
+}