nexus-ai-pro 2.3.0 → 2.4.0

package/dist/types/config.d.ts

@@ -25,6 +25,11 @@ export interface OpenAIProviderConfig {
     apiKey: string;
     /** API base URL. Point it at an OpenAI-compatible server to use that instead. */
     baseUrl?: string;
+    /**
+     * Replaces the global `fetch` for every request: a platform's bound fetch on an edge runtime, a
+     * proxy, or a stub in tests.
+     */
+    fetch?: typeof globalThis.fetch;
     /** OpenAI organization to bill. */
     organization?: string;
     /** Headers added to every request. */
@@ -59,6 +64,11 @@ export interface AnthropicProviderConfig {
     apiKey: string;
     /** API base URL. */
     baseUrl?: string;
+    /**
+     * Replaces the global `fetch` for every request: a platform's bound fetch on an edge runtime, a
+     * proxy, or a stub in tests.
+     */
+    fetch?: typeof globalThis.fetch;
     /** Name this provider registers under. */
     providerName?: string;
     /** Model-name prefixes this provider answers for. */
@@ -75,6 +85,11 @@ export interface GoogleProviderConfig {
     apiKey: string;
     /** API base URL. */
     baseUrl?: string;
+    /**
+     * Replaces the global `fetch` for every request: a platform's bound fetch on an edge runtime, a
+     * proxy, or a stub in tests.
+     */
+    fetch?: typeof globalThis.fetch;
 }
 /** Configuration for a local Ollama server. */
 export interface OllamaProviderConfig {
@@ -101,6 +116,11 @@ export interface CohereProviderConfig {
     apiKey: string;
     /** API base URL. */
     baseUrl?: string;
+    /**
+     * Replaces the global `fetch` for every request: a platform's bound fetch on an edge runtime, a
+     * proxy, or a stub in tests.
+     */
+    fetch?: typeof globalThis.fetch;
 }
 export interface OpenRouterProviderConfig {
     apiKey: string;

package/dist/types/server.d.ts

@@ -7,6 +7,7 @@
  * anything that can stream events for an input, which a compiled graph already does.
  */
 import type { Principal } from './principal.js';
+import type { RunFeedback } from './tracing.js';
 export type { Principal };
 /** Where a run stands, as the server reports it. */
 export type RunStatus = 'queued' | 'running' | 'awaiting_input' | 'succeeded' | 'failed' | 'cancelled' | 'expired';
@@ -75,6 +76,11 @@ export interface RunRecord {
     worker?: string;
     /** Its latest attempt, starting at 1. */
     attempt?: number;
+    /**
+     * Scores left on the run by people or by online evaluation, through `POST /runs/:runId/feedback`
+     * or `Deployments.evaluate()`. A canary guard compares them between revisions as its quality signal.
+     */
+    feedback?: RunFeedback[];
 }
 /** Why a run got the revision it did. */
 export type RevisionReason = 'split' | 'thread' | 'requested';

package/dist/utils/base64.d.ts

@@ -0,0 +1,4 @@
+/** Base64 text as bytes, in a buffer of their own, so typed-array views of it are aligned. */
+export declare function decodeBase64(data: string): Uint8Array;
+/** Bytes as base64 text. */
+export declare function encodeBase64(bytes: Uint8Array): string;

package/dist/utils/base64.js

@@ -0,0 +1,21 @@
+const host = () => globalThis.Buffer;
+export function decodeBase64(data) {
+    const buffer = host();
+    if (buffer)
+        return new Uint8Array(buffer.from(data, 'base64'));
+    const binary = atob(data);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1)
+        bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}
+export function encodeBase64(bytes) {
+    const buffer = host();
+    if (buffer)
+        return buffer.from(bytes).toString('base64');
+    let binary = '';
+    for (let index = 0; index < bytes.length; index += 0x8000) {
+        binary += String.fromCharCode(...bytes.subarray(index, index + 0x8000));
+    }
+    return btoa(binary);
+}

package/dist/utils/checksums.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Checks that tell a real identifier from a number that only looks like one. Every detector of card
+ * numbers and account numbers uses them, so an order id or a millisecond timestamp is never masked as
+ * a card.
+ */
+/** Whether a card number passes the Luhn check, with 13 to 19 digits; spaces and dashes are ignored. */
+export declare function luhn(value: string): boolean;
+/** Whether an IBAN passes its mod-97 check, with 15 to 34 characters; spaces are ignored. */
+export declare function ibanChecksum(value: string): boolean;
+/** Whether a phone-like match has as many digits as a phone number can: 10 to 15. */
+export declare function phoneDigits(value: string): boolean;
+/**
+ * Whether a match reads as a phone number: 10 to 15 digits, written with a leading `+` or with
+ * separators. A bare run of digits is an id or a timestamp far more often than a phone number.
+ */
+export declare function phoneNumber(value: string): boolean;
+/**
+ * Text as a detector should read it: Unicode compatibility forms folded (full-width letters become
+ * ASCII), and the invisible characters an attacker uses to split a phrase removed, so
+ * `ｉｇｎｏｒｅ` and `ig​nore` read as `ignore`.
+ */
+export declare function normalizeForDetection(text: string): string;

package/dist/utils/checksums.js

@@ -0,0 +1,39 @@
+export function luhn(value) {
+    const digits = value.replace(/[\s-]/g, '');
+    if (!/^\d{13,19}$/.test(digits))
+        return false;
+    let sum = 0;
+    for (let index = 0; index < digits.length; index += 1) {
+        let digit = Number(digits[digits.length - 1 - index]);
+        if (index % 2 === 1) {
+            digit *= 2;
+            if (digit > 9)
+                digit -= 9;
+        }
+        sum += digit;
+    }
+    return sum % 10 === 0;
+}
+export function ibanChecksum(value) {
+    const iban = value.replace(/ /g, '').toUpperCase();
+    if (!/^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/.test(iban))
+        return false;
+    const rearranged = `${iban.slice(4)}${iban.slice(0, 4)}`;
+    let remainder = 0;
+    for (const char of rearranged) {
+        const code = /\d/.test(char) ? char : String(char.charCodeAt(0) - 55);
+        for (const digit of code)
+            remainder = (remainder * 10 + Number(digit)) % 97;
+    }
+    return remainder === 1;
+}
+export function phoneDigits(value) {
+    const digits = value.replace(/\D/g, '').length;
+    return digits >= 10 && digits <= 15;
+}
+export function phoneNumber(value) {
+    return phoneDigits(value) && (/^\s*\+/.test(value) || /\d[\s.()-]+\d/.test(value));
+}
+export function normalizeForDetection(text) {
+    return text.normalize('NFKC').replace(/[­᠎​-‏‪-‮⁠-⁤]/g, '');
+}

package/dist/utils/ids.d.ts

@@ -1 +1,9 @@
+/**
+ * Ids and text measures from Web Crypto and plain JavaScript, so the modules that use them run on
+ * every runtime: Node.js, Deno, Bun, edge runtimes, and browsers.
+ */
+/** Random bytes as lowercase hex, two characters per byte. */
+export declare function randomHex(bytes: number): string;
 export declare function generateRequestId(): string;
+/** The bytes UTF-8 takes for a string, as `Buffer.byteLength()` counts them, without encoding it. */
+export declare function utf8Length(text: string): number;

package/dist/utils/ids.js

@@ -1,4 +1,28 @@
-import { randomBytes } from 'node:crypto';
+export function randomHex(bytes) {
+    const values = globalThis.crypto.getRandomValues(new Uint8Array(bytes));
+    let hex = '';
+    for (const value of values)
+        hex += HEX[value];
+    return hex;
+}
 export function generateRequestId() {
-    return `req_${randomBytes(12).toString('hex')}`;
+    return `req_${randomHex(12)}`;
+}
+export function utf8Length(text) {
+    let length = 0;
+    for (let index = 0; index < text.length; index += 1) {
+        const code = text.charCodeAt(index);
+        if (code < 0x80)
+            length += 1;
+        else if (code < 0x800)
+            length += 2;
+        else if (code >= 0xd800 && code <= 0xdbff && (text.charCodeAt(index + 1) & 0xfc00) === 0xdc00) {
+            length += 4;
+            index += 1;
+        }
+        else
+            length += 3;
+    }
+    return length;
 }
+const HEX = Array.from({ length: 256 }, (_, value) => value.toString(16).padStart(2, '0'));

package/dist/utils/sha256.d.ts

@@ -0,0 +1,22 @@
+/**
+ * SHA-256 that can be fed in pieces, as `createHash('sha256')` is, with the same digest. Strings are
+ * hashed as UTF-8. Synchronous, unlike Web Crypto's `digest()`, so a cache key can be computed where
+ * it is needed.
+ */
+export declare class Sha256 {
+    private readonly state;
+    private readonly block;
+    private readonly words;
+    private filled;
+    private total;
+    /** Adds data: a string, as UTF-8, or bytes. */
+    update(data: string | Uint8Array): this;
+    /** The digest as lowercase hex. The hash takes no more data afterwards. */
+    digest(): string;
+    private compress;
+}
+/**
+ * The SHA-256 digest of a string, as UTF-8, or of bytes, as lowercase hex. Native where the runtime
+ * has it, which is ten times faster on large inputs, and the same digest everywhere else.
+ */
+export declare function sha256Hex(data: string | Uint8Array): string;

package/dist/utils/sha256.js

@@ -0,0 +1,120 @@
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98,
+    0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786,
+    0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8,
+    0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+    0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819,
+    0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a,
+    0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7,
+    0xc67178f2,
+]);
+const encoder = new TextEncoder();
+export class Sha256 {
+    state = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+    ]);
+    block = new Uint8Array(64);
+    words = new Uint32Array(64);
+    filled = 0;
+    total = 0;
+    update(data) {
+        const bytes = typeof data === 'string' ? encoder.encode(data) : data;
+        this.total += bytes.length;
+        let offset = 0;
+        if (this.filled > 0) {
+            const take = Math.min(64 - this.filled, bytes.length);
+            this.block.set(bytes.subarray(0, take), this.filled);
+            this.filled += take;
+            offset = take;
+            if (this.filled < 64)
+                return this;
+            this.compress(this.block, 0);
+            this.filled = 0;
+        }
+        for (; offset + 64 <= bytes.length; offset += 64)
+            this.compress(bytes, offset);
+        if (offset < bytes.length) {
+            this.block.set(bytes.subarray(offset), 0);
+            this.filled = bytes.length - offset;
+        }
+        return this;
+    }
+    digest() {
+        const bits = this.total * 8;
+        const padding = new Uint8Array(this.filled < 56 ? 64 - this.filled : 128 - this.filled);
+        padding[0] = 0x80;
+        const view = new DataView(padding.buffer);
+        view.setUint32(padding.length - 8, Math.floor(bits / 0x100000000));
+        view.setUint32(padding.length - 4, bits >>> 0);
+        const total = this.total;
+        this.update(padding);
+        this.total = total;
+        let hex = '';
+        for (const word of this.state)
+            hex += word.toString(16).padStart(8, '0');
+        return hex;
+    }
+    compress(bytes, offset) {
+        const w = this.words;
+        for (let index = 0; index < 16; index += 1) {
+            const at = offset + index * 4;
+            w[index] =
+                (bytes[at] << 24) |
+                    (bytes[at + 1] << 16) |
+                    (bytes[at + 2] << 8) |
+                    bytes[at + 3];
+        }
+        for (let index = 16; index < 64; index += 1) {
+            const a = w[index - 15];
+            const b = w[index - 2];
+            const s0 = ((a >>> 7) | (a << 25)) ^ ((a >>> 18) | (a << 14)) ^ (a >>> 3);
+            const s1 = ((b >>> 17) | (b << 15)) ^ ((b >>> 19) | (b << 13)) ^ (b >>> 10);
+            w[index] = (w[index - 16] + s0 + w[index - 7] + s1) | 0;
+        }
+        const h = this.state;
+        let a = h[0];
+        let b = h[1];
+        let c = h[2];
+        let d = h[3];
+        let e = h[4];
+        let f = h[5];
+        let g = h[6];
+        let k = h[7];
+        for (let index = 0; index < 64; index += 1) {
+            const s1 = ((e >>> 6) | (e << 26)) ^ ((e >>> 11) | (e << 21)) ^ ((e >>> 25) | (e << 7));
+            const choose = (e & f) ^ (~e & g);
+            const t1 = (k + s1 + choose + K[index] + w[index]) | 0;
+            const s0 = ((a >>> 2) | (a << 30)) ^ ((a >>> 13) | (a << 19)) ^ ((a >>> 22) | (a << 10));
+            const majority = (a & b) ^ (a & c) ^ (b & c);
+            const t2 = (s0 + majority) | 0;
+            k = g;
+            g = f;
+            f = e;
+            e = (d + t1) | 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) | 0;
+        }
+        h[0] = h[0] + a;
+        h[1] = h[1] + b;
+        h[2] = h[2] + c;
+        h[3] = h[3] + d;
+        h[4] = h[4] + e;
+        h[5] = h[5] + f;
+        h[6] = h[6] + g;
+        h[7] = h[7] + k;
+    }
+}
+const nativeHash = (() => {
+    try {
+        const host = globalThis.process;
+        return host?.getBuiltinModule?.('crypto')?.createHash;
+    }
+    catch {
+        return undefined;
+    }
+})();
+export function sha256Hex(data) {
+    return nativeHash ? nativeHash('sha256').update(data).digest('hex') : new Sha256().update(data).digest();
+}

