@plurnk/plurnk-providers 5.0.1 → 6.0.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.
Files changed (108) hide show
  1. package/.env.defaults +11 -81
  2. package/README.md +21 -22
  3. package/SPEC.md +109 -1190
  4. package/dist/LeadingReasoning.js +1 -1
  5. package/dist/LeadingReasoning.js.map +1 -1
  6. package/dist/Mock.d.ts +2 -2
  7. package/dist/Mock.d.ts.map +1 -1
  8. package/dist/Mock.js +2 -2
  9. package/dist/Mock.js.map +1 -1
  10. package/dist/{AiSdkProvider.d.ts → ModelProvider.d.ts} +12 -21
  11. package/dist/ModelProvider.d.ts.map +1 -0
  12. package/dist/{AiSdkProvider.js → ModelProvider.js} +140 -188
  13. package/dist/ModelProvider.js.map +1 -0
  14. package/dist/{AiSdkRequestBody.d.ts → ModelRequestBody.d.ts} +6 -10
  15. package/dist/ModelRequestBody.d.ts.map +1 -0
  16. package/dist/{AiSdkRequestBody.js → ModelRequestBody.js} +17 -63
  17. package/dist/ModelRequestBody.js.map +1 -0
  18. package/dist/Pool.js +24 -24
  19. package/dist/Pool.js.map +1 -1
  20. package/dist/ProviderRegistry.d.ts.map +1 -1
  21. package/dist/ProviderRegistry.js +15 -15
  22. package/dist/ProviderRegistry.js.map +1 -1
  23. package/dist/RequestCapture.d.ts +1 -0
  24. package/dist/RequestCapture.d.ts.map +1 -1
  25. package/dist/RequestCapture.js +9 -6
  26. package/dist/RequestCapture.js.map +1 -1
  27. package/dist/accounting.d.ts +1 -1
  28. package/dist/accounting.d.ts.map +1 -1
  29. package/dist/accounting.js +4 -4
  30. package/dist/accounting.js.map +1 -1
  31. package/dist/capacity.js +4 -4
  32. package/dist/capacity.js.map +1 -1
  33. package/dist/catalogProvider.d.ts +5 -8
  34. package/dist/catalogProvider.d.ts.map +1 -1
  35. package/dist/catalogProvider.js +216 -66
  36. package/dist/catalogProvider.js.map +1 -1
  37. package/dist/compatibleProvider.d.ts.map +1 -1
  38. package/dist/compatibleProvider.js +8 -8
  39. package/dist/compatibleProvider.js.map +1 -1
  40. package/dist/discover.d.ts +1 -1
  41. package/dist/discover.d.ts.map +1 -1
  42. package/dist/discover.js +1 -8
  43. package/dist/discover.js.map +1 -1
  44. package/dist/env.d.ts +2 -2
  45. package/dist/env.d.ts.map +1 -1
  46. package/dist/env.js +20 -59
  47. package/dist/env.js.map +1 -1
  48. package/dist/errors.d.ts +48 -0
  49. package/dist/errors.d.ts.map +1 -1
  50. package/dist/errors.js +61 -4
  51. package/dist/errors.js.map +1 -1
  52. package/dist/index.d.ts +5 -6
  53. package/dist/index.d.ts.map +1 -1
  54. package/dist/index.js +6 -7
  55. package/dist/index.js.map +1 -1
  56. package/dist/{sdkModels.d.ts → modelAdapters.d.ts} +7 -9
  57. package/dist/modelAdapters.d.ts.map +1 -0
  58. package/dist/{sdkModels.js → modelAdapters.js} +194 -87
  59. package/dist/modelAdapters.js.map +1 -0
  60. package/dist/native-tools.d.ts +1 -2
  61. package/dist/native-tools.d.ts.map +1 -1
  62. package/dist/native-tools.js +9 -11
  63. package/dist/native-tools.js.map +1 -1
  64. package/dist/ollama.d.ts.map +1 -1
  65. package/dist/ollama.js +26 -12
  66. package/dist/ollama.js.map +1 -1
  67. package/dist/openai.d.ts +3 -3
  68. package/dist/openai.d.ts.map +1 -1
  69. package/dist/openai.js +1 -1
  70. package/dist/pi-transport.d.ts +69 -0
  71. package/dist/pi-transport.d.ts.map +1 -0
  72. package/dist/pi-transport.js +697 -0
  73. package/dist/pi-transport.js.map +1 -0
  74. package/dist/providerError.js +1 -1
  75. package/dist/providerError.js.map +1 -1
  76. package/dist/retry-deadline.d.ts +3 -0
  77. package/dist/retry-deadline.d.ts.map +1 -0
  78. package/dist/retry-deadline.js +96 -0
  79. package/dist/retry-deadline.js.map +1 -0
  80. package/dist/stream-forensics.d.ts +51 -0
  81. package/dist/stream-forensics.d.ts.map +1 -0
  82. package/dist/stream-forensics.js +403 -0
  83. package/dist/stream-forensics.js.map +1 -0
  84. package/dist/types.d.ts +29 -4
  85. package/dist/types.d.ts.map +1 -1
  86. package/dist/types.js.map +1 -1
  87. package/dist/usage.js +2 -2
  88. package/dist/usage.js.map +1 -1
  89. package/docs/models.md +3 -3
  90. package/package.json +8 -21
  91. package/dist/AiSdkProvider.d.ts.map +0 -1
  92. package/dist/AiSdkProvider.js.map +0 -1
  93. package/dist/AiSdkRequestBody.d.ts.map +0 -1
  94. package/dist/AiSdkRequestBody.js.map +0 -1
  95. package/dist/RequestFields.d.ts +0 -24
  96. package/dist/RequestFields.d.ts.map +0 -1
  97. package/dist/RequestFields.js +0 -237
  98. package/dist/RequestFields.js.map +0 -1
  99. package/dist/aiSdkTransport.d.ts +0 -84
  100. package/dist/aiSdkTransport.d.ts.map +0 -1
  101. package/dist/aiSdkTransport.js +0 -651
  102. package/dist/aiSdkTransport.js.map +0 -1
  103. package/dist/model-options.d.ts +0 -3
  104. package/dist/model-options.d.ts.map +0 -1
  105. package/dist/model-options.js +0 -26
  106. package/dist/model-options.js.map +0 -1
  107. package/dist/sdkModels.d.ts.map +0 -1
  108. package/dist/sdkModels.js.map +0 -1
