@plurnk/plurnk-providers 1.3.12 → 1.5.0

package/.env.defaults

@@ -1,6 +1,6 @@
 # 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).
+# PLURNK_PROVIDERS_* knobs and provider declarations ({§operator-config-env-defaults});
+# every package owns what it reads, and this 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.
@@ -10,23 +10,31 @@
 # whose UNSET state is meaningful (derive/auto/off, or a required secret) - uncomment to pin.
 #
 # 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.
+# and model facts. {§model-fact-resolution} defines precedence per fact; there is
+# no live price fetch. 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.
 # off | adaptive | on. The provider maps intent to each backend's native mechanism
-# (reasoning_effort, enable_thinking, think, ...). Default ADAPTIVE (owner ruling,
-# #399): reasoning ACTIVE on a fresh install, each backend's own adaptive depth,
+# (reasoning_effort, enable_thinking, think, ...). Default ADAPTIVE (#399):
+# reasoning ACTIVE on a fresh install, each backend's own adaptive depth,
 # no shipped magnitude - a reasoning model that ships un-reasoning blind-edits and
-# declares done (svc#396 A/B: 25 EXECs -> 0, build broken, confident SEND[200]).
+# declares done.
 PLURNK_PROVIDERS_REASONING=adaptive
-# Positive int, REQUIRED iff REASONING=on - the magnitude for tier/budget mapping. On
-# llama.cpp the ENFORCEMENT is the box's --reasoning-budget LAUNCH flag (per-request
-# numerics are ignored): env budget and launch flag are the same number, changed together.
+# Positive int, REQUIRED iff REASONING=on - the magnitude for tier/budget mapping.
+# On llama-server it is a request-scoped reasoning allowance and may tighten, but
+# cannot exceed, the resolved PLURNK_PROVIDERS_REASONING_RESERVE.
 # PLURNK_PROVIDERS_REASONING_BUDGET=4096
 
-# --- Decode tuning (measured canonical values; bench/TUNING-EPIC.md F1/F6; #9/#30) ---
+# Response-content interpretation ({§provider-tagged-reasoning}) is independent
+# from request-side reasoning activation. The portable floor trusts only
+# structured provider/SDK reasoning fields and leaves visible content verbatim.
+# Set think-tags only on an alias whose exact model/endpoint contract emits one
+# leading <think> envelope; it is never inferred from generic reasoning capability.
+PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE=verbatim
+# PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE_cfds1=think-tags
+
+# --- Decode tuning (measured canonical values; #9/#30) ---
 # TEMPERATURE is the default for EVERY request (under caller sampling); REPEAT_PENALTY is
 # the floor the provider manages wherever a grammar rides (greedy-under-mask loops without it).
 PLURNK_PROVIDERS_TEMPERATURE=0.2
@@ -44,28 +52,32 @@ PLURNK_PROVIDERS_FREQUENCY_PENALTY=0
 # 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,
-# ~6% runaways vs 19% off). Enable per-alias: DRY_MULTIPLIER_<alias>=0.8, ALLOWED_LENGTH_<alias>=32.
+# #567: DRY is a llama.cpp-only repeated-sequence penalty. It can reduce
+# degenerate loops, but it can also corrupt exact source, identifiers, quoted
+# evidence, and other repetition required by PLURNK operations. The portable
+# server-wide default is off. A nonzero alias override is an explicit fidelity
+# tradeoff; DRY_BASE_<alias> and DRY_ALLOWED_LENGTH_<alias> tune that opt-in.
 PLURNK_PROVIDERS_DRY_MULTIPLIER=0
-PLURNK_PROVIDERS_DRY_BASE=1.75
-PLURNK_PROVIDERS_DRY_ALLOWED_LENGTH=32
-# REPEAT_LAST_N widens the older repeat_penalty window past the box's 64; optional (DRY's
-# whole-context window makes it secondary). Set per-alias if a model wants it.
+# PLURNK_PROVIDERS_DRY_BASE_<alias>=
+# PLURNK_PROVIDERS_DRY_ALLOWED_LENGTH_<alias>=
+# REPEAT_LAST_N widens the older repeat_penalty window past the box's default.
+# Set it per alias only from measured model behavior.
 # PLURNK_PROVIDERS_REPEAT_LAST_N_<alias>=512
 
 # --- Transport budgets (§4, #18) ---
 # Total generation-operation timeout (ms), including retries; caller cancellation also spans the operation.
 PLURNK_PROVIDERS_FETCH_TIMEOUT=600000
 # Maximum silence (ms) between streamed response-body chunks after response
