@graphoria/server 0.1.0

package/src/ai/agent/agent.ts

@@ -0,0 +1,222 @@
+import { z } from "zod";
+import type { Message, Tool, ToolDefinition } from "./types";
+import { getProvider } from "./providers";
+import { logger } from "../../logging";
+
+const MAX_ITERATIONS = 10;
+
+/** Strip null values from tool-call arguments — LLMs pass `null` for optional fields instead of omitting them. */
+function stripNulls(args: Record<string, unknown>): Record<string, unknown> {
+  for (const key of Object.keys(args)) {
+    if (args[key] === null) delete args[key];
+  }
+  return args;
+}
+
+/** Minimal view of a Zod 4 internal def for schema introspection. */
+type ZodDef = { type: string; innerType?: ZodLike; shape?: Record<string, ZodLike> };
+type ZodLike = { def?: ZodDef };
+
+/** Unwrap optional/default/nullable to the base Zod type. */
+function baseType(field: ZodLike): ZodLike {
+  let cur = field;
+  while (
+    cur.def &&
+    ["optional", "default", "nullable"].includes(cur.def.type) &&
+    cur.def.innerType
+  ) {
+    cur = cur.def.innerType;
+  }
+  return cur;
+}
+
+/**
+ * JSON.parse string args whose schema target is a structured/scalar type.
+ * Small LLMs send `'["a"]'` or `'true'` as strings; parse before Zod validation.
+ */
+function coerceJsonStrings(
+  schema: z.ZodTypeAny,
+  args: Record<string, unknown>,
+): Record<string, unknown> {
+  const shape = (schema as unknown as ZodLike).def?.shape;
+  if (!shape) return args;
+  for (const key of Object.keys(args)) {
+    if (typeof args[key] !== "string" || !shape[key]) continue;
+    const t = baseType(shape[key]).def?.type;
+    if (t && ["array", "object", "record", "number", "boolean"].includes(t)) {
+      try {
+        args[key] = JSON.parse(args[key] as string);
+      } catch {
+        /* let Zod reject */
+      }
+    }
+  }
+  return args;
+}
+
+/** Convert a Zod-based Tool to an OpenAI-compatible ToolDefinition. */
+function toToolDefinition(tool: Tool): ToolDefinition {
+  const jsonSchema = z.toJSONSchema(tool.schema);
+  return {
+    type: "function",
+    function: {
+      name: tool.name,
+      description: tool.description,
+      parameters: jsonSchema as ToolDefinition["function"]["parameters"],
+    },
+  };
+}
+
+// ---- Factory ----
+
+/** Pre-bound agent config. Use with {@link createAgent}. */
+export interface AgentConfig {
+  tools: Tool[];
+  systemPrompt: string;
+  /** Wraps the raw user prompt into the final user message sent to the LLM. */
+  wrap: (content: string) => string;
+}
+
+/**
+ * Create a pre-configured agent function. Bind tools, system prompt, and prompt
+ * wrapper once — call with just a prompt string any number of times.
+ *
+ * @example
+ *   const ask = createAgent({
+ *     tools,
+ *     systemPrompt: "You are a database assistant...",
+ *     wrap: (prompt) => `Database-query from user:\n> ${prompt}`,
+ *   });
+ *   const answer = await ask("list all contacts grouped by role");
+ */
+export function createAgent(config: AgentConfig): (prompt: string) => Promise<string> {
+  return (prompt: string) => ask(prompt, config.tools, config.systemPrompt, config.wrap);
+}
+
+// ---- Core agent loop ----
+
+/**
+ * Send a prompt to the LLM and return ONLY the final text answer.
+ * Handles tool-calling loops internally — the caller never sees tool calls.
+ *
+ * Use {@link createAgent} for a pre-configured single-arg version.
+ *
+ * @example
+ *   const answer = await ask(
+ *     "list all contacts grouped by role",
+ *     tools,
+ *     "You are a database assistant...",
+ *     (prompt) => `Database-query from user:\n> ${prompt}`,
+ *   );
+ */
+export async function ask(
+  prompt: string,
+  tools: Tool[],
+  systemPrompt: string,
+  wrap: (content: string) => string,
+): Promise<string> {
+  const messages: Message[] = [
+    { role: "system", content: systemPrompt },
+    { role: "user", content: wrap(prompt) },
+  ];
+
+  const provider = await getProvider();
+  const toolDefs: ToolDefinition[] = tools.map(toToolDefinition);
+  const log = logger("ai-agent");
+
+  for (let i = 0; i < MAX_ITERATIONS; i++) {
+    log.debug({ iteration: i + 1 }, "agent iteration");
+
+    const { content, toolCalls } = await provider.chat(messages, toolDefs);
+
+    // If the model returned tool calls, execute them and feed results back
+    if (toolCalls.length > 0) {
+      log.debug({ toolCallCount: toolCalls.length }, "model requested tool calls");
+
+      // Append assistant message (with tool_calls) to history
+      messages.push({
+        role: "assistant",
+        content,
+        tool_calls: toolCalls,
+      });
+
+      // Execute each tool and append results
+      for (const tc of toolCalls) {
+        const toolName = tc.function.name;
+        const rawArgs = tc.function.arguments;
+
+        log.debug({ tool: toolName, args: rawArgs }, "calling tool");
+
+        const tool = tools.find((t) => t.name === toolName);
+        if (!tool) {
+          log.warn({ tool: toolName }, "unknown tool requested by model");
+          messages.push({
+            role: "tool",
+            content: JSON.stringify({
+              error: `Unknown tool: ${toolName}`,
+            }),
+            tool_name: toolName,
+            tool_call_id: tc.id,
+          });
+          continue;
+        }
+
+        try {
+          // Strip nulls, coerce stringified JSON (LLM robustness), then validate via Zod
+          const cleanedArgs = coerceJsonStrings(tool.schema, stripNulls(rawArgs));
+          const parsedArgs = tool.schema.parse(cleanedArgs);
+          const result = await tool.execute(parsedArgs);
+          const resultStr = JSON.stringify(result);
+
+          log.debug({ tool: toolName, resultLength: resultStr.length }, "tool returned");
+
+          messages.push({
+            role: "tool",
+            content: resultStr,
+            tool_name: toolName,
+            tool_call_id: tc.id,
+          });
+        } catch (err) {
+          log.warn({ tool: toolName, err }, "tool execution failed");
+          messages.push({
+            role: "tool",
+            content: JSON.stringify({
+              error: err instanceof Error ? err.message : String(err),
+            }),
+            tool_name: toolName,
+            tool_call_id: tc.id,
+          });
+        }
+      }
+
+      // Continue loop — feed tool results back to model
+      continue;
+    }
+
+    // No tool calls — this is the final answer
+    // Guard: if model never called query_data or graphql_execute, it's likely hallucinating
+    const calledTools = messages
+      .filter((m) => m.role === "assistant" && m.tool_calls)
+      .flatMap((m) => m.tool_calls!.map((tc) => tc.function.name));
+
+    const hasDescribed = calledTools.includes("describe_entity");
+    const hasQueried = calledTools.includes("query_data");
+    const hasGraphql = calledTools.includes("graphql_execute");
+
+    if (!hasQueried && !hasGraphql) {
+      log.warn("model attempted answer without querying data, nudging");
+      messages.push({
+        role: "user",
+        content: hasDescribed
+          ? "STOP — you haven't queried the data yet. Call query_data with the entity and columns from describe_entity. Use operation 'aggregate' with groupBy for grouping. Do NOT fabricate data."
+          : "STOP — you skipped steps. Call describe_entity to get the table schema, then query_data to run the query. Do NOT fabricate data.",
+      });
+      continue;
+    }
+
+    log.debug({ answerLength: content.length }, "model answered directly");
+    return content;
+  }
+
+  throw new Error(`Agent loop exceeded ${MAX_ITERATIONS} iterations without a final answer.`);
+}

