import { O as OpenAIProviderConfig, R as RealtimeSessionConfig, a as RealtimeSession, E as EphemeralSecret, C as Capabilities, B as BaseLLMAdapter, L as LLMProviderConfig, b as LLMCompletionRequest, c as LLMCompletionResponse, d as LLMStreamChunk, e as LLMProviderRegistry, P as ProviderSelectionStrategy, H as HoloScriptGenerationRequest, f as HoloScriptGenerationResponse, g as LLMProviderName, I as ILLMProvider, A as AnthropicProviderConfig, h as BitNetProviderConfig, i as BrittneyCloudProviderConfig$1, G as GeminiProviderConfig, j as LocalLLMProviderConfig, k as OpenRouterProviderConfig, X as XAIProviderConfig } from './base-adapter-BQZiL4zs.cjs';
export { l as AnthropicAdvisorToolSpec, m as AnthropicContainerUploadBlock, n as AnthropicDocumentFileBlock, o as AnthropicEffortLevel, p as AnthropicFileContentBlock, q as AnthropicFileContentBlockOptions, r as AnthropicFileContentBlockType, s as AnthropicFileSource, t as AnthropicImageFileBlock, u as AnthropicProviderExtensions, v as AnthropicThinkingParam, w as AssistantContentBlock, x as AudioUsage, y as CacheControlEphemeral, z as GeminiProviderExtensions, D as GrokProviderExtensions, F as InlineModerationRequest, J as InlineModerationResult, K as LLMAssistantMessage, M as LLMAuthenticationError, N as LLMContentBlock, Q as LLMContextLengthError, S as LLMCreditExhaustedError, T as LLMFileMetadata, U as LLMFileUploadRequest, V as LLMMessage, W as LLMProviderError, Y as LLMRateLimitError, Z as LLMSystemMessage, _ as LLMUserMessage, $ as MessageRole, a0 as OllamaProviderExtensions, a1 as OpenAIApiSurface, a2 as OpenAIProviderExtensions, a3 as OpenAIReasoningEffort, a4 as ProviderExtensions, a5 as RealtimeServerEvent, a6 as RealtimeTransport, a7 as TextBlock, a8 as TokenUsage, a9 as ToolResultBlock, aa as ToolSpec, ab as ToolSpecUnion, ac as ToolUseBlock, ad as anthropicFileContentBlock, ae as filterGenericTools, af as isAnthropicAdvisorTool, ag as isToolSpec, ah as messageContentAsString, ai as supportsRealtime } from './base-adapter-BQZiL4zs.cjs';
import { OpenAIAdapter } from './adapters/openai.cjs';
export { OPENAI_CAPABILITIES, OPENAI_MODELS, OpenAIModel, messagesToOpenAIResponsesInput, parseOpenAIModerationResult, parseOpenAIResponsesResult, resolveOpenAIToolControls, toolSpecsToOpenAIResponseTools } from './adapters/openai.cjs';
import { AnthropicAdapter } from './adapters/anthropic.cjs';
export { ANTHROPIC_ADVISOR_BETA, ANTHROPIC_CAPABILITIES, ANTHROPIC_FILES_BETA, ANTHROPIC_MODELS, ANTHROPIC_MODEL_METADATA, AnthropicModel, AnthropicModelMetadata, buildThinkingAndOutputForAnthropic, collectAnthropicBetaHeaders, getAnthropicModelMetadata, hasAnthropicFileContent, isAnthropicDefaultRoutingEligible } from './adapters/anthropic.cjs';
import { GeminiAdapter } from './adapters/gemini.cjs';
export { GEMINI_CAPABILITIES, GEMINI_MODELS, GEMINI_MODEL_METADATA, GeminiModel, GeminiModelMetadata, getGeminiModelMetadata, isGeminiDefaultRoutingEligible } from './adapters/gemini.cjs';
import { BitNetAdapter } from './adapters/bitnet.cjs';
export { BITNET_CAPABILITIES, BITNET_MODELS, BITNET_MODEL_ALIASES, BitNetModel } from './adapters/bitnet.cjs';
import { OpenRouterAdapter } from './adapters/openrouter.cjs';
export { OPENROUTER_CAPABILITIES, OPENROUTER_MODELS, OpenRouterModel } from './adapters/openrouter.cjs';
export { VAST_SERVERLESS_CAPABILITIES, VastServerlessAdapter, VastServerlessAdapterConfig } from './adapters/vast-serverless.cjs';
import { XAIAdapter } from './adapters/xai.cjs';
export { XAIModel, XAIModelCapability, XAI_CAPABILITIES, XAI_MODELS, XAI_MODEL_CAPABILITIES } from './adapters/xai.cjs';

/**
 * OpenAI Realtime Voice Adapter
 *
 * The OpenAI implementation of the realtime transport axis (`realtime.ts`).
 * `OpenAIAdapter` stays the single provider object for chat; this companion
 * module holds the duplex-transport code so it stays OFF the chat path and
 * realtime model ids stay OFF `OPENAI_MODELS` (the chat registry). Realtime is
 * a separate axis — see `realtime.ts` and plan §0/§1.4.
 *
 * The transport is MOCKABLE: `openOpenAIRealtimeSession()` takes injectable
 * `webSocketFactory` + `fetchImpl` so a test can drive the full
 * mint-ephemeral-secret → open-WebSocket → echo-turn → usage flow without a
 * live endpoint. Real-endpoint audio verification is slice E (manual/founder);
 * the default factory lazily loads the `ws` package for the production path.
 *
 * SSOT: research/2026-07-10_realtime-adapter-implementation-plan-p0pp.md §1, §5.
 *
 * @module @holoscript/llm-provider
 */

declare const OPENAI_REALTIME_MODELS: readonly ["gpt-realtime-2.1", "gpt-realtime-2.1-mini", "gpt-realtime-2", "gpt-realtime-1.5", "gpt-realtime-mini"];
type OpenAIRealtimeModel = (typeof OPENAI_REALTIME_MODELS)[number];
/** Default full-quality realtime model. */
declare const DEFAULT_OPENAI_REALTIME_MODEL: OpenAIRealtimeModel;
/** Default cost-optimized realtime model. */
declare const DEFAULT_OPENAI_REALTIME_MINI_MODEL: OpenAIRealtimeModel;
/**
 * Minimal WebSocket contract the session driver needs. Deliberately shaped like
 * the `ws` package's EventEmitter surface (`.on('open'|'message'|'close'|
 * 'error')`, `.send`, `.close`) so the default factory can hand a real `ws`
 * instance straight through, and a test can hand a fake with the same shape.
 */
interface RealtimeWebSocketLike {
    send(data: string): void;
    close(code?: number, reason?: string): void;
    on(event: 'open' | 'message' | 'close' | 'error', handler: (arg?: unknown) => void): void;
}
type RealtimeWebSocketFactory = (url: string, options: {
    headers: Record<string, string>;
}) => RealtimeWebSocketLike;
/** Minimal fetch shape (avoids a DOM lib dependency under lib: ES2020). */
type RealtimeFetchLike = (url: string, init?: {
    method?: string;
    headers?: Record<string, string>;
    body?: string;
}) => Promise<{
    ok: boolean;
    status: number;
    json(): Promise<unknown>;
    text(): Promise<string>;
}>;
interface OpenAIRealtimeDeps {
    apiKey: string;
    /** Defaults to https://api.openai.com. */
    baseURL?: string;
    /** Inject for tests; production default lazily loads the `ws` package. */
    webSocketFactory?: RealtimeWebSocketFactory;
    /** Inject for tests; defaults to `globalThis.fetch`. */
    fetchImpl?: RealtimeFetchLike;
}
/**
 * Mint a short-lived client secret so a browser/Quest client can connect
 * directly to the vendor without the master `OPENAI_API_KEY` ever leaving the
 * server. Scoped per surface, short-TTL. For pure server-side WebSocket the
 * caller may skip this and use the master key directly — but the session-open
 * flow mints by default so the ephemeral path is exercised (plan §1.3, §5.1).
 */
declare function mintOpenAIEphemeralSecret(surface: string, deps: OpenAIRealtimeDeps, opts?: {
    ttlSeconds?: number;
    model?: string;
}): Promise<EphemeralSecret>;
/**
 * Open a realtime voice session against OpenAI. Mints an ephemeral secret,
 * opens the WebSocket, and returns a live duplex handle. The event loop maps
 * OpenAI's wire events to the provider-neutral `RealtimeServerEvent` union.
 *
 * Inject `deps.webSocketFactory` + `deps.fetchImpl` to drive the whole flow in
 * a test without a live endpoint.
 */
declare function openOpenAIRealtimeSession(config: RealtimeSessionConfig, deps: OpenAIRealtimeDeps): Promise<RealtimeSession>;
/**
 * The OpenAI realtime adapter. Extends `OpenAIAdapter` so it stays the SAME
 * provider object shape the capability router already reads (inherits
 * `OPENAI_CAPABILITIES`, which declares `realtimeVoice: true`), and only adds
 * the optional `openRealtimeSession()` method — making the `realtimeVoice`
 * flag honest for the first vendor. The chat adapter (`openai.ts`) is untouched.
 *
 * `realtimeDeps` lets a caller/test inject the transport seam through the
 * adapter path too, not just the standalone `openOpenAIRealtimeSession()`.
 */
declare class OpenAIRealtimeAdapter extends OpenAIAdapter {
    private readonly realtimeDeps?;
    constructor(config: OpenAIProviderConfig, realtimeDeps?: Partial<OpenAIRealtimeDeps>);
    openRealtimeSession(config: RealtimeSessionConfig): Promise<RealtimeSession>;
}

/**
 * Mock LLM Provider Adapter
 *
 * A fully functional mock adapter for testing HoloScript applications
 * without real API calls. Returns deterministic responses based on
 * the input prompt.
 *
 * @version 1.0.0
 */

/**
 * Mock LLM provider for testing - no API calls, no cost.
 *
 * @example
 * ```typescript
 * // Use in tests
 * const mock = new MockAdapter();
 * const scene = await mock.generateHoloScript({ prompt: "a floating island" });
 * expect(scene.valid).toBe(true);
 * ```
 */
/**
 * Capability manifest — generous defaults so test paths exercising
 * common features (streaming, tools, vision) can route to mock without
 * routing-filter rejection. Tests that need to exercise capability-
 * filter edge cases should construct a custom adapter with narrower
 * `capabilities` rather than mutating mock's defaults.
 *
 * Exported as a constant so the capability-aware router can read it
 * without instantiating the adapter — single source of truth per W.GOLD.006.
 */
declare const MOCK_CAPABILITIES: Capabilities;
declare class MockAdapter extends BaseLLMAdapter {
    readonly name: "mock";
    readonly models: readonly ["mock-gpt-4", "mock-claude", "mock-gemini"];
    readonly defaultHoloScriptModel = "mock-gpt-4";
    readonly capabilities: Capabilities;
    /** Number of complete() calls made */
    callCount: number;
    /** Whether the next call should fail (for testing error handling) */
    failOnNextCall: boolean;
    /** Simulated latency in ms */
    simulatedLatencyMs: number;
    constructor(config?: Partial<LLMProviderConfig>);
    protected getDefaultModel(): string;
    complete(request: LLMCompletionRequest, _model?: string): Promise<LLMCompletionResponse>;
    /**
     * Override healthCheck to always succeed instantly.
     */
    healthCheck(): Promise<{
        ok: boolean;
        latencyMs: number;
        error?: string;
    }>;
    /** Reset call counter and state. */
    reset(): void;
    private generateMockCode;
}