package/.env.defaults CHANGED
@@ -35,7 +35,7 @@ PLURNK_PROVIDERS_OUTPUT_FLOOR=10%
35
35
  # PLURNK_PROVIDERS_CONTEXT_WINDOW=200000
36
36
 
37
37
  # --- Reasoning ---
38
- # off | adaptive | low | medium | high | xhigh | max. Seed for durable Worker reasoning.
38
+ # off | adaptive | low | medium | high | xhigh | max. Seed for durable Session reasoning.
39
39
  # adaptive prefers native dynamic reasoning, then the supported fallback below.
40
40
  PLURNK_PROVIDERS_EFFORT=adaptive
41
41
  # Fixed effort when native adaptation is unavailable; empty/unsupported = enabled provider default.
@@ -43,22 +43,10 @@ PLURNK_PROVIDERS_EFFORT_FALLBACK=high
43
43
  # Response interpretation: verbatim = trust structured reasoning fields; think-tags = extract one
44
44
  # leading <think> envelope. Select only for an endpoint that emits it; independent of activation.
45
45
  PLURNK_PROVIDERS_REASONING_RESPONSE_STYLE=verbatim
46
- # Compatible wire declarations below supplement Models.dev; native SDKs own their protocols.
47
- # Route knobs use the same suffix, e.g. PLURNK_PROVIDERS_REASONING_BUDGET_PATH_<alias>.
48
- # PLURNK_PROVIDERS_OUTPUT_PATH=/max_completion_tokens
49
- # PLURNK_PROVIDERS_REASONING_EFFORT_PATH=/reasoning_effort
50
- # PLURNK_PROVIDERS_REASONING_CONTROLS=exclusive
51
- # PLURNK_PROVIDERS_REASONING_ON_BODY='{"enable_thinking":true}'
52
- # PLURNK_PROVIDERS_REASONING_OFF_BODY='{"enable_thinking":false}'
53
- # PLURNK_PROVIDERS_REASONING_EFFORTS=low,medium,high
46
+ # Additional supported reasoning effort values supplementing Models.dev, comma-separated.
54
47
  # A llama-server route admits off and adaptive; declare the fixed efforts its chat template
