@urun-sh/sense 0.0.0-stage → 0.1.1

package/dist/question.d.ts

@@ -0,0 +1,43 @@
+import type { Predicate } from "./predicate.js";
+export type QuestionKind = "noul" | "choice" | "score";
+export interface QuestionInit {
+    id: string;
+    kind: QuestionKind;
+    prompt?: string;
+    /** choice option names (noul: server defaults to true/false). */
+    options?: string[];
+    /** score level names, ordinal order. */
+    levels?: string[];
+}
+/** One registered question. */
+export declare class Question {
+    readonly id: string;
+    readonly kind: QuestionKind;
+    readonly prompt?: string;
+    readonly options?: string[];
+    readonly levels?: string[];
+    constructor(init: QuestionInit);
+    /** argmax accessor: `actions.top.eq("respond")`. */
+    get top(): import("./predicate.js").Ops & ((option?: string) => import("./predicate.js").Ops);
+    /** score expected-ordinal accessor. */
+    get value(): import("./predicate.js").Ops & ((option?: string) => import("./predicate.js").Ops);
+    /** noul P(true) accessor; choice: `intent.p("support").gte(0.7)`. */
+    get p(): import("./predicate.js").Ops & ((option?: string) => import("./predicate.js").Ops);
+    /** score level-threshold accessor. */
+    pAtLeast(level: string): import("./predicate.js").Ops & ((option?: string) => import("./predicate.js").Ops);
+    private argmax;
+    eq(value: string | number | boolean): Predicate;
+    ne(value: string | number | boolean): Predicate;
+    gt(value: number): Predicate;
+    gte(value: number): Predicate;
+    lt(value: number): Predicate;
+    lte(value: number): Predicate;
+    and(...others: Predicate[]): Predicate;
+    or(...others: Predicate[]): Predicate;
+    not(): Predicate;
+}
+/** The §2 instructions envelope body (values, not the JSON string). */
+export declare function instructionsEnvelope(questions: readonly Question[], hz: number): {
+    questions: Record<string, Record<string, unknown>>;
+    hz: number;
+};

package/dist/question.js

@@ -0,0 +1,75 @@
+/** Questions and the instructions envelope (protocol §2). */
+import { opsFor } from "./predicate.js";
+/** One registered question. */
+export class Question {
+    id;
+    kind;
+    prompt;
+    options;
+    levels;
+    constructor(init) {
+        this.id = init.id;
+        this.kind = init.kind;
+        this.prompt = init.prompt;
+        this.options = init.options;
+        this.levels = init.levels;
+        if (init.kind === "score" && (init.levels?.length ?? 0) < 2) {
+            throw new RangeError(`score question "${init.id}" needs 2..10 levels`);
+        }
+    }
+    /** argmax accessor: `actions.top.eq("respond")`. */
+    get top() {
+        return opsFor({ type: "top", question: this.id });
+    }
+    /** score expected-ordinal accessor. */
+    get value() {
+        return opsFor({ type: "value", question: this.id });
+    }
+    /** noul P(true) accessor; choice: `intent.p("support").gte(0.7)`. */
+    get p() {
+        return opsFor({ type: "p", question: this.id });
+    }
+    /** score level-threshold accessor. */
+    pAtLeast(level) {
+        return opsFor({ type: "p_at_least", question: this.id, level });
+    }
+    // Argmax sugar on the question itself: `intent.eq("support")` == the top
+    // option equals "support"; `finished.eq(true)` / `finished.and(...)` /
+    // `finished.not()` for noul. Same trees the accessors build.
+    argmax() {
+        return opsFor({ type: "question", id: this.id });
+    }
+    eq(value) { return this.argmax().eq(value); }
+    ne(value) { return this.argmax().ne(value); }
+    gt(value) { return this.argmax().gt(value); }
+    gte(value) { return this.argmax().gte(value); }
+    lt(value) { return this.argmax().lt(value); }
+    lte(value) { return this.argmax().lte(value); }
+    and(...others) { return this.argmax().truthy().and(...others); }
+    or(...others) { return this.argmax().truthy().or(...others); }
+    not() { return this.argmax().truthy().not(); }
+}
+/** The §2 instructions envelope body (values, not the JSON string). */
+export function instructionsEnvelope(questions, hz) {
+    const out = {};
+    for (const q of questions) {
+        if (q.kind === "score") {
+            // The server's _score_levels wants an ORDERED ARRAY of level
+            // descriptions (a string parses as free text and the model then
+            // free-scores into ~10 unnamed buckets — live-verified).
+            out[q.id] = {
+                kind: q.kind,
+                prompt: q.prompt ?? "",
+                criteria: q.levels ?? [],
+            };
+        }
+        else {
+            out[q.id] = {
+                kind: q.kind,
+                prompt: q.prompt ?? "",
+                ...(q.options ? { options: q.options } : {}),
+            };
+        }
+    }
+    return { questions: out, hz };
+}