/**
 * Local LLM Adapter
 *
 * Connects to any local OpenAI-compatible inference server:
 * llama.cpp, Ollama, LM Studio, or similar.
 * No API key required — the server runs locally.
 *
 * Supported runtimes:
 *   llama.cpp:  llama-server -m model.gguf --port 8080 --ctx-size 4096
 *   Ollama:     ollama serve  (default port 11434)
 *   LM Studio:  Start server in UI  (default port 1234)
 *
 * The server must expose: POST http://localhost:PORT/v1/chat/completions
 *
 * @version 1.0.0
 */

type LocalLLMAdapterConfig = Omit<LLMProviderConfig, 'apiKey'> & {
    apiKey?: string;
    model?: string;
    /**
     * Use Ollama's native /api/chat endpoint instead of /v1/chat/completions.
     * Auto-detected when the base URL contains ':11434' (Ollama default port).
     * Required for thinking models (qwen3, deepseek-r1, etc.) because the OpenAI
     * compat layer drops tool_calls in responses that include thinking tokens.
     * Verified 2026-06-16: /v1/chat/completions returns toolCalls=[] for qwen3:4b
     * with tools; /api/chat returns tool_calls correctly.
     */
    nativeOllamaApi?: boolean;
};
declare const LOCAL_LLM_MODELS: readonly ["qwen3-4b-instruct-2507", "mistral-small-4", "mistral-7b-instruct", "llama-3.1-8b-instruct", "llama-3.2-3b-instruct", "granite-4.0-1b", "phi-4-mini-instruct"];
type LocalLLMModel = (typeof LOCAL_LLM_MODELS)[number];
/**
 * Capability manifest — Ollama / llama.cpp / LM Studio / vLLM via
 * OpenAI-compatible interface. Capabilities are PER-MODEL not
 * per-provider; this is the conservative manifest for the
 * runtime itself. Brains needing specific local-model superpowers
 * (e.g. tool-use on deepseek-v3.1) should override via per-deployment
 * capability declarations.
 *
 * Per /research task_1778109552044_xhmm — populate per-model
 * capability sheets for the models actually run (deepseek-v3.1:671b,
 * gpt-oss:120b, kimi-1T cloud, etc.). Until then: conservative defaults.
 *
 * Exported as a constant so the capability-aware router can read it
 * without instantiating the adapter — single source of truth per W.GOLD.006.
 */
declare const LOCAL_LLM_CAPABILITIES: Capabilities;
declare class LocalLLMAdapter extends BaseLLMAdapter {
    readonly name: "local-llm";
    readonly models: readonly ["qwen3-4b-instruct-2507", "mistral-small-4", "mistral-7b-instruct", "llama-3.1-8b-instruct", "llama-3.2-3b-instruct", "granite-4.0-1b", "phi-4-mini-instruct"];
    readonly defaultHoloScriptModel: string;
    readonly capabilities: Capabilities;
    private readonly localBaseURL;
    /** True → complete() uses /api/chat (native Ollama); false → /v1/chat/completions. */
    private readonly useNativeOllamaApi;
    constructor(config?: LocalLLMAdapterConfig);
    protected getDefaultModel(): string;
    /**
     * Send a chat completion request to the local LLM server.
     *
     * Two paths depending on `useNativeOllamaApi` (auto-detected from port 11434):
     *
     * Ollama native (/api/chat, stream:false) — used when useNativeOllamaApi=true.
     *   Ollama's /v1/chat/completions OpenAI-compat shim silently drops tool_calls
     *   for thinking models (qwen3, deepseek-r1) because thinking tokens precede
     *   tool calls and the compat layer misroutes them. The native endpoint does not
     *   have this bug. Verified 2026-06-16: /v1 → toolCalls=0, /api/chat → toolCalls=1.
     *
     * OpenAI-compat (/v1/chat/completions) — used for llama.cpp / LM Studio / vLLM.
     */
    complete(request: LLMCompletionRequest, model?: string): Promise<LLMCompletionResponse>;
    /**
     * Injects `/no_think` into the system prompt for qwen3-family models when
     * thinking mode is off. Ollama ≤0.30.x silently ignores `think: false` and
     * routes thinking tokens into the `content` field, bloating outputs and
     * corrupting tool-call parsing. The `/no_think` directive works at the model
     * tokenizer level, independent of Ollama version.
     * Verified: Ollama 0.30.8 + qwen3:4b — `think:false` ignored, `/no_think` works.
     */
    private _withNoThinkMessages;
    /**
     * Returns `{}` — we never send `think:false` in the Ollama payload.
     *
     * Confirmed 2026-06-16: `think:false` disables the decode-time grammar mask
     * that enables structured JSON tool calls for BOTH qwen3 AND Gemma 4 families
     * (same root cause as Ollama #15260 / vLLM #39130 — mask deferred until the
     * end-of-thinking token which never fires when thinking is closed, so the model
     * emits prose instead of tool_calls JSON). With thinking ON, Ollama 0.30.8
     * correctly routes thinking to `message.thinking` (separate field) and leaves
     * `message.content` clean — _stripThinkBlock() handles any edge-case bleed.
     * Thinking is soft-suppressed via `/no_think` in the system prompt
     * (_withNoThinkMessages), which reduces thinking tokens without breaking
     * tool-call structured output.
     */
    private _thinkParam;
    /**
     * Ollama 0.30.x (qwen3): strips the <think> opener but leaves the thinking
     * body + </think> closing tag inside message.content. Strip everything up to
     * and including </think> so the returned content is the model's actual reply.
     * When future Ollama separates thinking into message.thinking, content will
     * arrive clean and this is a no-op.
     */
    private _stripThinkBlock;
    private completeNativeOllama;
    private completeOpenAICompat;
    /** Shared fetch+error handling for both complete() paths. */
    private fetchJson;
    /** Build a unified LLMCompletionResponse from either response format. */
    private buildResponse;
    /**
     * Map Ollama's tool definition shape (function.parameters) from our
     * ToolSpec shape (input_schema). Ollama's /api/chat uses `parameters`
     * where our ToolSpec uses `input_schema` — same schema, different key.
     */
    private mapToolsToOllama;
    /**
     * Map Ollama's `done_reason` to our unified `finishReason`.
     */
    private mapDoneReason;
    /**
     * Stream a completion as provider-agnostic chunks via Ollama's native
     * `/api/chat` endpoint with `stream: true`.
     *
     * Ollama returns NDJSON — one JSON object per line. Each line carries an
     * incremental `message.content` text delta and/or a `message.tool_calls`
     * array. The final line has `done: true` with usage statistics.
     *
     * Translation rules:
     *   message.content (non-empty)  → text_delta
     *   message.tool_calls            → tool_use_start + tool_use_end per tool
     *                                  (Ollama sends complete tool calls in one
     *                                   shot, no streamed JSON fragments, so no
     *                                   tool_use_input_delta chunks)
     *   done: true                    → message_stop (with finishReason + usage)
     *
     * No `withRetry` — partial-text retries would re-emit prefix tokens and
     * corrupt downstream state (the same contract as AnthropicAdapter).
     * Pre-flight failures (429, 5xx, network) throw before the first chunk;
     * mid-stream failures yield a `message_stop` with `finishReason: 'error'`
     * and the partial state observed so far.
     */
    streamCompletion(request: LLMCompletionRequest, model?: string): AsyncIterable<LLMStreamChunk>;
    /** Pre-flight for both streaming paths: POST, status-check, throw before the first chunk. */
    private preflightStream;
    private streamNativeOllama;
    /**
     * Stream a completion via the OpenAI-compatible SSE surface
     * (`POST /v1/chat/completions`, `stream: true`) — llama.cpp llama-server,
     * HoloServe (pytorch-holo), LM Studio, vLLM.
     *
     * SSE framing: `data: {json}` lines, terminated by `data: [DONE]`. Each JSON
     * chunk carries `choices[0].delta.content` text deltas and/or `delta.tool_calls`
     * argument FRAGMENTS (accumulated per tool-call index, emitted as
     * tool_use_start + tool_use_end once the stream finishes — OpenAI semantics:
     * arguments are only complete at finish). Usage rides the final data chunk
     * when the server sends it (llama-server and HoloServe both do).
     *
     * Same error contract as the Ollama path: pre-flight failures throw before the
     * first chunk; mid-stream failures yield message_stop with finishReason 'error'
     * then throw. `request.grammar` passes through for valid-by-construction output.
     */
    private streamOpenAICompat;
    /**
     * Returns the HoloScript-tuned system prompt for local models.
     */
    protected getHoloScriptSystemPrompt(): string;
    /**
     * Check if the local LLM server is reachable.
     * Delegates to BaseLLMAdapter.healthCheckLocalServer — same /health →
     * /v1/models fallback, branded error message for this adapter.
     */
    healthCheck(): Promise<{
        ok: boolean;
        latencyMs: number;
        error?: string;
    }>;
}

/**
 * OpenAI-Compatible Bearer Adapter
 *
 * A hosted OpenAI-compatible chat-completions adapter for any provider that
 * speaks the `${baseURL}/chat/completions` wire format with an optional
 * `Authorization: Bearer <apiKey>` header. This is the shared substrate for
 * Fireworks, Kimi (via Fireworks), Together, and the self-hosted Fleet serving
 * tier — all of which are OpenAI-compatible Bearer endpoints.
 *
 * Why a separate adapter from `openrouter.ts` / `xai.ts`?
 *   - Those adapters depend on the optional `openai` SDK and add provider
 *     attribution headers. This adapter is SDK-free (raw fetch) and carries no
 *     provider-specific headers — it's the lowest-common-denominator path so a
 *     caller can point it at ANY OpenAI-compatible endpoint (cloud or
 *     self-hosted vLLM/TGI/SGLang box) with just `{ baseURL, apiKey?, model }`.
 *   - It implements native streaming (`streamCompletion`) by parsing the
 *     OpenAI chat-completions SSE stream, INCLUDING fragmented
 *     `tool_calls.function.arguments` accumulation across deltas — the exact
 *     parsing logic that previously lived in
 *     `services/llm-service/src/services/InferenceRouter.ts` (`parseOpenAIStream`).
 *     Lifting it here lets the service dogfood the package instead of
 *     hand-rolling the parser.
 *
 * The public stream shape is the package's `LLMStreamChunk` discriminated
 * union (text_delta / tool_use_start / tool_use_input_delta / tool_use_end /
 * message_stop). Service-side callers that need the legacy
 * `StreamEvent {type,payload}` wire contract shim `LLMStreamChunk` → that shape
 * at their boundary; the package itself never speaks `StreamEvent`.
 *
 * @version 1.0.0
 */

/**
 * Config for a generic hosted OpenAI-compatible Bearer endpoint.
 *
 * `apiKey` is optional — a self-hosted box launched without `--api-key`
 * answers unauthenticated, so we omit the `Authorization` header when no key
 * is present (matches the Fleet serving tier's dev/unauthenticated mode).
 */
type OpenAICompatibleAdapterConfig = Omit<LLMProviderConfig, 'apiKey'> & {
    /** Bearer token for the endpoint. Omit / empty => no Authorization header. */
    apiKey?: string;
    /** Default model id sent in the request body. */
    model?: string;
};
/**
 * Capability manifest — generic OpenAI-compatible endpoint. Capabilities are
 * per-endpoint/per-model not per-provider; this is the conservative manifest
 * for the wire protocol itself. Tool-calling is declared `true` because the
 * adapter parses fragmented `tool_calls` deltas — but whether the BACKING
 * model honors tools is model-dependent.
 *
 * Exported as a constant so the capability-aware router can read it without
 * instantiating the adapter — single source of truth per W.GOLD.006.
 */