55
48
  # distinguishes, e.g. PLURNK_PROVIDERS_REASONING_EFFORTS_<alias>=low,medium,xhigh.
56
- # PLURNK_PROVIDERS_REASONING_TRANSPORT_EFFORTS=none,low,medium,high
57
- # PLURNK_PROVIDERS_OPTIONS_NAMESPACE=openrouter
58
- # PLURNK_PROVIDERS_REASONING_ADAPTIVE_BODY='{}'
59
- # PLURNK_PROVIDERS_REASONING_TOGGLE_BODY='{"reasoning":{"enabled":true}}'
60
- # PLURNK_PROVIDERS_ADAPTIVE_OPTIONS='[{"models":["*"],"options":{"<sdk-namespace>":{…}}}]'
61
- # PLURNK_PROVIDERS_SYSTEM_CACHE_OPTIONS=
49
+ # PLURNK_PROVIDERS_REASONING_EFFORTS=low,medium,high
62
50
  # PLURNK_PROVIDERS_APP_URL=https://example.test/app
63
51
  # PLURNK_PROVIDERS_APP_NAME=Example
64
52
 
@@ -87,21 +75,13 @@ PLURNK_PROVIDERS_DRY_MULTIPLIER=0
87
75
  # PLURNK_PROVIDERS_DRY_ALLOWED_LENGTH=
88
76
 
89
77
  # --- Cache and billing ---
90
- # Stable Worker affinity on supported routes: 1 = on; 0 = off. Unknown routes get no guessed field.
78
+ # Stable Session affinity on supported routes: 1 = on; 0 = off. Unknown routes get no guessed field.
91
79
  PLURNK_PROVIDERS_CACHE_AFFINITY=1
92
- # FIELD declares placement, independent of the enable switch; null clears it for an alias.
93
- # target is header or body with name, or provider-option with provider and name.
94
- # PLURNK_PROVIDERS_CACHE_AFFINITY_FIELD_<alias>='{"target":"header","name":"x-session-id"}'
95
- PLURNK_PROVIDERS_PROVIDER_OPENAI_CACHE_AFFINITY_FIELD='{"target":"provider-option","provider":"openai","name":"promptCacheKey"}'
96
- PLURNK_PROVIDERS_PROVIDER_DEEPINFRA_CACHE_AFFINITY_FIELD='{"target":"provider-option","provider":"deepinfra","name":"prompt_cache_key"}'
97
- PLURNK_PROVIDERS_PROVIDER_OPENROUTER_CACHE_AFFINITY_FIELD='{"target":"header","name":"x-session-id"}'
98
- PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_WORKERS_AI_CACHE_AFFINITY_FIELD='{"target":"header","name":"x-session-affinity"}'
99
- PLURNK_PROVIDERS_PROVIDER_FIREWORKS_AI_CACHE_AFFINITY_FIELD='{"target":"header","name":"x-session-affinity"}'
100
- # Explicit cache writes: stable-system = reusable system boundary where SYSTEM_CACHE_OPTIONS declares it;
80
+ # Explicit cache writes: stable-system = reusable system boundary on routes whose adapter supports it;
101
81
  # off = no explicit writes. This is distinct from affinity and can affect billing.
