@applica-software-guru/persona-sdk 0.1.107 → 0.1.109

package/dist/index.d.ts

@@ -22,6 +22,8 @@ export declare interface Agent {
     initialMessageMode?: "processed" | "static";
     knowledge?: KnowledgeConfiguration;
     wakeup?: WakeupConfiguration;
+    backchannel?: BackchannelConfiguration;
+    thinkingFiller?: ThinkingFillerConfiguration;
     telegram?: TelegramConfiguration;
     whatsapp?: WhatsAppConfiguration;
     collaboration?: CollaborationConfiguration;
@@ -56,6 +58,8 @@ export declare interface AgentCreateRequest {
     initialMessageMode?: "processed" | "static";
     knowledge?: KnowledgeConfiguration;
     wakeup?: WakeupConfiguration;
+    backchannel?: BackchannelConfiguration;
+    thinkingFiller?: ThinkingFillerConfiguration;
     telegram?: TelegramConfiguration;
     whatsapp?: WhatsAppConfiguration;
     collaboration?: CollaborationConfiguration;
@@ -165,6 +169,44 @@ export declare interface AuthorizeResponse {
     redirectUrl?: string;
 }
 
+/**
+ * Riempitivi vocali emessi mentre l'utente sta ancora parlando.
+ *
+ * Due modalità con compromessi diversi:
+ * - `static`: una parola scelta a caso dalla lista. Le clip sono
+ *   pre-sintetizzate e in cache, quindi la latenza aggiunta è zero.
+ * - `llm`: un modello veloce genera la frase seguendo `instructions`. Più
+ *   pertinente, ma la prima volta che produce un testo nuovo si paga LLM più
+ *   TTS; se non è pronto in tempo si ripiega su una parola della lista.
+ *
+ * Richiede un synthesizer con sintesi one-shot (gcloud o elevenlabs).
+ */
+export declare interface BackchannelConfiguration {
+    enabled?: boolean;
+    mode?: BackchannelMode;
+    /** Lista per `static`, e fallback per `llm` quando il modello tarda. */
+    words?: string[];
+    /** Solo `llm`: cosa deve generare il modello. */
+    instructions?: string;
+    /** Tetto sulle parole generate, per non parlare sopra l'utente. */
+    maxGeneratedWords?: number;
+    /** Parlato continuo richiesto prima di intervenire. */
+    minSpeechSeconds?: number;
+    maxPerUserTurn?: number;
+    partialFreshnessSeconds?: number;
+    agentSilenceSeconds?: number;
+    throttleSeconds?: number;
+    /**
+     * Modello usato dalla modalità `llm`. Va scelto piccolo e veloce: sta nel
+     * percorso critico di un riempitivo che deve arrivare entro un secondo.
+     */
+    model?: ModelConfiguration;
+    llmTimeoutSeconds?: number;
+    prewarm?: boolean;
+}
+
+export declare type BackchannelMode = 'static' | 'llm';
+
 export declare class BearerTokenAuthenticationProvider implements AuthenticationProvider {
     private readonly token;
     constructor(token: string);
@@ -246,6 +288,8 @@ export declare interface Collaborator {
     scope?: string;
 }
 
+export declare type CommitStrategy = 'vad' | 'manual';
+
 export declare interface CommittedUsage {
     id?: string;
     committedAt?: string;
@@ -1240,10 +1284,25 @@ export declare interface SynthesizerConfiguration {
     stability?: number;
     style?: number;
     voiceInstructions?: string;
+    /**
+     * Solo ElevenLabs. `websocket` spinge il testo man mano che arriva dal
+     * modello su una connessione persistente (un socket per sessione, un contesto
+     * per turno) invece di una richiesta HTTP per frase: l'handshake si paga una
+     * volta per chiamata e non per turno. Se il socket cade si degrada sull'HTTP.
+     */
+    transport?: SynthesizerTransport;
+    /**
+     * Solo ElevenLabs, 0-4. Valori alti riducono la latenza ma dal 4 il
+     * normalizzatore del testo viene disattivato e numeri e date vengono
+     * pronunciati male.
+     */
+    optimizeStreamingLatency?: number;
 }
 
 export declare type SynthesizerName = 'gcloud' | 'elevenlabs' | 'gtts' | 'openai';
 
+export declare type SynthesizerTransport = 'http' | 'websocket';
+
 export declare interface SynthesizerVoice {
     id?: string;
     name?: string;
@@ -1257,6 +1316,31 @@ export declare interface TelegramConfiguration {
     enabledUsers?: string[];
 }
 
+/**
+ * Riempitivo emesso quando l'agente è occupato e muto.
+ *
+ * Copre due momenti che per l'utente sono lo stesso silenzio: la chiamata di uno
+ * strumento e la fase di ragionamento del modello. Non scatta se l'agente ha già
+ * detto qualcosa prima di occuparsi.
+ */
+export declare interface ThinkingFillerConfiguration {
+    enabled?: boolean;
+    /** `sound` è il tono breve, `words` una frase parlata scelta a caso. */
+    mode?: ThinkingFillerMode;
+    words?: string[];
+    /** Attesa prima di emettere: le attese rapide non producono niente. */
+    delaySeconds?: number;
+    /** Distanza minima tra due riempitivi, condivisa col backchannel. */
+    throttleSeconds?: number;
+    /**
+     * Se emettere il riempitivo anche mentre il modello ragiona. Disattivo per
+     * default: con modelli che ragionano a ogni turno può diventare invadente.
+     */
+    onReasoning?: boolean;
+}
+
+export declare type ThinkingFillerMode = 'sound' | 'words';
+
 export declare interface Tool {
     type?: ToolType;
     name?: string;
@@ -1297,9 +1381,22 @@ export declare interface TranscriberConfiguration {
     transcriberName?: TranscriberName;
     languageCode?: LanguageCode;
     sampleRateHertz?: number;
+    /**
+     * Secondi di silenzio dopo i quali il turno dell'utente è considerato
+     * concluso: è il parametro con più impatto sulla latenza percepita, perché
+     * l'agente non inizia a elaborare prima che scada. Valori bassi rendono la
+     * conversazione reattiva ma spezzano le pause di pensiero in due turni.
+     */
+    silenceDurationThreshold?: number;
+    /** Solo ElevenLabs Scribe. */
+    modelId?: string;
+    commitStrategy?: CommitStrategy;
+    keyterms?: string[];
+    secondaryLanguages?: string[];
+    filterBackgroundAudio?: boolean;
 }
 
-export declare type TranscriberName = 'gcloud' | 'deepgram' | 'vosk';
+export declare type TranscriberName = 'gcloud' | 'deepgram' | 'elevenlabs' | 'vosk';
 
 export declare interface TransferAction {
     request?: string;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@applica-software-guru/persona-sdk",
   "description": "Official TypeScript SDK for the Persona API — manage agents, sessions, projects, knowledge bases, workflows, triggers and more.",
   "private": false,
-  "version": "0.1.107",
+  "version": "0.1.109",
   "type": "module",
   "scripts": {
     "dev": "vite",

package/src/agents/types.ts

@@ -6,8 +6,9 @@ export type LanguageCode = 'en-US' | 'it-IT' | 'es-ES' | 'fr-FR' | 'de-DE' | 'pt
 
 
 export type SynthesizerName = 'gcloud' | 'elevenlabs' | 'gtts' | 'openai';
+export type SynthesizerTransport = 'http' | 'websocket';
 
-export type TranscriberName = 'gcloud' | 'deepgram' | 'vosk';
+export type TranscriberName = 'gcloud' | 'deepgram' | 'elevenlabs' | 'vosk';
 
 
 export type ToolType = 'remote' | 'local';
@@ -93,13 +94,41 @@ export interface SynthesizerConfiguration {
   stability?: number;
   style?: number;
   voiceInstructions?: string;
-}
+  /**
+   * Solo ElevenLabs. `websocket` spinge il testo man mano che arriva dal
+   * modello su una connessione persistente (un socket per sessione, un contesto
+   * per turno) invece di una richiesta HTTP per frase: l'handshake si paga una
+   * volta per chiamata e non per turno. Se il socket cade si degrada sull'HTTP.
+   */
+  transport?: SynthesizerTransport;
+  /**
+   * Solo ElevenLabs, 0-4. Valori alti riducono la latenza ma dal 4 il
+   * normalizzatore del testo viene disattivato e numeri e date vengono
+   * pronunciati male.
+   */
+  optimizeStreamingLatency?: number;
+}
+
+export type CommitStrategy = 'vad' | 'manual';
 
 export interface TranscriberConfiguration {
   enabled?: boolean;
   transcriberName?: TranscriberName;
   languageCode?: LanguageCode;
   sampleRateHertz?: number;
+  /**
+   * Secondi di silenzio dopo i quali il turno dell'utente è considerato
+   * concluso: è il parametro con più impatto sulla latenza percepita, perché
+   * l'agente non inizia a elaborare prima che scada. Valori bassi rendono la
+   * conversazione reattiva ma spezzano le pause di pensiero in due turni.
+   */
+  silenceDurationThreshold?: number;
+  /** Solo ElevenLabs Scribe. */
+  modelId?: string;
+  commitStrategy?: CommitStrategy;
+  keyterms?: string[];
+  secondaryLanguages?: string[];
+  filterBackgroundAudio?: boolean;
 }
 
 export interface KnowledgeConfiguration {
@@ -149,6 +178,69 @@ export interface WakeupConfiguration {
   sleepDelaySeconds?: number;
 }
 
+export type ThinkingFillerMode = 'sound' | 'words';
+
+/**
+ * Riempitivo emesso quando l'agente è occupato e muto.
+ *
+ * Copre due momenti che per l'utente sono lo stesso silenzio: la chiamata di uno
+ * strumento e la fase di ragionamento del modello. Non scatta se l'agente ha già
+ * detto qualcosa prima di occuparsi.
+ */
+export interface ThinkingFillerConfiguration {
+  enabled?: boolean;
+  /** `sound` è il tono breve, `words` una frase parlata scelta a caso. */
+  mode?: ThinkingFillerMode;
+  words?: string[];
+  /** Attesa prima di emettere: le attese rapide non producono niente. */
+  delaySeconds?: number;
+  /** Distanza minima tra due riempitivi, condivisa col backchannel. */
+  throttleSeconds?: number;
+  /**
+   * Se emettere il riempitivo anche mentre il modello ragiona. Disattivo per
+   * default: con modelli che ragionano a ogni turno può diventare invadente.
+   */
+  onReasoning?: boolean;
+}
+
+export type BackchannelMode = 'static' | 'llm';
+
+/**
+ * Riempitivi vocali emessi mentre l'utente sta ancora parlando.
+ *
+ * Due modalità con compromessi diversi:
+ * - `static`: una parola scelta a caso dalla lista. Le clip sono
+ *   pre-sintetizzate e in cache, quindi la latenza aggiunta è zero.
+ * - `llm`: un modello veloce genera la frase seguendo `instructions`. Più
+ *   pertinente, ma la prima volta che produce un testo nuovo si paga LLM più
+ *   TTS; se non è pronto in tempo si ripiega su una parola della lista.
+ *
+ * Richiede un synthesizer con sintesi one-shot (gcloud o elevenlabs).
+ */
+export interface BackchannelConfiguration {
+  enabled?: boolean;
+  mode?: BackchannelMode;
+  /** Lista per `static`, e fallback per `llm` quando il modello tarda. */
+  words?: string[];
+  /** Solo `llm`: cosa deve generare il modello. */
+  instructions?: string;
+  /** Tetto sulle parole generate, per non parlare sopra l'utente. */
+  maxGeneratedWords?: number;
+  /** Parlato continuo richiesto prima di intervenire. */
+  minSpeechSeconds?: number;
+  maxPerUserTurn?: number;
+  partialFreshnessSeconds?: number;
+  agentSilenceSeconds?: number;
+  throttleSeconds?: number;
+  /**
+   * Modello usato dalla modalità `llm`. Va scelto piccolo e veloce: sta nel
+   * percorso critico di un riempitivo che deve arrivare entro un secondo.
+   */
+  model?: ModelConfiguration;
+  llmTimeoutSeconds?: number;
+  prewarm?: boolean;
+}
+
 export interface TelegramConfiguration {
   enabled?: boolean;
   botToken?: string;
@@ -286,6 +378,8 @@ export interface Agent {
   initialMessageMode?: "processed" | "static";
   knowledge?: KnowledgeConfiguration;
   wakeup?: WakeupConfiguration;
+  backchannel?: BackchannelConfiguration;
+  thinkingFiller?: ThinkingFillerConfiguration;
   telegram?: TelegramConfiguration;
   whatsapp?: WhatsAppConfiguration;
   collaboration?: CollaborationConfiguration;
@@ -317,6 +411,8 @@ export interface AgentCreateRequest {
   initialMessageMode?: "processed" | "static";
   knowledge?: KnowledgeConfiguration;
   wakeup?: WakeupConfiguration;
+  backchannel?: BackchannelConfiguration;
+  thinkingFiller?: ThinkingFillerConfiguration;
   telegram?: TelegramConfiguration;
   whatsapp?: WhatsAppConfiguration;
   collaboration?: CollaborationConfiguration;

package/src/index.ts

@@ -31,6 +31,7 @@ export type {
   OrchestrationAgent,
   SynthesizerConfiguration,
   SynthesizerName,
+  SynthesizerTransport,
   SynthesizerVoice,
   TranscriberConfiguration,
   TranscriberName,
@@ -39,6 +40,11 @@ export type {
   Variable,
   VariableSource,
   WakeupConfiguration,
+  BackchannelConfiguration,
+  BackchannelMode,
+  ThinkingFillerConfiguration,
+  ThinkingFillerMode,
+  CommitStrategy,
   WhatsAppConfiguration,
   Tool,
   ToolType,