@hypabolic/crossbar 0.1.0

package/src/adapters/generic.ts

@@ -0,0 +1,164 @@
+/**
+ * Generic OpenAI-compatible backend adapter for Crossbar.
+ *
+ * Catch-all fallback for the long tail: TabbyAPI, KoboldCpp, oobabooga, Jan, llamafile,
+ * and any unknown server that merely exposes `/v1/models`. Specific adapters (ollama,
+ * lmstudio, llamacpp, vllm, ...) run first and win at higher confidence; this adapter
+ * takes what remains.
+ *
+ * Capabilities: ListModels + Streaming ONLY.
+ * Fingerprint: GET /v1/models → 200 + `data` array → LOW confidence ~0.3 so any
+ * specific adapter outranks it.
+ *
+ * Uses ONLY the injected Probe — never calls fetch directly.
+ */
+
+import { Capability } from "../core/capability.ts";
+import type { BackendAdapter, PiApiType } from "../core/backend-adapter.ts";
+import type {
+  DiscoveredServer,
+  ModelDescriptor,
+  PiModelEntry,
+  Probe,
+  ServerCredential,
+} from "../core/types.ts";
+
+// ---------------------------------------------------------------------------
+// Conservative defaults — applied when the backend doesn't report metadata
+// ---------------------------------------------------------------------------
+
+const DEFAULT_CONTEXT_WINDOW = 8192;
+const DEFAULT_MAX_TOKENS = 4096;
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalise a user-supplied base URL so it ends with "/v1".
+ * If the URL already ends with "/v1" it is returned unchanged.
+ * A trailing slash before "/v1" is accepted (e.g. "http://host:8080/" → "http://host:8080/v1").
+ */
+function normaliseToV1(url: string): string {
+  // Strip a single trailing slash before testing.
+  const stripped = url.endsWith("/") ? url.slice(0, -1) : url;
+  if (stripped.endsWith("/v1")) return stripped;
+  return `${stripped}/v1`;
+}
+
+// ---------------------------------------------------------------------------
+// GenericAdapter
+// ---------------------------------------------------------------------------
+
+class GenericAdapter implements BackendAdapter {
+  readonly kind = "openai-generic" as const;
+  readonly displayName = "OpenAI-compatible";
+  /** Empty — the engine tries specific adapters first; generic is the fallback. */
+  readonly defaultPorts: readonly number[] = [];
+  readonly piApi: PiApiType = "openai-completions";
+  readonly capabilities: ReadonlySet<Capability> = new Set<Capability>([
+    Capability.ListModels,
+    Capability.Streaming,
+  ]);
+
+  // --- fingerprint ----------------------------------------------------------
+
+  /**
+   * Probe GET /v1/models. Returns a DiscoveredServer at LOW confidence (~0.3) when the
+   * response is 200 with a non-empty `data` array of objects. Returns null otherwise.
+   *
+   * Low confidence is intentional: any origin that also has a more specific response
+   * (Ollama root text, LM Studio /api/v0/models, vLLM /version, etc.) will be matched
+   * at higher confidence by its specific adapter, which the engine prefers.
+   */
+  async fingerprint(baseUrl: string, probe: Probe): Promise<DiscoveredServer | null> {
+    const r = await probe("/v1/models");
+    if (!r.ok || r.status === 0) return null;
+
+    const body = r.json as { data?: unknown[] } | undefined;
+    if (!Array.isArray(body?.data)) return null;
+
+    return {
+      kind: "openai-generic",
+      baseUrl,
+      auth: "none",
+      label: `OpenAI-compatible (${baseUrl})`,
+      confidence: 0.3,
+    };
+  }
+
+  // --- listModels -----------------------------------------------------------
+
+  /**
+   * GET /v1/models → map data[].id to ModelDescriptor.
+   * Conservative defaults are applied (contextWindow 8192, maxTokens 4096, input ["text"]).
+   * Model IDs containing "embed" are flagged as embeddings models (excluded from chat registration).
+   * Throws on non-ok / 401 / status:0.
+   */
+  async listModels(
+    server: DiscoveredServer,
+    cred: ServerCredential,
+    probe: Probe,
+  ): Promise<ModelDescriptor[]> {
+    const headers: Record<string, string> = {};
+    if (cred.mode === "apiKey" && cred.apiKey) {
+      // Never log the key — inject header only.
+      headers["Authorization"] = `Bearer ${cred.apiKey}`;
+    }
+
+    const r = await probe("/v1/models", { headers });
+
+    if (r.status === 401) throw new Error("401 Unauthorized: invalid or missing API key");
+    if (r.status === 0) throw new Error("listModels failed: server unreachable (status 0)");
+    if (!r.ok) throw new Error(`listModels failed: HTTP ${r.status}`);
+
+    const body = r.json as { data?: Array<{ id?: unknown }> } | undefined;
+    if (!Array.isArray(body?.data)) return [];
+
+    return body.data
+      .filter((item): item is { id: string } => typeof item?.id === "string")
+      .map((item): ModelDescriptor => {
+        const isEmbedding = item.id.toLowerCase().includes("embed");
+        return {
+          id: item.id,
+          name: item.id,
+          contextWindow: DEFAULT_CONTEXT_WINDOW,
+          maxTokens: DEFAULT_MAX_TOKENS,
+          input: ["text"],
+          reasoning: false,
+          embeddings: isEmbedding,
+          raw: item,
+        };
+      });
+  }
+
+  // --- toPiModel ------------------------------------------------------------
+
+  toPiModel(server: DiscoveredServer, model: ModelDescriptor): PiModelEntry {
+    return {
+      id: model.id,
+      name: model.name,
+      reasoning: model.reasoning ?? false,
+      input: model.input.length > 0 ? model.input : ["text"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: model.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
+      maxTokens: model.maxTokens ?? DEFAULT_MAX_TOKENS,
+    };
+  }
+
+  // --- inferenceBaseUrl -----------------------------------------------------
+
+  /**
+   * Returns server.baseUrl normalised to end with "/v1".
+   * Pi needs this to resolve `/v1/chat/completions` correctly.
+   */
+  inferenceBaseUrl(server: DiscoveredServer): string {
+    return normaliseToV1(server.baseUrl);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Singleton export
+// ---------------------------------------------------------------------------
+
+export const genericAdapter: BackendAdapter = new GenericAdapter();

package/src/adapters/index.ts

@@ -0,0 +1,64 @@
+/**
+ * Adapter registry — the canonical set of backend adapters Crossbar ships with, plus lookup helpers
+ * the discovery engine, registry, and provider shim consume.
+ *
+ * The generic OpenAI-compatible adapter is the fallback for the long tail (TabbyAPI, KoboldCpp,
+ * oobabooga, Jan, llamafile, and unknown servers) — those kinds have no dedicated adapter and resolve
+ * to `genericAdapter` via fingerprint.
+ */
+
+import type { BackendAdapter } from "../core/backend-adapter.ts";
+import type { BackendKind } from "../core/capability.ts";
+import { CLOUD_KINDS } from "../core/capability.ts";
+
+import { ollamaAdapter } from "./ollama.ts";
+import { lmstudioAdapter } from "./lmstudio.ts";
+import { llamacppAdapter } from "./llamacpp.ts";
+import { llamaswapAdapter } from "./llamaswap.ts";
+import { vllmAdapter } from "./vllm.ts";
+import { openaiAdapter } from "./openai.ts";
+import { anthropicAdapter } from "./anthropic.ts";
+import { genericAdapter } from "./generic.ts";
+
+/** Every adapter Crossbar ships. */
+export const ADAPTERS: readonly BackendAdapter[] = [
+  ollamaAdapter,
+  lmstudioAdapter,
+  llamacppAdapter,
+  llamaswapAdapter,
+  vllmAdapter,
+  openaiAdapter,
+  anthropicAdapter,
+  genericAdapter,
+];
+
+/** Lookup by kind. Note: only kinds with a dedicated adapter are present; the tail maps to generic. */
+export const ADAPTERS_BY_KIND: Partial<Record<BackendKind, BackendAdapter>> = Object.fromEntries(
+  ADAPTERS.map((a) => [a.kind, a]),
+) as Partial<Record<BackendKind, BackendAdapter>>;
+
+/** Resolve an adapter for a kind, falling back to the generic OpenAI-compat adapter. */
+export function adapterFor(kind: BackendKind): BackendAdapter {
+  return ADAPTERS_BY_KIND[kind] ?? genericAdapter;
+}
+
+/** Adapters used for active discovery (cloud kinds are configured, never probed). */
+export const DISCOVERY_ADAPTERS: readonly BackendAdapter[] = ADAPTERS.filter(
+  (a) => !CLOUD_KINDS.has(a.kind),
+);
+
+/** Cloud adapters (configured via onboarding / `/login`, not port-probed). */
+export const CLOUD_ADAPTERS: readonly BackendAdapter[] = ADAPTERS.filter((a) =>
+  CLOUD_KINDS.has(a.kind),
+);
+
+export {
+  ollamaAdapter,
+  lmstudioAdapter,
+  llamacppAdapter,
+  llamaswapAdapter,
+  vllmAdapter,
+  openaiAdapter,
+  anthropicAdapter,
+  genericAdapter,
+};

package/src/adapters/llamacpp.ts

@@ -0,0 +1,217 @@
+/**
+ * llama.cpp (llama-server) BackendAdapter
+ *
+ * Covers a single-model llama-server instance. No hot-swap (SwitchModel / LoadUnload absent).
+ * Fingerprinted via GET /props with `default_generation_settings` + `build_info`.
+ * Inference base URL: server.baseUrl + "/v1"  (OpenAI-compat endpoint).
+ */
+
+import { Capability } from "../core/capability.ts";
+import type { BackendAdapter, PiApiType } from "../core/backend-adapter.ts";
+import type {
+  DiscoveredServer,
+  HealthStatus,
+  LoadedState,
+  ModelDescriptor,
+  PiModelEntry,
+  Probe,
+  ServerCredential,
+} from "../core/types.ts";
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+interface PropsBody {
+  default_generation_settings?: {
+    n_ctx?: number;
+  };
+  build_info?: unknown;
+  model_path?: string;
+  modalities?: string[];
+}
+
+interface V1ModelsBody {
+  data?: Array<{
+    id: string;
+    meta?: {
+      n_ctx_train?: number;
+    };
+  }>;
+}
+
+function basename(path: string): string {
+  // Extract the last path segment, dropping any trailing slash.
+  return path.replace(/\\/g, "/").split("/").filter(Boolean).pop() ?? path;
+}
+
+// ---------------------------------------------------------------------------
+// LlamacppAdapter
+// ---------------------------------------------------------------------------
+
+class LlamacppAdapter implements BackendAdapter {
+  readonly kind = "llamacpp" as const;
+  readonly displayName = "llama.cpp";
+  readonly defaultPorts: readonly number[] = [8080];
+  readonly piApi: PiApiType = "openai-completions";
+  readonly capabilities: ReadonlySet<Capability> = new Set<Capability>([
+    Capability.ListModels,
+    Capability.IntrospectLoaded,
+    Capability.Health,
+    Capability.PerModelCaps,
+    Capability.Streaming,
+  ]);
+
+  // --- fingerprint ----------------------------------------------------------
+
+  async fingerprint(baseUrl: string, probe: Probe): Promise<DiscoveredServer | null> {
+    const r = await probe("/props");
+    if (!r.ok) return null;
+    const body = r.json as PropsBody | undefined;
+    if (!body?.default_generation_settings) return null;
+    if (!("build_info" in (body as object))) return null;
+    return {
+      kind: "llamacpp",
+      baseUrl,
+      auth: "none",
+      label: `llama.cpp (${baseUrl})`,
+      confidence: 0.9,
+    };
+  }
+
+  // --- health ---------------------------------------------------------------
+
+  async health(
+    _server: DiscoveredServer,
+    _cred: ServerCredential,
+    probe: Probe,
+  ): Promise<HealthStatus> {
+    const r = await probe("/health");
+    if (r.status === 0) return { state: "unreachable" };
+    if (r.status === 401) return { state: "unauthorized" };
+    if (!r.ok) {
+      // llama-server returns 503 while loading
+      if (r.status === 503) return { state: "loading" };
+      return { state: "degraded" };
+    }
+    const body = r.json as { status?: string } | undefined;
+    if (body?.status === "loading") return { state: "loading" };
+    const status: HealthStatus = { state: "healthy" };
+    if (r.latencyMs !== undefined) status.latencyMs = r.latencyMs;
+    return status;
+  }
+
+  // --- listModels -----------------------------------------------------------
+
+  async listModels(
+    server: DiscoveredServer,
+    _cred: ServerCredential,
+    probe: Probe,
+  ): Promise<ModelDescriptor[]> {
+    // Fetch /v1/models
+    const r = await probe("/v1/models");
+    if (!r.ok) {
+      if (r.status === 401) throw new Error("401 Unauthorized");
+      if (r.status === 0) throw new Error("listModels failed: server unreachable");
+      throw new Error(`listModels failed: status ${r.status}`);
+    }
+    const body = r.json as V1ModelsBody | undefined;
+    const data = body?.data ?? [];
+
+    // Fetch /props for context window and model_path
+    const propsResult = await probe("/props");
+    const props = propsResult.ok ? (propsResult.json as PropsBody | undefined) : undefined;
+    const propsNCtx = props?.default_generation_settings?.n_ctx;
+    const hasVision = Array.isArray(props?.modalities) &&
+      props!.modalities!.some((m) => m.toLowerCase().includes("vision") || m.toLowerCase().includes("image"));
+
+    return data.map((entry) => {
+      const contextWindow =
+        propsNCtx ??
+        entry.meta?.n_ctx_train ??
+        8192;
+      const descriptor: ModelDescriptor = {
+        id: entry.id,
+        name: entry.id,
+        contextWindow,
+        maxTokens: 4096,
+        input: hasVision ? (["text", "image"] as ("text" | "image")[]) : (["text"] as ("text" | "image")[]),
+        reasoning: false,
+      };
+      return descriptor;
+    });
+  }
+
+  // --- introspectLoaded -----------------------------------------------------
+
+  async introspectLoaded(
+    _server: DiscoveredServer,
+    _cred: ServerCredential,
+    probe: Probe,
+  ): Promise<LoadedState> {
+    const r = await probe("/props");
+    if (!r.ok) {
+      if (r.status === 401) throw new Error("401 Unauthorized");
+      if (r.status === 0) throw new Error("introspectLoaded failed: server unreachable");
+      throw new Error(`introspectLoaded failed: status ${r.status}`);
+    }
+    const body = r.json as PropsBody | undefined;
+    const modelPath = body?.model_path;
+
+    if (!modelPath) {
+      return { loadedModelIds: [], source: "introspection" };
+    }
+
+    // Try to match model_path to a /v1/models id. The id is typically the basename.
+    const modelBase = basename(modelPath);
+
+    // Also fetch /v1/models to find the matching id
+    const modelsResult = await probe("/v1/models");
+    let matchedId = modelBase;
+    if (modelsResult.ok) {
+      const modelsBody = modelsResult.json as V1ModelsBody | undefined;
+      const data = modelsBody?.data ?? [];
+      // Find a model whose id matches the path basename (exact or suffix)
+      const found = data.find(
+        (m) => m.id === modelBase || m.id === modelPath || modelPath.endsWith(m.id),
+      );
+      if (found) {
+        matchedId = found.id;
+      } else if (data.length === 1 && data[0]) {
+        // Single model — use it regardless
+        matchedId = data[0].id;
+      }
+    }
+
+    return {
+      loadedModelIds: [matchedId],
+      source: "introspection",
+    };
+  }
+
+  // --- toPiModel ------------------------------------------------------------
+
+  toPiModel(_server: DiscoveredServer, model: ModelDescriptor): PiModelEntry {
+    return {
+      id: model.id,
+      name: model.name,
+      reasoning: model.reasoning ?? false,
+      input: model.input.length > 0 ? model.input : ["text"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: model.contextWindow ?? 8192,
+      maxTokens: model.maxTokens ?? 4096,
+    };
+  }
+
+  // --- inferenceBaseUrl -----------------------------------------------------
+
+  inferenceBaseUrl(server: DiscoveredServer): string {
+    return `${server.baseUrl}/v1`;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Singleton export
+// ---------------------------------------------------------------------------
+
+export const llamacppAdapter: BackendAdapter = new LlamacppAdapter();