@graphorin/provider 0.6.1 → 0.7.0

package/src/adapters/llamacpp-server.ts

@@ -0,0 +1,102 @@
+/**
+ * Direct adapter for the upstream `llama-server` binary from the
+ * llama.cpp project. The binary speaks the OpenAI-compatible REST
+ * contract end-to-end (`POST /v1/chat/completions`, `POST /v1/completions`,
+ * `POST /v1/embeddings`); streaming is via `text/event-stream` chunks
+ * terminated by `data: [DONE]` exactly as the upstream OpenAI shape.
+ *
+ * The adapter shares a single `LocalProviderTrust` classifier with
+ * `ollamaAdapter` and `openAICompatibleAdapter` - one classifier, one
+ * policy table, one error type.
+ *
+ * @packageDocumentation
+ */
+
+import type { Provider, Sensitivity } from '@graphorin/core';
+
+import { buildOpenAIShapedProvider } from '../internal/openai-shaped.js';
+
+/**
+ * Default port used by the upstream `llama-server` binary.
+ *
+ * @stable
+ */
+export const DEFAULT_LLAMACPP_SERVER_BASE_URL = 'http://127.0.0.1:8080';
+
+/**
+ * Options accepted by {@link llamaCppServerAdapter}.
+ *
+ * @stable
+ */
+export interface LlamaCppServerAdapterOptions {
+  /** GGUF model identifier exposed by the running server (e.g. `'qwen2.5:7b-instruct-q4_k_m'`). */
+  readonly model: string;
+  /** Base URL of the running `llama-server` process. Defaults to `http://127.0.0.1:8080`. */
+  readonly baseUrl?: string;
+  /** Optional bearer-auth API key (`--api-key` flag on the server). */
+  readonly apiKey?: string;
+  /** Extra headers merged on top of `content-type` + `accept` defaults. */
+  readonly headers?: Readonly<Record<string, string>>;
+  /** Custom `fetch` implementation; useful for tests. */
+  readonly fetchImpl?: typeof fetch;
+  /**
+   * Time-to-response budget per request (PS-24). Default
+   * `DEFAULT_REQUEST_TIMEOUT_MS` (120s); `0` disables.
+   */
+  readonly timeoutMs?: number;
+  /** Capability overrides merged on top of the adapter defaults. */
+  readonly capabilities?: Partial<import('@graphorin/core').ProviderCapabilities>;
+  /**
+   * Acknowledge the risk of running over plaintext HTTP against a
+   * public host. Without this flag the adapter throws
+   * `LocalProviderInsecureTransportError`.
+   */
+  readonly allowInsecureTransport?: boolean;
+  /** Override for the default `acceptsSensitivity` value. */
+  readonly acceptsSensitivity?: ReadonlyArray<Sensitivity>;
+  /** Provider name attached to spans / log lines. */
+  readonly name?: string;
+  /** Optional log sink. Tests pass a fixture sink to silence the console. */
+  readonly logger?: (level: 'warn' | 'info', message: string, meta?: object) => void;
+}
+
+/**
+ * Build a Graphorin {@link Provider} backed by the upstream
+ * `llama-server` binary. The factory does not start the binary -
+ * operators launch it themselves with the desired model + GPU flags
+ * and pass the URL here.
+ *
+ * @example
+ * ```ts
+ * const local = createProvider(
+ *   llamaCppServerAdapter({
+ *     model: 'qwen2.5:7b-instruct-q4_k_m',
+ *     baseUrl: 'http://127.0.0.1:8080',
+ *   }),
+ * );
+ * ```
+ *
+ * @stable
+ */
+export function llamaCppServerAdapter(options: LlamaCppServerAdapterOptions): Provider {
+  const baseUrl = options.baseUrl ?? DEFAULT_LLAMACPP_SERVER_BASE_URL;
+  const providerName = options.name ?? `llamacpp-server-${options.model}`;
+  const built = buildOpenAIShapedProvider({
+    providerName,
+    model: options.model,
+    baseUrl,
+    ...(options.apiKey !== undefined ? { apiKey: options.apiKey } : {}),
+    ...(options.headers !== undefined ? { headers: options.headers } : {}),
+    ...(options.fetchImpl !== undefined ? { fetchImpl: options.fetchImpl } : {}),
+    ...(options.allowInsecureTransport !== undefined
+      ? { allowInsecureTransport: options.allowInsecureTransport }
+      : {}),
+    ...(options.acceptsSensitivity !== undefined
+      ? { acceptsSensitivity: options.acceptsSensitivity }
+      : {}),
+    ...(options.logger !== undefined ? { logger: options.logger } : {}),
+    ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+    capabilities: { multimodal: false, parallelToolCalls: false, ...options.capabilities },
+  });
+  return built.provider;
+}