package/src/ai/agent/index.ts

@@ -0,0 +1,2 @@
+export { ask, createAgent } from "./agent";
+export type { AgentConfig } from "./agent";

package/src/ai/agent/providers/anthropic.ts

@@ -0,0 +1,113 @@
+import Anthropic from "@anthropic-ai/sdk";
+import type { ChatResult, Message, Provider, ToolCall, ToolDefinition } from "../types";
+
+export interface AnthropicConfig {
+  apiKey: string;
+  model: string;
+  maxTokens?: number;
+  temperature?: number;
+}
+
+function toAnthropicTool(t: ToolDefinition): Anthropic.Tool {
+  return {
+    name: t.function.name,
+    description: t.function.description,
+    input_schema: t.function.parameters as Anthropic.Tool["input_schema"],
+  };
+}
+
+/**
+ * Serialize normalized history → Anthropic's wire shape.
+ * - `system` messages are extracted to the top-level `system` param.
+ * - consecutive `tool` results are coalesced into a single user message of
+ *   tool_result blocks (Anthropic requires them grouped after the assistant turn).
+ */
+function toAnthropicMessages(messages: Message[]): {
+  system: string | undefined;
+  anthropicMessages: Anthropic.MessageParam[];
+} {
+  let system: string | undefined;
+  const out: Anthropic.MessageParam[] = [];
+
+  for (const m of messages) {
+    if (m.role === "system") {
+      system = system ? `${system}\n\n${m.content}` : m.content;
+      continue;
+    }
+
+    if (m.role === "user") {
+      out.push({ role: "user", content: m.content });
+      continue;
+    }
+
+    if (m.role === "assistant") {
+      const blocks: Array<Anthropic.TextBlockParam | Anthropic.ToolUseBlockParam> = [];
+      if (m.content) blocks.push({ type: "text", text: m.content });
+      for (const tc of m.tool_calls ?? []) {
+        blocks.push({
+          type: "tool_use",
+          id: tc.id,
+          name: tc.function.name,
+          input: tc.function.arguments,
+        });
+      }
+      out.push({ role: "assistant", content: blocks });
+      continue;
+    }
+
+    // role === "tool" → tool_result block, grouped into a trailing user message.
+    const block: Anthropic.ToolResultBlockParam = {
+      type: "tool_result",
+      tool_use_id: m.tool_call_id ?? "",
+      content: m.content,
+    };
+    const last = out[out.length - 1];
+    if (last && last.role === "user" && Array.isArray(last.content)) {
+      last.content.push(block);
+    } else {
+      out.push({ role: "user", content: [block] });
+    }
+  }
+
+  return { system, anthropicMessages: out };
+}
+
+/** Provider for Anthropic's Messages API (Claude). */
+export function makeAnthropic(cfg: AnthropicConfig): Provider {
+  const client = new Anthropic({ apiKey: cfg.apiKey });
+  const maxTokens = cfg.maxTokens ?? 4096;
+  const temperature = cfg.temperature ?? 0;
+
+  return {
+    async chat(messages: Message[], tools: ToolDefinition[]): Promise<ChatResult> {
+      const { system, anthropicMessages } = toAnthropicMessages(messages);
+
+      const res = await client.messages.create({
+        model: cfg.model,
+        max_tokens: maxTokens,
+        temperature,
+        system,
+        tools: tools.map(toAnthropicTool),
+        messages: anthropicMessages,
+      });
+
+      let content = "";
+      const toolCalls: ToolCall[] = [];
+      for (const block of res.content) {
+        if (block.type === "text") {
+          content += block.text;
+        } else if (block.type === "tool_use") {
+          toolCalls.push({
+            id: block.id,
+            function: {
+              name: block.name,
+              arguments: (block.input ?? {}) as Record<string, unknown>,
+            },
+          });
+        }
+      }
+
+      return { content, toolCalls };
+    },
+  };
+}