declare const OPENAI_COMPATIBLE_CAPABILITIES: Capabilities;
declare class OpenAICompatibleAdapter extends BaseLLMAdapter {
    readonly name: "openrouter";
    readonly models: readonly string[];
    readonly defaultHoloScriptModel: string;
    readonly capabilities: Capabilities;
    private readonly endpointBaseURL;
    private readonly bearerKey;
    constructor(config?: OpenAICompatibleAdapterConfig);
    protected getDefaultModel(): string;
    private buildHeaders;
    private mapFinishReason;
    private ollamaNumCtx;
    complete(request: LLMCompletionRequest, model?: string): Promise<LLMCompletionResponse>;
    private mapToolToOpenAI;
    streamCompletion(request: LLMCompletionRequest, model?: string): AsyncIterable<LLMStreamChunk>;
    /**
     * Health check — probe the OpenAI-compatible endpoint's /v1/models-style
     * surface cheaply rather than a full chat round-trip. Tries the parent of
     * the chat-completions path (`${baseURL}/models`), falling back to a HEAD on
     * the base. Local boxes expose /v1/models; cloud endpoints usually do too.
     */
    healthCheck(): Promise<{
        ok: boolean;
        latencyMs: number;
        error?: string;
    }>;
}

/**
 * Brittney Cloud Adapter
 *
 * Connects to the first-party Brittney Cloud Service — HoloScript's
 * cloud-grade AI gateway. Supports SSE streaming, tool calling, and
 * tiered inference (standard / pro) with automatic provider routing
 * behind the service.
 *
 * Endpoints (relative to baseURL):
 *   POST /api/chat     — SSE streaming chat (primary)
 *   POST /api/generate — Non-streaming code generation
 *   GET  /api/health   — Service health
 *
 * @version 1.0.0
 */

/**
 * Task lane — what kind of work requests from this adapter are (task-type
 * modulation). The service maps lanes to per-lane model overrides
 * (BRITTNEY_LANE_<LANE>_MODEL) and promotes explicit vision/reasoning lanes
 * to the pro tier when no tier is pinned.
 */
type BrittneyCloudLane = 'operator' | 'code' | 'vision' | 'reasoning';
interface BrittneyCloudProviderConfig extends Omit<LLMProviderConfig, 'apiKey'> {
    /** API key — optional for dev mode; required for authenticated endpoints. */
    apiKey?: string;
    /**
     * Inference tier. 'pro' routes to Kimi K2.5 when available;
     * 'standard' uses the preferred available provider (Fireworks,
     * Together, or Ollama fallback). Unset = service default (standard),
     * which also allows lane-based tier promotion server-side.
     */
    tier?: 'standard' | 'pro';
    /**
     * Task lane for requests from this adapter. Unset = service-side
     * heuristic detection (backward compatible).
     */
    lane?: BrittneyCloudLane;
}
declare const BRITTNEY_CLOUD_MODELS: readonly ["brittney-standard", "brittney-pro", "brittney-qwen-v23"];
type BrittneyCloudModel = (typeof BRITTNEY_CLOUD_MODELS)[number];
declare const BRITTNEY_CLOUD_CAPABILITIES: Capabilities;
declare class BrittneyCloudAdapter extends BaseLLMAdapter {
    readonly name: "brittney-cloud";
    readonly models: readonly ["brittney-standard", "brittney-pro", "brittney-qwen-v23"];
    readonly defaultHoloScriptModel: string;
    readonly capabilities: Capabilities;
    private readonly baseURL;
    private readonly tier?;
    private readonly lane?;
    constructor(config?: BrittneyCloudProviderConfig);
    protected getDefaultModel(): string;
    complete(request: LLMCompletionRequest, model?: string): Promise<LLMCompletionResponse>;
    streamCompletion(request: LLMCompletionRequest, model?: string): AsyncIterable<LLMStreamChunk>;
    healthCheck(): Promise<{
        ok: boolean;
        latencyMs: number;
        error?: string;
    }>;
    private estimateTokens;
}

/**
 * LLM Provider Manager
 *
 * Manages multiple LLM provider adapters and implements provider selection
 * strategies including fallback, cost optimization, and speed optimization.
 *
 * @version 1.0.0
 */

interface ProviderManagerConfig {
    /** Provider registry - register the adapters you want to use */
    providers: LLMProviderRegistry;
    /** Selection strategy */
    strategy?: ProviderSelectionStrategy;
}
/**
 * Manages multiple LLM providers with automatic fallback and strategy selection.
 *
 * @example
 * ```typescript
 * const manager = new LLMProviderManager({
 *   providers: {
 *     anthropic: new AnthropicAdapter({ apiKey: process.env.ANTHROPIC_API_KEY! }),
 *     openai: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! }),
 *   },
 *   strategy: {
 *     primary: 'anthropic',
 *     fallback: 'openai',
 *   },
 * });
 *
 * const scene = await manager.generateHoloScript({
 *   prompt: "a futuristic city skyline at sunset",
 * });
 * ```
 */
declare class LLMProviderManager {
    private readonly providers;
    private readonly strategy;
    constructor(config: ProviderManagerConfig);
    /**
     * Generate HoloScript code using the configured provider strategy.
     * Falls back to secondary provider if primary fails.
     */
    generateHoloScript(request: HoloScriptGenerationRequest): Promise<HoloScriptGenerationResponse & {
        attemptedProviders: LLMProviderName[];
    }>;
    /**
     * Send a completion request using the configured primary provider.
     */
    complete(request: LLMCompletionRequest, providerName?: LLMProviderName): Promise<LLMCompletionResponse>;
    /**
     * Run health checks on all registered providers.
     */
    healthCheckAll(): Promise<Record<LLMProviderName, {
        ok: boolean;
        latencyMs: number;
        error?: string;
    }>>;
    /**
     * Get the list of registered provider names.
     */
    getRegisteredProviders(): LLMProviderName[];
    /**
     * Get a specific provider by name.
     */
    getProvider(name: LLMProviderName): ILLMProvider | undefined;
    private getProviderOrder;
    private detectDefaultStrategy;
}

/**
 * Local multi-GPU fleet router — routes one inference request across the
 * OWNED-metal GPU nodes (Jetson Orin + dev-laptop RTX 3060) so both cards
 * answer as ONE local tier instead of one sitting idle while the other queues.
 *
 * This is the runtime the native HoloScript brain
 * `compositions/model-fleet.hsplus` declares (founder 2026-06-16, "this is
 * supposed to be native holoscript"): the `.hsplus` is the SPEC, this module is
 * the consumer. The single-endpoint {@link pickLocalModel} is its degenerate
 * one-node case.
 *
 * Endpoint resolution is by sovereign-devices registry HANDLE, never a
 * hardcoded address (founder ruling 2026-06-16): a `localhost` literal is
 * consumer-relative and only correct on the node it runs on. The git-tracked
 * registry is the source of truth for node identity (pillar 8). It lives at
 * `config/sovereign-devices/<handle>.json` and each fleet node
 * carries a `local-llm` capability whose `endpoint` is the LAN-absolute Ollama
 * URL. A node with no resolvable `local-llm` endpoint is simply not a fleet
 * member right now — the fleet degrades to whatever IS reachable (Jetson-only
 * until the laptop's Ollama binds `0.0.0.0`).
 *
 * Routing = the least-loaded GPU that HAS the model, warm-preferred. Live model
 * inventory + load come from each node's Ollama (`/api/tags` + `/api/ps`);
 * blacklist + safe fallback come from the model-policy SSOT. $0 marginal — both
 * nodes are owned metal.
 */
/** Serving backend a fleet node runs. Default (unset) = Ollama. */
type FleetBackend = 'ollama' | 'llama.cpp' | 'pytorch-holo';
/** One declared fleet node. Addresses are NOT here — only the registry handle. */
interface FleetNode {
    /** sovereign-devices registry handle, e.g. "jetson-orin". */
    handle: string;
    /** Declared model hints (the runtime re-discovers what is actually installed). */
    models: string[];
    /** Human role note from the brain (diagnostics only). */
    role?: string;
    /** Whether the node is expected to be always-on (diagnostics only). */
    alwaysOn?: boolean;
    /**
     * Serving backend. Unset/`ollama` → discovered via Ollama `/api/tags` + `/api/ps`.
     * `llama.cpp` → discovered via a HoloLlama llama-server's `/health` + `/props` +
     * `/slots`. `pytorch-holo` → discovered via the SAME three routes on a HoloServe
     * native sovereign server (scripts/holoserve.py in ai-ecosystem, D.118 — no
     * llama.cpp/GGUF), with `/health` additionally required to ASSERT sovereignty
     * (`sovereign:true`, not `llama_cpp:true`) before the node is admitted. The same
     * least-loaded / warm-preferred ranking applies to all three, so every backend
     * kind load-balances beside the others on the owned GPUs.
     */
    backend?: FleetBackend;
}
/** The parsed `@model_fleet` declaration. */
interface FleetSpec {
    nodes: FleetNode[];
    /** Routing strategy, e.g. "least-loaded". */
    strategy: string;
    /** Prefer a node where the model is already resident in VRAM. */
    warmPreferred: boolean;
    /** Spec-level blacklist (merged with the model-policy blacklist). */
    blacklist: string[];
    /**
     * Primary node handle — the node that should carry the MAIN inference load.
     * The router prefers it over all others UNTIL its VRAM load crosses
     * `primaryMaxLoadBytes`, then spills to the next-freest node (the overflow
     * GPUs "on top"). Unset → pure strategy ranking. (founder 2026-06-17:
     * "the jetson handles the main inference and the laptop provides GPU on top".)
     */
    primary?: string;
    /** VRAM-resident bytes above which the primary is "saturated" → spill. Default 6 GB. */
    primaryMaxLoadBytes?: number;
}
/** Live per-node inventory + load. */
interface NodeDiscovery {
    handle: string;
    baseURL: string;
    /** Installed, non-blacklisted model tags (`/api/tags`). */
    installed: string[];
    /** Models currently resident in VRAM (`/api/ps`). */
    warm: Set<string>;
    /** Sum of resident model `size_vram` bytes — lower = freer GPU. */
    loadScore: number;
    /**
     * Which serving backend answered discovery. Carried through to the route so a
     * consumer knows which API shape the chosen node speaks (Ollama `/api/chat` vs
     * OpenAI-compat `/v1/*`) instead of guessing from a `:11434` port heuristic.
     */
    backend: FleetBackend;
}
/** A routing candidate (node, model) the router weighed. */
interface FleetCandidate {
    handle: string;
    baseURL: string;
    model: string;
    warm: boolean;
    loadScore: number;
    /** Serving backend of the node (see {@link NodeDiscovery.backend}). */
    backend: FleetBackend;
}
/** The chosen route across the fleet. */
interface FleetRoute extends FleetCandidate {
    reason: string;
    candidates: FleetCandidate[];
}
/** Minimal `fetch` shape so tests can inject a fake without a real network. */
type FetchLike = (url: string, init?: {
    method?: string;
    headers?: Record<string, string>;
    signal?: AbortSignal;
    body?: string;
}) => Promise<{
    ok: boolean;
    json(): Promise<unknown>;
}>;
interface FleetRouteOptions {
    /** Requested model (e.g. the brain's @provider_policy prefer). Blacklisted → ignored. */
    model?: string;
    /** Per-fetch timeout in ms (default 6000 — node discovery should be snappy). */
    timeoutMs?: number;
    /** Override the registry directory (default env SOVEREIGN_DEVICES_DIR or a local config directory). */
    registryDir?: string;
    /** Inject a fetch (tests). Defaults to global fetch. */
    fetchImpl?: FetchLike;
    /** Inject endpoint resolution (tests). Defaults to registry-file resolution. */
    resolveEndpoint?: (handle: string) => Promise<string | null>;
}
/**
 * Parse a `@model_fleet { … }` block out of a `.hsplus` brain. Returns null when
 * the brain declares no fleet (so the caller falls back to single-node routing).
 *
 * Node sub-blocks are recognised structurally — any `name { … }` containing a
 * `node:` field is a fleet node — so the brain can name them freely
 * (jetson/laptop/…); top-level `strategy`/`warm_preferred`/`blacklist` are read
 * after the node sub-blocks are carved out, so a node's `models:` list never
 * leaks into the fleet-level blacklist.
 */