package/dist/sense.d.ts

@@ -0,0 +1,54 @@
+/** Sense: the app facade — register questions, compose predicates, open sessions. */
+import { Question } from "./question.js";
+import type { QuestionKind } from "./question.js";
+import type { Predicate } from "./predicate.js";
+import type { WaveHandler } from "./context.js";
+import { Session, type SessionOptions } from "./session.js";
+import type { Transport } from "./transport.js";
+export interface SenseOptions extends SessionOptions {
+}
+export declare class Sense {
+    readonly apiKey?: string;
+    readonly baseUrl?: string;
+    readonly model: string;
+    readonly hz: number;
+    readonly transport: Transport;
+    private questions;
+    private whens;
+    private waveHandlers;
+    constructor(opts?: SenseOptions);
+    /** Register a binary question. TEXT-FIRST like the python facade: the
+     * natural-language question is the first argument; the id is optional and
+     * auto-slugged from the question text (options optional; the server
+     * defaults to true/false). */
+    noul(question: string, opts?: {
+        id?: string;
+        options?: string[];
+    }): Question;
+    /** Register an n-way choice question (text-first; id auto-slugs). */
+    choice(question: string, options: string[], opts?: {
+        id?: string;
+    }): Question;
+    /** Register an ordinal score question, 2..10 levels (text-first; id auto-slugs). */
+    score(question: string, levels: string[], opts?: {
+        id?: string;
+    }): Question;
+    /** Mirror of python `_qid`: the question text is required and non-empty;
+     * the id is auto-slugged from it when omitted and must be non-empty when
+     * given explicitly. */
+    private qid;
+    private register;
+    when(pred: Predicate, handler: WaveHandler): {
+        cancel(): void;
+    };
+    /** Observe waves on every session opened from here; `coalesce` skips
+     * consecutive same-argmax waves (latest wins). */
+    onWave(handler: WaveHandler, opts?: {
+        coalesce?: boolean;
+    }): {
+        cancel(): void;
+    };
+    /** Open a session carrying the questions and handlers registered here. */
+    session(): Session;
+}
+export type { QuestionKind };

package/dist/sense.js

