@lloyal-labs/sdk 1.0.0

package/dist/Session.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Session = void 0;
+const deltas_1 = require("./deltas");
+/**
+ * Session - Trunk lifecycle + conversation delta helpers
+ *
+ * Owns the current "trunk" branch and provides promote() to crown a winner,
+ * plus delta helpers that centralize the sep + formatChat + tokenize + prefill
+ * pattern for injecting new turns into an ongoing conversation.
+ *
+ * Session does NOT own the SessionContext or BranchStore — the consumer
+ * creates those and passes them in. dispose() prunes trunk only.
+ *
+ * @example
+ * ```typescript
+ * const session = new Session({ ctx, store });
+ * session.trunk = initialBranch;
+ *
+ * // After verification, promote the best attempt
+ * await session.promote(bestAttempt.branch);
+ *
+ * // Inject a user turn and generate
+ * await session.prefillUser('What about X?');
+ * for await (const { text } of session.trunk) {
+ *   process.stdout.write(text);
+ * }
+ *
+ * // Cleanup
+ * await session.dispose();
+ * ctx.dispose();
+ * ```
+ *
+ * @category Branching
+ */
+class Session {
+    _ctx;
+    _store;
+    _trunk;
+    constructor({ ctx, store }) {
+        this._ctx = ctx;
+        this._store = store;
+        this._trunk = null;
+    }
+    /** Current trunk branch */
+    get trunk() {
+        return this._trunk;
+    }
+    /** Assign initial trunk (no promote) */
+    set trunk(branch) {
+        this._trunk = branch;
+    }
+    /**
+     * Promote a winner to trunk — retainOnly + reassign
+     *
+     * Safe even if winner is the only branch (resets topology, no-op on KV).
+     */
+    async promote(winner) {
+        await this._store.retainOnly(winner);
+        this._trunk = winner;
+    }
+    /**
+     * Dispose trunk only — consumer owns ctx and other resources
+     */
+    async dispose() {
+        if (this._trunk && !this._trunk.disposed) {
+            await this._trunk.prune();
+        }
+        this._trunk = null;
+    }
+    /**
+     * Prefill a user turn into trunk
+     *
+     * @param content - User message content
+     * @param opts - Optional tools JSON string
+     */
+    async prefillUser(content, opts = {}) {
+        const tokens = (0, deltas_1.buildUserDelta)(this._ctx, content, opts);
+        await this._trunk.prefill(tokens);
+    }
+    /**
+     * Prefill a tool result turn into trunk
+     *
+     * @param resultStr - JSON-stringified tool result
+     * @param callId - Tool call ID
+     */
+    async prefillToolResult(resultStr, callId) {
+        const tokens = (0, deltas_1.buildToolResultDelta)(this._ctx, resultStr, callId);
+        await this._trunk.prefill(tokens);
+    }
+}
+exports.Session = Session;
+//# sourceMappingURL=Session.js.map

package/dist/Session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Session.js","sourceRoot":"","sources":["../src/Session.ts"],"names":[],"mappings":";;;AAGA,qCAAgE;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAa,OAAO;IACV,IAAI,CAAiB;IACrB,MAAM,CAAc;IACpB,MAAM,CAAgB;IAE9B,YAAY,EAAE,GAAG,EAAE,KAAK,EAA+C;QACrE,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;QAChB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,2BAA2B;IAC3B,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,wCAAwC;IACxC,IAAI,KAAK,CAAC,MAAqB;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO,CAAC,MAAc;QAC1B,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO;QACX,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACzC,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAC5B,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACrB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,WAAW,CAAC,OAAe,EAAE,OAA2B,EAAE;QAC9D,MAAM,MAAM,GAAG,IAAA,uBAAc,EAAC,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;QACxD,MAAM,IAAI,CAAC,MAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,iBAAiB,CAAC,SAAiB,EAAE,MAAc;QACvD,MAAM,MAAM,GAAG,IAAA,6BAAoB,EAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;QAClE,MAAM,IAAI,CAAC,MAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC;CACF;AA9DD,0BA8DC"}

package/dist/deltas.d.ts

