@kindgi/capabilities 0.0.0-bootstrap.0 → 0.1.0

package/src/adapter-factory.ts

@@ -0,0 +1,155 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { ModelProvider, ProviderMetadata } from './types.js';
+
+/**
+ * In-process factory-function registry — the code-side counterpart of a
+ * persistent adapter registry (`AdapterRegistryBinding` in
+ * `@kindgi/api`). A store can hold adapter records but not JavaScript
+ * functions, so the runtime keeps a Map keyed by the same adapter id
+ * the stored record uses.
+ *
+ * Populated at boot by deployment code, in lockstep with the adapters
+ * it registers in storage. A storage-backed provider registry reads a
+ * tenant's stored providers, looks up each one's adapter id here, calls
+ * the factory to instantiate a `ModelProvider`, and caches the result.
+ *
+ * Failure surfaces:
+ *   - A stored provider references an adapter id with no in-process
+ *     factory (deployment forgot to register it, or a boot ordering
+ *     bug) → `get(adapterId)` returns `undefined`, and the provider
+ *     registry fails the invocation with a clear error.
+ *   - Factory throws at construction time → propagates through the
+ *     provider registry to the caller.
+ */
+export interface AdapterFactoryEntry {
+  /** Adapter identifier — MUST equal the id of the stored adapter record. */
+  readonly adapterId: string;
+  /** Capability kind this adapter fulfils (`'llm-inference'`, `'embedding'`, ...). */
+  readonly capabilityKind: string;
+  readonly factory: AdapterFactory;
+  /**
+   * Optional download / warmup step. Adapters that need
+   * expensive one-time setup (in-process model downloads, ONNX
+   * runtime warmup, cache preheating) implement this; adapters that
+   * only need config-time construction leave it undefined.
+   *
+   * Streams `PrepareEvent`s so the caller (HTTP SSE endpoint,
+   * console progress bar) can render progress. Framework doesn't
+   * cache — implementations decide whether re-invoking `prepare` on
+   * an already-prepared adapter is a no-op or a re-check.
+   *
+   * `params` shape is adapter-specific — the framework passes it
+   * through unchanged (e.g. `{model: 'smollm2-360m'}` for
+   * in-process).
+   */
+  readonly prepare?: (params?: Readonly<Record<string, unknown>>) => AsyncIterable<PrepareEvent>;
+}
+
+/**
+ * Event stream emitted by `AdapterFactoryEntry.prepare()`. Shape kept
+ * deliberately open (`message` + optional numeric progress fields)
+ * so adapters with different progress models (byte-count download,
+ * step-count warmup, cache hit ratio) can populate what they know.
+ * Consumers render whichever fields are present.
+ */
+export type PrepareEvent =
+  | {
+      readonly kind: 'progress';
+      readonly message?: string;
+      /** Ratio in [0, 1] when known; absent for indeterminate progress. */
+      readonly ratio?: number;
+      readonly loadedBytes?: number;
+      readonly totalBytes?: number;
+      readonly file?: string;
+    }
+  | { readonly kind: 'ready'; readonly message?: string }
+  | { readonly kind: 'error'; readonly message: string };
+
+/**
+ * Input passed to an adapter factory at instantiation time. The
+ * provider registry composes the arguments from persisted state (the
+ * stored provider `metadata`) plus a pre-bound `resolveApiKey` closure
+ * that reads the tenant-scoped secret store.
+ *
+ * Adapters that don't need credentials (dev-echo, in-process
+ * models) receive no `resolveApiKey` — they ignore the field
+ * entirely.
+ */
+export interface AdapterFactoryInput {
+  readonly metadata: ProviderMetadata;
+  /**
+   * How the adapter connects — the provider's adapter-specific,
+   * non-secret settings (a cloud project, a base URL), as registered
+   * with the provider. Credentials never go here; they come from
+   * `resolveApiKey`. Each adapter documents and validates its own keys.
+   */
+  readonly config?: AdapterConfig;
+  /**
+   * Lazy API-key resolver. Adapters that need external
+   * credentials pass this into their SDK client construction (or
+   * refresh on every invoke, as
+   * `@kindgi/adapter-model-anthropic` does).
+   */
+  readonly resolveApiKey?: () => Promise<string>;
+  /**
+   * The fetch for a provider endpoint the registration chose (a base URL).
+   * The runtime passes one that refuses the hosts its deployment forbids
+   * (`KINDGI_TENANT_HOST_ACCESS`: the cloud metadata endpoints and the
+   * server's own host). Absent: the global `fetch`.
+   */
+  readonly fetch?: typeof fetch;
+}
+
+/** An adapter's connection settings: flat, non-secret values. */
+export type AdapterConfig = Readonly<Record<string, string | number | boolean>>;
+
+export type AdapterFactory = (input: AdapterFactoryInput) => ModelProvider;
+
+export interface AdapterFactoryRegistry {
+  register(entry: AdapterFactoryEntry): void;
+  get(adapterId: string): AdapterFactoryEntry | undefined;
+  has(adapterId: string): boolean;
+  list(): readonly AdapterFactoryEntry[];
+}
+
+/**
+ * Create an in-memory `AdapterFactoryRegistry`. Global
+ * (deployment-scoped) — every tenant reads from the same map because
+ * adapter code is code, not user data.
+ *
+ * Duplicate registrations under the same `adapterId` throw at
+ * `register` time; accidental clobber of a running factory would be
+ * catastrophic. Deployments call `register` once per shipped adapter
+ * at boot.
+ */
+export function createAdapterFactoryRegistry(
+  seed: readonly AdapterFactoryEntry[] = [],
+): AdapterFactoryRegistry {
+  const entries = new Map<string, AdapterFactoryEntry>();
+
+  function register(entry: AdapterFactoryEntry): void {
+    if (entries.has(entry.adapterId)) {
+      throw new Error(
+        `AdapterFactoryRegistry: "${entry.adapterId}" is already registered. Duplicate adapter registration at boot indicates a wiring bug.`,
+      );
+    }
+    entries.set(entry.adapterId, entry);
+  }
+
+  for (const entry of seed) register(entry);
+
+  return {
+    register,
+    get(adapterId): AdapterFactoryEntry | undefined {
+      return entries.get(adapterId);
+    },
+    has(adapterId): boolean {
+      return entries.has(adapterId);
+    },
+    list(): readonly AdapterFactoryEntry[] {
+      return [...entries.values()];
+    },
+  };
+}