declare function parseFleetSpec(brainSrc: string): FleetSpec | null;
/** Load + parse a fleet spec from a brain file path. Null on any read/parse miss. */
declare function loadFleetSpec(brainPath: string): Promise<FleetSpec | null>;
/**
 * Resolve a node handle → its LAN-absolute Ollama endpoint by reading
 * `<registryDir>/<handle>.json` and returning the `local-llm` capability's
 * `endpoint`. Null when the file is missing, unparseable, or carries no
 * `local-llm` endpoint (→ the node is not a fleet member right now).
 */
declare function resolveNodeEndpoint(handle: string, registryDir?: string): Promise<string | null>;
/**
 * Probe one node's Ollama: installed models (`/api/tags`, blacklist-filtered) +
 * resident models with their VRAM load (`/api/ps`). Returns null when the node
 * is unreachable (so it is dropped from routing).
 */
declare function discoverNode(handle: string, baseURL: string, isBlocked: (name: string) => boolean, opts?: {
    timeoutMs?: number;
    fetchImpl?: FetchLike;
}): Promise<NodeDiscovery | null>;
/**
 * Probe one HoloLlama llama-server node: gate on `/health`, read the single loaded
 * model from `/props`, and derive load from busy `/slots`. Returns the SAME
 * {@link NodeDiscovery} shape as {@link discoverNode} so the router ranks llama.cpp
 * and Ollama nodes identically. Returns null when `/health` is unreachable/not-ok
 * (so the node is dropped from routing this turn).
 *
 * A llama-server serves exactly one model and holds it resident once `/health` is
 * ok, so `installed` is that one model and `warm` is the same single element — there
 * is no cold state to distinguish. loadScore is the count of busy slots (a small
 * integer); cross-backend load magnitudes are nominal, but the model-match filter
 * plus the primary/warm tiers (checked before loadScore) keep routing sensible.
 */
declare function discoverLlamaCppNode(handle: string, baseURL: string, isBlocked: (name: string) => boolean, opts?: {
    timeoutMs?: number;
    fetchImpl?: FetchLike;
}): Promise<NodeDiscovery | null>;
/**
 * Probe one HoloServe node (the native PyTorch-direct sovereign server, D.118 —
 * scripts/holoserve.py in ai-ecosystem). Same `/health` + `/props` + `/slots`
 * surface while its exact health registry may advertise multiple resident models, so it
 * shares {@link discoverLlamaCppNode}'s discovery body — with one addition: the
 * `/health` body must MACHINE-CHECKABLY assert sovereignty (`sovereign: true` and
 * not `llama_cpp: true`). A node declared `backend: "pytorch-holo"` whose health
 * doesn't carry that claim (e.g. someone pointed the handle at a llama-server) is
 * dropped rather than routed as sovereign.
 * Admission additionally requires the exact canonical model-artifact registry,
 * agreement with `/props`, finite slot
 * telemetry, and an unchanged registry after all discovery probes.
 */
declare function discoverPytorchHoloNode(handle: string, baseURL: string, isBlocked: (name: string) => boolean, opts?: {
    timeoutMs?: number;
    fetchImpl?: FetchLike;
}): Promise<NodeDiscovery | null>;
declare function pickFleetModel(spec: FleetSpec, opts?: FleetRouteOptions): Promise<FleetRoute | null>;
/**
 * High-level helper for callers that just want `(baseURL, model)` for the local
 * tier across both GPUs. Loads the fleet spec from `opts.brainPath` (or env
 * `HOLO_LLM_FLEET_BRAIN`), routes, and returns the pick — or null when no fleet
 * is declared / none reachable (caller then keeps its single-endpoint path).
 */
declare function resolveLocalFleet(opts?: FleetRouteOptions & {
    brainPath?: string;
    spec?: FleetSpec;
}): Promise<{
    baseURL: string;
    model: string;
    backend: FleetBackend;
    route: FleetRoute;
} | null>;
/**
 * Embed `text` via the fleet's embedding model, routed to whichever OWNED node has
 * it installed (default `nomic-embed-text` → the Jetson model store). Reuses the
 * same registry-handle endpoint resolution + live `/api/tags` discovery as chat
 * routing, then calls Ollama `POST /api/embed`. Returns the vector, or `null` on
 * ANY miss (no fleet / node down / model absent / bad response) so callers treat
 * embeddings as best-effort (a retrieval miss never breaks the turn). $0 — owned metal.
 */
declare function embedAcrossFleet(text: string, opts?: FleetRouteOptions & {
    brainPath?: string;
    spec?: FleetSpec;
    embedModel?: string;
}): Promise<number[] | null>;
/** Cosine similarity of two equal-length vectors. Returns 0 on mismatch / zero-norm. */
declare function cosineSimilarity(a: number[], b: number[]): number;

/**
 * Universal sovereign-first LLM provider resolution.
 *
 * Founder directive (2026-06-10): HoloClaw, the fleet, and Brittney resolve
 * their LLM the SAME way — sovereign by default, frontier APIs as BYOK
 * fallback only. This file is the canonical implementation of that policy
 * (F.112 extended ecosystem-wide; P.009 sovereign embeddings is the
 * companion for embeddings). Surfaces that still carry their own copy of
 * the policy (studio's lib/brittney/provider.ts) should converge here.
 *
 * Auto-detect priority (no explicit provider):
 *   1. local-fleet — owned laptop/Jetson model-fleet routes, discovered per request
 *   2. fleet       — Vast serverless sovereign serving fleet (P.008), route-probed
 *                    per request so cold pools can fall back while they wake
 *   3. cloud       — pinned sovereign serving endpoint (BrittneyCloudAdapter)
 *   4. holollama   — sovereign local inference layer (llama.cpp llama-server, D.117),
 *                  when HOLOLLAMA_URL is set; preferred over legacy Ollama
 *   5. ollama      — legacy local model (OLLAMA_HOST), kept for back-compat
 *   6. anthropic / xai / openai — BYOK frontier fallback, in that order
 *   7. holollama (default :18080) — TERMINAL sovereign default (D.117), instead of
 *                  a bare "nothing configured" throw
 *
 * Env surface (universal names first, BRITTNEY_* kept as compat aliases):
 *   HOLO_LLM_PROVIDER | BRITTNEY_PROVIDER         explicit override
 *   HOLO_LLM_SERVICE_URL | BRITTNEY_SERVICE_URL   cloud endpoint
 *   HOLO_LLM_MODEL | BRITTNEY_MODEL               model override
 *   HOLO_LLM_MAX_TOKENS | BRITTNEY_MAX_TOKENS     max-token override
 *   OLLAMA_HOST | OLLAMA_BASE_URL | OLLAMA_URL    local endpoint
 *   FLEET_PROVIDER_ENDPOINT | VAST_QWEN_ENDPOINT_NAME  Vast endpoint
 *   HOLO_LLM_FLEET_MODEL | BRITTNEY_FLEET_MODEL   fleet model
 *   HOLO_LLM_FLEET_BRAIN                            owned local @model_fleet source
 *   VAST_API_KEY                                  Vast route + worker bearer
 *   ANTHROPIC_API_KEY / XAI_API_KEY / OPENAI_API_KEY  BYOK fallbacks
 *   HOLOSERVE_PARITY_PINS                         model@binding-sha256 pins (comma-separated)
 *   HOLOSERVE_PARITY_REGISTRY                     path to the parity pin registry JSON
 *                                                 (maintained by ai-ecosystem
 *                                                 scripts/holoserve-llamaserver-parity-receipt.mjs)
 */

type SovereignProviderName = 'local-fleet' | 'fleet' | 'cloud' | 'holoserve' | 'holollama' | 'ollama' | 'anthropic' | 'xai' | 'openai';
interface ResolvedSovereignProvider {
    provider: ILLMProvider;
    /** Model string to pass to complete()/streamCompletion(). */
    model: string;
    maxTokens: number;
    providerName: SovereignProviderName;
    /** Concrete owned-fleet wire protocol selected in-band by resolveLocalFleet. */
    fleetBackend?: FleetBackend;
    /** Exact parity-tested HoloServe binding when a strangler pin selected this route. */
    artifactBindingSha256?: string;
}
interface SovereignResolveOptions {
    /** Explicit provider override (CLI flag etc.) — beats every env. */
    explicit?: string;
    /** BYOK Anthropic key (e.g. per-user vault) — overrides ANTHROPIC_API_KEY. */
    anthropicKey?: string | null;
    /** Model override — beats HOLO_LLM_MODEL/BRITTNEY_MODEL. */
    model?: string;
    /** Max-token override — beats HOLO_LLM_MAX_TOKENS/BRITTNEY_MAX_TOKENS. */
    maxTokens?: number;
}
/**
 * Synchronous sovereign-first resolution: cloud → ollama → anthropic → xai →
 * openai. Fleet (dynamic-resolve) needs a network round-trip — use
 * `resolveSovereignProviderAsync` to include it.
 */
declare function resolveSovereignProvider(opts?: SovereignResolveOptions): ResolvedSovereignProvider;
/**
 * Async sovereign-first resolution — prefers the serving fleet
 * (dynamic-resolve; the GET also bumps demand so the autoscaler warms a box),
 * gracefully falling back to the sync chain when the fleet is cold or
 * unreachable, so scale-to-zero never breaks a caller.
 */
declare function resolveSovereignProviderAsync(opts?: SovereignResolveOptions): Promise<ResolvedSovereignProvider>;

/**
 * Model Policy — THE single source of truth for the ecosystem's model DEFAULTS
 * and the model BLACKLIST. "Lock in our models": to change a default, edit it
 * HERE, not in the ~20 files that used to hardcode the same string.
 *
 * Division of responsibility:
 *   - Per-provider model CATALOGS (which models a provider offers + their
 *     capabilities) live WITH their adapters — OPENAI_MODELS, ANTHROPIC_MODELS,
 *     GEMINI_MODELS, XAI_MODELS, LOCAL_LLM_MODELS, BITNET_MODELS, … . That is
 *     correct: a provider owns its own model list.
 *   - This module owns the cross-cutting POLICY: which model each TIER selects by
 *     default, and which models are REFUSED everywhere (the blacklist).
 *
 * Everything that needs "the default local/fleet/cloud model" imports from here.
 * `@holoscript/llm-provider` is the lowest-level package in the model stack
 * (core, studio, mcp-server, services all depend on it; it depends on none of
 * them), so this is a cycle-free home for the SSOT.
 *
 * @version 1.0.0
 */
