@rebyteai/agent-sdk 0.2.0

package/src/lib/jsonschema.ts

@@ -0,0 +1,215 @@
+// File mostly copied from @types/json-schema, but stripped down a bit for brevity
+// https://github.com/DefinitelyTyped/DefinitelyTyped/blob/817274f3280152ba2929a6067c93df8b34c4c9aa/types/json-schema/index.d.ts
+//
+// ==================================================================================================
+// JSON Schema Draft 07
+// ==================================================================================================
+// https://tools.ietf.org/html/draft-handrews-json-schema-validation-01
+// --------------------------------------------------------------------------------------------------
+
+/**
+ * A JSON value category accepted by a schema's `type` keyword.
+ * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.1.1
+ */
+export type JSONSchemaTypeName =
+  // oxlint-disable-next-line typescript/ban-types -- The empty intersection preserves literal-union widening for arbitrary JSON Schema type names.
+  ({} & string) | 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
+
+/**
+ * Any JSON-serializable primitive, object, array, or `null` value.
+ * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.1.1
+ */
+export type JSONSchemaType =
+  | string //
+  | number
+  | boolean
+  | JSONSchemaObject
+  | JSONSchemaArray
+  | null;
+
+/** A JSON object whose property values may themselves be nested JSON values. */
+export interface JSONSchemaObject {
+  /** A JSON-serializable property value addressed by its object key. */
+  [key: string]: JSONSchemaType;
+}
+
+/** An array of JSON-serializable values, including nested arrays and objects. */
+export interface JSONSchemaArray extends Array<JSONSchemaType> {
+  /** The JSON-serializable value at a numeric array position. */
+  [index: number]: JSONSchemaType;
+}
+
+/**
+ * Meta schema
+ *
+ * Recommended values:
+ * - 'http://json-schema.org/schema#'
+ * - 'http://json-schema.org/hyper-schema#'
+ * - 'http://json-schema.org/draft-07/schema#'
+ * - 'http://json-schema.org/draft-07/hyper-schema#'
+ *
+ * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-5
+ */
+export type JSONSchemaVersion = string;
+
+/**
+ * JSON Schema v7
+ * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01
+ */
+export type JSONSchemaDefinition = JSONSchema | boolean;
+/** A JSON Schema document or subschema accepted by SDK function and structured-output helpers. */
+export interface JSONSchema {
+  /** URI identifying the JSON Schema dialect used by this document. */
+  $schema?: JSONSchemaVersion | undefined;
+  /** URI identifying this schema resource and establishing its reference base. */
+  $id?: string | undefined;
+  /** Implementation-facing comment that does not affect instance validation. */
+  $comment?: string | undefined;
+
+  /**
+   * JSON value category, or categories, accepted by this schema.
+   *
+   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.1
+   */
+  type?: JSONSchemaTypeName | JSONSchemaTypeName[] | undefined;
+  /** The complete set of literal values accepted by this schema. */
+  enum?: JSONSchemaType[] | undefined;
+  /** The single literal value accepted by this schema. */
+  const?: JSONSchemaType | undefined;
+
+  /**
+   * Requires a numeric instance to be an exact multiple of this value.
+   *
+   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.2
+   */
+  multipleOf?: number | undefined;
+  /** The greatest numeric value accepted, including the boundary. */
+  maximum?: number | undefined;
+  /** The upper numeric boundary, which the instance must be strictly less than. */
+  exclusiveMaximum?: number | undefined;
+  /** The smallest numeric value accepted, including the boundary. */
+  minimum?: number | undefined;
+  /** The lower numeric boundary, which the instance must be strictly greater than. */
+  exclusiveMinimum?: number | undefined;
+
+  /**
+   * The maximum number of Unicode characters accepted in a string.
+   *
+   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.3
+   */
+  maxLength?: number | undefined;
+  /** The minimum number of Unicode characters required in a string. */
+  minLength?: number | undefined;
+  /** A regular expression that matching string instances must satisfy. */
+  pattern?: string | undefined;
+  /** Encoding used by a string that represents non-text content, such as `base64`. */
+  contentEncoding?: string | undefined;
+  /** Media type describing content represented by a string instance. */
+  contentMediaType?: string | undefined;
+
+  /**
+   * A schema shared by array items, or position-specific schemas for tuple items.
+   *
+   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.4
+   */
+  items?: JSONSchemaDefinition | JSONSchemaDefinition[] | undefined;
+  /** Schema applied to array items beyond the explicitly defined tuple positions. */
+  additionalItems?: JSONSchemaDefinition | undefined;
+  /** The maximum number of items accepted in an array. */
+  maxItems?: number | undefined;
+  /** The minimum number of items required in an array. */
+  minItems?: number | undefined;
+  /** Whether every array item must be distinct from every other item. */
+  uniqueItems?: boolean | undefined;
+  /** A schema that at least one array item must satisfy. */
+  contains?: JSONSchemaDefinition | undefined;
+
+  /**
+   * The maximum number of properties accepted in an object.
+   *
+   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.5
+   */
+  maxProperties?: number | undefined;
+  /** The minimum number of properties required in an object. */
+  minProperties?: number | undefined;
+  /** Property names that must be present in a valid object. */
+  required?: string[] | undefined;
+  /** Schemas associated with explicitly named object properties. */
+  properties?: Record<string, JSONSchemaDefinition> | undefined;
+  /** Schemas applied to properties whose names match each regular-expression key. */
+  patternProperties?: Record<string, JSONSchemaDefinition> | undefined;
+  /** Schema for properties not covered by `properties` or `patternProperties`. */
+  additionalProperties?: JSONSchemaDefinition | undefined;
+  /** Schema that every property name in an object must satisfy. */
+  propertyNames?: JSONSchemaDefinition | undefined;
+
+  /**
+   * Condition that selects the `then` or `else` validation schema.
+   *
+   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.6
+   */
+  if?: JSONSchemaDefinition | undefined;
+  /** Schema applied when the instance satisfies the `if` condition. */
+  then?: JSONSchemaDefinition | undefined;
+  /** Schema applied when the instance does not satisfy the `if` condition. */
+  else?: JSONSchemaDefinition | undefined;
+
+  /**
+   * Subschemas that the instance must all satisfy.
+   *
+   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-6.7
+   */
+  allOf?: JSONSchemaDefinition[] | undefined;
+  /** Alternative subschemas, at least one of which the instance must satisfy. */
+  anyOf?: JSONSchemaDefinition[] | undefined;
+  /** Alternative subschemas, exactly one of which the instance must satisfy. */
+  oneOf?: JSONSchemaDefinition[] | undefined;
+  /** A subschema that the instance must not satisfy. */
+  not?: JSONSchemaDefinition | undefined;
+
+  /**
+   * Reusable subschemas that can be targeted by local `$ref` pointers.
+   *
+   * @see https://json-schema.org/draft/2020-12/json-schema-core.html#section-8.2.4
+   */
+  $defs?: Record<string, JSONSchemaDefinition> | undefined;
+
+  /**
+   * Legacy reusable subschemas that can be targeted by local `$ref` pointers.
+   *
+   * @deprecated Use $defs instead (draft 2019-09+)
+   * @see https://tools.ietf.org/doc/html/draft-handrews-json-schema-validation-01#page-22
+   */
+  definitions?: Record<string, JSONSchemaDefinition> | undefined;
+
+  /**
+   * URI reference identifying another schema to apply at this position.
+   *
+   * @see https://json-schema.org/draft/2020-12/json-schema-core#ref
+   */
+  $ref?: string | undefined;
+
+  /**
+   * Semantic format annotation, such as `date-time`, `email`, or `uri`.
+   *
+   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-7
+   */
+  format?: string | undefined;
+
+  /**
+   * A short, human-readable title describing the schema.
+   *
+   * @see https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-10
+   */
+  title?: string | undefined;
+  /** Human-readable explanation of the value accepted by the schema. */
+  description?: string | undefined;
+  /** Suggested value to use when an instance value is not provided. */
+  default?: JSONSchemaType | undefined;
+  /** Whether this value should be treated as read-only by consumers. */
+  readOnly?: boolean | undefined;
+  /** Whether this value should be treated as write-only by consumers. */
+  writeOnly?: boolean | undefined;
+  /** Representative example value or values illustrating this schema. */
+  examples?: JSONSchemaType | undefined;
+}

