@personize/sdk 0.6.6 → 0.7.1

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { PersonizeConfig, ApiResponse, MeResponse, TestResponse, ListOptions, GuidelinesResponse, GuidelineSectionOptions, GuidelineUpdatePayload, GuidelineCreatePayload, GuidelineHistoryResponse, GuidelineHistoryOptions, CollectionsResponse, CollectionCreatePayload, CollectionUpdatePayload, CollectionHistoryOptions, CollectionHistoryResponse, SmartGuidelinesOptions, SmartGuidelinesResponse, PromptOptions, PromptResponse, PromptStreamOptions, PromptSSEEvent, AgentRunOptions, AgentResponse, MemorizeOptions, SmartRecallOptions, RecallOptions, RecallResponse, SearchOptions, SearchResponse, BatchMemorizeOptions, SmartDigestOptions, SmartDigestResponse, EvaluateMemorizationOptions, EvaluateMemorizationResponse, UpdatePropertyOptions, UpdateResult, BulkUpdateOptions, BulkUpdateResult, PropertyHistoryOptions, PropertyHistoryResult, QueryPropertiesOptions, QueryPropertiesResult, DeleteMemoriesOptions, DeleteRecordOptions, DeletionResult, CancelDeletionOptions, CancelDeletionResult, FilterByPropertyOptions, FilterByPropertyResult, GetPropertiesOptions, GetPropertiesResponse } from './types';
+import { PersonizeConfig, ApiResponse, MeResponse, TestResponse, ListOptions, GuidelinesResponse, GuidelineSectionOptions, GuidelineUpdatePayload, GuidelineCreatePayload, GuidelineHistoryResponse, GuidelineHistoryOptions, CollectionsResponse, CollectionCreatePayload, CollectionUpdatePayload, CollectionHistoryOptions, CollectionHistoryResponse, SmartGuidelinesOptions, SmartGuidelinesResponse, PromptOptions, PromptResponse, PromptStreamOptions, PromptSSEEvent, AgentRunOptions, AgentResponse, MemorizeOptions, SmartRecallOptions, RecallOptions, RecallResponse, SearchOptions, SearchResponse, BatchMemorizeOptions, SmartDigestOptions, SmartDigestResponse, EvaluateMemorizationOptions, EvaluateMemorizationResponse, UpdatePropertyOptions, UpdateResult, BulkUpdateOptions, BulkUpdateResult, PropertyHistoryOptions, PropertyHistoryResult, QueryPropertiesOptions, QueryPropertiesResult, DeleteMemoriesOptions, DeleteRecordOptions, DeletionResult, CancelDeletionOptions, CancelDeletionResult, FilterByPropertyOptions, FilterByPropertyResult, GetPropertiesOptions, GetPropertiesResponse, ResponsesCreateOptions, ResponsesCompletedResult, ChatCompletionsOptions, ChatCompletionResult, SimilarOptions, SimilarResponse, SegmentOptions, SegmentResponse } from './types';
 export declare class Personize {
     private client;
     private _organizationId?;
@@ -229,6 +229,18 @@ export declare class Personize {
          * POST /api/v1/properties — Get record properties with schema descriptions.
          */
         properties: (data: GetPropertiesOptions) => Promise<ApiResponse<GetPropertiesResponse>>;
+        /**
+         * POST /api/v1/similar -- Find records similar to a seed record.
+         * Returns ranked results with similarity tiers.
+         * @see https://docs.personize.ai/api#similar
+         */
+        similar: (data: SimilarOptions) => Promise<ApiResponse<SimilarResponse>>;
+        /**
+         * POST /api/v1/segment -- Bucket all records into similarity tiers.
+         * Supports record-based or text-based seeds.
+         * @see https://docs.personize.ai/api#segment
+         */
+        segment: (data: SegmentOptions) => Promise<ApiResponse<SegmentResponse>>;
     };
     evaluate: {
         /**
@@ -237,4 +249,22 @@ export declare class Personize {
          */
         memorizationAccuracy: (data: EvaluateMemorizationOptions) => Promise<ApiResponse<EvaluateMemorizationResponse>>;
     };
+    responses: {
+        /**
+         * POST /api/v1/responses — Execute step-driven orchestration.
+         *
+         * If tools with execute functions are provided (Record format), the SDK
+         * automatically handles the tool execution loop: execute locally, send
+         * results back, repeat until completed.
+         */
+        create: (options: ResponsesCreateOptions) => Promise<ResponsesCompletedResult>;
+    };
+    chat: {
+        completions: {
+            /**
+             * POST /api/v1/chat/completions — OpenAI-compatible chat completion.
+             */
+            create: (options: ChatCompletionsOptions) => Promise<ChatCompletionResult>;
+        };
+    };
 }

package/dist/client.js

