@tyvm/knowhow 0.0.105 → 0.0.107

package/src/clients/gemini.ts

@@ -16,15 +16,17 @@ import { wait } from "../utils";
 import {
   EmbeddingModels,
   Models,
+  GoogleThinkingLevelModels,
+  GoogleThinkingBudgetModels,
   GoogleImageModels,
   GoogleVideoModels,
   GoogleTTSModels,
-  GoogleEmbeddingModels,
+  GoogleEmbeddingModelsList,
   GoogleReasoningModels,
 } from "../types";
 import { GeminiTextPricing } from "./pricing";
 import { ContextLimits } from "./contextLimits";
-import { ModelModality } from "./types";
+import { ModelModality, TokenUsage } from "./types";
 
 import {
   GenericClient,
@@ -389,9 +391,49 @@ export class GenericGeminiClient implements GenericClient {
     return [{ functionDeclarations }];
   }
 
+  /**
+   * Builds the thinkingConfig for Gemini models that support it.
+   * - Gemini 3.x models use thinkingLevel: "minimal" | "low" | "medium" | "high"
+   * - Gemini 2.5 models use thinkingBudget: number (0 = off, -1 = dynamic)
+   *
+   * Maps CompletionOptions.reasoning_effort to provider-specific values.
+   */
+  buildThinkingConfig(options: CompletionOptions): Record<string, unknown> | undefined {
+    const model = options.model;
+    const effort = options.reasoning_effort ?? "low";
+
+    // Gemini 3.x — use thinkingLevel
+    if (GoogleThinkingLevelModels.includes(model)) {
+      const levelMap: Record<string, string> = {
+        low: "low",
+        medium: "medium",
+        high: "high",
+      };
+      return {
+        thinkingLevel: levelMap[effort] ?? "low",
+      };
+    }
+
+    // Gemini 2.5 — use thinkingBudget
+    if (GoogleThinkingBudgetModels.includes(model)) {
+      // Map effort to token budget
+      const budgetMap: Record<string, number> = {
+        low: 1024,
+        medium: 8192,
+        high: -1, // dynamic
+      };
+      return {
+        thinkingBudget: budgetMap[effort] ?? 1024,
+      };
+    }
+
+    return undefined;
+  }
+
   async createChatCompletion(
     options: CompletionOptions
   ): Promise<CompletionResponse> {
+    const thinkingConfig = this.buildThinkingConfig(options);
     const { systemInstruction, contents } = this.transformMessages(
       options.messages
     );
@@ -403,6 +445,7 @@ export class GenericGeminiClient implements GenericClient {
         contents,
         config: {
           systemInstruction,
+          thinkingConfig,
           tools: this.transformTools(options.tools),
           maxOutputTokens: options.max_tokens,
         },
@@ -481,10 +524,22 @@ export class GenericGeminiClient implements GenericClient {
         ? this.calculateCost(options.model, usage)
         : undefined;
 
+      // Map cachedContentTokenCount → prompt_tokens_details.cached_tokens so that
+      // base.ts can read cache hit tokens via usage.prompt_tokens_details?.cached_tokens
+      const cachedTokens = (usage as any)?.cachedContentTokenCount ?? 0;
+      const usageWithCache: TokenUsage | undefined = usage
+        ? ({
+            prompt_tokens: (usage as any).promptTokenCount ?? 0,
+            completion_tokens: (usage as any).candidatesTokenCount ?? 0,
+            total_tokens: (usage as any).totalTokenCount,
+            prompt_tokens_details: { cached_tokens: cachedTokens },
+          } as TokenUsage)
+        : undefined;
+
       return {
         choices,
         model: options.model,
-        usage,
+        usage: usageWithCache,
         usd_cost: usdCost,
       };
     } catch (error) {
@@ -600,7 +655,7 @@ export class GenericGeminiClient implements GenericClient {
     if (modality) {
       const map: Partial<Record<ModelModality, string[]>> = {
         completion: GoogleReasoningModels,
-        embedding: GoogleEmbeddingModels,
+        embedding: GoogleEmbeddingModelsList,
         image: GoogleImageModels,
         audio: GoogleTTSModels,
         video: GoogleVideoModels,

package/src/clients/github.ts

@@ -0,0 +1,16 @@
+import { HttpClient } from "./http";
+import { GitHubModelsTextPricing } from "./pricing/github";
+
+/**
+ * GitHub Models client — OpenAI-compatible API
+ * https://docs.github.com/en/github-models
+ * Free access to premium models (GPT-4o, DeepSeek R1, Llama, Phi etc.) with a GitHub token.
+ * Set env var GITHUB_TOKEN to enable.
+ */
+export class GenericGitHubModelsClient extends HttpClient {
+  constructor(apiKey = process.env.GITHUB_TOKEN) {
+    super("https://models.github.ai/inference");
+    if (apiKey) this.setJwt(apiKey);
+    this.setPrices(GitHubModelsTextPricing);
+  }
+}

package/src/clients/groq.ts

@@ -0,0 +1,15 @@
+import { HttpClient } from "./http";
+import { GroqTextPricing } from "./pricing/groq";
+
+/**
+ * Groq client — OpenAI-compatible API (ultra-fast inference)
+ * https://console.groq.com/docs/openai
+ * Set env var GROQ_API_KEY to enable.
+ */
+export class GenericGroqClient extends HttpClient {
+  constructor(apiKey = process.env.GROQ_API_KEY) {
+    super("https://api.groq.com/openai");
+    if (apiKey) this.setJwt(apiKey);
+    this.setPrices(GroqTextPricing);
+  }
+}

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,129 @@ 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,
+            prompt_tokens_details: {
+              cached_tokens:
+                data.usage.input_tokens_details?.cached_tokens ?? 0,
+            },
+          }
+        : 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 +316,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 +330,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 +339,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

@@ -43,6 +43,16 @@ import type {
   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,
@@ -75,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();
@@ -94,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 {
@@ -153,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;
     }
 
@@ -492,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"
@@ -822,7 +926,6 @@ export class AIClient {
             id,
             provider,
             type,
-            displayName: id,
             pricing: p,
           });
         }
@@ -871,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);
+  }
+}