@@ -0,0 +1,109 @@
+/** Sense: the app facade — register questions, compose predicates, open sessions. */
+import { Question } from "./question.js";
+import { Session } from "./session.js";
+/** Mirror of python `_slug`: lowercase, each non-alphanumeric char becomes
+ * `_`, leading/trailing `_` trimmed, never empty, unique within the app. */
+function slug(text, taken) {
+    let base = "";
+    for (const c of text.trim().toLowerCase())
+        base += /\p{L}|\p{N}/u.test(c) ? c : "_";
+    base = base.replace(/^_+/, "").replace(/_+$/, "") || "question";
+    const takenSet = new Set(taken);
+    let qid = base;
+    let n = 1;
+    while (takenSet.has(qid)) {
+        n += 1;
+        qid = `${base}_${n}`;
+    }
+    return qid;
+}
+export class Sense {
+    apiKey;
+    baseUrl;
+    model;
+    hz;
+    transport;
+    questions = [];
+    whens = [];
+    waveHandlers = [];
+    constructor(opts = {}) {
+        this.apiKey = opts.apiKey ?? process.env.SENSE_API_KEY;
+        this.baseUrl = opts.baseUrl ?? process.env.SENSE_BASE_URL;
+        this.model = opts.model ?? Session.DEFAULT_MODEL;
+        this.hz = opts.hz ?? 25;
+        this.transport = opts.transport ?? "auto";
+    }
+    /** Register a binary question. TEXT-FIRST like the python facade: the
+     * natural-language question is the first argument; the id is optional and
+     * auto-slugged from the question text (options optional; the server
+     * defaults to true/false). */
+    noul(question, opts = {}) {
+        return this.register({ id: this.qid(question, opts.id), kind: "noul", prompt: question, options: opts.options });
+    }
+    /** Register an n-way choice question (text-first; id auto-slugs). */
+    choice(question, options, opts = {}) {
+        return this.register({ id: this.qid(question, opts.id), kind: "choice", prompt: question, options });
+    }
+    /** Register an ordinal score question, 2..10 levels (text-first; id auto-slugs). */
+    score(question, levels, opts = {}) {
+        return this.register({ id: this.qid(question, opts.id), kind: "score", prompt: question, levels });
+    }
+    /** Mirror of python `_qid`: the question text is required and non-empty;
+     * the id is auto-slugged from it when omitted and must be non-empty when
+     * given explicitly. */
+    qid(question, id) {
+        if (typeof question !== "string" || question.trim() === "") {
+            throw new Error("question text must be a non-empty string (text-first API)");
+        }
+        if (id === undefined)
+            return slug(question, this.questions.map((q) => q.id));
+        if (id.trim() === "")
+            throw new Error("explicit id must be non-empty");
+        return id;
+    }
+    register(init) {
+        const q = new Question(init);
+        const i = this.questions.findIndex((x) => x.id === q.id);
+        if (i >= 0)
+            this.questions[i] = q;
+        else
+            this.questions.push(q);
+        return q;
+    }
+    when(pred, handler) {
+        const handle = { pred, handler };
+        this.whens.push(handle);
+        return {
+            cancel: () => {
+                this.whens = this.whens.filter((h) => h !== handle);
+            },
+        };
+    }
+    /** Observe waves on every session opened from here; `coalesce` skips
+     * consecutive same-argmax waves (latest wins). */
+    onWave(handler, opts = {}) {
+        const entry = { handler, opts };
+        this.waveHandlers.push(entry);
+        return {
+            cancel: () => {
+                this.waveHandlers = this.waveHandlers.filter((h) => h !== entry);
+            },
+        };
+    }
+    /** Open a session carrying the questions and handlers registered here. */
+    session() {
+        const s = new Session({
+            apiKey: this.apiKey,
+            baseUrl: this.baseUrl,
+            model: this.model,
+            hz: this.hz,
+            transport: this.transport,
+            questions: this.questions,
+        });
+        for (const { pred, handler } of this.whens)
+            s.when(pred, handler);
+        for (const { handler, opts } of this.waveHandlers)
+            s.onWave(handler, opts);
+        return s;
+    }
+}

package/dist/session.d.ts

