@personize/sdk 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # Personize SDK
 
-The official Node.js/TypeScript SDK for the Personize Product API. Authenticate with your secret key to access variables, smart context, RAG memory, prompt execution, and agents.
+The official Node.js/TypeScript SDK for the Personize Product API. Authenticate with your secret key to access variables, smart context, RAG memory, prompt execution, agents, and evaluation tools.
 
 ## Installation
 
@@ -18,7 +18,11 @@ const client = new Personize({
     // baseURL: 'http://localhost:3000' // Optional: for local development
 });
 
-// Verify auth and read plan limits
+// Verify API key
+const testResult = await client.test();
+console.log(testResult.data.organizationId);
+
+// Read plan limits
 const me = await client.me();
 console.log(me.data.plan.name);
 console.log(me.data.plan.limits);
@@ -28,25 +32,41 @@ console.log(me.data.plan.limits);
 
 | Method | Path | SDK Method |
 | :--- | :--- | :--- |
+| **Identity** | | |
+| GET | `/api/v1/test` | `client.test()` |
 | GET | `/api/v1/me` | `client.me()` |
+| **AI** | | |
+| POST | `/api/v1/ai/smart-context` | `client.ai.smartContext(opts)` |
+| POST | `/api/v1/prompt` | `client.ai.prompt(opts)` |
+| **Memory** | | |
+| POST | `/api/v1/memorize` | `client.memory.memorize(opts)` |
+| POST | `/api/v1/smart-recall` | `client.memory.smartRecall(opts)` |
+| POST | `/api/v1/recall` | `client.memory.recall(opts)` |
+| POST | `/api/v1/search` | `client.memory.search(opts)` |
+| POST | `/api/v1/upsert` | `client.memory.upsert(opts)` |
+| POST | `/api/v1/upsert` | `client.memory.upsertBatch(opts)` |
+| POST | `/api/v1/batch-memorize` | `client.memory.memorizeBatch(opts)` |
+| POST | `/api/v1/smart-memory-digest` | `client.memory.smartDigest(opts)` |
+| **Variables** | | |
 | GET | `/api/v1/variables` | `client.variables.list()` |
+| POST | `/api/v1/variables` | `client.variables.create(payload)` |
 | GET | `/api/v1/variables/:id/structure` | `client.variables.getStructure(id)` |
 | GET | `/api/v1/variables/:id/section` | `client.variables.getSection(id, opts)` |
 | PATCH | `/api/v1/variables/:id` | `client.variables.update(id, payload)` |
-| POST | `/api/v1/variables` | `client.variables.create(payload)` |
 | DELETE | `/api/v1/variables/:id` | `client.variables.delete(id)` |
+| GET | `/api/v1/actions/:id/history` | `client.variables.history(id)` |
+| **Collections** | | |
 | GET | `/api/v1/collections` | `client.collections.list()` |
-| POST | `/api/v1/ai/smart-context` | `client.ai.smartContext(opts)` |
-| POST | `/api/v1/prompt` | `client.ai.prompt(opts)` |
+| POST | `/api/v1/collections` | `client.collections.create(payload)` |
+| PATCH | `/api/v1/collections/:id` | `client.collections.update(id, payload)` |
+| DELETE | `/api/v1/collections/:id` | `client.collections.delete(id)` |
+| GET | `/api/v1/collections/:id/history` | `client.collections.history(id)` |
+| **Agents** | | |
 | GET | `/api/v1/agents` | `client.agents.list()` |
+| GET | `/api/v1/agents/:id` | `client.agents.get(id)` |
 | POST | `/api/v1/agents/:id/run` | `client.agents.run(id, opts)` |
