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

package/schemas/decision.config.schema.json

@@ -0,0 +1,553 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "Decision Bridge configuration",
+    "description": "Explicit schemaVersion 1 configuration. Runtime preflight also enforces URL, credential and provider limits.",
+    "oneOf": [
+        {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "$schema": {
+                    "$ref": "#/$defs/text"
+                },
+                "schemaVersion": {
+                    "const": 1
+                },
+                "model": {
+                    "$ref": "#/$defs/text"
+                },
+                "apiKeyEnv": {
+                    "$ref": "#/$defs/keyEnv"
+                },
+                "timeoutMs": {
+                    "$ref": "#/$defs/timeout"
+                },
+                "baseURL": {
+                    "$ref": "#/$defs/text"
+                },
+                "maxRetries": {
+                    "$ref": "#/$defs/retries"
+                },
+                "maxRequestBytes": {
+                    "$ref": "#/$defs/bytes"
+                },
+                "maxResponseBytes": {
+                    "$ref": "#/$defs/bytes"
+                },
+                "provider": {
+                    "const": "jev"
+                }
+            }
+        },
+        {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "$schema": {
+                    "$ref": "#/$defs/text"
+                },
+                "schemaVersion": {
+                    "const": 1
+                },
+                "model": {
+                    "$ref": "#/$defs/text"
+                },
+                "apiKeyEnv": {
+                    "$ref": "#/$defs/keyEnv"
+                },
+                "timeoutMs": {
+                    "$ref": "#/$defs/timeout"
+                },
+                "baseURL": {
+                    "$ref": "#/$defs/text"
+                },
+                "maxRetries": {
+                    "$ref": "#/$defs/retries"
+                },
+                "maxRequestBytes": {
+                    "$ref": "#/$defs/bytes"
+                },
+                "maxResponseBytes": {
+                    "$ref": "#/$defs/bytes"
+                },
+                "provider": {
+                    "const": "openai-decisions"
+                }
+            },
+            "required": [
+                "provider"
+            ]
+        },
+        {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "$schema": {
+                    "$ref": "#/$defs/text"
+                },
+                "schemaVersion": {
+                    "const": 1
+                },
+                "model": {
+                    "$ref": "#/$defs/text"
+                },
+                "apiKeyEnv": {
+                    "$ref": "#/$defs/keyEnv"
+                },
+                "timeoutMs": {
+                    "$ref": "#/$defs/timeout"
+                },
+                "baseURL": {
+                    "$ref": "#/$defs/text"
+                },
+                "maxRetries": {
+                    "$ref": "#/$defs/retries"
+                },
+                "maxRequestBytes": {
+                    "$ref": "#/$defs/bytes"
+                },
+                "maxResponseBytes": {
+                    "$ref": "#/$defs/bytes"
+                },
+                "provider": {
+                    "const": "cloudflare-decisions"
+                },
+                "accountId": {
+                    "$ref": "#/$defs/text"
+                },
+                "rejectIfBusy": {
+                    "$ref": "#/$defs/boolean"
+                },
+                "gateway": {
+                    "$ref": "#/$defs/gateway"
+                }
+            },
+            "required": [
+                "provider"
+            ],
+            "allOf": [
+                {
+                    "if": {
+                        "properties": {
+                            "rejectIfBusy": {
+                                "const": true
+                            }
+                        },
+                        "required": [
+                            "rejectIfBusy"
+                        ]
+                    },
+                    "then": {
+                        "properties": {
+                            "maxRetries": {
+                                "const": 0
+                            },
+                            "gateway": {
+                                "properties": {
+                                    "retries": {
+                                        "properties": {
+                                            "maxAttempts": {
+                                                "const": 1
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            ]
+        },
+        {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "$schema": {
+                    "$ref": "#/$defs/text"
+                },
+                "schemaVersion": {
+                    "const": 1
+                },
+                "model": {
+                    "$ref": "#/$defs/text"
+                },
+                "apiKeyEnv": {
+                    "$ref": "#/$defs/keyEnv"
+                },
+                "timeoutMs": {
+                    "$ref": "#/$defs/timeout"
+                },
+                "baseURL": {
+                    "$ref": "#/$defs/text"
+                },
+                "maxRetries": {
+                    "$ref": "#/$defs/retries"
+                },
+                "maxRequestBytes": {
+                    "$ref": "#/$defs/bytes"
+                },
+                "maxResponseBytes": {
+                    "$ref": "#/$defs/bytes"
+                },
+                "maxTokens": {
+                    "$ref": "#/$defs/tokens"
+                },
+                "responseFormat": {
+                    "$ref": "#/$defs/responseFormat"
+                },
+                "tokenParameter": {
+                    "$ref": "#/$defs/tokenParameter"
+                },
+                "parameters": {
+                    "$ref": "#/$defs/parameters"
+                },
+                "provider": {
+                    "const": "custom-generative"
+                },
+                "preset": {
+                    "const": "openai-compatible"
+                },
+                "noAuth": {
+                    "$ref": "#/$defs/boolean"
+                }
+            },
+            "required": [
+                "provider",
+                "preset"
+            ]
+        },
+        {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "$schema": {
+                    "$ref": "#/$defs/text"
+                },
+                "schemaVersion": {
+                    "const": 1
+                },
+                "model": {
+                    "$ref": "#/$defs/text"
+                },
+                "apiKeyEnv": {
+                    "$ref": "#/$defs/keyEnv"
+                },
+                "timeoutMs": {
+                    "$ref": "#/$defs/timeout"
+                },
+                "maxRetries": {
+                    "$ref": "#/$defs/retries"
+                },
+                "maxRequestBytes": {
+                    "$ref": "#/$defs/bytes"
+                },
+                "maxResponseBytes": {
+                    "$ref": "#/$defs/bytes"
+                },
+                "maxTokens": {
+                    "$ref": "#/$defs/tokens"
+                },
+                "responseFormat": {
+                    "$ref": "#/$defs/responseFormat"
+                },
+                "tokenParameter": {
+                    "$ref": "#/$defs/tokenParameter"
+                },
+                "parameters": {
+                    "$ref": "#/$defs/parameters"
+                },
+                "provider": {
+                    "const": "custom-generative"
+                },
+                "preset": {
+                    "const": "openrouter"
+                }
+            },
+            "required": [
+                "provider",
+                "preset"
+            ]
+        },
+        {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "$schema": {
+                    "$ref": "#/$defs/text"
+                },
+                "schemaVersion": {
+                    "const": 1
+                },
+                "model": {
+                    "$ref": "#/$defs/text"
+                },
+                "apiKeyEnv": {
+                    "$ref": "#/$defs/keyEnv"
+                },
+                "timeoutMs": {
+                    "$ref": "#/$defs/timeout"
+                },
+                "baseURL": {
+                    "$ref": "#/$defs/text"
+                },
+                "maxRetries": {
+                    "$ref": "#/$defs/retries"
+                },
+                "maxRequestBytes": {
+                    "$ref": "#/$defs/bytes"
+                },
+                "maxResponseBytes": {
+                    "$ref": "#/$defs/bytes"
+                },
+                "maxTokens": {
+                    "$ref": "#/$defs/tokens"
+                },
+                "parameters": {
+                    "allOf": [
+                        {
+                            "$ref": "#/$defs/parameters"
+                        },
+                        {
+                            "properties": {
+                                "thinking": false
+                            }
+                        }
+                    ]
+                },
+                "provider": {
+                    "const": "custom-generative"
+                },
+                "preset": {
+                    "const": "anthropic"
+                }
+            },
+            "required": [
+                "provider",
+                "preset"
+            ]
+        },
+        {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "$schema": {
+                    "$ref": "#/$defs/text"
+                },
+                "schemaVersion": {
+                    "const": 1
+                },
+                "model": {
+                    "$ref": "#/$defs/text"
+                },
+                "apiKeyEnv": {
+                    "$ref": "#/$defs/keyEnv"
+                },
+                "timeoutMs": {
+                    "$ref": "#/$defs/timeout"
+                },
+                "provider": {
+                    "const": "custom-decision"
+                },
+                "module": {
+                    "$ref": "#/$defs/text"
+                },
+                "options": {
+                    "$ref": "#/$defs/options"
+                }
+            },
+            "required": [
+                "provider",
+                "module"
+            ]
+        },
+        {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "$schema": {
+                    "$ref": "#/$defs/text"
+                },
+                "schemaVersion": {
+                    "const": 1
+                },
+                "model": {
+                    "$ref": "#/$defs/text"
+                },
+                "apiKeyEnv": {
+                    "$ref": "#/$defs/keyEnv"
+                },
+                "timeoutMs": {
+                    "$ref": "#/$defs/timeout"
+                },
+                "provider": {
+                    "const": "custom-generative"
+                },
+                "module": {
+                    "$ref": "#/$defs/text"
+                },
+                "options": {
+                    "$ref": "#/$defs/options"
+                }
+            },
+            "required": [
+                "provider",
+                "module"
+            ]
+        }
+    ],
+    "$defs": {
+        "text": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S"
+        },
+        "keyEnv": {
+            "type": "string",
+            "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+        },
+        "timeout": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 2147483647
+        },
+        "bytes": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 67108864
+        },
+        "retries": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 10
+        },
+        "tokens": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 1048576
+        },
+        "boolean": {
+            "type": "boolean"
+        },
+        "responseFormat": {
+            "enum": [
+                "json_schema",
+                "json_object",
+                "text"
+            ]
+        },
+        "tokenParameter": {
+            "enum": [
+                "max_completion_tokens",
+                "max_tokens"
+            ]
+        },
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "model": false,
+                "messages": false,
+                "system": false,
+                "tools": false,
+                "tool_choice": false,
+                "toolChoice": false,
+                "functions": false,
+                "function_call": false,
+                "response_format": false,
+                "stream": false,
+                "stream_options": false,
+                "n": false,
+                "max_tokens": false,
+                "max_completion_tokens": false,
+                "headers": false,
+                "apiKey": false,
+                "api_key": false,
+                "baseURL": false,
+                "authorization": false
+            }
+        },
+        "options": {
+            "type": "object",
+            "properties": {
+                "apiKey": false,
+                "api_key": false
+            }
+        },
+        "gateway": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+                "id"
+            ],
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 64,
+                    "pattern": "^[\\x20-\\x7e]*\\S[\\x20-\\x7e]*$"
+                },
+                "cacheKey": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 200,
+                    "pattern": "^[\\x20-\\x7e]*\\S[\\x20-\\x7e]*$"
+                },
+                "cacheTtl": {
+                    "type": "integer",
+                    "minimum": 60,
+                    "maximum": 2592000
+                },
+                "skipCache": {
+                    "type": "boolean"
+                },
+                "collectLog": {
+                    "type": "boolean"
+                },
+                "requestTimeoutMs": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 2147483647
+                },
+                "metadata": {
+                    "type": "object",
+                    "maxProperties": 5,
+                    "propertyNames": {
+                        "not": {
+                            "pattern": "^cf\\."
+                        }
+                    },
+                    "additionalProperties": {
+                        "type": [
+                            "string",
+                            "number",
+                            "boolean",
+                            "null"
+                        ]
+                    }
+                },
+                "retries": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                        "maxAttempts": {
+                            "type": "integer",
+                            "minimum": 1,
+                            "maximum": 5
+                        },
+                        "retryDelayMs": {
+                            "type": "integer",
+                            "minimum": 0,
+                            "maximum": 60000
+                        },
+                        "backoff": {
+                            "enum": [
+                                "constant",
+                                "linear",
+                                "exponential"
+                            ]
+                        }
+                    }
+                }
+            }
+        }
+    }
+}