@@ -0,0 +1,37 @@
+import type { SessionContext } from './types';
+/**
+ * Build a token delta for a user turn
+ *
+ * Composes `getTurnSeparator()` + `formatChatSync()` + `tokenizeSync()` into a
+ * single token array suitable for `branch.prefill()`. Usable with any
+ * branch — not tied to {@link Session}'s trunk.
+ *
+ * This is the canonical way to build a user-turn delta for warm prefill
+ * in multi-turn conversations.
+ *
+ * @param ctx - Active session context
+ * @param content - User message content
+ * @param opts - Optional tools JSON for tool-aware formatting
+ * @returns Token array ready for `branch.prefill()`
+ *
+ * @category Agents
+ */
+export declare function buildUserDelta(ctx: SessionContext, content: string, opts?: {
+    tools?: string;
+}): number[];
+/**
+ * Build a token delta for a tool result turn
+ *
+ * Composes `getTurnSeparator()` + `formatChatSync()` + `tokenizeSync()` into a
+ * single token array suitable for `branch.prefill()`. Used by
+ * {@link useAgentPool} to inject tool results back into agent context.
+ *
+ * @param ctx - Active session context
+ * @param resultStr - JSON-serialized tool result
+ * @param callId - Tool call identifier from the model's parsed output
+ * @returns Token array ready for `branch.prefill()`
+ *
+ * @category Agents
+ */
+export declare function buildToolResultDelta(ctx: SessionContext, resultStr: string, callId: string): number[];
+//# sourceMappingURL=deltas.d.ts.map

package/dist/deltas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deltas.d.ts","sourceRoot":"","sources":["../src/deltas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,cAAc,EACnB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5B,MAAM,EAAE,CASV;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,cAAc,EACnB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,MAAM,EAAE,CAUV"}

package/dist/deltas.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildUserDelta = buildUserDelta;
+exports.buildToolResultDelta = buildToolResultDelta;
+/**
+ * Build a token delta for a user turn
+ *
+ * Composes `getTurnSeparator()` + `formatChatSync()` + `tokenizeSync()` into a
+ * single token array suitable for `branch.prefill()`. Usable with any
+ * branch — not tied to {@link Session}'s trunk.
+ *
+ * This is the canonical way to build a user-turn delta for warm prefill
+ * in multi-turn conversations.
+ *
+ * @param ctx - Active session context
+ * @param content - User message content
+ * @param opts - Optional tools JSON for tool-aware formatting
+ * @returns Token array ready for `branch.prefill()`
+ *
+ * @category Agents
+ */
+function buildUserDelta(ctx, content, opts = {}) {
+    const sep = ctx.getTurnSeparator();
+    const fmtOpts = opts.tools ? { tools: opts.tools } : {};
+    const { prompt } = ctx.formatChatSync(JSON.stringify([{ role: 'system', content: '' }, { role: 'user', content }]), fmtOpts);
+    const delta = ctx.tokenizeSync(prompt, false);
+    return [...sep, ...delta];
+}
+/**
+ * Build a token delta for a tool result turn
+ *
+ * Composes `getTurnSeparator()` + `formatChatSync()` + `tokenizeSync()` into a
+ * single token array suitable for `branch.prefill()`. Used by
+ * {@link useAgentPool} to inject tool results back into agent context.
+ *
+ * @param ctx - Active session context
+ * @param resultStr - JSON-serialized tool result
+ * @param callId - Tool call identifier from the model's parsed output
+ * @returns Token array ready for `branch.prefill()`
+ *
+ * @category Agents
+ */
+function buildToolResultDelta(ctx, resultStr, callId) {
+    const sep = ctx.getTurnSeparator();
+    const { prompt } = ctx.formatChatSync(JSON.stringify([
+        { role: 'system', content: '' },
+        { role: 'tool', content: resultStr, tool_call_id: callId },
+    ]));
+    const delta = ctx.tokenizeSync(prompt, false);
+    return [...sep, ...delta];
+}
+//# sourceMappingURL=deltas.js.map