@@ -456,6 +456,24 @@ class Personize {
                 });
                 return response.data;
             },
+            /**
+             * POST /api/v1/similar -- Find records similar to a seed record.
+             * Returns ranked results with similarity tiers.
+             * @see https://docs.personize.ai/api#similar
+             */
+            similar: async (data) => {
+                const response = await this.client.post('/api/v1/similar', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/segment -- Bucket all records into similarity tiers.
+             * Supports record-based or text-based seeds.
+             * @see https://docs.personize.ai/api#segment
+             */
+            segment: async (data) => {
+                const response = await this.client.post('/api/v1/segment', data);
+                return response.data;
+            },
         };
         this.evaluate = {
             /**
@@ -467,6 +485,84 @@ class Personize {
                 return response.data;
             },
         };
+        this.responses = {
+            /**
+             * POST /api/v1/responses — Execute step-driven orchestration.
+             *
+             * If tools with execute functions are provided (Record format), the SDK
+             * automatically handles the tool execution loop: execute locally, send
+             * results back, repeat until completed.
+             */
+            create: async (options) => {
+                // Extract execute functions from tools (they don't get sent to server)
+                let toolSchemas;
+                let executeMap;
+                if (options.tools && !Array.isArray(options.tools)) {
+                    // Record format — extract execute functions
+                    executeMap = new Map();
+                    toolSchemas = [];
+                    for (const [name, def] of Object.entries(options.tools)) {
+                        executeMap.set(name, def.execute);
+                        toolSchemas.push({
+                            type: 'function',
+                            function: { name, description: def.description, parameters: def.parameters },
+                        });
+                    }
+                }
+                else if (Array.isArray(options.tools)) {
+                    toolSchemas = options.tools;
+                }
+                // Build request body (exclude execute functions)
+                const body = { ...options, tools: toolSchemas };
+                // Tool execution loop
+                let maxRounds = 20;
+                while (maxRounds-- > 0) {
+                    const response = await this.client.post('/api/v1/responses', body);
+                    const result = response.data;
+                    if (result.status === 'completed') {
+                        return result;
+                    }
+                    // requires_action — execute tools locally
+                    if (!executeMap || executeMap.size === 0) {
+                        // No execute functions provided — return as-is (caller handles manually)
+                        return result;
+                    }
+                    const toolResults = [];
+                    for (const tc of result.required_action.tool_calls) {
+                        const executeFn = executeMap.get(tc.name);
+                        if (!executeFn) {
+                            toolResults.push({ tool_call_id: tc.id, output: JSON.stringify({ error: `No execute function for tool: ${tc.name}` }) });
+                            continue;
+                        }
+                        try {
+                            const output = await executeFn(tc.args);
+                            toolResults.push({ tool_call_id: tc.id, output: typeof output === 'string' ? output : JSON.stringify(output) });
+                        }
+                        catch (err) {
+                            toolResults.push({ tool_call_id: tc.id, output: JSON.stringify({ error: err.message }) });
+                        }
+                    }
+                    // Send continuation request
+                    body.conversation = result.conversation;
+                    body.conversation_signature = result.conversation_signature;
+                    body.remaining_steps = result.remaining_steps;
+                    body.completed_step_count = result.completed_step_count;
+                    body.tool_results = toolResults;
+                }
+                throw new Error('Tool execution loop exceeded maximum rounds (20)');
+            },
+        };
+        this.chat = {
+            completions: {
+                /**
+                 * POST /api/v1/chat/completions — OpenAI-compatible chat completion.
+                 */
+                create: async (options) => {
+                    const response = await this.client.post('/api/v1/chat/completions', options);
+                    return response.data;
+                },
+            },
+        };
         this.maxRetries = config.maxRetries ?? 3;
         this.retryDelay = config.retryDelay ?? 1000;
         this.client = axios_1.default.create({

package/dist/types.d.ts

@@ -760,6 +760,10 @@ export interface SmartRecallOptions {
     recency_half_life_days?: number;
     /** Metadata filters for narrowing results. */
     filters?: Record<string, unknown>;
+    /** Group results by record. Returns recordGroups array alongside flat results. */
+    groupByRecord?: boolean;
+    /** Alias for groupByRecord. */
+    group_by_record?: boolean;
 }
 /** @deprecated Use SmartRecallOptions instead. */
 export type RecallProOptions = SmartRecallOptions;
@@ -802,6 +806,10 @@ export interface RecallOptions {
     collectionName?: string;
     /** Compatibility alias for collection scoping by name. */
     collectionNames?: string[];
+    /** Group results by record. Returns recordGroups array alongside flat results. */
+    groupByRecord?: boolean;
+    /** Alias for groupByRecord. */
+    group_by_record?: boolean;
 }
 export interface RecallResultItem {
     content?: string;
@@ -1371,3 +1379,351 @@ export interface EvaluateMemorizationResponse {
         propertiesAttempted: number;
     };
 }
+export interface StepDefinition {
+    prompt: string;
+    order?: number;
+    tools?: string[];
+    max_steps?: number;
+}
+export interface PersonizeExtensions {
+    governance?: {
+        guideline_ids?: string[];
+        mode?: 'fast' | 'deep';
+    };
+    memory?: {
+        record_id?: string;
+        recall?: boolean;
+    };
+    mcp_integration_ids?: string[];
+    outputs?: Array<{
+        key: string;
+        type: string;
+    }>;
+    memorize?: {
+        record_id?: string;
+        collection?: string;
+        capture_tool_results?: boolean;
+    };
+}
+export interface ClientToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+export interface ResponsesCreateOptions {
+    steps?: StepDefinition[];
+    messages?: Array<{
+        role: string;
+        content: string;
+    }>;
+    tools?: ClientToolDefinition[] | Record<string, {
+        description: string;
+        parameters: Record<string, unknown>;
+        execute: (args: any) => Promise<any>;
+    }>;
+    model?: string;
+    provider?: string;
+    tier?: string;
+    temperature?: number;
+    max_tokens?: number;
+    system_prompt?: string;
+    session_id?: string;
+    llm_api_key?: string;
+    openrouter_api_key?: string;
+    personize?: PersonizeExtensions;
+    attachments?: Array<{
+        name: string;
+        mimeType: string;
+        url?: string;
+        content?: string;
+    }>;
+    conversation?: any[];
+    conversation_signature?: string;
+    remaining_steps?: StepDefinition[];
+    completed_step_count?: number;
+}
+export interface ResponsesToolCall {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+export interface ResponsesStepResult {
+    order: number;
+    text: string;
+    tool_calls: Array<{
+        name: string;
+        args: Record<string, unknown>;
+        result?: unknown;
+    }>;
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+    };
+}
+export interface ResponsesCompletedResult {
+    id: string;
+    status: 'completed';
+    session_id: string;
+    output: Array<{
+        type: string;
+        role: string;
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+    }>;
+    steps: ResponsesStepResult[];
+    outputs?: Record<string, unknown>;
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+    metadata: {
+        tier: string;
+        credits_charged: number;
+        byok?: boolean;
+        model?: string;
+        provider?: string;
+    };
+}
+export interface ResponsesRequiresActionResult {
+    id: string;
+    status: 'requires_action';
+    session_id: string;
+    required_action: {
+        type: 'tool_calls';
+        tool_calls: ResponsesToolCall[];
+    };
+    conversation: any[];
+    remaining_steps: StepDefinition[];
+    completed_step_count: number;
+    conversation_signature: string;
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+export type ResponsesResult = ResponsesCompletedResult | ResponsesRequiresActionResult;
+export interface ChatCompletionsOptions {
+    model?: string;
+    provider?: string;
+    tier?: string;
+    messages: Array<{
+        role: 'system' | 'user' | 'assistant' | 'tool';
+        content: string | null;
+        tool_call_id?: string;
+        tool_calls?: any[];
+    }>;
+    tools?: ClientToolDefinition[];
+    tool_choice?: 'auto' | 'none' | 'required';
+    temperature?: number;
+    max_tokens?: number;
+    llm_api_key?: string;
+    openrouter_api_key?: string;
+    personize?: PersonizeExtensions;
+}
+export interface ChatCompletionChoice {
+    index: number;
+    message: {
+        role: 'assistant';
+        content: string | null;
+        tool_calls?: Array<{
+            id: string;
+            type: 'function';
+            function: {
+                name: string;
+                arguments: string;
+            };
+        }>;
+    };
+    finish_reason: 'stop' | 'tool_calls' | 'length';
+}
+export interface ChatCompletionResult {
+    id: string;
+    object: 'chat.completion';
+    created: number;
+    model: string;
+    choices: ChatCompletionChoice[];
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+    session_id?: string;
+    metadata?: {
+        tier: string;
+        credits_charged: number;
+        byok?: boolean;
+    };
+}
+/** Options for POST /api/v1/similar -- find records similar to a seed record. */
+export interface SimilarOptions {
+    /** Seed record identifier. Provide exactly one: recordId, email, websiteUrl, or customKey. */
+    seed: {
+        recordId?: string;
+        email?: string;
+        websiteUrl?: string;
+        customKeyName?: string;
+        customKeyValue?: string;
+    };
+    /** Seed entity type. Inferred from seed key if omitted (email -> contact, websiteUrl -> company). */
+    type?: string;
+    /** What dimensions drive similarity. Default: 'hybrid'. */
+    dimensions?: 'properties' | 'memories' | 'hybrid' | 'connections';
+    /** Fine-tune which properties/connections matter. */
+    dimensionFilters?: {
+        propertyNames?: string[];
+        collectionIds?: string[];
+        systemNames?: string[];
+        keywords?: string[];
+        entities?: string[];
+    };
+    /** Scoring mode. Default: 'balanced'. */
+    rankingMode?: 'balanced' | 'weighted';
+    /** Dimension weights. Only used with rankingMode: 'weighted'. */
+    weights?: {
+        properties?: number;
+        memories?: number;
+    };
+    /** Scope search to specific candidates. */
+    candidatePool?: {
+        recordIds?: string[];
+        type?: string;
+        collectionIds?: string[];
+    };
+    /** Max results per page (default: 25, max: 500). */
+    topK?: number;
+    /** Pagination offset (default: 0). */
+    offset?: number;
+    /** Min similarity threshold (default: 0.3). */
+    minScore?: number;
+    /** Include tier arrays in response (default: true). */
+    includeTiers?: boolean;
+    /** Override tier thresholds. */
+    tierThresholds?: {
+        very_similar?: number;
+        similar?: number;
+    };
+    /** Max matched snippets per result (default: 3, max: 5). */
+    maxSnippetsPerResult?: number;
+    /** Batch mode: return flat list of all matching recordIds (default: false). */
+    returnAllIds?: boolean;
+}
+export interface SimilarResult {
+    recordId: string;
+    type: string;
+    score: number;
+    tier: 'very_similar' | 'similar' | 'somewhat_similar';
+    matchBreakdown: {
+        propertiesScore: number | null;
+        memoriesScore: number | null;
+        connectionsScore: number | null;
+        matchedProperties: {
+            name: string;
+            value: string;
+            similarity: number;
+        }[];
+        matchedMemorySnippets: {
+            seedSnippet: string;
+            matchSnippet: string;
+            score: number;
+        }[];
+        sharedConnections: {
+            persons: string[];
+            entities: string[];
+            keywords: string[];
+        } | null;
+    };
+}
+export interface SimilarResponse {
+    seed: {
+        recordId: string;
+        type: string;
+        label: string;
+        vectorsUsed: number;
+    };
+    results?: SimilarResult[];
+    tiers?: Record<string, string[]>;
+    allIds?: {
+        recordId: string;
+        score: number;
+        tier: string;
+    }[];
+    tierSummary?: Record<string, number>;
+    totalMatches: number;
+    metadata: Record<string, unknown>;
+    warning?: string;
+    usage: {
+        credits: number;
+    };
+}
+/** Options for POST /api/v1/segment -- bucket records into similarity tiers. */
+export interface SegmentOptions {
+    /** Seed: record identifier OR text. Text creates a text-based seed. */
+    seed: {
+        recordId?: string;
+        email?: string;
+        websiteUrl?: string;
+        customKeyName?: string;
+        customKeyValue?: string;
+        /** Free-form text seed (e.g., "Enterprise SaaS CTO"). Segment only. */
+        text?: string;
+    };
+    /** Entity type (default: 'contact'). */
+    type?: string;
+    /** What dimensions drive similarity. Default: 'hybrid'. No 'connections' for segment. */
+    dimensions?: 'properties' | 'memories' | 'hybrid';
+    /** Fine-tune which properties matter. */
+    dimensionFilters?: {
+        propertyNames?: string[];
+        collectionIds?: string[];
+        systemNames?: string[];
+    };
+    /** Scope to candidate records. */
+    candidatePool?: {
+        type?: string;
+        collectionIds?: string[];
+    };
+    /** Override tier thresholds. */
+    tierThresholds?: {
+        very_similar?: number;
+        similar?: number;
+    };
+    /** Min similarity threshold (default: 0.3). */
+    minScore?: number;
+    /** Max recordIds per tier page (default: 50, max: 500). */
+    maxPerTier?: number;
+    /** Skip N recordIds per tier for pagination (default: 0). */
+    tierOffset?: number;
+    /** Fetch only one tier. */
+    returnTier?: 'very_similar' | 'similar' | 'somewhat_similar';
+}
+export interface SegmentTier {
+    count: number;
+    recordIds: string[];
+    scoreRange: {
+        min: number;
+        max: number;
+    };
+    hasMore: boolean;
+    approximate?: boolean;
+}
+export interface SegmentResponse {
+    seed: {
+        recordId: string | null;
+        type: string;
+        label: string;
+        vectorsUsed: number;
+    };
+    tiers: Record<string, SegmentTier>;
+    totalRecords: number;
+    metadata: Record<string, unknown>;
+    usage: {
+        credits: number;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@personize/sdk",
-    "version": "0.6.6",
+    "version": "0.7.1",
     "description": "Official Personize SDK",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",