package/src/adapters/ollama.ts

@@ -0,0 +1,382 @@
+/**
+ * Direct adapter for the Ollama HTTP API. The adapter speaks the
+ * native Ollama streaming JSON protocol (`POST /api/chat` returning
+ * newline-delimited JSON objects). For operators who prefer the
+ * OpenAI-compatible variant exposed by recent Ollama releases, the
+ * generic `openAICompatibleAdapter` is the better choice - both
+ * adapters share the same `LocalProviderTrust` classifier and
+ * {@link LocalProviderInsecureTransportError} startup behaviour.
+ *
+ * @packageDocumentation
+ */
+
+import { randomUUID } from 'node:crypto';
+import type {
+  FinishReason,
+  Provider,
+  ProviderCapabilities,
+  ProviderEvent,
+  ProviderRequest,
+  ProviderResponse,
+  Sensitivity,
+  Usage,
+} from '@graphorin/core';
+
+import { LocalProviderInsecureTransportError, ProviderStreamParseError } from '../errors/errors.js';
+import {
+  type ChatMessageConversionOptions,
+  callJsonHttp,
+  makeStreamStartEvent,
+  toOllamaChatMessages,
+} from '../internal/http.js';
+import { parseNdJsonStream } from '../internal/sse.js';
+import { stripTrailingSlashes } from '../internal/url-utils.js';
+import { applyReasoningPolicy } from '../reasoning/apply-policy.js';
+import { resolveReasoningRetention } from '../reasoning/retention.js';
+import { foldToolExamples } from '../tool-examples.js';
+import {
+  classifyLocalProvider,
+  type LocalProviderClassification,
+} from '../trust/classify-local-provider.js';
+
+/**
+ * Default Ollama base URL.
+ *
+ * @stable
+ */
+export const DEFAULT_OLLAMA_BASE_URL = 'http://127.0.0.1:11434';
+
+/**
+ * Options accepted by {@link ollamaAdapter}.
+ *
+ * @stable
+ */
+export interface OllamaAdapterOptions {
+  readonly model: string;
+  readonly baseUrl?: string;
+  readonly chatPath?: string;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly fetchImpl?: typeof fetch;
+  /**
+   * Time-to-response budget per request (PS-24). Default
+   * `DEFAULT_REQUEST_TIMEOUT_MS` (120s); `0` disables.
+   */
+  readonly timeoutMs?: number;
+  readonly allowInsecureTransport?: boolean;
+  readonly acceptsSensitivity?: ReadonlyArray<Sensitivity>;
+  readonly capabilities?: Partial<ProviderCapabilities>;
+  readonly name?: string;
+  readonly logger?: (level: 'warn' | 'info', message: string, meta?: object) => void;
+}
+
+const DEFAULT_CAPABILITIES: ProviderCapabilities = {
+  streaming: true,
+  toolCalling: true,
+  parallelToolCalls: false,
+  multimodal: false,
+  structuredOutput: true,
+  reasoning: false,
+  contextWindow: 8_192,
+  maxOutput: 4_096,
+  reasoningContract: 'optional',
+};
+
+/**
+ * Build a Graphorin {@link Provider} backed by Ollama's native HTTP
+ * API. The adapter is fail-safe by default: public-cleartext URLs
+ * refuse to start with `LocalProviderInsecureTransportError`.
+ *
+ * @stable
+ */
+export function ollamaAdapter(options: OllamaAdapterOptions): Provider {
+  const baseUrl = options.baseUrl ?? DEFAULT_OLLAMA_BASE_URL;
+  const classification = classifyLocalProvider(baseUrl);
+  if (classification.trust === 'public-cleartext' && options.allowInsecureTransport !== true) {
+    throw new LocalProviderInsecureTransportError(baseUrl);
+  }
+  const log = options.logger ?? defaultLogger;
+  emitTrustWarning(log, classification, baseUrl);
+  const acceptsSensitivity = options.acceptsSensitivity ?? classification.acceptsSensitivity;
+  const providerName = options.name ?? `ollama-${options.model}`;
+  const capabilities: ProviderCapabilities = {
+    ...DEFAULT_CAPABILITIES,
+    ...options.capabilities,
+  };
+  const chatPath = options.chatPath ?? '/api/chat';
+  const url = `${stripTrailingSlashes(baseUrl)}${chatPath}`;
+  return {
+    name: providerName,
+    modelId: options.model,
+    capabilities,
+    acceptsSensitivity,
+    stream(req) {
+      return streamOllama(options, providerName, url, applyOllamaPreflight(req, capabilities));
+    },
+    async generate(req) {
+      return generateOllama(options, providerName, url, applyOllamaPreflight(req, capabilities));
+    },
+  };
+}
+
+function applyOllamaPreflight(
+  req: ProviderRequest,
+  capabilities: ProviderCapabilities,
+): ProviderRequest {
+  const retention = resolveReasoningRetention({
+    ...(req.reasoningRetention !== undefined ? { requested: req.reasoningRetention } : {}),
+    ...(capabilities.reasoningContract !== undefined
+      ? { contract: capabilities.reasoningContract }
+      : {}),
+  });
+  if (retention === 'pass-through-all') return req;
+  const filtered = applyReasoningPolicy({ messages: req.messages, retention });
+  if (filtered === req.messages) return req;
+  return { ...req, messages: filtered };
+}
+
+async function* streamOllama(
+  options: OllamaAdapterOptions,
+  providerName: string,
+  url: string,
+  req: ProviderRequest,
+): AsyncIterable<ProviderEvent> {
+  const body = buildBody(
+    options.model,
+    req,
+    true,
+    options.capabilities?.structuredOutput ?? true,
+    conversionOptionsFor(options),
+  );
+  const resp = await callJsonHttp({
+    providerName,
+    url,
+    headers: buildHeaders(options),
+    body,
+    ...(req.signal !== undefined ? { signal: req.signal } : {}),
+    ...(options.fetchImpl !== undefined ? { fetchImpl: options.fetchImpl } : {}),
+    ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+  });
+  yield makeStreamStartEvent({ providerName, modelId: options.model });
+  let usage: Usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+  let finishReason: FinishReason = 'stop';
+  for await (const line of parseNdJsonStream(
+    resp.body,
+    req.signal !== undefined ? { signal: req.signal } : {},
+  )) {
+    if (req.signal?.aborted) {
+      finishReason = 'aborted'; // PS-12: honest abort reason, not 'stop'
+      break;
+    }
+    let chunk: OllamaChatChunk;
+    try {
+      chunk = JSON.parse(line) as OllamaChatChunk;
+    } catch (cause) {
+      throw new ProviderStreamParseError(
+        providerName,
+        `failed to parse ndjson line: ${(cause as Error).message}`,
+        cause,
+      );
+    }
+    if (chunk.message?.content !== undefined && chunk.message.content.length > 0) {
+      yield { type: 'text-delta', delta: chunk.message.content };
+    }
+    if (Array.isArray(chunk.message?.tool_calls)) {
+      for (const tc of chunk.message.tool_calls) {
+        const toolCallId = tc.id ?? `call_${randomUUID()}`;
+        const toolName = tc.function?.name ?? '';
+        if (toolName.length === 0) continue;
+        yield { type: 'tool-call-start', toolCallId, toolName };
+        yield {
+          type: 'tool-call-end',
+          toolCallId,
+          finalArgs: tc.function?.arguments ?? {},
+        };
+      }
+    }
+    if (chunk.done === true) {
+      finishReason = mapFinishReason(chunk.done_reason);
+      usage = mapUsage(chunk);
+      break;
+    }
+  }
+  yield { type: 'finish', finishReason, usage };
+}
+
+async function generateOllama(
+  options: OllamaAdapterOptions,
+  providerName: string,
+  url: string,
+  req: ProviderRequest,
+): Promise<ProviderResponse> {
+  const body = buildBody(
+    options.model,
+    req,
+    false,
+    options.capabilities?.structuredOutput ?? true,
+    conversionOptionsFor(options),
+  );
+  const resp = await callJsonHttp({
+    providerName,
+    url,
+    headers: buildHeaders(options),
+    body,
+    ...(req.signal !== undefined ? { signal: req.signal } : {}),
+    ...(options.fetchImpl !== undefined ? { fetchImpl: options.fetchImpl } : {}),
+    ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+  });
+  let json: OllamaChatChunk;
+  try {
+    json = (await resp.json()) as OllamaChatChunk;
+  } catch (cause) {
+    throw new ProviderStreamParseError(providerName, 'response body was not valid JSON', cause);
+  }
+  return {
+    usage: mapUsage(json),
+    finishReason: mapFinishReason(json.done_reason),
+    ...(typeof json.message?.content === 'string' && json.message.content.length > 0
+      ? { text: json.message.content }
+      : {}),
+    ...(Array.isArray(json.message?.tool_calls) && json.message.tool_calls.length > 0
+      ? {
+          toolCalls: json.message.tool_calls.map((tc) => ({
+            toolCallId: tc.id ?? `call_${randomUUID()}`,
+            toolName: tc.function?.name ?? '',
+            args: tc.function?.arguments ?? {},
+          })),
+        }
+      : {}),
+  };
+}
+
+function buildBody(
+  model: string,
+  req: ProviderRequest,
+  stream: boolean,
+  structuredOutput: boolean,
+  conversion: ChatMessageConversionOptions,
+): Record<string, unknown> {
+  const messages =
+    req.systemMessage !== undefined
+      ? [{ role: 'system' as const, content: req.systemMessage }, ...req.messages]
+      : req.messages;
+  const body: Record<string, unknown> = {
+    model,
+    messages: toOllamaChatMessages(messages, conversion),
+    stream,
+  };
+  if (req.temperature !== undefined || req.maxTokens !== undefined) {
+    const optionsBlock: Record<string, unknown> = {};
+    if (req.temperature !== undefined) optionsBlock.temperature = req.temperature;
+    if (req.maxTokens !== undefined) optionsBlock.num_predict = req.maxTokens;
+    body.options = optionsBlock;
+  }
+  if (req.tools !== undefined && req.tools.length > 0) {
+    // C2: fold worked examples in the adapter itself (idempotent when an
+    // upstream createProvider fold already ran).
+    body.tools = foldToolExamples(req.tools).map((t) => ({
+      type: 'function',
+      function: {
+        name: t.name,
+        ...(t.description !== undefined ? { description: t.description } : {}),
+        parameters: t.inputSchema,
+      },
+    }));
+  }
+  // PS-24: Ollama's native structured output - `format` takes a JSON
+  // schema object (or 'json' for schema-less JSON mode).
+  if (structuredOutput && req.outputType?.kind === 'structured') {
+    body.format = req.outputType.jsonSchema ?? 'json';
+  }
+  if (req.providerOptions !== undefined) {
+    Object.assign(body, req.providerOptions);
+  }
+  return body;
+}
+
+function buildHeaders(options: OllamaAdapterOptions): Record<string, string> {
+  return {
+    'content-type': 'application/json',
+    accept: 'application/json',
+    ...options.headers,
+  };
+}
+
+function mapFinishReason(value: string | null | undefined): FinishReason {
+  switch (value) {
+    case 'stop':
+    case 'length':
+      return value;
+    case 'tool_calls':
+      return 'tool-calls';
+    default:
+      return 'stop';
+  }
+}
+
+function mapUsage(chunk: OllamaChatChunk): Usage {
+  const promptTokens = chunk.prompt_eval_count ?? 0;
+  const completionTokens = chunk.eval_count ?? 0;
+  return {
+    promptTokens,
+    completionTokens,
+    totalTokens: promptTokens + completionTokens,
+  };
+}
+
+function emitTrustWarning(
+  log: (level: 'warn' | 'info', message: string, meta?: object) => void,
+  classification: LocalProviderClassification,
+  baseUrl: string,
+): void {
+  if (classification.trust === 'public-cleartext') {
+    log('warn', `[ollama] allowInsecureTransport=true accepted for ${baseUrl}`, { baseUrl });
+  } else if (classification.trust === 'public-tls') {
+    log('warn', `[ollama] public-TLS endpoint; treating as cloud-tier`, { baseUrl });
+  } else if (classification.trust === 'private') {
+    log('warn', `[ollama] private-network endpoint detected (${classification.reason})`, {
+      baseUrl,
+      acceptsSensitivity: classification.acceptsSensitivity,
+    });
+  }
+}
+
+function defaultLogger(level: 'warn' | 'info', message: string, meta?: object): void {
+  const fn = level === 'warn' ? console.warn : console.info;
+  if (meta !== undefined) {
+    fn(`[graphorin/provider] ${message}`, meta);
+  } else {
+    fn(`[graphorin/provider] ${message}`);
+  }
+}
+
+/** W-095: one dropped-content WARN per adapter instance. */
+const droppedContentWarned = new WeakSet<object>();
+
+function conversionOptionsFor(options: OllamaAdapterOptions): ChatMessageConversionOptions {
+  const log = options.logger ?? defaultLogger;
+  return {
+    multimodal: options.capabilities?.multimodal ?? false,
+    warn: (message) => {
+      if (droppedContentWarned.has(options)) return;
+      droppedContentWarned.add(options);
+      log('warn', message);
+    },
+  };
+}
+
+interface OllamaChatChunk {
+  readonly model?: string;
+  readonly created_at?: string;
+  readonly message?: {
+    readonly role?: string;
+    readonly content?: string;
+    readonly tool_calls?: ReadonlyArray<{
+      readonly id?: string;
+      readonly function?: { readonly name?: string; readonly arguments?: unknown };
+    }>;
+  };
+  readonly done?: boolean;
+  readonly done_reason?: string;
+  readonly prompt_eval_count?: number;
+  readonly eval_count?: number;
+}

