@applica-software-guru/persona-sdk 0.1.100 → 0.1.101

package/package.json

@@ -1,7 +1,8 @@
 {
   "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.100",
+  "version": "0.1.101",
   "type": "module",
   "scripts": {
     "dev": "vite",
@@ -12,68 +13,25 @@
     "format": "prettier --write ."
   },
   "devDependencies": {
-    "@assistant-ui/react-markdown": "^0.11.6",
-    "@radix-ui/react-avatar": "^1.1.11",
-    "@radix-ui/react-tooltip": "^1.2.8",
-    "@radix-ui/react-separator": "^1.1.8",
-    "@tailwindcss/vite": "^4.0.17",
-    "@types/inflection": "^1.13.2",
-    "@types/lodash": "^4.17.15",
     "@types/node": "^20.12.13",
-    "@types/react-dom": "^19.1.1",
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "@vitejs/plugin-react": "^4.3.0",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
     "eslint": "^8.25.0",
     "eslint-config-prettier": "^8.10.0",
-    "eslint-config-react-app": "7.0.1",
-    "eslint-plugin-export": "^0.1.2",
-    "eslint-plugin-filenames": "^1.3.2",
-    "eslint-plugin-import": "^2.26.0",
-    "eslint-plugin-jsx-a11y": "^6.6.1",
     "eslint-plugin-prettier": "^4.2.1",
-    "eslint-plugin-react": "^7.31.10",
-    "eslint-plugin-react-hooks": "^4.6.0",
-    "eslint-plugin-react-refresh": "^0.4.19",
-    "eslint-plugin-sort-exports": "^0.9.1",
-    "husky": "^9.0.11",
-    "jsdom": "^22.1.0",
-    "lodash": "^4.17.21",
-    "lucide-react": "^0.485.0",
     "prettier": "^2.8.8",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "react-markdown": "^10.0.1",
-    "remark-gfm": "^4.0.1",
-    "tailwind-merge": "^3.2.0",
-    "tailwindcss": "^4.0.17",
-    "tw-animate-css": "^1.2.8",
     "typescript": "^5.4.5",
     "vite": "^5.2.12",
-    "vite-plugin-compression": "^0.5.1",
-    "vite-plugin-dts": "^2.3.0",
-    "vite-plugin-linter": "^2.0.2",
-    "vitest": "^1.6.0"
+    "vite-plugin-dts": "^4.5.4"
   },
-  "peerDependencies": {
-    "@assistant-ui/react": "^0.11.47",
-    "@radix-ui/react-dialog": "^1.1.15",
-    "@radix-ui/react-slot": "^1.2.4",
-    "react": "^18 || ^19 || ^19.0.0-rc",
-    "react-dom": "^18 || ^19 || ^19.0.0-rc",
-    "rehype-raw": "^7.0.0",
-    "zustand": "^5.0.9"
-  },
-  "peerDependenciesMeta": {
-    "react-dom": {
-      "optional": false
-    }
-  },
-  "dependencies": {},
   "keywords": [
-    "persona-sdk"
+    "persona-sdk",
+    "persona",
+    "ai",
+    "sdk",
+    "chatbot",
+    "agents"
   ],
   "main": "dist/bundle.cjs.js",
   "module": "dist/bundle.es.js",

package/src/agents/agents-api.ts

@@ -0,0 +1,66 @@
+import { HttpApi } from '../http-api';
+import { Paginated } from '../paginated';
+import { AuthenticationProvider } from '../auth/authentication-provider';
+import {
+  Agent,
+  AgentCreateRequest,
+  AgentUpdateRequest,
+  SynthesizerVoice,
+  Revision,
+} from './types';
+
+export class AgentsApi 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<Agent>> {
+    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<Agent>>('/agents', params);
+  }
+
+  async get(agentId: string): Promise<Agent> {
+    return this.httpGet<Agent>('/agents/' + agentId);
+  }
+
+  async create(request: AgentCreateRequest): Promise<Agent> {
+    return this.httpPost<Agent>('/agents', request);
+  }
+
+  async update(request: AgentUpdateRequest): Promise<Agent> {
+    return this.httpPut<Agent>('/agents/' + request.id, request);
+  }
+
+  async remove(agentId: string): Promise<void> {
+    await this.httpDelete('/agents/' + agentId);
+  }
+
+  async getSynthesizerSupportedVoices(synthesizerName: string): Promise<SynthesizerVoice[]> {
+    return this.httpGet<SynthesizerVoice[]>('/values/synthesizers/' + synthesizerName + '/voices');
+  }
+
+  async listRevisions(agentId: string): Promise<Revision[]> {
+    return this.httpGet<Revision[]>('/agents/' + agentId + '/revisions');
+  }
+
+  async getRevision(agentId: string, revisionId: string): Promise<Revision> {
+    return this.httpGet<Revision>('/agents/' + agentId + '/revisions/' + revisionId);
+  }
+
+  async rollback(agentId: string, revisionId: string): Promise<Agent> {
+    return this.httpPost<Agent>('/agents/' + agentId + '/revisions/' + revisionId + '/rollback', {});
+  }
+
+  async generateSystemInstructions(prompt: string, sessionId?: string): Promise<string> {
+    const body: Record<string, unknown> = { prompt };
+    if (sessionId) body.sessionId = sessionId;
+    const result = await this.httpPost<{ instructions: string }>('/agents/system-instructions', body);
+    return result.instructions;
+  }
+
+  async getArchitect(): Promise<Agent> {
+    return this.httpGet<Agent>('/agents/architect');
+  }
+}

