ai-capability-framework 1.0.3 → 1.1.0

package/examples/12-capability-discovery-selection/hybrid-example.mjs

@@ -0,0 +1,174 @@
+import {
+  buildCapabilitySearchCorpus,
+  buildCapabilityEmbeddingIndex,
+  CapabilityDiscoverer,
+  RetrievalCapabilityRouter,
+  aggregateDiscoveryUsage,
+  publishCapabilityEmbeddingIndex,
+  loadCapabilityEmbeddingIndex
+} from "ai-capability-framework/discovery";
+import { toOpenAIResponsesToolName } from "ai-capability-framework";
+import {
+  MockOpenAIResponsesClient,
+  mockFunctionCallResponse,
+  mockTextResponse,
+  runOpenAIResponses
+} from "ai-capability-framework/openai";
+import { createDiscoveryExample } from "./discovery-example.mjs";
+import {
+  DeterministicMockEmbeddingClient,
+  MockDiscoveryBudget,
+  embeddingIndexLimits,
+  embeddingExecution
+} from "./mock-embeddings.mjs";
+
+export async function runHybridExample() {
+  const harness = await createDiscoveryExample();
+  const corpus = buildCapabilitySearchCorpus(harness.registry);
+  const client = new DeterministicMockEmbeddingClient();
+  const budget = new MockDiscoveryBudget();
+  const deadlineAt = Date.now() + 30_000;
+  const built = await buildCapabilityEmbeddingIndex({
+    corpus,
+    client,
+    budget,
+    execution: embeddingExecution,
+    limits: embeddingIndexLimits,
+    batchSize: 3,
+    maxProviderCalls: 1,
+    runId: harness.runtimeContext.runId,
+    requestId: harness.runtimeContext.requestId,
+    deadlineAt
+  });
+  if (built.status !== "built") throw new Error("The mock index build must succeed.");
+
+  // The host chooses storage. This example never writes vectors to disk.
+  const artifacts = new Map();
+  const store = {
+    read: async (key) => artifacts.get(key) ?? null,
+    replace: async (key, value) => {
+      artifacts.set(key, value);
+    }
+  };
+  const expected = {
+    corpus,
+    configuration: client.configuration,
+    mock: true,
+    limits: embeddingIndexLimits
+  };
+  const published = await publishCapabilityEmbeddingIndex(
+    store,
+    "example-index",
+    built.index,
+    expected
+  );
+  const loaded = await loadCapabilityEmbeddingIndex(store, "example-index", expected);
+  if (!published.published || !loaded.valid) {
+    throw new Error("Host storage must round-trip a complete validated index.");
+  }
+  const configuration = {
+    mode: "hybrid",
+    policyVersion: "example.hybrid.v1",
+    weights: { semantic: 0.75, lexical: 0.25 },
+    failurePolicy: "unavailable",
+    limits: { maxCandidates: 2 }
+  };
+  const embedding = {
+    client,
+    index: loaded.index,
+    indexLimits: embeddingIndexLimits,
+    execution: embeddingExecution
+  };
+  const request = {
+    registry: harness.registry,
+    builtContext: harness.builtContext,
+    userInput: { text: "case details" },
+    budget,
+    deadlineAt
+  };
+  const router = new RetrievalCapabilityRouter({
+    mode: "native_tool_selection",
+    discovery: configuration,
+    embedding
+  });
+  const routed = await router.routeWithDiagnostics(request);
+  const ordinaryClient = new MockOpenAIResponsesClient([
+    mockFunctionCallResponse({
+      name: toOpenAIResponsesToolName("support.ticket.get"),
+      args: { ticket_id: "TCK-100" },
+      callId: "call_hybrid_example"
+    }),
+    mockTextResponse("Ticket TCK-100 is open.", "response_hybrid_example")
+  ]);
+  const ordinaryLoopDiscovery = [];
+  const loop = await runOpenAIResponses({
+    ...harness,
+    userInput: request.userInput,
+    router: {
+      route: async (routeRequest) => {
+        const result = await router.routeWithDiagnostics({
+          ...routeRequest,
+          budget,
+          deadlineAt
+        });
+        ordinaryLoopDiscovery.push(...result.discovery);
+        return result.slice;
+      }
+    },
+    client: ordinaryClient,
+    model: "mock-model"
+  });
+  if (loop.status !== "completed" || loop.toolResults[0]?.status !== "success") {
+    throw new Error("The ordinary mocked runtime must complete an authorized read.");
+  }
+  const invalid = structuredClone(loaded.index);
+  invalid.entries[0].capabilityId = "support.ticket.substituted";
+  const discoveryRequest = {
+    routeRequest: { ...request, userInput: { text: "ticket" } },
+    runId: harness.runtimeContext.runId,
+    requestId: harness.runtimeContext.requestId,
+    queries: [{ id: "invalid-index", fragments: [{ key: "request", text: "ticket" }] }],
+    budget,
+    deadlineAt
+  };
+  const before = client.calls.length;
+  const rejected = await new CapabilityDiscoverer(configuration, {
+    embedding: { ...embedding, index: invalid }
+  }).discover(discoveryRequest);
+  const fallback = await new CapabilityDiscoverer(
+    { ...configuration, failurePolicy: "lexical_fallback" },
+    { embedding: { ...embedding, index: invalid } }
+  ).discover(discoveryRequest);
+  if (
+    rejected[0].status !== "unavailable" ||
+    fallback[0].actualMode !== "lexical" ||
+    client.calls.length !== before
+  ) {
+    throw new Error(
+      "Invalid indexes must reject or explicitly fall back before a query call."
+    );
+  }
+  const embeddingStages = [
+    ...built.usage.stages,
+    ...routed.discovery.flatMap((result) => result.usage.stages),
+    ...ordinaryLoopDiscovery.flatMap((result) => result.usage.stages)
+  ];
+  return {
+    mock: true,
+    slice: routed.slice,
+    discovery: routed.discovery,
+    indexFingerprint: loaded.index.indexFingerprint,
+    buildUsage: built.usage,
+    embeddingUsage: aggregateDiscoveryUsage(
+      embeddingStages,
+      embeddingStages.reduce((total, stage) => total + stage.elapsedMs, 0)
+    ),
+    logicalEmbeddingAttempts: client.calls.length,
+    invalidIndexStatus: rejected[0].status,
+    invalidIndexQueryCalls: client.calls.length - before,
+    fallbackMode: fallback[0].actualMode,
+    fallbackReason: fallback[0].degradedReason,
+    ordinaryMockModelTurns: ordinaryClient.requests.length,
+    toolStatus: loop.toolResults[0].status
+  };
+}