package/dist/version.d.ts

@@ -2,4 +2,4 @@
  * This package's version, recorded where provenance matters, such as on every experiment. A test
  * keeps it equal to `package.json`.
  */
-export declare const NEXUS_VERSION = "2.3.0";
+export declare const NEXUS_VERSION = "2.4.0";

package/dist/version.js

@@ -1 +1 @@
-export const NEXUS_VERSION = '2.3.0';
+export const NEXUS_VERSION = '2.4.0';

package/dist-cjs/adapter-kit/contracts.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The contract suites the adapter kit ships: what every vector store, retriever, and long-term store
+ * must do, as checks that need no test framework. Each check is named for the behavior it proves,
+ * and a capability the adapter does not declare is reported as skipped, never as a failure.
+ */
+import type { RagChunk } from '../hallucination/rag.js';
+import type { EmbeddingProvider, VectorStore } from '../hallucination/retrieval.js';
+import type { Retriever } from '../rag/retrievers.js';
+import type { Store } from '../types/store.js';
+/** One check of a contract suite. */
+export interface AdapterCheck {
+    /** What was checked, as a sentence. */
+    name: string;
+    /** Whether it held. */
+    ok: boolean;
+    /** Why it did not hold, or why it was skipped. */
+    detail?: string;
+    /** True when the adapter does not declare the capability the check needs. */
+    skipped?: boolean;
+}
+/** The passages every retrieval contract runs on, and that benchmarks reuse. */
+export declare const ADAPTER_FIXTURE_PASSAGES: readonly RagChunk[];
+/** What a vector store declares it supports, for its contract. */
+export interface VectorStoreCapabilities {
+    /** `searchVector()` with a vector computed elsewhere. Defaults to true. */
+    searchVector?: boolean;
+    /** `minScore` drops weak matches. Defaults to true. */
+    minScore?: boolean;
+    /** Metadata filters: `exact` matches values, `typed` also tells `3` from `'3'`, `none` has no filters. Defaults to `exact`. */
+    filters?: 'none' | 'exact' | 'typed';
+}
+/** Options for `runVectorStoreContract()`. */
+export interface VectorStoreContractOptions {
+    /** The embedding function the store was given, to compute a query vector for `searchVector()`. */
+    embed: EmbeddingProvider;
+    /** What the store supports. */
+    capabilities?: VectorStoreCapabilities;
+    /** Waits for writes to become searchable, for a store whose index is eventually consistent. */
+    settle?: () => Promise<void>;
+}
+/**
+ * The `VectorStore` contract: ranking, `topK`, sources and metadata round-tripped, filters,
+ * `minScore`, vector search, replacement by id, deletes, and empty writes. The store should be empty
+ * when it starts.
+ */
+export declare function runVectorStoreContract(store: VectorStore, options: VectorStoreContractOptions): Promise<AdapterCheck[]>;
+/** What a retriever declares it supports, for its contract. */
+export interface RetrieverCapabilities {
+    /** It holds its own passages, with `add()` and `delete()`: a `SparseRetriever`. Defaults to whether it has them. */
+    writes?: boolean;
+    /** Metadata filters. Defaults to true. */
+    filters?: boolean;
+}
+/** Options for `runRetrieverContract()`. */
+export interface RetrieverContractOptions {
+    /** What the retriever supports. */
+    capabilities?: RetrieverCapabilities;
+    /**
+     * Loads the fixture passages, for a retriever that does not hold its own: into the vector store
+     * behind it, say. A retriever with `add()` is loaded through that.
+     */
+    load?: (passages: RagChunk[]) => Promise<void>;
+    /** Waits for writes to become searchable. */
+    settle?: () => Promise<void>;
+}
+/**
+ * The `Retriever` contract, and the `SparseRetriever` contract when the retriever takes writes:
+ * an exact term found, ranking, `topK`, filters, replacement, deletes, and an empty query.
+ */
+export declare function runRetrieverContract(retriever: Retriever, options?: RetrieverContractOptions): Promise<AdapterCheck[]>;
+/** What a long-term store declares it supports, for its contract. */
+export interface StoreCapabilities {
+    /** `search()` lists a namespace prefix, newest first. Defaults to true. */
+    search?: boolean;
+    /** `search()` filters on value fields. Defaults to true. */
+    filters?: boolean;
+    /** `listNamespaces()`. Defaults to true. */
+    namespaces?: boolean;
+}
+/**
+ * The long-term `Store` contract: values round-trip, a replaced item keeps its creation time, a
+ * missing key reads as nothing, deletes, prefix search with filters and paging, and namespace
+ * listing. The store should be empty when it starts.
+ */
+export declare function runStoreContract(store: Store, options?: {
+    capabilities?: StoreCapabilities;
+}): Promise<AdapterCheck[]>;