/**
 * Canonical sovereign LOCAL (Ollama) default model. The on-device / LAN tier
 * (daily-driver Ollama, Jetson edge node).
 *
 * `qwen3:4b-instruct-2507` (classic Qwen3, non-thinking, 256K) — chosen over the
 * earlier `qwen3.5:4b` because Qwen3.5 reproduces the BLACKLISTED-class failure
 * on Ollama: it was trained on the Qwen3-Coder XML tool-call format, but Ollama
 * sends the Hermes-JSON parser, so tool calls fall through as PLAIN TEXT
 * (Ollama #14745/#14493) — the exact symptom we blacklisted qwen2.5 for. The
 * 2507 line has the proven Hermes parser path + BFCL ~62%/82.6% AST. See
 * research/2026-06-16_open-weight-model-lane-evaluation.md (W.512). The local
 * picker still PREFERS behaviorally-verified discovery; this is the floor.
 */
declare const LOCAL_DEFAULT_MODEL = "qwen3:4b-instruct-2507";
/**
 * Canonical FLEET serving default — the model the sovereign GPU fleet serves
 * (vLLM / scale-to-zero autoscaler) when no explicit served model is pinned.
 * For the served CODE lane prefer LANE_DEFAULTS.code_served (qwen3-coder:30b).
 */
declare const FLEET_DEFAULT_MODEL = "qwen3:4b-instruct-2507";
/**
 * Canonical CLOUD frontier default — the BYOK fallback when sovereign tiers are
 * unavailable AND a frontier key is present (F.112 sovereign-first, BYOK-fallback).
 */
declare const CLOUD_DEFAULT_MODEL = "claude-opus-4-8";
/**
 * Back-compat alias: the local model picker's "safe fallback" IS the local
 * default. Kept as a named export so existing call sites keep working.
 */
declare const SAFE_LOCAL_FALLBACK = "qwen3:4b-instruct-2507";
/**
 * Per-lane default models (D.085 "variable models per scenario"). Evidence-based
 * from research/2026-06-16_open-weight-model-lane-evaluation.md. A lane router
 * (capacity-plan Gap #2) selects these per request; until that wiring lands they
 * document the intended model per lane and back per-lane env overrides.
 *
 * NOTE: `code_served` / `vision` / `fleet_worker` tags must be pulled/served on
 * the target box before a lane routes to them (verify on Ollama/fleet first).
 */
declare const LANE_DEFAULTS: {
    /** CODE, local 4B — proven Hermes tool-calls. */
    readonly code_local: "qwen3:4b-instruct-2507";
    /** CODE, fleet-served — purpose-built tool-calling (30B-A3B). */
    readonly code_served: "qwen3-coder:30b";
    /** OPERATOR — fast short chat; served alt: glm-4.5-air / minimax-m2. */
    readonly operator: "qwen3:4b";
    /** REASONING — cloud frontier; open co-primary: deepseek-v4-pro / kimi-k2.6. */
    readonly reasoning: "claude-opus-4-8";
    /** VISION — local GUI/screenshot agent (fills the cloud-only vision gap). */
    readonly vision: "qwen3-vl:4b";
    /** FLEET-WORKER — cheap 0.5-1.5B tool-caller; closes capacity-plan Gap #1. */
    readonly fleet_worker: "granite4:1b";
};
type ModelLane = keyof typeof LANE_DEFAULTS;
/** The default model for a given lane (non-blacklisted by construction). */
declare function laneDefault(lane: ModelLane): string;
/** Execution tier a model runs in. */
type ModelTier = 'local' | 'fleet' | 'cloud';
/** A catalog entry: a recommended model + the metadata lane routing / UIs need. */
interface ModelLibraryEntry {
    /** Canonical id — Ollama tag for local/fleet, provider id for cloud. */
    id: string;
    /** Lanes this model is recommended for. */
    lanes: ModelLane[];
    /** Approx parameters in billions (ACTIVE params for MoE; 0 = cloud/N-A). */
    paramsB: number;
    /** License family — all entries are NMoS-clean to self-host or BYOK. */
    license: 'apache-2.0' | 'mit' | 'gemma' | 'frontier';
    /** Where it runs. */
    tier: ModelTier;
    /** One-line capability note (tool-calling quality / caveat). */
    note: string;
}
/**
 * THE model library — the current (2026-06) open-weight catalog the ecosystem
 * recommends, distilled from research/2026-06-16_open-weight-model-lane-evaluation.md.
 * LANE_DEFAULTS picks ONE model per lane; this is the fuller set incl. alternatives
 * so a lane router / model-picker UI can choose. Non-blacklisted by construction.
 *
 * ⚠ Local/fleet tags must be pulled/served on the target box before use; the
 * local picker's behavioral tool-call probe remains the real gate. Update this
 * list (and LANE_DEFAULTS) as the open-weight landscape moves — it is the SSOT.
 */
declare const MODEL_LIBRARY: readonly ModelLibraryEntry[];
/** Library entries recommended for a lane. */
declare function modelsForLane(lane: ModelLane): ModelLibraryEntry[];
/** Look up a library entry by exact id. */
declare function modelLibraryEntry(id: string): ModelLibraryEntry | undefined;
/**
 * Model families the ecosystem refuses to auto-select. qwen2.5 (esp.
 * qwen2.5-coder:7b) FALSELY reports `tools` support in /api/show capabilities
 * yet emits malformed / prose tool calls — it lies past the capability check and
 * silently degrades real agent turns. Matched case-insensitively as a SUBSTRING
 * so every tag and quant variant (qwen2.5-coder:7b, qwen2.5:14b-instruct-q4_K_M,
 * qwen2.5-7b-instruct, …) is covered.
 */
declare const MODEL_BLACKLIST: readonly string[];
/** True when `name` matches a blacklisted model family (case-insensitive substring). */
declare function isBlacklistedModel(name: string | undefined | null): boolean;
/**
 * Resolve a requested model against policy: returns it unless it is blacklisted,
 * in which case `fallback` (default: the safe local default) is returned. Use at
 * any seam that accepts an external/explicit model string.
 */
declare function resolveAllowedModel(requested: string | undefined | null, fallback?: string): string;

/**
 * HoloWeight v1 — backend-neutral planning for contract-carrying model-weight changes.
 *
 * This module never loads tensors, trains a model, mutates serving state, or pretends an
 * empirical behavior claim is statically proven. It validates physical compatibility and graph
 * integrity, then exposes the behavioral receipts still required for an external admission
 * transaction.
 */
type ContentDigest = `sha256:${string}`;
type WeightArtifactFormat = 'safetensors' | 'gguf' | 'onnx' | 'peft' | 'other';
interface WeightArtifactRef {
    digest: ContentDigest;
    format: WeightArtifactFormat;
}
interface WeightCompatibility {
    baseDigest: ContentDigest;
    architecture: string;
    tokenizerDigest: ContentDigest;
    targetModules: string[];
    dtype?: string;
    rank?: number;
}
type WeightDeltaRole = 'generator' | 'critic' | 'router' | 'teacher';
type WeightActivationMode = 'global' | 'task_scoped' | 'shadow_only';
/**
 * Declares what a weight delta is allowed to do at runtime. The planner defaults
 * legacy deltas to a global, user-visible generator. Any narrower activation
 * scope must fail closed to an immutable previously admitted head.
 */
interface WeightRoleContract {
    role: WeightDeltaRole;
    activation: {
        mode: WeightActivationMode;
        taskTags?: string[];
        minRouterConfidence?: number;
        allowUserVisibleOutput: boolean;
        fallbackHead?: ContentDigest;
    };
}
interface WeightDelta {
    id: string;
    artifact: WeightArtifactRef;
    compatibility: WeightCompatibility;
    provides: string[];
    mustPreserve: string[];
    producerRef: string;
    roleContract?: WeightRoleContract;
}
type EvaluationRule = {
    kind: 'minimum';
    value: number;
} | {
    kind: 'maximum';
    value: number;
} | {
    kind: 'improves_by';
    value: number;
} | {
    kind: 'non_regression';
    tolerance: number;
};
type EvaluatorPolicy = 'deterministic' | 'provenance_independent' | 'cross_family';
interface EvaluationRequirement {
    id: string;
    subject: string;
    metric: string;
    suiteDigest: ContentDigest;
    rule: EvaluationRule;
    minSeeds: number;
    evaluatorPolicy: EvaluatorPolicy;
}
interface EvaluationReceiptRef {
    requirementId: string;
    candidateDigest: ContentDigest;
    receiptDigest: ContentDigest;
    evaluatorRef: string;
    /**
     * Consensus metadata is optional for deterministic evaluators, but is required by
     * provenance_independent and cross_family policies. `signatureVerified` is asserted by the
     * receipt-verification boundary (for example HoloTune's EIP-191 verifier), not by this planner.
     */
    evaluatorFamily?: string;
    signerAddress?: string;
    signatureVerified?: boolean;
    seed?: number;
    seedCount: number;
    passed: boolean;
}
type WeightCompositionMethod = 'linear' | 'concat' | 'ties' | 'dare_ties' | 'custom';
interface WeightComposition {
    id: string;
    inputs: string[];
    method: WeightCompositionMethod;
    parameters?: Record<string, number | string | boolean>;
}
interface WeightDeltaGraph {
    schema: 'holoweight.graph.v1';
    id: string;
    /**
     * Exact content identity supplied by the materialization/content-addressing layer.
     * V1 validates and binds this digest but deliberately does not generate it.
     */
    candidateDigest: ContentDigest;
    base: {
        artifact: WeightArtifactRef;
        architecture: string;
        tokenizerDigest: ContentDigest;
    };
    deltas: WeightDelta[];
    compositions: WeightComposition[];
    requirements: EvaluationRequirement[];
    receipts?: EvaluationReceiptRef[];
    previousAdmittedHead?: ContentDigest;
}
type WeightGraphReadiness = 'invalid' | 'candidate' | 'ready';
type WeightPlanIssueCode = 'INVALID_GRAPH_SCHEMA' | 'GRAPH_ID_REQUIRED' | 'CANDIDATE_DIGEST_INVALID' | 'BASE_DIGEST_INVALID' | 'BASE_ARCHITECTURE_REQUIRED' | 'BASE_TOKENIZER_DIGEST_INVALID' | 'DELTA_ID_REQUIRED' | 'DUPLICATE_NODE_ID' | 'DELTA_ARTIFACT_DIGEST_INVALID' | 'DELTA_PRODUCER_REQUIRED' | 'WEIGHT_BASE_MISMATCH' | 'WEIGHT_ARCHITECTURE_MISMATCH' | 'WEIGHT_TOKENIZER_MISMATCH' | 'TARGET_MODULES_REQUIRED' | 'TARGET_MODULE_REQUIRED' | 'DUPLICATE_TARGET_MODULE' | 'INVALID_ADAPTER_RANK' | 'SEMANTIC_LABEL_REQUIRED' | 'WEIGHT_ROLE_INVALID' | 'ACTIVATION_MODE_INVALID' | 'ACTIVATION_TASK_TAG_REQUIRED' | 'ACTIVATION_TASK_TAG_INVALID' | 'DUPLICATE_ACTIVATION_TASK_TAG' | 'ACTIVATION_TASK_TAGS_FORBIDDEN' | 'ACTIVATION_ROUTER_CONFIDENCE_REQUIRED' | 'ACTIVATION_ROUTER_CONFIDENCE_INVALID' | 'ROLE_OUTPUT_VISIBILITY_INVALID' | 'ROLE_OUTPUT_VISIBILITY_FORBIDDEN' | 'ROLE_FALLBACK_HEAD_REQUIRED' | 'ROLE_FALLBACK_HEAD_INVALID' | 'ROLE_FALLBACK_HEAD_MISMATCH' | 'COMPOSITION_ID_REQUIRED' | 'COMPOSITION_INPUT_REQUIRED' | 'DUPLICATE_COMPOSITION_INPUT' | 'COMPOSITION_INPUT_FORWARD_REFERENCE' | 'COMPOSITION_INPUT_NOT_FOUND' | 'REQUIREMENT_REQUIRED' | 'REQUIREMENT_ID_REQUIRED' | 'DUPLICATE_REQUIREMENT_ID' | 'REQUIREMENT_SUBJECT_REQUIRED' | 'REQUIREMENT_SUBJECT_NOT_DECLARED' | 'REQUIREMENT_METRIC_REQUIRED' | 'REQUIREMENT_SUITE_DIGEST_INVALID' | 'REQUIREMENT_MIN_SEEDS_INVALID' | 'REQUIREMENT_RULE_INVALID' | 'RECEIPT_REQUIREMENT_NOT_FOUND' | 'RECEIPT_DIGEST_INVALID' | 'RECEIPT_EVALUATOR_REQUIRED' | 'RECEIPT_SEED_COUNT_INVALID' | 'CONFLICTING_REQUIREMENT_RECEIPTS' | 'PREVIOUS_HEAD_DIGEST_INVALID';
interface WeightPlanIssue {
    code: WeightPlanIssueCode;
    severity: 'error' | 'warning';
    path: string;
    message: string;
}
type AdmissionRequirementStatus = 'missing' | 'candidate_mismatch' | 'under_seeded' | 'failed' | 'invalid_receipt' | 'unverified_evaluator' | 'insufficient_independence' | 'insufficient_families' | 'satisfied';
interface AdmissionRequirementPlan {
    requirementId: string;
    status: AdmissionRequirementStatus;
    receipt?: EvaluationReceiptRef;
    receipts?: EvaluationReceiptRef[];
    evaluatorEvidence?: {
        verifiedSigners: string[];
        evaluatorFamilies: string[];
        seedCount: number;
    };
}
type WeightExecutionStep = {
    kind: 'select-base';
    artifact: WeightArtifactRef;
    architecture: string;
    tokenizerDigest: ContentDigest;
} | {
    kind: 'apply-delta';
    deltaId: string;
    artifact: WeightArtifactRef;
    roleContract: WeightRoleContract;
} | {
    kind: 'compose';
    compositionId: string;
    inputs: string[];
    method: WeightCompositionMethod;
    parameters?: Record<string, number | string | boolean>;
} | {
    kind: 'evaluate';
    requirementId: string;
    candidateDigest: ContentDigest;
    suiteDigest: ContentDigest;
    minSeeds: number;
    evaluatorPolicy: EvaluatorPolicy;
} | {
    kind: 'admit';
    candidateDigest: ContentDigest;
    ready: boolean;
} | {
    kind: 'select-rollback-head';
    head: ContentDigest;
};
interface WeightExecutionPlan {
    graphId: string;
    candidateDigest: ContentDigest;
    readiness: WeightGraphReadiness;
    issues: WeightPlanIssue[];
    steps: WeightExecutionStep[];
    semanticLabels: {
        provides: string[];
        mustPreserve: string[];
    };
    admissionRequirements: AdmissionRequirementPlan[];
    rollbackHead?: ContentDigest;
}
/**
 * Validate a HoloWeight graph and emit the deterministic work/evidence plan for its exact
 * candidate. `ready` means ready for an external admission transaction; this function does not
 * perform that transaction.
 */