102
82
  PLURNK_PROVIDERS_CACHE_WRITE_POLICY=stable-system
103
83
  # Provider service tier; unset = provider default. Usually set per alias: routing can change cost.
104
- # Native routes send it only where the SDK documents one ({§provider-request-controls}); others warn.
84
+ # Native routes send it only where the SDK documents one ({§provider-request-authority}); others warn.
105
85
  # PLURNK_PROVIDERS_SERVICE_TIER=
106
86
  # PLURNK_PROVIDERS_SERVICE_TIER_myfireworks=priority
107
87
  # USD per million tokens, merged over Models.dev rates; omitted categories retain catalog values.
@@ -132,7 +112,7 @@ PLURNK_PROVIDERS_PROBE_DELAY=250
132
112
 
133
113
  # --- Evidence capture ---
134
114
  # OpenAI top_logprobs: off/unset = none; 0 = chosen token only; N > 0 = alternatives.
135
- # Compatible routes and native OpenAI send it; other native routes warn ({§provider-request-controls}).
115
+ # Compatible routes and native OpenAI send it; other native routes warn ({§provider-request-authority}).
136
116
  # PLURNK_PROVIDERS_TOP_LOGPROBS=3
137
117
  # Retain request bodies and SDK raw responses: unset/empty/0 = off; other values = on.
138
118
  # Diagnostic evidence includes model input/native payloads; isolate to a capture alias.
@@ -141,70 +121,20 @@ PLURNK_PROVIDERS_PROBE_DELAY=250
141
121
  # --- Provider declarations ---
142
122
  # Override known facts or declare an uncataloged provider. NAME is the route's provider segment.
143
123
  # API_KEY_ENV names a variable, never its secret value.
144
- # PLURNK_PROVIDERS_PROVIDER_ACME_NPM=@ai-sdk/openai-compatible
124
+ # PLURNK_PROVIDERS_PROVIDER_ACME_ADAPTER=openai-compatible
145
125
  # PLURNK_PROVIDERS_PROVIDER_ACME_BASE_URL=https://api.acme.example/v1
146
126
  # PLURNK_PROVIDERS_PROVIDER_ACME_API_KEY_ENV=ACME_API_KEY
147
- # Compatible request fields use RFC 6901 pointers; output defaults to the SDK's max_tokens.
148
127
  # Effort vocabulary and budget bounds come from Models.dev; EFFORTS adds declared values.
149
- # ON_BODY applies whenever reasoning is active. OFF_BODY disables it. ADAPTIVE_BODY replaces
150
- # the graded fallback; {} leaves the enabled endpoint at its native default.
151
- # TOGGLE_BODY enables a catalog toggle when no adaptive body or supported fallback applies.
152
- # Bodies contain only reasoning controls, not model/messages, sampling, or token ceilings.
153
- # With both paths declared, CONTROLS must say exclusive or combined. Fixed effort plus a numeric
154
- # budget on an exclusive route fails before inference; adaptive + budget selects the numeric dial.
155
- # PLURNK_PROVIDERS_PROVIDER_ACME_OUTPUT_PATH=/max_completion_tokens
156
- # PLURNK_PROVIDERS_PROVIDER_ACME_REASONING_EFFORT_PATH=/reasoning/effort
157
- # PLURNK_PROVIDERS_PROVIDER_ACME_REASONING_BUDGET_PATH=/reasoning/max_tokens
158
- # PLURNK_PROVIDERS_PROVIDER_ACME_REASONING_CONTROLS=exclusive
159
128
  # PLURNK_PROVIDERS_PROVIDER_ACME_REASONING_EFFORTS=low,medium,high
