@plurnk/plurnk-providers 6.1.1 → 6.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/types.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,6EAA6E;AAC7E,iCAAiC;AA2DjC,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IACpC,MAAM,CAAS;IACf,SAAS,CAAoB;IAEtC,YAAY,MAAc,EAAE,MAAc,EAAE,SAA4B,EAAE,MAAe;QACrF,yEAAyE;QACzE,qEAAqE;QACrE,+DAA+D;QAC/D,yDAAyD;QACzD,MAAM,YAAY,GAAG,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACzD,MAAM,KAAK,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,UAAU;YACzF,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,gHAAgH,CAAC,YAAY,IAAI,QAAQ,CAAC,CAAC,UAAU,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,sBAAsB,MAAM,qBAAqB,CAAC;QACnP,KAAK,CAAC,GAAG,MAAM,aAAa,MAAM,wCAAwC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC;QAC3G,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC/B,CAAC;CACJ;AAKD,MAAM,CAAC,MAAM,gBAAgB,GAA6B,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;AAW5G,8EAA8E;AAC9E,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,OAAqC,EAAU,EAAE,CAC7E,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ;IAC/B,CAAC,CAAC,OAAO,CAAC,OAAO;IACjB,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC","sourcesContent":["// Provider transport contract. Providers return raw wire-level output —\n// content unparsed (consumer parses via @plurnk/plurnk-contracts), reasoning\n// is the wire-reported CoT only.\n\nimport type { OpenAICompletionsCompat } from \"@earendil-works/pi-ai\";\nimport type { ProviderNotice } from \"./notices.ts\";\nimport type {\n ExtensionAttribution,\n ExtensionAttributionContext,\n ExtensionAttributionSource,\n} from \"@plurnk/plurnk-meta\";\nimport type {\n ProviderCost,\n ProviderRequestAccounting,\n ProviderRequestObserver,\n Effort,\n} from \"@plurnk/plurnk-contracts\";\n\nexport type ProviderModelApi =\n | \"openai-completions\"\n | \"openai-responses\"\n | \"anthropic-messages\"\n | \"google-generative-ai\"\n | \"bedrock-converse-stream\";\n\nexport interface ProviderModel {\n readonly id: string;\n readonly api: ProviderModelApi;\n readonly provider: string;\n readonly baseUrl: string;\n readonly name?: string;\n readonly reasoning?: boolean;\n readonly input?: readonly (\"text\" | \"image\")[];\n readonly cost?: {\n readonly input: number;\n readonly output: number;\n readonly cacheRead: number;\n readonly cacheWrite: number;\n };\n readonly contextWindow?: number;\n readonly maxTokens?: number;\n readonly headers?: Readonly<Record<string, string>>;\n readonly compat?: OpenAICompletionsCompat;\n readonly apiKey?: string;\n readonly env?: Readonly<Record<string, string | undefined>>;\n readonly includeTopK?: boolean;\n readonly xaiPreferResponses?: boolean;\n readonly onPayload?: (payload: unknown, model: ProviderModel) => unknown;\n}\n\nexport type {\n ProviderAccounting,\n ProviderCost,\n ProviderRequestAccounting,\n ProviderRequestIdentity,\n ProviderRequestObserver,\n ProviderRequestSettlement,\n ProviderUsage,\n Effort,\n} from \"@plurnk/plurnk-contracts\";\n\nexport class UnsupportedEffortError extends Error {\n readonly policy: Effort;\n readonly supported: readonly Effort[];\n\n constructor(source: string, policy: Effort, supported: readonly Effort[], remedy?: string) {\n // A graded-effort refusal names the operator's declaration lever (#472):\n // the catalog is authoritative per model, and where a provider's API\n // accepts more than its catalog entry lists, the remedy is the\n // operator's, never a vendored fact in shipped defaults.\n const providerName = /^provider:(.+)$/.exec(source)?.[1];\n const lever = remedy !== undefined ? ` ${remedy}` : policy === \"off\" || policy === \"adaptive\"\n ? \"\"\n : ` If the provider's API documents this effort beyond its catalog entry, declare it: PLURNK_PROVIDERS_PROVIDER_${(providerName ?? \"<NAME>\").replaceAll(/[^a-zA-Z0-9<>]/g, \"_\").toUpperCase()}_REASONING_EFFORTS=${policy} (comma-separated).`;\n super(`${source}: effort '${policy}' is unsupported; supported efforts: ${supported.join(\", \")}.${lever}`);\n this.name = \"UnsupportedEffortError\";\n this.policy = policy;\n this.supported = supported;\n }\n}\n\n// {§provider-interface} — the native non-text inputs a route's model accepts, in the\n// catalog's vocabulary (Models.dev `modalities.input` minus `text`).\nexport type InputModality = \"image\" | \"pdf\" | \"audio\" | \"video\";\nexport const INPUT_MODALITIES: readonly InputModality[] = Object.freeze([\"image\", \"pdf\", \"audio\", \"video\"]);\n// A user message may carry parts: text beside native files for a model that declares\n// the matching modality. The media type distinguishes images, PDFs, and future kinds;\n// system and assistant messages stay text.\nexport type ChatContentPart =\n | { readonly type: \"text\"; readonly text: string }\n | { readonly type: \"file\"; readonly data: Uint8Array; readonly mediaType: string };\nexport interface ChatMessage {\n role: \"system\" | \"user\" | \"assistant\";\n content: string | readonly ChatContentPart[];\n}\n// The text of a message, for counting and for transports that take only text.\nexport const chatMessageText = (message: Pick<ChatMessage, \"content\">): string =>\n typeof message.content === \"string\"\n ? message.content\n : message.content.map((part) => part.type === \"text\" ? part.text : \"\").join(\"\");\n\n// {§provider-interface} The caller-owned semantic contract for one logical model call. Providers do\n// not infer this from messages: an emission expects PLURNK\n// output, while a bare call expects unconstrained response text.\nexport type ProviderCallKind = \"emission\" | \"bare\";\n\n// {§provider-sdk-boundary} Optional caller-supplied durable prefix boundary inside the final user\n// message (`chars` when `content` is a string, `parts` when `content` is `ChatContentPart[]`),\n// separating append-mostly conversation/log evidence from trailing per-turn volatile status blocks.\nexport type FinalUserCachePrefix =\n | { readonly kind: \"chars\"; readonly length: number }\n | { readonly kind: \"parts\"; readonly count: number };\n\n// Preflight evidence for the complete provider request. An empirical estimate\n// is useful telemetry but cannot authorize hard context-envelope admission.\nexport type PromptTokenMeasurement =\n | {\n readonly kind: \"exact\" | \"upper_bound\";\n readonly tokens: number;\n readonly source: string;\n }\n | {\n readonly kind: \"estimate\";\n readonly tokens: number;\n readonly source: string;\n readonly detail: string;\n }\n | {\n readonly kind: \"unavailable\";\n readonly source: string;\n readonly detail: string;\n };\n\nexport type ProviderRequestCapacityDecision = \"admit\" | \"defer\" | \"reject\";\n\n// Complete pre-I/O evidence for one logical request. `defer` is intentional:\n// an estimate or incomplete limit set cannot safely veto a request, so the\n// upstream provider remains the capacity oracle.\nexport interface ProviderRequestCapacity {\n readonly decision: ProviderRequestCapacityDecision;\n readonly contextWindow: number | null;\n readonly maxInputTokens: number | null;\n readonly maxOutputTokens: number | null;\n readonly outputBudget: number | null;\n // {§provider-capacity-admission}: the least response room this request keeps; never above outputBudget.\n readonly outputFloor: number | null;\n readonly reasoningBudget: number | null;\n // {§provider-capacity-admission}: the curation reservation's line (maxInputTokens and\n // window − outputBudget) and the physical input wall (maxInputTokens and window − outputFloor)\n // the decision was taken against.\n readonly inputCapacity: number | null;\n readonly inputWall: number | null;\n // {§provider-capacity-admission}: the response allowance actually granted this\n // request — the window's remainder, between the floor and the model's limit.\n readonly responseMax: number | null;\n readonly prompt: PromptTokenMeasurement;\n}\n\nexport type ChargedCost = Extract<ProviderCost, { kind: \"charged\" }>;\n\n// Evidence exposed by the transport to the provider adapter that owns its\n// vendor protocol. Core and downstream consumers receive only the normalized\n// charge, never a requirement to understand provider metadata fields.\nexport interface ProviderChargeEvidence {\n readonly providerMetadata?: unknown;\n // A protocol-owned direct monetary field. It remains unknown until the\n // selected adapter explicitly validates and normalizes it.\n readonly charge?: unknown;\n // Provider-owned raw usage projection retained independently of optional\n // full-body capture. Accounting fields cannot disappear merely because\n // forensic raw-body capture is disabled.\n readonly usage?: unknown;\n readonly response: {\n readonly id?: string;\n readonly headers?: Readonly<Record<string, string>>;\n };\n}\n\nexport type ProviderCostNormalizer = (\n evidence: ProviderChargeEvidence,\n) => ProviderCost | undefined;\n\n// {§provider-interface} Transient readable-reasoning observation. The completed ProviderResponse is\n// still the sole authoritative value; this callback exposes exact, ordered,\n// nonempty deltas early enough for an attached client to render them live.\nexport type ProviderReasoningObserver = (delta: string) => void;\n\n// A successful exchange's closed finish set. ProviderAttemptFinishReason adds\n// the failed disposition that may occur only on ProviderError attempt evidence.\nexport type FinishReason = \"stop\" | \"length\" | \"tool_calls\" | \"content_filter\" | null;\nexport type ProviderAttemptFinishReason = FinishReason | \"resource_interrupted\" | \"error\";\n\n// {§provider-failure-normalization} A per-token logprob. `logprob` is the backend's raw model\n// log-probability of the emitted token — the sampling-transform-invariant\n// confidence, chosen over Fireworks' post-mask `sampling_logprob` (the raw value is the honest\n// model belief and the correct distillation target). `top` carries the top-N\n// alternatives when top_logprobs was requested. The verbatim per-token record\n// (sampling_logprob, token_id, bytes, mask fields) survives on\n// ProviderResponse.rawBody — this structured view is the canonical signal only.\nexport interface TokenAlternative {\n readonly token: string;\n readonly logprob: number;\n}\nexport interface TokenLogprob {\n readonly token: string;\n readonly logprob: number;\n readonly top?: readonly TokenAlternative[];\n}\n\nexport interface ProviderAssistant<TFinish extends ProviderAttemptFinishReason = FinishReason> {\n readonly content: string;\n readonly reasoning: string | null;\n readonly finishReason: TFinish;\n readonly model: string;\n // Per-token logprobs, present only when PLURNK_PROVIDERS_TOP_LOGPROBS is set\n // AND the backend returned them. Absent otherwise — NEVER synthesized. Opt-in,\n // per-alias: a scraping alias enables it; serving turns carry nothing.\n readonly logprobs?: readonly TokenLogprob[];\n // Convenience: mean of logprobs[].logprob (natural log). Absent when logprobs is.\n readonly meanLogprob?: number;\n}\n\n// {§provider-interface}: body bytes after SDK serialization and owned\n// transforms. Origin deliberately excludes userinfo, path, query and fragment.\nexport interface ProviderRequestCapture {\n readonly method: string;\n readonly origin: string;\n readonly body: string;\n}\n\nexport interface ProviderResponse<TFinish extends ProviderAttemptFinishReason = FinishReason> {\n readonly assistant: ProviderAssistant<TFinish>;\n readonly assistantRaw: unknown;\n // Ordered physical request evidence, including automatic retries and pool\n // failover that preceded this response. {§provider-request-accounting}\n readonly accounting: readonly ProviderRequestAccounting[];\n readonly capacity: ProviderRequestCapacity;\n // Per-turn provider→client metadata bag: the backend's non-standard top-level\n // response fields passed through verbatim. Monetary values carry their own\n // amount and currency; the provider does not reinterpret them. The consumer\n // (service) merges this into its Turn metadata and\n // filters what reaches the client; it reads `meta`, never mines `assistantRaw`.\n // Absent when the backend reported no extra fields.\n readonly meta?: Record<string, unknown>;\n // The verbatim backend response body ({§provider-failure-normalization}) — the full wire JSON for\n // a non-streamed turn, or the reassembled equivalent for a streamed one.\n // `assistantRaw` is a normalized DIGEST (it drops choices[]); this is the\n // capture-everything record for the endpoint's fine-tune corpus. Present ONLY\n // when PLURNK_PROVIDERS_RAWBODY is on — off by default so serving turns never\n // carry it. Absent otherwise.\n readonly rawBody?: unknown;\n // Notices attached to the represented attempt. Successful\n // returns may relay them; interrupted attempt notices remain forensic.\n readonly notices?: readonly ProviderNotice[];\n}\n\nexport type ProviderAttempt = ProviderResponse<ProviderAttemptFinishReason>;\n\nexport interface ProviderGenerateArgs {\n readonly messages: ChatMessage[];\n readonly sessionId: string;\n readonly signal?: AbortSignal;\n readonly maxOutputTokens?: number;\n // The workspace this call serves: ordinary call context for an adapter that\n // fronts more than one workspace. It is never transported to a backend and\n // never model-facing.\n readonly workspaceId?: string;\n readonly sampling?: Record<string, unknown>;\n readonly observeRequest?: ProviderRequestObserver;\n readonly observeReasoning?: ProviderReasoningObserver;\n readonly callKind?: ProviderCallKind;\n readonly finalUserCachePrefix?: FinalUserCachePrefix;\n}\n\nexport interface Provider {\n // Optional package-authored folksonomy evaluated by the consumer immediately\n // before a provider emission attempt ({§extension-discovery}).\n attributions?(context: ExtensionAttributionContext): ExtensionAttribution;\n // `maxOutputTokens` may tighten the provider's configured total output\n // budget for this call. It includes visible output and hidden reasoning;\n // the adapter owns projection into each backend's native wire semantics.\n //\n // `sessionId` is the REQUIRED, opaque, stable identity of the consumer's work\n // stream (loop/run). Providers MAY key backend affinity on it — e.g.\n // llama-server slot pinning for KV-cache reuse — and MUST NOT interpret\n // its content. The consumer never sees or chooses backend resources\n // (slot integers, connections); the mechanism is the provider's.\n //\n // `sampling` is an optional bag of standard OpenAI-compat sampling params\n // (temperature, top_p, top_k, min_p, penalties, stop, seed, …) forwarded into\n // the request body UNDER the provider's managed fields — model/messages/\n // reasoning/max_tokens/slot always win, and transport/protocol keys (stream,\n // response_format, id_slot) are stripped, so it carries sampling intent\n // only ({§provider-request-authority}). A\n // proxy consumer fronting its own backends uses it to pass its caller's\n // sampling knobs through; a direct consumer typically leaves it unset.\n //\n // `callKind` is the caller's explicit output contract, never inferred from\n // the request shape. Generic callers may omit it; Core always supplies\n // `emission` or `bare`.\n generate(args: ProviderGenerateArgs): Promise<ProviderResponse>;\n // {§model-fact-resolution} — effective total context envelope in tokens,\n // including any stricter operator cap. `null` means unknown; under\n // llama-server parallelism the probed natural value is per slot.\n readonly contextWindow: number | null;\n readonly maxInputTokens: number | null;\n readonly maxOutputTokens: number | null;\n readonly outputBudget: number | null;\n // {§provider-capacity-admission}: the least response room any request keeps; never above outputBudget.\n readonly outputFloor: number | null;\n readonly reasoningBudget: number | null;\n // Exact durable policies this adapter can represent without coercion.\n readonly supportedEfforts: readonly Effort[];\n // {§provider-interface} — the native non-text parts the route's model accepts.\n readonly inputModalities: ReadonlySet<InputModality>;\n // {§provider-capacity-admission}: the reservation's line Core packs the room against, and the\n // physical input wall ({§provider-capacity-admission}) that ends a loop; null when the limits\n // cannot establish one.\n readonly inputCapacity: number | null;\n readonly inputWall: number | null;\n readonly model: string;\n readonly temperature?: number | null;\n readonly seed?: number;\n // Optional: the backend's self-reported served model id, from a\n // /v1/models-shaped probe (llama-server today; any such backend). For a local\n // alias, `model` is the alias but this is the real served name (the .gguf) the\n // tokenizer seam maps exactly. Read-only, best-effort, no extra probing —\n // absent when no probe ran. Consumers resolve `servedModel ?? model`.\n readonly servedModel?: string;\n // Optional resolved capability: true when this backend decodes\n // UNBOUNDED absent a caller cap — llama-server honors n_predict to the\n // context wall (observed in a 30,736-junk-token wall run), so a consumer\n // MUST bring an output envelope ({§provider-configuration}). Cloud backends that silently\n // clamp an over-ask (fireworks/xai, verified live) never set this; undefined\n // = no claim. Introspectable so a consumer can refuse AT BOOT a local alias\n // with no declared envelope, instead of dying mid-turn in partition math.\n readonly requiresOutputBudget?: boolean;\n // The adapter owns request-specific physical admission. A proven fit may\n // admit and an exact overflow may reject before I/O. Incomplete limits,\n // estimates, bounds that do not prove fit, and unavailable measurements\n // defer to the upstream provider as the capacity oracle.\n assessRequestCapacity(\n messages: readonly ChatMessage[],\n maxOutputTokens?: number,\n signal?: AbortSignal,\n ): Promise<ProviderRequestCapacity>;\n // Provider-owned preflight measurement of the complete chat request,\n // including provider/template framing when the adapter can know it.\n // Estimates are explicit and MUST NOT authorize hard context-envelope admission.\n countPromptTokens(messages: readonly ChatMessage[], signal?: AbortSignal): Promise<PromptTokenMeasurement>;\n // OPTIONAL capability: exact tokenization served by the backend's own vocab\n // (llama-server /tokenize) — token ids in the model's real vocabulary.\n // Present ONLY when the backend exposes such an endpoint (probe-gated);\n // `tokenize === undefined` means the backend can't. Exact-counting\n // consumers (the tokenizer seam) prefer this over any client-side data.\n tokenize?(text: string): Promise<number[]>;\n}\n\n// ProviderAlias lives in @plurnk/plurnk-aliases (the zero-dependency parser);\n// index.ts re-exports it so the \".\" surface is unchanged.\n\n// Per-alias instantiation overrides, threaded from the alias cascade into the\n// factory. `baseUrl` lets two aliases on the SAME provider name (openai, ollama)\n// target DIFFERENT endpoints — the only way to run N self-hosted boxes, since the\n// provider's own base-URL env var binds one URL per name. Absent → the provider\n// resolves its base from its env var as before.\nexport interface ProviderOptions {\n readonly baseUrl?: string;\n}\n\n// A discovered provider extension default-exports a provider factory. PLURNK owns\n// the adapter into Provider; the extension owns only its protocol binding.\nexport interface ProviderExtension extends ExtensionAttributionSource {\n model(model: string): ProviderModel;\n}\n"]}
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,6EAA6E;AAC7E,iCAAiC;AA2DjC,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IACpC,MAAM,CAAS;IACf,SAAS,CAAoB;IAEtC,YAAY,MAAc,EAAE,MAAc,EAAE,SAA4B,EAAE,MAAe;QACrF,yEAAyE;QACzE,qEAAqE;QACrE,+DAA+D;QAC/D,yDAAyD;QACzD,MAAM,YAAY,GAAG,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACzD,MAAM,KAAK,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,UAAU;YACzF,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,gHAAgH,CAAC,YAAY,IAAI,QAAQ,CAAC,CAAC,UAAU,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,sBAAsB,MAAM,qBAAqB,CAAC;QACnP,KAAK,CAAC,GAAG,MAAM,aAAa,MAAM,wCAAwC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC;QAC3G,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC/B,CAAC;CACJ;AAKD,MAAM,CAAC,MAAM,gBAAgB,GAA6B,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;AAW5G,8EAA8E;AAC9E,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,OAAqC,EAAU,EAAE,CAC7E,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ;IAC/B,CAAC,CAAC,OAAO,CAAC,OAAO;IACjB,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC","sourcesContent":["// Provider transport contract. Providers return raw wire-level output —\n// content unparsed (consumer parses via @plurnk/plurnk-contracts), reasoning\n// is the wire-reported CoT only.\n\nimport type { OpenAICompletionsCompat } from \"@earendil-works/pi-ai\";\nimport type { ProviderNotice } from \"./notices.ts\";\nimport type {\n ExtensionAttribution,\n ExtensionAttributionContext,\n ExtensionAttributionSource,\n} from \"@plurnk/plurnk-meta\";\nimport type {\n ProviderCost,\n ProviderRequestAccounting,\n ProviderRequestObserver,\n Effort,\n} from \"@plurnk/plurnk-contracts\";\n\nexport type ProviderModelApi =\n | \"openai-completions\"\n | \"openai-responses\"\n | \"anthropic-messages\"\n | \"google-generative-ai\"\n | \"bedrock-converse-stream\";\n\nexport interface ProviderModel {\n readonly id: string;\n readonly api: ProviderModelApi;\n readonly provider: string;\n readonly baseUrl: string;\n readonly name?: string;\n readonly reasoning?: boolean;\n readonly input?: readonly (\"text\" | \"image\")[];\n readonly cost?: {\n readonly input: number;\n readonly output: number;\n readonly cacheRead: number;\n readonly cacheWrite: number;\n };\n readonly contextWindow?: number;\n readonly maxTokens?: number;\n readonly headers?: Readonly<Record<string, string>>;\n readonly compat?: OpenAICompletionsCompat;\n readonly apiKey?: string;\n readonly env?: Readonly<Record<string, string | undefined>>;\n readonly includeTopK?: boolean;\n readonly xaiPreferResponses?: boolean;\n readonly onPayload?: (payload: unknown, model: ProviderModel) => unknown;\n}\n\nexport type {\n ProviderAccounting,\n ProviderCost,\n ProviderRequestAccounting,\n ProviderRequestIdentity,\n ProviderRequestObserver,\n ProviderRequestSettlement,\n ProviderUsage,\n Effort,\n} from \"@plurnk/plurnk-contracts\";\n\nexport class UnsupportedEffortError extends Error {\n readonly policy: Effort;\n readonly supported: readonly Effort[];\n\n constructor(source: string, policy: Effort, supported: readonly Effort[], remedy?: string) {\n // A graded-effort refusal names the operator's declaration lever (#472):\n // the catalog is authoritative per model, and where a provider's API\n // accepts more than its catalog entry lists, the remedy is the\n // operator's, never a vendored fact in shipped defaults.\n const providerName = /^provider:(.+)$/.exec(source)?.[1];\n const lever = remedy !== undefined ? ` ${remedy}` : policy === \"off\" || policy === \"adaptive\"\n ? \"\"\n : ` If the provider's API documents this effort beyond its catalog entry, declare it: PLURNK_PROVIDERS_PROVIDER_${(providerName ?? \"<NAME>\").replaceAll(/[^a-zA-Z0-9<>]/g, \"_\").toUpperCase()}_REASONING_EFFORTS=${policy} (comma-separated).`;\n super(`${source}: effort '${policy}' is unsupported; supported efforts: ${supported.join(\", \")}.${lever}`);\n this.name = \"UnsupportedEffortError\";\n this.policy = policy;\n this.supported = supported;\n }\n}\n\n// {§provider-interface} — the native non-text inputs a route's model accepts, in the\n// catalog's vocabulary (Models.dev `modalities.input` minus `text`).\nexport type InputModality = \"image\" | \"pdf\" | \"audio\" | \"video\";\nexport const INPUT_MODALITIES: readonly InputModality[] = Object.freeze([\"image\", \"pdf\", \"audio\", \"video\"]);\n// A user message may carry parts: text beside native files for a model that declares\n// the matching modality. The media type distinguishes images, PDFs, and future kinds;\n// system and assistant messages stay text.\nexport type ChatContentPart =\n | { readonly type: \"text\"; readonly text: string }\n | { readonly type: \"file\"; readonly data: Uint8Array; readonly mediaType: string };\nexport interface ChatMessage {\n role: \"system\" | \"user\" | \"assistant\";\n content: string | readonly ChatContentPart[];\n}\n// The text of a message, for counting and for transports that take only text.\nexport const chatMessageText = (message: Pick<ChatMessage, \"content\">): string =>\n typeof message.content === \"string\"\n ? message.content\n : message.content.map((part) => part.type === \"text\" ? part.text : \"\").join(\"\");\n\n// {§provider-interface} The caller-owned semantic contract for one logical model call. Providers do\n// not infer this from messages: an emission expects PLURNK\n// output, while a bare call expects unconstrained response text.\nexport type ProviderCallKind = \"emission\" | \"bare\";\n\n// {§provider-sdk-boundary} Optional caller-supplied durable prefix boundary inside a user\n// message (`chars` when `content` is a string, `parts` when `content` is `ChatContentPart[]`),\n// separating prior-turn durable log blocks from a trailing replayed-emission announcement row or\n// trailing per-turn volatile status blocks.\nexport type UserCachePrefix =\n | { readonly kind: \"chars\"; readonly length: number }\n | { readonly kind: \"parts\"; readonly count: number };\n\n// Preflight evidence for the complete provider request. An empirical estimate\n// is useful telemetry but cannot authorize hard context-envelope admission.\nexport type PromptTokenMeasurement =\n | {\n readonly kind: \"exact\" | \"upper_bound\";\n readonly tokens: number;\n readonly source: string;\n }\n | {\n readonly kind: \"estimate\";\n readonly tokens: number;\n readonly source: string;\n readonly detail: string;\n }\n | {\n readonly kind: \"unavailable\";\n readonly source: string;\n readonly detail: string;\n };\n\nexport type ProviderRequestCapacityDecision = \"admit\" | \"defer\" | \"reject\";\n\n// Complete pre-I/O evidence for one logical request. `defer` is intentional:\n// an estimate or incomplete limit set cannot safely veto a request, so the\n// upstream provider remains the capacity oracle.\nexport interface ProviderRequestCapacity {\n readonly decision: ProviderRequestCapacityDecision;\n readonly contextWindow: number | null;\n readonly maxInputTokens: number | null;\n readonly maxOutputTokens: number | null;\n readonly outputBudget: number | null;\n // {§provider-capacity-admission}: the least response room this request keeps; never above outputBudget.\n readonly outputFloor: number | null;\n readonly reasoningBudget: number | null;\n // {§provider-capacity-admission}: the curation reservation's line (maxInputTokens and\n // window − outputBudget) and the physical input wall (maxInputTokens and window − outputFloor)\n // the decision was taken against.\n readonly inputCapacity: number | null;\n readonly inputWall: number | null;\n // {§provider-capacity-admission}: the response allowance actually granted this\n // request — the window's remainder, between the floor and the model's limit.\n readonly responseMax: number | null;\n readonly prompt: PromptTokenMeasurement;\n}\n\nexport type ChargedCost = Extract<ProviderCost, { kind: \"charged\" }>;\n\n// Evidence exposed by the transport to the provider adapter that owns its\n// vendor protocol. Core and downstream consumers receive only the normalized\n// charge, never a requirement to understand provider metadata fields.\nexport interface ProviderChargeEvidence {\n readonly providerMetadata?: unknown;\n // A protocol-owned direct monetary field. It remains unknown until the\n // selected adapter explicitly validates and normalizes it.\n readonly charge?: unknown;\n // Provider-owned raw usage projection retained independently of optional\n // full-body capture. Accounting fields cannot disappear merely because\n // forensic raw-body capture is disabled.\n readonly usage?: unknown;\n readonly response: {\n readonly id?: string;\n readonly headers?: Readonly<Record<string, string>>;\n };\n}\n\nexport type ProviderCostNormalizer = (\n evidence: ProviderChargeEvidence,\n) => ProviderCost | undefined;\n\n// {§provider-interface} Transient readable-reasoning observation. The completed ProviderResponse is\n// still the sole authoritative value; this callback exposes exact, ordered,\n// nonempty deltas early enough for an attached client to render them live.\nexport type ProviderReasoningObserver = (delta: string) => void;\n\n// A successful exchange's closed finish set. ProviderAttemptFinishReason adds\n// the failed disposition that may occur only on ProviderError attempt evidence.\nexport type FinishReason = \"stop\" | \"length\" | \"tool_calls\" | \"content_filter\" | null;\nexport type ProviderAttemptFinishReason = FinishReason | \"resource_interrupted\" | \"error\";\n\n// {§provider-failure-normalization} A per-token logprob. `logprob` is the backend's raw model\n// log-probability of the emitted token — the sampling-transform-invariant\n// confidence, chosen over Fireworks' post-mask `sampling_logprob` (the raw value is the honest\n// model belief and the correct distillation target). `top` carries the top-N\n// alternatives when top_logprobs was requested. The verbatim per-token record\n// (sampling_logprob, token_id, bytes, mask fields) survives on\n// ProviderResponse.rawBody — this structured view is the canonical signal only.\nexport interface TokenAlternative {\n readonly token: string;\n readonly logprob: number;\n}\nexport interface TokenLogprob {\n readonly token: string;\n readonly logprob: number;\n readonly top?: readonly TokenAlternative[];\n}\n\nexport interface ProviderAssistant<TFinish extends ProviderAttemptFinishReason = FinishReason> {\n readonly content: string;\n readonly reasoning: string | null;\n readonly finishReason: TFinish;\n readonly model: string;\n // Per-token logprobs, present only when PLURNK_PROVIDERS_TOP_LOGPROBS is set\n // AND the backend returned them. Absent otherwise — NEVER synthesized. Opt-in,\n // per-alias: a scraping alias enables it; serving turns carry nothing.\n readonly logprobs?: readonly TokenLogprob[];\n // Convenience: mean of logprobs[].logprob (natural log). Absent when logprobs is.\n readonly meanLogprob?: number;\n}\n\n// {§provider-interface}: body bytes after SDK serialization and owned\n// transforms. Origin deliberately excludes userinfo, path, query and fragment.\nexport interface ProviderRequestCapture {\n readonly method: string;\n readonly origin: string;\n readonly body: string;\n}\n\nexport interface ProviderResponse<TFinish extends ProviderAttemptFinishReason = FinishReason> {\n readonly assistant: ProviderAssistant<TFinish>;\n readonly assistantRaw: unknown;\n // Ordered physical request evidence, including automatic retries and pool\n // failover that preceded this response. {§provider-request-accounting}\n readonly accounting: readonly ProviderRequestAccounting[];\n readonly capacity: ProviderRequestCapacity;\n // Per-turn provider→client metadata bag: the backend's non-standard top-level\n // response fields passed through verbatim. Monetary values carry their own\n // amount and currency; the provider does not reinterpret them. The consumer\n // (service) merges this into its Turn metadata and\n // filters what reaches the client; it reads `meta`, never mines `assistantRaw`.\n // Absent when the backend reported no extra fields.\n readonly meta?: Record<string, unknown>;\n // The verbatim backend response body ({§provider-failure-normalization}) — the full wire JSON for\n // a non-streamed turn, or the reassembled equivalent for a streamed one.\n // `assistantRaw` is a normalized DIGEST (it drops choices[]); this is the\n // capture-everything record for the endpoint's fine-tune corpus. Present ONLY\n // when PLURNK_PROVIDERS_RAWBODY is on — off by default so serving turns never\n // carry it. Absent otherwise.\n readonly rawBody?: unknown;\n // Notices attached to the represented attempt. Successful\n // returns may relay them; interrupted attempt notices remain forensic.\n readonly notices?: readonly ProviderNotice[];\n}\n\nexport type ProviderAttempt = ProviderResponse<ProviderAttemptFinishReason>;\n\nexport interface ProviderGenerateArgs {\n readonly messages: ChatMessage[];\n readonly sessionId: string;\n readonly signal?: AbortSignal;\n readonly maxOutputTokens?: number;\n // The workspace this call serves: ordinary call context for an adapter that\n // fronts more than one workspace. It is never transported to a backend and\n // never model-facing.\n readonly workspaceId?: string;\n readonly sampling?: Record<string, unknown>;\n readonly observeRequest?: ProviderRequestObserver;\n readonly observeReasoning?: ProviderReasoningObserver;\n readonly callKind?: ProviderCallKind;\n readonly userCachePrefixes?: readonly (UserCachePrefix | undefined)[];\n}\n\nexport interface Provider {\n // Optional package-authored folksonomy evaluated by the consumer immediately\n // before a provider emission attempt ({§extension-discovery}).\n attributions?(context: ExtensionAttributionContext): ExtensionAttribution;\n // `maxOutputTokens` may tighten the provider's configured total output\n // budget for this call. It includes visible output and hidden reasoning;\n // the adapter owns projection into each backend's native wire semantics.\n //\n // `sessionId` is the REQUIRED, opaque, stable identity of the consumer's work\n // stream (loop/run). Providers MAY key backend affinity on it — e.g.\n // llama-server slot pinning for KV-cache reuse — and MUST NOT interpret\n // its content. The consumer never sees or chooses backend resources\n // (slot integers, connections); the mechanism is the provider's.\n //\n // `sampling` is an optional bag of standard OpenAI-compat sampling params\n // (temperature, top_p, top_k, min_p, penalties, stop, seed, …) forwarded into\n // the request body UNDER the provider's managed fields — model/messages/\n // reasoning/max_tokens/slot always win, and transport/protocol keys (stream,\n // response_format, id_slot) are stripped, so it carries sampling intent\n // only ({§provider-request-authority}). A\n // proxy consumer fronting its own backends uses it to pass its caller's\n // sampling knobs through; a direct consumer typically leaves it unset.\n //\n // `callKind` is the caller's explicit output contract, never inferred from\n // the request shape. Generic callers may omit it; Core always supplies\n // `emission` or `bare`.\n generate(args: ProviderGenerateArgs): Promise<ProviderResponse>;\n // {§model-fact-resolution} — effective total context envelope in tokens,\n // including any stricter operator cap. `null` means unknown; under\n // llama-server parallelism the probed natural value is per slot.\n readonly contextWindow: number | null;\n readonly maxInputTokens: number | null;\n readonly maxOutputTokens: number | null;\n readonly outputBudget: number | null;\n // {§provider-capacity-admission}: the least response room any request keeps; never above outputBudget.\n readonly outputFloor: number | null;\n readonly reasoningBudget: number | null;\n // Exact durable policies this adapter can represent without coercion.\n readonly supportedEfforts: readonly Effort[];\n // {§provider-interface} — the native non-text parts the route's model accepts.\n readonly inputModalities: ReadonlySet<InputModality>;\n // {§provider-capacity-admission}: the reservation's line Core packs the room against, and the\n // physical input wall ({§provider-capacity-admission}) that ends a loop; null when the limits\n // cannot establish one.\n readonly inputCapacity: number | null;\n readonly inputWall: number | null;\n readonly model: string;\n readonly temperature?: number | null;\n readonly seed?: number;\n // Optional: the backend's self-reported served model id, from a\n // /v1/models-shaped probe (llama-server today; any such backend). For a local\n // alias, `model` is the alias but this is the real served name (the .gguf) the\n // tokenizer seam maps exactly. Read-only, best-effort, no extra probing —\n // absent when no probe ran. Consumers resolve `servedModel ?? model`.\n readonly servedModel?: string;\n // Optional resolved capability: true when this backend decodes\n // UNBOUNDED absent a caller cap — llama-server honors n_predict to the\n // context wall (observed in a 30,736-junk-token wall run), so a consumer\n // MUST bring an output envelope ({§provider-configuration}). Cloud backends that silently\n // clamp an over-ask (fireworks/xai, verified live) never set this; undefined\n // = no claim. Introspectable so a consumer can refuse AT BOOT a local alias\n // with no declared envelope, instead of dying mid-turn in partition math.\n readonly requiresOutputBudget?: boolean;\n // The adapter owns request-specific physical admission. A proven fit may\n // admit and an exact overflow may reject before I/O. Incomplete limits,\n // estimates, bounds that do not prove fit, and unavailable measurements\n // defer to the upstream provider as the capacity oracle.\n assessRequestCapacity(\n messages: readonly ChatMessage[],\n maxOutputTokens?: number,\n signal?: AbortSignal,\n ): Promise<ProviderRequestCapacity>;\n // Provider-owned preflight measurement of the complete chat request,\n // including provider/template framing when the adapter can know it.\n // Estimates are explicit and MUST NOT authorize hard context-envelope admission.\n countPromptTokens(messages: readonly ChatMessage[], signal?: AbortSignal): Promise<PromptTokenMeasurement>;\n // OPTIONAL capability: exact tokenization served by the backend's own vocab\n // (llama-server /tokenize) — token ids in the model's real vocabulary.\n // Present ONLY when the backend exposes such an endpoint (probe-gated);\n // `tokenize === undefined` means the backend can't. Exact-counting\n // consumers (the tokenizer seam) prefer this over any client-side data.\n tokenize?(text: string): Promise<number[]>;\n}\n\n// ProviderAlias lives in @plurnk/plurnk-aliases (the zero-dependency parser);\n// index.ts re-exports it so the \".\" surface is unchanged.\n\n// Per-alias instantiation overrides, threaded from the alias cascade into the\n// factory. `baseUrl` lets two aliases on the SAME provider name (openai, ollama)\n// target DIFFERENT endpoints — the only way to run N self-hosted boxes, since the\n// provider's own base-URL env var binds one URL per name. Absent → the provider\n// resolves its base from its env var as before.\nexport interface ProviderOptions {\n readonly baseUrl?: string;\n}\n\n// A discovered provider extension default-exports a provider factory. PLURNK owns\n// the adapter into Provider; the extension owns only its protocol binding.\nexport interface ProviderExtension extends ExtensionAttributionSource {\n model(model: string): ProviderModel;\n}\n"]}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@plurnk/plurnk-providers",
3
- "version": "6.1.1",
3
+ "version": "6.2.0",
4
4
  "description": "PLURNK's stable model-provider contract and provider SDK adapter.",
5
5
  "keywords": [
6
6
  "plurnk",
@@ -68,12 +68,12 @@
68
68
  "dependencies": {
69
69
  "@earendil-works/pi-ai": "1.5.2",
70
70
  "@plurnk/plurnk-aliases": "^2.0.0",
71
- "@plurnk/plurnk-contracts": "^7.4.0",
71
+ "@plurnk/plurnk-contracts": "^7.5.0",
72
72
  "@plurnk/plurnk-meta": "^2.2.0",
73
73
  "@plurnk/plurnk-models": "^4.0.0"
74
74
  },
75
75
  "devDependencies": {
76
76
  "esbuild": "^0.28.2"
77
77
  },
78
- "gitHead": "49f92d9351021ae0729d69e72ab9b1b95e3a974b"
78
+ "gitHead": "9206fac0bc773bc1bdb4cc0a541f8bd58f45f87b"
79
79
  }