package/src/agents/types.ts

@@ -0,0 +1,349 @@
+export type AgentProtocol = 'webrtc' | 'twilio' | 'rest' | 'websocket' | 'telegram';
+
+export type KnowledgeType = 'multi_hop' | 'simple';
+
+export type LanguageCode = 'en-US' | 'it-IT' | 'es-ES' | 'fr-FR' | 'de-DE' | 'pt-BR';
+
+
+export type SynthesizerName = 'gcloud' | 'elevenlabs' | 'gtts' | 'openai';
+
+export type TranscriberName = 'gcloud' | 'deepgram' | 'vosk';
+
+export type StmType = 'simple' | 'summary' | 'compact';
+
+export type ToolType = 'remote' | 'local';
+
+export type CollaborationMode = 'delegate_and_return' | 'persistent_transfer' | 'consult_then_respond';
+
+export type ReasoningEffort = 'minimal' | 'low' | 'medium' | 'high';
+
+export type ModelProvider = 'google' | 'openai' | 'grok' | 'fireworks' | 'together' | 'ollama' | 'openai_compatible' | 'openrouter';
+
+export type AgentType = 'agent';
+
+export interface VariableSource {
+  type?: string;
+  tool?: string;
+  args?: Record<string, unknown>;
+  property?: string;
+  mcpServer?: string;
+  resourceUri?: string;
+}
+
+export interface Variable {
+  name?: string;
+  source?: VariableSource;
+  defaultValue?: unknown;
+}
+
+export interface ModelConfiguration {
+  /** litellm-style "<provider>/<model>" string (e.g. "fireworks/accounts/fireworks/models/minimax-m3"). Use the known-models API for the current list. */
+  modelName?: string;
+  temperature?: number;
+  reasoningEffort?: ReasoningEffort;
+  /** Maximum number of output tokens to generate. Undefined = provider default. */
+  maxOutputTokens?: number;
+  /** Override the per-provider default API key (env var) when set. */
+  apiKey?: string;
+  /** Override the per-provider default base URL when set. */
+  baseUrl?: string;
+  /** Passed verbatim as extra_body to the underlying LLM request (e.g. { service_tier: "priority" }). */
+  extraBody?: Record<string, unknown>;
+  /** @deprecated use `baseUrl`. Kept for backward compatibility. */
+  url?: string;
+  /** @deprecated use litellm `modelName` (e.g. "ollama/llama3.1"). */
+  ollamaModelName?: string;
+  /** @deprecated use litellm `modelName` (e.g. "openai_compatible/gpt-4o"). */
+  openaiCompatibleModelName?: string;
+  /** @deprecated use `apiKey`. */
+  openaiCompatibleApiKey?: string;
+  /** @deprecated use litellm `modelName` (e.g. "openrouter/anthropic/claude-3"). */
+  openrouterModelName?: string;
+}
+
+export type AttachmentsPreprocessorImageHandling = 'drop' | 'describe' | 'keep';
+
+export interface AttachmentsPreprocessorConfiguration {
+  enabled?: boolean;
+  imageHandling?: AttachmentsPreprocessorImageHandling;
+  standalonePassthrough?: boolean;
+  secondaryModel?: ModelConfiguration;
+  llmPrompt?: string;
+  pdfImageDpi?: number;
+  maxPages?: number;
+  failOpen?: boolean;
+}
+
+export interface SynthesizerVoice {
+  id?: string;
+  name?: string;
+  languageCodes?: string[];
+  gender?: string;
+}
+
+export interface SynthesizerConfiguration {
+  enabled?: boolean;
+  synthesizerName?: SynthesizerName;
+  languageCode?: LanguageCode;
+  voice?: string;
+  sampleRateHertz?: number;
+  speed?: number;
+  similarityBoost?: number;
+  stability?: number;
+  style?: number;
+  voiceInstructions?: string;
+}
+
+export interface TranscriberConfiguration {
+  enabled?: boolean;
+  transcriberName?: TranscriberName;
+  languageCode?: LanguageCode;
+  sampleRateHertz?: number;
+}
+
+export interface KnowledgeConfiguration {
+  enabled?: boolean;
+  knowledgeType?: KnowledgeType;
+  namespace?: string[];
+  numberOfEntries?: number;
+  args?: Record<string, unknown>;
+  knowledgeBaseId?: string;
+}
+
+export interface CollaborationConfiguration {
+  enabled?: boolean;
+  collaborators?: Collaborator[];
+  mode?: CollaborationMode;
+  maxNumberOfIterations?: number;
+}
+
+export interface Collaborator {
+  name?: string;
+  agent?: string;
+  scope?: string;
+}
+
+export interface OrchestrationAgent {
+  name?: string;
+  agent?: string;
+  scope?: string;
+}
+
+export interface OrchestrationConfiguration {
+  enabled?: boolean;
+  agents?: OrchestrationAgent[];
+  maxParallelCalls?: number;
+}
+
+export interface NetworkConfiguration {
+  allowedWebsites?: string[];
+  allowedIps?: string[];
+}
+
+export interface WakeupConfiguration {
+  enabled?: boolean;
+  wakeupWords?: string[];
+  sleepWords?: string[];
+  sleepInEachRequest?: boolean;
+  sleepDelaySeconds?: number;
+}
+
+export interface TelegramConfiguration {
+  enabled?: boolean;
+  botToken?: string;
+  enabledUsers?: string[];
+}
+
+export interface TwilioConfiguration {
+  phoneNumber?: string;
+}
+
+export interface WhatsAppConfiguration {
+  phoneNumberId?: string;
+  enabledUsers?: string[];
+}
+
+export interface SkillResource {
+  path?: string;
+  content?: string;
+  contentType?: string;
+}
+
+export interface SkillConfiguration {
+  name?: string;
+  description?: string;
+  instructions?: string;
+  allowedTools?: string[];
+  metadata?: Record<string, unknown>;
+  resources?: SkillResource[];
+}
+
+export interface McpServerConfiguration {
+  type?: string;
+  name?: string;
+  transport?: Transport;
+  enabledTools?: string[];
+  disabledTools?: string[];
+}
+
+export interface FlagConfiguration {
+  type?: string;
+  flag?: string;
+}
+
+export type FeatureConfiguration = McpServerConfiguration | FlagConfiguration | SkillConfiguration;
+
+export interface HttpTransport {
+  url?: string;
+  enablePersonaAuth?: boolean;
+  headers?: Record<string, string>;
+}
+
+export interface StdioTransport {
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+}
+
+export type Transport = HttpTransport | StdioTransport;
+
+export interface Feature {
+  id?: string;
+  templateId?: string;
+  credentialsId?: string;
+}
+
+export interface ToolLocalConfig {
+  parameters?: Record<string, unknown>;
+  output?: Record<string, unknown>;
+}
+
+export interface ToolRemoteConfig {
+  serviceUrl?: string;
+  secret?: string;
+  timeout?: number;
+}
+
+export type ToolConfig = ToolLocalConfig | ToolRemoteConfig;
+
+export interface ToolDefinition {
+  name?: string;
+  description?: string;
+  parameters?: Record<string, unknown>;
+  output?: Record<string, unknown>;
+}
+
+export interface Tool {
+  type?: ToolType;
+  name?: string;
+  description?: string;
+  config?: ToolConfig;
+}
+
+export interface ToolkitConfiguration {
+  tools?: Tool[];
+}
+
+export interface StmConfiguration {
+  type?: StmType;
+  maxMessages?: number;
+  includeToolCalls?: boolean;
+  model?: ModelConfiguration;
+  maxNumberOfWords?: number;
+  keepLastNObservations?: number;
+  maskingThreshold?: number;
+  summaryThreshold?: number;
+  maxContextTokens?: number;
+}
+
+export interface ContextManagementConfiguration {
+  enabled?: boolean;
+  maxContextTokens?: number;
+  summarizationThreshold?: number;
+  keepLastNIterations?: number;
+  keepFirstMessage?: boolean;
+  maxToolCallsBeforeCompaction?: number;
+  useLlmCompaction?: boolean;
+  maxSummaryWords?: number;
+  truncationEnabled?: boolean;
+  maxObservationTokens?: number;
+  compactionModel?: ModelConfiguration;
+}
+
+export interface Revision {
+  id?: string;
+  entityId?: string;
+  projectId?: string;
+  revisionNumber?: number;
+  createdAt?: string;
+  snapshot?: Record<string, unknown>;
+}
+
+export interface Agent {
+  id?: string;
+  projectId?: string;
+  apiKey?: string;
+  code?: string;
+  name?: string;
+  description?: string;
+  type?: AgentType;
+  synthesizer?: SynthesizerConfiguration;
+  transcriber?: TranscriberConfiguration;
+  model?: ModelConfiguration;
+  systemInstructions?: string;
+  variables?: Variable[];
+  enabledProtocols?: AgentProtocol[];
+  twilio?: TwilioConfiguration;
+  languageCode?: LanguageCode;
+  initialMessage?: string;
+  initialMessageMode?: "processed" | "static";
+  knowledge?: KnowledgeConfiguration;
+  wakeup?: WakeupConfiguration;
+  telegram?: TelegramConfiguration;
+  whatsapp?: WhatsAppConfiguration;
+  collaboration?: CollaborationConfiguration;
+  orchestration?: OrchestrationConfiguration;
+  network?: NetworkConfiguration;
+  features?: Feature[];
+  toolkit?: ToolkitConfiguration;
+  shortTermMemory?: StmConfiguration;
+  contextManagement?: ContextManagementConfiguration;
+  attachmentsPreprocessor?: AttachmentsPreprocessorConfiguration;
+  responseSchema?: Record<string, unknown>;
+  verboseErrors?: boolean;
+}
+
+export interface AgentCreateRequest {
+  projectId?: string;
+  code?: string;
+  name?: string;
+  description?: string;
+  type?: AgentType;
+  synthesizer?: SynthesizerConfiguration;
+  transcriber?: TranscriberConfiguration;
+  model?: ModelConfiguration;
+  systemInstructions?: string;
+  variables?: Variable[];
+  enabledProtocols?: AgentProtocol[];
+  twilio?: TwilioConfiguration;
+  languageCode?: LanguageCode;
+  initialMessage?: string;
+  initialMessageMode?: "processed" | "static";
+  knowledge?: KnowledgeConfiguration;
+  wakeup?: WakeupConfiguration;
+  telegram?: TelegramConfiguration;
+  whatsapp?: WhatsAppConfiguration;
+  collaboration?: CollaborationConfiguration;
+  orchestration?: OrchestrationConfiguration;
+  network?: NetworkConfiguration;
+  features?: Feature[];
+  toolkit?: ToolkitConfiguration;
+  shortTermMemory?: StmConfiguration;
+  contextManagement?: ContextManagementConfiguration;
+  attachmentsPreprocessor?: AttachmentsPreprocessorConfiguration;
+  responseSchema?: Record<string, unknown>;
+  verboseErrors?: boolean;
+}
+
+export interface AgentUpdateRequest extends Agent {}