declare function planWeightDeltaGraph(graph: WeightDeltaGraph): WeightExecutionPlan;

/**
 * Local model picker — discovery over hardcodes (founder 2026-06-10:
 * "why are we hardcoding 1 qwen model, don't we have a large variety?").
 *
 * Instead of pinning one Ollama tag, enumerate what is actually installed
 * (/api/tags), keep models whose template supports tools (/api/show
 * capabilities), rank by modernity + size, and BEHAVIORALLY verify the top
 * candidate with one tiny forced tool call. The capability flag alone is a
 * liar: qwen2.5-coder:7b reports `tools` in capabilities yet emits the call
 * JSON as plain text (proven 2026-06-10 — the tend_garden stall / the
 * zero-objects benchmark cells). Only a model that actually returns
 * `tool_calls` passes.
 *
 * Pull a better model tomorrow → it gets picked automatically. Env override
 * (HOLO_LLM_MODEL / BRITTNEY_MODEL, surfaced via opts.override) always wins
 * and skips discovery entirely.
 */
/**
 * Canonical default endpoint for the LOCAL Ollama tier. Single source for the
 * one allowed localhost literal (founder-ruled 2026-06-10): the local tier is
 * only reachable after OLLAMA_* env explicitly selected it in auto-detect, or
 * via explicit provider=ollama — production sovereign surfaces (fleet, cloud)
 * always rank above it. Ollama's own server binds this address by default.
 */
declare const OLLAMA_DEFAULT_BASE_URL = "http://localhost:11434";

interface LocalModelChoice {
    model: string;
    /** How the choice was made — env pin, verified discovery, or static fallback. */
    source: 'override' | 'discovery' | 'fallback';
    /** True when the model passed the live tool-call probe (always true for discovery). */
    toolCallVerified: boolean;
    /** Every installed model considered, in ranked order (diagnostics). */
    candidates: string[];
}
declare function pickLocalModel(baseURL: string, opts?: {
    override?: string;
    fallback?: string;
    /** Skip candidates above this parameter count (default 15B — keeps a
     * surprise 70B pull from silently making every turn minutes long). */
    maxParamsB?: number;
    timeoutMs?: number;
}): Promise<LocalModelChoice>;
/** Test hook: clear the per-process picker cache. */
declare function __clearLocalModelPickerCache(): void;

/**
 * @fileoverview Quest Generator
 * @module @holoscript/llm-provider
 *
 * PURPOSE:
 * Uses configured LLMs to dynamically generate business quest narratives, NPC
 * dialogues, and localized hooks based on a business's geo-anchor context.
 */

interface QuestNarrativeRequest {
    business_name: string;
    business_type: string;
    location: string;
    theme?: string;
    target_audience?: string;
}
interface QuestNarrativeResponse {
    title: string;
    description: string;
    npc_greeting: string;
    success_message: string;
}
declare class QuestGenerator {
    private llmManager;
    constructor(manager: LLMProviderManager);
    /**
     * Generates a complete narrative suite for a new Business Quest
     * @param request The parameters for the business and location
     */
    generateQuestNarrative(request: QuestNarrativeRequest): Promise<QuestNarrativeResponse>;
}

/**
 * KVFlow Types — workflow-aware KV cache management for multi-agent systems.
 *
 * Inspired by KVFlow (arXiv:2507.07400): Agent Step Graph, steps-to-execution
 * eviction, and overlapped prefetch. Sovereign re-implementation on HoloScript's
 * substrate — NOT an adoption of the SGLang binary or radix cache.
 *
 * @module @holoscript/llm-provider/kvflow
 * @version 0.1.0
 */
/**
 * Unique identifier for an agent step node. Format: `{agentId}:{stepIndex}`
 * where `stepIndex` is the sequential activation count for that agent within
 * the current workflow.
 */
type StepNodeId = string;
/**
 * Cache scope mirrors BrainCachingScope from brittney/caching.ts but is
 * independent so @holoscript/llm-provider doesn't depend on @holoscript/studio.
 *
 * - `shared-prefix`: team-board context (stable, reused across many agents)
 * - `role-overlay`: per-agent role composition (stable within a session)
 * - `scene-turn`: ephemeral per-turn context (low reuse, high churn)
 */
type KVFlowScope = 'shared-prefix' | 'role-overlay' | 'scene-turn';
/**
 * Residency state of a KV cache entry. Mirrors PagedKVCache.PageRef but
 * generalized for any backing store (GPU pages, CPU pages, remote cache).
 */
type KVResidency$1 = 'device' | 'host' | 'evicted';
/**
 * A single step in the agent workflow graph. Each step represents one
 * activation of an agent (one LLM call cycle: prompt in → completion out).
 *
 * Steps are the scheduling unit for KVFlow — the cache manager uses the
 * graph topology to decide what to evict and what to prefetch.
 */
interface AgentStep {
    /** Unique node id within this graph (agentId:stepIndex). */
    id: StepNodeId;
    /** Which agent this step belongs to (e.g. 'claudecode-claude-x402'). */
    agentId: string;
    /** Sequential activation index for this agent within the workflow. */
    stepIndex: number;
    /** Caching scope of the KV prefix this step uses. */
    scope: KVFlowScope;
    /** Estimated token count for this step's KV entry (prefix + overlay). */
    estimatedTokens: number;
    /**
     * Steps that must complete before this one can start.
     * Edges in the dependency graph — the KV cache uses these to compute
     * "steps-to-execution" (how many other steps will run before this agent
     * is re-activated).
     */
    dependsOn: StepNodeId[];
    /** Wall-clock priority hint (lower = higher priority for cache residency). */
    priority: number;
    /** Timestamp of the most recent activation (ISO 8601). */
    lastActivatedAt?: string;
}
/**
 * A single KV cache entry tracked by the KVFlow manager. Each entry maps
 * to one agent step's KV tensor (shared prefix + role overlay).
 */
interface KVCacheEntry {
    /** The agent step this entry belongs to. */
    stepId: StepNodeId;
    /** Cache scope (shared prefix vs role overlay vs scene turn). */
    scope: KVFlowScope;
    /** Current residency of this entry's KV tensors. */
    residency: KVResidency$1;
    /**
     * Steps-to-execution value from the AgentStepGraph. Lower = more likely
     * to be needed soon = higher cache priority.
     */
    stepsToExecution: number;
    /** Estimated GPU memory footprint in bytes. */
    estimatedBytes: number;
    /** Timestamp this entry was last used or prefetched (ISO 8601). */
    lastUsedAt: string;
    /**
     * Whether this entry shares a prefix root with other entries.
     * Shared-prefix entries (team-board scope) are protected from eviction
     * until ALL dependent overlays are evicted first.
     */
    isSharedPrefix: boolean;
    /** Step IDs that depend on this entry's prefix (only set for shared-prefix scope). */
    dependentOverlayIds: StepNodeId[];
}
/**
 * Configuration for the KVFlow cache manager.
 */
interface KVFlowConfig {
    /** Maximum GPU memory available for KV cache, in bytes. */
    maxGpuMemoryBytes: number;
    /**
     * Fraction of max GPU memory to reserve for shared prefixes.
     * These entries are never evicted until all overlays are gone.
     * Default: 0.4 (40% for team-board context).
     */
    sharedPrefixReserveFraction: number;
    /**
     * Prefetch lookahead window — how many future steps to warm.
     * Default: 2 (prefetch KV for the next 2 agents in the schedule).
     */
    prefetchLookahead: number;
    /**
     * Minimum steps-to-execution threshold. Entries with STE below this
     * value are never evicted (they'll be needed too soon).
     * Default: 1 (currently-executing steps are always retained).
     */
    minRetentionSte: number;
    /**
     * Background prefetch concurrency. How many KV entries can be
     * loaded from CPU to GPU simultaneously.
     * Default: 1 (serial prefetch — conservative for single-GPU setups).
     */
    prefetchConcurrency: number;
}
/**
 * Result of an eviction pass. The cache manager runs this when GPU memory
 * pressure exceeds the threshold.
 */