package/src/capability.schema.json

@@ -0,0 +1,250 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kindgi.com/schemas/v1/capability.schema.json",
+  "$comment": "schema-version: 1.1.0",
+  "title": "Capability declaration",
+  "description": "An agent's model requirements as declarative constraints. The model router matches capabilities against registered providers, respecting per-tenant policy. `defineCapability` validates a declaration against this schema; a declaration that no registered provider satisfies fails at routing time with `capability-unsatisfiable`.",
+  "type": "object",
+  "required": ["needs"],
+  "additionalProperties": false,
+  "properties": {
+    "kind": {
+      "type": "string",
+      "minLength": 1,
+      "default": "llm-inference",
+      "examples": ["llm-inference", "embedding", "gpu-compute", "sandbox-exec", "browser-session"],
+      "description": "Resource kind this capability requests. Open string: `examples` lists the well-known kinds, and adapters can declare their own. Absent means `llm-inference`. The router only considers providers whose `capabilityKind` equals it (a provider that declares none counts as `llm-inference`). Added in schema-version 1.1.0."
+    },
+    "needs": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/Requirement"
+      }
+    },
+    "prefer": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/Preference"
+      },
+      "description": "Soft preferences: the router picks the highest-scoring model that also satisfies all 'needs'."
+    },
+    "budget": {
+      "$ref": "#/$defs/Budget",
+      "description": "Per-invocation budget. Declarative: carried with the declaration but not enforced by the runtime (per-turn spend is capped by the agent's `budget.maxCostUsd`)."
+    }
+  },
+  "$defs": {
+    "Requirement": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/FeatureRequirement"
+        },
+        {
+          "$ref": "#/$defs/ContextRequirement"
+        },
+        {
+          "$ref": "#/$defs/CostRequirement"
+        },
+        {
+          "$ref": "#/$defs/RegionRequirement"
+        },
+        {
+          "$ref": "#/$defs/LatencyRequirement"
+        },
+        {
+          "$ref": "#/$defs/ProviderRequirement"
+        },
+        {
+          "$ref": "#/$defs/ModelRequirement"
+        }
+      ]
+    },
+    "FeatureRequirement": {
+      "type": "object",
+      "required": ["feature"],
+      "additionalProperties": false,
+      "properties": {
+        "feature": {
+          "type": "string",
+          "enum": [
+            "structured-output",
+            "vision",
+            "audio-input",
+            "audio-output",
+            "tool-use",
+            "parallel-tool-use",
+            "thinking",
+            "long-context",
+            "code-execution",
+            "web-search",
+            "file-search",
+            "streaming",
+            "batch"
+          ]
+        }
+      }
+    },
+    "ContextRequirement": {
+      "type": "object",
+      "required": ["contextWindow"],
+      "additionalProperties": false,
+      "properties": {
+        "contextWindow": {
+          "type": "object",
+          "required": ["op", "value"],
+          "additionalProperties": false,
+          "properties": {
+            "op": {
+              "type": "string",
+              "enum": [">=", ">", "=", "<=", "<"]
+            },
+            "value": {
+              "type": "integer",
+              "minimum": 1
+            }
+          }
+        }
+      }
+    },
+    "CostRequirement": {
+      "type": "object",
+      "required": ["costPerCall"],
+      "additionalProperties": false,
+      "properties": {
+        "costPerCall": {
+          "type": "object",
+          "required": ["op", "usd"],
+          "additionalProperties": false,
+          "properties": {
+            "op": {
+              "type": "string",
+              "enum": [">=", ">", "=", "<=", "<"]
+            },
+            "usd": {
+              "type": "number",
+              "minimum": 0
+            }
+          }
+        }
+      }
+    },
+    "RegionRequirement": {
+      "type": "object",
+      "required": ["region"],
+      "additionalProperties": false,
+      "properties": {
+        "region": {
+          "type": "string",
+          "description": "Geographic region constraint (e.g. 'eu-only', 'us-only', 'us-gov'). Enforced by the router against each provider's declared region; a tenant policy's `regionAllow` can constrain it further."
+        }
+      }
+    },
+    "LatencyRequirement": {
+      "type": "object",
+      "required": ["p95LatencyMs"],
+      "additionalProperties": false,
+      "properties": {
+        "p95LatencyMs": {
+          "type": "object",
+          "required": ["op", "value"],
+          "additionalProperties": false,
+          "properties": {
+            "op": {
+              "type": "string",
+              "enum": ["<=", "<"]
+            },
+            "value": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        }
+      }
+    },
+    "ProviderRequirement": {
+      "type": "object",
+      "required": ["providers"],
+      "additionalProperties": false,
+      "description": "Hard constraint on allowed providers (allowlist) or disallowed providers (denylist). Tenant policy can narrow the set further.",
+      "properties": {
+        "providers": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "allow": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "deny": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "ModelRequirement": {
+      "type": "object",
+      "required": ["models"],
+      "additionalProperties": false,
+      "description": "Hard constraint on allowed models (allowlist) or disallowed models (denylist), matched against each provider's model names (`ModelInfo.name`). Can be combined with a providers requirement. Tenant policy can narrow the set further. Added in schema-version 1.1.0.",
+      "properties": {
+        "models": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "allow": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "deny": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "Preference": {
+      "type": "object",
+      "required": ["feature", "weight"],
+      "additionalProperties": false,
+      "properties": {
+        "feature": {
+          "type": "string",
+          "description": "A capability feature or a soft attribute (e.g. 'lower-cost', 'lower-latency', 'higher-accuracy')."
+        },
+        "weight": {
+          "type": "number"
+        }
+      }
+    },
+    "Budget": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "maxCostUsd": {
+          "type": "number",
+          "minimum": 0
+        },
+        "maxTokens": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "maxDurationMs": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    }
+  }
+}

package/src/define.ts

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { createSpecRegistry } from '@kindgi/schema';
+import type { SpecRegistry } from '@kindgi/schema';
+import type { Result } from '@kindgi/types';
+
+import capabilitySchema from './capability.schema.json' with { type: 'json' };
+import type { InvalidCapabilityError } from './errors.js';
+import type { Capability } from './types.js';
+
+const CAPABILITY_SCHEMA_ID = 'https://kindgi.com/schemas/v1/capability.schema.json';
+
+let cachedRegistry: SpecRegistry | undefined;
+function registry(): SpecRegistry {
+  if (cachedRegistry !== undefined) return cachedRegistry;
+  const built = createSpecRegistry([capabilitySchema]);
+  if (built.kind === 'err') {
+    throw new Error(
+      `@kindgi/capabilities: bundled schema failed to compile: ${built.error.message}`,
+    );
+  }
+  cachedRegistry = built.value;
+  return cachedRegistry;
+}
+
+/**
+ * Validate a capability declaration against `@kindgi/specs/capability.schema.json`
+ * and return a typed `Capability` on success. Called by pack authors at
+ * agent construction — a rejection here surfaces at pack init, well
+ * before any user request touches the flow.
+ */
+export function defineCapability(spec: Capability): Result<Capability, InvalidCapabilityError> {
+  const r = registry().validate<Capability>(CAPABILITY_SCHEMA_ID, spec);
+  if (r.kind === 'ok') return r;
+  const err = r.error;
+  if (err.code !== 'validation-error') {
+    throw new Error(`@kindgi/capabilities: unexpected schema error ${err.code}: ${err.message}`);
+  }
+  const issues = err.errors.map((e) => {
+    const ajv = e as { instancePath?: unknown; message?: unknown };
+    return {
+      path: typeof ajv.instancePath === 'string' ? ajv.instancePath : '',
+      message: typeof ajv.message === 'string' ? ajv.message : 'validation failed',
+    };
+  });
+  return {
+    kind: 'err',
+    error: { code: 'invalid-capability', message: err.message, issues },
+  };
+}
+
+/** The `$id` of the JSON Schema this loader validates against. */
+export const CAPABILITY_SCHEMA_URI = CAPABILITY_SCHEMA_ID;

package/src/errors.ts

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { TenantId } from '@kindgi/types';
+
+/**
+ * Errors emitted by @kindgi/capabilities. Every variant carries a `code`
+ * for pattern matching; messages are human-readable, not API contract.
+ */
+export type CapabilityError =
+  | InvalidCapabilityError
+  | InvalidProviderError
+  | DuplicateProviderError
+  | CapabilityUnsatisfiableError
+  | BudgetExceededError;
+
+/** `defineCapability` rejected the declaration shape (schema mismatch). */
+export interface InvalidCapabilityError {
+  readonly code: 'invalid-capability';
+  readonly message: string;
+  readonly issues: readonly { readonly path: string; readonly message: string }[];
+}
+
+/** Provider registration (`createProviderRegistry(...).register`) rejected the metadata shape. */
+export interface InvalidProviderError {
+  readonly code: 'invalid-provider';
+  readonly message: string;
+  readonly reason: string;
+}
+
+/** Provider registration was called with an id already registered for the tenant. */
+export interface DuplicateProviderError {
+  readonly code: 'duplicate-provider';
+  readonly message: string;
+  readonly providerId: string;
+}
+
+/**
+ * The router couldn't find any provider satisfying the capability
+ * declaration + tenant policy. `reasons` explains which requirement
+ * rejected which `(provider, model)` candidate.
+ */
+export interface CapabilityUnsatisfiableError {
+  readonly code: 'capability-unsatisfiable';
+  readonly message: string;
+  /**
+   * One entry per requirement, indicating which providers matched
+   * and which didn't. Each rejection carries a structured
+   * `RejectionReason` — callers can `switch (r.reason.code)` to route
+   * on specific failure modes (e.g. surface an "add region" tip when
+   * every failure is `region-mismatch`).
+   */
+  readonly reasons: readonly {
+    readonly requirement: string;
+    readonly satisfyingProviders: readonly string[];
+    readonly rejectingProviders: readonly {
+      readonly id: string;
+      readonly reason: import('./types.js').RejectionReason;
+    }[];
+  }[];
+  readonly tenantId?: TenantId;
+}
+
+/**
+ * A model invocation exceeded the caller's declared `budget`. Cost meter
+ * emits this either pre-flight (if the estimated cost is already over
+ * budget) or post-flight (if actual cost overran).
+ */
+export interface BudgetExceededError {
+  readonly code: 'budget-exceeded';
+  readonly message: string;
+  readonly limit: { readonly kind: 'cost' | 'tokens' | 'duration'; readonly value: number };
+  readonly actual: number;
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+export { createAdapterFactoryRegistry } from './adapter-factory.js';
+export type {
+  AdapterConfig,
+  AdapterFactory,
+  AdapterFactoryEntry,
+  AdapterFactoryInput,
+  AdapterFactoryRegistry,
+  PrepareEvent,
+} from './adapter-factory.js';
+export { CAPABILITY_SCHEMA_URI, defineCapability } from './define.js';
+export { createProviderRegistry } from './registry.js';
+export { matchTuples, route } from './router.js';
+export type { RouteInput } from './router.js';
+export { BUILT_IN_CAPABILITY_KINDS, DEFAULT_CAPABILITY_KIND, FEATURES } from './types.js';
+export type {
+  Budget,
+  BuiltInCapabilityKind,
+  Capability,
+  CapabilityKind,
+  ComparisonOp,
+  Feature,
+  ModelCallInput,
+  ModelCallResult,
+  ModelMessage,
+  ModelInfo,
+  ModelProvider,
+  ModelToolCall,
+  ModelToolDefinition,
+  Preference,
+  ProviderMetadata,
+  ProviderModelPick,
+  ProviderRegistry,
+  RejectionReason,
+  Requirement,
+  RoutingDecision,
+  StructuredOutputRequest,
+  TenantPolicy,
+  UpperBoundOp,
+  UsageCounters,
+} from './types.js';
+export type {
+  BudgetExceededError,
+  CapabilityError,
+  CapabilityUnsatisfiableError,
+  DuplicateProviderError,
+  InvalidCapabilityError,
+  InvalidProviderError,
+} from './errors.js';