package/src/auth/api-key-auth.ts

@@ -0,0 +1,13 @@
+import { AuthenticationProvider } from './authentication-provider';
+
+export class ApiKeyAuthenticationProvider implements AuthenticationProvider {
+  constructor(private readonly apiKey: string) {}
+
+  applyHeaders(headers: Headers): void {
+    headers.set('x-persona-apikey', this.apiKey);
+  }
+
+  getCredentials(): string {
+    return this.apiKey;
+  }
+}

package/src/auth/authentication-provider.ts

@@ -0,0 +1,4 @@
+export interface AuthenticationProvider {
+  applyHeaders(headers: Headers): void;
+  getCredentials(): string;
+}

package/src/auth/bearer-token-auth.ts

@@ -0,0 +1,13 @@
+import { AuthenticationProvider } from './authentication-provider';
+
+export class BearerTokenAuthenticationProvider implements AuthenticationProvider {
+  constructor(private readonly token: string) {}
+
+  applyHeaders(headers: Headers): void {
+    headers.set('Authorization', `Bearer ${this.token}`);
+  }
+
+  getCredentials(): string {
+    return this.token;
+  }
+}

package/src/auth/index.ts

@@ -0,0 +1,3 @@
+export type { AuthenticationProvider } from './authentication-provider';
+export { ApiKeyAuthenticationProvider } from './api-key-auth';
+export { BearerTokenAuthenticationProvider } from './bearer-token-auth';