-| POST | `/api/v1/memorize_pro` | `client.memory.memorize(opts)` |
-| POST | `/api/v1/batch-memorize` | `client.memory.memorizeBatch(opts)` |
-| POST | `/api/v1/recall_pro` | `client.memory.recall(opts)` |
-| POST | `/api/v1/export` | `client.memory.export(opts)` |
-| POST | `/api/v1/smart-memory-digest` | `client.memory.smartDigest(opts)` |
-| POST | `/api/v1/upsert` | `client.memory.upsert(opts)` |
-| POST | `/api/v1/upsert` | `client.memory.upsertBatch(opts)` |
+| **Evaluation** | | |
+| POST | `/api/v1/evaluate/memorization-accuracy` | `client.evaluate.memorizationAccuracy(opts)` |
 
 All endpoints require `Authorization: Bearer sk_live_...` and count against your plan limits.
 
@@ -72,6 +92,9 @@ const section = await client.variables.getSection(variableId, { header: '## Pric
 
 // Delete a variable
 await client.variables.delete(variableId);
+
+// Version history
+const history = await client.variables.history(variableId, { limit: 5 });
 ```
 
 ### Smart Context
@@ -81,6 +104,7 @@ const ctx = await client.ai.smartContext({
     message: 'Write a sales sequence for our top 3 ICPs',
     tags: ['sales'],
     excludeTags: ['internal'],
+    sessionId: 'my-session', // for incremental context delivery
 });
 console.log(ctx.data.compiledContext);
 ```
@@ -102,6 +126,23 @@ const result = await client.ai.prompt({
     evaluate: { criteria: 'sales', serverSide: true },
 });
 
+// Multimodal — image analysis
+const analysis = await client.ai.prompt({
+    prompt: 'Describe what you see in this screenshot.',
+    attachments: [
+        { name: 'dashboard.png', mimeType: 'image/png', data: base64EncodedImage },
+    ],
+    model: 'anthropic/claude-sonnet-4-20250514',
+});
+
+// Multimodal — PDF extraction via URL
+const extraction = await client.ai.prompt({
+    prompt: 'Extract the key terms from this contract.',
+    attachments: [
+        { name: 'contract.pdf', mimeType: 'application/pdf', url: 'https://your-bucket.s3.amazonaws.com/contract.pdf' },
+    ],
+});
+
 // Output extraction + auto-memorize
 const research = await client.ai.prompt({
     instructions: [
@@ -128,7 +169,7 @@ console.log(research.data?.evaluation?.finalScore);
 ### Memory (RAG)
 
 ```typescript
-// Memorize content
+// Memorize content (dual extraction: structured + free-form)
 await client.memory.memorize({
     content: 'Meeting notes: John prefers email contact.',
     speaker: 'Sales Rep',
@@ -137,19 +178,32 @@ await client.memory.memorize({
     email: 'john@example.com',
 });
 
-// Recall memories
-const results = await client.memory.recall({
+// Smart recall — advanced recall with reflection
+const results = await client.memory.smartRecall({
     query: 'What does John prefer?',
     limit: 5,
     minScore: 0.7,
+    enable_reflection: true,
+    generate_answer: true,
 });
 
-// Export/filter records
-const exported = await client.memory.export({
+// Fast recall — low-latency mode (~500ms)
+const fast = await client.memory.smartRecall({
+    query: 'contact info for John',
+    email: 'john@example.com',
+    fast_mode: true,
+});
+
+// Direct recall — simple memory lookup (no reflection)
+const direct = await client.memory.recall({
+    query: 'What do we know about Acme?',
+    email: 'john@acme.com',
+});
+
+// Search/filter records by property conditions
+const found = await client.memory.search({
     groups: [{
-        id: 'g1',
-        logic: 'AND',
-        conditions: [{ field: 'Company', operator: 'EQ', value: 'Acme Corp' }],
+        conditions: [{ property: 'company-name', operator: 'equals', value: 'Acme Corp' }],
     }],
     returnRecords: true,
     pageSize: 50,
@@ -180,7 +234,7 @@ const digest = await client.memory.smartDigest({
 });
 console.log(digest.data?.compiledContext); // ready-to-use markdown for LLM prompts
 
-// Structured upsert — legacy, no AI extraction
+// Structured upsert — no AI extraction
 await client.memory.upsert({
     type: 'Contact',
     properties: {
@@ -195,10 +249,16 @@ await client.memory.upsert({
 ### Agents
 
 ```typescript
+// List agents
 const agents = await client.agents.list();
 
+// Get agent details and expected inputs
+const agent = await client.agents.get(agentId);
+console.log(agent.data.expectedInputs); // ['companyName', 'industry']
+
+// Run an agent
 const result = await client.agents.run(agentId, {
-    inputs: { userMessage: 'Help with onboarding' },
+    inputs: { companyName: 'Acme Corp', industry: 'SaaS' },
     email: 'customer@example.com',
 });
 ```
@@ -206,7 +266,40 @@ const result = await client.agents.run(agentId, {
 ### Collections
 
 ```typescript
+// List collections
 const collections = await client.collections.list();
+
+// Create a collection
+await client.collections.create({
+    collectionName: 'Deal Properties',
+    entityType: 'Contact',
+    properties: [
+        { propertyName: 'Deal Stage', type: 'options', options: 'Discovery,Proposal,Closed' },
+    ],
+});
+
+// Update a collection
+await client.collections.update(collectionId, {
+    properties: [{ propertyName: 'Budget', type: 'number', description: 'Estimated budget' }],
+});
+
+// Delete a collection
+await client.collections.delete(collectionId);
+
+// Version history (full snapshots or compact diffs)
+const history = await client.collections.history(collectionId, { mode: 'diff', limit: 10 });
+```
+
+### Evaluation
+
+```typescript
+// Run memorization accuracy evaluation against a collection
+const evaluation = await client.evaluate.memorizationAccuracy({
+    collectionId: 'col_123',
+    input: 'John Smith is VP of Sales at Acme Corp, based in NYC.',
+    skipStorage: true,
+});
+console.log(evaluation.data.summary.propertiesOptimized);
 ```
 
 ## Configuration
@@ -215,6 +308,9 @@ const collections = await client.collections.list();
 | :--- | :--- | :--- | :--- |
 | `secretKey` | string | Yes | Your secret key (`sk_live_...`). |
 | `baseURL` | string | No | Custom API endpoint (default: `https://api.personize.ai`). |
+| `timeout` | number | No | Request timeout in ms (default: `30000`). |
+| `maxRetries` | number | No | Max retry attempts for 429/5xx errors (default: `3`). |
+| `retryDelay` | number | No | Base delay in ms for exponential backoff (default: `1000`). |
 
 ## Test Key (Local Development)
 
@@ -225,6 +321,29 @@ const client = new Personize({
 });
 ```
 
+## Migration from 0.3.x
+
+**Breaking changes in 0.4.0:**
+
+| 0.3.x | 0.4.0 | Notes |
+| :--- | :--- | :--- |
+| `client.memory.recall(opts)` | `client.memory.smartRecall(opts)` | Advanced recall with reflection (route changed to `/smart-recall`) |
+| `client.memory.export(opts)` | `client.memory.search(opts)` | Filter/search records (route changed to `/search`) |
+| `MemorizeProOptions` | `MemorizeOptions` | Type renamed (old name still available as deprecated alias) |
+| `RecallProOptions` | `SmartRecallOptions` | Type renamed (old name still available as deprecated alias) |
+| `ExportOptions` / `ExportResponse` | `SearchOptions` / `SearchResponse` | Types renamed (old names still available as deprecated aliases) |
+
+**New in 0.4.0:**
+- `client.test()` — Verify API key validity
+- `client.agents.get(id)` — Get agent details and expected inputs
+- `client.memory.recall(opts)` — Direct memory lookup (no reflection, low latency)
+- `client.memory.search(opts)` — Search/filter records with `property`-based conditions
+- `client.evaluate.memorizationAccuracy(opts)` — Three-phase memorization evaluation
+- `attachments` on `PromptOptions` — Multimodal support (images, PDFs, documents)
+- `sessionId` on `SmartContextOptions` — Progressive context delivery across multi-step workflows
+- New fields on `MemorizeOptions`: `collectionIds`, `skipStorage`, `skipDualWrite`, `skipPropertySelection`
+- New fields on `SmartRecallOptions`: `max_reflection_rounds`, `filters`
+
 ## Skills
 
 The SDK ships with AI-assistant skills in `skills/` that teach Claude Code, Codex, and Cursor how to use the SDK for common workflows.

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { PersonizeConfig, ApiResponse, MeResponse, ListOptions, VariablesResponse, VariableSectionOptions, VariableUpdatePayload, VariableCreatePayload, VariableHistoryResponse, VariableHistoryOptions, CollectionsResponse, CollectionCreatePayload, CollectionUpdatePayload, CollectionHistoryOptions, CollectionHistoryResponse, SmartContextOptions, SmartContextResponse, PromptOptions, PromptResponse, AgentRunOptions, MemorizeProOptions, RecallProOptions, ExportOptions, ExportResponse, UpsertOptions, UpsertBatchOptions, BatchMemorizeOptions, SmartDigestOptions, SmartDigestResponse } from './types';
+import { PersonizeConfig, ApiResponse, MeResponse, TestResponse, ListOptions, VariablesResponse, VariableSectionOptions, VariableUpdatePayload, VariableCreatePayload, VariableHistoryResponse, VariableHistoryOptions, CollectionsResponse, CollectionCreatePayload, CollectionUpdatePayload, CollectionHistoryOptions, CollectionHistoryResponse, SmartContextOptions, SmartContextResponse, PromptOptions, PromptResponse, AgentRunOptions, AgentResponse, MemorizeOptions, SmartRecallOptions, RecallOptions, SearchOptions, SearchResponse, UpsertOptions, UpsertBatchOptions, BatchMemorizeOptions, SmartDigestOptions, SmartDigestResponse, EvaluateMemorizationOptions, EvaluateMemorizationResponse } from './types';
 export declare class Personize {
     private client;
     private _organizationId?;
@@ -8,6 +8,10 @@ export declare class Personize {
     constructor(config: PersonizeConfig);
     private resolveIdentity;
     private getOrganizationId;
+    /**
+     * GET /api/v1/test — Verify API key is valid. Returns request metadata and resolved identity.
+     */
+    test(): Promise<ApiResponse<TestResponse>>;
     /**
      * GET /api/v1/me — Current context (org, user, plan)
      */
@@ -88,6 +92,10 @@ export declare class Personize {
          * Pass `limit` and `nextToken` for cursor-based pagination.
          */
         list: (options?: ListOptions) => Promise<ApiResponse>;
+        /**
+         * GET /api/v1/agents/:id — Get agent details and expected inputs.
+         */
+        get: (id: string) => Promise<ApiResponse<AgentResponse>>;
         /**
          * POST /api/v1/agents/:id/run — Run an agent
          */
@@ -95,17 +103,24 @@ export declare class Personize {
     };
     memory: {
         /**
-         * POST /api/v1/memorize_pro — Advanced memorization (RAG)
+         * POST /api/v1/memorize — Advanced memorization with dual extraction (RAG).
+         * Performs structured property extraction and free-form memory creation.
          */
-        memorize: (data: MemorizeProOptions) => Promise<ApiResponse>;
+        memorize: (data: MemorizeOptions) => Promise<ApiResponse>;
         /**
-         * POST /api/v1/recall_pro — Advanced recall with reflection (RAG)
+         * POST /api/v1/smart-recall — Advanced recall with reflection (RAG).
+         * Supports reflection loops for improved coverage, answer generation, and entity scoping.
          */
-        recall: (data: RecallProOptions) => Promise<ApiResponse>;
+        smartRecall: (data: SmartRecallOptions) => Promise<ApiResponse>;
         /**
-         * POST /api/v1/export — Filter and export records
+         * POST /api/v1/recall — Direct memory lookup (no reflection).
          */
-        export: (data: ExportOptions) => Promise<ApiResponse<ExportResponse>>;
+        recall: (data: RecallOptions) => Promise<ApiResponse>;
+        /**
+         * POST /api/v1/search — Filter and search records by property conditions.
+         * Returns matching record IDs with optional property values and memories.
+         */
+        search: (data: SearchOptions) => Promise<ApiResponse<SearchResponse>>;
         /**
          * POST /api/v1/upsert — Structured upsert (no AI extraction)
          */
@@ -126,4 +141,11 @@ export declare class Personize {
          */
         smartDigest: (data: SmartDigestOptions) => Promise<ApiResponse<SmartDigestResponse>>;
     };
+    evaluate: {
+        /**
+         * POST /api/v1/evaluate/memorization-accuracy — Run memorization accuracy evaluation.
+         * Three-phase evaluation: extraction → analysis → schema optimization.
+         */
+        memorizationAccuracy: (data: EvaluateMemorizationOptions) => Promise<ApiResponse<EvaluateMemorizationResponse>>;
+    };
 }

package/dist/client.js

@@ -180,6 +180,13 @@ class Personize {
                 const response = await this.client.get('/api/v1/agents', { params });
                 return response.data;
             },
+            /**
+             * GET /api/v1/agents/:id — Get agent details and expected inputs.
+             */
+            get: async (id) => {
+                const response = await this.client.get(`/api/v1/agents/${id}`);
+                return response.data;
+            },
             /**
              * POST /api/v1/agents/:id/run — Run an agent
              */
@@ -190,24 +197,34 @@ class Personize {
         };
         this.memory = {
             /**
-             * POST /api/v1/memorize_pro — Advanced memorization (RAG)
+             * POST /api/v1/memorize — Advanced memorization with dual extraction (RAG).
+             * Performs structured property extraction and free-form memory creation.
              */
             memorize: async (data) => {
-                const response = await this.client.post('/api/v1/memorize_pro', data);
+                const response = await this.client.post('/api/v1/memorize', data);
                 return response.data;
             },
             /**
-             * POST /api/v1/recall_pro — Advanced recall with reflection (RAG)
+             * POST /api/v1/smart-recall — Advanced recall with reflection (RAG).
+             * Supports reflection loops for improved coverage, answer generation, and entity scoping.
+             */
+            smartRecall: async (data) => {
+                const response = await this.client.post('/api/v1/smart-recall', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/recall — Direct memory lookup (no reflection).
              */
             recall: async (data) => {
-                const response = await this.client.post('/api/v1/recall_pro', data);
+                const response = await this.client.post('/api/v1/recall', data);
                 return response.data;
             },
             /**
-             * POST /api/v1/export — Filter and export records
+             * POST /api/v1/search — Filter and search records by property conditions.
+             * Returns matching record IDs with optional property values and memories.
              */
-            export: async (data) => {
-                const response = await this.client.post('/api/v1/export', data);
+            search: async (data) => {
+                const response = await this.client.post('/api/v1/search', data);
                 return response.data;
             },
             /**
@@ -255,6 +272,16 @@ class Personize {
                 return response.data;
             },
         };
+        this.evaluate = {
+            /**
+             * POST /api/v1/evaluate/memorization-accuracy — Run memorization accuracy evaluation.
+             * Three-phase evaluation: extraction → analysis → schema optimization.
+             */
+            memorizationAccuracy: async (data) => {
+                const response = await this.client.post('/api/v1/evaluate/memorization-accuracy', data);
+                return response.data;
+            },
+        };
         this.maxRetries = config.maxRetries ?? 3;
         this.retryDelay = config.retryDelay ?? 1000;
         this.client = axios_1.default.create({
@@ -307,6 +334,13 @@ class Personize {
         const { organizationId } = await this.resolveIdentity();
         return organizationId;
     }
+    /**
+     * GET /api/v1/test — Verify API key is valid. Returns request metadata and resolved identity.
+     */
+    async test() {
+        const response = await this.client.get('/api/v1/test');
+        return response.data;
+    }
     /**
      * GET /api/v1/me — Current context (org, user, plan)
      */

package/dist/types.d.ts

@@ -223,6 +223,8 @@ export interface SmartContextOptions {
     mode?: 'fast' | 'full' | 'auto';
     /** Minimum cosine similarity score (0-1) for fast mode results. Lower values return more results. Default: 0.4 for supplementary, 0.7 for critical. */
     minScore?: number;
+    /** Session ID for conversation continuity. */
+    sessionId?: string;
 }
 export interface SmartContextAnalysis {
     taskUnderstanding: string;
@@ -301,6 +303,17 @@ export interface PromptOutputDefinition {
     /** Unique name for this output (used in <output name="..."> markers). */
     name: string;
 }
+/** Multimodal attachment for prompt requests (images, PDFs, documents). */
+export interface PromptAttachment {
+    /** Filename (e.g. 'screenshot.png'). Max 255 chars. */
+    name?: string;
+    /** MIME type. Supported: image/png, image/jpeg, image/gif, image/webp, image/svg+xml, application/pdf, text/plain, text/csv, text/html, text/markdown, application/json. */
+    mimeType: string;
+    /** Base64-encoded content. Required if url is not provided. */
+    data?: string;
+    /** Public URL to the content. Required if data is not provided. */
+    url?: string;
+}
 export interface PromptOptions {
     prompt?: string;
     instructions?: Array<string | {
@@ -312,6 +325,12 @@ export interface PromptOptions {
     provider?: string;
     context?: string;
     sessionId?: string;
+    /**
+     * Multimodal attachments (images, PDFs, documents).
+     * Max 10 attachments, 20 MB per attachment, 50 MB total.
+     * In multi-step mode, attachments are sent with the first instruction only.
+     */
+    attachments?: PromptAttachment[];
     /**
      * Evaluation configuration.
      * - `true` — server-side auto-evaluation with default criteria
@@ -359,14 +378,27 @@ export interface PromptResponse {
             completionTokens: number;
             totalTokens: number;
         };
+        /** Tool calls made during execution (name + args). */
         toolCalls?: Array<{
             toolName: string;
+            args?: Record<string, unknown>;
         }>;
+        /** Tool call return values (name + result). Always present regardless of captureToolResults. */
+        toolResults?: Array<{
+            toolName: string;
+            result: unknown;
+        }>;
+        /** Number of AI SDK steps (simple mode). */
         stepsExecuted?: number;
+        /** Number of instruction steps executed (multi-step mode). */
         instructionsExecuted?: number;
     };
+    /** Per-step breakdown (multi-step mode only). */
     steps?: Array<{
         instructionIndex: number;
+        /** Instruction prompt that was executed. */
+        prompt: string;
+        /** Raw response text for this step (may include <output> markers). */
         text: string;
         usage?: {
             promptTokens: number;
@@ -375,10 +407,34 @@ export interface PromptResponse {
         };
         toolCalls?: Array<{
             toolName: string;
+            args?: Record<string, unknown>;
         }>;
         stepsExecuted: number;
     }>;
 }
+export interface TestResponse {
+    timestamp: string;
+    ip: string;
+    userAgent: string;
+    userId: string;
+    organizationId: string;
+}
+export interface AgentInstructionStep {
+    prompt: string;
+    order: number;
+}
+export interface AgentResponse {
+    id: string;
+    type: string;
+    payload: {
+        name: string;
+        instructions: AgentInstructionStep[];
+        actions: Array<Record<string, unknown>>;
+        aiConfig?: Record<string, unknown>;
+    };
+    /** Variable names extracted from {{placeholder}} tokens in the agent's instructions. */
+    expectedInputs: string[];
+}
 export interface AgentRunOptions {
     inputs?: Record<string, unknown>;
     stream?: boolean;
@@ -388,29 +444,62 @@ export interface AgentRunOptions {
     /** Per-MCP tool selection override (allowlist or denylist per MCP) */
     mcpTools?: McpToolSelection[];
 }
-export interface MemorizeProOptions {
+export interface MemorizeOptions {
+    /** Content to memorize. */
     content: string;
+    /** Speaker/source label. */
     speaker?: string;
+    /** Timestamp of the content. */
     timestamp?: string;
+    /** Schema hint for extraction. */
     schema?: Record<string, unknown>;
+    /** Action ID for linking. */
     actionId?: string;
+    /** CRM record ID for entity scoping. */
     record_id?: string;
+    /** Email for CRM linking. */
     email?: string;
+    /** Website URL for CRM linking. */
     website_url?: string;
+    /** Enable enhanced dual extraction (structured + free-form). */
     enhanced?: boolean;
+    /** Tags for property selection. */
     tags?: string[];
+    /** Limit extraction to specific collections. */
+    collectionIds?: string[];
+    /** Max properties to select for extraction. */
     max_properties?: number;
-}
-export interface RecallProOptions {
+    /** If true, extract without persisting (dry run). */
+    skipStorage?: boolean;
+    /** If true, skip the secondary write path. */
+    skipDualWrite?: boolean;
+    /** If true, skip property selection step. */
+    skipPropertySelection?: boolean;
+}
+/** @deprecated Use MemorizeOptions instead. */
+export type MemorizeProOptions = MemorizeOptions;
+export interface SmartRecallOptions {
+    /** Natural-language query. */
     query: string;
+    /** Max results to return (default: 10). */
     limit?: number;
+    /** Minimum similarity score threshold. */
     minScore?: number;
+    /** CRM record ID for entity scoping. */
     record_id?: string;
+    /** Filter results to a specific entity by email. */
     email?: string;
+    /** Website URL for entity scoping. */
     website_url?: string;
+    /** Entity type filter (e.g. 'Contact', 'Company'). */
     type?: string;
+    /** Return schema-enforced property values separately from free-form memories. */
     include_property_values?: boolean;
+    /** Enable reflection loop to improve recall coverage (default: true). */
     enable_reflection?: boolean;
+    /** Maximum reflection iterations (default: 2). Only used when enable_reflection is true. */
+    max_reflection_rounds?: number;
+    /** Generate a synthesized answer from recalled memories. */
     generate_answer?: boolean;
     /**
      * Fast mode: skip reflection loop and answer generation, use minScore 0.3,
@@ -423,6 +512,22 @@ export interface RecallProOptions {
      * In fast_mode, defaults to 0.3 if not specified.
      */
     min_score?: number;
+    /** Metadata filters for narrowing results. */
+    filters?: Record<string, unknown>;
+}
+/** @deprecated Use SmartRecallOptions instead. */
+export type RecallProOptions = SmartRecallOptions;
+export interface RecallOptions {
+    /** Natural-language query. */
+    query: string;
+    /** CRM record ID for entity scoping. */
+    record_id?: string;
+    /** Filter results to a specific entity by email. */
+    email?: string;
+    /** Website URL for entity scoping. */
+    website_url?: string;
+    /** Additional filters. */
+    filters?: Record<string, unknown>;
 }
 export interface UpsertOptions {
     /** Entity type (e.g. 'Contact', 'Company') */
@@ -524,44 +629,130 @@ export interface SmartDigestResponse {
     tokenEstimate: number;
     tokenBudget: number;
 }
-export interface ExportOptions {
-    groups?: Array<{
-        id: string;
-        logic: 'AND' | 'OR';
-        conditions: Array<{
-            field: string;
-            operator: string;
-            value?: PropertyValue;
-            collectionId?: string;
-        }>;
-    }>;
+export interface SearchFilterCondition {
+    /** Property system name to filter on. */
+    property: string;
+    /** Comparison operator (e.g. 'equals', 'contains', 'gt', 'lt'). */
+    operator: string;
+    /** Value to compare against. */
+    value?: PropertyValue;
+    /** Scope to a specific collection. */
+    collectionId?: string;
+}
+export interface SearchFilterGroup {
+    /** Filter conditions within this group. */
+    conditions: SearchFilterCondition[];
+}
+export interface SearchOptions {
+    /** Filter groups with conditions. To list all records, send one group with empty conditions. */
+    groups?: SearchFilterGroup[];
+    /** Entity type (e.g. 'Contact', 'Company'). */
     type?: string;
+    /** Scope to a specific entity by email. */
     email?: string;
+    /** Scope to a specific entity by website URL. */
     websiteUrl?: string;
+    /** Scope to a specific record ID. */
     recordId?: string;
+    /** Scope to specific collections. */
     collectionIds?: string[];
+    /** Page number (1-based, default: 1). */
     page?: number;
+    /** Results per page (max 200, default: 50). */
     pageSize?: number;
+    /** Return only totalMatched count. */
     countOnly?: boolean;
+    /** Include property values per record. */
     returnRecords?: boolean;
+    /** Include free-form memories. */
     includeMemories?: boolean;
+    /** Data source: 'lancedb' or 'snapshot' (default: 'lancedb'). */
+    dataSource?: 'lancedb' | 'snapshot';
 }
+/** @deprecated Use SearchOptions instead. */
+export type ExportOptions = SearchOptions;
 export interface MemoryItem {
     text: string;
     createdAt?: string;
     score?: number;
     metadata?: Record<string, PropertyValue>;
 }
-export interface ExportResponse {
+export interface SearchResponse {
     recordIds: string[];
     totalMatched: number;
     page: number;
     pageSize: number;
     totalPages: number;
+    /** Property values per record (when returnRecords is true). */
     records?: Record<string, Record<string, {
         value: PropertyValue;
         collectionId: string;
         collectionName?: string;
     }>>;
+    /** Main property summary per record. */
+    mainProperties?: Record<string, Record<string, string>>;
+    /** Free-form memories per record (when includeMemories is true). */
     memories?: Record<string, MemoryItem[]>;
 }
+/** @deprecated Use SearchResponse instead. */
+export type ExportResponse = SearchResponse;
+export interface EvaluateMemorizationOptions {
+    /** Collection to evaluate against. */
+    collectionId: string;
+    /** Text to extract from. */
+    input: string;
+    /** Model for extraction phase. */
+    extractionModel?: string;
+    /** Model for analysis phase. */
+    analysisModel?: string;
+    /** Model for schema optimization phase. */
+    optimizerModel?: string;
+    /** If true, don't persist extracted values. Default: true. */
+    skipStorage?: boolean;
+    /** Stream response as SSE events. Default: false. */
+    stream?: boolean;
+    /** Include free-form memories in extraction. Default: false. */
+    includeFreeformMemories?: boolean;
+    /** CRM scope for entity context. */
+    crmKeys?: {
+        recordId?: string;
+        email?: string;
+        websiteUrl?: string;
+    };
+}
+export interface EvaluateMemorizationResponse {
+    success: boolean;
+    phases: Array<{
+        phase: string;
+        model?: string;
+        duration?: number;
+        collectionName?: string;
+        totalProperties?: number;
+        extraction?: {
+            propertyValues: Array<{
+                propertyId: string;
+                propertyName: string;
+                value: unknown;
+                type: string;
+                confidence: number;
+            }>;
+            duration: number;
+        };
+        metrics?: Record<string, unknown>;
+        optimizedCollection?: {
+            properties: Array<{
+                propertyId: string;
+                propertyName: string;
+                description?: string;
+                type: string;
+                wasModified: boolean;
+                changeReason?: string;
+            }>;
+        };
+    }>;
+    summary: {
+        totalDuration: number;
+        propertiesOptimized: number;
+        propertiesAttempted: number;
+    };
+}

package/package.json

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