160
- # PLURNK_PROVIDERS_PROVIDER_ACME_REASONING_ON_BODY='{"reasoning":{"enabled":true}}'
161
- # PLURNK_PROVIDERS_PROVIDER_ACME_REASONING_OFF_BODY='{"reasoning":{"enabled":false}}'
162
- # PLURNK_PROVIDERS_PROVIDER_ACME_REASONING_ADAPTIVE_BODY='{}'
163
129
  # The form of every provider declaration; NAME is the route's provider segment.
164
130
  # PLURNK_PROVIDERS_PROVIDER_<NAME>_<SETTING>=<value>
165
- PLURNK_PROVIDERS_PROVIDER_FIREWORKS_AI_REASONING_EFFORT_PATH=/reasoning_effort
166
- PLURNK_PROVIDERS_PROVIDER_FIREWORKS_AI_REASONING_OFF_BODY='{"reasoning_effort":"none"}'
167
- PLURNK_PROVIDERS_PROVIDER_FIREWORKS_AI_REASONING_TOGGLE_BODY='{"reasoning_effort":true}'
168
- PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_WORKERS_AI_REASONING_EFFORT_PATH=/reasoning_effort
169
131
  # Additional supported Cloudflare effort values, comma-separated; empty = Models.dev only.
170
132
  PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_WORKERS_AI_REASONING_EFFORTS=
171
- # Direct DeepSeek thinking activation and effort.
172
- PLURNK_PROVIDERS_PROVIDER_DEEPSEEK_REASONING_EFFORT_PATH=/reasoning_effort
173
- PLURNK_PROVIDERS_PROVIDER_DEEPSEEK_REASONING_ON_BODY='{"thinking":{"type":"enabled"}}'
174
- PLURNK_PROVIDERS_PROVIDER_DEEPSEEK_REASONING_OFF_BODY='{"thinking":{"type":"disabled"}}'
175
- # OpenRouter's native SDK accepts these same fields in per-call provider options.
176
- PLURNK_PROVIDERS_PROVIDER_OPENROUTER_OPTIONS_NAMESPACE=openrouter
177
- PLURNK_PROVIDERS_PROVIDER_OPENROUTER_REASONING_EFFORT_PATH=/reasoning/effort
178
- PLURNK_PROVIDERS_PROVIDER_OPENROUTER_REASONING_BUDGET_PATH=/reasoning/max_tokens
179
- PLURNK_PROVIDERS_PROVIDER_OPENROUTER_REASONING_CONTROLS=exclusive
180
- PLURNK_PROVIDERS_PROVIDER_OPENROUTER_REASONING_TRANSPORT_EFFORTS=none,minimal,low,medium,high,xhigh,max
181
- PLURNK_PROVIDERS_PROVIDER_OPENROUTER_REASONING_ON_BODY='{"reasoning":{"enabled":true}}'
182
- PLURNK_PROVIDERS_PROVIDER_OPENROUTER_REASONING_OFF_BODY='{"reasoning":{"effort":"none"}}'
183
- # DeepInfra's and Together's native SDKs extend openai-compatible, which overwrites a raw `reasoning_effort`
184
- # option; the effort rides the SDK's own `reasoningEffort`, so every catalog effort, max included, reaches the wire.
185
- PLURNK_PROVIDERS_PROVIDER_DEEPINFRA_OPTIONS_NAMESPACE=deepinfra
186
- PLURNK_PROVIDERS_PROVIDER_DEEPINFRA_REASONING_EFFORT_PATH=/reasoningEffort
187
- PLURNK_PROVIDERS_PROVIDER_DEEPINFRA_REASONING_OFF_BODY='{"reasoningEffort":"none"}'
188
- PLURNK_PROVIDERS_PROVIDER_TOGETHERAI_OPTIONS_NAMESPACE=togetherai
189
- PLURNK_PROVIDERS_PROVIDER_TOGETHERAI_REASONING_EFFORT_PATH=/reasoningEffort
190
- PLURNK_PROVIDERS_PROVIDER_TOGETHERAI_REASONING_OFF_BODY='{"reasoningEffort":"none"}'
191
- # Model-family provider options: a JSON array of {"models":["<glob>",…],"options":{…}} rules matched
192
- # against the route's model id, first match wins ({§provider-model-options}). ADAPTIVE_OPTIONS replaces the
193
- # adaptive policy's projection; SYSTEM_CACHE_OPTIONS marks the stable system prompt for cache writes.
194
- # None ship: the shipped defaults serve open models only; declare a closed family's options yourself.
195
- # Alibaba DashScope (OpenAI-compatible): max_tokens is answer-only, max_completion_tokens is inclusive;
196
- # effort and thinking budget are alternatives; enable_thinking switches reasoning.
197
- PLURNK_PROVIDERS_PROVIDER_ALIBABA_OUTPUT_PATH=/max_completion_tokens
198
- PLURNK_PROVIDERS_PROVIDER_ALIBABA_REASONING_EFFORT_PATH=/reasoning_effort
199
- PLURNK_PROVIDERS_PROVIDER_ALIBABA_REASONING_BUDGET_PATH=/thinking_budget
200
- PLURNK_PROVIDERS_PROVIDER_ALIBABA_REASONING_CONTROLS=exclusive
201
- PLURNK_PROVIDERS_PROVIDER_ALIBABA_REASONING_ON_BODY='{"enable_thinking":true}'
202
- PLURNK_PROVIDERS_PROVIDER_ALIBABA_REASONING_OFF_BODY='{"enable_thinking":false}'
203
- # Uncataloged compatible providers: SDK, endpoint, and credential-variable name.
204
- PLURNK_PROVIDERS_PROVIDER_BAICHUAN_NPM=@ai-sdk/openai-compatible
133
+ # Uncataloged compatible providers: adapter, endpoint, and credential-variable name.
134
+ PLURNK_PROVIDERS_PROVIDER_BAICHUAN_ADAPTER=openai-compatible
205
135
  PLURNK_PROVIDERS_PROVIDER_BAICHUAN_BASE_URL=https://api.baichuan-ai.com/v1