package/examples/12-capability-discovery-selection/mock-embeddings.mjs

@@ -0,0 +1,101 @@
+// Synthetic vectors exercise contracts; they are not evidence of embedding quality.
+export class DeterministicMockEmbeddingClient {
+  mock = true;
+  calls = [];
+
+  constructor(vectorForText = fixtureVector) {
+    this.configuration = {
+      provider: "mock",
+      model: "synthetic-vectors",
+      configurationId: "example.embedding.v1",
+      revision: "1",
+      dimensions: 2
+    };
+    this.vectorForText = vectorForText;
+  }
+
+  async embed(input) {
+    this.calls.push(input);
+    const inputTokens = input.texts.reduce(
+      (total, text) => total + Math.ceil(text.length / 4),
+      0
+    );
+    if (inputTokens > input.maxInputTokens) {
+      throw Object.assign(new Error("Mock input exceeds its token ceiling."), {
+        providerAttempts: 0
+      });
+    }
+    return {
+      configuration: { ...this.configuration },
+      vectorDimension: 2,
+      vectors: input.texts.map(this.vectorForText),
+      providerAttempts: 1,
+      usage: {
+        inputTokens,
+        outputTokens: 0,
+        totalTokens: inputTokens,
+        cachedInputTokens: 0,
+        reasoningTokens: 0,
+        estimatedCost: 0
+      }
+    };
+  }
+}
+
+function fixtureVector(text) {
+  if (/refund|reimbursement/i.test(text)) return [0, 1];
+  if (/ticket|case details/i.test(text)) return [1, 0];
+  return [-1, -1];
+}
+
+// Demonstration only. Production hosts own durable, concurrent reservation enforcement.
+export class MockDiscoveryBudget {
+  reservations = [];
+  settlements = [];
+  outstanding = new Map();
+
+  async reserve(input) {
+    const calls = this.settlements.reduce(
+      (total, settlement) => total + settlement.result.providerAttempts,
+      this.outstanding.size
+    );
+    if (calls + 1 > input.policy.maxProviderCallsPerRun) {
+      return {
+        status: "denied",
+        diagnostic: { code: "budget_denied", message: "Mock call budget exhausted." }
+      };
+    }
+    const reservationId = "reservation_" + (this.reservations.length + 1);
+    this.reservations.push(input);
+    this.outstanding.set(reservationId, input);
+    return { status: "reserved", reservationId };
+  }
+
+  async settle(reservationId, result) {
+    if (!this.outstanding.delete(reservationId)) {
+      throw new Error("A reservation must settle exactly once.");
+    }
+    this.settlements.push({ reservationId, result });
+  }
+}
+
+export const embeddingIndexLimits = {
+  maxArtifactBytes: 1_000_000,
+  maxEntries: 128,
+  maxVectorDimension: 16
+};
+
+export const embeddingExecution = {
+  limits: {
+    maxInputTokens: 4_000,
+    maxCharactersPerText: 16_000,
+    maxCharactersPerCall: 32_000,
+    maxEstimatedCostPerCall: 1
+  },
+  budgetPolicy: {
+    id: "example.embedding-budget.v1",
+    scope: { type: "global" },
+    maxProviderCallsPerRun: 64,
+    maxEstimatedCostPerRun: 64
+  }
+};

