@johpaz/hive-agents 0.0.34 → 0.0.36

package/packages/core/src/agent/llm-providers/interface.ts

@@ -0,0 +1,195 @@
+/**
+ * Shared types and utilities for LLM providers.
+ */
+
+import type { LLMCallOptions, LLMMessage, LLMResponse, LLMToolCall, ContentPart } from "../llm-client"
+export type { LLMCallOptions, LLMMessage, LLMResponse, LLMToolCall, ContentPart }
+
+import { logger } from "../../utils/logger"
+const log = logger.child("llm-client")
+
+// ─── Provider interface ────────────────────────────────────────────────────────
+
+export interface LLMProvider {
+  call(options: LLMCallOptions): Promise<LLMResponse>
+}
+
+// ─── Shared constants ─────────────────────────────────────────────────────────
+
+// Models that only accept temperature=1 (reasoning/thinking models).
+export const FIXED_TEMPERATURE_1_MODELS = new Set(["kimi-k2.5", "kimi-k2", "kimi-k2-5"])
+
+export const OPENAI_COMPAT_BASE_URLS: Record<string, string> = {
+  groq: "https://api.groq.com/openai/v1",
+  mistral: "https://api.mistral.ai/v1",
+  openrouter: "https://openrouter.ai/api/v1",
+  deepseek: "https://api.deepseek.com/v1",
+  kimi: "https://api.moonshot.ai/v1",
+  "local-llama": "http://localhost:8081/v1",
+  nvidia: "https://integrate.api.nvidia.com/v1",
+  qwen: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
+}
+
+// ─── Provider profiles ────────────────────────────────────────────────────────
+
+export interface ProviderProfile {
+  /** Normalize tool names to strict OpenAI format: [a-zA-Z0-9_-]{1,64} */
+  normalizeToolNames: boolean
+  /** Replacement string for invalid tool name chars, e.g. "__" */
+  toolNameReplacement: string
+  /** Value for the tool_choice parameter ("auto" | "any" for Mistral) */
+  toolChoiceAuto: string
+  /** Send parallel_tool_calls: false when true */
+  disableParallelToolCalls: boolean
+  /** Strip additionalProperties: false from tool parameter schemas */
+  stripAdditionalProperties: boolean
+  /** Retry the call without tools when these HTTP status codes are returned */
+  retryWithoutToolsOnCodes: number[]
+}
+
+const DEFAULT_PROFILE: ProviderProfile = {
+  normalizeToolNames: false,
+  toolNameReplacement: "__",
+  toolChoiceAuto: "auto",
+  disableParallelToolCalls: false,
+  stripAdditionalProperties: false,
+  retryWithoutToolsOnCodes: [],
+}
+
+export const PROVIDER_PROFILES: Record<string, ProviderProfile> = {
+  openai: { ...DEFAULT_PROFILE, normalizeToolNames: true },
+  kimi: { ...DEFAULT_PROFILE, normalizeToolNames: true, disableParallelToolCalls: true, retryWithoutToolsOnCodes: [422] },
+  deepseek: { ...DEFAULT_PROFILE, normalizeToolNames: true },
+  groq: { ...DEFAULT_PROFILE, normalizeToolNames: true, retryWithoutToolsOnCodes: [400, 422] },
+  mistral: { ...DEFAULT_PROFILE, normalizeToolNames: true, toolChoiceAuto: "any", stripAdditionalProperties: true },
+  openrouter: { ...DEFAULT_PROFILE, normalizeToolNames: true, retryWithoutToolsOnCodes: [400, 422] },
+  nvidia: { ...DEFAULT_PROFILE, normalizeToolNames: true },
+  qwen: { ...DEFAULT_PROFILE, normalizeToolNames: true, retryWithoutToolsOnCodes: [400, 422] },
+  "local-llama": { ...DEFAULT_PROFILE },
+}
+
+export function getProviderProfile(provider: string): ProviderProfile {
+  return PROVIDER_PROFILES[provider] ?? DEFAULT_PROFILE
+}
+
+// ─── Models that don't support tool calling ───────────────────────────────────
+
+export const NO_TOOL_MODELS = new Set([
+  "deepseek-reasoner",
+  "deepseek/deepseek-r1:free",
+])
+
+export function modelSupportsTools(provider: string, model: string): boolean {
+  if (NO_TOOL_MODELS.has(model)) return false
+  // DeepSeek R1 and OpenRouter-routed R1 variants don't support tools
+  if ((provider === "deepseek" || provider === "openrouter") && /[-/]r1\b/i.test(model)) return false
+  return true
+}
+
+// ─── Tool name & schema normalization ────────────────────────────────────────
+
+const OPENAI_TOOL_NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/
+const NORMALIZE_CHARS_RE = /[^a-zA-Z0-9_-]/g
+
+/** Normalize a tool name to pass strict [a-zA-Z0-9_-]{1,64} validation. */
+export function normalizeToolName(name: string, replacement: string): string {
+  if (OPENAI_TOOL_NAME_RE.test(name)) return name
+  const escapedReplacement = replacement.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+  const collapseRE = new RegExp(`(${escapedReplacement}){2,}`, "g")
+  let n = name.replace(NORMALIZE_CHARS_RE, replacement).replace(collapseRE, replacement)
+  if (!/^[a-zA-Z_]/.test(n)) n = "_" + n
+  return n.slice(0, 64)
+}
+
+/** Strip provider-incompatible fields from a tool parameter schema. */
+export function normalizeToolSchema(
+  schema: Record<string, unknown>,
+  profile: ProviderProfile
+): Record<string, unknown> {
+  if (!profile.stripAdditionalProperties) return schema
+  return deepStripSchema(schema)
+}
+
+function deepStripSchema(obj: unknown): any {
+  if (typeof obj !== "object" || obj === null) return obj
+  if (Array.isArray(obj)) return obj.map(deepStripSchema)
+  const result: any = {}
+  for (const [k, v] of Object.entries(obj as Record<string, unknown>)) {
+    if (k === "additionalProperties" && v === false) continue
+    result[k] = deepStripSchema(v)
+  }
+  return result
+}
+
+// ─── Temperature constraints ──────────────────────────────────────────────────
+
+/**
+ * Returns true when the model requires temperature=1.
+ * Used for Kimi K2 thinking mode which rejects any other temperature.
+ */
+export function requiresTemperature1(provider: string, model: string): boolean {
+  if (FIXED_TEMPERATURE_1_MODELS.has(model)) return true
+  if (provider === "kimi") {
+    const m = model.toLowerCase()
+    if (m.includes("k2")) return true
+  }
+  return false
+}
+
+// ─── Message sanitization ─────────────────────────────────────────────────────
+
+/**
+ * Remove tool_calls from assistant messages whose corresponding tool results
+ * are missing from the history (e.g. cleared by compaction). Providers like
+ * Kimi reject message sequences with orphaned tool_calls.
+ */
+export function sanitizeMessages(messages: LLMMessage[]): LLMMessage[] {
+  // Pass 0: collect all tool_call_ids that appear in assistant messages.
+  const knownToolCallIds = new Set<string>()
+  for (const m of messages) {
+    if (m.role === "assistant" && m.tool_calls?.length) {
+      for (const tc of m.tool_calls) knownToolCallIds.add(tc.id)
+    }
+  }
+
+  // Pass 1: determine which tool_call_ids are "dead"
+  const deadIds = new Set<string>()
+
+  for (let i = 0; i < messages.length; i++) {
+    const m = messages[i]
+    if (m.role !== "assistant" || !m.tool_calls?.length) continue
+
+    const neededIds = new Set(m.tool_calls.map((tc) => tc.id))
+    let j = i + 1
+    while (j < messages.length && messages[j].role === "tool") {
+      if (messages[j].tool_call_id) neededIds.delete(messages[j].tool_call_id!)
+      j++
+    }
+    if (neededIds.size > 0) {
+      log.warn(`[llm-client] Stripping orphaned tool_calls (missing results for: ${[...neededIds].join(", ")})`)
+      for (const tc of m.tool_calls) deadIds.add(tc.id)
+    }
+  }
+
+  // Pass 2: rebuild message list, dropping/fixing affected messages
+  const result: LLMMessage[] = []
+  for (const m of messages) {
+    if (m.role === "tool" && m.tool_call_id) {
+      if (deadIds.has(m.tool_call_id) || !knownToolCallIds.has(m.tool_call_id)) {
+        log.warn(`[llm-client] Dropping orphaned tool result (tool_call_id: ${m.tool_call_id})`)
+        continue
+      }
+    }
+    if (m.role === "assistant" && m.tool_calls?.some((tc) => deadIds.has(tc.id))) {
+      const { tool_calls, ...rest } = m
+      const hasContent = typeof rest.content === "string"
+        ? rest.content.trim()
+        : Array.isArray(rest.content) && rest.content.length > 0
+      if (hasContent) result.push(rest as LLMMessage)
+      continue
+    }
+    result.push(m)
+  }
+
+  return result
+}