package/src/lib/live/transcript-grouper.ts

@@ -0,0 +1,303 @@
+import { EventEmitter } from '../../core/EventEmitter';
+import { OpenAIError } from '../../core/error';
+import type { ServerEvent } from '../../resources/live/live';
+import { TranscriptGrouping } from './transcript-grouping';
+import type { GroupingUpdate, TranscriptFragment } from './transcript-grouping';
+
+/** Options for the speaker-based transcript grouping policy. */
+export interface TranscriptGrouperOptions {
+  /** Minimum source-time gap before promoting buffered assistant text. Default: 500 ms. */
+  minTurnSeparationMs?: number;
+  /** Assistant transcript inactivity before closing a segment. Default: 2000 ms; not an audio/VAD signal. */
+  assistantSilenceMs?: number;
+  /** Acknowledgments shorter than this may be suppressed as backchannels. Default: 1000 ms; zero disables suppression. */
+  backchannelMaxDurationMs?: number;
+  /** Isolation window used to distinguish backchannels from assistant replies. Default: 2000 ms. */
+  backchannelIsolationMs?: number;
+  /** Extra phrases eligible for backchannel suppression, in addition to the built-in acknowledgments.
+   * Normalized like transcript text (case, hyphens, whitespace, and surrounding punctuation).
+   * Copied when the grouper is created; the same timing thresholds apply.
+   */
+  additionalAcknowledgments?: readonly string[];
+}
+
+/** An immutable SDK projection of spoken text, not a server conversation item. */
+export interface TranscriptSegment {
+  /** Stable ID local to this SDK projection; not a server turn or item ID. */
+  readonly id: string;
+  /** ID of the preceding emitted segment, or null for the first segment. */
+  readonly previousId: string | null;
+  /** Speaker whose transcript text was grouped. */
+  readonly speaker: 'user' | 'assistant';
+  /** Complete append-only text; replace the displayed text on each update. */
+  readonly text: string;
+  /** Start of the first contributing public transcript interval, in session milliseconds. */
+  readonly startMs: number;
+  /** Latest end of the contributing public transcript intervals; never a playback completion time. */
+  readonly endMs: number;
+}
+
+/** Why a display segment was finalized; none of these proves audible speech completed. */
+export type TranscriptSegmentCloseReason =
+  | 'speaker_change'
+  | 'inactivity'
+  | 'timestamp_reset'
+  | 'session_closed'
+  | 'manual';
+
+/** A final segment snapshot and the reason it will receive no further updates. */
+export interface TranscriptSegmentClosedEvent {
+  /** The final immutable segment, including all previously emitted text. */
+  readonly segment: TranscriptSegment;
+  /** The local grouping decision that finalized the segment. */
+  readonly reason: TranscriptSegmentCloseReason;
+}
+
+/** Events emitted by a TranscriptGrouper. */
+// oxlint-disable-next-line typescript/consistent-type-definitions -- A closed event-map type satisfies the SDK emitter's Record constraint without permitting arbitrary event names.
+export type TranscriptGrouperEvents = {
+  /** First and subsequent complete snapshots of an emitted segment. */
+  'segment.updated': (segment: TranscriptSegment) => void;
+  /** Exactly one final snapshot per emitted segment; closed segments are never reopened. */
+  'segment.closed': (event: TranscriptSegmentClosedEvent) => void;
+};
+
+type ReceivedFragment = TranscriptFragment & { receivedAt: number };
+const SETTLE_MS = 50;
+const MAX_TIMEOUT_MS = 2_147_483_647;
+let nextGrouperId = 0;
+
+function normalizeTranscript(
+  event: Extract<ServerEvent, { type: 'session.input_transcript.delta' | 'session.output_transcript.delta' }>,
+): ReceivedFragment & { id: string } {
+  const { event_id: id, delta: text, start_ms: startMs, end_ms: endMs } = event;
+  const speaker = event.type === 'session.input_transcript.delta' ? 'user' : 'assistant';
+  if (
+    typeof id !== 'string' ||
+    !id ||
+    typeof text !== 'string' ||
+    !Number.isSafeInteger(startMs) ||
+    startMs < 0 ||
+    !Number.isSafeInteger(endMs) ||
+    endMs < startMs
+  ) {
+    throw new OpenAIError(
+      'Invalid Live transcript delta: expected an event ID, text, and a nonnegative timed interval',
+    );
+  }
+  return { id, speaker, text, startMs, endMs, receivedAt: performance.now() };
+}
+
+function optionsWithDefaults(options: TranscriptGrouperOptions): Required<TranscriptGrouperOptions> {
+  const resolved = {
+    minTurnSeparationMs: options.minTurnSeparationMs ?? 500,
+    assistantSilenceMs: options.assistantSilenceMs ?? 2000,
+    backchannelMaxDurationMs: options.backchannelMaxDurationMs ?? 1000,
+    backchannelIsolationMs: options.backchannelIsolationMs ?? 2000,
+  };
+  for (const [name, value] of Object.entries(resolved)) {
+    if (!Number.isFinite(value) || value < 0 || value > MAX_TIMEOUT_MS) {
+      throw new OpenAIError(`${name} must be a finite number between 0 and ${MAX_TIMEOUT_MS}`);
+    }
+  }
+  return { ...resolved, additionalAcknowledgments: options.additionalAcknowledgments ?? [] };
+}
+
+/**
+ * Groups public Live transcript events using speaker and
+ * backchannel heuristics. Raw events remain available on your transport.
+ *
+ * Only session.input_transcript.delta, session.output_transcript.delta and session.closed are
+ * consumed. No audio, engine frames, server turn events or internal end markers
+ * are required. Ambiguous speaker changes settle for at most 50 ms. When source
+ * time stops arriving, a monotonic local clock supplies a best-effort inactivity
+ * fallback. Delayed delivery can therefore change grouping; this is not VAD,
+ * playback tracking, or a lossless transcript (some backchannels are suppressed).
+ *
+ * Create one instance per session. Call close() on transport loss or teardown;
+ * the grouper never owns or closes your transport and does not reconnect it.
+ */
+// oxlint-disable-next-line unicorn/prefer-event-target -- This is the SDK's browser-compatible typed emitter, not node:events.
+export class TranscriptGrouper extends EventEmitter<TranscriptGrouperEvents> {
+  private readonly grouping: TranscriptGrouping;
+  private readonly seenIds = new Set<string>();
+  private pending: ReceivedFragment[] = [];
+  private timer: ReturnType<typeof setTimeout> | undefined;
+  private anchor: { sourceMs: number; receivedAt: number } | undefined;
+  private lastStartMs: number | undefined;
+  private closed = false;
+  private dispatching = false;
+  private readonly updates: GroupingUpdate[] = [];
+
+  /** Create a grouper with speaker-based defaults. Invalid timing options throw OpenAIError. */
+  constructor(options: TranscriptGrouperOptions = {}) {
+    super();
+    this.grouping = new TranscriptGrouping(optionsWithDefaults(options), `segment_${nextGrouperId}`);
+    nextGrouperId += 1;
+  }
+
+  /**
+   * Consume one public Live event. Duplicate transcript event IDs and unrelated
+   * event types are ignored. Empty text does not count as speech activity.
+   * Malformed transcript fields or use after close() throw OpenAIError.
+   */
+  push(event: ServerEvent): void {
+    if (this.closed) {
+      throw new OpenAIError('Cannot push events after closing the transcript grouper');
+    }
+    if (event.type === 'session.closed') {
+      this.finish('session_closed');
+      return;
+    }
+    if (event.type !== 'session.input_transcript.delta' && event.type !== 'session.output_transcript.delta') {
+      return;
+    }
+    const fragment = normalizeTranscript(event);
+    const { id, startMs, endMs, speaker } = fragment;
+    if (this.seenIds.has(id)) {
+      return;
+    }
+    this.seenIds.add(id);
+    if (!fragment.text) {
+      return;
+    }
+    const updates: GroupingUpdate[] = [];
+    const [pending] = this.pending;
+    if (pending && pending.startMs === startMs && pending.endMs === endMs) {
+      this.pending.push(fragment);
+      if (this.pending.some((part) => part.speaker !== speaker)) {
+        updates.push(...this.flushPending());
+      }
+    } else {
+      updates.push(...this.flushPending());
+      if (this.grouping.speaker === speaker) {
+        updates.push(...this.commit([fragment]));
+      } else {
+        this.pending.push(fragment);
+      }
+    }
+    this.schedule();
+    this.dispatch(updates);
+  }
+
+  /**
+   * Flush buffered text according to the grouping policy, finalize all emitted
+   * segments, and cancel timers. Idempotent; further push() calls fail. Does not
+   * close the transport. Invoke before discarding the grouper at session teardown.
+   */
+  close(): void {
+    this.finish('manual');
+  }
+
+  private finish(reason: 'manual' | 'session_closed'): void {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    this.clearTimer();
+    const updates = this.flushPending();
+    updates.push(...this.grouping.close(this.sourceNow(), reason));
+    this.seenIds.clear();
+    this.dispatch(updates);
+  }
+
+  private commit(fragments: readonly ReceivedFragment[]): GroupingUpdate[] {
+    const [first] = fragments;
+    if (!first) {
+      return [];
+    }
+    const updates: GroupingUpdate[] = [];
+    if (this.lastStartMs !== undefined && first.startMs < this.lastStartMs) {
+      updates.push(...this.grouping.close(this.sourceNow(), 'timestamp_reset'));
+      this.anchor = undefined;
+    }
+    this.lastStartMs = first.startMs;
+    // Overlapping intervals can end before earlier ones. Preserve the source
+    // high-water mark while restarting local inactivity on newly received text.
+    this.anchor = {
+      sourceMs: Math.max(this.anchor?.sourceMs ?? 0, first.endMs),
+      receivedAt: first.receivedAt,
+    };
+    for (const part of fragments) {
+      this.anchor.sourceMs = Math.max(this.anchor.sourceMs, part.endMs);
+      this.anchor.receivedAt = Math.max(this.anchor.receivedAt, part.receivedAt);
+    }
+    updates.push(...this.grouping.process(fragments));
+    return updates;
+  }
+
+  private flushPending(): GroupingUpdate[] {
+    const { pending } = this;
+    this.pending = [];
+    return this.commit(pending);
+  }
+
+  private sourceNow(): number {
+    return this.anchor ? this.anchor.sourceMs + Math.max(0, performance.now() - this.anchor.receivedAt) : 0;
+  }
+
+  private clearTimer(): void {
+    if (this.timer !== undefined) {
+      clearTimeout(this.timer);
+    }
+    this.timer = undefined;
+  }
+
+  private schedule(): void {
+    this.clearTimer();
+    if (this.closed) {
+      return;
+    }
+    const [pending] = this.pending;
+    const deadline = this.grouping.deadline();
+    // Settle newly arrived text before applying an older inactivity deadline.
+    let delay: number | undefined;
+    if (pending) {
+      delay = pending.receivedAt + SETTLE_MS - performance.now();
+    } else if (deadline !== undefined) {
+      delay = deadline - this.sourceNow();
+    }
+    if (delay === undefined) {
+      return;
+    }
+    this.timer = setTimeout(
+      () => {
+        this.timer = undefined;
+        const updates = this.flushPending();
+        updates.push(...this.grouping.advance(this.sourceNow()));
+        this.schedule();
+        this.dispatch(updates);
+      },
+      Math.min(MAX_TIMEOUT_MS, Math.max(0, Math.ceil(delay))),
+    );
+    const timer: unknown = this.timer;
+    if (
+      typeof timer === 'object' &&
+      timer !== null &&
+      'unref' in timer &&
+      typeof timer.unref === 'function'
+    ) {
+      timer.unref();
+    }
+  }
+
+  private dispatch(updates: GroupingUpdate[]): void {
+    this.updates.push(...updates);
+    if (this.dispatching) {
+      return;
+    }
+    this.dispatching = true;
+    try {
+      while (this.updates.length) {
+        const update = this.updates.shift();
+        if (update?.type === 'updated') {
+          this._emit('segment.updated', update.segment);
+        } else if (update) {
+          this._emit('segment.closed', { segment: update.segment, reason: update.reason });
+        }
+      }
+    } finally {
+      this.dispatching = false;
+    }
+  }
+}