interface EvictionResult {
    /** Entries that were evicted from GPU (residency moved to 'evicted'). */
    evicted: KVCacheEntry[];
    /** Entries that were demoted from GPU to CPU (residency moved to 'host'). */
    demoted: KVCacheEntry[];
    /** Entries that were retained on GPU. */
    retained: KVCacheEntry[];
    /** GPU memory freed by this eviction, in bytes. */
    freedBytes: number;
    /** Current GPU memory usage after eviction, in bytes. */
    usedBytesAfter: number;
}
/**
 * Result of a prefetch pass. The cache manager runs this proactively to
 * warm KV entries for agents scheduled in the near future.
 */
interface PrefetchResult {
    /** Entries successfully prefetched from CPU to GPU. */
    prefetched: KVCacheEntry[];
    /** Entries that couldn't be prefetched (insufficient GPU memory, etc.). */
    failed: KVCacheEntry[];
    /** Time spent on prefetch in milliseconds. */
    durationMs: number;
    /** Total bytes transferred from CPU to GPU. */
    bytesTransferred: number;
}
/**
 * Telemetry event emitted by the KVFlow manager. Wired to the early-warning
 * telemetry in holoscript-agent/cost-guard and the /pipeline-audit + /reflect
 * skill surfaces.
 */
interface KVFlowTelemetry {
    /** Type of telemetry event. */
    type: 'eviction' | 'prefetch' | 'hit' | 'miss' | 'pressure';
    /** Agent step that triggered this event. */
    stepId: StepNodeId;
    /** Cache scope of the affected entry. */
    scope: KVFlowScope;
    /** Steps-to-execution value at the time of this event. */
    stepsToExecution: number;
    /** Timestamp (ISO 8601). */
    timestamp: string;
    /** GPU memory usage at the time of this event, in bytes. */
    gpuUsedBytes: number;
    /** Total GPU memory available, in bytes. */
    gpuTotalBytes: number;
    /** For hit/miss events: was this a cache hit or miss? */
    cacheHit?: boolean;
    /** For eviction events: entries evicted in this pass. */
    evictedCount?: number;
    /** For prefetch events: entries prefetched in this pass. */
    prefetchedCount?: number;
    /** For pressure events: current pressure ratio (0.0–1.0). */
    pressureRatio?: number;
}

/**
 * AgentStepGraph — directed graph of agent activations for KVFlow-aware
 * KV cache management.
 *
 * Models the multi-agent workflow as a dependency graph where each node
 * is an agent activation (step) and edges represent scheduling dependencies.
 * The KVFlow cache manager uses graph topology to compute "steps-to-execution"
 * (STE) for eviction and prefetch decisions.
 *
 * @module @holoscript/llm-provider/kvflow
 * @version 0.1.0
 */

/**
 * In-memory AgentStepGraph implementation. Constructed from HoloMesh team
 * board data (active agents, roles, priorities) and updated as agents
 * activate/deactivate during the workflow lifecycle.
 *
 * Lifecycle:
 * 1. Build initial graph from team board (which agents are active, their
 *    dependencies and priorities).
 * 2. As agents execute, update `lastActivatedAt` and `stepIndex`.
 * 3. When an agent session ends, remove its steps.
 * 4. The cache manager calls `computeStepsToExecution()` to drive eviction
 *    and `nextScheduled()` to drive prefetch.
 */
declare class InMemoryAgentStepGraph {
    private readonly steps;
    /** Reverse index: stepId → set of steps that depend on it (forward edges). */
    private readonly dependents;
    addStep(step: AgentStep): void;
    removeStep(stepId: StepNodeId): void;
    getStep(stepId: StepNodeId): AgentStep | undefined;
    allSteps(): AgentStep[];
    stepCount(): number;
    /**
     * Compute the "steps-to-execution" (STE) value for every node.
     *
     * KVFlow's core insight: eviction should be workflow-aware, not just
     * recency-based. An entry with STE=0 is currently executing; higher STE
     * means more steps before this agent runs again, making it a better
     * eviction candidate.
     *
     * Algorithm:
     * 1. Active steps get STE = 0 (they're executing now).
     * 2. For every other step, STE = length of the shortest path from any
     *    active step through the dependency graph, using BFS.
     * 3. Steps unreachable from any active step get STE = max topological
     *    position (fairness fallback — they'll be needed eventually).
     * 4. Shared-prefix scope entries get STE reduced by 1 (they're reused
     *    by multiple agents, so they're effectively "closer" to execution).
     *    Minimum STE for shared-prefix is 0 (never evict currently-active
     *    shared prefixes).
     */
    computeStepsToExecution(activeStepIds: StepNodeId[]): Map<StepNodeId, number>;
    /**
     * Get the next N agents scheduled to execute after the given step.
     * Uses BFS from the step's dependents to find agents in execution order.
     */
    nextScheduled(stepId: StepNodeId, count: number): AgentStep[];
    /**
     * Topological sort of the dependency graph. Used as fallback for
     * computing STE when no active steps exist.
     */
    private topologicalSort;
    /**
     * Serialize to a plain object for persistence, debugging, or telemetry.
     */
    toJSON(): {
        steps: AgentStep[];
    };
    /**
     * Reconstruct from a serialized graph.
     */
    static fromJSON(data: {
        steps: AgentStep[];
    }): InMemoryAgentStepGraph;
}

/**
 * The KVFlow cache manager. Maintains an in-memory model of KV cache entries,
 * an AgentStepGraph for workflow-aware scheduling, and drives eviction/prefetch
 * decisions based on steps-to-execution values.
 *
 * This is a *coordination layer* — it doesn't manage actual GPU memory or
 * tensor transfers. Downstream adapters (PagedKVCache, Anthropic prompt cache,
 * etc.) implement the residency transitions. This manager tells them *what*
 * to evict, prefetch, or retain.
 *
 * Wire to the @caching declaration via `scopeFromBrainCaching()` which maps
 * BrainCachingScope → KVFlowScope.
 */
declare class KVFlowCacheManager {
    private readonly config;
    private readonly graph;
    private readonly entries;
    private readonly telemetry;
    private readonly bytesPerToken;
    private activeStepIds;
    constructor(config?: Partial<KVFlowConfig>);
    /**
     * Register an agent step into the workflow graph.
     * Call when an agent activates, claims a task, or changes role.
     */
    addStep(step: AgentStep): void;
    /**
     * Remove an agent step (and its edges) from the graph.
     * Call when an agent deactivates or its session ends.
     */
    removeStep(stepId: StepNodeId): void;
    /**
     * Get the underlying step graph for direct inspection.
     */
    getGraph(): InMemoryAgentStepGraph;
    /**
     * Set the currently active (executing) steps. These get STE=0 in eviction
     * calculations and are never evicted.
     */
    setActiveSteps(stepIds: StepNodeId[]): void;
    /**
     * Register a KV cache entry for an agent step. Call when an agent's
     * KV tensors are first loaded (either freshly computed or prefetched).
     */
    addEntry(entry: KVCacheEntry): void;
    /**
     * Mark a cache entry as used (updates lastUsedAt timestamp and
     * recomputes STE from the graph). Call on every cache hit.
     */
    touchEntry(stepId: StepNodeId, now?: string): void;
    /**
     * Get a cache entry by step ID.
     */
    getEntry(stepId: StepNodeId): KVCacheEntry | undefined;
    /**
     * Get all cache entries.
     */
    getAllEntries(): KVCacheEntry[];
    /**
     * Run an eviction pass when GPU memory pressure exceeds threshold.
     *
     * Strategy:
     * 1. Compute STE for all entries using the AgentStepGraph.
     * 2. Protect entries with STE <= minRetentionSte (they'll be needed soon).
     * 3. Protect shared-prefix entries until ALL their dependent overlays are evicted.
     * 4. Evict scene-turn entries with highest STE first.
     * 5. Demote role-overlay entries to CPU (host) before evicting entirely.
     * 6. Evict role-overlay entries with highest STE if still over pressure.
     *
     * Returns the eviction result with entries categorized by action.
     */
    evict(targetFreedBytes: number): EvictionResult;
    /**
     * Run a prefetch pass for agents scheduled to execute soon.
     *
     * Uses the AgentStepGraph to identify the next N agents in the schedule,
     * checks if their KV entries are on CPU (host) or evicted, and initiates
     * background transfer to GPU.
     *
     * This is the "overlapped prefetch" from KVFlow: while the current agent
     * generates tokens, the next agent's KV tensors are being loaded in
     * parallel, hiding PCIe transfer latency.
     *
     * In a real implementation, this would dispatch GPU memory copy operations
     * on a background thread/stream. Here, we model the scheduling decision
     * and return the prefetch plan for the adapter layer to execute.
     */
    prefetch(currentStepId: StepNodeId): PrefetchResult;
    /**
     * Record a cache hit for an agent step. Updates STE and emits telemetry.
     * Call when a cached KV entry is reused without recomputation.
     */
    recordHit(stepId: StepNodeId): void;
    /**
     * Record a cache miss for an agent step. Emits telemetry.
     * Call when an agent's KV tensors need to be recomputed from scratch.
     */
    recordMiss(stepId: StepNodeId, scope: KVFlowScope): void;
    /**
     * Get recent telemetry events. Used by /pipeline-audit and /reflect
     * to surface KVFlow hit rate and prefetch metrics.
     */
    getTelemetry(limit?: number): KVFlowTelemetry[];
    /**
     * Compute cache hit rate over recent telemetry.
     */
    hitRate(sampleSize?: number): {
        hits: number;
        misses: number;
        rate: number;
    };
    /**
     * Current GPU memory pressure (0.0 = empty, 1.0 = full).
     */
    pressure(): number;
    private currentGpuUsage;
    private emitTelemetry;
}
/**
 * Map Brittney's BrainCachingScope to KVFlowScope.
 * This is the bridge between the @caching declaration in brain compositions
 * and the KVFlow cache manager's eviction policy.
 *
 * BrainCachingScope → KVFlowScope:
 * - 'team-board' → 'shared-prefix' (high reuse, protected in eviction)
 * - 'agent-role' → 'role-overlay' (medium reuse, demoted before eviction)
 * - 'scene-local' → 'scene-turn' (low reuse, evicted first)
 */
declare function scopeFromBrainCaching(brainScope: 'team-board' | 'agent-role' | 'scene-local'): KVFlowScope;
/**
 * Map KVFlowScope back to BrainCacheUsage for telemetry and diagnostics.
 */
declare function scopeToCacheUsage(scope: KVFlowScope): 'shared-prefix' | 'role-overlay' | 'scene-turn';
/**
 * Estimate the byte size of a KV cache entry from its token count.
 * Uses a configurable bytes-per-token estimate (default 512 bytes/token).
 */
declare function estimateKVBytes(tokenCount: number, bytesPerToken?: number): number;
/**
 * Create a KVCacheEntry from an AgentStep and computed STE value.
 * Convenience factory for wiring step graph → cache manager.
 */
declare function entryFromStep(step: AgentStep, stepsToExecution: number, residency?: KVResidency, dependentOverlayIds?: StepNodeId[], bytesPerToken?: number): KVCacheEntry;
type KVResidency = KVResidency$1;

interface QuestParams {
    locationName: string;
    theme: 'cyberpunk' | 'fantasy' | 'historical' | 'mystery';
    difficulty: 'easy' | 'medium' | 'hard';
    poiContext?: string;
}
interface GeneratedQuest {
    title: string;
    loreDescription: string;
    objectives: {
        id: string;
        instruction: string;
    }[];
    npcDialogue: {
        trigger: string;
        text: string;
    }[];
    rewardMetadata: {
        assetId: string;
        dropRate: number;
    };
}
/**
 * Service to dynamically generate narrative quests anchored to real-world or digital locations.
 * Pipes into BusinessQuestTools.
 */
