@plurnk/plurnk-providers 1.3.4 → 1.3.6

package/.env.defaults

@@ -1,6 +1,6 @@
-# REFERENCE - @plurnk/plurnk-providers' shipped .env.defaults: the operative floor for the
-# PLURNK_PROVIDERS_* knobs AND the standard providers' endpoints + alias config (ecosystem
-# standard, providers#44: every package owns what it reads; the file IS the documentation).
+# REFERENCE - @plurnk/plurnk-providers' shipped .env.defaults: the operative floor for
+# PLURNK_PROVIDERS_* knobs and provider declarations (providers#44: every package owns
+# what it reads; the file IS the configuration reference).
 # The daemon assembles every installed member's file into one floor (set-if-unset under the
 # operator's env) - do NOT edit this file; put YOUR config in ~/.plurnk/.env or ./.env. A key
 # claimed by two packages crashes boot naming both.
@@ -9,10 +9,9 @@
 # the bare name (suffix case-folds; SPEC §4). Set lines are the floor; commented lines are values
 # whose UNSET state is meaningful (derive/auto/off, or a required secret) - uncomment to pin.
 #
-# Base URLs are SHIPPED DEFAULTS - the canonical vendor endpoint lives HERE (overridable in your
-# .env, or per-alias via PLURNK_BASEURL_<alias>), so the happy path needs ZERO endpoint config.
-# The ONLY required per-provider input is the API KEY: a secret with no default, set in your own
-# .env; an unset key for a provider you actually use fails hard at construction naming the var.
+# Models.dev supplies cataloged providers' SDK package, endpoint, credential names,
+# model metadata, and prices. Operator declarations below cover only facts absent
+# from or deliberately overridden over that catalog. Secret VALUES never belong here.
 
 # --- Side-channel reasoning (SPEC §4, #32/#33/#399) ---
 # ACTIVATION and BUDGET are separate so a numeric can never silently flip wire flags.
@@ -32,16 +31,19 @@ PLURNK_PROVIDERS_REASONING=adaptive
 # the floor the provider manages wherever a grammar rides (greedy-under-mask loops without it).
 PLURNK_PROVIDERS_TEMPERATURE=0.2
 PLURNK_PROVIDERS_REPEAT_PENALTY=1.15
-# FREQUENCY_PENALTY (#426): the anti-degeneration guard on the CLOUD path. repeat_penalty is a
-# llama.cpp/vLLM MULTIPLIER the plain cloud path (grammarStyle "none") can't use; frequency_penalty
-# is OpenAI-standard, so every OpenAI-compat backend accepts it (verified live: together, deepinfra,
-# fireworks). Without it a cloud alias ran the sampler bare and looped to the token cap. 0 = off.
-# NOTE: 0.4 is a STARTING value (acceptance-verified, not yet effectiveness-benched) - raise it if a
-# firefast/deepseek re-bench still degenerates.
-PLURNK_PROVIDERS_FREQUENCY_PENALTY=0.4
+# FREQUENCY_PENALTY (#426): optional cloud anti-degeneration tuning. API acceptance
+# permits the field to ride but does not establish its semantic effect, and provider
+# implementations differ. The portable floor is off; enable per alias only from
+# provider documentation or a controlled behavioral experiment.
+PLURNK_PROVIDERS_FREQUENCY_PENALTY=0
+# PLURNK_PROVIDERS_FREQUENCY_PENALTY_myendpoint=0.4
 # Fixed provider service tier. Fireworks accepts auto|default|flex|priority;
 # normally set per alias so a paid routing choice is explicit.
 # PLURNK_PROVIDERS_SERVICE_TIER_myfireworks=priority
+# Compatible endpoints verified to accept the OpenAI prompt_cache_key use the
+# stable worker id for replica-local prefix affinity. Official native SDKs own
+# their cache mechanisms and do not receive this compatible extension.
+PLURNK_PROVIDERS_PROMPT_CACHE_KEY=1
 # #567: DRY loop-breaker - llama.cpp-only (grammarStyle "none" paths skip it). MULTIPLIER=0
 # disables DRY at the general floor: the #567 sweep showed L=2 is WORSE than DRY-off on both
 # runaways AND corruption; L=32 is the measured plurnk-safe threshold (0 corruption fails,