package/src/ai/agent/providers/index.ts

@@ -0,0 +1,62 @@
+import type { Provider } from "../types";
+
+function requireEnv(key: string): string {
+  const value = process.env[key];
+  if (!value) {
+    throw new Error(`${key} is required for LLM_PROVIDER="${process.env.LLM_PROVIDER}".`);
+  }
+  return value;
+}
+
+// Provider registry. Each factory dynamically imports its module so the
+// provider SDK is loaded into memory ONLY when that provider is selected.
+// Add OpenAI-compatible backends (Groq, Mistral, Together, …) as one more
+// entry pointing makeOpenAICompatible at their baseURL.
+const REGISTRY: Record<string, () => Promise<Provider>> = {
+  ollama: async () => {
+    const { ollamaProvider } = await import("./ollama");
+    return ollamaProvider;
+  },
+
+  openai: async () => {
+    const { makeOpenAICompatible } = await import("./openai");
+    return makeOpenAICompatible({
+      apiKey: requireEnv("OPENAI_API_KEY"),
+      baseURL: process.env.OPENAI_BASE_URL, // undefined → SDK default (api.openai.com)
+      model: process.env.LLM_MODEL ?? "gpt-4o-mini",
+    });
+  },
+
+  deepseek: async () => {
+    const { makeOpenAICompatible } = await import("./openai");
+    return makeOpenAICompatible({
+      apiKey: requireEnv("DEEPSEEK_API_KEY"),
+      baseURL: "https://api.deepseek.com",
+      model: process.env.LLM_MODEL ?? "deepseek-chat",
+    });
+  },
+
+  anthropic: async () => {
+    const { makeAnthropic } = await import("./anthropic");
+    return makeAnthropic({
+      apiKey: requireEnv("ANTHROPIC_API_KEY"),
+      model: process.env.LLM_MODEL ?? "claude-haiku-4-5-20251001",
+    });
+  },
+};
+
+/**
+ * Resolve the active LLM provider from `LLM_PROVIDER` (default "ollama").
+ * The provider module (and its SDK) is dynamically imported on demand, so
+ * unused provider SDKs never load. Each provider reads its own env vars lazily.
+ */
+export function getProvider(): Promise<Provider> {
+  const name = (process.env.LLM_PROVIDER ?? "ollama").toLowerCase();
+  const factory = REGISTRY[name];
+  if (!factory) {
+    throw new Error(
+      `Unknown LLM_PROVIDER "${name}". Valid options: ${Object.keys(REGISTRY).join(", ")}.`,
+    );
+  }
+  return factory();
+}

