@applica-software-guru/persona-sdk 0.1.106 → 0.1.108

package/src/agents/types.ts

@@ -7,7 +7,7 @@ export type LanguageCode = 'en-US' | 'it-IT' | 'es-ES' | 'fr-FR' | 'de-DE' | 'pt
 
 export type SynthesizerName = 'gcloud' | 'elevenlabs' | 'gtts' | 'openai';
 
-export type TranscriberName = 'gcloud' | 'deepgram' | 'vosk';
+export type TranscriberName = 'gcloud' | 'deepgram' | 'elevenlabs' | 'vosk';
 
 
 export type ToolType = 'remote' | 'local';
@@ -93,13 +93,34 @@ export interface SynthesizerConfiguration {
   stability?: number;
   style?: number;
   voiceInstructions?: string;
+  /**
+   * 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 +170,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 +370,8 @@ export interface Agent {
   initialMessageMode?: "processed" | "static";
   knowledge?: KnowledgeConfiguration;
   wakeup?: WakeupConfiguration;
+  backchannel?: BackchannelConfiguration;
+  thinkingFiller?: ThinkingFillerConfiguration;
   telegram?: TelegramConfiguration;
   whatsapp?: WhatsAppConfiguration;
   collaboration?: CollaborationConfiguration;
@@ -317,6 +403,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

@@ -39,6 +39,11 @@ export type {
   Variable,
   VariableSource,
   WakeupConfiguration,
+  BackchannelConfiguration,
+  BackchannelMode,
+  ThinkingFillerConfiguration,
+  ThinkingFillerMode,
+  CommitStrategy,
   WhatsAppConfiguration,
   Tool,
   ToolType,
@@ -151,7 +156,16 @@ export type {
 export { MissionsApi } from './missions/missions-api';
 export type { Mission, MissionStatus } from './missions/types';
 export { ServicePricesApi } from './service-prices/service-prices-api';
-export type { ServicePrice } from './service-prices/types';
+export type {
+  ServicePrice,
+  ServicePriceListParams,
+  ServicePricePricingStatus,
+  ServicePriceSort,
+  ServicePriceSortField,
+  ServicePriceStats,
+  ServicePriceStatsParams,
+  ServicePriceUnit,
+} from './service-prices/types';
 export { MarkupRulesApi } from './markup-rules/markup-rules-api';
 export type { MarkupRule } from './markup-rules/types';
 export { ProvidersApi } from './providers/providers-api';

package/src/service-prices/service-prices-api.ts

@@ -1,20 +1,29 @@
 import { HttpApi } from '../http-api';
 import { Paginated } from '../paginated';
 import { AuthenticationProvider } from '../auth/authentication-provider';
-import { ServicePrice } from './types';
+import { ServicePrice, ServicePriceListParams, ServicePriceStats, ServicePriceStatsParams } from './types';
 
 export class ServicePricesApi extends HttpApi {
   constructor(baseUrl: string, auth: string | AuthenticationProvider) {
     super(baseUrl, auth);
   }
 
-  async list(keyword?: string | null, page?: number, size?: number, extraParams?: Record<string, string>): Promise<Paginated<ServicePrice>> {
+  async list(
+    keyword?: string | null,
+    page?: number,
+    size?: number,
+    extraParams?: ServicePriceListParams
+  ): Promise<Paginated<ServicePrice>> {
     const { page: p, size: s } = this.normalizePageParams(page, size);
     const params: Record<string, unknown> = { page: p, size: s, ...extraParams };
     if (keyword) params.keyword = keyword;
     return this.httpGet<Paginated<ServicePrice>>('/service-prices', params);
   }
 
+  async getStats(params: ServicePriceStatsParams = {}): Promise<ServicePriceStats> {
+    return this.httpGet<ServicePriceStats>('/service-prices/stats', { ...params });
+  }
+
   async get(id: string): Promise<ServicePrice> {
     return this.httpGet<ServicePrice>('/service-prices/' + id);
   }

package/src/service-prices/types.ts

@@ -5,3 +5,27 @@ export interface ServicePrice {
   unit?: string;
   fixedPrice?: number;
 }
+
+export type ServicePriceUnit = 'seconds' | 'tokens' | 'characters' | 'pages' | 'calls';
+export type ServicePricePricingStatus = 'priced' | 'unpriced' | 'withFixedPrice';
+export type ServicePriceSortField = 'service' | 'cost' | 'unit' | 'fixedPrice';
+export type ServicePriceSort = `${ServicePriceSortField},${'asc' | 'desc'}`;
+
+export interface ServicePriceListParams {
+  sort?: ServicePriceSort;
+  unit?: ServicePriceUnit;
+  pricingStatus?: ServicePricePricingStatus;
+  [key: string]: string | undefined;
+}
+
+export interface ServicePriceStatsParams {
+  keyword?: string | null;
+  unit?: ServicePriceUnit;
+}
+
+export interface ServicePriceStats {
+  total: number;
+  priced: number;
+  unpriced: number;
+  withFixedPrice: number;
+}

package/tests/service-prices-api.test.mjs

@@ -0,0 +1,69 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { ServicePricesApi } from '../dist/bundle.es.js';
+
+function jsonResponse(body) {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+
+test('service price list forwards typed sort and filters', async (context) => {
+  const originalFetch = globalThis.fetch;
+  context.after(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  let requestUrl;
+  globalThis.fetch = async (url) => {
+    requestUrl = new URL(url);
+    return jsonResponse({ items: [], total: 0, page: 2, size: 10 });
+  };
+
+  const api = new ServicePricesApi('https://example.test', 'api-key');
+  await api.list('openai', 2, 10, {
+    sort: 'cost,desc',
+    unit: 'tokens',
+    pricingStatus: 'unpriced',
+  });
+
+  assert.equal(requestUrl.pathname, '/service-prices');
+  assert.deepEqual(Object.fromEntries(requestUrl.searchParams), {
+    page: '2',
+    size: '10',
+    sort: 'cost,desc',
+    unit: 'tokens',
+    pricingStatus: 'unpriced',
+    keyword: 'openai',
+  });
+});
+
+test('service price stats forwards its filters and returns KPI values', async (context) => {
+  const originalFetch = globalThis.fetch;
+  context.after(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  let requestUrl;
+  globalThis.fetch = async (url) => {
+    requestUrl = new URL(url);
+    return jsonResponse({ total: 10, priced: 7, unpriced: 3, withFixedPrice: 2 });
+  };
+
+  const api = new ServicePricesApi('https://example.test', 'api-key');
+  const stats = await api.getStats({ keyword: 'model', unit: 'tokens' });
+
+  assert.equal(requestUrl.pathname, '/service-prices/stats');
+  assert.deepEqual(Object.fromEntries(requestUrl.searchParams), {
+    keyword: 'model',
+    unit: 'tokens',
+  });
+  assert.deepEqual(stats, {
+    total: 10,
+    priced: 7,
+    unpriced: 3,
+    withFixedPrice: 2,
+  });
+});