package/src/async.mjs

@@ -0,0 +1,63 @@
+import { DecisionError, requireCondition as check } from './errors.mjs';
+
+// Carry absolute deadlines through our nested AbortSignals without changing their public shape.
+const signalDeadlines = new WeakMap();
+
+export function validateSignal(signal) {
+  check(signal === undefined || signal instanceof AbortSignal,
+    'signal must be an AbortSignal.', 'CONFIGURATION_ERROR');
+}
+
+export function abortError() {
+  return new DecisionError('Request cancelled by caller.', { code: 'ABORTED' });
+}
+
+/** Bound caller-visible waiting even when user-supplied code ignores the signal. */
+export function withSignal(promise, signal) {
+  if (!signal) return Promise.resolve(promise);
+  if (signal.aborted) {
+    Promise.resolve(promise).catch(() => {});
+    return Promise.reject(abortError());
+  }
+  return new Promise((resolve, reject) => {
+    const aborted = () => { cleanup(); reject(abortError()); };
+    const cleanup = () => signal.removeEventListener('abort', aborted);
+    signal.addEventListener('abort', aborted, { once: true });
+    Promise.resolve(promise).then(
+      value => { cleanup(); resolve(value); },
+      error => { cleanup(); reject(error); },
+    );
+  });
+}
+
+export function deadline(timeoutMs, parent) {
+  validateSignal(parent);
+  check(Number.isSafeInteger(timeoutMs) && timeoutMs > 0 && timeoutMs <= 2147483647,
+    'timeoutMs must be a positive 32-bit integer.', 'CONFIGURATION_ERROR');
+  const controller = new AbortController();
+  const expiresAt = Math.min(performance.now() + timeoutMs, signalDeadlines.get(parent) ?? Infinity);
+  signalDeadlines.set(controller.signal, expiresAt);
+  let timedOut = false;
+  let closed = false;
+  const expire = () => { timedOut = true; controller.abort(); };
+  // Timers cannot fire during synchronous validation, encoding or user callbacks.
+  const refresh = () => {
+    if (!closed && !controller.signal.aborted && performance.now() >= expiresAt) expire();
+  };
+  const cancel = () => controller.abort();
+  if (parent?.aborted) cancel();
+  parent?.addEventListener('abort', cancel, { once: true });
+  const timer = setTimeout(expire, Math.max(0, Math.ceil(expiresAt - performance.now())));
+  return {
+    signal: controller.signal,
+    get timedOut() { refresh(); return timedOut; },
+    get remainingMs() { return Math.max(0, expiresAt - performance.now()); },
+    throwIfAborted() { refresh(); if (controller.signal.aborted) throw abortError(); },
+    close() {
+      closed = true;
+      clearTimeout(timer);
+      signalDeadlines.delete(controller.signal);
+      parent?.removeEventListener('abort', cancel);
+    },
+  };
+}