@@ -64,7 +66,6 @@ PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT=0
 # Transient-failure retries: 0 = surface the first failure; N = retries on 429/5xx/timeout
 # with exponential backoff (Retry-After wins). RETRY_DELAY is the backoff base (ms).
 PLURNK_PROVIDERS_RETRY_ATTEMPTS=3
-PLURNK_PROVIDERS_RETRY_DELAY=2000
 
 # --- Endpoint probe (#34) ---
 # GET /v1/models at construction (context window + llama-server fingerprint). One failure
@@ -101,6 +102,27 @@ PLURNK_PROVIDERS_PROBE_DELAY=250
 # PLURNK_PROVIDERS_TOP_LOGPROBS_myscraper=3
 # PLURNK_PROVIDERS_RAWBODY_myscraper=1
 
+# --- Provider declarations (SPEC §5) ---
+# Models.dev supplies the AI SDK package, credential names, endpoint, and model
+# metadata for cataloged providers. These knobs override those facts or declare
+# an endpoint Models.dev does not list. NAME is the alias provider segment.
+# PLURNK_PROVIDERS_PROVIDER_<NAME>_NPM=<supported AI SDK package>
+# PLURNK_PROVIDERS_PROVIDER_<NAME>_BASE_URL=<endpoint>
+# PLURNK_PROVIDERS_PROVIDER_<NAME>_API_KEY_ENV=<comma-separated env names>
+PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_API_KEY_ENV=CLOUDFLARE_API_TOKEN,CLOUDFLARE_API_KEY
+# Fireworks reasoners default on when reasoning_effort is omitted; explicit
+# "none" is its off switch. This is a declared wire exception, not a registry.
+PLURNK_PROVIDERS_PROVIDER_FIREWORKS_REASONING_STYLE=effort_explicit
+PLURNK_PROVIDERS_PROVIDER_VOLCENGINE_NPM=@ai-sdk/openai-compatible
+PLURNK_PROVIDERS_PROVIDER_VOLCENGINE_BASE_URL=https://ark.ap-southeast.bytepluses.com/api/v3
+PLURNK_PROVIDERS_PROVIDER_VOLCENGINE_API_KEY_ENV=ARK_API_KEY
+PLURNK_PROVIDERS_PROVIDER_BAICHUAN_NPM=@ai-sdk/openai-compatible
+PLURNK_PROVIDERS_PROVIDER_BAICHUAN_BASE_URL=https://api.baichuan-ai.com/v1
+PLURNK_PROVIDERS_PROVIDER_BAICHUAN_API_KEY_ENV=BAICHUAN_API_KEY
+PLURNK_PROVIDERS_PROVIDER_QIANFAN_NPM=@ai-sdk/openai-compatible
+PLURNK_PROVIDERS_PROVIDER_QIANFAN_BASE_URL=https://qianfan.baidubce.com/v2
+PLURNK_PROVIDERS_PROVIDER_QIANFAN_API_KEY_ENV=QIANFAN_API_KEY
+
 # --- Alias cascade (SPEC §5) - declare aliases, then pick the active one ---
 # First path segment is the provider name; the rest is the provider-native model id (may
 # contain "/"). Operator-specific, no default - the examples are commented.
@@ -117,44 +139,11 @@ PLURNK_PROVIDERS_PROBE_DELAY=250
 # PLURNK_MODEL_NOOK=ollama/qwen2.5-coder
 # PLURNK_BASEURL_NOOK=http://nook:11434
 
-# --- Standard provider endpoints (frozen table) ---
-# Base URLs ship at their canonical vendor default - zero endpoint config for the happy path.
-# Override in your .env (proxy/self-host/regional twin), or per-alias with PLURNK_BASEURL_<alias>
-# (which wins over these). Each provider ALSO needs its API KEY - a required secret with no
-# default, set in ~/.plurnk/.env; the key var mirrors the *_BASE_URL prefix (FIREWORKS_API_KEY,
-# ...) except where noted. An unset key fails hard at construction naming the var.
-
-# Generic OpenAI-compat - OpenAI proper by default; for a local llama-server/vLLM, override the
-# endpoint per-alias (PLURNK_BASEURL_<alias>). OPENAI_API_BASE is a legacy URL alias.
+# The compatible `openai` and first-party `plurnk` adapters are intentionally
+# local contracts rather than catalog declarations. OpenAI defaults to its
+# canonical endpoint; override it per alias for llama-server or vLLM.
 OPENAI_BASE_URL=https://api.openai.com/v1