package/src/adapters/openai-compatible.ts

@@ -0,0 +1,95 @@
+/**
+ * Generic OpenAI-compatible adapter - works against any HTTP server
+ * that speaks the `/v1/chat/completions` REST contract. Tested
+ * deployments include LMStudio (default port 1234), LocalAI (default
+ * port 8080), vLLM (`python -m vllm.entrypoints.openai.api_server`,
+ * default port 8000), Together-style self-host endpoints, and any
+ * other server in the OpenAI-compatible ecosystem.
+ *
+ * The adapter shares the same `LocalProviderTrust` classifier as
+ * `ollamaAdapter` and `llamaCppServerAdapter` - one classifier, one
+ * policy table, one error type.
+ *
+ * @packageDocumentation
+ */
+
+import type { Provider, ProviderCapabilities, Sensitivity } from '@graphorin/core';
+
+import { buildOpenAIShapedProvider } from '../internal/openai-shaped.js';
+
+/**
+ * Options accepted by {@link openAICompatibleAdapter}.
+ *
+ * @stable
+ */
+export interface OpenAICompatibleAdapterOptions {
+  /** Model identifier sent in the request body's `model` field. */
+  readonly model: string;
+  /**
+   * Base URL of the OpenAI-compatible server. The classifier inspects
+   * the protocol + host to assign a `LocalProviderTrust` value.
+   */
+  readonly baseUrl: string;
+  /** Optional REST path override. Defaults to `/v1/chat/completions`. */
+  readonly chatPath?: string;
+  /** Optional bearer-auth API key. */
+  readonly apiKey?: string;
+  /** Extra headers merged on top of `content-type` + `accept` defaults. */
+  readonly headers?: Readonly<Record<string, string>>;
+  /** Custom `fetch` implementation; useful for tests. */
+  readonly fetchImpl?: typeof fetch;
+  /**
+   * Acknowledge the risk of running over plaintext HTTP against a
+   * public host.
+   */
+  readonly allowInsecureTransport?: boolean;
+  /**
+   * Capability overrides merged on top of the adapter defaults
+   * (core-provider-10). Use them to widen `contextWindow` /
+   * `maxOutput` for large-context servers or to set
+   * `structuredOutput: false` for servers that reject
+   * `response_format`.
+   */
+  readonly capabilities?: Partial<ProviderCapabilities>;
+  /**
+   * Time-to-response budget per request (PS-24). Default 120s; `0`
+   * disables.
+   */
+  readonly timeoutMs?: number;
+  /** Override for the default `acceptsSensitivity` value. */
+  readonly acceptsSensitivity?: ReadonlyArray<Sensitivity>;
+  /** Provider name attached to spans / log lines. */
+  readonly name?: string;
+  /** Optional log sink. */
+  readonly logger?: (level: 'warn' | 'info', message: string, meta?: object) => void;
+}
+
+/**
+ * Build a Graphorin {@link Provider} backed by an OpenAI-compatible
+ * HTTP server. The same code path serves LMStudio, LocalAI, vLLM, and
+ * any other compatible self-host endpoint.
+ *
+ * @stable
+ */
+export function openAICompatibleAdapter(options: OpenAICompatibleAdapterOptions): Provider {
+  const providerName = options.name ?? `openai-compatible-${options.model}`;
+  const built = buildOpenAIShapedProvider({
+    providerName,
+    model: options.model,
+    baseUrl: options.baseUrl,
+    ...(options.chatPath !== undefined ? { chatPath: options.chatPath } : {}),
+    ...(options.apiKey !== undefined ? { apiKey: options.apiKey } : {}),
+    ...(options.headers !== undefined ? { headers: options.headers } : {}),
+    ...(options.fetchImpl !== undefined ? { fetchImpl: options.fetchImpl } : {}),
+    ...(options.allowInsecureTransport !== undefined
+      ? { allowInsecureTransport: options.allowInsecureTransport }
+      : {}),
+    ...(options.capabilities !== undefined ? { capabilities: options.capabilities } : {}),
+    ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+    ...(options.acceptsSensitivity !== undefined
+      ? { acceptsSensitivity: options.acceptsSensitivity }
+      : {}),
+    ...(options.logger !== undefined ? { logger: options.logger } : {}),
+  });
+  return built.provider;
+}