-# streaming begins. Disabled at the portable floor: slow local inference may
-# pause legitimately. Enable per alias only from measured endpoint behavior.
-PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT=0
-# PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT_firefast=120000
-# 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).
+# streaming begins. Two minutes: generous for slow local inference, fast enough
+# to catch a dead connection before the total timeout. A detected stall consumes
+# the same configured retry budget as every other retryable transport failure.
+PLURNK_PROVIDERS_STREAM_IDLE_TIMEOUT=120000
+# Transient-failure retries: 0 = surface the first failure; N = retries on
+# 429/5xx/stream-idle timeout with the AI SDK's backoff (Retry-After wins).
 PLURNK_PROVIDERS_RETRY_ATTEMPTS=3
+# Maximum characters retained from an upstream provider diagnostic in the
+# public Problem detail. Structured failure facts are not truncated.
+PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT=512
 
 # --- Endpoint probe (#34) ---
 # GET /v1/models at construction (context window + llama-server fingerprint). One failure
@@ -82,20 +94,13 @@ PLURNK_PROVIDERS_PROBE_DELAY=250
 # unconstrained output's divergence. Development aid; leave unset in production.
 # PLURNK_PROVIDERS_GBNF_DEBUG=0
 
-# --- Window (SPEC §11) ---
-# Unset = derive: env -> live endpoint probe (n_ctx) -> models.dev catalog -> null (surfaced
-# once via PLURNK_CONTEXT_UNKNOWN naming the model). Set to pin the window deliberately -
-# per-alias (_<alias>) for a box whose model the catalog doesn't know.
+# --- Window ({§model-fact-resolution}) ---
+# Physical provider context only. Unset derives from a live endpoint probe (n_ctx) or
+# models.dev, else null (surfaced once via PLURNK_CONTEXT_UNKNOWN). A configured value
+# caps detected physics or declares it when unknown. Prompt packing and model-facing
+# pressure are consumer policy, not provider configuration.
 # PLURNK_PROVIDERS_CONTEXT_WINDOW=200000
 
-# --- Model pricing override (USD per million tokens; SPEC §4) ---
-# Models.dev owns catalog rates. Set these together for a model absent from the
-# snapshot or to deliberately override its rates. Cached input defaults to the
-# input rate when omitted. All three knobs are per-alias scopable.
-# PLURNK_PROVIDERS_INPUT_USD_PER_MILLION=1
-# PLURNK_PROVIDERS_CACHE_READ_USD_PER_MILLION=0.1
-# PLURNK_PROVIDERS_OUTPUT_USD_PER_MILLION=5
-
 # --- llama-server detection pin (#34) ---
 # Unset = auto-detect from the /v1/models fingerprint. 1 = pin llama-server capabilities
 # (grammar transport, slot pinning, /tokenize) WITHOUT trusting the probe; 0 = force plain
@@ -122,6 +127,8 @@ PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_API_KEY_ENV=CLOUDFLARE_API_TOKEN,CLOUDFLARE
 # 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
+# Direct DeepSeek reasoning follows {§deepseek-reasoning-request}.
+PLURNK_PROVIDERS_PROVIDER_DEEPSEEK_REASONING_STYLE=thinking_effort
 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
@@ -156,11 +163,13 @@ OPENAI_BASE_URL=https://api.openai.com/v1
 PLURNK_BASE_URL=https://plurnk.ai/v1
 # PLURNK_BASE_URL=http://plurnksnr2kihuukt6v22ko72r34dxeatbsfhgow3hvnlw6btanxphad.onion/v1   # Tor
 
-# --- Generation envelope (#507, owner-ruled) - sane defaults from the DETECTED window ---
+# --- Generation envelope (#507) - sane defaults from the DETECTED window ---
 # When a backend advertises its context window (llama-server n_ctx, the plurnk.ai router,
 # a cataloged cloud model), the reserves derive from it automatically - ZERO operator
 # tuning. Each accepts a percentage of the window ("10%") or an absolute token count
 # ("4096"; absolutes win outright, alias-scopable for measured envelopes). The prompt
 # budget is window - reasoning - completion - the consumer's own safety margin.
+# On llama-server, the resolved reasoning reserve is also the adaptive per-response
+# reasoning ceiling. It is one cumulative allowance across every reasoning block.
 PLURNK_PROVIDERS_REASONING_RESERVE=10%
 PLURNK_PROVIDERS_COMPLETION_RESERVE=25%

package/README.md