declare class NarrativeQuestService {
    private static instance;
    static getInstance(): NarrativeQuestService;
    /**
     * Generates a fully fleshed out quest narrative for an agent or player.
     */
    generateQuestNarrative(params: QuestParams): Promise<GeneratedQuest>;
}
declare function getNarrativeQuestService(): NarrativeQuestService;

/**
 * @holoscript/llm-provider
 *
 * Unified LLM provider SDK for HoloScript.
 * Supports OpenAI, Anthropic (Claude), Google Gemini, and Mock adapters
 * with a consistent interface for scene generation and AI integration.
 *
 * @example
 * ```typescript
 * import { AnthropicAdapter, LLMProviderManager } from '@holoscript/llm-provider';
 *
 * const claude = new AnthropicAdapter({ apiKey: process.env.ANTHROPIC_API_KEY! });
 * const scene = await claude.generateHoloScript({
 *   prompt: "a floating island with glowing crystals and a waterfall",
 * });
 * console.log(scene.code);
 * ```
 *
 * @module @holoscript/llm-provider
 * @version 1.0.0
 */

/**
 * Create an OpenAI adapter from environment variables.
 * Uses OPENAI_API_KEY environment variable.
 */
declare function createOpenAIProvider(config?: Partial<OpenAIProviderConfig>): OpenAIAdapter;
/**
 * Create an Anthropic adapter from environment variables.
 * Uses ANTHROPIC_API_KEY environment variable.
 */
declare function createAnthropicProvider(config?: Partial<AnthropicProviderConfig>): AnthropicAdapter;
/**
 * Create a Gemini adapter from environment variables.
 * Uses GEMINI_API_KEY or GOOGLE_AI_API_KEY environment variable.
 */
declare function createGeminiProvider(config?: Partial<GeminiProviderConfig>): GeminiAdapter;
/**
 * Create a mock provider for testing (no API key required).
 */
declare function createMockProvider(): MockAdapter;
/**
 * Create a BitNet adapter targeting a local bitnet.cpp server.
 * Requires bitnet.cpp running at http://localhost:8080 (or custom baseURL).
 * No API key required — the server runs locally.
 *
 * Setup: https://github.com/microsoft/BitNet
 *   python setup_env.py -md microsoft/bitnet-b1.58-2B-4T -q i2_s
 *   python run_inference.py --serve --port 8080 --host 0.0.0.0
 *
 * @example
 * ```typescript
 * const bitnet = createBitNetProvider();
 * const health = await bitnet.healthCheck();
 * if (health.ok) {
 *   const scene = await bitnet.generateHoloScript({ prompt: 'a glowing sphere' });
 * }
 * ```
 */
declare function createBitNetProvider(config?: Partial<BitNetProviderConfig>): BitNetAdapter;
/**
 * Create a LocalLLM adapter for any OpenAI-compatible local inference server.
 * Works with llama.cpp, Ollama, LM Studio, or similar.
 * No API key required — the server runs locally.
 *
 * @example
 * ```typescript
 * // llama.cpp: llama-server -m mistral-7b-instruct.gguf --port 8080
 * const localLlm = createLocalLLMProvider({ baseURL: 'http://localhost:8080' });
 * const scene = await localLlm.generateHoloScript({ prompt: 'a glowing sphere' });
 *
 * // Ollama: ollama serve
 * const ollama = createLocalLLMProvider({ baseURL: 'http://localhost:11434', model: 'mistral' });
 * ```
 */
declare function createLocalLLMProvider(config?: Partial<LocalLLMProviderConfig>): LocalLLMAdapter;
/**
 * Create a LocalLLMAdapter from a fleet route, using the route's `backend`
 * (carried since the pytorch-holo fleet parity work) to select the wire
 * protocol IN-BAND: `ollama` → native /api/chat NDJSON, anything else
 * (llama.cpp llama-server, pytorch-holo HoloServe) → OpenAI-compat /v1/*.
 * Replaces the `:11434`-port-heuristic guess for routed consumers.
 *
 * @example
 * ```typescript
 * const picked = await resolveLocalFleet({ brainPath: process.env.HOLO_LLM_FLEET_BRAIN });
 * if (picked) {
 *   const adapter = createLocalLLMProviderForRoute(picked);
 *   const res = await adapter.complete({ messages }, picked.model);
 * }
 * ```
 */
declare function createLocalLLMProviderForRoute(route: {
    baseURL: string;
    model: string;
    backend: FleetBackend;
}, config?: Partial<LocalLLMProviderConfig>): LocalLLMAdapter;
/**
 * Create an OpenRouter adapter from environment variables.
 * Uses OPENROUTER_API_KEY environment variable.
 * OpenRouter provides an OpenAI-compatible API that routes to 200+ models.
 *
 * @example
 * ```typescript
 * const openrouter = createOpenRouterProvider();
 * const scene = await openrouter.generateHoloScript({
 *   prompt: "a floating island with glowing crystals",
 * });
 * ```
 */
declare function createOpenRouterProvider(config?: Partial<OpenRouterProviderConfig>): OpenRouterAdapter;
/**
 * Create an OpenAI-compatible Bearer adapter for any hosted endpoint that
 * speaks `${baseURL}/chat/completions` with an optional `Authorization: Bearer`
 * header (Fireworks, Together, Kimi-via-Fireworks, self-hosted vLLM/TGI/SGLang).
 *
 * Unlike the other factories this does NOT read an env var by default — the
 * endpoint baseURL is the discriminator, so the caller passes `{ baseURL,
 * apiKey?, model }` explicitly.
 *
 * @example
 * ```typescript
 * const fireworks = createOpenAICompatibleProvider({
 *   baseURL: 'https://api.fireworks.ai/inference/v1',
 *   apiKey: process.env.FIREWORKS_API_KEY,
 *   model: 'accounts/fireworks/models/llama-v3p1-8b-instruct',
 * });
 * ```
 */
declare function createOpenAICompatibleProvider(config?: Partial<OpenAICompatibleAdapterConfig>): OpenAICompatibleAdapter;
/**
 * Create an xAI (Grok) adapter from environment variables.
 * Uses XAI_API_KEY environment variable.
 * xAI provides an OpenAI-compatible API at https://api.x.ai/v1.
 *
 * @example
 * ```typescript
 * const xai = createXAIProvider();
 * const scene = await xai.generateHoloScript({
 *   prompt: "a floating island with glowing crystals",
 * });
 * ```
 */
declare function createXAIProvider(config?: Partial<XAIProviderConfig>): XAIAdapter;
/**
 * Create a Brittney Cloud adapter from environment variables.
 * Uses BRITTNEY_SERVICE_URL and optional BRITTNEY_API_KEY.
 *
 * Brittney Cloud is HoloScript's first-party inference gateway.
 * It routes to Fireworks, Together, Kimi, or Ollama backends.
 *
 * @example
 * ```typescript
 * const brittney = createBrittneyCloudProvider();
 * const scene = await brittney.generateHoloScript({
 *   prompt: "a floating island with glowing crystals",
 * });
 * ```
 */
declare function createBrittneyCloudProvider(config?: Partial<BrittneyCloudProviderConfig$1>): BrittneyCloudAdapter;
/**
 * Create a provider manager with automatic provider detection.
 * Reads API keys from environment variables.
 */
declare function createProviderManager(): LLMProviderManager;

export { type AdmissionRequirementPlan, type AdmissionRequirementStatus, type AgentStep, AnthropicAdapter, AnthropicProviderConfig, BRITTNEY_CLOUD_CAPABILITIES, BRITTNEY_CLOUD_MODELS, BaseLLMAdapter, BitNetAdapter, BitNetProviderConfig, BrittneyCloudAdapter, type BrittneyCloudLane, type BrittneyCloudModel, type BrittneyCloudProviderConfig, CLOUD_DEFAULT_MODEL, Capabilities, type ContentDigest, DEFAULT_OPENAI_REALTIME_MINI_MODEL, DEFAULT_OPENAI_REALTIME_MODEL, EphemeralSecret, type EvaluationReceiptRef, type EvaluationRequirement, type EvaluationRule, type EvaluatorPolicy, type EvictionResult, FLEET_DEFAULT_MODEL, type FetchLike, type FleetBackend, type FleetCandidate, type FleetNode, type FleetRoute, type FleetRouteOptions, type FleetSpec, GeminiAdapter, GeminiProviderConfig, HoloScriptGenerationRequest, HoloScriptGenerationResponse, ILLMProvider, InMemoryAgentStepGraph, type KVCacheEntry, KVFlowCacheManager, type KVFlowConfig, type KVFlowScope, type KVFlowTelemetry, type KVResidency$1 as KVResidency, LANE_DEFAULTS, LLMCompletionRequest, LLMCompletionResponse, LLMProviderConfig, LLMProviderManager, LLMProviderName, LLMProviderRegistry, LLMStreamChunk, LOCAL_DEFAULT_MODEL, LOCAL_LLM_CAPABILITIES, LOCAL_LLM_MODELS, LocalLLMAdapter, type LocalLLMModel, LocalLLMProviderConfig, type LocalModelChoice, MOCK_CAPABILITIES, MODEL_BLACKLIST, MODEL_LIBRARY, MockAdapter, type ModelLane, type ModelLibraryEntry, type ModelTier, NarrativeQuestService, type NodeDiscovery, OLLAMA_DEFAULT_BASE_URL, OPENAI_COMPATIBLE_CAPABILITIES, OPENAI_REALTIME_MODELS, OpenAIAdapter, OpenAICompatibleAdapter, type OpenAICompatibleAdapterConfig, OpenAIProviderConfig, OpenAIRealtimeAdapter, type OpenAIRealtimeDeps, type OpenAIRealtimeModel, OpenRouterAdapter, OpenRouterProviderConfig, type PrefetchResult, type ProviderManagerConfig, ProviderSelectionStrategy, QuestGenerator, type QuestNarrativeRequest, type QuestNarrativeResponse, type QuestParams, type RealtimeFetchLike, RealtimeSession, RealtimeSessionConfig, type RealtimeWebSocketFactory, type RealtimeWebSocketLike, type ResolvedSovereignProvider, SAFE_LOCAL_FALLBACK, type SovereignProviderName, type SovereignResolveOptions, type StepNodeId, type WeightActivationMode, type WeightArtifactFormat, type WeightArtifactRef, type WeightCompatibility, type WeightComposition, type WeightCompositionMethod, type WeightDelta, type WeightDeltaGraph, type WeightDeltaRole, type WeightExecutionPlan, type WeightExecutionStep, type WeightGraphReadiness, type WeightPlanIssue, type WeightPlanIssueCode, type WeightRoleContract, XAIAdapter, XAIProviderConfig, __clearLocalModelPickerCache, cosineSimilarity, createAnthropicProvider, createBitNetProvider, createBrittneyCloudProvider, createGeminiProvider, createLocalLLMProvider, createLocalLLMProviderForRoute, createMockProvider, createOpenAICompatibleProvider, createOpenAIProvider, createOpenRouterProvider, createProviderManager, createXAIProvider, discoverLlamaCppNode, discoverNode, discoverPytorchHoloNode, embedAcrossFleet, entryFromStep, estimateKVBytes, getNarrativeQuestService, isBlacklistedModel, laneDefault, loadFleetSpec, mintOpenAIEphemeralSecret, modelLibraryEntry, modelsForLane, openOpenAIRealtimeSession, parseFleetSpec, pickFleetModel, pickLocalModel, planWeightDeltaGraph, resolveAllowedModel, resolveLocalFleet, resolveNodeEndpoint, resolveSovereignProvider, resolveSovereignProviderAsync, scopeFromBrainCaching, scopeToCacheUsage };