package/dist/deltas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deltas.js","sourceRoot":"","sources":["../src/deltas.ts"],"names":[],"mappings":";;AAmBA,wCAaC;AAgBD,oDAcC;AA5DD;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,cAAc,CAC5B,GAAmB,EACnB,OAAe,EACf,OAA2B,EAAE;IAE7B,MAAM,GAAG,GAAG,GAAG,CAAC,gBAAgB,EAAE,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACxD,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,cAAc,CACnC,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,EAC5E,OAAO,CACR,CAAC;IACF,MAAM,KAAK,GAAG,GAAG,CAAC,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC9C,OAAO,CAAC,GAAG,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC;AAC5B,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,oBAAoB,CAClC,GAAmB,EACnB,SAAiB,EACjB,MAAc;IAEd,MAAM,GAAG,GAAG,GAAG,CAAC,gBAAgB,EAAE,CAAC;IACnC,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,cAAc,CACnC,IAAI,CAAC,SAAS,CAAC;QACb,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,EAAE;QAC/B,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE;KAC3D,CAAC,CACH,CAAC;IACF,MAAM,KAAK,GAAG,GAAG,CAAC,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC9C,OAAO,CAAC,GAAG,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC;AAC5B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { Branch } from './Branch';
+export { BranchStore } from './BranchStore';
+export { Session } from './Session';
+export { Rerank } from './Rerank';
+export { buildUserDelta, buildToolResultDelta } from './deltas';
+export { PoolingType, CHAT_FORMAT_CONTENT_ONLY, CHAT_FORMAT_GENERIC, ReasoningFormat, GrammarTriggerType } from './types';
+export type { ChatFormat } from './types';
+export type { GpuVariant, KvCacheType, LoadOptions, ContextOptions, FormatChatOptions, GrammarTrigger, FormattedChatResult, ParseChatOutputOptions, ParsedToolCall, ParseChatOutputResult, PenaltyParams, MirostatParams, DryParams, XtcParams, AdvancedSamplingParams, SamplingParams, SessionContext, Produced, RerankOptions, RerankResult, RerankProgress, } from './types';
+//# 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,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAGhE,OAAO,EAAE,WAAW,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAG1H,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,YAAY,EACV,UAAU,EACV,WAAW,EACX,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,mBAAmB,EACnB,sBAAsB,EACtB,cAAc,EACd,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,SAAS,EACT,SAAS,EACT,sBAAsB,EACtB,cAAc,EACd,cAAc,EACd,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,cAAc,GACf,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GrammarTriggerType = exports.ReasoningFormat = exports.CHAT_FORMAT_GENERIC = exports.CHAT_FORMAT_CONTENT_ONLY = exports.PoolingType = exports.buildToolResultDelta = exports.buildUserDelta = exports.Rerank = exports.Session = exports.BranchStore = exports.Branch = void 0;
+var Branch_1 = require("./Branch");
+Object.defineProperty(exports, "Branch", { enumerable: true, get: function () { return Branch_1.Branch; } });
+var BranchStore_1 = require("./BranchStore");
+Object.defineProperty(exports, "BranchStore", { enumerable: true, get: function () { return BranchStore_1.BranchStore; } });
+var Session_1 = require("./Session");
+Object.defineProperty(exports, "Session", { enumerable: true, get: function () { return Session_1.Session; } });
+var Rerank_1 = require("./Rerank");
+Object.defineProperty(exports, "Rerank", { enumerable: true, get: function () { return Rerank_1.Rerank; } });
+var deltas_1 = require("./deltas");
+Object.defineProperty(exports, "buildUserDelta", { enumerable: true, get: function () { return deltas_1.buildUserDelta; } });
+Object.defineProperty(exports, "buildToolResultDelta", { enumerable: true, get: function () { return deltas_1.buildToolResultDelta; } });
+// ── Enums + constants ────────────────────────────────────────
+var types_1 = require("./types");
+Object.defineProperty(exports, "PoolingType", { enumerable: true, get: function () { return types_1.PoolingType; } });
+Object.defineProperty(exports, "CHAT_FORMAT_CONTENT_ONLY", { enumerable: true, get: function () { return types_1.CHAT_FORMAT_CONTENT_ONLY; } });
+Object.defineProperty(exports, "CHAT_FORMAT_GENERIC", { enumerable: true, get: function () { return types_1.CHAT_FORMAT_GENERIC; } });
+Object.defineProperty(exports, "ReasoningFormat", { enumerable: true, get: function () { return types_1.ReasoningFormat; } });
+Object.defineProperty(exports, "GrammarTriggerType", { enumerable: true, get: function () { return types_1.GrammarTriggerType; } });
+//# 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,mCAAkC;AAAzB,gGAAA,MAAM,OAAA;AACf,6CAA4C;AAAnC,0GAAA,WAAW,OAAA;AACpB,qCAAoC;AAA3B,kGAAA,OAAO,OAAA;AAChB,mCAAkC;AAAzB,gGAAA,MAAM,OAAA;AACf,mCAAgE;AAAvD,wGAAA,cAAc,OAAA;AAAE,8GAAA,oBAAoB,OAAA;AAE7C,gEAAgE;AAChE,iCAA0H;AAAjH,oGAAA,WAAW,OAAA;AAAE,iHAAA,wBAAwB,OAAA;AAAE,4GAAA,mBAAmB,OAAA;AAAE,wGAAA,eAAe,OAAA;AAAE,2GAAA,kBAAkB,OAAA"}