-GROQ_BASE_URL=https://api.groq.com/openai/v1
-DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
-MISTRAL_BASE_URL=https://api.mistral.ai/v1
-TOGETHER_BASE_URL=https://api.together.xyz/v1
-FIREWORKS_BASE_URL=https://api.fireworks.ai/inference/v1
-DEEPINFRA_BASE_URL=https://api.deepinfra.com/v1/openai   # key aliases: DEEPINFRA_API_TOKEN, DEEPINFRA_TOKEN
-
-# Chinese cloud hosts - base ships INTERNATIONAL; mainland operators repoint *_BASE_URL at the `.cn` twin.
-MOONSHOT_BASE_URL=https://api.moonshot.ai/v1
-DASHSCOPE_BASE_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1   # Alibaba Qwen
-ZHIPU_BASE_URL=https://api.z.ai/api/paas/v4   # Zhipu GLM; key ZHIPUAI_API_KEY (alias ZAI_API_KEY)
-ARK_BASE_URL=https://ark.ap-southeast.bytepluses.com/api/v3   # ByteDance Doubao (BytePlus ModelArk)
-HUNYUAN_BASE_URL=https://api.hunyuan.cloud.tencent.com/v1   # Tencent Hunyuan
-MINIMAX_BASE_URL=https://api.minimax.io/v1
-STEPFUN_BASE_URL=https://api.stepfun.com/v1   # StepFun; key STEP_API_KEY
-BAICHUAN_BASE_URL=https://api.baichuan-ai.com/v1
-QIANFAN_BASE_URL=https://qianfan.baidubce.com/v2   # Baidu ERNIE (Qianfan v2)
-SILICONFLOW_BASE_URL=https://api.siliconflow.com/v1
-MODELSCOPE_BASE_URL=https://api-inference.modelscope.cn/v1   # key alias: MODELSCOPE_TOKEN
-
-# First-party Claude (Anthropic's OpenAI-compat endpoint).
-ANTHROPIC_BASE_URL=https://api.anthropic.com/v1
-
-# AWS Bedrock (OpenAI-compat path /openai/v1) - base is REGION-templated: leave unset to derive
-# from AWS_REGION / AWS_DEFAULT_REGION, or pin explicitly. No static default. Key AWS_BEARER_TOKEN_BEDROCK.
-# BEDROCK_BASE_URL=https://bedrock-runtime.us-east-1.amazonaws.com/openai/v1
-
-# plurnk hosted model - PLURNK_API_KEY is an OPTIONAL bearer (sent only when set).
+# PLURNK_API_KEY is an optional bearer; the endpoint is eventually keyless.
 PLURNK_BASE_URL=https://plurnk.ai/v1
 # PLURNK_BASE_URL=http://plurnksnr2kihuukt6v22ko72r34dxeatbsfhgow3hvnlw6btanxphad.onion/v1   # Tor
 

package/README.md

@@ -1,35 +1,48 @@
 # @plurnk/plurnk-providers
 
