/**
 * The adapter kit: how a package outside this repository builds an adapter — a provider, an
 * embeddings backend, a vector store, a retriever, or a long-term store — and proves it works.
 *
 * Each `define*()` takes what the adapter is, the releases of `nexus-ai-pro` it supports, what it
 * can do, and how to create it, and returns an adapter whose instances normalize every failure into
 * an `AdapterError` and report every call for telemetry. Its `verify()` runs the same contract suite
 * this package runs on its own adapters, skipping only what the adapter declares it cannot do, with a
 * small benchmark held to the budgets it declares.
 */
import type { EmbeddingProvider, VectorStore } from '../hallucination/retrieval.js';
import type { BaseProvider } from '../providers/base.js';
import type { Retriever } from '../rag/retrievers.js';
import { type EmbeddingProviderConformanceOptions } from '../testing/embedding-provider-conformance.js';
import { type ProviderConformanceOptions } from '../testing/provider-conformance.js';
import type { EmbeddingsProvider } from '../types/embeddings.js';
import type { Store } from '../types/store.js';
import { type AdapterCheck, type RetrieverCapabilities, type RetrieverContractOptions, type StoreCapabilities, type VectorStoreCapabilities } from './contracts.js';
import { type AdapterErrorClass } from './errors.js';
import { type CompatibilityRecord, type CompatibilityRecordOptions } from './record.js';
export { ADAPTER_CONTRACTS, ADAPTER_FIXTURE_PASSAGES, type AdapterCheck, type AdapterContract, type AdapterContractVersion, type RetrieverCapabilities, type RetrieverContractOptions, runRetrieverContract, runStoreContract, runVectorStoreContract, type StoreCapabilities, type VectorStoreCapabilities, type VectorStoreContractOptions, } from './contracts.js';
export { AdapterError, type AdapterErrorClass, type AdapterErrorCode, classifyAdapterError } from './errors.js';
export { ADAPTER_KEYWORD, type GatheredSource, type GatherOutcome, type GatherRecordsOptions, type GatherReport, gatherRecords, type RecordSource, } from './gather.js';
export { type CheckChange, COMPATIBILITY_RECORD_FORMAT, type CompatibilityComparison, type CompatibilityPageOptions, type CompatibilityRecord, type CompatibilityRecordAdapter, CompatibilityRecordError, type CompatibilityRecordOptions, type CompatibilityState, type CompatibilityStatus, compareRecords, compatibilityPage, compatibilityRecord, readCompatibilityRecord, recordDigest, recordStatus, } from './record.js';
export { parseVersion, satisfiesRange } from './semver.js';
/** The kinds of adapter the kit builds. */
export type AdapterKind = 'provider' | 'embeddings' | 'vector-store' | 'retriever' | 'store';
/** What every adapter declares about itself. */
export interface AdapterDefinition<Config, Instance, Capabilities> {
    /** Its name, usually its package name, such as `@acme/nexus-milvus`. */
    name: string;
    /** Its own version. */
    version: string;
    /** The releases of `nexus-ai-pro` it works with, as a range: `>=2.4.0 <3`. */
    nexus: string;
    /** What it can do. The contract skips what it declares it cannot, and fails what it claims and cannot. */
    capabilities: Capabilities;
    /** Creates an instance from its configuration. */
    create(config: Config): Instance | Promise<Instance>;
    /**
     * Classifies a failure from the service behind the adapter, when the kit's own reading of statuses
     * and network codes is not enough. Returning nothing falls back to that reading.
     */
    normalizeError?(error: unknown, operation: string): AdapterErrorClass | undefined;
    /** The p95 latency each operation must stay within in `verify()`'s benchmark, in milliseconds. */
    budgets?: Readonly<Record<string, number>>;
}
/** One call through an adapter, for telemetry. */
export interface AdapterCallEvent {
    /** The adapter. */
    adapter: string;
    /** Its kind. */
    kind: AdapterKind;
    /** The method called, such as `search`. */
    operation: string;
    /** How long the call took, in milliseconds. */
    durationMs: number;
    /** Whether it succeeded. */
    ok: boolean;
    /** How it failed, when it did. */
    error?: AdapterErrorClass;
}
/** Options for an adapter's `create()`. */
export interface AdapterCreateOptions {
    /** Receives every call: the hook a tracer, a metrics exporter, or a log subscribes with. */
    onCall?: (event: AdapterCallEvent) => void;
}
/** What `verify()` measured for one operation over the contract's calls. */
export interface AdapterBenchmarkEntry {
    /** Successful calls measured. */
    calls: number;
    /** Median latency, in milliseconds. */
    p50Ms: number;
    /** 95th-percentile latency, in milliseconds. */
    p95Ms: number;
}
/** What `verify()` found. */
export interface AdapterReport {
    /** The adapter. */
    adapter: string;
    /** Its version. */
    version: string;
    /** Its kind. */
    kind: AdapterKind;
    /** The `nexus-ai-pro` release it was verified against. */
    nexusVersion: string;
    /** Whether that release is inside the adapter's declared range. */
    compatible: boolean;
    /** True when it is compatible and every check that ran held. */
    passed: boolean;
    /** Every check, in order, with skipped ones marked. */
    checks: AdapterCheck[];
    /** Latency per operation over the contract's calls. */
    benchmark: Record<string, AdapterBenchmarkEntry>;
    /** The releases the adapter declares support for. */
    nexusRange: string;
    /** What it declares it can do. */
    capabilities: unknown;
    /** The p95 budgets it declares. */
    budgets?: Readonly<Record<string, number>>;
    /** The version of its kind's contract it was verified against, from `ADAPTER_CONTRACTS`. */
    contractVersion: number;
}
/** An adapter built with the kit. */
export interface Adapter<Config, Instance, Capabilities, VerifyOptions> extends Readonly<Omit<AdapterDefinition<Config, Instance, Capabilities>, 'create'>> {
    /** Its kind. */
    readonly kind: AdapterKind;
    /** Creates an instance whose every call normalizes its failures and reports itself. */
    create(config: Config, options?: AdapterCreateOptions): Promise<Instance>;
    /** Whether a release of `nexus-ai-pro` is inside the declared range. Defaults to the installed one. */
    compatible(nexusVersion?: string): boolean;
    /** Runs the contract suite for its kind against a fresh instance, with a benchmark. */
    verify(config: Config, options: VerifyOptions): Promise<AdapterReport>;
    /**
     * Verifies it and seals the report as a `CompatibilityRecord`: what a page lists, and what a release
     * is checked against.
     */
    record(config: Config, options: VerifyOptions, record?: CompatibilityRecordOptions): Promise<CompatibilityRecord>;
}
/** What a chat provider supports, which decides the conformance cases it runs. */
export interface ProviderAdapterCapabilities {
    /** `stream()`. */
    streaming: boolean;
    /** JSON output through `responseFormat`. */
    json: boolean;
    /** Tool calls. */
    tools: boolean;
    /** `healthCheck()`. */
    health: boolean;
}
/** Options for a provider adapter's `verify()`: the model and, if you like, cases of your own. */
export type ProviderVerifyOptions = Pick<ProviderConformanceOptions, 'model' | 'fixtures'>;
/** Builds a chat-provider adapter, verified by the provider conformance suite. */
export declare function defineProviderAdapter<Config, Instance extends BaseProvider>(definition: AdapterDefinition<Config, Instance, ProviderAdapterCapabilities>): Adapter<Config, Instance, ProviderAdapterCapabilities, ProviderVerifyOptions>;
/** What an embeddings backend supports. */
export interface EmbeddingsAdapterCapabilities {
    /** Stops an embedding call when its signal aborts. */
    abort: boolean;
    /** Returns the same vectors for the same input. */
    deterministic: boolean;
}
/** Options for an embeddings adapter's `verify()`. */
export type EmbeddingsVerifyOptions = Pick<EmbeddingProviderConformanceOptions, 'model' | 'fixtures'>;
/** Builds an embeddings adapter, verified by the embeddings conformance suite. */
export declare function defineEmbeddingsAdapter<Config, Instance extends EmbeddingsProvider>(definition: AdapterDefinition<Config, Instance, EmbeddingsAdapterCapabilities>): Adapter<Config, Instance, EmbeddingsAdapterCapabilities, EmbeddingsVerifyOptions>;
/** Options for a vector-store adapter's `verify()`. */
export interface VectorStoreVerifyOptions {
    /** The embedding function the store embeds with, to compute a query vector. */
    embed: EmbeddingProvider;
    /** Waits for writes to become searchable, for an eventually consistent index. */
    settle?: () => Promise<void>;
}
/** Builds a vector-store adapter, verified by the `VectorStore` contract. */
export declare function defineVectorStoreAdapter<Config, Instance extends VectorStore>(definition: AdapterDefinition<Config, Instance, VectorStoreCapabilities>): Adapter<Config, Instance, VectorStoreCapabilities, VectorStoreVerifyOptions>;
/** Options for a retriever adapter's `verify()`. */
export type RetrieverVerifyOptions = Omit<RetrieverContractOptions, 'capabilities'>;
/** Builds a retriever adapter, verified by the `Retriever` contract, and the `SparseRetriever` one when it takes writes. */
export declare function defineRetrieverAdapter<Config, Instance extends Retriever>(definition: AdapterDefinition<Config, Instance, RetrieverCapabilities>): Adapter<Config, Instance, RetrieverCapabilities, RetrieverVerifyOptions>;
/** Builds a long-term store adapter, verified by the `Store` contract. */
export declare function defineStoreAdapter<Config, Instance extends Store>(definition: AdapterDefinition<Config, Instance, StoreCapabilities>): Adapter<Config, Instance, StoreCapabilities, Record<string, never>>;