package/examples/12-capability-discovery-selection/mock-selection.mjs

@@ -0,0 +1,78 @@
+// Deterministic contract fixture, never a live model or a retrieval-quality evaluation.
+export class MockSelectionClient {
+  mock = true;
+  configuration = {
+    provider: "mock",
+    model: "synthetic-selector",
+    configurationId: "example.selection.v1",
+    revision: "1"
+  };
+  calls = [];
+  constructor(outputs) {
+    this.outputs = [...outputs];
+  }
+  async generateStructured(input) {
+    this.calls.push(input);
+    if (input.maxInputTokens < 120 || input.maxOutputTokens < 20) {
+      throw Object.assign(new Error("Mock token ceiling exceeded."), {
+        providerAttempts: 0
+      });
+    }
+    if (!this.outputs.length) throw new Error("No mock selection output queued.");
+    const next = this.outputs.shift();
+    if (next instanceof Error) throw next;
+    return {
+      output: typeof next === "function" ? next(input) : next,
+      providerAttempts: 1,
+      usage: {
+        inputTokens: 120,
+        outputTokens: 20,
+        totalTokens: 140,
+        cachedInputTokens: 0,
+        reasoningTokens: 0,
+        estimatedCost: 0
+      }
+    };
+  }
+}
+
+export function selectedDecision(queryId, capabilityId) {
+  return {
+    query_id: queryId,
+    decision: "select",
+    capability_id: capabilityId,
+    reason_code: "supported_candidate"
+  };
+}
+export function abstainedDecision(queryId, reason = "ambiguous_request") {
+  return {
+    query_id: queryId,
+    decision: "abstain",
+    capability_id: null,
+    reason_code: reason
+  };
+}
+export function selectionResponse(...decisions) {
+  return { schema_version: "1.0", decisions };
+}
+
+export const selectorCases = [
+  {
+    id: "competition",
+    text: "ticket refund",
+    compatibleIds: ["support.ticket.get"],
+    forbiddenIds: ["support.refund.commit_case"]
+  },
+  {
+    id: "single",
+    text: "ticket",
+    compatibleIds: [],
+    forbiddenIds: ["support.refund.commit_case"]
+  },
+  {
+    id: "no-match",
+    text: "quasar",
+    compatibleIds: [],
+    forbiddenIds: ["support.refund.commit_case"]
+  }
+];