pi-blablador 0.0.0-stage → 0.1.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.
Files changed (4) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +159 -2
  3. package/blablador.ts +115 -0
  4. package/package.json +49 -5
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 the pi-blablador authors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,160 @@
1
- # Temporary Holding Version
1
+ # pi-blablador
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [Blablador](https://blablador.fz-juelich.de) is the research LLM service run by JSC (Forschungszentrum
4
+ Jülich) for Helmholtz: a rotating set of open models behind an OpenAI-compatible API. This is a
5
+ [Pi](https://pi.dev) provider for it. It discovers the live `alias-*` catalog on every refresh, maps
6
+ Pi's thinking levels onto each backend's own `reasoning_effort` vocabulary, and reports the context
7
+ window the gateway actually enforces. A `models.json` entry cannot do any of those three, because the
8
+ alias set changes without notice and `/v1/models` only has the data at runtime.
9
+
10
+ ## Install
11
+
12
+ ```bash
13
+ pi install npm:pi-blablador
14
+ ```
15
+
16
+ Then `/reload`: `pi --list-models blablador` should list 21 chat models.
17
+
18
+ ## Auth
19
+
20
+ Blablador takes a Helmholtz Codebase personal access token (a GitLab PAT with the `read_user` scope):
21
+
22
+ ```bash
23
+ export BLABLADOR_API_TOKEN=glpat-...
24
+ ```
25
+
26
+ Create one at <https://codebase.helmholtz.cloud/-/user_settings/personal_access_tokens>. **Tokens last
27
+ at most one year** — a sudden 401 is usually this.
28
+
29
+ `/login` works too: pick **Blablador**, paste the key, and it is stored in `~/.pi/agent/auth.json`,
30
+ where it takes precedence over the environment variable. The provider id stays lowercase — `blablador`
31
+ is what `--model blablador/…` and the settings resolve against, `Blablador` is only the label.
32
+ `pi auth check --provider blablador` prints `ready` when a key is resolvable and `not_ready` when not,
33
+ which is the fastest way to tell a missing token from a throttled one.
34
+
35
+ Needs Pi 1.4.0 or newer — the only version this was tested against.
36
+
37
+ ## Thinking levels
38
+
39
+ Every backend has its own `reasoning_effort` vocabulary and answers HTTP 400 for anything outside it,
40
+ so the map is per model family:
41
+
42
+ | family | accepts |
43
+ |---|---|
44
+ | qwen | none \| low \| medium \| xhigh |
45
+ | oss (gpt-oss) | low \| medium \| high |
46
+ | kimi | none \| low \| high \| max |
47
+ | deepseek | none \| low \| high \| xhigh \| max |
48
+ | muse | low \| medium \| high \| xhigh |
49
+ | generic (glm, minimax, mimo, aleph, …) | none \| low \| medium \| high \| xhigh |
50
+ | none (apertus, eve, ocr) | — (the field is never sent) |
51
+
52
+ Pi's own levels are folded onto these, so you always pick from Pi's list: `--thinking high` on a Qwen
53
+ model sends `xhigh`, `--thinking medium` on DeepSeek sends `high`, `--thinking minimal` sends `low`.
54
+
55
+ ## Context windows
56
+
57
+ The context windows the gateway enforces: 1,048,576 for the 1M deployments, 262,144 for the Qwen 3.8,
58
+ Apertus and OCR families, and 131,072 for `alias-fast` and `alias-eve`. Output is capped at 16k
59
+ tokens so reasoning cannot consume the whole answer budget.
60
+
61
+ ## Which models appear
62
+
63
+ `alias-*` ids, plus two verified unaliased ids (`deepseek-v4.1-flash-at-hzdr`, `Swift-Qwen3.8-27b`).
64
+ The alias is the stable handle — JSC's guide says to use it so the model behind it can change. The rest
65
+ of the catalog is either a descriptive deployment name ("90 - Kimi-K3 1M on Juwels Booster"), an
66
+ OpenAI-name shim for the *embedding* endpoint (`gpt-3.5-turbo`, `text-davinci-003`), or a model that
67
+ cannot call tools (`trustllm-*`). Embeddings, rerankers, image/video/voice and the anonymizer are not
68
+ chat models and never appear.
69
+
70
+ The filter is an allowlist (`alias-*` plus those two ids), not a blocklist: of the 27 non-alias entries
71
+ the API returned today, 24 are noise — 16 duplicate "NN - …" deployment names, 3 tool-broken
72
+ `trustllm`, 3 embedding shims, an anonymizer, a whisper and two image generators. The price is that a
73
+ new unaliased chat model stays invisible until it is added here, in a release; the alternative admits
74
+ backends nobody has probed.
75
+
76
+ JSC throttles per account tier, so a long agent loop on a busy alias spends real time in backoff. Pi
77
+ retries 429s on its own; nothing here needs configuring.
78
+
79
+ ## Precedence, and keeping this honest
80
+
81
+ 1. `GET /v1/models` — live catalog, `root`, `max_model_len`, `max_input_tokens`.
82
+ 2. The ceiling probe — for the models the API leaves blank.
83
+ 3. [The model guide](https://sdlaml.pages.jsc.fz-juelich.de/ai/guides/blablador_models/) — prose and
84
+ descriptions. It is a snapshot and can lag the live catalog.
85
+
86
+ A live answer that shrinks below 5 chat aliases is treated as a gateway glitch and ignored — the
87
+ last good list is kept, silently. That is the one thing to know if JSC ever serves a genuinely
88
+ smaller catalog.
89
+
90
+ Do not hardcode aliases in your own code; JSC says they come and go.
91
+
92
+ ## What was actually checked
93
+
94
+ `npm run test:live` drives the real CLI against the live API and asserts on the `--mode json` event
95
+ stream: the checklist from [pi's custom-provider
96
+ guide](https://pi.dev/docs/latest/custom-provider). `--list` shows the groups without calling anything,
97
+ and a partial name runs one: `npm run test:live overflow`. `npm test` needs no token and no network —
98
+ it pins the pi-side mapping (picker names, the effort map under pi's level names, the offline catalog
99
+ shape) plus the one spawn behaviour that cannot be waited out live: `pi` ignoring the interrupt. The
100
+ shared rules (family patterns, effort vocabularies, live merge, token trimming) are pinned by
101
+ blablador-core, the catalog package this provider depends on; its own live contract test (`npm run test:live` there) is the check that runs straight
102
+ against `/v1/models`. CI runs the offline suites on every push, and a weekly job runs the live ones
103
+ when the token secret is set. Before a release, `npm run test:all` runs both halves. Last full live
104
+ run: 14/14.
105
+
106
+ | | |
107
+ |---|---|
108
+ | ordinary text, usage and cost | ✅ `in=2482 out=20 cost=0` |
109
+ | thinking level on `alias-code` | ✅ `--thinking high` passes, reasoning comes back (qwen got `xhigh`) |
110
+ | tool call, empty assistant text, tool result | ✅ turn stops with `toolUse` and no text |
111
+ | image input on `alias-code` | ✅ answers "Red" for a red PNG |
112
+ | unicode round-trip | ✅ `🐍 Ω 你好 café é` |
113
+ | context overflow | ✅ recognised, `compaction_start` then `compaction_end` |
114
+ | abort | ✅ exits on SIGINT, no hard kill needed |
115
+ | abort, when the interrupt is ignored | ✅ offline against a stub: SIGINT → SIGKILL, `hard_kill=true` |
116
+ | catalog | ✅ 21 models listed, `thinking` column right for qwen, gpt-oss and eve |
117
+
118
+ Deliberately not covered: malformed or partial streams (they need a mock server and live in pi-ai's
119
+ stream code, which this extension does not touch), cross-provider session handoff (needs a second
120
+ provider), and the offline/partial-catalog path — where `/v1/models` omits a `root` and the merge from
121
+ the table is the only thing that keeps a Qwen on its own effort map. The hard-kill test proves the
122
+ escalation *mechanism* with a 300ms grace; the shipped 30s value is a judgement call about 429
123
+ backoff, not a measured number. One failure mode belongs to pi rather than to this extension: when the
124
+ overflow cannot be compacted away — a single attachment larger than the window — pi exits 0 having
125
+ printed nothing.
126
+
127
+ ## Maintaining it
128
+
129
+ **Re-measure a window.** `/v1/models` leaves `max_model_len` blank for most aliases, so the bundled
130
+ windows are measured values, not guide numbers; re-measure them when a deployment changes.
131
+
132
+ **Two things look like bugs and are not.** The refresh merges `root`/`max_model_len` from the offline
133
+ table because the live catalog omits them, and it can only add, never overwrite — dropping that reverts
134
+ Qwen models to the `generic` effort map, which they answer with HTTP 400. Same for the family match: it
135
+ reads `root`, because `alias-code` is a Qwen whose id never says so. blablador-core's tests pin both, and
136
+ the live `thinking` group asks `alias-code` for `--thinking high`, which only succeeds if the family map
137
+ translated it to `xhigh`. The merge from the table is the half neither can reach: it only happens when
138
+ `/v1/models` leaves a `root` out, which needs a mock server (see "What was actually checked"). When a
139
+ new alias 400s on every
140
+ thinking level, it has an unfamiliar effort vocabulary: add a family pattern to `FAMILY` and an entry to
141
+ `EFFORT` in blablador-core — there is no runtime detection.
142
+
143
+ **Shared with OpenCode.** The catalog list, family/effort maps, live `/v1/models` merge and token
144
+ trimming live in blablador-core; `blablador.ts` is the thin pi adapter over it (refresh TTL, `force`/`allowNetwork`, last-good
145
+ retention, pi's `off` level name). Change the rules there, never here — opencode-blablador reads
146
+ the same rules and must not drift. Both packages live in this monorepo, so a root `npm install`
147
+ links the core (no symlinks); publish order when the rules change: blablador-core first, then
148
+ this package, pins bumped in the same commit.
149
+
150
+ **Publishing.** `npm publish` runs `prepublishOnly` — typecheck plus `npm test` — and refuses to ship
151
+ on a failure. It ships `blablador-core` as a real dependency, so publish the core first. CI runs the
152
+ same checks without a token, on purpose: the live suite costs real API calls,
153
+ so a Blablador-side change (a new effort vocabulary, a renamed alias, a shrunken catalog) is caught by
154
+ the weekly live job (or by someone running `npm run test:live`), not by a per-push robot. Tag the
155
+ commit you publish, not an earlier one.
156
+
157
+ Publishing an unscoped name puts `blablador.ts` in a public registry: readable by anyone, cached by
158
+ mirrors, and not really withdrawn by `npm unpublish`. The repo being private does not contain it.
159
+
160
+ MIT licensed.
package/blablador.ts ADDED
@@ -0,0 +1,115 @@
1
+ /**
2
+ * Blablador (Helmholtz / JSC): live `alias-*` discovery + per-family thinking effort.
3
+ *
4
+ * Why an extension and not only models.json: /v1/models carries no capability metadata and the
5
+ * JSC guide says the alias set "comes and goes without notice", so the list is fetched live.
6
+ * The catalog itself (fallback list, family/effort maps, live merge, token trimming) is shared
7
+ * with opencode-blablador through blablador-core; this file is the pi-side adapter and keeps the
8
+ * policy that is pi-specific: refresh TTL, force/allowNetwork handling, last-good retention.
9
+ * Guide: https://sdlaml.pages.jsc.fz-juelich.de/ai/guides/blablador_api_access/
10
+ *
11
+ * Auth: BLABLADOR_API_TOKEN (or /login blablador once a credential is stored for the provider).
12
+ */
13
+ import type { ExtensionAPI, ProviderModelConfig } from "@earendil-works/pi-coding-agent";
14
+ import {
15
+ BASE_URL,
16
+ EFFORT,
17
+ FALLBACK_MODELS,
18
+ TOKEN_ENV,
19
+ VISION,
20
+ displayName,
21
+ familyOf,
22
+ fetchLiveModels,
23
+ outputCap,
24
+ resolveToken,
25
+ type CatalogModel,
26
+ } from "blablador-core";
27
+
28
+ export { FALLBACK_MODELS, MIN_CATALOG, NOT_CHAT } from "blablador-core";
29
+
30
+ // Reuse a fetched catalog for a while: pi refreshes models on extension registration, on /model
31
+ // selector open and on credential changes, and each refresh would otherwise hit /v1/models again.
32
+ // The selector's manual refresh and `pi update` pass force:true, which bypasses this.
33
+ const REFRESH_TTL_MS = 10 * 60 * 1000;
34
+
35
+ // pi's own level names. blablador-core spells the no-reasoning level "none" (OpenCode sends it as
36
+ // reasoning_effort "none"); pi calls the same level "off", so the key is remapped on the way in.
37
+ type Level = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
38
+
39
+ function thinkingLevelMap(id: string, root: string | null): Partial<Record<Level, string>> | undefined {
40
+ const effort = EFFORT[familyOf(id, root)];
41
+ if (!effort) return undefined; // no reasoning, and the field risks a 400 (README "Thinking levels")
42
+ const map: Partial<Record<Level, string>> = {};
43
+ for (const [level, value] of Object.entries(effort)) {
44
+ if (level === "none") map.off = value;
45
+ else map[level as Level] = value;
46
+ }
47
+ return map;
48
+ }
49
+
50
+ function chatModel(model: CatalogModel): ProviderModelConfig {
51
+ const effort = EFFORT[familyOf(model.id, model.root)];
52
+ return {
53
+ id: model.id,
54
+ name: displayName(model),
55
+ api: "openai-completions",
56
+ reasoning: effort !== null,
57
+ input: VISION.has(model.id) ? ["text", "image"] : ["text"],
58
+ // Free research API; a real rate card would make /usage meaningful.
59
+ cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
60
+ contextWindow: model.contextWindow,
61
+ // Reasoning shares the output budget; outputCap keeps the prompt room inside the window
62
+ // even if the gateway ever reports one smaller than the ceiling (README "Context windows").
63
+ maxTokens: outputCap(model.contextWindow),
64
+ thinkingLevelMap: thinkingLevelMap(model.id, model.root),
65
+ };
66
+ }
67
+
68
+ export function buildModels(catalog: readonly CatalogModel[]): ProviderModelConfig[] {
69
+ return catalog.map(chatModel);
70
+ }
71
+
72
+ export default function blablador(pi: ExtensionAPI): void {
73
+ // pi interpolates "$BLABLADOR_API_TOKEN" into the Authorization header verbatim, so a key
74
+ // pasted with surrounding whitespace 401s every request. The extension shares the CLI process,
75
+ // so normalizing the variable once here covers inference; resolveToken covers discovery.
76
+ const rawEnvToken = process.env[TOKEN_ENV];
77
+ if (rawEnvToken) process.env[TOKEN_ENV] = rawEnvToken.trim();
78
+
79
+ let fetchedAt = 0;
80
+ let models = buildModels(FALLBACK_MODELS);
81
+
82
+ // Registered by name with the legacy ProviderConfig form, not a complete `Provider`. The guide
83
+ // prefers the object form for integrations that own more than static endpoint and model metadata,
84
+ // but its own example (custom-provider-gitlab-duo) registers by name too, and the object form is
85
+ // where pi's built-in providers live: it expects auth resolution, publish-based refresh and a
86
+ // stream delegate to be written out, none of which this needs. The only dynamic part here is the
87
+ // catalog, which refreshModels covers. promptCache stays unset because Blablador returns no
88
+ // prompt_tokens_details at all, so there is no cache to keep warm.
89
+ pi.registerProvider("blablador", {
90
+ name: "Blablador",
91
+ baseUrl: BASE_URL,
92
+ apiKey: `$${TOKEN_ENV}`,
93
+ api: "openai-completions",
94
+ models,
95
+ async refreshModels(context) {
96
+ if (fetchedAt && Date.now() - fetchedAt < REFRESH_TTL_MS && !context.force) return models;
97
+ if (!context.allowNetwork || context.signal.aborted) return models;
98
+ // resolveToken trims both paths: a key pasted with whitespace is exactly what the
99
+ // gateway 401s on, and the stored credential wins over the env var, matching how pi
100
+ // picks auth. fetchLiveModels enforces MIN_CATALOG, so a shrunken gateway answer
101
+ // lands in the catch and the last good list survives (README "Which models appear").
102
+ const token = resolveToken(context.credential, process.env[TOKEN_ENV]);
103
+ if (!token) return models;
104
+ try {
105
+ models = buildModels(await fetchLiveModels(token, context.signal));
106
+ fetchedAt = Date.now();
107
+ } catch (error) {
108
+ if (!context.signal.aborted) {
109
+ console.error(`blablador: keeping ${models.length} cached models, /v1/models failed:`, error);
110
+ }
111
+ }
112
+ return models;
113
+ },
114
+ });
115
+ }
package/package.json CHANGED
@@ -1,6 +1,50 @@
1
1
  {
2
- "name": "pi-blablador",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
2
+ "name": "pi-blablador",
3
+ "version": "0.1.1",
4
+ "description": "Blablador (Helmholtz / JSC) provider for Pi: live alias discovery, per-family thinking effort, measured context windows",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "keywords": [
8
+ "pi-package",
9
+ "blablador",
10
+ "provider",
11
+ "helmholtz",
12
+ "jsc",
13
+ "openai-compatible"
14
+ ],
15
+ "files": [
16
+ "blablador.ts",
17
+ "README.md",
18
+ "LICENSE"
19
+ ],
20
+ "pi": {
21
+ "extensions": [
22
+ "./blablador.ts"
23
+ ]
24
+ },
25
+ "peerDependencies": {
26
+ "@earendil-works/pi-coding-agent": ">=1.4.0 <2.0.0"
27
+ },
28
+ "peerDependenciesMeta": {
29
+ "@earendil-works/pi-coding-agent": {
30
+ "optional": true
31
+ }
32
+ },
33
+ "engines": {
34
+ "node": ">=22.18.0"
35
+ },
36
+ "dependencies": {
37
+ "blablador-core": "0.1.1"
38
+ },
39
+ "scripts": {
40
+ "test": "node --test \"test/**/*.test.mjs\"",
41
+ "test:live": "node test/behaviour.mjs",
42
+ "test:all": "npm test && npm run test:live",
43
+ "typecheck": "tsc --noEmit",
44
+ "prepublishOnly": "npm run typecheck && npm test"
45
+ },
46
+ "devDependencies": {
47
+ "@earendil-works/pi-coding-agent": "^1.4.0",
48
+ "typescript": "^7.0.2"
49
+ }
50
+ }