@plumbus/core 0.8.0-beta.5 → 0.8.0-beta.7

package/instructions/ai-classification.md

@@ -0,0 +1,114 @@
+# AI classification: provider and model selection
+
+Read this when implementing classification, categorization, label selection, or
+TypeSafe/Jev and Laya integration. Requires **@plumbus/core 0.7.4+** (0.8 family: **0.8.0-beta.6+**) for the
+`classify()` provider/model options. Use this recipe inside Plumbus capabilities
+and flows; preserve their access policies and declare `effects.ai: true`.
+
+## Choose the operation
+
+| Need | Operation |
+| --- | --- |
+| Matching labels from a known list, using a generative or decision model | `ctx.ai.classify()` → `string[]` |
+| Typed choices, ordinal scores, probabilities, or mixed questions | `ctx.ai.decide()` → typed answers |
+| Generated text or structured output from a prompt | `ctx.ai.generate()` |
+
+Do not call vendor adapters directly for application business logic. Both native
+classification and decisions use core validation, security, budgets, identity,
+cancellation, and accounting. Predictions never replace authorization.
+
+## Register the provider
+
+Install only the decision provider needed by the app:
+
+```bash
+pnpm add @plumbus/core@~0.7.4 @plumbus/ai-decision-typesafe@~0.2.2
+# For self-hosted Laya, use @plumbus/ai-decision-laya@~0.2.2 instead.
+# 0.8 beta family: pnpm add @plumbus/core@plumbus-next @plumbus/ai-decision-typesafe@plumbus-next
+```
+
+Export registration at the server boundary so API and workers share it:
+
+```ts
+// app/server.ts
+import { createTypeSafeDecisionAdapter } from '@plumbus/ai-decision-typesafe';
+
+export const decisions = {
+  providers: {
+    typesafe: createTypeSafeDecisionAdapter({
+      apiKey: process.env.TYPESAFE_API_KEY ?? '',
+      model: 'jev-1.13.0',
+    }),
+  },
+  defaultProvider: 'typesafe',
+};
+```
+
+For Laya, register `laya: createLayaDecisionAdapter({ baseUrl, apiKey })` using the
+factory from `@plumbus/ai-decision-laya`. Keep credentials and adapter construction
+on the server. Laya requires a separately running service. For programmatic
+bootstrap, pass `decisions` to `createServer()` / `buildWorkerAiService()` or
+`createAIService()`. Decision adapters belong under `decisions.providers`, not the
+text-completion `providers` map. Use distinct names across those two maps.
+
+## Select a provider and model per call
+
+```ts
+// Inside a capability handler or flow step:
+const labels = await ctx.ai.classify({
+  text: input.ticketText,
+  labels: ['billing', 'technical', 'refund'],
+  provider: 'typesafe',
+  model: 'jev-1.13.0',
+  threshold: 0.5,
+  signal: ctx.signal,
+  costContext: { projectId: input.projectId },
+});
+```
+
+`provider` is the registered map key; `model` is a model ID supported by that
+endpoint. For Laya automatic language routing use `provider: 'laya', model: 'auto'`;
+an explicit checkpoint must be configured on your Laya service.
+
+| Setting | Resolution |
+| --- | --- |
+| Omitted `provider` | Existing default text provider, even when `decisions.defaultProvider` is set |
+| Decision `model` | Per-call `model` → `decisions.defaultModel` → adapter default |
+| Text `model` | Per-call `model` → AI service `defaultModel` → adapter default |
+| Decision `threshold` | Inclusive probability cutoff in [0, 1], default 0.5 |
+
+For a generative provider, pass its registered name and model and omit `threshold`:
+
+```ts
+const labels = await ctx.ai.classify({
+  text: input.ticketText,
+  labels: ['billing', 'technical'],
+  provider: 'openai',
+  model: 'gpt-6-sol',
+});
+```
+
+Native classification accepts 1–256 nonempty labels, batches one independent
+probability question per label, and returns matching labels in input order. Zero
+or multiple matches are valid. `threshold` is rejected for text providers. Use
+`decide()` with a choice question when exactly one choice and its distribution
+are required; generative models are not a `decide()` backend.
+
+## Cost recording and tests
+
+Persist the existing `onAICostRecorded` hook. Native classification records one
+`operation: 'classify'` row per dispatched logical call, including failures, with
+actual model, usage, cost, tenant/actor, and `costContext`. It does not create an
+extra `decide` row. Unknown cost remains `null`; never invent zero to bypass a
+budget. TypeSafe uses adapter pricing; Laya uses optional `costPerRequestUsd`.
+
+Use `mockAI({ classify: ['billing'] })` through `createTestContext` and
+`runCapability` / `simulateFlow` for application tests. Read the installed provider's
+`instructions/README.md` for adapter tests. Live Laya inference is opt-in; keep it
+out of routine tests.
+
+After upgrading core, run `plumbus init --patch --agent all` and `plumbus doctor`
+to refresh agent wiring to **v17**, preserving app-owned text outside managed blocks.
+
+See [AI operations](ai.md), [instruction index](README.md), and the
+[decision provider guide](https://github.com/plumbus-framework/plumbus/blob/main/docs/ai/decision-providers.md).

package/instructions/ai.md

@@ -70,6 +70,11 @@ const invoice = await ctx.ai.extract({
 
 ### Classify
 
+**Start with [the classification recipe](ai-classification.md)** for provider/model
+selection, TypeSafe/Jev and Laya registration, defaults, thresholds, and cost hooks
+(core **0.7.4+** / **0.8.0-beta.6+**). Use `classify()` for matching labels and `decide()` for richer
+typed questions. Keep calls inside capabilities/flows.
+
 Classify text into provided categories:
 
 ```ts
@@ -115,7 +120,7 @@ await ctx.ai.generateWithUsage({
 });
 ```
 
-Omit `reasoning` to inherit prompt/config; use `null` to restore the provider/model default for one call, clearing both inherited `reasoning` and inherited legacy `reasoningEffort`. Explicit modes are `{ mode:'disabled' }`, `{ mode:'effort', effort:'minimal'|'low'|'medium'|'high'|'xhigh'|'max' }`, and `{ mode:'budget', maxTokens }`. Built-in core adapters translate the intent: OpenAI uses Chat Completions normally and switches caller-tool requests that need active/default GPT-5.6 reasoning to the Responses API; Anthropic uses `thinking` + `output_config.effort`. Responses tool continuations are stateless (`store:false`) and preserve encrypted reasoning items through server-owned `providerState`. Custom providers translate the contract in their own `AIProviderAdapter`. Unsupported modes fail with `AIInvalidRequestError` before provider I/O when the adapter can identify the incompatibility. Deprecated `reasoningEffort` remains the unchanged OpenAI-only `'low' | 'medium' | 'high'` shorthand.
+Omit `reasoning` to inherit prompt/config; use `null` to restore the provider/model default for one call, clearing both inherited `reasoning` and inherited legacy `reasoningEffort`. Explicit modes are `{ mode:'disabled' }`, `{ mode:'effort', effort:'minimal'|'low'|'medium'|'high'|'xhigh'|'max' }`, and `{ mode:'budget', maxTokens }`. Built-in core adapters translate the intent: OpenAI uses Chat Completions normally and switches caller-tool requests that need active/default GPT-5.6 or GPT-6 reasoning to the Responses API; Anthropic uses `thinking` + `output_config.effort`. GPT-6 Chat Completions use `max_completion_tokens`; GPT-6 requests omit sampling temperature unless reasoning is explicitly disabled. Responses tool continuations are stateless (`store:false`) and preserve encrypted reasoning items through server-owned `providerState`. Custom providers translate the contract in their own `AIProviderAdapter`. Unsupported modes fail with `AIInvalidRequestError` before provider I/O when the adapter can identify the incompatibility. Deprecated `reasoningEffort` remains the unchanged OpenAI-only `'low' | 'medium' | 'high'` shorthand.
 
 ### Tool calling (provider-native)
 
@@ -382,3 +387,25 @@ See `docs/ai/ai-integration.md` and `docs/upgrading-contract-alignment.md` §12.
 - With security configured, generate/stream/extract/classify apply the field-classification policy. Extract/classify use the `text` field; arbitrary free-text PII is not automatically detected. Explainability stores redacted input.
 - Unknown prior spend rejects further requests when a dollar cap is configured. Local/unpriced providers still work without dollar caps; explicit free prices stay supported. Never supply fake zero costs to bypass budgets.
 - Read [the security release checklist](./upgrading-security-release.md) before upgrading custom cost hooks or AI wrappers.
+
+
+## Typed decisions (core 0.7.4+ / 0.8.0-beta.6+)
+
+For choices, scores, and probabilities, use `ctx.ai.decide()` inside capabilities
+and flows. Define reusable contracts with `defineDecision` from
+`@plumbus/ai-decision`; CLI startup discovers `app/decisions/`. The shared contract
+package is provided by core; install only the TypeSafe/Laya provider required by
+the app. Export `decisions = { providers, defaultProvider }` from `app/server.ts`
+for both API and workers, using `createTypeSafeDecisionAdapter` or
+`createLayaDecisionAdapter` at that server-owned boundary. Do not register these
+adapters as text-completion providers or call them directly for app business logic.
+
+Core records `operation: 'decide'` with actual model, usage, cost, tenant/actor,
+optional `decisionName`, and the caller's `costContext`. Existing
+`onAICostRecorded(record, costContext, db)` hooks persist these rows; include the
+new operation in any app-owned ledger enum/schema. Failed responses and cancelled
+calls also produce rows. Unknown USD cost is null, never a free zero. Security
+scans state and structured questions; budgets are checked before provider work.
+Use `mockAI({ decide: result })` and test through `runCapability`/`simulateFlow`.
+
+Guide: https://github.com/plumbus-framework/plumbus/blob/main/docs/ai/decision-providers.md

package/instructions/peer-dependencies.md

@@ -43,4 +43,4 @@ Run lint, format checking, typechecking, tests, and packed npm install checks be
 
 ## Consumer upgrade
 
-Read [upgrading-security-release.md](./upgrading-security-release.md) and the 0.8 notes in the root docs, explicitly select the new package versions for every installed Plumbus add-on, and run `plumbus init --patch` for agent wiring **v16**. Keep application business logic in Plumbus primitives and `ctx.*`; do not bypass security checks to make a migration pass.
+Read [upgrading-security-release.md](./upgrading-security-release.md) and the 0.8 notes in the root docs, explicitly select the new package versions for every installed Plumbus add-on, and run `plumbus init --patch --agent all` for current agent wiring (**v17** with core 0.7.4+ / 0.8.0-beta.6+). For classification/provider/model selection, read [ai-classification.md](./ai-classification.md). Keep application business logic in Plumbus primitives and `ctx.*`; do not bypass security checks to make a migration pass.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plumbus/core",
-  "version": "0.8.0-beta.5",
+  "version": "0.8.0-beta.7",
   "description": "Plumbus framework core — types, SDK, runtime, CLI, test utilities",
   "type": "module",
   "main": "./dist/index.js",
@@ -89,7 +89,8 @@
     "xml-crypto": "^6.1.2",
     "xpath": "^0.0.34",
     "zod": "^3.24.0",
-    "zod-to-json-schema": "^3.25.2"
+    "zod-to-json-schema": "^3.25.2",
+    "@plumbus/ai-decision": "~0.3.0-beta.0"
   },
   "peerDependencies": {
     "@plumbus/api": ">=0.3.0-beta.0 <0.4.0",
@@ -121,10 +122,10 @@
     "@vitest/browser": "^3.0.0",
     "esbuild": "^0.25.12",
     "typescript": "^5.7.0",
-    "@plumbus/api": "0.3.0-beta.0",
     "@plumbus/ai-bedrock": "0.3.0-beta.0",
-    "@plumbus/voice": "0.6.0-beta.0",
-    "@plumbus/mcp": "0.7.0-beta.0"
+    "@plumbus/api": "0.3.0-beta.0",
+    "@plumbus/mcp": "0.7.0-beta.0",
+    "@plumbus/voice": "0.6.0-beta.1"
   },
   "scripts": {
     "build": "tsc -b",

package/dist/ai/__typecheck-fixtures__/legacy-cost-api.d.ts

@@ -1,5 +0,0 @@
-import { type AIService, type RAGPipelineConfig, type RunToolLoopParams } from '@plumbus/core';
-export declare function legacyConsumer(ai: AIService, params: RunToolLoopParams): Promise<number>;
-export declare const legacyEmbeddingCallback: RAGPipelineConfig['onEmbeddingCost'];
-export declare const uncheckedEstimate: number;
-//# sourceMappingURL=legacy-cost-api.d.ts.map

package/dist/ai/__typecheck-fixtures__/legacy-cost-api.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"legacy-cost-api.d.ts","sourceRoot":"","sources":["../../../src/ai/__typecheck-fixtures__/legacy-cost-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AAEvB,wBAAsB,cAAc,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAM9F;AAED,eAAO,MAAM,uBAAuB,EAAE,iBAAiB,CAAC,iBAAiB,CAGxE,CAAC;AAGF,eAAO,MAAM,iBAAiB,EAAE,MAAyC,CAAC"}

package/dist/ai/__typecheck-fixtures__/legacy-cost-api.js

@@ -1,15 +0,0 @@
-import { calculateModelCost, estimateModelCost, runToolLoop, } from '@plumbus/core';
-export async function legacyConsumer(ai, params) {
-    const result = await ai.generateWithUsage({ prompt: 'p', input: {} });
-    const cost = result.cost;
-    const loop = await runToolLoop(ai, params);
-    const total = loop.aggregatedCost;
-    return cost + total + calculateModelCost(1, 1, 'local');
-}
-export const legacyEmbeddingCallback = (info) => {
-    const numericCost = info.cost;
-    void numericCost;
-};
-// @ts-expect-error Unknown-aware estimates cannot be treated as definitely priced.
-export const uncheckedEstimate = estimateModelCost(1, 1, 'local');
-//# sourceMappingURL=legacy-cost-api.js.map

package/dist/ai/__typecheck-fixtures__/legacy-cost-api.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"legacy-cost-api.js","sourceRoot":"","sources":["../../../src/ai/__typecheck-fixtures__/legacy-cost-api.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,WAAW,GAIZ,MAAM,eAAe,CAAC;AAEvB,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,EAAa,EAAE,MAAyB;IAC3E,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,iBAAiB,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;IACtE,MAAM,IAAI,GAAW,MAAM,CAAC,IAAI,CAAC;IACjC,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAW,IAAI,CAAC,cAAc,CAAC;IAC1C,OAAO,IAAI,GAAG,KAAK,GAAG,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,CAAC,MAAM,uBAAuB,GAAyC,CAAC,IAAI,EAAE,EAAE;IACpF,MAAM,WAAW,GAAW,IAAI,CAAC,IAAI,CAAC;IACtC,KAAK,WAAW,CAAC;AACnB,CAAC,CAAC;AAEF,mFAAmF;AACnF,MAAM,CAAC,MAAM,iBAAiB,GAAW,iBAAiB,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC"}