@contractspec/integration.providers-impls 2.9.0 → 3.0.0

package/dist/impls/mistral-conversational.js

@@ -0,0 +1,476 @@
+// @bun
+// src/impls/async-event-queue.ts
+class AsyncEventQueue {
+  values = [];
+  waiters = [];
+  done = false;
+  push(value) {
+    if (this.done) {
+      return;
+    }
+    const waiter = this.waiters.shift();
+    if (waiter) {
+      waiter({ value, done: false });
+      return;
+    }
+    this.values.push(value);
+  }
+  close() {
+    if (this.done) {
+      return;
+    }
+    this.done = true;
+    for (const waiter of this.waiters) {
+      waiter({ value: undefined, done: true });
+    }
+    this.waiters.length = 0;
+  }
+  [Symbol.asyncIterator]() {
+    return {
+      next: async () => {
+        const value = this.values.shift();
+        if (value != null) {
+          return { value, done: false };
+        }
+        if (this.done) {
+          return { value: undefined, done: true };
+        }
+        return new Promise((resolve) => {
+          this.waiters.push(resolve);
+        });
+      }
+    };
+  }
+}
+
+// src/impls/mistral-stt.ts
+var DEFAULT_BASE_URL = "https://api.mistral.ai/v1";
+var DEFAULT_MODEL = "voxtral-mini-latest";
+var AUDIO_MIME_BY_FORMAT = {
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+  ogg: "audio/ogg",
+  pcm: "audio/pcm",
+  opus: "audio/opus"
+};
+
+class MistralSttProvider {
+  apiKey;
+  defaultModel;
+  defaultLanguage;
+  baseUrl;
+  fetchImpl;
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new Error("MistralSttProvider requires an apiKey");
+    }
+    this.apiKey = options.apiKey;
+    this.defaultModel = options.defaultModel ?? DEFAULT_MODEL;
+    this.defaultLanguage = options.defaultLanguage;
+    this.baseUrl = normalizeBaseUrl(options.serverURL ?? DEFAULT_BASE_URL);
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+  async transcribe(input) {
+    const formData = new FormData;
+    const model = input.model ?? this.defaultModel;
+    const mimeType = AUDIO_MIME_BY_FORMAT[input.audio.format] ?? "audio/wav";
+    const fileName = `audio.${input.audio.format}`;
+    const audioBytes = new Uint8Array(input.audio.data);
+    const blob = new Blob([audioBytes], { type: mimeType });
+    formData.append("file", blob, fileName);
+    formData.append("model", model);
+    formData.append("response_format", "verbose_json");
+    const language = input.language ?? this.defaultLanguage;
+    if (language) {
+      formData.append("language", language);
+    }
+    const response = await this.fetchImpl(`${this.baseUrl}/audio/transcriptions`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`
+      },
+      body: formData
+    });
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(`Mistral transcription request failed (${response.status}): ${body}`);
+    }
+    const payload = await response.json();
+    return toTranscriptionResult(payload, input);
+  }
+}
+function toTranscriptionResult(payload, input) {
+  const record = asRecord(payload);
+  const text = readString(record, "text") ?? "";
+  const language = readString(record, "language") ?? input.language ?? "unknown";
+  const segments = parseSegments(record);
+  if (segments.length === 0 && text.length > 0) {
+    segments.push({
+      text,
+      startMs: 0,
+      endMs: input.audio.durationMs ?? 0
+    });
+  }
+  const durationMs = input.audio.durationMs ?? segments.reduce((max, segment) => Math.max(max, segment.endMs), 0);
+  const topLevelWords = parseWordTimings(record.words);
+  const flattenedWords = segments.flatMap((segment) => segment.wordTimings ?? []);
+  const wordTimings = topLevelWords.length > 0 ? topLevelWords : flattenedWords.length > 0 ? flattenedWords : undefined;
+  const speakers = dedupeSpeakers(segments);
+  return {
+    text,
+    segments,
+    language,
+    durationMs,
+    speakers: speakers.length > 0 ? speakers : undefined,
+    wordTimings
+  };
+}
+function parseSegments(record) {
+  if (!Array.isArray(record.segments)) {
+    return [];
+  }
+  const parsed = [];
+  for (const entry of record.segments) {
+    const segmentRecord = asRecord(entry);
+    const text = readString(segmentRecord, "text");
+    if (!text) {
+      continue;
+    }
+    const startSeconds = readNumber(segmentRecord, "start") ?? 0;
+    const endSeconds = readNumber(segmentRecord, "end") ?? startSeconds;
+    parsed.push({
+      text,
+      startMs: secondsToMs(startSeconds),
+      endMs: secondsToMs(endSeconds),
+      speakerId: readString(segmentRecord, "speaker") ?? undefined,
+      confidence: readNumber(segmentRecord, "confidence"),
+      wordTimings: parseWordTimings(segmentRecord.words)
+    });
+  }
+  return parsed;
+}
+function parseWordTimings(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  const words = [];
+  for (const entry of value) {
+    const wordRecord = asRecord(entry);
+    const word = readString(wordRecord, "word");
+    const startSeconds = readNumber(wordRecord, "start");
+    const endSeconds = readNumber(wordRecord, "end");
+    if (!word || startSeconds == null || endSeconds == null) {
+      continue;
+    }
+    words.push({
+      word,
+      startMs: secondsToMs(startSeconds),
+      endMs: secondsToMs(endSeconds),
+      confidence: readNumber(wordRecord, "confidence")
+    });
+  }
+  return words;
+}
+function dedupeSpeakers(segments) {
+  const seen = new Set;
+  const speakers = [];
+  for (const segment of segments) {
+    if (!segment.speakerId || seen.has(segment.speakerId)) {
+      continue;
+    }
+    seen.add(segment.speakerId);
+    speakers.push({
+      id: segment.speakerId,
+      name: segment.speakerName
+    });
+  }
+  return speakers;
+}
+function normalizeBaseUrl(url) {
+  return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+function asRecord(value) {
+  if (value && typeof value === "object") {
+    return value;
+  }
+  return {};
+}
+function readString(record, key) {
+  const value = record[key];
+  return typeof value === "string" ? value : undefined;
+}
+function readNumber(record, key) {
+  const value = record[key];
+  return typeof value === "number" ? value : undefined;
+}
+function secondsToMs(value) {
+  return Math.round(value * 1000);
+}
+
+// src/impls/mistral-conversational.session.ts
+class MistralConversationSession {
+  events;
+  queue = new AsyncEventQueue;
+  turns = [];
+  history = [];
+  sessionId = crypto.randomUUID();
+  startedAt = Date.now();
+  sessionConfig;
+  defaultModel;
+  complete;
+  sttProvider;
+  pending = Promise.resolve();
+  closed = false;
+  closedSummary;
+  constructor(options) {
+    this.sessionConfig = options.sessionConfig;
+    this.defaultModel = options.defaultModel;
+    this.complete = options.complete;
+    this.sttProvider = options.sttProvider;
+    this.events = this.queue;
+    this.queue.push({
+      type: "session_started",
+      sessionId: this.sessionId
+    });
+  }
+  sendAudio(chunk) {
+    if (this.closed) {
+      return;
+    }
+    this.pending = this.pending.then(async () => {
+      const transcription = await this.sttProvider.transcribe({
+        audio: {
+          data: chunk,
+          format: this.sessionConfig.inputFormat ?? "pcm",
+          sampleRateHz: 16000
+        },
+        language: this.sessionConfig.language
+      });
+      const transcriptText = transcription.text.trim();
+      if (transcriptText.length > 0) {
+        await this.handleUserText(transcriptText);
+      }
+    }).catch((error) => {
+      this.emitError(error);
+    });
+  }
+  sendText(text) {
+    if (this.closed) {
+      return;
+    }
+    const normalized = text.trim();
+    if (normalized.length === 0) {
+      return;
+    }
+    this.pending = this.pending.then(() => this.handleUserText(normalized)).catch((error) => {
+      this.emitError(error);
+    });
+  }
+  interrupt() {
+    if (this.closed) {
+      return;
+    }
+    this.queue.push({
+      type: "error",
+      error: new Error("Interrupt is not supported for non-streaming sessions.")
+    });
+  }
+  async close() {
+    if (this.closedSummary) {
+      return this.closedSummary;
+    }
+    this.closed = true;
+    await this.pending;
+    const durationMs = Date.now() - this.startedAt;
+    const summary = {
+      sessionId: this.sessionId,
+      durationMs,
+      turns: this.turns.map((turn) => ({
+        role: turn.role === "assistant" ? "agent" : turn.role,
+        text: turn.text,
+        startMs: turn.startMs,
+        endMs: turn.endMs
+      })),
+      transcript: this.turns.map((turn) => `${turn.role}: ${turn.text}`).join(`
+`)
+    };
+    this.closedSummary = summary;
+    this.queue.push({
+      type: "session_ended",
+      reason: "closed_by_client",
+      durationMs
+    });
+    this.queue.close();
+    return summary;
+  }
+  async handleUserText(text) {
+    if (this.closed) {
+      return;
+    }
+    const userStart = Date.now();
+    this.queue.push({ type: "user_speech_started" });
+    this.queue.push({ type: "user_speech_ended", transcript: text });
+    this.queue.push({
+      type: "transcript",
+      role: "user",
+      text,
+      timestamp: userStart
+    });
+    this.turns.push({
+      role: "user",
+      text,
+      startMs: userStart,
+      endMs: Date.now()
+    });
+    this.history.push({ role: "user", content: text });
+    const assistantStart = Date.now();
+    const assistantText = await this.complete(this.history, {
+      ...this.sessionConfig,
+      llmModel: this.sessionConfig.llmModel ?? this.defaultModel
+    });
+    if (this.closed) {
+      return;
+    }
+    const normalizedAssistantText = assistantText.trim();
+    const finalAssistantText = normalizedAssistantText.length > 0 ? normalizedAssistantText : "I was unable to produce a response.";
+    this.queue.push({
+      type: "agent_speech_started",
+      text: finalAssistantText
+    });
+    this.queue.push({
+      type: "transcript",
+      role: "agent",
+      text: finalAssistantText,
+      timestamp: assistantStart
+    });
+    this.queue.push({ type: "agent_speech_ended" });
+    this.turns.push({
+      role: "assistant",
+      text: finalAssistantText,
+      startMs: assistantStart,
+      endMs: Date.now()
+    });
+    this.history.push({ role: "assistant", content: finalAssistantText });
+  }
+  emitError(error) {
+    if (this.closed) {
+      return;
+    }
+    this.queue.push({ type: "error", error: toError(error) });
+  }
+}
+function toError(error) {
+  if (error instanceof Error) {
+    return error;
+  }
+  return new Error(String(error));
+}
+
+// src/impls/mistral-conversational.ts
+var DEFAULT_BASE_URL2 = "https://api.mistral.ai/v1";
+var DEFAULT_MODEL2 = "mistral-small-latest";
+var DEFAULT_VOICE = "default";
+
+class MistralConversationalProvider {
+  apiKey;
+  defaultModel;
+  defaultVoiceId;
+  baseUrl;
+  fetchImpl;
+  sttProvider;
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new Error("MistralConversationalProvider requires an apiKey");
+    }
+    this.apiKey = options.apiKey;
+    this.defaultModel = options.defaultModel ?? DEFAULT_MODEL2;
+    this.defaultVoiceId = options.defaultVoiceId ?? DEFAULT_VOICE;
+    this.baseUrl = normalizeBaseUrl2(options.serverURL ?? DEFAULT_BASE_URL2);
+    this.fetchImpl = options.fetchImpl ?? fetch;
+    this.sttProvider = options.sttProvider ?? new MistralSttProvider({
+      apiKey: options.apiKey,
+      defaultModel: options.sttOptions?.defaultModel,
+      defaultLanguage: options.sttOptions?.defaultLanguage,
+      serverURL: options.sttOptions?.serverURL ?? options.serverURL,
+      fetchImpl: this.fetchImpl
+    });
+  }
+  async startSession(config) {
+    return new MistralConversationSession({
+      sessionConfig: {
+        ...config,
+        voiceId: config.voiceId || this.defaultVoiceId
+      },
+      defaultModel: this.defaultModel,
+      complete: (history, sessionConfig) => this.completeConversation(history, sessionConfig),
+      sttProvider: this.sttProvider
+    });
+  }
+  async listVoices() {
+    return [
+      {
+        id: this.defaultVoiceId,
+        name: "Mistral Default Voice",
+        description: "Default conversational voice profile.",
+        capabilities: ["conversational"]
+      }
+    ];
+  }
+  async completeConversation(history, sessionConfig) {
+    const model = sessionConfig.llmModel ?? this.defaultModel;
+    const messages = [];
+    if (sessionConfig.systemPrompt) {
+      messages.push({ role: "system", content: sessionConfig.systemPrompt });
+    }
+    for (const item of history) {
+      messages.push({ role: item.role, content: item.content });
+    }
+    const response = await this.fetchImpl(`${this.baseUrl}/chat/completions`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        model,
+        messages
+      })
+    });
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(`Mistral conversational request failed (${response.status}): ${body}`);
+    }
+    const payload = await response.json();
+    return readAssistantText(payload);
+  }
+}
+function normalizeBaseUrl2(url) {
+  return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+function readAssistantText(payload) {
+  const record = asRecord2(payload);
+  const choices = Array.isArray(record.choices) ? record.choices : [];
+  const firstChoice = asRecord2(choices[0]);
+  const message = asRecord2(firstChoice.message);
+  if (typeof message.content === "string") {
+    return message.content;
+  }
+  if (Array.isArray(message.content)) {
+    const textParts = message.content.map((part) => {
+      const entry = asRecord2(part);
+      const text = entry.text;
+      return typeof text === "string" ? text : "";
+    }).filter((text) => text.length > 0);
+    return textParts.join("");
+  }
+  return "";
+}
+function asRecord2(value) {
+  if (value && typeof value === "object") {
+    return value;
+  }
+  return {};
+}
+export {
+  MistralConversationalProvider
+};

package/dist/impls/mistral-conversational.session.d.ts

@@ -0,0 +1,32 @@
+import type { ConversationalEvent, ConversationalSession, ConversationalSessionConfig, ConversationalSessionSummary, STTProvider } from '../voice';
+export interface ConversationMessage {
+    role: 'user' | 'assistant';
+    content: string;
+}
+export declare class MistralConversationSession implements ConversationalSession {
+    readonly events: AsyncIterable<ConversationalEvent>;
+    private readonly queue;
+    private readonly turns;
+    private readonly history;
+    private readonly sessionId;
+    private readonly startedAt;
+    private readonly sessionConfig;
+    private readonly defaultModel;
+    private readonly complete;
+    private readonly sttProvider;
+    private pending;
+    private closed;
+    private closedSummary?;
+    constructor(options: {
+        sessionConfig: ConversationalSessionConfig;
+        defaultModel: string;
+        complete: (history: ConversationMessage[], sessionConfig: ConversationalSessionConfig) => Promise<string>;
+        sttProvider: STTProvider;
+    });
+    sendAudio(chunk: Uint8Array): void;
+    sendText(text: string): void;
+    interrupt(): void;
+    close(): Promise<ConversationalSessionSummary>;
+    private handleUserText;
+    private emitError;
+}

package/dist/impls/mistral-conversational.session.js

@@ -0,0 +1,206 @@
+// @bun
+// src/impls/async-event-queue.ts
+class AsyncEventQueue {
+  values = [];
+  waiters = [];
+  done = false;
+  push(value) {
+    if (this.done) {
+      return;
+    }
+    const waiter = this.waiters.shift();
+    if (waiter) {
+      waiter({ value, done: false });
+      return;
+    }
+    this.values.push(value);
+  }
+  close() {
+    if (this.done) {
+      return;
+    }
+    this.done = true;
+    for (const waiter of this.waiters) {
+      waiter({ value: undefined, done: true });
+    }
+    this.waiters.length = 0;
+  }
+  [Symbol.asyncIterator]() {
+    return {
+      next: async () => {
+        const value = this.values.shift();
+        if (value != null) {
+          return { value, done: false };
+        }
+        if (this.done) {
+          return { value: undefined, done: true };
+        }
+        return new Promise((resolve) => {
+          this.waiters.push(resolve);
+        });
+      }
+    };
+  }
+}
+
+// src/impls/mistral-conversational.session.ts
+class MistralConversationSession {
+  events;
+  queue = new AsyncEventQueue;
+  turns = [];
+  history = [];
+  sessionId = crypto.randomUUID();
+  startedAt = Date.now();
+  sessionConfig;
+  defaultModel;
+  complete;
+  sttProvider;
+  pending = Promise.resolve();
+  closed = false;
+  closedSummary;
+  constructor(options) {
+    this.sessionConfig = options.sessionConfig;
+    this.defaultModel = options.defaultModel;
+    this.complete = options.complete;
+    this.sttProvider = options.sttProvider;
+    this.events = this.queue;
+    this.queue.push({
+      type: "session_started",
+      sessionId: this.sessionId
+    });
+  }
+  sendAudio(chunk) {
+    if (this.closed) {
+      return;
+    }
+    this.pending = this.pending.then(async () => {
+      const transcription = await this.sttProvider.transcribe({
+        audio: {
+          data: chunk,
+          format: this.sessionConfig.inputFormat ?? "pcm",
+          sampleRateHz: 16000
+        },
+        language: this.sessionConfig.language
+      });
+      const transcriptText = transcription.text.trim();
+      if (transcriptText.length > 0) {
+        await this.handleUserText(transcriptText);
+      }
+    }).catch((error) => {
+      this.emitError(error);
+    });
+  }
+  sendText(text) {
+    if (this.closed) {
+      return;
+    }
+    const normalized = text.trim();
+    if (normalized.length === 0) {
+      return;
+    }
+    this.pending = this.pending.then(() => this.handleUserText(normalized)).catch((error) => {
+      this.emitError(error);
+    });
+  }
+  interrupt() {
+    if (this.closed) {
+      return;
+    }
+    this.queue.push({
+      type: "error",
+      error: new Error("Interrupt is not supported for non-streaming sessions.")
+    });
+  }
+  async close() {
+    if (this.closedSummary) {
+      return this.closedSummary;
+    }
+    this.closed = true;
+    await this.pending;
+    const durationMs = Date.now() - this.startedAt;
+    const summary = {
+      sessionId: this.sessionId,
+      durationMs,
+      turns: this.turns.map((turn) => ({
+        role: turn.role === "assistant" ? "agent" : turn.role,
+        text: turn.text,
+        startMs: turn.startMs,
+        endMs: turn.endMs
+      })),
+      transcript: this.turns.map((turn) => `${turn.role}: ${turn.text}`).join(`
+`)
+    };
+    this.closedSummary = summary;
+    this.queue.push({
+      type: "session_ended",
+      reason: "closed_by_client",
+      durationMs
+    });
+    this.queue.close();
+    return summary;
+  }
+  async handleUserText(text) {
+    if (this.closed) {
+      return;
+    }
+    const userStart = Date.now();
+    this.queue.push({ type: "user_speech_started" });
+    this.queue.push({ type: "user_speech_ended", transcript: text });
+    this.queue.push({
+      type: "transcript",
+      role: "user",
+      text,
+      timestamp: userStart
+    });
+    this.turns.push({
+      role: "user",
+      text,
+      startMs: userStart,
+      endMs: Date.now()
+    });
+    this.history.push({ role: "user", content: text });
+    const assistantStart = Date.now();
+    const assistantText = await this.complete(this.history, {
+      ...this.sessionConfig,
+      llmModel: this.sessionConfig.llmModel ?? this.defaultModel
+    });
+    if (this.closed) {
+      return;
+    }
+    const normalizedAssistantText = assistantText.trim();
+    const finalAssistantText = normalizedAssistantText.length > 0 ? normalizedAssistantText : "I was unable to produce a response.";
+    this.queue.push({
+      type: "agent_speech_started",
+      text: finalAssistantText
+    });
+    this.queue.push({
+      type: "transcript",
+      role: "agent",
+      text: finalAssistantText,
+      timestamp: assistantStart
+    });
+    this.queue.push({ type: "agent_speech_ended" });
+    this.turns.push({
+      role: "assistant",
+      text: finalAssistantText,
+      startMs: assistantStart,
+      endMs: Date.now()
+    });
+    this.history.push({ role: "assistant", content: finalAssistantText });
+  }
+  emitError(error) {
+    if (this.closed) {
+      return;
+    }
+    this.queue.push({ type: "error", error: toError(error) });
+  }
+}
+function toError(error) {
+  if (error instanceof Error) {
+    return error;
+  }
+  return new Error(String(error));
+}
+export {
+  MistralConversationSession
+};