package/src/ai/agent/providers/ollama.ts

@@ -0,0 +1,128 @@
+import type { ChatResult, Message, Provider, ToolDefinition } from "../types";
+
+const OLLAMA_HOST = process.env.OLLAMA_HOST ?? "http://localhost:11434";
+// LLM_MODEL is the unified knob; OLLAMA_MODEL kept for backward compatibility.
+const OLLAMA_MODEL = process.env.LLM_MODEL ?? process.env.OLLAMA_MODEL ?? "qwen3.5:2b";
+
+export const config = {
+  host: OLLAMA_HOST,
+  model: OLLAMA_MODEL,
+};
+
+// ---- Per-model presets for optimal accuracy ----
+// Keyed by model family prefix (matched case-insensitive).
+
+interface ModelPreset {
+  temperature: number;
+  top_p?: number;
+  top_k?: number;
+  num_predict?: number;
+  seed?: number;
+}
+
+const PRESETS: Record<string, ModelPreset> = {
+  // Google Gemma 4 — recommended sampling params from official docs
+  gemma4: { temperature: 1.0, top_p: 0.95, top_k: 64 },
+
+  // Meta Llama 3.x — temp 0 kills hallucination on small models
+  llama3: { temperature: 0, num_predict: 2048 },
+
+  // Alibaba Qwen 3.x — low temp for deterministic tool use
+  qwen3: { temperature: 0.1, top_p: 0.9 },
+
+  // IBM Granite 4 — conservative sampling
+  granite4: { temperature: 0.1 },
+
+  // Google FunctionGemma — tiny, keep deterministic
+  functiongemma: { temperature: 0 },
+
+  // Default fallback — safe for unknown models
+  default: { temperature: 0, top_p: 0.9 },
+};
+
+function resolvePreset(model: string): ModelPreset {
+  const key = model.toLowerCase();
+  for (const [prefix, preset] of Object.entries(PRESETS)) {
+    if (key.startsWith(prefix)) return preset;
+  }
+  return PRESETS.default!;
+}
+
+// ---- Ollama wire format ----
+
+interface OllamaToolCall {
+  function: { name: string; arguments: Record<string, unknown> };
+}
+
+interface OllamaMessage {
+  role: "system" | "user" | "assistant" | "tool";
+  content: string;
+  tool_calls?: OllamaToolCall[];
+  tool_name?: string;
+}
+
+interface OllamaChatResponse {
+  message: { role: "assistant"; content: string; tool_calls?: OllamaToolCall[] };
+}
+
+/** Serialize normalized history → Ollama's wire shape (tool results keyed by tool_name). */
+function toOllamaMessages(messages: Message[]): OllamaMessage[] {
+  return messages.map((m): OllamaMessage => {
+    if (m.role === "assistant" && m.tool_calls && m.tool_calls.length > 0) {
+      return {
+        role: "assistant",
+        content: m.content,
+        tool_calls: m.tool_calls.map((tc) => ({
+          function: { name: tc.function.name, arguments: tc.function.arguments },
+        })),
+      };
+    }
+    if (m.role === "tool") {
+      return { role: "tool", content: m.content, tool_name: m.tool_name };
+    }
+    return { role: m.role, content: m.content };
+  });
+}
+
+/**
+ * Native Ollama provider. Talks to /api/chat directly (no SDK) and keeps the
+ * per-model sampling presets. Default provider — runs local/free, no API key.
+ */
+export const ollamaProvider: Provider = {
+  async chat(messages: Message[], tools: ToolDefinition[]): Promise<ChatResult> {
+    const preset = resolvePreset(config.model);
+
+    const body = {
+      model: config.model,
+      messages: toOllamaMessages(messages),
+      tools,
+      stream: false,
+      options: {
+        temperature: preset.temperature,
+        top_p: preset.top_p,
+        top_k: preset.top_k,
+        num_predict: preset.num_predict,
+        seed: preset.seed,
+      },
+    };
+
+    const res = await fetch(`${config.host}/api/chat`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Ollama API error ${res.status} (${res.statusText}): ${text}`);
+    }
+
+    const data = (await res.json()) as OllamaChatResponse;
+    const toolCalls = (data.message.tool_calls ?? []).map((tc, i) => ({
+      id: `ollama-${i}`, // Ollama omits ids; synthesize one for correlation.
+      function: { name: tc.function.name, arguments: tc.function.arguments },
+    }));
+
+    return { content: data.message.content ?? "", toolCalls };
+  },
+};

package/src/ai/agent/providers/openai.ts

@@ -0,0 +1,100 @@
+import OpenAI from "openai";
+import type { ChatResult, Message, Provider, ToolDefinition } from "../types";
+
+type OAIMessage = OpenAI.Chat.Completions.ChatCompletionMessageParam;
+type OAITool = OpenAI.Chat.Completions.ChatCompletionTool;
+
+export interface OpenAICompatConfig {
+  apiKey: string;
+  model: string;
+  /** Override for OpenAI-compatible endpoints (DeepSeek, Groq, Mistral, …). */
+  baseURL?: string;
+  temperature?: number;
+}
+
+function parseArgs(raw: string): Record<string, unknown> {
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+/** Serialize normalized history → OpenAI Chat Completions messages. */
+function toOpenAIMessages(messages: Message[]): OAIMessage[] {
+  return messages.map((m): OAIMessage => {
+    switch (m.role) {
+      case "system":
+        return { role: "system", content: m.content };
+      case "user":
+        return { role: "user", content: m.content };
+      case "assistant":
+        return m.tool_calls && m.tool_calls.length > 0
+          ? {
+              role: "assistant",
+              content: m.content || null,
+              tool_calls: m.tool_calls.map((tc) => ({
+                id: tc.id,
+                type: "function",
+                function: {
+                  name: tc.function.name,
+                  arguments: JSON.stringify(tc.function.arguments),
+                },
+              })),
+            }
+          : { role: "assistant", content: m.content };
+      case "tool":
+        return { role: "tool", tool_call_id: m.tool_call_id ?? "", content: m.content };
+      default: {
+        const _exhaustive: never = m.role;
+        throw new Error(`Unhandled message role: ${String(_exhaustive)}`);
+      }
+    }
+  });
+}
+
+function toOpenAITools(tools: ToolDefinition[]): OAITool[] {
+  return tools.map((t) => ({
+    type: "function",
+    function: {
+      name: t.function.name,
+      description: t.function.description,
+      parameters: t.function.parameters,
+    },
+  }));
+}
+
+/**
+ * Provider for any OpenAI-compatible Chat Completions endpoint.
+ * Used for OpenAI, DeepSeek, and other compatible servers via `baseURL`.
+ */
+export function makeOpenAICompatible(cfg: OpenAICompatConfig): Provider {
+  const client = new OpenAI({ apiKey: cfg.apiKey, baseURL: cfg.baseURL });
+  const temperature = cfg.temperature ?? 0;
+
+  return {
+    async chat(messages: Message[], tools: ToolDefinition[]): Promise<ChatResult> {
+      const res = await client.chat.completions.create({
+        model: cfg.model,
+        messages: toOpenAIMessages(messages),
+        tools: toOpenAITools(tools),
+        temperature,
+      });
+
+      const msg = res.choices[0]?.message;
+      const toolCalls = (msg?.tool_calls ?? []).flatMap((tc) =>
+        tc.type === "function"
+          ? [
+              {
+                id: tc.id,
+                function: { name: tc.function.name, arguments: parseArgs(tc.function.arguments) },
+              },
+            ]
+          : [],
+      );
+
+      return { content: msg?.content ?? "", toolCalls };
+    },
+  };
+}

package/src/ai/agent/types.ts

@@ -0,0 +1,65 @@
+// ---- Tool definitions (OpenAI-compatible JSON Schema) ----
+
+import type { z } from "zod";
+
+export interface ToolFunction {
+  name: string;
+  description: string;
+  parameters: {
+    type: "object";
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+}
+
+export interface ToolDefinition {
+  type: "function";
+  function: ToolFunction;
+}
+
+// ---- Unified tool (Zod schema + executor in one place) ----
+
+export interface Tool<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {
+  name: string;
+  description: string;
+  schema: TSchema;
+  execute: (args: z.infer<TSchema>) => Promise<unknown>;
+}
+
+// ---- Normalized messages (provider-agnostic) ----
+
+export interface ToolCall {
+  /** Correlation id. Synthesized for providers that omit one (Ollama). */
+  id: string;
+  function: {
+    name: string;
+    arguments: Record<string, unknown>;
+  };
+}
+
+export interface Message {
+  role: "system" | "user" | "assistant" | "tool";
+  content: string;
+  tool_calls?: ToolCall[];
+  /** Tool-result correlation id (OpenAI tool_call_id / Anthropic tool_use_id). */
+  tool_call_id?: string;
+  /** Tool name for Ollama tool-result messages. */
+  tool_name?: string;
+}
+
+// ---- Provider abstraction ----
+
+/** Normalized result of one chat turn, independent of provider wire format. */
+export interface ChatResult {
+  content: string;
+  toolCalls: ToolCall[];
+}
+
+/**
+ * A chat backend. Each implementation translates the normalized message/tool
+ * history to and from its provider's wire format. Stateless: the full message
+ * history is passed on every call.
+ */
+export interface Provider {
+  chat(messages: Message[], tools: ToolDefinition[]): Promise<ChatResult>;
+}