@jambonz/llm 0.1.0

package/dist/test-kit/index.d.ts

@@ -0,0 +1,162 @@
+import { a as AdapterFactory, d as AuthKind, A as AuthSpec, l as LlmEvent, M as Message, L as LlmAdapter, c as ApiKeyAuth, g as ClientOptions, P as PromptRequest, n as ModelInfo, b as AdapterManifest } from '../types-D8rgMCbi.js';
+
+/**
+ * Named scenarios the harness must be able to stage. Each scenario configures
+ * the vendor mock to produce a specific response the next time `stream()` is
+ * called. The kit calls `harness.mockScenario(name)` before running a test.
+ */
+type ContractScenario = 
+/** 3+ text tokens then end('stop'). No tools. */
+'simple-stream'
+/** A single tool call (no content) then end('tool'). */
+ | 'tool-call'
+/** Content tokens, then a tool call, then end('tool'). */
+ | 'tool-call-after-tokens'
+/** 10+ text tokens yielded slowly (>= 20ms apart) then end('stop'). */
+ | 'long-stream'
+/**
+ * Stream that would produce a tool call, but with enough delay before the
+ * tool call arrives that the kit can fire an abort in the middle.
+ * Expected behavior: on abort, no toolCall event fires; end('aborted') is yielded.
+ */
+ | 'long-stream-with-pending-tool'
+/** `listAvailableModels()` returns at least 2 models. */
+ | 'list-models';
+/**
+ * A vendor-agnostic view of the most recent request the adapter sent upstream.
+ * The harness captures whatever the vendor wire actually contained and exposes
+ * a normalized view so the kit can assert on it without vendor knowledge.
+ */
+interface CapturedRequest {
+    /** System prompt as the adapter forwarded it (top-level, injected-into-messages, or missing). */
+    system?: string;
+    /** Number of non-system messages forwarded. */
+    messageCount: number;
+    /** True if any message's vendorRaw contents appear to have influenced the wire request. */
+    vendorRawHonored: boolean;
+}
+/**
+ * Harness an adapter provides so the contract kit can run. Adapter authors
+ * implement this once for their adapter, then call `runContractTests(harness)`.
+ *
+ * The harness hides vendor-specific concerns (SDK mocking, wire format,
+ * credential shapes) behind a small uniform surface.
+ */
+interface ContractHarness {
+    /** Machine-readable vendor id. Used in test descriptions only. */
+    vendor: string;
+    /** The factory under test. */
+    factory: AdapterFactory;
+    /**
+     * Return a valid AuthSpec for each `AuthKind` the adapter's manifest declares.
+     * Called once per declared kind during the "accepts declared auth kinds" check.
+     * Values need not be real credentials — mocks don't care.
+     */
+    authFor(kind: AuthKind): AuthSpec;
+    /**
+     * An AuthSpec that the adapter MUST reject via `init()`. Typically a kind the
+     * adapter does not accept. Return `null` if the adapter truly accepts every
+     * AuthKind (unusual — check #4 will be skipped).
+     */
+    unsupportedAuth: AuthSpec | null;
+    /**
+     * Configure the vendor mock for the named scenario. Called before each
+     * behavioral test. The next `stream()` or `listAvailableModels()` call will
+     * return the scenario's canned response.
+     */
+    mockScenario(scenario: ContractScenario): void | Promise<void>;
+    /**
+     * Clean up mocks between tests. Called in an `afterEach`. Safe to call even
+     * if no scenario is active.
+     */
+    cleanup(): void | Promise<void>;
+    /**
+     * Return a normalized view of the most recent wire request the adapter sent
+     * upstream, or null if no request has been made since the last cleanup().
+     */
+    getCapturedRequest(): CapturedRequest | null;
+    /** A model id in `knownModels` whose capabilities.tools is true. */
+    toolCapableModel: string;
+    /**
+     * A model id whose capabilities.tools is false, for check #16. Return null if
+     * the adapter has no non-tool-capable models in its manifest — the check is
+     * then skipped.
+     */
+    nonToolCapableModel: string | null;
+    /**
+     * Does this adapter emit `toolCallStart` events? If true, check #12
+     * (toolCallStart precedes toolCall) runs; if false, that check is skipped.
+     */
+    emitsToolCallStart: boolean;
+    /**
+     * Construct an assistant `Message` (with `vendorRaw` populated in the shape
+     * THIS adapter expects back on re-submission) given a `toolCall` event the
+     * adapter previously emitted. Used by checks #13 and #20 to round-trip a
+     * realistic history through a subsequent `stream()` call.
+     *
+     * Implementation tip: set `vendorRaw` to the full vendor-native assistant
+     * message — the same shape your adapter puts in history after emitting a
+     * tool call during streaming.
+     */
+    buildAssistantWithToolCall(tc: Extract<LlmEvent, {
+        type: 'toolCall';
+    }>): Message;
+}
+
+/**
+ * Run the 20 contract checks against a vendor adapter via its harness.
+ *
+ * Call at the top level of a test file; registers vitest `describe`/`it` blocks
+ * that exercise every aspect of the adapter contract. Adapters that pass this
+ * suite are merge-ready for the library.
+ *
+ * The suite registers the harness's factory in the library registry for the
+ * duration of the run; existing registrations are preserved after cleanup.
+ */
+declare function runContractTests(harness: ContractHarness): void;
+
+/**
+ * Shared mutable state between the harness and the fake adapter instance.
+ * The harness writes to it (via mockScenario/cleanup), the adapter reads it
+ * during stream() / listAvailableModels() to decide what to produce.
+ */
+interface FakeState {
+    scenario: ContractScenario | null;
+    captured: CapturedRequest | null;
+}
+/**
+ * Reference fake adapter used by the test-kit to verify itself.
+ *
+ * Produces canned events for each `ContractScenario`. Does not talk to any
+ * real vendor. Used by `test/test-kit/self-check.test.ts` to prove that a
+ * correctly-behaving adapter passes all 20 contract checks.
+ *
+ * Anybody implementing a real adapter can read this as a minimal reference —
+ * it shows exactly what the library expects on the wire.
+ */
+declare class FakeAdapter implements LlmAdapter<ApiKeyAuth> {
+    private readonly state;
+    readonly vendor: string;
+    readonly acceptedAuth: readonly ["apiKey"];
+    private initialized;
+    constructor(state: FakeState);
+    init(auth: ApiKeyAuth, _client?: ClientOptions): void;
+    stream(req: PromptRequest): AsyncIterable<LlmEvent>;
+    appendToolResult(history: Message[], toolCallId: string, result: unknown): Message[];
+    listAvailableModels(): Promise<ModelInfo[]>;
+    private ensureInitialized;
+    private capture;
+}
+declare const fakeManifest: AdapterManifest;
+interface FakeHarness extends ContractHarness {
+    /** Expose the factory so callers can register if needed. */
+    factory: AdapterFactory;
+}
+/**
+ * Build a ContractHarness for the fake adapter. Used by the kit's self-check
+ * test. External contributors don't use this — they build their own harness
+ * against their adapter.
+ */
+declare function createFakeHarness(): FakeHarness;
+
+export { type CapturedRequest, type ContractHarness, type ContractScenario, FakeAdapter, type FakeHarness, createFakeHarness, fakeManifest, runContractTests };