-Provider contract and shared transports for PLURNK model backends.
+PLURNK's stable model-provider contract and its adapter to the
+[AI SDK](https://ai-sdk.dev/).
 
-The package includes:
+Ordinary provider behavior is intentionally not reimplemented here:
 
-- provider interfaces and normalized responses;
-- OpenAI-compatible streaming transport;
-- standard provider configuration;
-- alias resolution and provider discovery;
-- usage, cost, reasoning, grammar, and telemetry normalization.
+- Models.dev supplies provider package, endpoint, credential, context-window,
+  output-limit, and pricing metadata at build time.
+- Official AI SDK providers own vendor request and response protocols.
+- PLURNK owns aliases, generation envelopes, normalized usage and errors,
+  evidence capture, first-party metadata, and local endpoint capabilities.
 
-See `SPEC.md` for the complete API and `.env.defaults` for configuration.
+See `SPEC.md` for the contract and `.env.defaults` for every operational knob.
 
-## Standard providers
+## Configure a model
 
-Backends compatible with the shared transport are configured by the standard
-provider table and do not require a separate package. An alias selects a
-provider and model:
+Declare an alias, then select it:
 
 ```dotenv
-PLURNK_MODEL_fast=openai/gpt-4.1-mini
+PLURNK_MODEL_fast=openai/gpt-5-mini
 PLURNK_MODEL=fast
 OPENAI_API_KEY=...
 ```
 
-Provider-specific packages are appropriate when a backend requires a distinct
-protocol, discovery step, authentication flow, or response normalization.
+Cataloged providers need no endpoint declaration. To add an
+OpenAI-compatible provider that Models.dev does not describe:
+
+```dotenv
+PLURNK_PROVIDERS_PROVIDER_ACME_NPM=@ai-sdk/openai-compatible
+PLURNK_PROVIDERS_PROVIDER_ACME_BASE_URL=https://api.acme.example/v1
+PLURNK_PROVIDERS_PROVIDER_ACME_API_KEY_ENV=ACME_API_KEY
+PLURNK_MODEL_acme=acme/model-id
+```
+
+Provider declarations are configuration, not secrets. Secret values remain in
+the operator environment.
 
 ## Provider plugins
 
-A provider plugin may use any npm scope. Declare its identity:
+Most integrations should use an MCP server, executor, scheme, or a provider
+declaration. A provider plugin is only needed for a protocol binding unavailable
+through the catalog and installed SDK packages.
+
+It may use any npm scope. Its package manifest declares the PLURNK name:
 
 ```json
 {
@@ -38,51 +51,29 @@ A provider plugin may use any npm scope. Declare its identity:
     "name": "acme"
   },
   "peerDependencies": {
-    "@plurnk/plurnk-providers": "^1.2.0"
+    "@plurnk/plurnk-providers": "^1.2.0",
+    "ai": "^6.0.0"
   }
 }
 ```
 
-Default-export a factory compatible with `ProviderFactory`. The factory receives
-the environment, model name, and optional per-alias base URL. It returns a
-`Provider` synchronously or asynchronously.
-
-Packages using an OpenAI-compatible API should construct
-`OpenAICompatProvider`; other protocols implement `Provider` directly.
-
-The runtime-neutral `@plurnk/plurnk-providers/openai` entrypoint exports the
-OpenAI-compatible provider and its Web API transport types without importing
-package discovery, environment loading, or the provider registry. A consumer
-with its own request facility can inject a fetch-compatible implementation per
-instance:
-
-```ts
-import { OpenAICompatProvider } from "@plurnk/plurnk-providers/openai";
-
-const provider = new OpenAICompatProvider({
-  ...config,
-  fetch: providerFetch,
-});
-```
-
-The injected function receives the same URL, headers, body, and `AbortSignal`
-as the default `globalThis.fetch`. It owns only execution of that request;
-request shaping, response parsing, retries, usage, reasoning, raw capture, and
-telemetry remain provider behavior. Vendor binding adapters and their
-configuration belong to the consuming integration.
+The default export is an AI SDK provider with
+`languageModel(modelId)`. PLURNK adapts that language model into its own
+contract, so plugins do not reproduce retries, usage normalization, envelopes,
+or telemetry.
 
-Discovery scans installed npm packages for `plurnk.kind === "provider"`.
-Duplicate provider names are errors. `PLURNK_PLUGINS_TRUSTED_ONLY` can restrict
-third-party discovery.
+Discovery is scope-agnostic and rejects duplicate names.
+`PLURNK_PLUGINS_TRUSTED_ONLY` restricts third-party discovery.
 
-## Version compatibility
+## Local endpoints
 
-Provider plugins declare the compatible provider-framework range with normal
-peer dependency semantics. `plurnk.builtAgainst` records the exact framework
-version used to test the published artifact. Compatible framework patches do
-not require republishing an unchanged plugin.
+`openai` and `ollama` retain small in-package adapters because local operation
+requires runtime facts no static catalog owns: served model, context window,
+llama-server capabilities, slots, EOS token, and exact tokenization.
 
-Do not use npm force flags to install an incompatible peer graph.
+The `plurnk` provider retains the compatible transport because it carries
+first-party attribution and loop metadata and leaves model tuning to the
+endpoint.
 
 ## Development