@personize/sdk 0.7.0 → 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, ResponsesCreateOptions, ResponsesCompletedResult, ChatCompletionsOptions, ChatCompletionResult } 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: {
         /**

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 = {
             /**

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;
@@ -1553,3 +1561,169 @@ export interface ChatCompletionResult {
         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.7.0",
+    "version": "0.7.1",
     "description": "Official Personize SDK",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",