@fayegram-ai/decision-bridge 0.0.0-stage → 0.1.0

package/docs/guides/CUSTOM_GENERATIVE.md

@@ -0,0 +1,164 @@
+# Custom generative providers
+
+This opt-in path elicits decisions from general-purpose models. It retains the
+maintained OpenAI-compatible, OpenRouter, and Anthropic adapters. Import them from
+`@fayegram-ai/decision-bridge/custom/generative`; the root factory accepts native
+decision providers only.
+
+## Use a maintained preset
+
+```javascript
+import { createBridge, noul } from '@fayegram-ai/decision-bridge';
+import { createGenerativeProvider } from '@fayegram-ai/decision-bridge/custom/generative';
+
+const provider = createGenerativeProvider({
+    type: 'openrouter',
+    model: process.env.DECISION_MODEL, // A model available through your account.
+});
+const bridge = createBridge({ provider });
+const result = await bridge.evaluate({
+    state: 'Test report: two assertions failed.',
+    questions: { failure: noul('Does the report explicitly state that a test failed?') },
+});
+console.log(result.meta.providerKind);      // generative
+console.log(result.meta.probabilitySource); // elicited
+```
+
+Set `OPENROUTER_API_KEY` and a real `DECISION_MODEL`, then load your environment
+explicitly with Node or your application's configuration. Evaluation is a real
+service call. Presets have no default model. The classes `OpenAICompatibleProvider`,
+`OpenRouterProvider`, and `AnthropicProvider` and their option types are exported
+from the same subpath.
+
+## CLI presets
+
+```bash
+npm exec -- decision-bridge init ./my-model --provider custom-generative --preset openrouter --model VENDOR/MODEL_ID
+npm exec -- decision-bridge evaluate ./my-model/request.json --config ./my-model/decision.config.json --env-file .env
+```
+
+Use `--preset openai-compatible` or `--preset anthropic` for the other protocols.
+A configuration selects exactly one preset or module:
+
+```json
+{
+    "schemaVersion": 1,
+    "provider": "custom-generative",
+    "preset": "openai-compatible",
+    "model": "YOUR_MODEL_ID",
+    "apiKeyEnv": "OPENAI_API_KEY",
+    "responseFormat": "json_schema",
+    "timeoutMs": 30000
+}
+```
+
+For a loopback server, set `baseURL`, `noAuth: true`, the served model, and the
+appropriate `tokenParameter`. Remote custom origins require explicit credentials.
+See [configuration](../reference/CONFIGURATION.md).
+
+## A new protocol
+
+Use `defineGenerativeProvider` for a module implementing a new wire protocol.
+`init --provider custom-generative` creates a module with a clear unimplemented
+service call; it never produces synthetic decisions as a fallback.
+
+The subpath exports `buildResponseSchema(questions)`, `buildPrompt(request)`,
+`parseGeneratedJson(text)`, and `normalizeGenerated(payload, request, options)`.
+Build a prompt/schema from a validated, resolved legacy request, send it using
+transport you own, parse the generated JSON, then normalize it. The normalizer
+expects exactly `{ answers }`: each `noul` answer contains `{ noul }`, and each
+choice/score contains `{ probabilities }` with exactly the supplied option keys
+or zero-based level indices. It checks probabilities, derives argmax/weighted
+scores and matching legends, and marks absent usage as unknown. It does not repair
+JSON, strip Markdown, or create confidence. `buildPrompt` and `normalizeGenerated`
+independently validate and snapshot the request. They require shared state and
+legacy questions, and reject ordered input, typed choices, labelled scores, and
+safety identifiers with `UNSUPPORTED_CAPABILITY`. Malformed request JSON raises
+`VALIDATION_ERROR`; unsupported input is never silently discarded. New modules
+implement their own encoding and normalization for richer capabilities.
+
+| Helper | Return value and responsibility |
+| --- | --- |
+| `buildResponseSchema(questions)` | JSON Schema for legacy question answers; validates the definitions without selecting an inference model |
+| `buildPrompt(request)` | `{ system, user }` strings for a resolved shared-state request; requires a model in the request |
+| `parseGeneratedJson(text)` | Parsed JSON; rejects empty or malformed content with `INVALID_RESPONSE`; answer validation happens in normalization |
+| `normalizeGenerated(payload, request, options?)` | Canonical, validated `{ model, answers, usage, meta }`; returns a snapshot that the bridge subsequently freezes |
+
+The normalizer's optional third argument accepts `model`, `usage`, and `meta`:
+
+| Field | Meaning |
+| --- | --- |
+| `model` | Reported nonempty model ID; omission or null uses `request.model` and marks `modelSource: 'requested'` |
+| `usage` | Validated common token counts, with null for unreported counts; omission produces null input/output counts |
+| `meta` | Additional JSON metadata from your transport; normalization supplies authoritative `requestedModel`, `modelSource`, `probabilitySource: 'elicited'`, and `confidenceSource: 'unavailable'` |
+
+None of these helpers sends a request. Your provider supplies the transport,
+cancellation, response extraction, and safe error handling. Use the
+[common usage and metadata contract](../reference/SDK.md#returned-data) for the
+reported fields; the bridge adds its own classification and final timings.
+
+A runnable delegation module is provided at
+[examples/custom/generative-provider.mjs](../../examples/custom/generative-provider.mjs).
+Use the shared [module contract](CUSTOM_PROVIDERS.md) for loader options, timeouts,
+capabilities, and testing requirements. No arbitrary declarative HTTP mapping
+language is supported.
+
+## Result semantics
+
+These providers have `kind: 'generative'`. The bridge requires elicited probability
+provenance and `confidenceSource: 'unavailable'`, and rejects returned native
+confidence claims or answer confidence fields. Their output is an estimate elicited
+from a model, not a native probability, logprob, or calibration guarantee.
+Presets support shared state and legacy `choice`, `noul`, and `score`; ordered
+media, typed choices, labelled scores, and safety identifiers are unsupported.
+A new module may declare capabilities only after implementing and validating them.
+
+## OpenAI-compatible servers
+
+Default base URL: `https://api.openai.com/v1`. Base paths such as `/v1` are preserved;
+provide the API base, not the final `/chat/completions` path.
+
+`json_schema` sends `response_format.type = json_schema`, `strict: true`, and a
+schema whose required object fields disallow additional properties. Ranges and
+normalization are validated locally to accommodate different supported schema
+subsets. `json_object` requests JSON without schema enforcement. `text` omits the
+format field and relies on instructions plus strict local validation.
+
+There is **no auto mode**: an unsupported schema error is visible rather than
+triggering a second request with weaker enforcement. A refusal, truncated output,
+malformed JSON, probability violation, or unexpected tool call is an explicit
+error. No Markdown stripping or JSON repair occurs.
+
+The default token field is `max_completion_tokens`. Some compatible servers need
+`max_tokens`; set `tokenParameter` explicitly. No temperature or reasoning setting
+is forced. Additional generation parameters must be supported by the selected
+model. Presets reserve current and legacy tool/function controls, including
+`functions` and `function_call`, to preserve their answer-output protocol. Use a
+custom module when you need to implement a different protocol.
+This provider does not implement OpenAI Responses API, realtime streaming,
+multimodal inputs, or a general function-calling agent loop.
+
+## OpenRouter
+
+`OpenRouterProvider` is a fixed-endpoint generative preset. It reads its own key
+and defaults to `max_tokens`. It sets
+`parameters.provider.require_parameters = true` so required request features are
+not silently ignored by routing. Other explicit routing settings are preserved.
+The preset does not guarantee which upstream host serves a model; use OpenRouter's
+routing controls for stricter requirements.
+
+Select a **generative model** that supports the chosen output mode. Other API
+protocols require an explicit [custom provider](CUSTOM_PROVIDERS.md).
+
+## Anthropic
+
+The provider sends Messages API headers `x-api-key` and
+`anthropic-version: 2023-06-01`. It defines a synthetic `submit_decisions` tool whose
+input schema is the expected answer object, then forces exactly that tool. The
+returned `tool_use.input` carries the data; **no tool is executed** and no follow-up
+agent cycle is started.
+
+Extended thinking is not enabled in this forced-tool strategy; a `thinking`
+parameter is rejected. Refusals, truncated output, unexpected stop reasons, and
+missing/extra named tools fail. `GET /v1/models` returns the first page with
+`has_more` / `last_id` preserved. Automatic pagination is not implemented.

package/docs/guides/CUSTOM_PROVIDERS.md

@@ -0,0 +1,81 @@
+# Custom provider contracts
+
+Decision Bridge has one bridge and two explicit extension paths:
+
+| Path | SDK helper | CLI provider | Purpose |
+| --- | --- | --- | --- |
+| [Custom decision](CUSTOM_DECISION.md) | `defineDecisionProvider` from `custom/decision` | `custom-decision` with `module` | A new decision model protocol |
+| [Custom generative](CUSTOM_GENERATIVE.md) | `defineGenerativeProvider` from `custom/generative` | `custom-generative` with `preset` or `module` | Elicit structured decisions from a general-purpose model |
+
+The root `createProvider()` factory supports native Jev, OpenAI Decisions, and
+Cloudflare only. `createGenerativeProvider()` selects maintained generative
+presets. Select the corresponding custom entry point explicitly for either
+extension path.
+
+## Common SDK contract
+
+`Provider` requires a nonempty `name`, explicit `kind: 'decision' | 'generative'`,
+and `evaluate(request, { signal? })`. Optional fields and hooks are:
+
+- `defaultModel`: a nonempty model ID, otherwise the request must supply one.
+- `probabilitySource`: known provenance; generative providers use `elicited`.
+- `getCapabilities(model)`: a pure synchronous capability profile.
+- `validateRequest(request)`: pure synchronous provider preflight; no inference.
+- `getResultValidationOptions(model)`: pure synchronous probability precision
+  policy, never derived from a response or its metadata.
+- `listModels({ signal? })`: a model catalog when the service implements one.
+
+Both definition helpers validate plain data definitions and freeze their wrappers.
+Callbacks keep their original receiver. The bridge also accepts provider classes
+that implement this contract directly. Missing or invalid kinds fail at construction.
+`bridge.providerKind` and `result.meta.providerKind` come from the contract and
+cannot be overridden by response metadata.
+
+The request is already snapshotted, validated, resolved to a model, and frozen.
+Return canonical `{ model, answers, usage, meta? }`; the bridge validates and
+freezes the result. Custom providers own API encoding, transport, response mapping,
+credential destinations, bounded bodies, safe errors, and cancellation cleanup.
+Internal transport helpers are not stable public exports. Delegate a maintained
+preset for a protocol already supported, or implement and test your own transport.
+
+Capability omissions retain the legacy shared-state and question profile. Audio
+and video additions default to false/zero. Declare richer forms only when their
+encoding and validation are implemented. The bridge runs preflight again after
+preparation hooks. Unknown usage is null; no provider should invent token counts,
+confidence, or calibration. Generative native-provenance claims are rejected.
+Supplied `probabilitySource` and `confidenceSource` metadata must be nonempty
+strings. Decision providers may use custom labels; omitted probability provenance
+uses the provider's declared value, or `unspecified` when none is declared.
+
+## Explicit CLI modules
+
+Select a custom kind and `module` in JSON, or pass both `--provider custom-decision`
+(or `custom-generative`) and `--provider-module FILE`. A module flag does not infer
+a kind. A generative profile chooses exactly one `preset` or `module`; module
+profiles require JSON `options` for implementation-specific transport/tuning.
+Inline `apiKey`/`api_key` options are rejected; use top-level `apiKeyEnv`.
+
+The module exports `createProvider(options)`, synchronously or asynchronously.
+Import/factory waiting is bounded by `timeoutMs` (30 seconds by default) and CLI
+cancellation, separately from evaluation. The loader passes JSON `options`, then
+the selected `apiKey` and `model` when present. Its returned kind must match the
+selected path. The CLI also applies its configured model to common requests that
+omit a model, independently of the factory's own default; an explicit request
+model takes precedence, and `--model` overrides both. Module paths in JSON resolve
+relative to that file; flag paths
+resolve relative to the working directory. Explicit modules execute trusted code;
+this extension point is not a sandbox. No module is discovered automatically.
+
+`init` creates an honest service implementation placeholder when no implementation
+is selected. When given an existing module, it references that module without
+loading or overwriting it. Offline `validate` never imports custom modules or
+requires credentials; it reports structure-only validation for unknown protocols.
+`bridge.validate()` on an instantiated provider includes capabilities and preflight.
+
+## Tests for a new protocol
+
+Test serialized bodies, credentials/headers, endpoint paths, all supported question
+mappings, usage/provenance, refusals/truncation, malformed distributions, timeouts,
+cancellation, and safe errors. Use local HTTP fixtures for deterministic protocol
+checks. Live tests must be explicit and credential-dependent; fixture tests do
+not establish model quality. See [testing](../development/TESTING.md).

package/docs/guides/GETTING_STARTED.md

@@ -0,0 +1,252 @@
+# Getting started
+
+Use the SDK from your JavaScript or TypeScript application to submit `state` and
+`questions` and receive structured answers. The optional command runner can also
+evaluate request files.
+
+## Prerequisites
+
+This guide's example uses Node.js **22.16 or newer**, npm, and a TypeSafe API key
+for the explicitly selected Jev provider. The SDK also loads in modern browsers; direct calls
+depend on the provider's CORS policy and an explicit client-safe credential. See
+[browser integration](BROWSER.md). Other backends use their own keys; see
+[switching models](SWITCHING_MODELS.md).
+
+## Install into your application
+
+In your application's directory, install the package from npm:
+
+```bash
+npm install @fayegram-ai/decision-bridge
+```
+
+You can also install a verified local archive, replacing the path below. See
+[packaging and release](../development/RELEASING.md) to build and verify one from
+a source checkout:
+
+```bash
+npm install /path/to/fayegram-ai-decision-bridge-0.1.0.tgz
+```
+
+The installed package contains the SDK, declarations, command runner, examples,
+and docs. It runs without compilation; source development scripts and tests are
+excluded.
+
+## Configure credentials
+
+Create `.env` in your application's directory and edit it locally:
+
+```dotenv
+TYPESAFE_API_KEY=your_real_key_here
+```
+
+Add `.env` to your application's `.gitignore`. The SDK reads `TYPESAFE_API_KEY`
+from the process environment when constructing the selected Jev provider. It does not load
+`.env` itself; the Node startup command below loads it explicitly. In a deployed
+application, you can supply the same variable through your runtime's environment.
+
+## Make your first SDK call
+
+Save this as `app.mjs` beside `.env`. The `.mjs` extension enables ESM regardless
+of your application's `package.json` settings:
+
+```javascript
+import { createBridge, choice, noul, publicError } from '@fayegram-ai/decision-bridge';
+
+try {
+    const bridge = createBridge({ jev: {} }); // Jev; defaults to model jev-latest.
+    const result = await bridge.evaluate({
+        state: { message: 'I was charged twice for the same invoice.' },
+        questions: {
+            route: choice('Which team should inspect this message?', {
+                billing: 'Invoices, charges, or payment problems.',
+                technical: 'Software defects or connectivity problems.',
+                unknown: 'The evidence does not establish a team.',
+            }),
+            duplicate_charge: noul('Does the message report a duplicate charge?'),
+        },
+    });
+    console.log(result.answers.route.choice);
+    console.log(result.answers.duplicate_charge.noul);
+    console.log(result.model, result.meta.probabilitySource);
+} catch (error) {
+    console.error(publicError(error));
+    process.exitCode = 1;
+}
+```
+
+Run it from your application directory:
+
+```bash
+node --env-file=.env app.mjs
+```
+
+This sends one real evaluation and may incur charges. `route.choice` is one of
+`billing`, `technical`, or `unknown`; `duplicate_charge.noul` is a probability
+between 0 and 1. `result.model` identifies the returned model, and Jev marks its
+probability source as `native`. Predictions depend on the model. Your application
+decides how to use them; the SDK does not route messages or execute actions.
+
+Change `state` and the question instructions/criteria on each call. No prompt
+registration is required. Reuse the bridge for subsequent requests. To choose
+a Jev model explicitly, construct it with `createBridge({ jev: { model: 'YOUR_MODEL' } })`,
+using an ID available to your account. An individual request's `model` overrides
+that default. See the [SDK reference](../reference/SDK.md) for scores, result
+metadata, cancellation, batching, and extensions.
+
+Bridge construction can fail for invalid configuration or missing credentials;
+evaluation can fail for invalid input or provider errors. Both are inside the
+example's `try` block. `publicError(error)` returns a safe `code` and `message`, plus
+HTTP status, request ID, and attempt count when available. See [errors and recovery](../reference/ERRORS.md).
+
+SDK selection is explicit: use `createBridge({ provider })` with a constructed
+provider or `createBridge({ jev: options })` for Jev. Empty options and omitted
+options are errors. `createProvider` also requires its `type` explicitly.
+The CLI has its own Jev default and does not change SDK selection rules.
+
+## TypeScript
+
+Declarations ship with the package. For a standalone Node TypeScript example,
+install these development tools in the consuming application (TypeScript 5.8.3
+is the compiler used by this repository's CI):
+
+```bash
+npm install --save-dev typescript@5.8.3 @types/node@22
+```
+
+Create `tsconfig.json`, or incorporate these settings into your existing config:
+
+```json
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "NodeNext",
+        "moduleResolution": "NodeNext",
+        "strict": true,
+        "outDir": "dist",
+        "types": ["node"]
+    },
+    "include": ["app.mts"]
+}
+```
+
+Save this as `app.mts`. The `.mts` extension makes it an ESM module and produces
+`dist/app.mjs`; no `"type": "module"` setting is needed for this example:
+
+```typescript
+import { createBridge, choice, publicError } from '@fayegram-ai/decision-bridge';
+
+try {
+    const bridge = createBridge({ jev: {} });
+    const result = await bridge.evaluate({
+        state: 'An invoice appears twice.',
+        questions: {
+            route: choice('Which team should inspect this?', {
+                billing: 'An invoice or payment issue.',
+                unknown: 'Insufficient evidence.',
+            }),
+        },
+    });
+    // The builder preserves the allowed labels in the answer type.
+    const route: 'billing' | 'unknown' = result.answers.route.choice;
+    const probability: number = result.answers.route.probabilities[route];
+    console.log(route, probability);
+} catch (error) {
+    console.error(publicError(error));
+    process.exitCode = 1;
+}
+```
+
+Compile, then run with the same environment file:
+
+```bash
+npm exec -- tsc --project tsconfig.json
+node --env-file=.env dist/app.mjs
+```
+
+## Existing CommonJS applications
+
+Use dynamic import from an async function in a `.cjs` module:
+
+```javascript
+async function main() {
+    const { createBridge, noul } = await import('@fayegram-ai/decision-bridge');
+    const bridge = createBridge({ jev: {} });
+    const result = await bridge.evaluate({
+        state: 'The test log reports a failure.',
+        questions: { failed: noul('Does the log report a failed test?') },
+    });
+    console.log(result.answers.failed.noul);
+}
+
+main().catch(() => {
+    console.error('Evaluation failed. Check credentials and request configuration.');
+    process.exitCode = 1;
+});
+```
+
+Save it as `app.cjs` and run `node --env-file=.env app.cjs`. The package exposes an
+ESM import entry; it does not provide a native `require()` entry.
+
+## Optional command runner
+
+After a local package installation, use `npm exec` from the consuming project:
+
+```bash
+npm exec -- decision-bridge init ./my-decisions
+npm exec -- decision-bridge validate ./my-decisions/request.json
+```
+
+`init` creates `decision.config.json`, `decision.config.schema.json`, `request.json`,
+`.env.example`, and `.gitignore`; existing files are never overwritten. The config's
+`$schema` points to the copied schema for editor completion. `validate` checks the request offline.
+Copy the generated `.env.example` to `.env` inside `my-decisions`, then edit its key.
+Evaluate the generated request with explicit paths:
+
+```bash
+npm exec -- decision-bridge evaluate ./my-decisions/request.json --config ./my-decisions/decision.config.json --env-file ./my-decisions/.env
+```
+
+The command runner does not discover `.env` or configuration files automatically.
+Paths are relative to the working directory, except custom provider module paths
+inside a config file, which are relative to that file. The [command reference](../reference/CLI.md)
+covers commands, flags, streams, and exit codes.
+
+Global installation is optional:
+
+```bash
+npm install --global @fayegram-ai/decision-bridge
+decision-bridge --version
+```
+
+The package also installs `decision` and `faye-decision` as equivalent CLI aliases.
+For example, `npm exec -- faye-decision --version` runs the same command runner.
+The shorter `decision` alias may collide with an existing executable; prefer
+`decision-bridge` or `faye-decision` in automation.
+
+## Run from a source checkout
+
+For repository development, open a terminal at the source root. Copy `.env.example`
+to `.env` (`cp .env.example .env` on macOS/Linux or `Copy-Item .env.example .env`
+in PowerShell), then edit the key locally. Run:
+
+```bash
+npm ci --ignore-scripts
+npm test
+npm run validate
+npm run models
+npm run ask
+npm run example
+```
+
+`npm ci --ignore-scripts` installs the pinned development dependencies from the
+lockfile; it can access the npm registry and requires no model credentials.
+`npm test` and `npm run validate` are offline. `models` lists account models; `ask` evaluates
+`examples/request.json`; `example` runs the source SDK example. The last three
+explicitly load `.env` when present and access the provider. A model listing does
+not prove inference access; evaluation verifies that path.
+
+Source examples import `../src/index.mjs` and run directly without installing the
+package. Application code should use `@fayegram-ai/decision-bridge` as shown above.
+See [platform setup](PLATFORMS.md) for operating-system details and
+[contributor documentation](../development/README.md) for development checks.