package/packages/core/src/agent/llm-providers/kimi.ts

@@ -0,0 +1,8 @@
+import { OpenAICompatBase } from "./openai-compat-base"
+
+export class KimiProvider extends OpenAICompatBase {
+  constructor() { super("kimi") }
+
+  /** Kimi K2 thinking mode returns reasoning_content that must be round-tripped. */
+  protected needsReasoningRoundtrip(): boolean { return true }
+}

package/packages/core/src/agent/llm-providers/local-llama.ts

@@ -0,0 +1,37 @@
+import { logger } from "../../utils/logger"
+import { OpenAICompatBase } from "./openai-compat-base"
+import type { LLMCallOptions } from "./interface"
+
+const log = logger.child("llm-client")
+
+export class LocalLlamaProvider extends OpenAICompatBase {
+  constructor() { super("local-llama") }
+
+  protected isLocalProvider(): boolean { return true }
+
+  /** Auto-start the local llama server if not already running. */
+  protected async beforeCall(options: LLMCallOptions): Promise<void> {
+    try {
+      const { llamaManager } = await import("../../gateway/llm-local/manager")
+      const modelId = options.model.replace(/^local-llama\//i, "")
+      await llamaManager.start("TEXT", modelId as any)
+    } catch (err) {
+      log.warn(`[llm-client] local-llama auto-start failed or skipped: ${err}`)
+    }
+  }
+
+  /**
+   * Many GGUF chat templates don't support native tool calling via body.tools,
+   * so we inject tool descriptions into the system prompt as a fallback.
+   */
+  protected injectToolsIntoPrompt(body: any, preparedTools: any[]): void {
+    const toolDescriptions = preparedTools.map(t => JSON.stringify(t.function)).join("\n")
+    const instruction = `You have access to the following tools. To call a tool, output a JSON block like: <tool_call>{"name": "tool_name", "arguments": {"arg1": "value"}}</tool_call>\n\nTools:\n${toolDescriptions}`
+    const sysMsg = body.messages.find((m: any) => m.role === "system")
+    if (sysMsg) {
+      sysMsg.content += "\n\n" + instruction
+    } else {
+      body.messages.unshift({ role: "system", content: instruction })
+    }
+  }
+}

package/packages/core/src/agent/llm-providers/mistral.ts

@@ -0,0 +1,5 @@
+import { OpenAICompatBase } from "./openai-compat-base"
+
+export class MistralProvider extends OpenAICompatBase {
+  constructor() { super("mistral") }
+}

package/packages/core/src/agent/llm-providers/nvidia.ts

@@ -0,0 +1,5 @@
+import { OpenAICompatBase } from "./openai-compat-base"
+
+export class NvidiaProvider extends OpenAICompatBase {
+  constructor() { super("nvidia") }
+}

package/packages/core/src/agent/llm-providers/ollama.ts

@@ -0,0 +1,175 @@
+import { logger } from "../../utils/logger"
+import { sanitizeMessages } from "./interface"
+import type { LLMCallOptions, LLMProvider, LLMResponse, LLMToolCall } from "./interface"
+import type { ContentPart, LLMMessage } from "../llm-client"
+
+const log = logger.child("llm-client")
+
+export class OllamaProvider implements LLMProvider {
+  private _convertMessage(msg: LLMMessage): any {
+    if (typeof msg.content === "string") {
+      return { role: msg.role, content: msg.content }
+    }
+
+    let textContent = ""
+    const images: string[] = []
+
+    for (const part of msg.content) {
+      if (part.type === "text") {
+        textContent += part.text
+      } else if (part.type === "image_base64") {
+        images.push(part.base64)
+      } else if (part.type === "document") {
+        textContent += `\n[Document: ${part.fileName || "file"}] (base64 content not displayed)`
+      } else if (part.type === "image_url") {
+        const url = part.image_url.url
+        if (url.startsWith("data:")) {
+          const match = url.match(/^data:([^;]+);base64,(.+)$/)
+          if (match) images.push(match[2])
+        } else {
+          textContent += `\n[Image URL: ${url}]`
+        }
+      }
+    }
+
+    return { role: msg.role, content: textContent.trim(), ...(images.length > 0 ? { images } : {}) }
+  }
+
+  async call(options: LLMCallOptions): Promise<LLMResponse> {
+    const { Ollama } = await import("ollama")
+
+    const modelName = options.model.replace(/^ollama\//, "")
+    const host = options.baseUrl?.trim() || process.env.OLLAMA_HOST || "http://localhost:11434"
+    const isCloud = host.includes("ollama.com")
+    const headers: Record<string, string> = {}
+    if (isCloud && options.apiKey) headers["Authorization"] = `Bearer ${options.apiKey}`
+
+    const client = new Ollama({
+      host,
+      ...(Object.keys(headers).length ? { headers } : {}),
+    })
+
+    const messages = sanitizeMessages(options.messages).map((m): any => {
+      if (m.role === "assistant" && m.tool_calls?.length) {
+        return {
+          role: "assistant",
+          content: typeof m.content === "string" ? m.content : m.content.map(p => (p as any).text || "").join(""),
+          tool_calls: m.tool_calls.map((tc) => ({
+            function: {
+              name: tc.function.name,
+              arguments: (() => {
+                try { return JSON.parse(tc.function.arguments) } catch { return {} }
+              })(),
+            },
+          })),
+        }
+      }
+      if (m.role === "tool") return { role: "tool", content: typeof m.content === "string" ? m.content : JSON.stringify(m.content) }
+      return this._convertMessage(m)
+    })
+
+    const tools = options.tools?.map((t) => ({
+      type: "function" as const,
+      function: {
+        name: t.function.name,
+        description: t.function.description,
+        parameters: t.function.parameters,
+      },
+    }))
+
+    // Default num_ctx to 4096 for local models — prevents OOM on small models (2B-7B)
+    // when Ollama's default (32k+) is too large for available RAM/VRAM.
+    // Users can override via providers.num_ctx in DB.
+    const runtimeOptions: Record<string, unknown> = {
+      num_ctx: options.numCtx ?? 4096,
+    }
+    if (options.numGpu !== undefined) runtimeOptions.num_gpu = options.numGpu
+    if (options.temperature !== undefined) runtimeOptions.temperature = options.temperature
+
+    try {
+
+      log.info(
+        `[llm-client] ollama/${modelName} @ ${isCloud ? "ollama.com" : host} stream=true` +
+        ` — ${messages.length} msgs, ${tools?.length ?? 0} tools` +
+        ` num_ctx=${runtimeOptions.num_ctx}`
+      )
+
+      const stream = await client.chat({
+        model: modelName,
+        messages,
+        tools: tools?.length ? tools : undefined,
+        options: Object.keys(runtimeOptions).length ? runtimeOptions : undefined,
+        stream: true,
+      })
+
+      let content = ""
+      let promptEvalCount = 0
+      let evalCount = 0
+      const tool_calls: LLMToolCall[] = []
+
+      for await (const part of stream) {
+        const delta = part.message?.content ?? ""
+        if (delta) {
+          content += delta
+          if (options.onToken) options.onToken(delta)
+        }
+
+        if (part.message?.tool_calls?.length) {
+          for (const tc of part.message.tool_calls) {
+            tool_calls.push({
+              id: crypto.randomUUID(),
+              type: "function" as const,
+              function: {
+                name: (tc as any).function.name,
+                arguments: JSON.stringify((tc as any).function.arguments ?? {}),
+              },
+            })
+          }
+        }
+
+        if (part.prompt_eval_count !== undefined) promptEvalCount = part.prompt_eval_count
+        if (part.eval_count !== undefined) evalCount = part.eval_count
+      }
+
+      return {
+        content,
+        tool_calls: tool_calls.length ? tool_calls : undefined,
+        stop_reason: tool_calls.length > 0 ? "tool_calls" : "stop",
+        usage:
+          evalCount > 0
+            ? { input_tokens: promptEvalCount, output_tokens: evalCount }
+            : undefined,
+      }
+    } catch (error: any) {
+      log.error(`[llm-client] FAILED call to ollama/${modelName} at ${host}`)
+      log.error(`[llm-client] Error details: ${error.message || error}`)
+      if (options.numCtx) log.error(`[llm-client] Context requested: num_ctx=${options.numCtx}`)
+      if (options.tools?.length) log.error(`[llm-client] Tools defined: ${options.tools.length}`)
+
+      // If the model runner crashed (likely OOM) and tools were sent, retry without tools.
+      // The model can still answer conversationally — tools will be unavailable this turn.
+      // Match by error message string OR HTTP 500 with tools (resilient to Ollama message changes).
+      if (
+        (error.message?.includes("model runner has unexpectedly stopped") || error.status === 500) &&
+        tools?.length
+      ) {
+        log.warn(`[llm-client] OOM with tools — retrying without tools (num_ctx=${runtimeOptions.num_ctx})`)
+        const stream2 = await client.chat({
+          model: modelName,
+          messages,
+          tools: undefined,
+          options: runtimeOptions,
+          stream: true,
+        })
+        let content = ""
+        for await (const part of stream2) {
+          const delta = part.message?.content ?? ""
+          if (delta) { content += delta; if (options.onToken) options.onToken(delta) }
+        }
+        return { content, tool_calls: undefined, stop_reason: "stop" }
+      }
+
+      throw error
+    }
+  }
+}