@@ -5,13 +5,21 @@ PLURNK's stable model-provider contract and its adapter to the
 
 Ordinary provider behavior is intentionally not reimplemented here:
 
-- Models.dev supplies provider package, endpoint, credential, context-window,
-  output-limit, and pricing metadata at build time.
+- A release-time Models.dev snapshot supplies provider package, endpoint, and
+  credential names, plus context-window, output-limit, reasoning-capability,
+  and pricing metadata.
 - 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 contract and `.env.defaults` for every operational knob.
+The package-owned `PLURNK_PROVIDERS_ERROR_DETAIL_LIMIT` bounds upstream
+diagnostic text in public provider Problems.
+
+Model facts do not share one fallback chain. Context windows, output envelopes,
+reasoning activation, and estimated prices resolve independently
+({§model-fact-resolution}). PLURNK does not fetch live per-token prices, and the
+local estimate is not an authoritative relay-settled charge.
 
 ## Configure a model
 
@@ -60,10 +68,15 @@ It may use any npm scope. Its package manifest declares the PLURNK name:
 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.
+notices, or RFC 9457 failure normalization.
+
+The manifest may declare always-on `plurnk.attribution`. The default export may
+also implement synchronous `attributions(context)` and decide per provider
+attempt whether to return no, one, or many additional opaque tags
+({§plugin-attribution}).
 
 Discovery is scope-agnostic and rejects duplicate names.
-`PLURNK_PLUGINS_TRUSTED_ONLY` restricts third-party discovery.
+Third-party discovery uses the shared pre-import trust contract ({§plugin-trust-boundary}).
 
 ## Local endpoints
 
@@ -75,9 +88,60 @@ The `plurnk` provider retains the compatible transport because it carries
 first-party attribution and loop metadata and leaves model tuning to the
 endpoint.
 
+## Configured-provider packet conformance matrix
+
+Every configured model alias is exercised through a real PLURNK loop — the
+production packet, a model-selected operation, its materialized result, and
+completion — never a transport-only completion. Provider-exposed reasoning must
+survive in the durable assistant packet and digest; a provider with no private
+reasoning is valid when the observable operation cycle succeeds.
+
+One specimen at a time, deterministically:
+
+```sh
+cd plurnk-core
+npm run test:live:specimen -- "<test-name-pattern>"
+```
+
+The selector inserts `--test-name-pattern` before the expanded live file list in
+the exact standard `test:live` invocation; trailing npm arguments alone cannot
+narrow the suite. This procedure is `plurnk-core`'s own; the ledger below is
+maintained with the evidence for every alias it names.
+
+### Classifications
+
+| Class | Meaning |
+|---|---|
+| pass | Full packet cycle completed; durable packet and digest verified |
+| auth/credential | The route is blocked before the model by authorization or credential handling |
+| transport | The route fails at a transport/capability boundary, not the model |
+| op:stable-fail | An operation-level failure repeated on replay; assertion unweakened |
+| op:stochastic | An operation-level failure did not repeat on a later roll |
+| unreachable | The endpoint cannot be reached from this machine |
+
+Authorization and credential failures are reported as their own class, never as
+model failures. Repeated stochastic and stable operation failures are reported
+separately in the ledger's specimens.
+
+### Ledger
+
+| Alias | Route (snapshot) | Class | Evidence |
+|---|---|---|---|
+| 38 configured aliases — 2026-07 sweep | — | 20 × pass; 14 × auth/credential/transport; 4 × operation-level | Initial READ line-slice sweep (`#7`) |
+| `cfgpt120b`, `grok` | — | op:stochastic → pass on replay | `#7` |
+| `cfkimi27`, `kimi` | — | op:stable-fail (unresolved, unweakened assertion) | `#7` |
+| `cfds1` | `cloudflare/@cf/deepseek-ai/deepseek-r1-distill-qwen-32b` | op:stable-fail — READ repeated 13 turns to the 508 strike threshold; retrieval materialization verified (`2:beta` present, exact 409 recovery given) | `/home/hyzen/benchmarks/live-contract-read-L-TIgart/digest/` (`#7`) |
+
+The full current classifications of every configured alias are refreshed by the
+frozen-candidate live drill's honest reporting; this ledger is the maintained
+record of that procedure, never a substitute for it.
+
 ## Development
 
 ```sh
 npm run test:lint -w @plurnk/plurnk-providers
 npm run test:unit -w @plurnk/plurnk-providers
 ```
+
+`npm run test:providersPing` is an explicit paid diagnostic; it calls each
+keyed provider once and prints the retained sanitized evidence directory.