@12-apps/llm 1.0.0 → 1.2.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 +191 -4
- package/dist/index.d.ts +333 -6
- package/dist/index.js +612 -9
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -16,9 +16,14 @@ interface onto the provider's official SDK and maps the answer back.
|
|
|
16
16
|
refresh hook, both behind one interface.
|
|
17
17
|
- **A tool-use loop** that reports every turn's usage.
|
|
18
18
|
- **Typed errors** and one retry hook the host supplies.
|
|
19
|
+
- **A support ladder**: automation, then model tiers that escalate, then a
|
|
20
|
+
person, with least-privilege tools per tier bound to the host's scope.
|
|
19
21
|
|
|
20
|
-
|
|
21
|
-
transcription
|
|
22
|
+
- **Speech to text** behind the same shape: `createTranscriber`, a registry
|
|
23
|
+
of transcription adapters, ElevenLabs' Scribe built in (see
|
|
24
|
+
[Speech to text](#speech-to-text)).
|
|
25
|
+
|
|
26
|
+
Chat and transcription ship today; an adapter declares what it can do.
|
|
22
27
|
|
|
23
28
|
## Install
|
|
24
29
|
|
|
@@ -260,7 +265,7 @@ const outcome = await runToolLoop({
|
|
|
260
265
|
onUsage: (usage, turn) => meter.record(usage), // once per turn, refused turns included
|
|
261
266
|
});
|
|
262
267
|
|
|
263
|
-
outcome.status; // "completed" | "refused" | "max_turns" | "max_tokens" | "stopped"
|
|
268
|
+
outcome.status; // "completed" | "refused" | "max_turns" | "max_tokens" | "stopped" | "halted"
|
|
264
269
|
outcome.messages; // the conversation with every turn and tool result appended
|
|
265
270
|
outcome.usage; // the summed usage
|
|
266
271
|
outcome.refusal; // set when status is "refused"
|
|
@@ -269,7 +274,187 @@ outcome.refusal; // set when status is "refused"
|
|
|
269
274
|
The loop runs every tool call of a turn and sends all the results back
|
|
270
275
|
together. An unknown tool, or an executor that throws, becomes an error result
|
|
271
276
|
the model can read and recover from. When the turn limit is reached, the loop
|
|
272
|
-
stops without running the last turn's calls.
|
|
277
|
+
stops without running the last turn's calls. An executor that returns
|
|
278
|
+
`{ output, halt: true }` ends the loop with `status: "halted"` once every call
|
|
279
|
+
of that turn has its result, and no further model call is made.
|
|
280
|
+
|
|
281
|
+
## The support ladder
|
|
282
|
+
|
|
283
|
+
`createSupportLadder` routes each customer message up a ladder. Automation
|
|
284
|
+
answers what the host recognises with no model call. Anything else goes to
|
|
285
|
+
the first model tier, which answers or escalates. A tier escalates to the next
|
|
286
|
+
tier, which runs on the same message in the same call, or to a person. The
|
|
287
|
+
ladder carries no domain: tiers, tools, copy and the person are all the host's.
|
|
288
|
+
|
|
289
|
+
```ts
|
|
290
|
+
import { createSupportLadder, mcpTools } from "@12-apps/llm";
|
|
291
|
+
|
|
292
|
+
const ladder = createSupportLadder<{ accountId: string }, { locale: string }>({
|
|
293
|
+
automation: {
|
|
294
|
+
greeting: () => "Hi! Reply 1 for opening hours, 2 to reset your password.",
|
|
295
|
+
match: (message) => (message.trim() === "1" ? { reply: "We answer 9 to 5, Monday to Friday." } : null),
|
|
296
|
+
},
|
|
297
|
+
tiers: [
|
|
298
|
+
{
|
|
299
|
+
id: "triage",
|
|
300
|
+
client: { provider: "openai", model: "gpt-5-mini", credentials }, // or a ModelClient
|
|
301
|
+
instructions: "You answer simple helpdesk questions from the knowledge base.",
|
|
302
|
+
tools: [searchArticles], // read-only
|
|
303
|
+
},
|
|
304
|
+
{
|
|
305
|
+
id: "specialist",
|
|
306
|
+
client: { provider: "anthropic", model: "claude-opus-5-5", credentials },
|
|
307
|
+
instructions: "You resolve account problems, or hand them to a person.",
|
|
308
|
+
tools: [
|
|
309
|
+
searchArticles,
|
|
310
|
+
mcpTools({
|
|
311
|
+
connect: (scope) => accountServer.connectAs(scope.accountId), // the scope's own token
|
|
312
|
+
allow: ["reset_password"], // nothing else of the server's
|
|
313
|
+
}),
|
|
314
|
+
],
|
|
315
|
+
},
|
|
316
|
+
],
|
|
317
|
+
person: { handOff: ({ conversationId, reason, fromTier }) => queue.push({ conversationId, reason, fromTier }) },
|
|
318
|
+
state: {
|
|
319
|
+
get: (id) => levels.get(id),
|
|
320
|
+
// ATOMIC compare-and-set: store `to` only while the level is still `from`.
|
|
321
|
+
raise: (id, from, to) => levels.compareAndSet(id, from, to), // true when it moved
|
|
322
|
+
},
|
|
323
|
+
scopeFields: ["accountId"], // the model may never set these
|
|
324
|
+
onUsage: (tier, usage) => meter.record(tier, usage),
|
|
325
|
+
});
|
|
326
|
+
|
|
327
|
+
const result = await ladder.handle({
|
|
328
|
+
conversationId: "conv-42",
|
|
329
|
+
message: "I can't sign in",
|
|
330
|
+
transcript, // the conversation before this message
|
|
331
|
+
context: { locale: "en" },
|
|
332
|
+
scope: { accountId: "acct-7" }, // from the host's session, never from the model
|
|
333
|
+
});
|
|
334
|
+
|
|
335
|
+
switch (result.kind) {
|
|
336
|
+
case "automation": send(result.reply); break; // source: "greeting" | "match"
|
|
337
|
+
case "model": send(result.reply); break; // result.tier answered
|
|
338
|
+
case "person": notifyAgent(result); break; // fromTier, reason, handedOff
|
|
339
|
+
}
|
|
340
|
+
result.usage; // [{ tier, turns, usage }] per tier that ran, to meter each model separately
|
|
341
|
+
result.escalations; // [{ from, to, reason }]
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
- **Each tier answers or escalates.** Every tier gets the ladder's `escalate`
|
|
345
|
+
tool, `{ to: "next" | "person", reason }`; `"next"` is not offered on the last
|
|
346
|
+
tier. A refusal escalates with reason `"refused"`, and a turn with no words
|
|
347
|
+
with `"no_answer"`: to the next tier, or to a person from the last. A turn
|
|
348
|
+
that calls `escalate` leaves the tier: the other tools it called in that
|
|
349
|
+
turn are answered "not run" and never execute, and when it calls `escalate`
|
|
350
|
+
more than once, the FIRST call (in the model's order) decides and the rest
|
|
351
|
+
are ignored.
|
|
352
|
+
- **The next tier hears why.** The escalating tier's reason reaches the next
|
|
353
|
+
tier as a delimited USER-role note just before the customer's message
|
|
354
|
+
(`<handover from="…">…</handover>`, at most 500 characters, angle brackets
|
|
355
|
+
removed), never as a system block: it is the prior model's words, derived
|
|
356
|
+
from the customer's. The note is left out of the `messages` a result returns.
|
|
357
|
+
- **A conversation stays where it reached.** The `state` port stores the tier
|
|
358
|
+
that answered, or `"person"` (`WITH_PERSON`). The next message goes straight
|
|
359
|
+
to that tier; automation is consulted only before a conversation reached a
|
|
360
|
+
tier. Once a person has it, `handle` returns `{ kind: "person", handedOff:
|
|
361
|
+
false }` and never calls a model or `handOff` again.
|
|
362
|
+
- **Two messages in flight.** A customer can send two lines before the first
|
|
363
|
+
is answered, so the ladder never writes a level blindly. The port's one
|
|
364
|
+
write is `raise(conversationId, from, to) → boolean`, which the host makes
|
|
365
|
+
ATOMIC (a conditional `UPDATE … WHERE level = $from`, a Redis `WATCH`/Lua
|
|
366
|
+
compare-and-set, a Map on one event loop). The ladder only raises: an answer
|
|
367
|
+
from a lower tier leaves a higher stored level alone, and an answer that
|
|
368
|
+
finishes after the conversation reached a person returns `{ kind: "person",
|
|
369
|
+
handedOff: false, fromTier: null }` instead of the model's reply. Only the
|
|
370
|
+
call whose raise to `"person"` wins calls `handOff`, once, after the raise.
|
|
371
|
+
A raise that loses re-reads and retries; a port whose level keeps moving
|
|
372
|
+
is refused (`state_conflict`).
|
|
373
|
+
- **Resetting a conversation.** The host resets one by deleting its stored
|
|
374
|
+
level, so `get` returns nothing: the next message starts at automation and
|
|
375
|
+
the first tier again. The ladder has no reset of its own and never lowers a
|
|
376
|
+
level. A conversation stored on a tier id that no longer exists (a tier
|
|
377
|
+
renamed or removed) starts again at the first tier, skipping automation.
|
|
378
|
+
- **Least privilege per tier.** A tier's model sees exactly that tier's tools
|
|
379
|
+
plus `escalate`. A call to another tier's tool is answered as an unknown
|
|
380
|
+
tool and never runs.
|
|
381
|
+
- **Tools from MCP.** `mcpTools({ connect, allow, overrides? })` connects for
|
|
382
|
+
each call's scope and offers ONLY the allow-listed tools; the rest of the
|
|
383
|
+
server's list is never shown, and a call to one never reaches the server.
|
|
384
|
+
An allowed tool the server lacks is refused (`tool_missing`; the
|
|
385
|
+
conversation then goes to a person, see "A tool source that fails"). The client is
|
|
386
|
+
structural (`listTools`, `callTool`, as the official MCP SDK's `Client`), so
|
|
387
|
+
the package depends on no MCP SDK. Tool schemas must be strict; `overrides`
|
|
388
|
+
replaces a description or schema the server ships loose.
|
|
389
|
+
- **What `mcpTools` costs.** Every `handle` call, for every tier that runs,
|
|
390
|
+
calls `connect(scope)` and lists the server's tools (every page). Nothing is
|
|
391
|
+
cached inside the package, on purpose, so one scope's client never serves
|
|
392
|
+
another's. Cache on the host's side, keyed by the scope: have `connect`
|
|
393
|
+
return a client kept per scope (an LRU of connections, with the scope's own
|
|
394
|
+
credentials), and close it when the scope's session ends.
|
|
395
|
+
- **A tool source that fails.** When a source throws (`connect` fails, an
|
|
396
|
+
allowed tool is missing, a server tool clashes with `escalate` or exposes a
|
|
397
|
+
scope field), the conversation goes to a person with reason
|
|
398
|
+
`"tool_error"`, and `usage` still lists the tiers that already ran.
|
|
399
|
+
- **Scope binding.** `scope` is opaque to the ladder. Every tool's `run` gets
|
|
400
|
+
it in its context, and an MCP server gets it through the host's `connect`,
|
|
401
|
+
never through the model. For a server whose tools take the tenant as an
|
|
402
|
+
ARGUMENT, `mcpTools({ …, bindArgs: (scope, toolName) => ({ tenantId:
|
|
403
|
+
scope.tenantId }) })` merges those arguments AFTER the model's input (the
|
|
404
|
+
host's value wins), removes their names from the schema the model sees, and
|
|
405
|
+
refuses, without reaching the server, a model call that sets one. A tool
|
|
406
|
+
whose schema declares a `scopeFields` name is refused (`scope_exposed`), and a model call whose arguments carry one is
|
|
407
|
+
refused without running, so a conversation for one account cannot reach
|
|
408
|
+
another's data even when both use the same tools.
|
|
409
|
+
- **Refused configurations** throw `SupportLadderError` (an
|
|
410
|
+
`InvalidRequestError`) with a `code`: `empty_tiers`, `duplicate_tier` (a tier
|
|
411
|
+
id listed twice), `reserved_tier` (a tier named `"person"`), `tool_conflict`,
|
|
412
|
+
`tool_missing`, `scope_exposed`; and `state_conflict` when the state port's
|
|
413
|
+
level keeps changing while the ladder raises it.
|
|
414
|
+
|
|
415
|
+
## Speech to text
|
|
416
|
+
|
|
417
|
+
`createTranscriber` is `createModelClient`'s sibling for recordings: one
|
|
418
|
+
interface, one normalized result, an adapter per provider picked by id from a
|
|
419
|
+
registry the host can extend. ElevenLabs' speech-to-text ("Scribe") is built in,
|
|
420
|
+
over a direct `fetch` (no SDK to install).
|
|
421
|
+
|
|
422
|
+
```ts
|
|
423
|
+
import { createTranscriber } from "@12-apps/llm";
|
|
424
|
+
|
|
425
|
+
const transcriber = createTranscriber({
|
|
426
|
+
provider: "elevenlabs",
|
|
427
|
+
credentials: { kind: "apiKey", apiKey: () => readKeyFromYourVault() },
|
|
428
|
+
// model defaults to "scribe_v2"; retry takes the same hook as the chat client
|
|
429
|
+
});
|
|
430
|
+
|
|
431
|
+
const result = await transcriber.transcribe({
|
|
432
|
+
audio: bytes, // Uint8Array | Blob
|
|
433
|
+
mimeType: "audio/ogg",
|
|
434
|
+
languageHint: "pt", // optional: the provider detects the language otherwise
|
|
435
|
+
maxDurationSeconds: 120, // optional
|
|
436
|
+
durationSeconds: 37, // optional: the length, when the host already knows it
|
|
437
|
+
});
|
|
438
|
+
// { provider, model, text, language?, durationSeconds, usage: { audioSeconds } }
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
- **Duration limit.** A recording longer than `maxDurationSeconds` throws
|
|
442
|
+
`AudioTooLongError` (an `InvalidRequestError`, so never retried). It is
|
|
443
|
+
refused before anything is sent when the host passes `durationSeconds`, and
|
|
444
|
+
after the call when the provider reports a longer `audioSeconds`
|
|
445
|
+
(`beforeSending` says which).
|
|
446
|
+
- **Credentials:** API keys only. The adapter's calls go through the same
|
|
447
|
+
sealed edge as chat: one allowed route, no redirects, only the call's own key,
|
|
448
|
+
nothing from the platform's environment.
|
|
449
|
+
- **Errors** are the table below: 401/403 `AuthError`, 429 `RateLimitError`,
|
|
450
|
+
5xx and network failures `ProviderUnavailableError`, any other 4xx
|
|
451
|
+
`InvalidRequestError`. A 200 that carries no transcript (a webhook-shaped
|
|
452
|
+
`{ message, request_id }` body) is an `InvalidResponseError`.
|
|
453
|
+
- **Duration.** `durationSeconds` is the provider's `audio_duration_secs`, else
|
|
454
|
+
the last word's end, else the `durationSeconds` the host passed, else 0.
|
|
455
|
+
- **A second provider** is one `TranscriptionAdapter` (`id`, `credentialKinds`,
|
|
456
|
+
`transcribe(call)`) registered with `createTranscriptionRegistry(...)` and
|
|
457
|
+
passed as `registry`.
|
|
273
458
|
|
|
274
459
|
## Errors and retries
|
|
275
460
|
|
|
@@ -279,9 +464,11 @@ stops without running the last turn's calls.
|
|
|
279
464
|
| `RateLimitError` | 429; `retryAfterMs` comes from `retry-after-ms` or `retry-after` |
|
|
280
465
|
| `InvalidRequestError` | 400, 404, 413 or 422, a non-strict tool schema, too many breakpoints |
|
|
281
466
|
| `ProviderUnavailableError` | 5xx, 529, 408, network failures |
|
|
467
|
+
| `AudioTooLongError` | a recording over `maxDurationSeconds`; an `InvalidRequestError` |
|
|
282
468
|
| `InvalidResponseError` | an answer the adapter cannot read (tool arguments that are not JSON) |
|
|
283
469
|
| `RefusalError` | thrown only by `ensureNotRefused` |
|
|
284
470
|
| `UnsupportedError` | an unknown provider, an undeclared credential kind, a missing optional SDK |
|
|
471
|
+
| `SupportLadderError` | a support ladder's configuration or state refused; see `code` |
|
|
285
472
|
|
|
286
473
|
All of them extend `LlmError`, which has `kind`, `provider` and `status`. The
|
|
287
474
|
SDKs' own retries are switched off. The host's `retry` hook is the whole
|
package/dist/index.d.ts
CHANGED
|
@@ -407,9 +407,6 @@ declare const XAI_PROVIDER = "xai";
|
|
|
407
407
|
type XaiAdapterOptions = OpenAIAdapterOptions;
|
|
408
408
|
declare function xaiAdapter(options?: XaiAdapterOptions): ProviderAdapter;
|
|
409
409
|
|
|
410
|
-
/** Fresh instances of the built-in adapters, with their defaults. */
|
|
411
|
-
declare function builtInAdapters(): ProviderAdapter[];
|
|
412
|
-
|
|
413
410
|
/**
|
|
414
411
|
* Typed errors. Every adapter maps its SDK's failures onto these, so a host
|
|
415
412
|
* decides retry, hand-off and alerting once, whatever the provider.
|
|
@@ -448,6 +445,14 @@ declare class RefusalError extends LlmError {
|
|
|
448
445
|
declare class InvalidRequestError extends LlmError {
|
|
449
446
|
constructor(provider: string, message: string, status?: number);
|
|
450
447
|
}
|
|
448
|
+
/** The recording is longer than the host allows; it will fail again as is. */
|
|
449
|
+
declare class AudioTooLongError extends InvalidRequestError {
|
|
450
|
+
readonly durationSeconds: number;
|
|
451
|
+
readonly maxDurationSeconds: number;
|
|
452
|
+
/** True when the refusal came before anything was sent. */
|
|
453
|
+
readonly beforeSending: boolean;
|
|
454
|
+
constructor(provider: string, durationSeconds: number, maxDurationSeconds: number, beforeSending: boolean);
|
|
455
|
+
}
|
|
451
456
|
/** The provider is down, overloaded or unreachable (5xx, 529, network). */
|
|
452
457
|
declare class ProviderUnavailableError extends LlmError {
|
|
453
458
|
constructor(provider: string, message: string, status?: number);
|
|
@@ -460,6 +465,18 @@ declare class InvalidResponseError extends LlmError {
|
|
|
460
465
|
declare class UnsupportedError extends LlmError {
|
|
461
466
|
constructor(provider: string, message: string);
|
|
462
467
|
}
|
|
468
|
+
/** Why a support ladder refused its configuration or a state it was handed. */
|
|
469
|
+
type SupportLadderErrorCode = "empty_tiers" | "duplicate_tier" | "state_conflict" | "reserved_tier" | "tool_conflict" | "tool_missing" | "scope_exposed";
|
|
470
|
+
/**
|
|
471
|
+
* A support ladder refused a configuration (no tier, a tier id used twice, a
|
|
472
|
+
* tier named like the person level, a tool name clash, a tool whose schema
|
|
473
|
+
* exposes a scope-bound field, an allow-listed tool the source does not have),
|
|
474
|
+
* or the host's state port kept moving a level while the ladder raised it.
|
|
475
|
+
*/
|
|
476
|
+
declare class SupportLadderError extends InvalidRequestError {
|
|
477
|
+
readonly code: SupportLadderErrorCode;
|
|
478
|
+
constructor(code: SupportLadderErrorCode, message: string);
|
|
479
|
+
}
|
|
463
480
|
/** `retry-after-ms`, else `retry-after` in seconds or as an HTTP date. */
|
|
464
481
|
declare function retryAfterFrom(headers: unknown, now?: () => number): number | undefined;
|
|
465
482
|
/**
|
|
@@ -512,6 +529,100 @@ declare function retryTransient(options?: {
|
|
|
512
529
|
}): RetryPolicy;
|
|
513
530
|
declare function createModelClient(options: ModelClientOptions): ModelClient;
|
|
514
531
|
|
|
532
|
+
/**
|
|
533
|
+
* Speech to text behind the same interchangeable-provider shape as the chat
|
|
534
|
+
* connector: `createTranscriber` picks a `TranscriptionAdapter` by provider id
|
|
535
|
+
* from a registry the host can extend, and wraps it with what every provider
|
|
536
|
+
* shares (the credential strategy and the host's retry policy). A second
|
|
537
|
+
* provider is one adapter, registered next to the built-in one.
|
|
538
|
+
*/
|
|
539
|
+
|
|
540
|
+
/** One recording to transcribe. */
|
|
541
|
+
interface TranscriptionRequest {
|
|
542
|
+
/** The recording's bytes. */
|
|
543
|
+
audio: Uint8Array | Blob;
|
|
544
|
+
/** The recording's media type, e.g. `audio/ogg`. */
|
|
545
|
+
mimeType: string;
|
|
546
|
+
/** A BCP-47 / ISO 639 language code (`pt`); omitted, the provider detects it. */
|
|
547
|
+
languageHint?: string;
|
|
548
|
+
/** Longest recording accepted, in seconds; a longer one is refused with `AudioTooLongError`. */
|
|
549
|
+
maxDurationSeconds?: number;
|
|
550
|
+
/** The recording's length when the host already knows it, so a too-long one is refused before any byte is sent. */
|
|
551
|
+
durationSeconds?: number;
|
|
552
|
+
/** Aborts the call. */
|
|
553
|
+
signal?: AbortSignal;
|
|
554
|
+
}
|
|
555
|
+
interface TranscriptionUsage {
|
|
556
|
+
/** The audio the provider processed, which is what it bills. */
|
|
557
|
+
audioSeconds: number;
|
|
558
|
+
}
|
|
559
|
+
interface TranscriptionResult {
|
|
560
|
+
provider: string;
|
|
561
|
+
model: string;
|
|
562
|
+
text: string;
|
|
563
|
+
/** The language the provider heard, when it says. */
|
|
564
|
+
language?: string;
|
|
565
|
+
durationSeconds: number;
|
|
566
|
+
usage: TranscriptionUsage;
|
|
567
|
+
}
|
|
568
|
+
/** What the transcriber hands an adapter for one call. */
|
|
569
|
+
interface TranscribeCall {
|
|
570
|
+
model: string;
|
|
571
|
+
request: TranscriptionRequest;
|
|
572
|
+
credential: ResolvedCredential;
|
|
573
|
+
}
|
|
574
|
+
interface TranscriptionAdapter {
|
|
575
|
+
/** The provider id a host names in `createTranscriber({ provider })`. */
|
|
576
|
+
readonly id: string;
|
|
577
|
+
/** Used when the host names no model; an adapter may ship none. */
|
|
578
|
+
readonly defaultModel?: string;
|
|
579
|
+
readonly credentialKinds: readonly CredentialKind[];
|
|
580
|
+
/** Transcribe one recording. Throws the package's typed errors. */
|
|
581
|
+
transcribe(call: TranscribeCall): Promise<TranscriptionResult>;
|
|
582
|
+
}
|
|
583
|
+
interface TranscriptionRegistry {
|
|
584
|
+
register(adapter: TranscriptionAdapter, options?: {
|
|
585
|
+
replace?: boolean;
|
|
586
|
+
}): TranscriptionRegistry;
|
|
587
|
+
get(id: string): TranscriptionAdapter;
|
|
588
|
+
has(id: string): boolean;
|
|
589
|
+
ids(): string[];
|
|
590
|
+
}
|
|
591
|
+
declare function createTranscriptionRegistry(adapters?: readonly TranscriptionAdapter[]): TranscriptionRegistry;
|
|
592
|
+
/** Fresh instances of the built-in transcription adapters, with their defaults. */
|
|
593
|
+
declare function builtInTranscriptionAdapters(): TranscriptionAdapter[];
|
|
594
|
+
interface TranscriberOptions {
|
|
595
|
+
provider: string;
|
|
596
|
+
/** Defaults to the adapter's default model. */
|
|
597
|
+
model?: string;
|
|
598
|
+
credentials: Credentials;
|
|
599
|
+
retry?: RetryPolicy;
|
|
600
|
+
/** Where to find adapters. Defaults to a registry of the built-in one (ElevenLabs). */
|
|
601
|
+
registry?: TranscriptionRegistry;
|
|
602
|
+
/** Test seams. */
|
|
603
|
+
sleep?: (ms: number) => Promise<void>;
|
|
604
|
+
now?: () => number;
|
|
605
|
+
}
|
|
606
|
+
interface Transcriber {
|
|
607
|
+
readonly provider: string;
|
|
608
|
+
readonly model: string;
|
|
609
|
+
transcribe(request: TranscriptionRequest): Promise<TranscriptionResult>;
|
|
610
|
+
}
|
|
611
|
+
declare function createTranscriber(options: TranscriberOptions): Transcriber;
|
|
612
|
+
|
|
613
|
+
declare const ELEVENLABS_PROVIDER = "elevenlabs";
|
|
614
|
+
declare const ELEVENLABS_DEFAULT_MODEL = "scribe_v2";
|
|
615
|
+
interface ElevenLabsAdapterOptions {
|
|
616
|
+
baseURL?: string;
|
|
617
|
+
/** The `fetch` the adapter sends with (a proxy, a test double). */
|
|
618
|
+
fetch?: typeof globalThis.fetch;
|
|
619
|
+
defaultModel?: string;
|
|
620
|
+
}
|
|
621
|
+
declare function elevenLabsAdapter(options?: ElevenLabsAdapterOptions): TranscriptionAdapter;
|
|
622
|
+
|
|
623
|
+
/** Fresh instances of the built-in adapters, with their defaults. */
|
|
624
|
+
declare function builtInAdapters(): ProviderAdapter[];
|
|
625
|
+
|
|
515
626
|
/**
|
|
516
627
|
* The tool-use loop: run turns until the model stops calling tools, refuses,
|
|
517
628
|
* runs out of output budget, or the turn limit is reached.
|
|
@@ -522,6 +633,10 @@ declare function createModelClient(options: ModelClientOptions): ModelClient;
|
|
|
522
633
|
* loop. A refusal is a typed RESULT (`status: "refused"`), never an error, so
|
|
523
634
|
* the host can hand the conversation to a person.
|
|
524
635
|
*
|
|
636
|
+
* An executor may HALT the loop (`{ output, halt: true }`): the turn's tool
|
|
637
|
+
* results are appended and the loop ends with `status: "halted"` without
|
|
638
|
+
* another model call. A hand-off tool uses it to leave the conversation.
|
|
639
|
+
*
|
|
525
640
|
* The returned `messages` are always a valid request for the NEXT turn (B2):
|
|
526
641
|
* a turn the loop ends on keeps its text but never a tool call that was not
|
|
527
642
|
* run (no tool_use without its tool_result), and a turn with neither text nor
|
|
@@ -529,14 +644,20 @@ declare function createModelClient(options: ModelClientOptions): ModelClient;
|
|
|
529
644
|
* the provider reject the host's next request with a 400.
|
|
530
645
|
*/
|
|
531
646
|
|
|
532
|
-
/**
|
|
647
|
+
/**
|
|
648
|
+
* What an executor returns: the output text, or the text marked as an error.
|
|
649
|
+
* `halt` ends the loop once this turn's calls have all run.
|
|
650
|
+
*/
|
|
533
651
|
type ToolOutput = string | {
|
|
534
652
|
output: string;
|
|
535
653
|
isError?: boolean;
|
|
654
|
+
halt?: boolean;
|
|
536
655
|
};
|
|
656
|
+
/** `calls` is every call of the same turn, `call` among them, in the model's order. */
|
|
537
657
|
type ToolExecutor = (input: unknown, context: {
|
|
538
658
|
call: ToolCall;
|
|
539
659
|
turn: number;
|
|
660
|
+
calls: readonly ToolCall[];
|
|
540
661
|
}) => Promise<ToolOutput> | ToolOutput;
|
|
541
662
|
interface ToolLoopOptions {
|
|
542
663
|
client: ModelClient;
|
|
@@ -548,7 +669,7 @@ interface ToolLoopOptions {
|
|
|
548
669
|
/** Called once per turn with that turn's usage, turn numbers from 1. */
|
|
549
670
|
onUsage?: (usage: Usage, turn: number, result: ChatResult) => void | Promise<void>;
|
|
550
671
|
}
|
|
551
|
-
type ToolLoopStatus = "completed" | "refused" | "max_turns" | "max_tokens" | "stopped";
|
|
672
|
+
type ToolLoopStatus = "completed" | "refused" | "max_turns" | "max_tokens" | "stopped" | "halted";
|
|
552
673
|
interface ToolLoopResult {
|
|
553
674
|
status: ToolLoopStatus;
|
|
554
675
|
/** The conversation, with every turn and tool result appended. */
|
|
@@ -565,6 +686,212 @@ declare function runToolLoop(options: ToolLoopOptions): Promise<ToolLoopResult>;
|
|
|
565
686
|
/** Throw a `RefusalError` when a turn was refused; return it otherwise. */
|
|
566
687
|
declare function ensureNotRefused(result: ChatResult): ChatResult;
|
|
567
688
|
|
|
689
|
+
/** The level a conversation is at once a person has it. */
|
|
690
|
+
declare const WITH_PERSON = "person";
|
|
691
|
+
type Awaitable$1<T> = T | Promise<T>;
|
|
692
|
+
/** Where the host keeps the level each conversation reached. */
|
|
693
|
+
interface SupportStatePort {
|
|
694
|
+
/** A tier id, `"person"`, or nothing for a conversation that reached no tier. */
|
|
695
|
+
get(conversationId: string): Awaitable$1<string | null | undefined>;
|
|
696
|
+
/**
|
|
697
|
+
* ATOMIC on the host's side: when the stored level is still `from` (`null`:
|
|
698
|
+
* nothing stored), store `to` and return true; otherwise change nothing and
|
|
699
|
+
* return false. One conditional write, e.g. `UPDATE … SET level = $to WHERE
|
|
700
|
+
* id = $id AND level = $from` (an insert that loses on the key when `from`
|
|
701
|
+
* is null) and true when it touched a row. The ladder only ever raises.
|
|
702
|
+
*/
|
|
703
|
+
raise(conversationId: string, from: string | null, to: string): Awaitable$1<boolean>;
|
|
704
|
+
}
|
|
705
|
+
|
|
706
|
+
/** What a tool's `run` is told, all of it from the host, none from the model. */
|
|
707
|
+
interface SupportToolContext<Scope = unknown, Context = unknown> {
|
|
708
|
+
scope: Scope;
|
|
709
|
+
context: Context;
|
|
710
|
+
conversationId: string;
|
|
711
|
+
/** The id of the tier whose model called the tool. */
|
|
712
|
+
tier: string;
|
|
713
|
+
call: ToolCall;
|
|
714
|
+
}
|
|
715
|
+
/** A tool a tier offers its model: a strict definition and its handler. */
|
|
716
|
+
interface SupportTool<Scope = unknown, Context = unknown> {
|
|
717
|
+
definition: ToolDefinition;
|
|
718
|
+
run(input: unknown, context: SupportToolContext<Scope, Context>): ToolOutput | Promise<ToolOutput>;
|
|
719
|
+
}
|
|
720
|
+
/**
|
|
721
|
+
* Tools resolved per `handle()` call for that call's scope, such as an MCP
|
|
722
|
+
* server reached with the scope's own credentials (`mcpTools`).
|
|
723
|
+
*/
|
|
724
|
+
interface SupportToolSource<Scope = unknown, Context = unknown> {
|
|
725
|
+
resolve(scope: Scope): readonly SupportTool<Scope, Context>[] | Promise<readonly SupportTool<Scope, Context>[]>;
|
|
726
|
+
}
|
|
727
|
+
type SupportToolEntry<Scope = unknown, Context = unknown> = SupportTool<Scope, Context> | SupportToolSource<Scope, Context>;
|
|
728
|
+
/** The ladder's own tool. */
|
|
729
|
+
declare const ESCALATE_TOOL = "escalate";
|
|
730
|
+
type EscalationTarget = "next" | "person";
|
|
731
|
+
interface EscalationRequest {
|
|
732
|
+
to: EscalationTarget;
|
|
733
|
+
reason: string;
|
|
734
|
+
}
|
|
735
|
+
|
|
736
|
+
/**
|
|
737
|
+
* The support ladder: automation first, then model tiers, then a person.
|
|
738
|
+
*
|
|
739
|
+
* 1. `automation` answers what the host recognises (a greeting on the first
|
|
740
|
+
* contact, an option the customer picked) with no model call.
|
|
741
|
+
* 2. Anything else goes to the first model tier. Each tier answers, which
|
|
742
|
+
* means "I handle it", or calls the ladder's `escalate` tool: to the next
|
|
743
|
+
* tier, which runs on the same message in the same call, or to a person.
|
|
744
|
+
* A refusal, or a turn with no words, escalates too.
|
|
745
|
+
* 3. A person: the host's `handOff` is called once, and from then on the
|
|
746
|
+
* ladder never calls a model for that conversation.
|
|
747
|
+
*
|
|
748
|
+
* A conversation STAYS at the level it reached (the host's `state` port, only
|
|
749
|
+
* ever raised, atomically: see ./state.ts) until the host resets it;
|
|
750
|
+
* automation is consulted only before a conversation reached any tier. The
|
|
751
|
+
* ladder carries no domain: tiers, tools, copy and the person are all the
|
|
752
|
+
* host's.
|
|
753
|
+
*/
|
|
754
|
+
|
|
755
|
+
type Awaitable<T> = T | Promise<T>;
|
|
756
|
+
interface SupportAutomation<Context = unknown> {
|
|
757
|
+
/** The first contact's message (the transcript is empty), e.g. the options on offer. */
|
|
758
|
+
greeting?(context: Context): Awaitable<string | null | undefined>;
|
|
759
|
+
/** An option the host recognises, answered with no model call. */
|
|
760
|
+
match?(message: string, context: Context): Awaitable<{
|
|
761
|
+
reply: string;
|
|
762
|
+
} | null | undefined>;
|
|
763
|
+
}
|
|
764
|
+
interface SupportTier<Scope = unknown, Context = unknown> {
|
|
765
|
+
/** Unique; the level the state port stores. Not `"person"`. */
|
|
766
|
+
id: string;
|
|
767
|
+
/** A client, or what `createModelClient` takes, so providers stay interchangeable. */
|
|
768
|
+
client: ModelClient | ModelClientOptions;
|
|
769
|
+
instructions: string | readonly SystemBlock[];
|
|
770
|
+
/** EXACTLY this tier's tools; nothing is shared with another tier. */
|
|
771
|
+
tools?: readonly SupportToolEntry<Scope, Context>[];
|
|
772
|
+
/** Default 1024. */
|
|
773
|
+
maxOutputTokens?: number;
|
|
774
|
+
/** Default 8 (the tool loop's). */
|
|
775
|
+
maxTurns?: number;
|
|
776
|
+
effort?: Effort;
|
|
777
|
+
}
|
|
778
|
+
interface SupportHandOff<Scope = unknown, Context = unknown> {
|
|
779
|
+
conversationId: string;
|
|
780
|
+
/** The transcript plus the message that was escalated. */
|
|
781
|
+
conversation: Message[];
|
|
782
|
+
reason: string;
|
|
783
|
+
fromTier: string;
|
|
784
|
+
scope: Scope;
|
|
785
|
+
context: Context;
|
|
786
|
+
}
|
|
787
|
+
interface SupportPerson<Scope = unknown, Context = unknown> {
|
|
788
|
+
/** Called once per conversation, by the call whose raise to "person" won, after that raise. */
|
|
789
|
+
handOff(handOff: SupportHandOff<Scope, Context>): Awaitable<void>;
|
|
790
|
+
}
|
|
791
|
+
interface SupportLadderOptions<Scope = unknown, Context = unknown> {
|
|
792
|
+
automation?: SupportAutomation<Context>;
|
|
793
|
+
/** In escalation order, at least one. */
|
|
794
|
+
tiers: readonly SupportTier<Scope, Context>[];
|
|
795
|
+
person: SupportPerson<Scope, Context>;
|
|
796
|
+
/** Read and atomically RAISED, never lowered (see `SupportStatePort.raise`). */
|
|
797
|
+
state: SupportStatePort;
|
|
798
|
+
/** Argument names the host binds to the scope; the model may never set one. */
|
|
799
|
+
scopeFields?: readonly string[];
|
|
800
|
+
/** Live metering: every model turn's usage, with its tier. */
|
|
801
|
+
onUsage?: (tier: string, usage: Usage, turn: number) => Awaitable<void>;
|
|
802
|
+
}
|
|
803
|
+
interface SupportRequest<Scope = unknown, Context = unknown> {
|
|
804
|
+
conversationId: string;
|
|
805
|
+
message: string;
|
|
806
|
+
/** The conversation before `message`. */
|
|
807
|
+
transcript: readonly Message[];
|
|
808
|
+
context: Context;
|
|
809
|
+
/** Opaque to the ladder; handed to every tool, never to or from the model. */
|
|
810
|
+
scope: Scope;
|
|
811
|
+
}
|
|
812
|
+
interface TierUsage {
|
|
813
|
+
tier: string;
|
|
814
|
+
turns: number;
|
|
815
|
+
usage: Omit<Usage, "raw">;
|
|
816
|
+
}
|
|
817
|
+
interface Escalation {
|
|
818
|
+
from: string;
|
|
819
|
+
to: string;
|
|
820
|
+
reason: string;
|
|
821
|
+
}
|
|
822
|
+
type SupportResult = {
|
|
823
|
+
kind: "automation";
|
|
824
|
+
source: "greeting" | "match";
|
|
825
|
+
reply: string;
|
|
826
|
+
usage: TierUsage[];
|
|
827
|
+
escalations: Escalation[];
|
|
828
|
+
} | {
|
|
829
|
+
kind: "model";
|
|
830
|
+
tier: string;
|
|
831
|
+
reply: string;
|
|
832
|
+
messages: Message[];
|
|
833
|
+
usage: TierUsage[];
|
|
834
|
+
escalations: Escalation[];
|
|
835
|
+
} | {
|
|
836
|
+
kind: "person";
|
|
837
|
+
/** Null when another call (or an earlier message) handed the conversation off. */
|
|
838
|
+
fromTier: string | null;
|
|
839
|
+
reason: string | null;
|
|
840
|
+
/** True when THIS call handed the conversation off. */
|
|
841
|
+
handedOff: boolean;
|
|
842
|
+
usage: TierUsage[];
|
|
843
|
+
escalations: Escalation[];
|
|
844
|
+
};
|
|
845
|
+
interface SupportLadder<Scope = unknown, Context = unknown> {
|
|
846
|
+
handle(request: SupportRequest<Scope, Context>): Promise<SupportResult>;
|
|
847
|
+
}
|
|
848
|
+
declare function createSupportLadder<Scope = unknown, Context = unknown>(options: SupportLadderOptions<Scope, Context>): SupportLadder<Scope, Context>;
|
|
849
|
+
|
|
850
|
+
interface McpToolInfo {
|
|
851
|
+
name: string;
|
|
852
|
+
description?: string;
|
|
853
|
+
inputSchema: JsonSchema;
|
|
854
|
+
}
|
|
855
|
+
interface McpListToolsResult {
|
|
856
|
+
tools: McpToolInfo[];
|
|
857
|
+
nextCursor?: string;
|
|
858
|
+
}
|
|
859
|
+
/** The two calls this source makes; the official SDK's `Client` has both. */
|
|
860
|
+
interface McpClientLike {
|
|
861
|
+
listTools(params?: {
|
|
862
|
+
cursor?: string;
|
|
863
|
+
}): Promise<McpListToolsResult>;
|
|
864
|
+
callTool(params: {
|
|
865
|
+
name: string;
|
|
866
|
+
arguments?: Record<string, unknown>;
|
|
867
|
+
}): Promise<unknown>;
|
|
868
|
+
}
|
|
869
|
+
interface McpToolsOptions<Scope> {
|
|
870
|
+
/**
|
|
871
|
+
* A client for this scope. Put the scope's credentials or headers on its
|
|
872
|
+
* transport here; cache connections per scope if they are costly.
|
|
873
|
+
*/
|
|
874
|
+
connect(scope: Scope): McpClientLike | Promise<McpClientLike>;
|
|
875
|
+
/** The ONLY tools offered, by name. Every one must exist on the server. */
|
|
876
|
+
allow: readonly string[];
|
|
877
|
+
/**
|
|
878
|
+
* Replace an allowed tool's description or input schema, for a server
|
|
879
|
+
* whose schema is not strict (every tool schema must be; see `assertStrictTools`).
|
|
880
|
+
*/
|
|
881
|
+
overrides?: Readonly<Record<string, Partial<Pick<ToolDefinition, "description" | "inputSchema">>>>;
|
|
882
|
+
/**
|
|
883
|
+
* Arguments the HOST supplies, for a server whose tools take the tenant (or
|
|
884
|
+
* any scope field) as an argument. They are merged AFTER the model's input,
|
|
885
|
+
* so the host's value always wins; their names are removed from the schema
|
|
886
|
+
* the model sees, and a model call that sets one is refused without
|
|
887
|
+
* reaching the server.
|
|
888
|
+
*/
|
|
889
|
+
bindArgs?(scope: Scope, toolName: string): Readonly<Record<string, unknown>>;
|
|
890
|
+
}
|
|
891
|
+
/** An MCP `CallToolResult` as tool output: its text parts, else its structured content. */
|
|
892
|
+
declare function mcpResultToOutput(result: unknown): ToolOutput;
|
|
893
|
+
declare function mcpTools<Scope = unknown, Context = unknown>(options: McpToolsOptions<Scope>): SupportToolSource<Scope, Context>;
|
|
894
|
+
|
|
568
895
|
/**
|
|
569
896
|
* The strict-schema rule every tool input schema meets, whatever the provider.
|
|
570
897
|
*
|
|
@@ -583,4 +910,4 @@ declare function toolSchemaProblems(tools: readonly ToolDefinition[]): string[];
|
|
|
583
910
|
/** Throws a TypeError naming every problem in every tool's input schema. */
|
|
584
911
|
declare function assertStrictTools(tools: readonly ToolDefinition[]): void;
|
|
585
912
|
|
|
586
|
-
export { ANTHROPIC_DEFAULT_MODEL, ANTHROPIC_PROVIDER, type AdapterRegistry, type AnthropicAdapterOptions, type AnthropicClientLike, type ApiKeyCredentials, type AssistantMessage, AuthError, type CacheTtl, type Capability, type ChatCall, type ChatRequest, type ChatResult, type CredentialKind, CredentialRevokedError, type CredentialSession, type CredentialSessionOptions, type Credentials, type Effort, GEMINI_PROVIDER, type GeminiAdapterOptions, type GeminiClientLike, InvalidRequestError, InvalidResponseError, type JsonSchema, LlmError, type LlmErrorKind, type Message, type ModelClient, type ModelClientOptions, type OAuthCredentials, type OAuthToken, OPENAI_PROVIDER, type OpenAIAdapterOptions, type OpenAIClientLike, type ProviderAdapter, ProviderUnavailableError, RateLimitError, type RefreshReason, type Refusal, RefusalError, type RegisterOptions, ResolvedCredential, type RetryPolicy, type StopReason, type SystemBlock, type ToolCall, type ToolChoice, type ToolDefinition, type ToolExecutor, type ToolLoopOptions, type ToolLoopResult, type ToolLoopStatus, type ToolOutput, type ToolResult, type ToolResultsMessage, UnsupportedError, type Usage, type UserMessage, XAI_PROVIDER, type XaiAdapterOptions, anthropicAdapter, assertStrictTools, builtInAdapters, createAdapterRegistry, createCredentialSession, createModelClient, ensureNotRefused, geminiAdapter, mapProviderError, openaiAdapter, retryAfterFrom, retryTransient, runToolLoop, strictSchemaProblems, toolSchemaProblems, xaiAdapter };
|
|
913
|
+
export { ANTHROPIC_DEFAULT_MODEL, ANTHROPIC_PROVIDER, type AdapterRegistry, type AnthropicAdapterOptions, type AnthropicClientLike, type ApiKeyCredentials, type AssistantMessage, AudioTooLongError, AuthError, type CacheTtl, type Capability, type ChatCall, type ChatRequest, type ChatResult, type CredentialKind, CredentialRevokedError, type CredentialSession, type CredentialSessionOptions, type Credentials, ELEVENLABS_DEFAULT_MODEL, ELEVENLABS_PROVIDER, ESCALATE_TOOL, type Effort, type ElevenLabsAdapterOptions, type Escalation, type EscalationRequest, type EscalationTarget, GEMINI_PROVIDER, type GeminiAdapterOptions, type GeminiClientLike, InvalidRequestError, InvalidResponseError, type JsonSchema, LlmError, type LlmErrorKind, type McpClientLike, type McpListToolsResult, type McpToolInfo, type McpToolsOptions, type Message, type ModelClient, type ModelClientOptions, type OAuthCredentials, type OAuthToken, OPENAI_PROVIDER, type OpenAIAdapterOptions, type OpenAIClientLike, type ProviderAdapter, ProviderUnavailableError, RateLimitError, type RefreshReason, type Refusal, RefusalError, type RegisterOptions, ResolvedCredential, type RetryPolicy, type StopReason, type SupportAutomation, type SupportHandOff, type SupportLadder, SupportLadderError, type SupportLadderErrorCode, type SupportLadderOptions, type SupportPerson, type SupportRequest, type SupportResult, type SupportStatePort, type SupportTier, type SupportTool, type SupportToolContext, type SupportToolEntry, type SupportToolSource, type SystemBlock, type TierUsage, type ToolCall, type ToolChoice, type ToolDefinition, type ToolExecutor, type ToolLoopOptions, type ToolLoopResult, type ToolLoopStatus, type ToolOutput, type ToolResult, type ToolResultsMessage, type TranscribeCall, type Transcriber, type TranscriberOptions, type TranscriptionAdapter, type TranscriptionRegistry, type TranscriptionRequest, type TranscriptionResult, type TranscriptionUsage, UnsupportedError, type Usage, type UserMessage, WITH_PERSON, XAI_PROVIDER, type XaiAdapterOptions, anthropicAdapter, assertStrictTools, builtInAdapters, builtInTranscriptionAdapters, createAdapterRegistry, createCredentialSession, createModelClient, createSupportLadder, createTranscriber, createTranscriptionRegistry, elevenLabsAdapter, ensureNotRefused, geminiAdapter, mapProviderError, mcpResultToOutput, mcpTools, openaiAdapter, retryAfterFrom, retryTransient, runToolLoop, strictSchemaProblems, toolSchemaProblems, xaiAdapter };
|