@lloyal-labs/sdk 1.7.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @lloyal-labs/sdk
2
2
 
3
- Backend-agnostic TypeScript SDK for the lloyal inference platform.
3
+ Backend-agnostic inference primitives for the [lloyal HDK](https://github.com/lloyal-ai/hdk).
4
4
 
5
5
  Composable inference primitives for forkable decode state, shared-prefix KV branching, and continuous tree batching. Branches share a KV prefix while keeping independent machinery — sampler chain, grammar, logits snapshot, perplexity tracker — for controlled divergence at decode time. `BranchStore` packs tokens from N branches (each at a different position, different seq_id, each needing independent logits captured) into a single `llama_batch` and dispatches once.
6
6
 
@@ -8,7 +8,7 @@ Composable inference primitives for forkable decode state, shared-prefix KV bran
8
8
  npm i @lloyal-labs/sdk
9
9
  ```
10
10
 
11
- The SDK exports the `SessionContext` contract and the primitives that operate on it. Backend bindings ([lloyal.node](https://github.com/lloyal-ai/lloyal.node), [nitro-llama](https://github.com/lloyal-ai/nitro-llama)) provide `createContext()` the SDK takes it from there.
11
+ The SDK exports the `SessionContext` contract and the primitives that operate on it. A backend binding (e.g. [`@lloyal-labs/lloyal.node`](https://github.com/lloyal-ai/lloyal.node) for Node) provides `createContext()` — the SDK takes it from there. Underneath, [liblloyal](https://github.com/lloyal-ai/liblloyal) is the C++ core; the Node binding is one front-end on top of it.
12
12
 
13
13
  ## The Branch API
14
14
 
@@ -123,16 +123,19 @@ branch.samplingPerplexity; // sampling-level PPL (from filtered distribution)
123
123
  ```typescript
124
124
  const session = new Session({ ctx, store });
125
125
 
126
- // Prefill a user turn into the trunk
127
- await session.prefillUser('What is quantum entanglement?');
126
+ // High-level: extend the trunk with a new query–answer pair
127
+ await session.commitTurn('What is quantum entanglement?', answer);
128
128
 
129
- // After generation + verification, promote a branch to become the new trunk
129
+ // Lower-level building blocks (for harnesses that orchestrate trunk lifecycle directly)
130
+ await session.prefillUser('What is quantum entanglement?');
130
131
  await session.promote(verifiedBranch);
131
132
 
132
133
  // Next query starts from the promoted trunk's KV state
133
134
  session.trunk; // the live branch
134
135
  ```
135
136
 
137
+ `commitTurn` is the recommended high-level helper. Future queries fork from `session.trunk` and read prior conversation through KV attention — no prompt-history injection.
138
+
136
139
  ## Rerank
137
140
 
138
141
  Backend-agnostic reranker. The caller provides a `SessionContext` — how it was created (local, remote, quantized) is not the SDK's concern.
package/dist/Session.js CHANGED
@@ -100,18 +100,19 @@ class Session {
100
100
  * @param response - Assistant response
101
101
  */
102
102
  async commitTurn(query, response) {
103
- const messages = [
104
- { role: 'user', content: query },
105
- { role: 'assistant', content: response },
106
- ];
107
103
  if (this._trunk) {
108
- const sep = this._ctx.getTurnSeparator();
109
- const { prompt } = this._ctx.formatChatSync(JSON.stringify(messages), { enableThinking: false });
110
- const tokens = this._ctx.tokenizeSync(prompt, false);
111
- await this._trunk.prefill([...sep, ...tokens]);
104
+ // Warm path: append turn delta (with separator) to existing trunk.
105
+ // Explicit enableThinking:false session trunk serializes completed
106
+ // conversations; no thinking blocks should be embedded.
107
+ await this._trunk.prefill((0, deltas_1.buildTurnDelta)(this._ctx, query, response, { enableThinking: false }));
112
108
  }
113
109
  else {
114
- const { prompt } = this._ctx.formatChatSync(JSON.stringify(messages), { enableThinking: false });
110
+ // Cold path: create trunk at position 0, prefill without separator
111
+ // (fresh branch — no prior turn to separate from), then promote.
112
+ const { prompt } = this._ctx.formatChatSync(JSON.stringify([
113
+ { role: 'user', content: query },
114
+ { role: 'assistant', content: response },
115
+ ]), { enableThinking: false });
115
116
  const tokens = this._ctx.tokenizeSync(prompt, false);
116
117
  const trunk = Branch_1.Branch.create(this._ctx, 0, {});
117
118
  await trunk.prefill(tokens);
@@ -1 +1 @@
1
- {"version":3,"file":"Session.js","sourceRoot":"","sources":["../src/Session.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"Session.js","sourceRoot":"","sources":["../src/Session.ts"],"names":[],"mappings":"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"}
package/dist/deltas.d.ts CHANGED
@@ -1,4 +1,31 @@
1
1
  import type { SessionContext } from './types';
2
+ /**
3
+ * Options common to all delta builders.
4
+ *
5
+ * `enableThinking` controls whether the chat template delimits `<think>`
6
+ * blocks. Despite its name, the flag is about template parsing, not about
7
+ * whether the model reasons: many models (Qwen3 family) emit thinking
8
+ * tokens regardless. Setting it `true` gives the template's generation
9
+ * prompt the `<think>\n` prefix those models expect, so their thoughts
10
+ * are correctly delimited and `parseChatOutput` can extract them from
11
+ * visible response. Setting it `false` tells the template to omit think
12
+ * tokens — appropriate when the downstream agent is expected not to think.
13
+ *
14
+ * **Default: undefined** — the delta builder does NOT pass the flag to
15
+ * `formatChatSync`, and the native template chooses (typically `true`).
16
+ * Callers who want `false` must pass it explicitly.
17
+ *
18
+ * This preserves compatibility with thinking-capable models. Hardcoding
19
+ * `false` at the delta-builder layer caused tool-result prefills to corrupt
20
+ * the KV cache for Qwen3-style models: the template omitted the think
21
+ * generation prompt, the model still emitted think tokens, and those
22
+ * tokens leaked into raw output.
23
+ *
24
+ * @category Agents
25
+ */
26
+ export interface DeltaOpts {
27
+ enableThinking?: boolean;
28
+ }
2
29
  /**
3
30
  * Build a token delta for a user turn
4
31
  *
@@ -11,14 +38,34 @@ import type { SessionContext } from './types';
11
38
  *
12
39
  * @param ctx - Active session context
13
40
  * @param content - User message content
14
- * @param opts - Optional tools JSON for tool-aware formatting
41
+ * @param opts - Optional tools JSON for tool-aware formatting + thinking flag
15
42
  * @returns Token array ready for `branch.prefill()`
16
43
  *
17
44
  * @category Agents
18
45
  */
19
46
  export declare function buildUserDelta(ctx: SessionContext, content: string, opts?: {
20
47
  tools?: string;
21
- }): number[];
48
+ } & DeltaOpts): number[];
49
+ /**
50
+ * Build a token delta for a complete user+assistant conversation turn
51
+ *
52
+ * Composes `getTurnSeparator()` + `formatChatSync()` + `tokenizeSync()` into a
53
+ * single token array suitable for `branch.prefill()`. The canonical way to
54
+ * extend any branch (trunk, shared root, or spine) with a completed turn.
55
+ *
56
+ * Used by {@link Session.commitTurn} to persist query/response to the trunk,
57
+ * and by `PoolContext.extendRoot` in the agent pool to chain per-task
58
+ * findings onto the research spine.
59
+ *
60
+ * @param ctx - Active session context
61
+ * @param userContent - User message content (the question/task)
62
+ * @param assistantContent - Assistant response content (the answer/findings)
63
+ * @param opts - Optional thinking flag; see {@link DeltaOpts}
64
+ * @returns Token array ready for `branch.prefill()`
65
+ *
66
+ * @category Agents
67
+ */
68
+ export declare function buildTurnDelta(ctx: SessionContext, userContent: string, assistantContent: string, opts?: DeltaOpts): number[];
22
69
  /**
23
70
  * Build a token delta for a tool result turn
24
71
  *
@@ -33,9 +80,10 @@ export declare function buildUserDelta(ctx: SessionContext, content: string, opt
33
80
  * @param ctx - Active session context
34
81
  * @param resultStr - JSON-serialized tool result
35
82
  * @param callId - Tool call identifier from the model's parsed output
83
+ * @param opts - Optional thinking flag; see {@link DeltaOpts}
36
84
  * @returns Token array ready for `branch.prefill()`
37
85
  *
38
86
  * @category Agents
39
87
  */
40
- export declare function buildToolResultDelta(ctx: SessionContext, resultStr: string, callId: string): number[];
88
+ export declare function buildToolResultDelta(ctx: SessionContext, resultStr: string, callId: string, opts?: DeltaOpts): number[];
41
89
  //# sourceMappingURL=deltas.d.ts.map
@@ -1 +1 @@
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;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,cAAc,EACnB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,MAAM,EAAE,CAkBV"}
1
+ {"version":3,"file":"deltas.d.ts","sourceRoot":"","sources":["../src/deltas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,SAAS;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,cAAc,EACnB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAc,GACxC,MAAM,EAAE,CAWV;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,cAAc,EACnB,WAAW,EAAE,MAAM,EACnB,gBAAgB,EAAE,MAAM,EACxB,IAAI,GAAE,SAAc,GACnB,MAAM,EAAE,CAYV;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,cAAc,EACnB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,SAAc,GACnB,MAAM,EAAE,CAqBV"}
package/dist/deltas.js CHANGED
@@ -1,6 +1,7 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.buildUserDelta = buildUserDelta;
4
+ exports.buildTurnDelta = buildTurnDelta;
4
5
  exports.buildToolResultDelta = buildToolResultDelta;
5
6
  /**
6
7
  * Build a token delta for a user turn
@@ -14,18 +15,52 @@ exports.buildToolResultDelta = buildToolResultDelta;
14
15
  *
15
16
  * @param ctx - Active session context
16
17
  * @param content - User message content
17
- * @param opts - Optional tools JSON for tool-aware formatting
18
+ * @param opts - Optional tools JSON for tool-aware formatting + thinking flag
18
19
  * @returns Token array ready for `branch.prefill()`
19
20
  *
20
21
  * @category Agents
21
22
  */
22
23
  function buildUserDelta(ctx, content, opts = {}) {
23
24
  const sep = ctx.getTurnSeparator();
24
- const fmtOpts = opts.tools ? { tools: opts.tools } : {};
25
+ const fmtOpts = {};
26
+ if (opts.tools)
27
+ fmtOpts.tools = opts.tools;
28
+ if (opts.enableThinking !== undefined)
29
+ fmtOpts.enableThinking = opts.enableThinking;
25
30
  const { prompt } = ctx.formatChatSync(JSON.stringify([{ role: 'system', content: '' }, { role: 'user', content }]), fmtOpts);
26
31
  const delta = ctx.tokenizeSync(prompt, false);
27
32
  return [...sep, ...delta];
28
33
  }
34
+ /**
35
+ * Build a token delta for a complete user+assistant conversation turn
36
+ *
37
+ * Composes `getTurnSeparator()` + `formatChatSync()` + `tokenizeSync()` into a
38
+ * single token array suitable for `branch.prefill()`. The canonical way to
39
+ * extend any branch (trunk, shared root, or spine) with a completed turn.
40
+ *
41
+ * Used by {@link Session.commitTurn} to persist query/response to the trunk,
42
+ * and by `PoolContext.extendRoot` in the agent pool to chain per-task
43
+ * findings onto the research spine.
44
+ *
45
+ * @param ctx - Active session context
46
+ * @param userContent - User message content (the question/task)
47
+ * @param assistantContent - Assistant response content (the answer/findings)
48
+ * @param opts - Optional thinking flag; see {@link DeltaOpts}
49
+ * @returns Token array ready for `branch.prefill()`
50
+ *
51
+ * @category Agents
52
+ */
53
+ function buildTurnDelta(ctx, userContent, assistantContent, opts = {}) {
54
+ const sep = ctx.getTurnSeparator();
55
+ const fmtOpts = {};
56
+ if (opts.enableThinking !== undefined)
57
+ fmtOpts.enableThinking = opts.enableThinking;
58
+ const { prompt } = ctx.formatChatSync(JSON.stringify([
59
+ { role: 'user', content: userContent },
60
+ { role: 'assistant', content: assistantContent },
61
+ ]), fmtOpts);
62
+ return [...sep, ...ctx.tokenizeSync(prompt, false)];
63
+ }
29
64
  /**
30
65
  * Build a token delta for a tool result turn
31
66
  *
@@ -40,16 +75,20 @@ function buildUserDelta(ctx, content, opts = {}) {
40
75
  * @param ctx - Active session context
41
76
  * @param resultStr - JSON-serialized tool result
42
77
  * @param callId - Tool call identifier from the model's parsed output
78
+ * @param opts - Optional thinking flag; see {@link DeltaOpts}
43
79
  * @returns Token array ready for `branch.prefill()`
44
80
  *
45
81
  * @category Agents
46
82
  */
47
- function buildToolResultDelta(ctx, resultStr, callId) {
83
+ function buildToolResultDelta(ctx, resultStr, callId, opts = {}) {
48
84
  const sep = ctx.getTurnSeparator();
85
+ const fmtOpts = {};
86
+ if (opts.enableThinking !== undefined)
87
+ fmtOpts.enableThinking = opts.enableThinking;
49
88
  const { prompt, generationPrompt } = ctx.formatChatSync(JSON.stringify([
50
89
  { role: 'system', content: '' },
51
90
  { role: 'tool', content: resultStr, tool_call_id: callId },
52
- ]));
91
+ ]), fmtOpts);
53
92
  const delta = ctx.tokenizeSync(prompt, false);
54
93
  // Append generation prompt (e.g. "<|im_start|>assistant\n<think>\n" for thinking models).
55
94
  // For non-thinking models this is "<|im_start|>assistant\n" which is already
@@ -1 +1 @@
1
- {"version":3,"file":"deltas.js","sourceRoot":"","sources":["../src/deltas.ts"],"names":[],"mappings":";;AAmBA,wCAaC;AAoBD,oDAsBC;AAxED;;;;;;;;;;;;;;;;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;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,oBAAoB,CAClC,GAAmB,EACnB,SAAiB,EACjB,MAAc;IAEd,MAAM,GAAG,GAAG,GAAG,CAAC,gBAAgB,EAAE,CAAC;IACnC,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,GAAG,GAAG,CAAC,cAAc,CACrD,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,0FAA0F;IAC1F,6EAA6E;IAC7E,6EAA6E;IAC7E,2DAA2D;IAC3D,IAAI,SAAS,GAAa,EAAE,CAAC;IAC7B,IAAI,gBAAgB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAC3D,SAAS,GAAG,GAAG,CAAC,YAAY,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,CAAC,GAAG,GAAG,EAAE,GAAG,KAAK,EAAE,GAAG,SAAS,CAAC,CAAC;AAC1C,CAAC"}
1
+ {"version":3,"file":"deltas.js","sourceRoot":"","sources":["../src/deltas.ts"],"names":[],"mappings":"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"}
package/dist/index.d.ts CHANGED
@@ -2,7 +2,8 @@ export { Branch } from './Branch';
2
2
  export { BranchStore } from './BranchStore';
3
3
  export { Session } from './Session';
4
4
  export { Rerank } from './Rerank';
5
- export { buildUserDelta, buildToolResultDelta } from './deltas';
5
+ export { buildUserDelta, buildToolResultDelta, buildTurnDelta } from './deltas';
6
+ export type { DeltaOpts } from './deltas';
6
7
  export { PoolingType, CHAT_FORMAT_CONTENT_ONLY, CHAT_FORMAT_GENERIC, ReasoningFormat, GrammarTriggerType } from './types';
7
8
  export type { ChatFormat } from './types';
8
9
  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';
@@ -1 +1 @@
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"}
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,cAAc,EAAE,MAAM,UAAU,CAAC;AAChF,YAAY,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAG1C,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 CHANGED
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- 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;
3
+ exports.GrammarTriggerType = exports.ReasoningFormat = exports.CHAT_FORMAT_GENERIC = exports.CHAT_FORMAT_CONTENT_ONLY = exports.PoolingType = exports.buildTurnDelta = exports.buildToolResultDelta = exports.buildUserDelta = exports.Rerank = exports.Session = exports.BranchStore = exports.Branch = void 0;
4
4
  var Branch_1 = require("./Branch");
5
5
  Object.defineProperty(exports, "Branch", { enumerable: true, get: function () { return Branch_1.Branch; } });
6
6
  var BranchStore_1 = require("./BranchStore");
@@ -12,6 +12,7 @@ Object.defineProperty(exports, "Rerank", { enumerable: true, get: function () {
12
12
  var deltas_1 = require("./deltas");
13
13
  Object.defineProperty(exports, "buildUserDelta", { enumerable: true, get: function () { return deltas_1.buildUserDelta; } });
14
14
  Object.defineProperty(exports, "buildToolResultDelta", { enumerable: true, get: function () { return deltas_1.buildToolResultDelta; } });
15
+ Object.defineProperty(exports, "buildTurnDelta", { enumerable: true, get: function () { return deltas_1.buildTurnDelta; } });
15
16
  // ── Enums + constants ────────────────────────────────────────
16
17
  var types_1 = require("./types");
17
18
  Object.defineProperty(exports, "PoolingType", { enumerable: true, get: function () { return types_1.PoolingType; } });
package/dist/index.js.map CHANGED
@@ -1 +1 @@
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"}
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,mCAAgF;AAAvE,wGAAA,cAAc,OAAA;AAAE,8GAAA,oBAAoB,OAAA;AAAE,wGAAA,cAAc,OAAA;AAG7D,gEAAgE;AAChE,iCAA0H;AAAjH,oGAAA,WAAW,OAAA;AAAE,iHAAA,wBAAwB,OAAA;AAAE,4GAAA,mBAAmB,OAAA;AAAE,wGAAA,eAAe,OAAA;AAAE,2GAAA,kBAAkB,OAAA"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lloyal-labs/sdk",
3
- "version": "1.7.0",
3
+ "version": "2.0.0",
4
4
  "description": "Backend-agnostic TypeScript SDK for the lloyal inference platform",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
@@ -9,12 +9,12 @@
9
9
  },
10
10
  "repository": {
11
11
  "type": "git",
12
- "url": "git+https://github.com/lloyal-ai/sdk.git",
12
+ "url": "git+https://github.com/lloyal-ai/hdk.git",
13
13
  "directory": "packages/sdk"
14
14
  },
15
- "homepage": "https://github.com/lloyal-ai/sdk#readme",
15
+ "homepage": "https://github.com/lloyal-ai/hdk#readme",
16
16
  "bugs": {
17
- "url": "https://github.com/lloyal-ai/sdk/issues"
17
+ "url": "https://github.com/lloyal-ai/hdk/issues"
18
18
  },
19
19
  "keywords": [
20
20
  "llm",