@kindgi/capabilities 0.0.0-bootstrap.0 → 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,498 @@
+import type { TenantId } from '@kindgi/types';
+/**
+ * The closed set of feature flags an agent can require. Matches
+ * `@kindgi/specs/capability.schema.json` FeatureRequirement enum. Providers self-
+ * report which of these they satisfy.
+ */
+export declare const FEATURES: readonly ["structured-output", "vision", "audio-input", "audio-output", "tool-use", "parallel-tool-use", "thinking", "long-context", "code-execution", "web-search", "file-search", "streaming", "batch"];
+export type Feature = (typeof FEATURES)[number];
+/** Comparison operator used by numeric requirements (context, cost, latency). */
+export type ComparisonOp = '>=' | '>' | '=' | '<=' | '<';
+/** Numeric-comparison-only operators (latency can only bound from above). */
+export type UpperBoundOp = '<=' | '<';
+/**
+ * One member of the Requirement union — hard constraints that MUST hold.
+ *
+ * `providers` filters on `ProviderMetadata.id` (vendor connection);
+ * `models` filters on `ModelInfo.name` (specific model within a
+ * connection). Both may appear in the same capability declaration —
+ * "any provider EXCEPT anthropic, and any model EXCEPT haiku."
+ */
+export type Requirement = {
+    readonly feature: Feature;
+} | {
+    readonly contextWindow: {
+        readonly op: ComparisonOp;
+        readonly value: number;
+    };
+} | {
+    readonly costPerCall: {
+        readonly op: ComparisonOp;
+        readonly usd: number;
+    };
+} | {
+    readonly region: string;
+} | {
+    readonly p95LatencyMs: {
+        readonly op: UpperBoundOp;
+        readonly value: number;
+    };
+} | {
+    readonly providers: {
+        readonly allow?: readonly string[];
+        readonly deny?: readonly string[];
+    };
+} | {
+    readonly models: {
+        readonly allow?: readonly string[];
+        readonly deny?: readonly string[];
+    };
+};
+/**
+ * A soft preference. Router filters by `needs` first, then ranks the
+ * survivors by summed weights of matched preferences.
+ *
+ * `feature` may be a canonical Feature name (e.g. `'thinking'`) or a
+ * soft attribute the provider self-reports (`'lower-cost'`,
+ * `'lower-latency'`, `'higher-accuracy'`, `'local'`, etc.). Weight can be
+ * negative (deprioritize).
+ */
+export interface Preference {
+    readonly feature: string;
+    readonly weight: number;
+}
+/**
+ * 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`).
+ */
+export interface Budget {
+    readonly maxCostUsd?: number;
+    readonly maxTokens?: number;
+    readonly maxDurationMs?: number;
+}
+/**
+ * A capability declaration. Every agent (or every model-invoking node)
+ * declares one; the router uses it to pick a provider.
+ *
+ * `kind` discriminates the resource type being requested. An absent
+ * value is equivalent to `'llm-inference'`. Non-LLM kinds (`embedding`, `gpu-compute`,
+ * `sandbox-exec`, `browser-session`) are declared here as strings so
+ * adapter packages can register providers of that kind without a
+ * schema break. The router filters providers by
+ * `metadata.capabilityKind === capability.kind`.
+ */
+export interface Capability {
+    readonly kind?: CapabilityKind;
+    readonly needs: readonly Requirement[];
+    readonly prefer?: readonly Preference[];
+    readonly budget?: Budget;
+}
+/**
+ * Open string discriminating capability kinds. Well-known values
+ * enumerated in `BUILT_IN_CAPABILITY_KINDS`. Adapters register
+ * providers of other kinds by declaring their own strings; the router
+ * matches strictly on equality.
+ */
+export type CapabilityKind = string;
+/** Well-known capability kinds — for enums, schema validation, docs. */
+export declare const BUILT_IN_CAPABILITY_KINDS: readonly ["llm-inference", "embedding", "gpu-compute", "sandbox-exec", "browser-session"];
+export type BuiltInCapabilityKind = (typeof BUILT_IN_CAPABILITY_KINDS)[number];
+/** Default kind used when Capability.kind is omitted. */
+export declare const DEFAULT_CAPABILITY_KIND: CapabilityKind;
+/**
+ * Structured rejection reason surfaced when a provider fails a
+ * requirement. Each variant carries `code` (for programmatic
+ * matching) and `message` (for logs). Downstream callers can
+ * `switch (r.code)` to route on specific failure modes without
+ * string-parsing.
+ *
+ * The router's requirement checks return this discriminated union
+ * (rather than a bare string) so consumers of
+ * `CapabilityUnsatisfiableError.reasons[].rejectingProviders[].reason`
+ * can inspect programmatically.
+ */
+export type RejectionReason = {
+    readonly code: 'missing-feature';
+    readonly message: string;
+    readonly feature: string;
+} | {
+    readonly code: 'context-window-mismatch';
+    readonly message: string;
+    readonly observed: number;
+    readonly op: ComparisonOp;
+    readonly wanted: number;
+} | {
+    readonly code: 'cost-exceeds-cap';
+    readonly message: string;
+    readonly observedUsdPer1k: number;
+    readonly op: ComparisonOp;
+    readonly wantedUsd: number;
+} | {
+    readonly code: 'region-mismatch';
+    readonly message: string;
+    readonly observed: string;
+    readonly wanted: string;
+} | {
+    readonly code: 'p95-latency-unknown';
+    readonly message: string;
+} | {
+    readonly code: 'p95-latency-exceeds';
+    readonly message: string;
+    readonly observedMs: number;
+    readonly op: UpperBoundOp;
+    readonly wantedMs: number;
+} | {
+    readonly code: 'provider-on-denylist';
+    readonly message: string;
+    readonly providerId: string;
+} | {
+    readonly code: 'provider-not-in-allowlist';
+    readonly message: string;
+    readonly providerId: string;
+    readonly allow: readonly string[];
+} | {
+    readonly code: 'model-on-denylist';
+    readonly message: string;
+    readonly modelName: string;
+} | {
+    readonly code: 'model-not-in-allowlist';
+    readonly message: string;
+    readonly modelName: string;
+    readonly allow: readonly string[];
+} | {
+    readonly code: 'tenant-denied';
+    readonly message: string;
+    readonly providerId: string;
+} | {
+    readonly code: 'tenant-not-allowed';
+    readonly message: string;
+    readonly providerId: string;
+} | {
+    readonly code: 'tenant-model-denied';
+    readonly message: string;
+    readonly modelName: string;
+} | {
+    readonly code: 'tenant-model-not-allowed';
+    readonly message: string;
+    readonly modelName: string;
+} | {
+    readonly code: 'tenant-region-not-allowed';
+    readonly message: string;
+    readonly observed: string;
+    readonly allow: readonly string[];
+} | {
+    readonly code: 'tenant-cost-cap-exceeded';
+    readonly message: string;
+    readonly observedUsd: number;
+    readonly capUsd: number;
+} | {
+    readonly code: 'capability-kind-mismatch';
+    readonly message: string;
+    readonly observed: CapabilityKind;
+    readonly wanted: CapabilityKind;
+} | {
+    readonly code: 'unknown-requirement';
+    readonly message: string;
+};
+/**
+ * Per-model metadata. A provider row exposes one or more models (e.g.
+ * Anthropic exposing Sonnet + Opus + Haiku under one API key); each
+ * `ModelInfo` describes one entry the router can select. The router
+ * picks a `(provider, model)` tuple per invocation, and the caller
+ * threads `ModelCallInput.model = <ModelInfo.name>` so the adapter
+ * knows which model to invoke.
+ *
+ * Adapters may widen `cost` via intersection types when they need
+ * vendor-specific fields (e.g. Anthropic prompt-cache multipliers) —
+ * the framework declares the mandatory shape, adapters extend.
+ */
+export interface ModelInfo {
+    /** Vendor-facing model id passed to the SDK (e.g. `claude-sonnet-4-6`). */
+    readonly name: string;
+    /** Context window in tokens. */
+    readonly contextWindow: number;
+    /** Features this model supports (tool-use, thinking, structured-output, ...). */
+    readonly features: readonly Feature[];
+    /**
+     * Cost per 1K tokens. Prompt + completion billed separately; both
+     * required. Denominated in USD.
+     */
+    readonly cost: {
+        readonly promptUsdPer1kTokens: number;
+        readonly completionUsdPer1kTokens: number;
+    };
+    /** Best-effort p95 latency estimate in ms — varies by model. */
+    readonly p95LatencyMs?: number;
+    /**
+     * Fallback cap on output tokens. Adapters that require max_tokens on
+     * every request (e.g. Anthropic) use this when
+     * `ModelCallInput.maxOutputTokens` is unset.
+     */
+    readonly maxOutputTokens?: number;
+    /** Short per-model description surfaced in logs. */
+    readonly description?: string;
+}
+/**
+ * What a `ModelProvider` reports about itself so the router can match
+ * capabilities against it without invoking. Static metadata — no side
+ * effects, no network. Every field is provider-declared and the router
+ * trusts it; misrepresentation is a provider bug.
+ *
+ * Provider-level fields (`id`, `region`, `attributes`) describe the
+ * connection; per-model fields (context window, cost, features) live
+ * under `models[]` so one connection can expose multiple models. The
+ * router picks a `(provider, model)` tuple per invocation.
+ */
+export interface ProviderMetadata {
+    readonly id: string;
+    /**
+     * Region the connection routes to. All models on this provider share
+     * the region (Vertex-AI-Anthropic vs Bedrock-Anthropic vs
+     * Anthropic-direct are separate provider rows, one per region).
+     * `'unspecified'` if not region-scoped.
+     */
+    readonly region: string;
+    /**
+     * Models this connection exposes. Non-empty — a provider with zero
+     * models is unusable and rejected at registration. `models[i].name`
+     * must be unique within the list.
+     */
+    readonly models: readonly ModelInfo[];
+    /**
+     * Soft attributes the provider self-reports for preference-ranking.
+     * Examples: `'local'`, `'lower-cost'`, `'higher-accuracy'`. Opaque to
+     * the router — matched by string equality against `Preference.feature`.
+     */
+    readonly attributes?: readonly string[];
+    /** Short human description of the connection surfaced in logs + errors. */
+    readonly description?: string;
+    /**
+     * Kind of resource this provider fulfils. Optional — an absent value
+     * defaults to `'llm-inference'`. Adapters for non-LLM kinds
+     * (embedding, GPU compute, sandboxes, ...) set this explicitly. The router filters providers by
+     * `metadata.capabilityKind === capability.kind`.
+     */
+    readonly capabilityKind?: CapabilityKind;
+    /**
+     * A fallback serves a capability only when no other provider
+     * satisfies it — e.g. `kindgi dev`'s scripted `dev-echo`, which keeps
+     * agent turns runnable until a real model is registered. A turn routed
+     * to one says so (`RoutingDecision.fallback`).
+     */
+    readonly fallback?: boolean;
+}
+/**
+ * A single message in a model call. Standardised wire shape — provider
+ * adapters translate to/from their vendor SDK format.
+ */
+export interface ModelMessage {
+    readonly role: 'system' | 'user' | 'assistant' | 'tool';
+    /** Text content. Tool-use payloads carry their own fields; text may be empty. */
+    readonly content: string;
+    /** For role='tool': the tool call id being responded to. */
+    readonly toolCallId?: string;
+    /** For role='assistant': tool calls the model wants executed. */
+    readonly toolCalls?: readonly ModelToolCall[];
+}
+export interface ModelToolCall {
+    readonly id: string;
+    readonly name: string;
+    /** JSON arguments as parsed object. */
+    readonly arguments: Readonly<Record<string, unknown>>;
+    /**
+     * An opaque token the provider attached to this call and needs back
+     * when the conversation continues — Gemini's thought signature, for
+     * example. Callers keep it with the call, unchanged; only the adapter
+     * that produced it reads it.
+     */
+    readonly signature?: string;
+}
+/** Tool definition passed to a model call — JSON-Schema-shaped, provider-neutral. */
+export interface ModelToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+}
+/**
+ * Structured-output request — the model returns JSON matching this
+ * schema. Shape aligns with OpenAI's `response_format.json_schema`.
+ *
+ * Adapter coverage:
+ *   - `@kindgi/adapter-model-openai-compat` — translates to
+ *     `response_format: { type: "json_schema", json_schema: { name,
+ *     schema, strict: true } }`.
+ *   - `@kindgi/adapter-model-anthropic` — ignores it (see that
+ *     package's README).
+ */
+export interface StructuredOutputRequest {
+    readonly name: string;
+    readonly schema: Readonly<Record<string, unknown>>;
+}
+/**
+ * The input to a model invocation. All fields provider-agnostic; each
+ * adapter translates to its vendor SDK format.
+ */
+export interface ModelCallInput {
+    /**
+     * Which model to invoke. Must match one of the receiving provider's
+     * `metadata.models[i].name`. Set by the caller from
+     * `RoutingDecision.model.name` (typical path) or hand-picked when
+     * the caller has a specific pin in mind. Adapters that don't
+     * recognize the name reject with an `unknown-model` error.
+     */
+    readonly model: string;
+    readonly messages: readonly ModelMessage[];
+    readonly tools?: readonly ModelToolDefinition[];
+    readonly structuredOutput?: StructuredOutputRequest;
+    /** Sampling controls — providers translate to their equivalent. */
+    readonly temperature?: number;
+    readonly maxOutputTokens?: number;
+    /** Cooperative cancellation. Handlers should observe. */
+    readonly abortSignal?: AbortSignal;
+}
+/** Usage counters — used by the cost meter. */
+export interface UsageCounters {
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    /** Some providers report cached tokens separately. Optional. */
+    readonly cachedTokens?: number;
+}
+/**
+ * The result of a model invocation. `finishReason` matches OpenAI-style
+ * conventions; adapters normalize to this set.
+ */
+export interface ModelCallResult {
+    readonly message: ModelMessage;
+    readonly finishReason: 'stop' | 'length' | 'tool-use' | 'content-filter' | 'error';
+    readonly usage: UsageCounters;
+    /**
+     * Denominated in USD. Provider computes this from the actual token
+     * usage against its cost table. Cost meter uses it directly rather
+     * than re-computing (in case pricing changes between adapter
+     * versions).
+     */
+    readonly costUsd: number;
+    readonly durationMs: number;
+    /** Provider + model actually invoked (in case the router picked a variant). */
+    readonly provider: {
+        readonly id: string;
+        readonly model: string;
+    };
+}
+/**
+ * A registered provider — metadata + invoke function. Registered once at
+ * pack init; invoked many times by the router.
+ */
+export interface ModelProvider {
+    readonly metadata: ProviderMetadata;
+    invoke(input: ModelCallInput): Promise<ModelCallResult>;
+}
+/**
+ * Registry the router consults. Tenant-scoped: each tenant owns its
+ * own set of registered providers, and the router only sees a
+ * tenant's slice.
+ *
+ * Isolation model:
+ *   - Isolation across tenants is enforced here (not by after-the-fact
+ *     policy filtering).
+ *   - A deployment either (a) runs one Kindgi instance per tenant
+ *     with its own set of registered providers, or (b) runs a shared
+ *     instance where the framework registers per-tenant provider
+ *     entries — same adapter binary, different keys per tenant (each
+ *     provider closes over that tenant's secrets).
+ *   - `TenantPolicy` still narrows the visible set at routing time
+ *     (allow/deny lists, cost caps, region gates) — that stays
+ *     orthogonal to tenant isolation.
+ *
+ * This aligns with the storage-side `ProviderRegistryBinding` (in
+ * `@kindgi/api`), whose methods all take `tenantId`. A registry backed
+ * by that storage reads persisted provider metadata and instantiates
+ * providers through an `AdapterFactoryRegistry`.
+ */
+export interface ProviderRegistry {
+    register(tenantId: TenantId, provider: ModelProvider): void;
+    get(tenantId: TenantId, id: string): ModelProvider | undefined;
+    list(tenantId: TenantId): readonly ModelProvider[];
+    has(tenantId: TenantId, id: string): boolean;
+    /**
+     * Optional async warm-up. Storage-backed implementations
+     * hydrate their per-tenant instance cache from the persistent
+     * `ProviderRegistryBinding` on the first call for a given tenant;
+     * the agent runtime awaits this before the sync `list(tenantId)` call
+     * so the router sees the full set. In-memory implementations that
+     * hold their state eagerly leave this undefined, and callers skip it.
+     *
+     * Idempotent: hydrating an already-hydrated tenant returns
+     * immediately.
+     */
+    hydrate?(tenantId: TenantId): Promise<void>;
+    /**
+     * Optional cache invalidation. Storage-backed implementations call
+     * this from the provider write path (register, unregister) so the
+     * next `hydrate(tenantId)` re-reads from the persistent store.
+     * Without it, a provider registered after boot is persisted but the
+     * cache keeps serving the providers loaded at boot. In-memory
+     * implementations leave it undefined — no cache to invalidate.
+     */
+    invalidate?(tenantId: TenantId): void;
+}
+/**
+ * Per-tenant policy the router honors on top of the capability
+ * declaration. Every field optional; empty policy = "no additional
+ * constraints."
+ *
+ * `providers.allow` is a positive list of provider ids; if present,
+ * only listed providers are eligible — an empty list allows none.
+ * `providers.deny` excludes. `models.allow` / `models.deny` do the same
+ * at the model level (e.g. "tenant may use anthropic but not opus").
+ * Deny wins over allow where the two overlap at either level.
+ *
+ * `regionAllow` narrows to specific provider regions; an empty list
+ * allows none.
+ * `maxCostPerCallUsd` caps per-invocation cost using the picked
+ * model's `promptUsdPer1kTokens` as the cheap proxy.
+ * `maxTokensPerCall` caps the picked model's context window.
+ */
+export interface TenantPolicy {
+    readonly tenantId: TenantId;
+    readonly providers?: {
+        readonly allow?: readonly string[];
+        readonly deny?: readonly string[];
+    };
+    readonly models?: {
+        readonly allow?: readonly string[];
+        readonly deny?: readonly string[];
+    };
+    readonly regionAllow?: readonly string[];
+    readonly maxCostPerCallUsd?: number;
+    readonly maxTokensPerCall?: number;
+}
+/** A `(provider, model)` tuple as picked by the router. */
+export interface ProviderModelPick {
+    readonly provider: ModelProvider;
+    readonly model: ModelInfo;
+}
+/**
+ * The router's decision output. Returns a `(provider, model)` tuple —
+ * the picked connection AND the picked model within it. Callers thread
+ * `ModelCallInput.model = decision.model.name` when invoking
+ * `provider.invoke`.
+ */
+export interface RoutingDecision {
+    readonly provider: ModelProvider;
+    readonly model: ModelInfo;
+    readonly reason: string;
+    /**
+     * Alternate tuples in ranked order. Useful for failover — if the top
+     * pick throws or hits a rate limit, the caller can retry with the
+     * next.
+     */
+    readonly alternates: readonly ProviderModelPick[];
+    /**
+     * `true` when only fallback providers (`ProviderMetadata.fallback`)
+     * satisfy the capability, so the pick is one of them.
+     */
+    readonly fallback: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * The closed set of feature flags an agent can require. Matches
+ * `@kindgi/specs/capability.schema.json` FeatureRequirement enum. Providers self-
+ * report which of these they satisfy.
+ */
+export const FEATURES = [
+    'structured-output',
+    'vision',
+    'audio-input',
+    'audio-output',
+    'tool-use',
+    'parallel-tool-use',
+    'thinking',
+    'long-context',
+    'code-execution',
+    'web-search',
+    'file-search',
+    'streaming',
+    'batch',
+];
+/** Well-known capability kinds — for enums, schema validation, docs. */
+export const BUILT_IN_CAPABILITY_KINDS = [
+    'llm-inference',
+    'embedding',
+    'gpu-compute',
+    'sandbox-exec',
+    'browser-session',
+];
+/** Default kind used when Capability.kind is omitted. */
+export const DEFAULT_CAPABILITY_KIND = 'llm-inference';
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAIjC;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,mBAAmB;IACnB,QAAQ;IACR,aAAa;IACb,cAAc;IACd,UAAU;IACV,mBAAmB;IACnB,UAAU;IACV,cAAc;IACd,gBAAgB;IAChB,YAAY;IACZ,aAAa;IACb,WAAW;IACX,OAAO;CACC,CAAC;AAkFX,wEAAwE;AACxE,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,eAAe;IACf,WAAW;IACX,aAAa;IACb,cAAc;IACd,iBAAiB;CACT,CAAC;AAGX,yDAAyD;AACzD,MAAM,CAAC,MAAM,uBAAuB,GAAmB,eAAe,CAAC"}

package/package.json

@@ -1,7 +1,55 @@
 {
   "name": "@kindgi/capabilities",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Placeholder so a trusted publisher can be attached. Releases are published from https://github.com/kindgi/kindgi-sdk with provenance; use 0.1.0 or later.",
+  "version": "0.1.0",
+  "description": "Capability declarations + provider router for Kindgi™. Agents declare what they need from a model (features such as structured-output or tool-use, context window, cost, region, latency, provider and model allow/deny lists) and what they prefer; the router picks a registered (provider, model) pair that satisfies every hard constraint plus tenant policy, ranked by soft preferences, and reports per requirement which candidates it rejected when none qualify. Also the provider-neutral ModelProvider contract, a tenant-scoped provider registry, and an adapter-factory registry. Capability kinds are open strings matched by equality; llm-inference is the default.",
   "license": "Apache-2.0",
-  "repository": { "type": "git", "url": "git+https://github.com/kindgi/kindgi-sdk.git" }
-}
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kindgi/kindgi-sdk.git",
+    "directory": "packages/capabilities"
+  },
+  "homepage": "https://github.com/kindgi/kindgi-sdk/tree/main/packages/capabilities#readme",
+  "bugs": {
+    "url": "https://github.com/kindgi/kindgi-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "SPEC.md",
+    "type-manifest.json"
+  ],
+  "dependencies": {
+    "@kindgi/platform": "0.1.0",
+    "@kindgi/schema": "0.1.0",
+    "@kindgi/types": "0.1.0"
+  },
+  "devDependencies": {
+    "@kindgi/specs": "0.1.0",
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}