package/src/batch.mjs

@@ -0,0 +1,38 @@
+import { optionsObject } from './options.mjs';
+import { requireCondition as check, publicError } from './errors.mjs';
+import { validateRequest } from './validation.mjs';
+import { validateSignal } from './async.mjs';
+import { assertCapabilities, LEGACY_CAPABILITIES } from './capabilities.mjs';
+
+/** Ordered, bounded-concurrency batch. Validate every input before spending. */
+export async function evaluateBatch(bridge, inputs, options = {}) {
+  const { concurrency = 4, signal, stopOnError = false } = optionsObject(options, ['concurrency', 'signal', 'stopOnError'], 'Batch options');
+  check(bridge && typeof bridge.evaluate === 'function', 'A bridge is required.', 'CONFIGURATION_ERROR');
+  check(Array.isArray(inputs) && inputs.length <= 10000, 'inputs must be an array of at most 10000 requests.');
+  check(Number.isSafeInteger(concurrency) && concurrency >= 1 && concurrency <= 64,
+    'concurrency must be an integer from 1 to 64.', 'CONFIGURATION_ERROR');
+  check(typeof stopOnError === 'boolean', 'stopOnError must be boolean.', 'CONFIGURATION_ERROR');
+  validateSignal(signal);
+  const requests = Array.from(inputs, input => typeof bridge.validate === 'function' ? bridge.validate(input)
+    : assertCapabilities(validateRequest(input, bridge.defaultModel ?? ''), LEGACY_CAPABILITIES));
+  const results = new Array(requests.length);
+  let next = 0;
+  let stopped = false;
+  async function worker() {
+    while (next < requests.length) {
+      if (signal?.aborted || stopped) return;
+      const index = next++;
+      try { results[index] = { index, ok: true, result: await bridge.evaluate(requests[index], { signal }) }; }
+      catch (error) {
+        results[index] = { index, ok: false, error: publicError(error) };
+        if (stopOnError) stopped = true;
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(concurrency, requests.length) }, worker));
+  for (let index = 0; index < results.length; index++) {
+    results[index] ??= { index, ok: false, error: { code: signal?.aborted ? 'ABORTED' : 'BATCH_SKIPPED',
+      message: signal?.aborted ? 'Request cancelled before dispatch.' : 'Request skipped after a batch failure.' } };
+  }
+  return results;
+}