@plurnk/plurnk-providers 5.0.2 → 6.0.1
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/.env.defaults +18 -84
- package/README.md +21 -22
- package/SPEC.md +110 -1190
- package/dist/LeadingReasoning.js +1 -1
- package/dist/LeadingReasoning.js.map +1 -1
- package/dist/Mock.d.ts +2 -2
- package/dist/Mock.d.ts.map +1 -1
- package/dist/Mock.js +2 -2
- package/dist/Mock.js.map +1 -1
- package/dist/{AiSdkProvider.d.ts → ModelProvider.d.ts} +12 -21
- package/dist/ModelProvider.d.ts.map +1 -0
- package/dist/{AiSdkProvider.js → ModelProvider.js} +140 -188
- package/dist/ModelProvider.js.map +1 -0
- package/dist/{AiSdkRequestBody.d.ts → ModelRequestBody.d.ts} +6 -10
- package/dist/ModelRequestBody.d.ts.map +1 -0
- package/dist/{AiSdkRequestBody.js → ModelRequestBody.js} +17 -63
- package/dist/ModelRequestBody.js.map +1 -0
- package/dist/Pool.js +24 -24
- package/dist/Pool.js.map +1 -1
- package/dist/ProviderRegistry.d.ts.map +1 -1
- package/dist/ProviderRegistry.js +15 -15
- package/dist/ProviderRegistry.js.map +1 -1
- package/dist/RequestCapture.d.ts +1 -0
- package/dist/RequestCapture.d.ts.map +1 -1
- package/dist/RequestCapture.js +9 -6
- package/dist/RequestCapture.js.map +1 -1
- package/dist/accounting.d.ts +1 -1
- package/dist/accounting.d.ts.map +1 -1
- package/dist/accounting.js +4 -4
- package/dist/accounting.js.map +1 -1
- package/dist/capacity.js +4 -4
- package/dist/capacity.js.map +1 -1
- package/dist/catalogProvider.d.ts +5 -8
- package/dist/catalogProvider.d.ts.map +1 -1
- package/dist/catalogProvider.js +218 -68
- package/dist/catalogProvider.js.map +1 -1
- package/dist/compatibleProvider.d.ts.map +1 -1
- package/dist/compatibleProvider.js +19 -8
- package/dist/compatibleProvider.js.map +1 -1
- package/dist/discover.d.ts +1 -1
- package/dist/discover.d.ts.map +1 -1
- package/dist/discover.js +1 -8
- package/dist/discover.js.map +1 -1
- package/dist/env.d.ts +4 -4
- package/dist/env.d.ts.map +1 -1
- package/dist/env.js +43 -80
- package/dist/env.js.map +1 -1
- package/dist/errors.d.ts +48 -0
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +61 -4
- package/dist/errors.js.map +1 -1
- package/dist/index.d.ts +5 -6
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +6 -7
- package/dist/index.js.map +1 -1
- package/dist/{sdkModels.d.ts → modelAdapters.d.ts} +7 -9
- package/dist/modelAdapters.d.ts.map +1 -0
- package/dist/{sdkModels.js → modelAdapters.js} +194 -87
- package/dist/modelAdapters.js.map +1 -0
- package/dist/native-tools.d.ts +1 -2
- package/dist/native-tools.d.ts.map +1 -1
- package/dist/native-tools.js +9 -11
- package/dist/native-tools.js.map +1 -1
- package/dist/ollama.d.ts.map +1 -1
- package/dist/ollama.js +26 -12
- package/dist/ollama.js.map +1 -1
- package/dist/openai.d.ts +3 -3
- package/dist/openai.d.ts.map +1 -1
- package/dist/openai.js +1 -1
- package/dist/pi-transport.d.ts +69 -0
- package/dist/pi-transport.d.ts.map +1 -0
- package/dist/pi-transport.js +697 -0
- package/dist/pi-transport.js.map +1 -0
- package/dist/providerError.js +1 -1
- package/dist/providerError.js.map +1 -1
- package/dist/retry-deadline.d.ts +3 -0
- package/dist/retry-deadline.d.ts.map +1 -0
- package/dist/retry-deadline.js +96 -0
- package/dist/retry-deadline.js.map +1 -0
- package/dist/stream-forensics.d.ts +51 -0
- package/dist/stream-forensics.d.ts.map +1 -0
- package/dist/stream-forensics.js +466 -0
- package/dist/stream-forensics.js.map +1 -0
- package/dist/types.d.ts +29 -4
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js.map +1 -1
- package/dist/usage.js +2 -2
- package/dist/usage.js.map +1 -1
- package/docs/models.md +3 -3
- package/package.json +8 -21
- package/dist/AiSdkProvider.d.ts.map +0 -1
- package/dist/AiSdkProvider.js.map +0 -1
- package/dist/AiSdkRequestBody.d.ts.map +0 -1
- package/dist/AiSdkRequestBody.js.map +0 -1
- package/dist/RequestFields.d.ts +0 -24
- package/dist/RequestFields.d.ts.map +0 -1
- package/dist/RequestFields.js +0 -237
- package/dist/RequestFields.js.map +0 -1
- package/dist/aiSdkTransport.d.ts +0 -84
- package/dist/aiSdkTransport.d.ts.map +0 -1
- package/dist/aiSdkTransport.js +0 -651
- package/dist/aiSdkTransport.js.map +0 -1
- package/dist/model-options.d.ts +0 -3
- package/dist/model-options.d.ts.map +0 -1
- package/dist/model-options.js +0 -26
- package/dist/model-options.js.map +0 -1
- package/dist/sdkModels.d.ts.map +0 -1
- 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
|
|
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
|
-
#
|
|
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
|
-
#
|
|
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,26 +75,22 @@ PLURNK_PROVIDERS_DRY_MULTIPLIER=0
|
|
|
87
75
|
# PLURNK_PROVIDERS_DRY_ALLOWED_LENGTH=
|
|
88
76
|
|
|
89
77
|
# --- Cache and billing ---
|
|
90
|
-
# Stable
|
|
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
|
-
#
|
|
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-
|
|
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
|
-
# USD per million tokens, merged over Models.dev rates;
|
|
108
|
-
#
|
|
109
|
-
|
|
87
|
+
# USD per million tokens, merged over Models.dev rates; empty = retain catalog values.
|
|
88
|
+
# One scalar knob per category (all accept _<alias> overrides). This is estimation, not billing truth.
|
|
89
|
+
PLURNK_PROVIDERS_COST_INPUT=
|
|
90
|
+
PLURNK_PROVIDERS_COST_OUTPUT=
|
|
91
|
+
PLURNK_PROVIDERS_COST_REASONING=
|
|
92
|
+
PLURNK_PROVIDERS_COST_CACHE_READ=
|
|
93
|
+
PLURNK_PROVIDERS_COST_CACHE_WRITE=
|
|
110
94
|
|
|
111
95
|
# --- Connectivity (milliseconds; 0 = off) ---
|
|
112
96
|
# Logical generation deadline, including admission queues, physical attempts and retry delays.
|
|
@@ -132,7 +116,7 @@ PLURNK_PROVIDERS_PROBE_DELAY=250
|
|
|
132
116
|
|
|
133
117
|
# --- Evidence capture ---
|
|
134
118
|
# 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-
|
|
119
|
+
# Compatible routes and native OpenAI send it; other native routes warn ({§provider-request-authority}).
|
|
136
120
|
# PLURNK_PROVIDERS_TOP_LOGPROBS=3
|
|
137
121
|
# Retain request bodies and SDK raw responses: unset/empty/0 = off; other values = on.
|
|
138
122
|
# Diagnostic evidence includes model input/native payloads; isolate to a capture alias.
|
|
@@ -141,70 +125,20 @@ PLURNK_PROVIDERS_PROBE_DELAY=250
|
|
|
141
125
|
# --- Provider declarations ---
|
|
142
126
|
# Override known facts or declare an uncataloged provider. NAME is the route's provider segment.
|
|
143
127
|
# API_KEY_ENV names a variable, never its secret value.
|
|
144
|
-
#
|
|
128
|
+
# PLURNK_PROVIDERS_PROVIDER_ACME_ADAPTER=openai-compatible
|
|
145
129
|
# PLURNK_PROVIDERS_PROVIDER_ACME_BASE_URL=https://api.acme.example/v1
|
|
146
130
|
# 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
131
|
# 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
132
|
# 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
133
|
# The form of every provider declaration; NAME is the route's provider segment.
|
|
164
134
|
# 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
135
|
# Additional supported Cloudflare effort values, comma-separated; empty = Models.dev only.
|
|
170
136
|
PLURNK_PROVIDERS_PROVIDER_CLOUDFLARE_WORKERS_AI_REASONING_EFFORTS=
|
|
171
|
-
#
|
|
172
|
-
|
|
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
|
|
137
|
+
# Uncataloged compatible providers: adapter, endpoint, and credential-variable name.
|
|
138
|
+
PLURNK_PROVIDERS_PROVIDER_BAICHUAN_ADAPTER=openai-compatible
|
|
205
139
|
PLURNK_PROVIDERS_PROVIDER_BAICHUAN_BASE_URL=https://api.baichuan-ai.com/v1
|
|
206
140
|
PLURNK_PROVIDERS_PROVIDER_BAICHUAN_API_KEY_ENV=BAICHUAN_API_KEY
|
|
207
|
-
|
|
141
|
+
PLURNK_PROVIDERS_PROVIDER_QIANFAN_ADAPTER=openai-compatible
|
|
208
142
|
PLURNK_PROVIDERS_PROVIDER_QIANFAN_BASE_URL=https://qianfan.baidubce.com/v2
|
|
209
143
|
PLURNK_PROVIDERS_PROVIDER_QIANFAN_API_KEY_ENV=QIANFAN_API_KEY
|
|
210
144
|
|
package/README.md
CHANGED
|
@@ -1,19 +1,19 @@
|
|
|
1
1
|
# @plurnk/plurnk-providers
|
|
2
2
|
|
|
3
|
-
PLURNK's stable model-provider contract and its
|
|
4
|
-
|
|
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
|
|
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
|
-
-
|
|
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-
|
|
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
|
|
33
|
+
Browser and edge Sessions import accounting and normalized failures through
|
|
34
34
|
their dedicated runtime-neutral subpaths
|
|
35
|
-
({§provider-
|
|
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
|
-
|
|
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.
|
|
92
|
-
changing a startup default is not a command to retarget existing
|
|
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-
|
|
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 `
|
|
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-
|
|
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": "^
|
|
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
|
|
151
|
-
`
|
|
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-
|
|
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-
|
|
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
|
|
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
|
|
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
|
|
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
|
|