206
136
  PLURNK_PROVIDERS_PROVIDER_BAICHUAN_API_KEY_ENV=BAICHUAN_API_KEY
207
- PLURNK_PROVIDERS_PROVIDER_QIANFAN_NPM=@ai-sdk/openai-compatible
137
+ PLURNK_PROVIDERS_PROVIDER_QIANFAN_ADAPTER=openai-compatible
208
138
  PLURNK_PROVIDERS_PROVIDER_QIANFAN_BASE_URL=https://qianfan.baidubce.com/v2
209
139
  PLURNK_PROVIDERS_PROVIDER_QIANFAN_API_KEY_ENV=QIANFAN_API_KEY
210
140
 
package/README.md CHANGED
@@ -1,19 +1,19 @@
1
1
  # @plurnk/plurnk-providers
2
2
 
3
- PLURNK's stable model-provider contract and its adapter to the
4
- [AI SDK](https://ai-sdk.dev/).
3
+ PLURNK's stable model-provider contract and its transport adapters over
4
+ `@earendil-works/pi-ai` and OpenAI-compatible HTTP endpoints.
5
5
 
6
6
  Ordinary provider behavior is intentionally not reimplemented here:
7
7
 
8
- - A release-time Models.dev snapshot supplies provider package, endpoint, and
8
+ - A release-time Models.dev snapshot supplies provider adapter, endpoint, and
9
9
  credential names, plus context-window, output-limit, reasoning-capability,
10
10
  and pricing metadata.
11
- - Official AI SDK providers own vendor request and response protocols.
11
+ - Protocol adapters own vendor request and response protocols.
12
12
  - PLURNK owns aliases, generation envelopes, normalized usage and errors,
13
13
  evidence capture, first-party metadata, and local endpoint capabilities.
14
14
 
15
15
  Native tool calling is explicitly disabled through each protocol's standard
16
- controls; PLURNK operations travel as text ({§provider-native-tools-disabled}).
16
+ controls; PLURNK operations travel as text ({§provider-interface}).
17
17
 
18
18
  See [SPEC.md](SPEC.md) for the contract, [the model reference](docs/models.md)
19
19
  for what a model is told about routes and generation, and
@@ -30,9 +30,9 @@ router fee; incomplete billing evidence remains unknown ({§provider-monetary-ev
30
30
 
31
31
  ## Runtime-neutral contracts
32
32
 
33
- Browser and edge Workers import accounting and normalized failures through
33
+ Browser and edge Sessions import accounting and normalized failures through
34
34
  their dedicated runtime-neutral subpaths
35
- ({§provider-runtime-neutral-accounting}, {§provider-runtime-neutral-errors}):
35
+ ({§provider-interface}):
36
36
 
37
37
  ```js
38
38
  import {
@@ -66,7 +66,7 @@ Cataloged providers need no endpoint declaration. To add an
66
66
  OpenAI-compatible provider that Models.dev does not describe:
67
67
 
68
68
  ```dotenv
69
- PLURNK_PROVIDERS_PROVIDER_ACME_NPM=@ai-sdk/openai-compatible
69
+ PLURNK_PROVIDERS_PROVIDER_ACME_ADAPTER=openai-compatible
70
70
  PLURNK_PROVIDERS_PROVIDER_ACME_BASE_URL=https://api.acme.example/v1
71
71
  PLURNK_PROVIDERS_PROVIDER_ACME_API_KEY_ENV=ACME_API_KEY
72
72
  PLURNK_MODEL_acme=acme/model-id
@@ -88,8 +88,8 @@ The forms, in one table:
88
88
  Models.dev supplies cataloged providers' endpoints, credential-variable names,
89
89
  model limits, reasoning capabilities, and rates. The operator supplies
90
90
  credentials to the service environment; a client's environment does not
91
- configure a remote daemon. Worker model and reasoning selections persist:
92
- changing a startup default is not a command to retarget existing Workers.
91
+ configure a remote daemon. Session model and reasoning selections persist:
92
+ changing a startup default is not a command to retarget existing Sessions.
93
93
  Clients expose explicit model, reasoning, and child-model controls; their
94
94
  available effort choices come from the selected route.
95
95
 
@@ -97,7 +97,7 @@ Sampling uses endpoint defaults unless configured. `TEMPERATURE`, `TOP_P`,
97
97
  `TOP_K`, `PRESENCE_PENALTY`, `FREQUENCY_PENALTY`, and `SEED` use the same
98
98
  `PLURNK_PROVIDERS_<KNOB>_<alias>` form. Supported values depend on the endpoint;
99
99
  Models.dev does not supply a recommended sampling profile. See the
100
- [sampling contract](SPEC.md) ({§provider-sampling-passthrough}) and
100
+ [sampling contract](SPEC.md) ({§provider-configuration}) and
101
101
  [environment panel](.env.defaults) for ranges and omission rules.
102
102
 
103
103
  ## Capacity and reasoning
@@ -117,11 +117,11 @@ flowchart TD
117
117
  - **Output** accepts positive tokens or a percentage of context; known model
118
118
  limits cap it. An explicit reasoning budget must be smaller than total output.
119
119
  Leaving the reasoning budget unset does not disable reasoning.
120
- - **Output floor** (`PLURNK_PROVIDERS_OUTPUT_FLOOR`, shipped `10%`) is the least
120
+ - **Output floor** (`PLURNK_PROVIDERS_OUTPUT_FLOOR`, shipped `25%`) is the least
121
121
  response room any request keeps, never above the output budget. The window less
122
122
  the floor is the input wall: a packet past the budget is still sent with its
123
123
  grant flexed down to the remainder; only a packet past the wall cannot be sent
124
- ({§provider-output-floor}).
124
+ ({§provider-capacity-admission}).
125
125
  - **Context** is derived from the live endpoint or catalog. An operator cap can
126
126
  shrink known capacity or declare unknown capacity, never enlarge known limits.
127
127
  Prompt projection and initialization reasoning READ limits are separate Core policy.
@@ -141,24 +141,23 @@ It may use any npm scope. Its package manifest declares the PLURNK name:
141
141
  "name": "acme"
142
142
  },
143
143
  "peerDependencies": {
144
- "@plurnk/plurnk-providers": "^1.2.0",
145
- "ai": "^6.0.0"
144
+ "@plurnk/plurnk-providers": "^6.0.0"
146
145
  }
147
146
  }
148
147
  ```
149
148
 
150
- The default export is an AI SDK provider with
151
- `languageModel(modelId)`. PLURNK adapts that language model into its own
149
+ The default export is a `ProviderExtension` with
150
+ `model(modelId)`. PLURNK adapts that model transport into its own
152
151
  contract, so extensions do not reproduce retries, usage normalization, envelopes,
153
152
  notices, or RFC 9457 failure normalization.
154
153
 
155
154
  The manifest may declare always-on `plurnk.attribution`. The default export may
156
155
  also implement synchronous `attributions(context)` and decide per provider
157
156
  attempt whether to return no, one, or many additional opaque tags
158
- ({§extension-attribution}).
157
+ ({§extension-discovery}).
159
158
 
160
159
  Discovery is scope-agnostic and rejects duplicate names.
161
- Third-party discovery uses the shared pre-import trust contract ({§extension-trust-boundary}).
160
+ Third-party discovery uses the shared pre-import trust contract ({§extension-discovery}).
162
161
 
163
162
  ## Local endpoints
164
163
 
@@ -175,7 +174,7 @@ PLURNK_MODEL=local
175
174
  # Optional explicit generation allowances, in tokens:
176
175
  # PLURNK_PROVIDERS_OUTPUT_BUDGET_local=8192
177
176
  # PLURNK_PROVIDERS_REASONING_BUDGET_local=4096
178
- # Optional: serialize inference on a single-slot endpoint without serializing workers:
177
+ # Optional: serialize inference on a single-slot endpoint without serializing sessions:
179
178
  # PLURNK_PROVIDERS_MAX_CONCURRENCY_local=1
180
179
  ```
181
180
 
@@ -200,12 +199,12 @@ opt-in for endpoints that emit a leading `<think>` envelope, not a reasoning swi
200
199
  | Discovery/tokenizer HTTP | Separate non-generation fetch bound; does not limit inference. |
201
200
  | Provider-directed waits | Bounded retries honor `Retry-After`; other recoverable failures return to Core. |
202
201
  | Loop recovery | Core reissues within its recovery window, then parks for a review-capable owner or concludes on the failure. |
203
- | Cache affinity | Stable Worker identity through documented provider controls; not a cache-hit guarantee. |
202
+ | Cache affinity | Stable Session identity through documented provider controls; not a cache-hit guarantee. |
204
203
  | Explicit cache writes | Separate policy on supported routes; can affect billing. |
205
204
  | Service tier | Explicit route choice that may change price and availability. |
206
205
  | Cost | Provider monetary evidence wins; known usage and catalog rates yield an estimate, not a settled charge. |
207
206
 
208
- For uncataloged compatible endpoints, declare the SDK, URL, and credential-variable
207
+ For uncataloged compatible endpoints, declare the adapter, URL, and credential-variable
209
208
  name together; the examples are in the defaults reference. A provider extension is
210
209
  needed only when the protocol cannot be expressed by the installed adapters.
211
210