@molecule/api-ai-decisions 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,446 @@
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-09-28T17:40:28.606Z
+-->
+
+# @molecule/api-ai-decisions
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+Typed AI decisions for molecule.dev.
+
+Ask typed questions about a piece of text or JSON and get probabilities back,
+not generated text: pick one option (`choice`), rate on an ordered scale
+(`score`), or test a statement (`yesNo`). Use it for routing and triage
+(which queue, how urgent), guardrails and moderation (is this spam, a
+jailbreak, a refund request), and any branch in your code that needs a
+judgment call about language. Many questions share one call.
+
+This core defines the `AIDecisionsProvider` contract and its bond accessor
+only. Bond one provider:
+
+| Bond                              | What answers                                                                                                                                                 | When                                                                 |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
+| `@molecule/api-ai-decisions-laya` | the open-weights Laya model (Apache-2.0) on a `laya-serve` host you run — or any other self-hosted `/v1/systemone` server, such as Kev (Qwen-based, GPU/MLX) | self-hosted, ~30–40 ms/question on a GPU (Laya), data stays with you |
+| `@molecule/api-ai-decisions-jev`  | TypeSafe's hosted Jev API                                                                                                                                    | no model to host; English-first                                      |
+| `@molecule/api-ai-decisions-llm`  | whatever `ai` chat bond is bonded                                                                                                                            | no extra service; slower and costlier per call                       |
+
+## Quick Start
+
+```typescript
+import { setProvider, requireProvider } from '@molecule/api-ai-decisions'
+import { provider as laya } from '@molecule/api-ai-decisions-laya'
+
+setProvider(laya) // at startup — reads LAYA_URL / LAYA_API_KEY on first use
+
+const { answers } = await requireProvider().decide({
+  state: { subject: 'Charged twice', body: 'I was billed twice this month, I want my money back' },
+  questions: {
+    queue: {
+      type: 'choice',
+      instructions: 'Which team should handle this?',
+      criteria: {
+        billing: 'invoices, refunds, charges',
+        tech: 'bugs, login, outages',
+        other: 'anything else',
+      },
+    },
+    urgency: {
+      type: 'score',
+      instructions: 'How upset is the customer?',
+      criteria: ['calm', 'firm', 'angry', 'furious'],
+    },
+    refund: { type: 'yesNo', instructions: 'The customer is asking for a refund.' },
+  },
+  minConfidence: 0.7,
+})
+
+answers.queue.choice // 'billing'
+answers.urgency.level // 2  (answers.urgency.score is the expected level, e.g. 2.64)
+answers.refund.probability // 0.97
+if (answers.queue.lowConfidence) {
+  // send to a human instead of auto-routing
+}
+```
+
+## Type
+
+`core`
+
+## Installation
+
+```bash
+npm install @molecule/api-ai-decisions @molecule/api-bond @molecule/api-i18n
+```
+
+## API
+
+### Interfaces
+
+#### `AIDecisionsProvider`
+
+AI decisions provider interface. Implemented by the Laya, Jev and LLM bonds.
+
+```typescript
+interface AIDecisionsProvider {
+  /** Provider identifier. */
+  readonly name: string
+
+  /**
+   * Answer every question about `state`.
+   *
+   * @param input - The state, the questions and options.
+   * @returns One typed answer per question id.
+   */
+  decide<Q extends Record<string, DecisionQuestion>>(
+    input: DecideInput<Q>,
+  ): Promise<DecideResult<Q>>
+}
+```
+
+#### `AnswerBase`
+
+Fields every answer carries.
+
+```typescript
+interface AnswerBase {
+  /**
+   * Probability mass on the reported answer (the highest option probability;
+   * `max(p, 1 - p)` for yes/no), in `0..1`. Every bond computes it this same
+   * way from the probabilities, so a threshold means the same thing whichever
+   * provider is bonded — it is NOT the vendor's own `confidence` field.
+   */
+  confidence: number
+  /** Set only when `minConfidence` was passed: `true` when `confidence` fell below it. */
+  lowConfidence?: boolean
+}
+```
+
+#### `ChoiceAnswer`
+
+Answer to a {@link ChoiceQuestion}.
+
+```typescript
+interface ChoiceAnswer extends AnswerBase {
+  type: 'choice'
+  /** The most likely option — always one of the question's `criteria` keys. */
+  choice: string
+  /** Probability per option (every `criteria` key present), summing to ~1. */
+  probabilities: Record<string, number>
+}
+```
+
+#### `ChoiceQuestion`
+
+Pick exactly one option.
+
+```typescript
+interface ChoiceQuestion {
+  type: 'choice'
+  /** What is being decided, e.g. `'Which team should handle this ticket?'`. */
+  instructions: string
+  /**
+   * The options, keyed by the label you want back, each with a short
+   * description of when it applies. `{ billing: 'invoices, refunds', tech: 'bugs, outages' }`.
+   */
+  criteria: Record<string, string>
+}
+```
+
+#### `DecideInput`
+
+Input to one decision request.
+
+```typescript
+interface DecideInput<
+  Q extends Record<string, DecisionQuestion> = Record<string, DecisionQuestion>,
+> {
+  /** What the questions are about. */
+  state: DecisionState
+  /** The questions, keyed by an id you choose; answers come back under the same ids. */
+  questions: Q
+  /** Provider-specific model / checkpoint id (e.g. `'jev-latest'`, `'multilingual'`). */
+  model?: string
+  /** Mark answers whose `confidence` is below this (`0..1`) with `lowConfidence: true`. */
+  minConfidence?: number
+  /** Abort signal to cancel the in-flight request. */
+  signal?: AbortSignal
+}
+```
+
+#### `DecideResult`
+
+Result of one decision request.
+
+```typescript
+interface DecideResult<
+  Q extends Record<string, DecisionQuestion> = Record<string, DecisionQuestion>,
+> {
+  /** One answer per question id. */
+  answers: AnswersFor<Q>
+  /** The model or checkpoint that answered, when the provider says. */
+  model?: string
+  /** Token usage, when reported. */
+  usage?: DecisionUsage
+}
+```
+
+#### `DecisionUsage`
+
+Token usage, when the provider reports it.
+
+```typescript
+interface DecisionUsage {
+  inputTokens: number
+  outputTokens: number
+}
+```
+
+#### `ScoreAnswer`
+
+Answer to a {@link ScoreQuestion}.
+
+```typescript
+interface ScoreAnswer extends AnswerBase {
+  type: 'score'
+  /** Expected level index — may fall between levels (e.g. `2.64`). */
+  score: number
+  /** The most likely level index (`0..criteria.length - 1`). */
+  level: number
+  /** Probability per level, indexed like `criteria`. */
+  probabilities: number[]
+}
+```
+
+#### `ScoreQuestion`
+
+Place the state on an ordered scale.
+
+```typescript
+interface ScoreQuestion {
+  type: 'score'
+  /** What is being rated, e.g. `'How urgent is this?'`. */
+  instructions: string
+  /**
+   * The levels, lowest first. Level `i` is described by `criteria[i]`:
+   * `['calm', 'firm', 'angry', 'furious']`.
+   */
+  criteria: string[]
+}
+```
+
+#### `YesNoAnswer`
+
+Answer to a {@link YesNoQuestion}.
+
+```typescript
+interface YesNoAnswer extends AnswerBase {
+  type: 'yesNo'
+  /** Probability that the statement is true, in `0..1`. */
+  probability: number
+  /** `probability >= 0.5`. Prefer thresholding `probability` yourself when the cost of each mistake differs. */
+  answer: boolean
+}
+```
+
+#### `YesNoQuestion`
+
+How likely is a statement true. (Called `noul` on the Jev/Laya wire.)
+
+```typescript
+interface YesNoQuestion {
+  type: 'yesNo'
+  /** The statement to test, e.g. `'The customer is asking for a refund.'`. */
+  instructions: string
+  /** Optional descriptions of what counts as yes and as no. */
+  criteria?: { yes?: string; no?: string }
+}
+```
+
+### Types
+
+#### `AnswersFor`
+
+Maps a questions object to its answers object, so
+`result.answers.department.choice` is typed when the questions are literal.
+
+```typescript
+type AnswersFor<Q extends Record<string, DecisionQuestion>> = {
+  [K in keyof Q]: Q[K] extends ChoiceQuestion
+    ? ChoiceAnswer
+    : Q[K] extends ScoreQuestion
+      ? ScoreAnswer
+      : YesNoAnswer
+}
+```
+
+#### `DecisionAnswer`
+
+Any answer. `answers[id].type` matches `questions[id].type`.
+
+```typescript
+type DecisionAnswer = ChoiceAnswer | ScoreAnswer | YesNoAnswer
+```
+
+#### `DecisionQuestion`
+
+Any question a decision provider answers.
+
+```typescript
+type DecisionQuestion = ChoiceQuestion | ScoreQuestion | YesNoQuestion
+```
+
+#### `DecisionState`
+
+What the questions are about: plain text, or a JSON object / array (an
+email with headers, a ticket with metadata, a chat log).
+
+```typescript
+type DecisionState = string | Record<string, unknown> | unknown[]
+```
+
+### Functions
+
+#### `getAllProviders()`
+
+Retrieves all named AI decisions providers as a Map keyed by name.
+
+```typescript
+function getAllProviders(): Map<string, AIDecisionsProvider>
+```
+
+**Returns:** Map of provider name → AIDecisionsProvider.
+
+#### `getProvider()`
+
+Retrieves the singleton AI decisions provider, or `null` if none is bonded.
+
+Falls back to a single named provider when no singleton is bonded. When
+multiple named providers are bonded the fallback declines (returns `null`)
+because the choice is ambiguous — use `getProviderByName(name)` instead.
+
+```typescript
+function getProvider(): AIDecisionsProvider | null
+```
+
+**Returns:** The bonded AI decisions provider, or `null`.
+
+#### `getProviderByName(name)`
+
+Retrieves a named AI decisions provider, or `null` if not bonded.
+
+```typescript
+function getProviderByName(name: string): AIDecisionsProvider | null
+```
+
+- `name` — The provider name.
+
+**Returns:** The named AI decisions provider, or `null`.
+
+#### `hasProvider(name)`
+
+Checks whether an AI decisions provider is currently bonded.
+
+```typescript
+function hasProvider(name?: string): boolean
+```
+
+- `name` — Optional provider name. If omitted, checks the singleton.
+
+**Returns:** `true` if the provider is bonded.
+
+#### `requireProvider()`
+
+Retrieves the bonded AI decisions provider, throwing if none is bonded.
+
+```typescript
+function requireProvider(): AIDecisionsProvider
+```
+
+**Returns:** The bonded AI decisions provider.
+
+#### `setProvider(provider)`
+
+Registers an AI decisions provider in singleton mode.
+
+```typescript
+function setProvider(provider: AIDecisionsProvider): void
+```
+
+- `provider` — The default provider implementation for this process.
+
+## Available Providers
+
+| Provider | Package                           |
+| -------- | --------------------------------- |
+| Jev      | `@molecule/api-ai-decisions-jev`  |
+| Laya     | `@molecule/api-ai-decisions-laya` |
+| LLM      | `@molecule/api-ai-decisions-llm`  |
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/api-bond` ^1.0.1
+- `@molecule/api-i18n` ^1.0.1
+
+### Runtime Dependencies
+
+- `@molecule/api-bond`
+- `@molecule/api-i18n`
+
+- **Interface + accessor only.** Use the core's `setProvider(provider)` /
+  `setProvider('name', provider)`, then `requireProvider()` or
+  `getProviderByName('name')`.
+- **`confidence` is the probability of the reported answer** (`max` of the
+  distribution), computed the same way by every bond. Vendors define their
+  own `confidence` differently (Jev: `(n·pmax − 1)/(n − 1)`; Laya: normalized
+  entropy), so a threshold copied from a vendor's docs does not transfer —
+  pick thresholds on your own data.
+- **Base models are not a finished classifier for your domain.** Laya's own
+  benchmarks put its base checkpoints near chance (0.36) on the
+  typed-decisions set zero-shot; its fine-tuned checkpoint reaches 0.77.
+  Measure accuracy on a labelled sample of YOUR inputs before letting an
+  answer act unattended, and gate on `minConfidence` → a human or an LLM
+  fallback for the rest.
+- **Probabilities ship over-confident** until calibrated on your traffic (Laya
+  reports ECE 0.47 → 0.08 after temperature fitting). A 0.95 is not "right 95%
+  of the time" until you have checked.
+- **Keep option lists short.** Accuracy drops past ~20 `choice` options on
+  Laya (the option texts share a ~192-token window); Jev accepts up to 255,
+  `laya-serve` refuses >100. `score` takes 2–10 levels on Jev.
+- **Keep state short.** Laya's English checkpoint reads 512 tokens (the
+  multilingual one 1,024); longer state is truncated, not refused. Put the
+  decisive text first.
+- **Never use it to generate text** — there is no text output. For a
+  free-text label set that changes per request, use
+  `@molecule/api-ai-classification`.
+- **Server-side only.** The provider key and the model host never belong in
+  browser code.
+
+## E2E Tests
+
+Integration checklist — drive the real UI (live preview, no mocks), adapt
+each item to this app's actual screens/flows, and check every box off one
+by one. A box you can't check is an integration bug to fix — not a skip:
+
+- [ ] Each flow that makes a decision (routing, triage, moderation, a
+      guardrail) runs it from the real UI, and the answer DRIVES what happens
+      next (the item lands in the chosen queue, the badge shows, the action is
+      blocked) — not just printed.
+- [ ] Both directions: a clearly-billing input routes to billing AND a
+      clearly-technical one routes elsewhere. One label for every input is a
+      broken integration.
+- [ ] A low-confidence answer takes the app's fallback path (human review,
+      "unsure" state) instead of being acted on.
+- [ ] Provider errors (service down, bad key) show a visible, recoverable
+      state — never a blank screen or an unhandled rejection.
+- [ ] The call runs server-side: no provider request or key in the browser's
+      Network tab.

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,19 @@
+/**
+ * Browser guard — `@molecule/api-ai-decisions` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-ai-decisions is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};
+//# sourceMappingURL=browser-guard.js.map

package/dist/browser-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.js","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,GAAG,UAIT,CAAA;AACD,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACrF,MAAM,IAAI,KAAK,CACb,qGAAqG;QACnG,sFAAsF;QACtF,iFAAiF;QACjF,0CAA0C,CAC7C,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Typed AI decisions for molecule.dev.
+ *
+ * Ask typed questions about a piece of text or JSON and get probabilities back,
+ * not generated text: pick one option (`choice`), rate on an ordered scale
+ * (`score`), or test a statement (`yesNo`). Use it for routing and triage
+ * (which queue, how urgent), guardrails and moderation (is this spam, a
+ * jailbreak, a refund request), and any branch in your code that needs a
+ * judgment call about language. Many questions share one call.
+ *
+ * This core defines the `AIDecisionsProvider` contract and its bond accessor
+ * only. Bond one provider:
+ *
+ * | Bond | What answers | When |
+ * |---|---|---|
+ * | `@molecule/api-ai-decisions-laya` | the open-weights Laya model (Apache-2.0) on a `laya-serve` host you run — or any other self-hosted `/v1/systemone` server, such as Kev (Qwen-based, GPU/MLX) | self-hosted, ~30–40 ms/question on a GPU (Laya), data stays with you |
+ * | `@molecule/api-ai-decisions-jev` | TypeSafe's hosted Jev API | no model to host; English-first |
+ * | `@molecule/api-ai-decisions-llm` | whatever `ai` chat bond is bonded | no extra service; slower and costlier per call |
+ *
+ * @example
+ * ```typescript
+ * import { setProvider, requireProvider } from '@molecule/api-ai-decisions'
+ * import { provider as laya } from '@molecule/api-ai-decisions-laya'
+ *
+ * setProvider(laya) // at startup — reads LAYA_URL / LAYA_API_KEY on first use
+ *
+ * const { answers } = await requireProvider().decide({
+ *   state: { subject: 'Charged twice', body: 'I was billed twice this month, I want my money back' },
+ *   questions: {
+ *     queue: {
+ *       type: 'choice',
+ *       instructions: 'Which team should handle this?',
+ *       criteria: { billing: 'invoices, refunds, charges', tech: 'bugs, login, outages', other: 'anything else' },
+ *     },
+ *     urgency: { type: 'score', instructions: 'How upset is the customer?', criteria: ['calm', 'firm', 'angry', 'furious'] },
+ *     refund: { type: 'yesNo', instructions: 'The customer is asking for a refund.' },
+ *   },
+ *   minConfidence: 0.7,
+ * })
+ *
+ * answers.queue.choice        // 'billing'
+ * answers.urgency.level       // 2  (answers.urgency.score is the expected level, e.g. 2.64)
+ * answers.refund.probability  // 0.97
+ * if (answers.queue.lowConfidence) {
+ *   // send to a human instead of auto-routing
+ * }
+ * ```
+ *
+ * @remarks
+ * - **Interface + accessor only.** Use the core's `setProvider(provider)` /
+ *   `setProvider('name', provider)`, then `requireProvider()` or
+ *   `getProviderByName('name')`.
+ * - **`confidence` is the probability of the reported answer** (`max` of the
+ *   distribution), computed the same way by every bond. Vendors define their
+ *   own `confidence` differently (Jev: `(n·pmax − 1)/(n − 1)`; Laya: normalized
+ *   entropy), so a threshold copied from a vendor's docs does not transfer —
+ *   pick thresholds on your own data.
+ * - **Base models are not a finished classifier for your domain.** Laya's own
+ *   benchmarks put its base checkpoints near chance (0.36) on the
+ *   typed-decisions set zero-shot; its fine-tuned checkpoint reaches 0.77.
+ *   Measure accuracy on a labelled sample of YOUR inputs before letting an
+ *   answer act unattended, and gate on `minConfidence` → a human or an LLM
+ *   fallback for the rest.
+ * - **Probabilities ship over-confident** until calibrated on your traffic (Laya
+ *   reports ECE 0.47 → 0.08 after temperature fitting). A 0.95 is not "right 95%
+ *   of the time" until you have checked.
+ * - **Keep option lists short.** Accuracy drops past ~20 `choice` options on
+ *   Laya (the option texts share a ~192-token window); Jev accepts up to 255,
+ *   `laya-serve` refuses >100. `score` takes 2–10 levels on Jev.
+ * - **Keep state short.** Laya's English checkpoint reads 512 tokens (the
+ *   multilingual one 1,024); longer state is truncated, not refused. Put the
+ *   decisive text first.
+ * - **Never use it to generate text** — there is no text output. For a
+ *   free-text label set that changes per request, use
+ *   `@molecule/api-ai-classification`.
+ * - **Server-side only.** The provider key and the model host never belong in
+ *   browser code.
+ *
+ * @e2e
+ * Integration checklist — drive the real UI (live preview, no mocks), adapt
+ * each item to this app's actual screens/flows, and check every box off one
+ * by one. A box you can't check is an integration bug to fix — not a skip:
+ * - [ ] Each flow that makes a decision (routing, triage, moderation, a
+ *   guardrail) runs it from the real UI, and the answer DRIVES what happens
+ *   next (the item lands in the chosen queue, the badge shows, the action is
+ *   blocked) — not just printed.
+ * - [ ] Both directions: a clearly-billing input routes to billing AND a
+ *   clearly-technical one routes elsewhere. One label for every input is a
+ *   broken integration.
+ * - [ ] A low-confidence answer takes the app's fallback path (human review,
+ *   "unsure" state) instead of being acted on.
+ * - [ ] Provider errors (service down, bad key) show a visible, recoverable
+ *   state — never a blank screen or an unhandled rejection.
+ * - [ ] The call runs server-side: no provider request or key in the browser's
+ *   Network tab.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './provider.js';
+export * from './types.js';
+//# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiGG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,102 @@
+/**
+ * Typed AI decisions for molecule.dev.
+ *
+ * Ask typed questions about a piece of text or JSON and get probabilities back,
+ * not generated text: pick one option (`choice`), rate on an ordered scale
+ * (`score`), or test a statement (`yesNo`). Use it for routing and triage
+ * (which queue, how urgent), guardrails and moderation (is this spam, a
+ * jailbreak, a refund request), and any branch in your code that needs a
+ * judgment call about language. Many questions share one call.
+ *
+ * This core defines the `AIDecisionsProvider` contract and its bond accessor
+ * only. Bond one provider:
+ *
+ * | Bond | What answers | When |
+ * |---|---|---|
+ * | `@molecule/api-ai-decisions-laya` | the open-weights Laya model (Apache-2.0) on a `laya-serve` host you run — or any other self-hosted `/v1/systemone` server, such as Kev (Qwen-based, GPU/MLX) | self-hosted, ~30–40 ms/question on a GPU (Laya), data stays with you |
+ * | `@molecule/api-ai-decisions-jev` | TypeSafe's hosted Jev API | no model to host; English-first |
+ * | `@molecule/api-ai-decisions-llm` | whatever `ai` chat bond is bonded | no extra service; slower and costlier per call |
+ *
+ * @example
+ * ```typescript
+ * import { setProvider, requireProvider } from '@molecule/api-ai-decisions'
+ * import { provider as laya } from '@molecule/api-ai-decisions-laya'
+ *
+ * setProvider(laya) // at startup — reads LAYA_URL / LAYA_API_KEY on first use
+ *
+ * const { answers } = await requireProvider().decide({
+ *   state: { subject: 'Charged twice', body: 'I was billed twice this month, I want my money back' },
+ *   questions: {
+ *     queue: {
+ *       type: 'choice',
+ *       instructions: 'Which team should handle this?',
+ *       criteria: { billing: 'invoices, refunds, charges', tech: 'bugs, login, outages', other: 'anything else' },
+ *     },
+ *     urgency: { type: 'score', instructions: 'How upset is the customer?', criteria: ['calm', 'firm', 'angry', 'furious'] },
+ *     refund: { type: 'yesNo', instructions: 'The customer is asking for a refund.' },
+ *   },
+ *   minConfidence: 0.7,
+ * })
+ *
+ * answers.queue.choice        // 'billing'
+ * answers.urgency.level       // 2  (answers.urgency.score is the expected level, e.g. 2.64)
+ * answers.refund.probability  // 0.97
+ * if (answers.queue.lowConfidence) {
+ *   // send to a human instead of auto-routing
+ * }
+ * ```
+ *
+ * @remarks
+ * - **Interface + accessor only.** Use the core's `setProvider(provider)` /
+ *   `setProvider('name', provider)`, then `requireProvider()` or
+ *   `getProviderByName('name')`.
+ * - **`confidence` is the probability of the reported answer** (`max` of the
+ *   distribution), computed the same way by every bond. Vendors define their
+ *   own `confidence` differently (Jev: `(n·pmax − 1)/(n − 1)`; Laya: normalized
+ *   entropy), so a threshold copied from a vendor's docs does not transfer —
+ *   pick thresholds on your own data.
+ * - **Base models are not a finished classifier for your domain.** Laya's own
+ *   benchmarks put its base checkpoints near chance (0.36) on the
+ *   typed-decisions set zero-shot; its fine-tuned checkpoint reaches 0.77.
+ *   Measure accuracy on a labelled sample of YOUR inputs before letting an
+ *   answer act unattended, and gate on `minConfidence` → a human or an LLM
+ *   fallback for the rest.
+ * - **Probabilities ship over-confident** until calibrated on your traffic (Laya
+ *   reports ECE 0.47 → 0.08 after temperature fitting). A 0.95 is not "right 95%
+ *   of the time" until you have checked.
+ * - **Keep option lists short.** Accuracy drops past ~20 `choice` options on
+ *   Laya (the option texts share a ~192-token window); Jev accepts up to 255,
+ *   `laya-serve` refuses >100. `score` takes 2–10 levels on Jev.
+ * - **Keep state short.** Laya's English checkpoint reads 512 tokens (the
+ *   multilingual one 1,024); longer state is truncated, not refused. Put the
+ *   decisive text first.
+ * - **Never use it to generate text** — there is no text output. For a
+ *   free-text label set that changes per request, use
+ *   `@molecule/api-ai-classification`.
+ * - **Server-side only.** The provider key and the model host never belong in
+ *   browser code.
+ *
+ * @e2e
+ * Integration checklist — drive the real UI (live preview, no mocks), adapt
+ * each item to this app's actual screens/flows, and check every box off one
+ * by one. A box you can't check is an integration bug to fix — not a skip:
+ * - [ ] Each flow that makes a decision (routing, triage, moderation, a
+ *   guardrail) runs it from the real UI, and the answer DRIVES what happens
+ *   next (the item lands in the chosen queue, the badge shows, the action is
+ *   blocked) — not just printed.
+ * - [ ] Both directions: a clearly-billing input routes to billing AND a
+ *   clearly-technical one routes elsewhere. One label for every input is a
+ *   broken integration.
+ * - [ ] A low-confidence answer takes the app's fallback path (human review,
+ *   "unsure" state) instead of being acted on.
+ * - [ ] Provider errors (service down, bad key) show a visible, recoverable
+ *   state — never a blank screen or an unhandled rejection.
+ * - [ ] The call runs server-side: no provider request or key in the browser's
+ *   Network tab.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './provider.js';
+export * from './types.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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiGG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA"}

package/dist/provider.d.ts

@@ -0,0 +1,60 @@
+/**
+ * AI decisions provider bond accessor (singleton + named, like the `ai` core).
+ *
+ * This core defines the `AIDecisionsProvider` contract only — bond a concrete
+ * implementation (`@molecule/api-ai-decisions-laya`, `-jev` or `-llm`).
+ *
+ * @module
+ */
+import type { AIDecisionsProvider } from './types.js';
+/**
+ * Registers an AI decisions provider in singleton mode.
+ *
+ * @param provider - The default provider implementation for this process.
+ */
+export declare function setProvider(provider: AIDecisionsProvider): void;
+/**
+ * Registers a named AI decisions provider under bond type `ai-decisions`.
+ *
+ * @param name - Provider identifier used when selecting the provider.
+ * @param provider - Concrete provider bound to `name`.
+ */
+export declare function setProvider(name: string, provider: AIDecisionsProvider): void;
+/**
+ * Retrieves the singleton AI decisions provider, or `null` if none is bonded.
+ *
+ * Falls back to a single named provider when no singleton is bonded. When
+ * multiple named providers are bonded the fallback declines (returns `null`)
+ * because the choice is ambiguous — use `getProviderByName(name)` instead.
+ *
+ * @returns The bonded AI decisions provider, or `null`.
+ */
+export declare function getProvider(): AIDecisionsProvider | null;
+/**
+ * Retrieves a named AI decisions provider, or `null` if not bonded.
+ *
+ * @param name - The provider name.
+ * @returns The named AI decisions provider, or `null`.
+ */
+export declare function getProviderByName(name: string): AIDecisionsProvider | null;
+/**
+ * Retrieves all named AI decisions providers as a Map keyed by name.
+ *
+ * @returns Map of provider name → AIDecisionsProvider.
+ */
+export declare function getAllProviders(): Map<string, AIDecisionsProvider>;
+/**
+ * Checks whether an AI decisions provider is currently bonded.
+ *
+ * @param name - Optional provider name. If omitted, checks the singleton.
+ * @returns `true` if the provider is bonded.
+ */
+export declare function hasProvider(name?: string): boolean;
+/**
+ * Retrieves the bonded AI decisions provider, throwing if none is bonded.
+ *
+ * @returns The bonded AI decisions provider.
+ * @throws {Error} When no provider is bonded.
+ */
+export declare function requireProvider(): AIDecisionsProvider;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AASrD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAA;AAChE;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAA;AAuB9E;;;;;;;;GAQG;AACH,wBAAgB,WAAW,IAAI,mBAAmB,GAAG,IAAI,CAKxD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAE1E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAElE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,mBAAmB,CASrD"}

package/dist/provider.js

@@ -0,0 +1,88 @@
+/**
+ * AI decisions provider bond accessor (singleton + named, like the `ai` core).
+ *
+ * This core defines the `AIDecisionsProvider` contract only — bond a concrete
+ * implementation (`@molecule/api-ai-decisions-laya`, `-jev` or `-llm`).
+ *
+ * @module
+ */
+import { bond, expectBond, get as bondGet, getAll as bondGetAll, isBonded, } from '@molecule/api-bond';
+import { t } from '@molecule/api-i18n';
+const BOND_TYPE = 'ai-decisions';
+expectBond(BOND_TYPE);
+/**
+ * Implementation that powers the `setProvider` overloads.
+ *
+ * @param nameOrProvider - Provider name (string) or the provider instance (singleton mode).
+ * @param provider - The provider instance (only when the first arg is a name).
+ */
+export function setProvider(nameOrProvider, provider) {
+    if (typeof nameOrProvider === 'string') {
+        bond(BOND_TYPE, nameOrProvider, provider);
+        // Also register as singleton if none exists yet, so validateBonds() passes
+        // and getProvider() works as a fallback.
+        if (!isBonded(BOND_TYPE)) {
+            bond(BOND_TYPE, provider);
+        }
+    }
+    else {
+        bond(BOND_TYPE, nameOrProvider);
+    }
+}
+/**
+ * Retrieves the singleton AI decisions provider, or `null` if none is bonded.
+ *
+ * Falls back to a single named provider when no singleton is bonded. When
+ * multiple named providers are bonded the fallback declines (returns `null`)
+ * because the choice is ambiguous — use `getProviderByName(name)` instead.
+ *
+ * @returns The bonded AI decisions provider, or `null`.
+ */
+export function getProvider() {
+    const singleton = bondGet(BOND_TYPE);
+    if (singleton)
+        return singleton;
+    const named = bondGetAll(BOND_TYPE);
+    return named.size === 1 ? (named.values().next().value ?? null) : null;
+}
+/**
+ * Retrieves a named AI decisions provider, or `null` if not bonded.
+ *
+ * @param name - The provider name.
+ * @returns The named AI decisions provider, or `null`.
+ */
+export function getProviderByName(name) {
+    return bondGet(BOND_TYPE, name) ?? null;
+}
+/**
+ * Retrieves all named AI decisions providers as a Map keyed by name.
+ *
+ * @returns Map of provider name → AIDecisionsProvider.
+ */
+export function getAllProviders() {
+    return bondGetAll(BOND_TYPE);
+}
+/**
+ * Checks whether an AI decisions provider is currently bonded.
+ *
+ * @param name - Optional provider name. If omitted, checks the singleton.
+ * @returns `true` if the provider is bonded.
+ */
+export function hasProvider(name) {
+    return name ? isBonded(BOND_TYPE, name) : isBonded(BOND_TYPE);
+}
+/**
+ * Retrieves the bonded AI decisions provider, throwing if none is bonded.
+ *
+ * @returns The bonded AI decisions provider.
+ * @throws {Error} When no provider is bonded.
+ */
+export function requireProvider() {
+    const found = getProvider();
+    if (found)
+        return found;
+    throw new Error(t('ai-decisions.error.noProvider', undefined, {
+        defaultValue: 'AI decisions provider not configured. Bond an ai-decisions provider (Laya, Jev or the LLM bond) first.',
+    }));
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,IAAI,EACJ,UAAU,EACV,GAAG,IAAI,OAAO,EACd,MAAM,IAAI,UAAU,EACpB,QAAQ,GACT,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAA;AAItC,MAAM,SAAS,GAAG,cAAc,CAAA;AAChC,UAAU,CAAC,SAAS,CAAC,CAAA;AAmBrB;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CACzB,cAA4C,EAC5C,QAA8B;IAE9B,IAAI,OAAO,cAAc,KAAK,QAAQ,EAAE,CAAC;QACvC,IAAI,CAAC,SAAS,EAAE,cAAc,EAAE,QAAS,CAAC,CAAA;QAC1C,2EAA2E;QAC3E,yCAAyC;QACzC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YACzB,IAAI,CAAC,SAAS,EAAE,QAAS,CAAC,CAAA;QAC5B,CAAC;IACH,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAA;IACjC,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW;IACzB,MAAM,SAAS,GAAG,OAAO,CAAsB,SAAS,CAAC,CAAA;IACzD,IAAI,SAAS;QAAE,OAAO,SAAS,CAAA;IAC/B,MAAM,KAAK,GAAG,UAAU,CAAsB,SAAS,CAAC,CAAA;IACxD,OAAO,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;AACxE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,OAAO,CAAsB,SAAS,EAAE,IAAI,CAAC,IAAI,IAAI,CAAA;AAC9D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,UAAU,CAAsB,SAAS,CAAC,CAAA;AACnD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,IAAa;IACvC,OAAO,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAA;AAC/D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,KAAK,GAAG,WAAW,EAAE,CAAA;IAC3B,IAAI,KAAK;QAAE,OAAO,KAAK,CAAA;IACvB,MAAM,IAAI,KAAK,CACb,CAAC,CAAC,+BAA+B,EAAE,SAAS,EAAE;QAC5C,YAAY,EACV,wGAAwG;KAC3G,CAAC,CACH,CAAA;AACH,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,150 @@
+/**
+ * AI decisions provider interface.
+ *
+ * A "decision" is a typed question about a piece of state (text, an email, a
+ * ticket, a JSON document) whose answer is a probability distribution, never
+ * generated text: pick one of N options (`choice`), place it on an ordered
+ * scale (`score`), or say how likely a statement is true (`yesNo`). One call
+ * asks any number of questions about the same state.
+ *
+ * The shape follows the `/v1/systemone` protocol spoken by TypeSafe's Jev and
+ * the open-weights Laya server, but it is provider-neutral: an LLM bond
+ * implements it too.
+ *
+ * @module
+ */
+/**
+ * What the questions are about: plain text, or a JSON object / array (an
+ * email with headers, a ticket with metadata, a chat log).
+ */
+export type DecisionState = string | Record<string, unknown> | unknown[];
+/**
+ * Pick exactly one option.
+ */
+export interface ChoiceQuestion {
+    type: 'choice';
+    /** What is being decided, e.g. `'Which team should handle this ticket?'`. */
+    instructions: string;
+    /**
+     * The options, keyed by the label you want back, each with a short
+     * description of when it applies. `{ billing: 'invoices, refunds', tech: 'bugs, outages' }`.
+     */
+    criteria: Record<string, string>;
+}
+/**
+ * Place the state on an ordered scale.
+ */
+export interface ScoreQuestion {
+    type: 'score';
+    /** What is being rated, e.g. `'How urgent is this?'`. */
+    instructions: string;
+    /**
+     * The levels, lowest first. Level `i` is described by `criteria[i]`:
+     * `['calm', 'firm', 'angry', 'furious']`.
+     */
+    criteria: string[];
+}
+/**
+ * How likely is a statement true. (Called `noul` on the Jev/Laya wire.)
+ */
+export interface YesNoQuestion {
+    type: 'yesNo';
+    /** The statement to test, e.g. `'The customer is asking for a refund.'`. */
+    instructions: string;
+    /** Optional descriptions of what counts as yes and as no. */
+    criteria?: {
+        yes?: string;
+        no?: string;
+    };
+}
+/** Any question a decision provider answers. */
+export type DecisionQuestion = ChoiceQuestion | ScoreQuestion | YesNoQuestion;
+/** Fields every answer carries. */
+export interface AnswerBase {
+    /**
+     * Probability mass on the reported answer (the highest option probability;
+     * `max(p, 1 - p)` for yes/no), in `0..1`. Every bond computes it this same
+     * way from the probabilities, so a threshold means the same thing whichever
+     * provider is bonded — it is NOT the vendor's own `confidence` field.
+     */
+    confidence: number;
+    /** Set only when `minConfidence` was passed: `true` when `confidence` fell below it. */
+    lowConfidence?: boolean;
+}
+/** Answer to a {@link ChoiceQuestion}. */
+export interface ChoiceAnswer extends AnswerBase {
+    type: 'choice';
+    /** The most likely option — always one of the question's `criteria` keys. */
+    choice: string;
+    /** Probability per option (every `criteria` key present), summing to ~1. */
+    probabilities: Record<string, number>;
+}
+/** Answer to a {@link ScoreQuestion}. */
+export interface ScoreAnswer extends AnswerBase {
+    type: 'score';
+    /** Expected level index — may fall between levels (e.g. `2.64`). */
+    score: number;
+    /** The most likely level index (`0..criteria.length - 1`). */
+    level: number;
+    /** Probability per level, indexed like `criteria`. */
+    probabilities: number[];
+}
+/** Answer to a {@link YesNoQuestion}. */
+export interface YesNoAnswer extends AnswerBase {
+    type: 'yesNo';
+    /** Probability that the statement is true, in `0..1`. */
+    probability: number;
+    /** `probability >= 0.5`. Prefer thresholding `probability` yourself when the cost of each mistake differs. */
+    answer: boolean;
+}
+/** Any answer. `answers[id].type` matches `questions[id].type`. */
+export type DecisionAnswer = ChoiceAnswer | ScoreAnswer | YesNoAnswer;
+/**
+ * Maps a questions object to its answers object, so
+ * `result.answers.department.choice` is typed when the questions are literal.
+ */
+export type AnswersFor<Q extends Record<string, DecisionQuestion>> = {
+    [K in keyof Q]: Q[K] extends ChoiceQuestion ? ChoiceAnswer : Q[K] extends ScoreQuestion ? ScoreAnswer : YesNoAnswer;
+};
+/** Input to one decision request. */
+export interface DecideInput<Q extends Record<string, DecisionQuestion> = Record<string, DecisionQuestion>> {
+    /** What the questions are about. */
+    state: DecisionState;
+    /** The questions, keyed by an id you choose; answers come back under the same ids. */
+    questions: Q;
+    /** Provider-specific model / checkpoint id (e.g. `'jev-latest'`, `'multilingual'`). */
+    model?: string;
+    /** Mark answers whose `confidence` is below this (`0..1`) with `lowConfidence: true`. */
+    minConfidence?: number;
+    /** Abort signal to cancel the in-flight request. */
+    signal?: AbortSignal;
+}
+/** Token usage, when the provider reports it. */
+export interface DecisionUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
+/** Result of one decision request. */
+export interface DecideResult<Q extends Record<string, DecisionQuestion> = Record<string, DecisionQuestion>> {
+    /** One answer per question id. */
+    answers: AnswersFor<Q>;
+    /** The model or checkpoint that answered, when the provider says. */
+    model?: string;
+    /** Token usage, when reported. */
+    usage?: DecisionUsage;
+}
+/**
+ * AI decisions provider interface. Implemented by the Laya, Jev and LLM bonds.
+ */
+export interface AIDecisionsProvider {
+    /** Provider identifier. */
+    readonly name: string;
+    /**
+     * Answer every question about `state`.
+     *
+     * @param input - The state, the questions and options.
+     * @returns One typed answer per question id.
+     */
+    decide<Q extends Record<string, DecisionQuestion>>(input: DecideInput<Q>): Promise<DecideResult<Q>>;
+}
+//# 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":"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"}

package/dist/types.js

@@ -0,0 +1,17 @@
+/**
+ * AI decisions provider interface.
+ *
+ * A "decision" is a typed question about a piece of state (text, an email, a
+ * ticket, a JSON document) whose answer is a probability distribution, never
+ * generated text: pick one of N options (`choice`), place it on an ordered
+ * scale (`score`), or say how likely a statement is true (`yesNo`). One call
+ * asks any number of questions about the same state.
+ *
+ * The shape follows the `/v1/systemone` protocol spoken by TypeSafe's Jev and
+ * the open-weights Laya server, but it is provider-neutral: an LLM bond
+ * implements it too.
+ *
+ * @module
+ */
+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;;;;;;;;;;;;;;GAcG"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@molecule/api-ai-decisions",
+  "version": "1.0.0",
+  "description": "Typed AI decisions for molecule.dev — answer choice, score and yes/no questions about text or JSON with calibrated probabilities, behind swappable bonds (Laya, Jev, any LLM)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "molecule",
+    "ai",
+    "decisions",
+    "classification",
+    "routing",
+    "triage",
+    "system-one"
+  ],
+  "license": "Apache-2.0",
+  "author": "Molecule Dev, Inc. (https://molecule.dev)",
+  "peerDependencies": {
+    "@molecule/api-bond": "^1.0.1",
+    "@molecule/api-i18n": "^1.0.1"
+  },
+  "devDependencies": {
+    "@molecule/api-bond": "1.0.2",
+    "@molecule/api-i18n": "1.0.3",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.11"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/api/core/ai-decisions"
+  },
+  "homepage": "https://www.molecule.dev/packages/api-ai-decisions",
+  "bugs": "https://github.com/molecule-dev/molecule/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}