@@ -0,0 +1,151 @@
+import type { Transport, WireDialer } from "./transport.js";
+import { Question } from "./question.js";
+import type { QuestionInit, QuestionKind } from "./question.js";
+import { Wave, type Result } from "./wave.js";
+import { Context, type WaveHandler } from "./context.js";
+import type { Predicate } from "./predicate.js";
+export interface SessionEvent {
+    type: string;
+    code?: string;
+    message?: string;
+    raw: unknown;
+}
+/** Parse a server event object into the SDK's session-event shape. */
+export declare function sessionEvent(raw: unknown): SessionEvent;
+export interface SessionOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    model?: string;
+    hz?: number;
+    questions?: Question[];
+    /** Wire transport: "auto" = quic → webrtc → ws (default). */
+    transport?: Transport;
+    /** @internal test seam: override the wire dialer. */
+    wireFactory?: WireDialer;
+}
+export declare class Session {
+    static readonly DEFAULT_BASE_URL = "wss://inference.urun.sh";
+    static readonly DEFAULT_MODEL = "sense-latest:bf16";
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly model: string;
+    readonly hz: number;
+    readonly transport: Transport;
+    readonly context: Context;
+    readonly audio: AudioInput;
+    readonly video: VideoInput;
+    readonly text: TextInput;
+    readonly stats: {
+        waves: number;
+        turns: number;
+        errors: number;
+        reconnects: number;
+        decisions: number;
+        protocolErrors: number;
+    };
+    private isClosed;
+    private wire;
+    private readonly wireFactory;
+    private waveSeq;
+    private sourceQueues;
+    private rrCursor;
+    private oneShotText;
+    private transcript;
+    private waveQueue;
+    private waveWaiters;
+    private accumulator;
+    private accTMs;
+    private turnOpen;
+    private audioPending;
+    private inputSinceTurn;
+    private registry;
+    private eventListeners;
+    constructor(opts?: SessionOptions);
+    get questions(): Question[];
+    get closed(): boolean;
+    /** Register (or replace) a question; takes effect at the next turn open. */
+    addQuestion(id: string, kind: QuestionKind, opts?: Omit<QuestionInit, "id" | "kind">): Question;
+    private addQuestionRaw;
+    realtimeUrl(): string;
+    /** @internal */
+    emitAudio(b64: string, source?: string): void;
+    /** ponytail: round-robin one queued non-default chunk per default push (PR-2
+     * degradation); replace with labeled lanes when PR-2 lands. */
+    private drainSourceQueues;
+    /** @internal */
+    emitVideo(jpeg: Uint8Array): void;
+    /** @internal */
+    emitText(text: string, mode: string): void;
+    private sendJson;
+    private sendSessionUpdate;
+    private openTurn;
+    /** Barge-in: stop the active turn's cadence. */
+    bargeIn(): void;
+    /** Connect with the §7 dial policy (503/429 → backoff and redial). The
+     * transport selection (auto: quic → webrtc → ws) happens in the wire
+     * factory; a refused dial restarts the whole order. */
+    connect(): Promise<void>;
+    private onClose;
+    private onMessage;
+    private onDeltaMessage;
+    private onTurnCompleted;
+    /** Returns true when the error was handled locally and needs no listener dispatch. */
+    private onErrorMessage;
+    onEvent(handler: (ev: SessionEvent) => void): {
+        cancel(): void;
+    };
+    /** §6.3 client-side wave assembly: one decision line per question per wave;
+     * a repeat qid closes the previous wave. */
+    private onDecisionLine;
+    private flushAccumulator;
+    private deliver;
+    private nextWave;
+    /** Async-iterator of waves: push any given inputs, then run the turn loop. */
+    run(inputs?: Iterable<InputFrame> | AsyncIterable<InputFrame>): AsyncGenerator<Wave>;
+    private applyFrame;
+    /** Latest result for a question, or null before the first wave. */
+    latest(question: string): Result | null;
+    /** Iterate waves live; coalesce drops earlier waves in runs of identical
+     * argmax values (latest wins). */
+    waves(opts?: {
+        coalesce?: boolean;
+    }): AsyncGenerator<Wave>;
+    when(pred: Predicate, handler: WaveHandler): {
+        cancel(): void;
+    };
+    /** Observe waves live; `coalesce` delivers the FIRST wave of a run of
+     * consecutive same-argmax waves — later waves update `latest()` without
+     * another callback. */
+    onWave(handler: WaveHandler, opts?: {
+        coalesce?: boolean;
+    }): {
+        cancel(): void;
+    };
+    close(): Promise<void>;
+}
+export type InputFrame = {
+    audio: Uint8Array | ArrayBuffer;
+    source?: string;
+} | {
+    video: Uint8Array | ArrayBuffer;
+} | {
+    text: string;
+    mode?: "append" | "replace" | "event";
+};
+export declare class AudioInput {
+    private session;
+    constructor(session: Session);
+    /** Push PCM16 24 kHz mono (encoded base64 on the wire). */
+    push(pcm: Uint8Array | ArrayBuffer, source?: string): void;
+}
+export declare class VideoInput {
+    private session;
+    constructor(session: Session);
+    push(jpeg: Uint8Array | ArrayBuffer): void;
+}
+export type TextMode = "append" | "replace" | "event";
+export declare class TextInput {
+    private session;
+    constructor(session: Session);
+    push(text: string, mode?: TextMode): void;
+}