@plurnk/plurnk-providers 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PossumTech Laboratories
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,18 @@
+# plurnk-providers
+
+Framework + contract for `@plurnk/plurnk-providers-*` sibling packages (LLM transports + tokenizer + cost accounting). Consumed by [plurnk-service](https://github.com/plurnk/plurnk-service).
+
+## Documentation
+
+- [`SPEC.md`](./SPEC.md) — author-facing contract for sibling implementers.
+- Constellation: [plurnk-grammar](https://github.com/plurnk/plurnk-grammar) (HEREDOC + AST), [plurnk-mimetypes](https://github.com/plurnk/plurnk-mimetypes), [plurnk-schemes](https://github.com/plurnk/plurnk-schemes), [plurnk-execs](https://github.com/plurnk/plurnk-execs).
+
+## Exports
+
+- `Provider`, `ChatMessage`, `ProviderResponse`, `ProviderAssistant`, `ProviderUsage`, `ProviderFactory` — types.
+- `parseAliasesFromEnv`, `resolveActiveAlias`, `instantiateProvider`, `loadActiveProvider` — alias-cascade resolution and provider instantiation.
+- `Mock` — reference implementation + test fixture (dual-purpose).
+
+## Tests
+
+`test:lint`, `test:unit`.

package/SPEC.md

@@ -0,0 +1,182 @@
+# plurnk-providers — Specification
+
+Contract for `@plurnk/plurnk-providers-*` sibling packages. Audience: implementer of an LLM transport. Consumer: [plurnk-service](https://github.com/plurnk/plurnk-service) (SPEC.md §2).
+
+## §1 Manifest
+
+Each provider package's `package.json`:
+
+```json
+{
+    "name": "@plurnk/plurnk-providers-<name>",
+    "plurnk": { "kind": "provider", "name": "<name>" }
+}
+```
+
+- `kind` MUST be `"provider"`.
+- `name` is a vendor identifier (`openai`, `anthropic`, `ollama`).
+
+Collision on `(kind: "provider", name)` at discovery: fail-hard.
+
+## §2 Provider interface
+
+```ts
+interface Provider {
+    // Identity (immutable across lifetime)
+    readonly contextSize: number | null;  // total context tokens, null if unresolved
+    readonly model: string;                // configured model id
+
+    // Tokenomic primitives (synchronous, pure)
+    countTokens(text: string): number;
+    costFor(usage: ProviderUsage): number;  // pico-USD (1e-12 USD)
+
+    // Transport
+    generate(args: { messages: ChatMessage[]; signal?: AbortSignal }): Promise<ProviderResponse>;
+}
+
+interface ProviderResponse {
+    assistant: {
+        content: string;            // raw model emission; consumer parses
+        reasoning: string | null;   // wire-reported CoT; null if absent
+        usage: ProviderUsage;       // { prompt, completion, cached, total }
+        finishReason: "stop" | "length" | "tool_calls" | "content_filter" | null;
+        model: string;              // wire-reported (may differ from requested for relay providers)
+    };
+    assistantRaw: unknown;          // verbatim wire response for forensics
+}
+
+interface ProviderUsage {
+    prompt: number;
+    completion: number;
+    cached: number;
+    total: number;
+}
+```
+
+### Promises
+
+- `assistant.content` is the **verbatim** model emission. Consumer parses via `@plurnk/plurnk-grammar` — providers MUST NOT parse. Native tool-call outputs (OpenAI function calls, Anthropic tool_use) MUST be normalized back to plurnk DSL string at the provider boundary.
+- `assistant.usage` is authoritative. Fill `0`s when the wire response omits a breakdown.
+- `countTokens` is **synchronous**, returns a non-negative integer, deterministic for the same input.
+- `costFor` is **pure**, returns pico-USD non-negative integer. Returns `0` for siblings with no known rates (local Ollama, generic OpenAI-compat shims).
+- `contextSize` resolves to `null` when provider can't determine the model's context window. Consumer treats null as "no budget info available."
+- `generate` rejects on signal abort — does NOT resolve with partial content.
+
+## §3 `fromEnv(env, model)` factory
+
+Default export MUST have a static `fromEnv(env, model)` factory:
+
+```ts
+class OpenAI {
+    static fromEnv(env: NodeJS.ProcessEnv, model: string): OpenAI | Promise<OpenAI> {
+        // Read provider-specific env (OPENAI_BASE_URL, OPENAI_API_KEY, ...)
+        // plus universal operator knobs (PLURNK_REASON, PLURNK_FETCH_TIMEOUT,
+        // PLURNK_PROVIDER_CONTEXT_SIZE).
+        return new OpenAI({ /* ... */ });
+    }
+    constructor(config: OpenAIConfig) { /* ... */ }
+}
+```
+
+The framework's `instantiateProvider` calls `mod.default.fromEnv(env, alias.model)` generically.
+
+`fromEnv` MAY be sync or async; return type `Provider | Promise<Provider>`.
+
+`fromEnv` MUST fail fast with a clear error if required env is missing — name the env var the operator needs to set.
+
+## §4 Universal operator knobs
+
+Each provider's `fromEnv` reads these:
+
+- **`PLURNK_REASON`** — engine-level reasoning-token budget. Non-negative integer. Providers translate to wire format: OpenAI o-series → `reasoning_effort: low|medium|high|disabled`; llama-server / Ollama OpenAI-compat → `think: true|false`; Anthropic → `thinking: { type: "enabled", budget_tokens: n }`.
+- **`PLURNK_FETCH_TIMEOUT`** — service-wide ms ceiling on any single outbound request. Each `fromEnv` reads and passes as `AbortSignal.timeout`. Per-provider override envs are NOT part of the contract.
+- **`PLURNK_PROVIDER_CONTEXT_SIZE`** — optional positive-integer override for the model's reported context window. Resolution: this env var → provider probe/config/table → `null`.
+
+## §5 Alias cascade resolution
+
+`PLURNK_MODEL_<alias>=<provider>/<model-id>` declares an alias; `PLURNK_MODEL=<alias>` selects which is active.
+
+```
+PLURNK_MODEL_gemma=openai/macher.gguf
+PLURNK_MODEL_opus=openrouter/anthropic/claude-opus-latest
+PLURNK_MODEL=gemma
+```
+
+First path segment names the provider plugin (`@plurnk/plurnk-providers-<provider>`); rest is the model identifier (may contain `/` for tri-level providers like openrouter's `publisher/model`).
+
+Framework helpers (`./ProviderRegistry.ts`):
+
+- `parseAliasesFromEnv(env)` — extracts alias entries.
+- `resolveActiveAlias(env)` — `{ alias, provider, model } | null`.
+- `instantiateProvider(alias, env)` — dynamic-imports `@plurnk/plurnk-providers-<provider>` and calls `fromEnv(env, model)`.
+- `loadActiveProvider(env)` — resolve + instantiate in one call.
+
+## §6 Engine → provider guarantees (consumer side)
+
+- `messages` is a complete prompt. Consumer has pre-assembled all sections. Provider does not add or reorder.
+- `signal` is wired to the run's AbortController.
+- `generate` is single-call per turn. No parallel calls on the same instance.
+- `assistantRaw` is opaque to the consumer (forensics-only).
+- `countTokens` is cheap by contract; consumer calls frequently.
+
+## §7 Provider → engine guarantees
+
+- **No DB access.** Provider never touches `node:sqlite` or storage layers.
+- **No service access.** No imports from `@plurnk/plurnk-service`.
+- **No grammar runtime dep.** Type-imports from `@plurnk/plurnk-grammar` are fine; invoking `PlurnkParser.parse` is consumer-side.
+- **Raw `content`.** Native tool-call outputs MUST be normalized back to plurnk DSL string.
+- **Atomic.** One `generate` call resolves with one complete `ProviderResponse`. No streaming partial resolves (v0).
+- **Honors `signal`.** Aborted calls reject; resources free; no orphaned connections.
+- **Single model.** One provider instance speaks to one model.
+- **Synchronous `countTokens`, pure `costFor`.** No I/O, no async, no state beyond cached tokenizer artifacts.
+
+## §8 Forbidden
+
+| ❌ |
+|---|
+| Database access |
+| Filesystem access beyond reading provider-internal config |
+| Imports from `@plurnk/plurnk-service/*` |
+| Resolving with partial content on abort |
+| Mutating `messages` |
+| Parsing `content` into `PlurnkStatement[]` |
+| Streaming the resolve (atomic only; v0) |
+| Holding state across `generate` calls beyond connection pooling and config |
+| Reading model output via `console.*` |
+| Ignoring `signal` |
+| Spawning subprocesses for inference |
+
+## §9 Reference — `Mock`
+
+`./src/Mock.ts` — test-fixture provider + worked example. Queue of pre-built responses; `generate` shifts one off.
+
+```ts
+import { Mock } from "@plurnk/plurnk-providers";
+
+const mock = new Mock({
+    contextSize: 100000,
+    responses: [{ assistant: { content: "<<SEND[200]:hi:SEND", reasoning: null } }],
+});
+const result = await mock.generate({ messages: [] });
+```
+
+`MockResponse.assistant.ops?: PlurnkStatement[]` is a pre-parsed escape hatch consumed by plurnk-service intg tests (skips parse roundtrip). Production providers don't expose `ops`.
+
+## §10 Conformance
+
+A sibling package satisfies the contract when:
+
+1. Default export is a class with `static fromEnv(env, model)` factory.
+2. Instance exposes `contextSize: number | null` and `model: string` (non-empty).
+3. Instance exposes `countTokens(text): number` and `costFor(usage): number`.
+4. `countTokens("")` returns `0`; `countTokens("…")` returns a non-negative integer.
+5. `costFor({prompt:0,completion:0,cached:0,total:0})` returns `0` (or non-negative pico-USD for non-free models).
+6. Identity getters return stable values across reads.
+7. `generate` resolves with a valid `ProviderResponse` shape.
+8. `generate` invoked with a pre-aborted `signal` rejects without making a wire call.
+9. `generate` invoked, then aborted mid-flight rejects within ≤5s; no connection leak.
+10. `assistantRaw` is present (any value, including `null`).
+11. No DB access, no imports from `@plurnk/plurnk-service`.
+12. No runtime import of `@plurnk/plurnk-grammar` parser entry points.
+
+Sibling-specific behavioral tests (wire-format compliance, model-family quirks, retry logic) live in each package's own test surface.

package/dist/Mock.d.ts

@@ -0,0 +1,39 @@
+import type { PlurnkStatement } from "@plurnk/plurnk-grammar";
+import type { ChatMessage, Provider, ProviderAssistant, ProviderUsage } from "./types.ts";
+export type MockAssistant = {
+    content: string;
+    reasoning: string | null;
+    usage?: ProviderUsage;
+    finishReason?: string | null;
+    model?: string;
+    ops?: PlurnkStatement[];
+};
+export type MockResponse = {
+    assistant: MockAssistant;
+    assistantRaw?: unknown;
+};
+export type MockReturnedAssistant = ProviderAssistant & {
+    ops?: PlurnkStatement[];
+};
+declare const DEFAULT_USAGE: ProviderUsage;
+export default class Mock implements Provider {
+    #private;
+    constructor({ contextSize, responses }: {
+        contextSize: number | null;
+        responses: MockResponse[];
+    });
+    get contextSize(): number | null;
+    get model(): string;
+    countTokens(text: string): number;
+    costFor(_usage: ProviderUsage): number;
+    generate(_: {
+        messages: ChatMessage[];
+        signal?: AbortSignal;
+    }): Promise<{
+        assistant: MockReturnedAssistant;
+        assistantRaw: unknown;
+    }>;
+    get remaining(): number;
+}
+export { DEFAULT_USAGE as mockDefaultUsage };
+//# sourceMappingURL=Mock.d.ts.map

package/dist/Mock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Mock.d.ts","sourceRoot":"","sources":["../src/Mock.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE1F,MAAM,MAAM,aAAa,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,GAAG,CAAC,EAAE,eAAe,EAAE,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACvB,SAAS,EAAE,aAAa,CAAC;IACzB,YAAY,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAGF,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,GAAG;IAAE,GAAG,CAAC,EAAE,eAAe,EAAE,CAAA;CAAE,CAAC;AAEpF,QAAA,MAAM,aAAa,EAAE,aAAiE,CAAC;AAEvF,MAAM,CAAC,OAAO,OAAO,IAAK,YAAW,QAAQ;;gBAI7B,EAAE,WAAW,EAAE,SAAS,EAAE,EAAE;QAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,SAAS,EAAE,YAAY,EAAE,CAAA;KAAE;IAKjG,IAAI,WAAW,IAAI,MAAM,GAAG,IAAI,CAA8B;IAC9D,IAAI,KAAK,IAAI,MAAM,CAAmB;IAItC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAKjC,OAAO,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM;IAEhC,QAAQ,CAAC,CAAC,EAAE;QAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,qBAAqB,CAAC;QAAC,YAAY,EAAE,OAAO,CAAA;KAAE,CAAC;IAe1I,IAAI,SAAS,IAAI,MAAM,CAA+B;CACzD;AAED,OAAO,EAAE,aAAa,IAAI,gBAAgB,EAAE,CAAC"}

package/dist/Mock.js

@@ -0,0 +1,42 @@
+// Mock provider — reference implementation + test fixture.
+//
+// Dual purpose: (a) plurnk-service intg suite uses it for deterministic
+// engine tests; (b) worked example for sibling authors implementing the
+// Provider contract. Production providers don't expose the `ops` escape
+// hatch — that's an intg-only convenience.
+const DEFAULT_USAGE = { prompt: 0, completion: 0, cached: 0, total: 0 };
+export default class Mock {
+    #contextSize;
+    #queue;
+    constructor({ contextSize, responses }) {
+        this.#contextSize = contextSize;
+        this.#queue = [...responses];
+    }
+    get contextSize() { return this.#contextSize; }
+    get model() { return "mock"; }
+    // Heuristic tokenizer. Mock is test-only; real provider siblings ship
+    // family-specific tokenizers.
+    countTokens(text) {
+        return text.length === 0 ? 0 : Math.ceil(text.length / 4);
+    }
+    // Mock is free.
+    costFor(_usage) { return 0; }
+    async generate(_) {
+        const next = this.#queue.shift();
+        if (next === undefined)
+            throw new Error("Mock provider exhausted: no more queued responses");
+        const a = next.assistant;
+        const assistant = {
+            content: a.content,
+            reasoning: a.reasoning,
+            usage: a.usage ?? DEFAULT_USAGE,
+            finishReason: a.finishReason ?? "stop",
+            model: a.model ?? "mock",
+            ...(a.ops !== undefined ? { ops: a.ops } : {}),
+        };
+        return { assistant, assistantRaw: next.assistantRaw ?? null };
+    }
+    get remaining() { return this.#queue.length; }
+}
+export { DEFAULT_USAGE as mockDefaultUsage };
+//# sourceMappingURL=Mock.js.map

package/dist/Mock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Mock.js","sourceRoot":"","sources":["../src/Mock.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,EAAE;AACF,wEAAwE;AACxE,wEAAwE;AACxE,wEAAwE;AACxE,2CAA2C;AAwB3C,MAAM,aAAa,GAAkB,EAAE,MAAM,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;AAEvF,MAAM,CAAC,OAAO,OAAO,IAAI;IACrB,YAAY,CAAgB;IAC5B,MAAM,CAAiB;IAEvB,YAAY,EAAE,WAAW,EAAE,SAAS,EAA6D;QAC7F,IAAI,CAAC,YAAY,GAAG,WAAW,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC;IACjC,CAAC;IAED,IAAI,WAAW,KAAoB,OAAO,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC;IAC9D,IAAI,KAAK,KAAa,OAAO,MAAM,CAAC,CAAC,CAAC;IAEtC,sEAAsE;IACtE,8BAA8B;IAC9B,WAAW,CAAC,IAAY;QACpB,OAAO,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED,gBAAgB;IAChB,OAAO,CAAC,MAAqB,IAAY,OAAO,CAAC,CAAC,CAAC,CAAC;IAEpD,KAAK,CAAC,QAAQ,CAAC,CAAoD;QAC/D,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACjC,IAAI,IAAI,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;QAC7F,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC;QACzB,MAAM,SAAS,GAA0B;YACrC,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,aAAa;YAC/B,YAAY,EAAE,CAAC,CAAC,YAAY,IAAI,MAAM;YACtC,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,MAAM;YACxB,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACjD,CAAC;QACF,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,IAAI,EAAE,CAAC;IAClE,CAAC;IAED,IAAI,SAAS,KAAa,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;CACzD;AAED,OAAO,EAAE,aAAa,IAAI,gBAAgB,EAAE,CAAC"}

package/dist/ProviderRegistry.d.ts

@@ -0,0 +1,4 @@
+import type { ProviderAlias } from "./types.ts";
+export declare const parseAliasesFromEnv: (env?: NodeJS.ProcessEnv) => ProviderAlias[];
+export declare const resolveActiveAlias: (env?: NodeJS.ProcessEnv) => ProviderAlias | null;
+//# sourceMappingURL=ProviderRegistry.d.ts.map

package/dist/ProviderRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProviderRegistry.d.ts","sourceRoot":"","sources":["../src/ProviderRegistry.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,eAAO,MAAM,mBAAmB,GAAI,MAAK,MAAM,CAAC,UAAwB,KAAG,aAAa,EAgBvF,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,MAAK,MAAM,CAAC,UAAwB,KAAG,aAAa,GAAG,IAKzF,CAAC"}

package/dist/ProviderRegistry.js

@@ -0,0 +1,38 @@
+// Model alias resolution. Reads PLURNK_MODEL_<alias>=<provider>/<model>
+// env vars; PLURNK_MODEL=<alias> selects which is active at boot.
+//
+// `instantiateProvider` and `loadActiveProvider` (the dynamic-import path)
+// live in the consumer (plurnk-service) because Node's `import()` resolves
+// package specifiers relative to the calling module's location; the
+// consumer is the package that actually has the `@plurnk/plurnk-providers-*`
+// sibling installed in its node_modules. This module ships only the pure
+// env-parsing helpers.
+export const parseAliasesFromEnv = (env = process.env) => {
+    const out = [];
+    for (const [key, value] of Object.entries(env)) {
+        if (value === undefined || value.length === 0)
+            continue;
+        if (!key.startsWith("PLURNK_MODEL_"))
+            continue;
+        const aliasRaw = key.slice("PLURNK_MODEL_".length);
+        if (aliasRaw.length === 0)
+            continue;
+        const slash = value.indexOf("/");
+        if (slash <= 0)
+            continue;
+        out.push({
+            alias: aliasRaw.toLowerCase(),
+            provider: value.slice(0, slash),
+            model: value.slice(slash + 1),
+        });
+    }
+    return out;
+};
+export const resolveActiveAlias = (env = process.env) => {
+    const selected = env.PLURNK_MODEL;
+    if (selected === undefined || selected.length === 0)
+        return null;
+    const aliases = parseAliasesFromEnv(env);
+    return aliases.find((a) => a.alias === selected.toLowerCase()) ?? null;
+};
+//# sourceMappingURL=ProviderRegistry.js.map

package/dist/ProviderRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProviderRegistry.js","sourceRoot":"","sources":["../src/ProviderRegistry.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,kEAAkE;AAClE,EAAE;AACF,2EAA2E;AAC3E,2EAA2E;AAC3E,oEAAoE;AACpE,6EAA6E;AAC7E,yEAAyE;AACzE,uBAAuB;AAIvB,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,MAAyB,OAAO,CAAC,GAAG,EAAmB,EAAE;IACzF,MAAM,GAAG,GAAoB,EAAE,CAAC;IAChC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7C,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACxD,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,eAAe,CAAC;YAAE,SAAS;QAC/C,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;QACnD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACpC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,KAAK,IAAI,CAAC;YAAE,SAAS;QACzB,GAAG,CAAC,IAAI,CAAC;YACL,KAAK,EAAE,QAAQ,CAAC,WAAW,EAAE;YAC7B,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC;YAC/B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC;SAChC,CAAC,CAAC;IACP,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,MAAyB,OAAO,CAAC,GAAG,EAAwB,EAAE;IAC7F,MAAM,QAAQ,GAAG,GAAG,CAAC,YAAY,CAAC;IAClC,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACjE,MAAM,OAAO,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC;IACzC,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,IAAI,CAAC;AAC3E,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { ChatMessage, Provider, ProviderAlias, ProviderAssistant, ProviderFactory, ProviderResponse, ProviderUsage, } from "./types.ts";
+export { parseAliasesFromEnv, resolveActiveAlias, } from "./ProviderRegistry.ts";
+export { default as Mock } from "./Mock.ts";
+export type { MockAssistant, MockResponse, MockReturnedAssistant } from "./Mock.ts";
+export { mockDefaultUsage } from "./Mock.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACR,WAAW,EACX,QAAQ,EACR,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,aAAa,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACH,mBAAmB,EACnB,kBAAkB,GACrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,WAAW,CAAC;AAC5C,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AACpF,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { parseAliasesFromEnv, resolveActiveAlias, } from "./ProviderRegistry.js";
+export { default as Mock } from "./Mock.js";
+export { mockDefaultUsage } from "./Mock.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,EACH,mBAAmB,EACnB,kBAAkB,GACrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,WAAW,CAAC;AAE5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,40 @@
+export interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+export interface ProviderUsage {
+    readonly prompt: number;
+    readonly completion: number;
+    readonly cached: number;
+    readonly total: number;
+}
+export interface ProviderAssistant {
+    readonly content: string;
+    readonly reasoning: string | null;
+    readonly usage: ProviderUsage;
+    readonly finishReason: string | null;
+    readonly model: string;
+}
+export interface ProviderResponse {
+    readonly assistant: ProviderAssistant;
+    readonly assistantRaw: unknown;
+}
+export interface Provider {
+    generate(args: {
+        messages: ChatMessage[];
+        signal?: AbortSignal;
+    }): Promise<ProviderResponse>;
+    readonly contextSize: number | null;
+    readonly model: string;
+    countTokens(text: string): number;
+    costFor(usage: ProviderUsage): number;
+}
+export interface ProviderAlias {
+    readonly alias: string;
+    readonly provider: string;
+    readonly model: string;
+}
+export interface ProviderFactory {
+    fromEnv(env: NodeJS.ProcessEnv, model: string): Provider | Promise<Provider>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,QAAQ;IACrB,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAI7F,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAGlC,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAAC;CACzC;AAED,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CAC1B;AAMD,MAAM,WAAW,eAAe;IAC5B,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAChF"}

package/dist/types.js

@@ -0,0 +1,5 @@
+// Provider transport contract. Providers return raw wire-level output —
+// content unparsed (consumer parses via @plurnk/plurnk-grammar), reasoning
+// is the wire-reported CoT only.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,2EAA2E;AAC3E,iCAAiC"}

package/package.json

@@ -0,0 +1,51 @@
+{
+    "name": "@plurnk/plurnk-providers",
+    "version": "0.1.0",
+    "description": "Framework + contract for the @plurnk/plurnk-providers-* LLM transport family.",
+    "keywords": ["plurnk", "llm", "provider", "tokenizer"],
+    "homepage": "https://github.com/plurnk/plurnk-providers#readme",
+    "bugs": {
+        "url": "https://github.com/plurnk/plurnk-providers/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/plurnk/plurnk-providers.git"
+    },
+    "engines": {
+        "node": ">=25"
+    },
+    "license": "MIT",
+    "author": "@wikitopian",
+    "type": "module",
+    "publishConfig": {
+        "access": "public"
+    },
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist/**/*",
+        "README.md",
+        "SPEC.md"
+    ],
+    "scripts": {
+        "test:lint": "tsc --noEmit",
+        "test:unit": "node --test src/**/*.test.ts",
+        "test": "npm run test:lint && npm run test:unit",
+        "build:dist": "tsc -p tsconfig.build.json",
+        "build": "npm run build:dist",
+        "prepare": "npm run build"
+    },
+    "peerDependencies": {
+        "@plurnk/plurnk-grammar": "^0.15.0"
+    },
+    "devDependencies": {
+        "@plurnk/plurnk-grammar": "^0.15.0",
+        "@types/node": "^25.8.0",
+        "typescript": "^6.0.3"
+    }
+}