@personize/sdk 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Personize SDK
2
2
 
3
- 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.
3
+ The official Node.js/TypeScript SDK for the Personize Product API. Authenticate with your secret key to access guidelines, smart guidelines, RAG memory, prompt execution, agents, and evaluation tools.
4
4
 
5
5
  ## Installation
6
6
 
@@ -18,7 +18,11 @@ const client = new Personize({
18
18
  // baseURL: 'http://localhost:3000' // Optional: for local development
19
19
  });
20
20
 
21
- // Verify auth and read plan limits
21
+ // Verify API key
22
+ const testResult = await client.test();
23
+ console.log(testResult.data.organizationId);
24
+
25
+ // Read plan limits
22
26
  const me = await client.me();
23
27
  console.log(me.data.plan.name);
24
28
  console.log(me.data.plan.limits);
@@ -28,59 +32,79 @@ console.log(me.data.plan.limits);
28
32
 
29
33
  | Method | Path | SDK Method |
30
34
  | :--- | :--- | :--- |
35
+ | **Identity** | | |
36
+ | GET | `/api/v1/test` | `client.test()` |
31
37
  | GET | `/api/v1/me` | `client.me()` |
32
- | GET | `/api/v1/variables` | `client.variables.list()` |
33
- | GET | `/api/v1/variables/:id/structure` | `client.variables.getStructure(id)` |
34
- | GET | `/api/v1/variables/:id/section` | `client.variables.getSection(id, opts)` |
35
- | PATCH | `/api/v1/variables/:id` | `client.variables.update(id, payload)` |
36
- | POST | `/api/v1/variables` | `client.variables.create(payload)` |
37
- | DELETE | `/api/v1/variables/:id` | `client.variables.delete(id)` |
38
- | GET | `/api/v1/collections` | `client.collections.list()` |
39
- | POST | `/api/v1/ai/smart-context` | `client.ai.smartContext(opts)` |
38
+ | **AI** | | |
39
+ | POST | `/api/v1/ai/smart-guidelines` | `client.ai.smartGuidelines(opts)` |
40
40
  | POST | `/api/v1/prompt` | `client.ai.prompt(opts)` |
41
- | GET | `/api/v1/agents` | `client.agents.list()` |
42
- | POST | `/api/v1/agents/:id/run` | `client.agents.run(id, opts)` |
43
- | POST | `/api/v1/memorize_pro` | `client.memory.memorize(opts)` |
44
- | POST | `/api/v1/batch-memorize` | `client.memory.memorizeBatch(opts)` |
45
- | POST | `/api/v1/recall_pro` | `client.memory.recall(opts)` |
46
- | POST | `/api/v1/export` | `client.memory.export(opts)` |
47
- | POST | `/api/v1/smart-memory-digest` | `client.memory.smartDigest(opts)` |
41
+ | **Memory** | | |
42
+ | POST | `/api/v1/memorize` | `client.memory.memorize(opts)` |
43
+ | POST | `/api/v1/smart-recall` | `client.memory.smartRecall(opts)` |
44
+ | POST | `/api/v1/recall` | `client.memory.recall(opts)` |
45
+ | POST | `/api/v1/search` | `client.memory.search(opts)` |
48
46
  | POST | `/api/v1/upsert` | `client.memory.upsert(opts)` |
49
47
  | POST | `/api/v1/upsert` | `client.memory.upsertBatch(opts)` |
48
+ | POST | `/api/v1/batch-memorize` | `client.memory.memorizeBatch(opts)` |
49
+ | POST | `/api/v1/smart-memory-digest` | `client.memory.smartDigest(opts)` |
50
+ | **Guidelines** | | |
51
+ | GET | `/api/v1/guidelines` | `client.guidelines.list()` |
52
+ | POST | `/api/v1/guidelines` | `client.guidelines.create(payload)` |
53
+ | GET | `/api/v1/guidelines/:id/structure` | `client.guidelines.getStructure(id)` |
54
+ | GET | `/api/v1/guidelines/:id/section` | `client.guidelines.getSection(id, opts)` |
55
+ | PATCH | `/api/v1/guidelines/:id` | `client.guidelines.update(id, payload)` |
56
+ | DELETE | `/api/v1/guidelines/:id` | `client.guidelines.delete(id)` |
57
+ | GET | `/api/v1/actions/:id/history` | `client.guidelines.history(id)` |
58
+ | **Collections** | | |
59
+ | GET | `/api/v1/collections` | `client.collections.list()` |
60
+ | POST | `/api/v1/collections` | `client.collections.create(payload)` |
61
+ | PATCH | `/api/v1/collections/:id` | `client.collections.update(id, payload)` |
62
+ | DELETE | `/api/v1/collections/:id` | `client.collections.delete(id)` |
63
+ | GET | `/api/v1/collections/:id/history` | `client.collections.history(id)` |
64
+ | **Agents** | | |
65
+ | GET | `/api/v1/agents` | `client.agents.list()` |
66
+ | GET | `/api/v1/agents/:id` | `client.agents.get(id)` |
67
+ | POST | `/api/v1/agents/:id/run` | `client.agents.run(id, opts)` |
68
+ | **Evaluation** | | |
69
+ | POST | `/api/v1/evaluate/memorization-accuracy` | `client.evaluate.memorizationAccuracy(opts)` |
50
70
 
51
71
  All endpoints require `Authorization: Bearer sk_live_...` and count against your plan limits.
52
72
 
53
73
  ## Usage
54
74
 
55
- ### Variables
75
+ ### Guidelines
56
76
 
57
77
  ```typescript
58
- // List all variables
59
- const vars = await client.variables.list();
78
+ // List all guidelines
79
+ const vars = await client.guidelines.list();
60
80
 
61
- // Create a variable
62
- await client.variables.create({ name: 'ICP', value: '...', tags: ['sales'] });
81
+ // Create a guideline
82
+ await client.guidelines.create({ name: 'ICP', value: '...', tags: ['sales'] });
63
83
 
64
- // Update a variable
65
- await client.variables.update(variableId, { value: 'new content' });
84
+ // Update a guideline
85
+ await client.guidelines.update(guidelineId, { value: 'new content' });
66
86
 
67
- // Get variable structure (headings)
68
- const structure = await client.variables.getStructure(variableId);
87
+ // Get guideline structure (headings)
88
+ const structure = await client.guidelines.getStructure(guidelineId);
69
89
 
70
90
  // Get a specific section
71
- const section = await client.variables.getSection(variableId, { header: '## Pricing' });
91
+ const section = await client.guidelines.getSection(guidelineId, { header: '## Pricing' });
72
92
 
73
- // Delete a variable
74
- await client.variables.delete(variableId);
93
+ // Delete a guideline
94
+ await client.guidelines.delete(guidelineId);
95
+
96
+ // Version history
97
+ const history = await client.guidelines.history(guidelineId, { limit: 5 });
75
98
  ```
76
99
 
77
- ### Smart Context
100
+ ### Smart Guidelines
78
101
 
79
102
  ```typescript
80
- const ctx = await client.ai.smartContext({
103
+ const ctx = await client.ai.smartGuidelines({
81
104
  message: 'Write a sales sequence for our top 3 ICPs',
82
105
  tags: ['sales'],
83
106
  excludeTags: ['internal'],
107
+ sessionId: 'my-session', // for incremental context delivery
84
108
  });
85
109
  console.log(ctx.data.compiledContext);
86
110
  ```
@@ -102,6 +126,23 @@ const result = await client.ai.prompt({
102
126
  evaluate: { criteria: 'sales', serverSide: true },
103
127
  });
104
128
 
129
+ // Multimodal — image analysis
130
+ const analysis = await client.ai.prompt({
131
+ prompt: 'Describe what you see in this screenshot.',
132
+ attachments: [
133
+ { name: 'dashboard.png', mimeType: 'image/png', data: base64EncodedImage },
134
+ ],
135
+ model: 'anthropic/claude-sonnet-4-20250514',
136
+ });
137
+
138
+ // Multimodal — PDF extraction via URL
139
+ const extraction = await client.ai.prompt({
140
+ prompt: 'Extract the key terms from this contract.',
141
+ attachments: [
142
+ { name: 'contract.pdf', mimeType: 'application/pdf', url: 'https://your-bucket.s3.amazonaws.com/contract.pdf' },
143
+ ],
144
+ });
145
+
105
146
  // Output extraction + auto-memorize
106
147
  const research = await client.ai.prompt({
107
148
  instructions: [
@@ -128,7 +169,7 @@ console.log(research.data?.evaluation?.finalScore);
128
169
  ### Memory (RAG)
129
170
 
130
171
  ```typescript
131
- // Memorize content
172
+ // Memorize content (dual extraction: structured + free-form)
132
173
  await client.memory.memorize({
133
174
  content: 'Meeting notes: John prefers email contact.',
134
175
  speaker: 'Sales Rep',
@@ -137,19 +178,32 @@ await client.memory.memorize({
137
178
  email: 'john@example.com',
138
179
  });
139
180
 
140
- // Recall memories
141
- const results = await client.memory.recall({
181
+ // Smart recall — advanced recall with reflection
182
+ const results = await client.memory.smartRecall({
142
183
  query: 'What does John prefer?',
143
184
  limit: 5,
144
185
  minScore: 0.7,
186
+ enable_reflection: true,
187
+ generate_answer: true,
188
+ });
189
+
190
+ // Fast recall — low-latency mode (~500ms)
191
+ const fast = await client.memory.smartRecall({
192
+ query: 'contact info for John',
193
+ email: 'john@example.com',
194
+ fast_mode: true,
145
195
  });
146
196
 
147
- // Export/filter records
148
- const exported = await client.memory.export({
197
+ // Direct recall — simple memory lookup (no reflection)
198
+ const direct = await client.memory.recall({
199
+ query: 'What do we know about Acme?',
200
+ email: 'john@acme.com',
201
+ });
202
+
203
+ // Search/filter records by property conditions
204
+ const found = await client.memory.search({
149
205
  groups: [{
150
- id: 'g1',
151
- logic: 'AND',
152
- conditions: [{ field: 'Company', operator: 'EQ', value: 'Acme Corp' }],
206
+ conditions: [{ property: 'company-name', operator: 'equals', value: 'Acme Corp' }],
153
207
  }],
154
208
  returnRecords: true,
155
209
  pageSize: 50,
@@ -180,7 +234,7 @@ const digest = await client.memory.smartDigest({
180
234
  });
181
235
  console.log(digest.data?.compiledContext); // ready-to-use markdown for LLM prompts
182
236
 
183
- // Structured upsert — legacy, no AI extraction
237
+ // Structured upsert — no AI extraction
184
238
  await client.memory.upsert({
185
239
  type: 'Contact',
186
240
  properties: {
@@ -195,10 +249,16 @@ await client.memory.upsert({
195
249
  ### Agents
196
250
 
197
251
  ```typescript
252
+ // List agents
198
253
  const agents = await client.agents.list();
199
254
 
255
+ // Get agent details and expected inputs
256
+ const agent = await client.agents.get(agentId);
257
+ console.log(agent.data.expectedInputs); // ['companyName', 'industry']
258
+
259
+ // Run an agent
200
260
  const result = await client.agents.run(agentId, {
201
- inputs: { userMessage: 'Help with onboarding' },
261
+ inputs: { companyName: 'Acme Corp', industry: 'SaaS' },
202
262
  email: 'customer@example.com',
203
263
  });
204
264
  ```
@@ -206,7 +266,40 @@ const result = await client.agents.run(agentId, {
206
266
  ### Collections
207
267
 
208
268
  ```typescript
269
+ // List collections
209
270
  const collections = await client.collections.list();
271
+
272
+ // Create a collection
273
+ await client.collections.create({
274
+ collectionName: 'Deal Properties',
275
+ entityType: 'Contact',
276
+ properties: [
277
+ { propertyName: 'Deal Stage', type: 'options', options: 'Discovery,Proposal,Closed' },
278
+ ],
279
+ });
280
+
281
+ // Update a collection
282
+ await client.collections.update(collectionId, {
283
+ properties: [{ propertyName: 'Budget', type: 'number', description: 'Estimated budget' }],
284
+ });
285
+
286
+ // Delete a collection
287
+ await client.collections.delete(collectionId);
288
+
289
+ // Version history (full snapshots or compact diffs)
290
+ const history = await client.collections.history(collectionId, { mode: 'diff', limit: 10 });
291
+ ```
292
+
293
+ ### Evaluation
294
+
295
+ ```typescript
296
+ // Run memorization accuracy evaluation against a collection
297
+ const evaluation = await client.evaluate.memorizationAccuracy({
298
+ collectionId: 'col_123',
299
+ input: 'John Smith is VP of Sales at Acme Corp, based in NYC.',
300
+ skipStorage: true,
301
+ });
302
+ console.log(evaluation.data.summary.propertiesOptimized);
210
303
  ```
211
304
 
212
305
  ## Configuration
@@ -214,7 +307,10 @@ const collections = await client.collections.list();
214
307
  | Option | Type | Required | Description |
215
308
  | :--- | :--- | :--- | :--- |
216
309
  | `secretKey` | string | Yes | Your secret key (`sk_live_...`). |
217
- | `baseURL` | string | No | Custom API endpoint (default: `https://api.personize.ai`). |
310
+ | `baseURL` | string | No | Custom API endpoint (default: `https://agent.personize.ai`). |
311
+ | `timeout` | number | No | Request timeout in ms (default: `30000`). |
312
+ | `maxRetries` | number | No | Max retry attempts for 429/5xx errors (default: `3`). |
313
+ | `retryDelay` | number | No | Base delay in ms for exponential backoff (default: `1000`). |
218
314
 
219
315
  ## Test Key (Local Development)
220
316
 
@@ -225,6 +321,29 @@ const client = new Personize({
225
321
  });
226
322
  ```
227
323
 
324
+ ## Migration from 0.3.x
325
+
326
+ **Breaking changes in 0.4.0:**
327
+
328
+ | 0.3.x | 0.4.0 | Notes |
329
+ | :--- | :--- | :--- |
330
+ | `client.memory.recall(opts)` | `client.memory.smartRecall(opts)` | Advanced recall with reflection (route changed to `/smart-recall`) |
331
+ | `client.memory.export(opts)` | `client.memory.search(opts)` | Filter/search records (route changed to `/search`) |
332
+ | `MemorizeProOptions` | `MemorizeOptions` | Type renamed (old name still available as deprecated alias) |
333
+ | `RecallProOptions` | `SmartRecallOptions` | Type renamed (old name still available as deprecated alias) |
334
+ | `ExportOptions` / `ExportResponse` | `SearchOptions` / `SearchResponse` | Types renamed (old names still available as deprecated aliases) |
335
+
336
+ **New in 0.4.0:**
337
+ - `client.test()` — Verify API key validity
338
+ - `client.agents.get(id)` — Get agent details and expected inputs
339
+ - `client.memory.recall(opts)` — Direct memory lookup (no reflection, low latency)
340
+ - `client.memory.search(opts)` — Search/filter records with `property`-based conditions
341
+ - `client.evaluate.memorizationAccuracy(opts)` — Three-phase memorization evaluation
342
+ - `attachments` on `PromptOptions` — Multimodal support (images, PDFs, documents)
343
+ - `sessionId` on `SmartGuidelinesOptions` — Progressive context delivery across multi-step workflows
344
+ - New fields on `MemorizeOptions`: `collectionIds`, `skipStorage`, `skipDualWrite`, `skipPropertySelection`
345
+ - New fields on `SmartRecallOptions`: `max_reflection_rounds`, `filters`
346
+
228
347
  ## Skills
229
348
 
230
349
  The SDK ships with AI-assistant skills in `skills/` that teach Claude Code, Codex, and Cursor how to use the SDK for common workflows.
@@ -248,7 +367,7 @@ skills/integrations/
248
367
 
249
368
  ### Governance (`skills/governance/`)
250
369
 
251
- Manage variables as code — maintain a `governance/variables/` folder of `.md` files and sync them to the Personize API.
370
+ Manage guidelines as code — maintain a `governance/guidelines/` folder of `.md` files and sync them to the Personize API.
252
371
 
253
372
  ```
254
373
  skills/governance/
package/dist/client.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- 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';
1
+ import { PersonizeConfig, ApiResponse, MeResponse, TestResponse, ListOptions, GuidelinesResponse, GuidelineSectionOptions, GuidelineUpdatePayload, GuidelineCreatePayload, GuidelineHistoryResponse, GuidelineHistoryOptions, CollectionsResponse, CollectionCreatePayload, CollectionUpdatePayload, CollectionHistoryOptions, CollectionHistoryResponse, SmartGuidelinesOptions, SmartGuidelinesResponse, PromptOptions, PromptResponse, AgentRunOptions, AgentResponse, MemorizeOptions, SmartRecallOptions, RecallOptions, SearchOptions, SearchResponse, UpsertOptions, UpsertBatchOptions, BatchMemorizeOptions, SmartDigestOptions, SmartDigestResponse, EvaluateMemorizationOptions, EvaluateMemorizationResponse } from './types';
2
2
  export declare class Personize {
3
3
  private client;
4
4
  private _organizationId?;
@@ -8,40 +8,44 @@ export declare class Personize {
8
8
  constructor(config: PersonizeConfig);
9
9
  private resolveIdentity;
10
10
  private getOrganizationId;
11
+ /**
12
+ * GET /api/v1/test — Verify API key is valid. Returns request metadata and resolved identity.
13
+ */
14
+ test(): Promise<ApiResponse<TestResponse>>;
11
15
  /**
12
16
  * GET /api/v1/me — Current context (org, user, plan)
13
17
  */
14
18
  me(): Promise<ApiResponse<MeResponse>>;
15
- variables: {
19
+ guidelines: {
16
20
  /**
17
- * GET /api/v1/variables — List variables for the organization (paginated).
21
+ * GET /api/v1/guidelines — List guidelines for the organization (paginated).
18
22
  * Pass `limit` and `nextToken` for cursor-based pagination.
19
23
  */
20
- list: (options?: ListOptions) => Promise<ApiResponse<VariablesResponse>>;
24
+ list: (options?: ListOptions) => Promise<ApiResponse<GuidelinesResponse>>;
21
25
  /**
22
- * GET /api/v1/variables/:id/structure — Get variable headings
26
+ * GET /api/v1/guidelines/:id/structure — Get guideline headings
23
27
  */
24
28
  getStructure: (id: string) => Promise<ApiResponse>;
25
29
  /**
26
- * GET /api/v1/variables/:id/section — Get a section of a variable by header
30
+ * GET /api/v1/guidelines/:id/section — Get a section of a guideline by header
27
31
  */
28
- getSection: (id: string, options: VariableSectionOptions) => Promise<ApiResponse>;
32
+ getSection: (id: string, options: GuidelineSectionOptions) => Promise<ApiResponse>;
29
33
  /**
30
- * PATCH /api/v1/variables/:id — Partial update to a variable
34
+ * PATCH /api/v1/guidelines/:id — Partial update to a guideline
31
35
  */
32
- update: (id: string, payload: VariableUpdatePayload) => Promise<ApiResponse>;
36
+ update: (id: string, payload: GuidelineUpdatePayload) => Promise<ApiResponse>;
33
37
  /**
34
- * POST /api/v1/variables — Create a new variable
38
+ * POST /api/v1/guidelines — Create a new guideline
35
39
  */
36
- create: (payload: VariableCreatePayload) => Promise<ApiResponse>;
40
+ create: (payload: GuidelineCreatePayload) => Promise<ApiResponse>;
37
41
  /**
38
- * DELETE /api/v1/variables/:id — Delete a variable
42
+ * DELETE /api/v1/guidelines/:id — Delete a guideline
39
43
  */
40
44
  delete: (id: string) => Promise<ApiResponse>;
41
45
  /**
42
- * GET /api/v1/actions/:id/history — Get version history for a variable
46
+ * GET /api/v1/actions/:id/history — Get version history for a guideline
43
47
  */
44
- history: (id: string, options?: VariableHistoryOptions) => Promise<ApiResponse<VariableHistoryResponse>>;
48
+ history: (id: string, options?: GuidelineHistoryOptions) => Promise<ApiResponse<GuidelineHistoryResponse>>;
45
49
  };
46
50
  collections: {
47
51
  /**
@@ -69,9 +73,9 @@ export declare class Personize {
69
73
  };
70
74
  ai: {
71
75
  /**
72
- * POST /api/v1/ai/smart-contextSemantic context routing
76
+ * POST /api/v1/ai/smart-guidelinesSmart guidelines routing. Selects relevant organizational guidelines for a task.
73
77
  */
74
- smartContext: (options: SmartContextOptions) => Promise<ApiResponse<SmartContextResponse>>;
78
+ smartGuidelines: (options: SmartGuidelinesOptions) => Promise<ApiResponse<SmartGuidelinesResponse>>;
75
79
  /**
76
80
  * POST /api/v1/prompt — Execute a prompt with tools, output extraction, and evaluation.
77
81
  *
@@ -88,6 +92,10 @@ export declare class Personize {
88
92
  * Pass `limit` and `nextToken` for cursor-based pagination.
89
93
  */
90
94
  list: (options?: ListOptions) => Promise<ApiResponse>;
95
+ /**
96
+ * GET /api/v1/agents/:id — Get agent details and expected inputs.
97
+ */
98
+ get: (id: string) => Promise<ApiResponse<AgentResponse>>;
91
99
  /**
92
100
  * POST /api/v1/agents/:id/run — Run an agent
93
101
  */
@@ -95,17 +103,24 @@ export declare class Personize {
95
103
  };
96
104
  memory: {
97
105
  /**
98
- * POST /api/v1/memorize_pro — Advanced memorization (RAG)
106
+ * POST /api/v1/memorize — Advanced memorization with dual extraction (RAG).
107
+ * Performs structured property extraction and free-form memory creation.
99
108
  */
100
- memorize: (data: MemorizeProOptions) => Promise<ApiResponse>;
109
+ memorize: (data: MemorizeOptions) => Promise<ApiResponse>;
101
110
  /**
102
- * POST /api/v1/recall_pro — Advanced recall with reflection (RAG)
111
+ * POST /api/v1/smart-recall — Advanced recall with reflection (RAG).
112
+ * Supports reflection loops for improved coverage, answer generation, and entity scoping.
103
113
  */
104
- recall: (data: RecallProOptions) => Promise<ApiResponse>;
114
+ smartRecall: (data: SmartRecallOptions) => Promise<ApiResponse>;
105
115
  /**
106
- * POST /api/v1/exportFilter and export records
116
+ * POST /api/v1/recallDirect memory lookup (no reflection).
107
117
  */
108
- export: (data: ExportOptions) => Promise<ApiResponse<ExportResponse>>;
118
+ recall: (data: RecallOptions) => Promise<ApiResponse>;
119
+ /**
120
+ * POST /api/v1/search — Filter and search records by property conditions.
121
+ * Returns matching record IDs with optional property values and memories.
122
+ */
123
+ search: (data: SearchOptions) => Promise<ApiResponse<SearchResponse>>;
109
124
  /**
110
125
  * POST /api/v1/upsert — Structured upsert (no AI extraction)
111
126
  */
@@ -126,4 +141,11 @@ export declare class Personize {
126
141
  */
127
142
  smartDigest: (data: SmartDigestOptions) => Promise<ApiResponse<SmartDigestResponse>>;
128
143
  };
144
+ evaluate: {
145
+ /**
146
+ * POST /api/v1/evaluate/memorization-accuracy — Run memorization accuracy evaluation.
147
+ * Three-phase evaluation: extraction → analysis → schema optimization.
148
+ */
149
+ memorizationAccuracy: (data: EvaluateMemorizationOptions) => Promise<ApiResponse<EvaluateMemorizationResponse>>;
150
+ };
129
151
  }
package/dist/client.js CHANGED
@@ -8,9 +8,9 @@ const axios_1 = __importDefault(require("axios"));
8
8
  const errors_1 = require("./errors");
9
9
  class Personize {
10
10
  constructor(config) {
11
- this.variables = {
11
+ this.guidelines = {
12
12
  /**
13
- * GET /api/v1/variables — List variables for the organization (paginated).
13
+ * GET /api/v1/guidelines — List guidelines for the organization (paginated).
14
14
  * Pass `limit` and `nextToken` for cursor-based pagination.
15
15
  */
16
16
  list: async (options) => {
@@ -25,32 +25,32 @@ class Personize {
25
25
  params.tags = Array.isArray(options.tags) ? options.tags.join(',') : options.tags;
26
26
  if (options?.excludeTags)
27
27
  params.excludeTags = Array.isArray(options.excludeTags) ? options.excludeTags.join(',') : options.excludeTags;
28
- const response = await this.client.get('/api/v1/variables', { params });
28
+ const response = await this.client.get('/api/v1/guidelines', { params });
29
29
  return response.data;
30
30
  },
31
31
  /**
32
- * GET /api/v1/variables/:id/structure — Get variable headings
32
+ * GET /api/v1/guidelines/:id/structure — Get guideline headings
33
33
  */
34
34
  getStructure: async (id) => {
35
- const response = await this.client.get(`/api/v1/variables/${id}/structure`);
35
+ const response = await this.client.get(`/api/v1/guidelines/${id}/structure`);
36
36
  return response.data;
37
37
  },
38
38
  /**
39
- * GET /api/v1/variables/:id/section — Get a section of a variable by header
39
+ * GET /api/v1/guidelines/:id/section — Get a section of a guideline by header
40
40
  */
41
41
  getSection: async (id, options) => {
42
- const response = await this.client.get(`/api/v1/variables/${id}/section`, {
42
+ const response = await this.client.get(`/api/v1/guidelines/${id}/section`, {
43
43
  params: { header: options.header },
44
44
  });
45
45
  return response.data;
46
46
  },
47
47
  /**
48
- * PATCH /api/v1/variables/:id — Partial update to a variable
48
+ * PATCH /api/v1/guidelines/:id — Partial update to a guideline
49
49
  */
50
50
  update: async (id, payload) => {
51
51
  const organizationId = await this.getOrganizationId();
52
52
  const { historyNote, ...rest } = payload;
53
- const response = await this.client.patch(`/api/v1/variables/${id}`, {
53
+ const response = await this.client.patch(`/api/v1/guidelines/${id}`, {
54
54
  organizationId,
55
55
  historyNote,
56
56
  payload: rest,
@@ -58,21 +58,21 @@ class Personize {
58
58
  return response.data;
59
59
  },
60
60
  /**
61
- * POST /api/v1/variables — Create a new variable
61
+ * POST /api/v1/guidelines — Create a new guideline
62
62
  */
63
63
  create: async (payload) => {
64
- const response = await this.client.post('/api/v1/variables', payload);
64
+ const response = await this.client.post('/api/v1/guidelines', payload);
65
65
  return response.data;
66
66
  },
67
67
  /**
68
- * DELETE /api/v1/variables/:id — Delete a variable
68
+ * DELETE /api/v1/guidelines/:id — Delete a guideline
69
69
  */
70
70
  delete: async (id) => {
71
- const response = await this.client.delete(`/api/v1/variables/${id}`);
71
+ const response = await this.client.delete(`/api/v1/guidelines/${id}`);
72
72
  return response.data;
73
73
  },
74
74
  /**
75
- * GET /api/v1/actions/:id/history — Get version history for a variable
75
+ * GET /api/v1/actions/:id/history — Get version history for a guideline
76
76
  */
77
77
  history: async (id, options) => {
78
78
  const organizationId = await this.getOrganizationId();
@@ -141,10 +141,10 @@ class Personize {
141
141
  };
142
142
  this.ai = {
143
143
  /**
144
- * POST /api/v1/ai/smart-contextSemantic context routing
144
+ * POST /api/v1/ai/smart-guidelinesSmart guidelines routing. Selects relevant organizational guidelines for a task.
145
145
  */
146
- smartContext: async (options) => {
147
- const response = await this.client.post('/api/v1/ai/smart-context', options);
146
+ smartGuidelines: async (options) => {
147
+ const response = await this.client.post('/api/v1/ai/smart-guidelines', options);
148
148
  return response.data;
149
149
  },
150
150
  /**
@@ -180,6 +180,13 @@ class Personize {
180
180
  const response = await this.client.get('/api/v1/agents', { params });
181
181
  return response.data;
182
182
  },
183
+ /**
184
+ * GET /api/v1/agents/:id — Get agent details and expected inputs.
185
+ */
186
+ get: async (id) => {
187
+ const response = await this.client.get(`/api/v1/agents/${id}`);
188
+ return response.data;
189
+ },
183
190
  /**
184
191
  * POST /api/v1/agents/:id/run — Run an agent
185
192
  */
@@ -190,24 +197,34 @@ class Personize {
190
197
  };
191
198
  this.memory = {
192
199
  /**
193
- * POST /api/v1/memorize_pro — Advanced memorization (RAG)
200
+ * POST /api/v1/memorize — Advanced memorization with dual extraction (RAG).
201
+ * Performs structured property extraction and free-form memory creation.
194
202
  */
195
203
  memorize: async (data) => {
196
- const response = await this.client.post('/api/v1/memorize_pro', data);
204
+ const response = await this.client.post('/api/v1/memorize', data);
197
205
  return response.data;
198
206
  },
199
207
  /**
200
- * POST /api/v1/recall_pro — Advanced recall with reflection (RAG)
208
+ * POST /api/v1/smart-recall — Advanced recall with reflection (RAG).
209
+ * Supports reflection loops for improved coverage, answer generation, and entity scoping.
210
+ */
211
+ smartRecall: async (data) => {
212
+ const response = await this.client.post('/api/v1/smart-recall', data);
213
+ return response.data;
214
+ },
215
+ /**
216
+ * POST /api/v1/recall — Direct memory lookup (no reflection).
201
217
  */
202
218
  recall: async (data) => {
203
- const response = await this.client.post('/api/v1/recall_pro', data);
219
+ const response = await this.client.post('/api/v1/recall', data);
204
220
  return response.data;
205
221
  },
206
222
  /**
207
- * POST /api/v1/export — Filter and export records
223
+ * POST /api/v1/search — Filter and search records by property conditions.
224
+ * Returns matching record IDs with optional property values and memories.
208
225
  */
209
- export: async (data) => {
210
- const response = await this.client.post('/api/v1/export', data);
226
+ search: async (data) => {
227
+ const response = await this.client.post('/api/v1/search', data);
211
228
  return response.data;
212
229
  },
213
230
  /**
@@ -255,10 +272,20 @@ class Personize {
255
272
  return response.data;
256
273
  },
257
274
  };
275
+ this.evaluate = {
276
+ /**
277
+ * POST /api/v1/evaluate/memorization-accuracy — Run memorization accuracy evaluation.
278
+ * Three-phase evaluation: extraction → analysis → schema optimization.
279
+ */
280
+ memorizationAccuracy: async (data) => {
281
+ const response = await this.client.post('/api/v1/evaluate/memorization-accuracy', data);
282
+ return response.data;
283
+ },
284
+ };
258
285
  this.maxRetries = config.maxRetries ?? 3;
259
286
  this.retryDelay = config.retryDelay ?? 1000;
260
287
  this.client = axios_1.default.create({
261
- baseURL: config.baseURL || 'https://api.personize.ai',
288
+ baseURL: config.baseURL || 'https://agent.personize.ai',
262
289
  timeout: config.timeout ?? 30000,
263
290
  headers: {
264
291
  'Authorization': `Bearer ${config.secretKey}`,
@@ -307,6 +334,13 @@ class Personize {
307
334
  const { organizationId } = await this.resolveIdentity();
308
335
  return organizationId;
309
336
  }
337
+ /**
338
+ * GET /api/v1/test — Verify API key is valid. Returns request metadata and resolved identity.
339
+ */
340
+ async test() {
341
+ const response = await this.client.get('/api/v1/test');
342
+ return response.data;
343
+ }
310
344
  /**
311
345
  * GET /api/v1/me — Current context (org, user, plan)
312
346
  */
package/dist/types.d.ts CHANGED
@@ -58,24 +58,37 @@ export interface ListOptions {
58
58
  /** When true, strip the full `value` field for lighter payloads. */
59
59
  summary?: boolean;
60
60
  }
61
- export interface VariablesResponse {
61
+ /** Inferred governance scope for a guideline — determines when it is proactively included in SmartContext results. */
62
+ export interface GovernanceScope {
63
+ /** True if this guideline applies to virtually all agent tasks (e.g., core company values, universal compliance). */
64
+ alwaysOn: boolean;
65
+ /** Action/domain keywords that trigger inclusion (e.g., "email", "pricing", "deploy"). */
66
+ triggerKeywords: string[];
67
+ }
68
+ export interface GuidelinesResponse {
62
69
  actions: Array<{
63
70
  id: string;
64
71
  type: string;
65
72
  payload: {
66
73
  name: string;
67
74
  value: string;
68
- [key: string]: PropertyValue;
75
+ /** Auto-inferred governance scope (read-only). Present when the guideline has been analyzed. */
76
+ governanceScope?: GovernanceScope;
77
+ [key: string]: PropertyValue | GovernanceScope | string[] | undefined;
69
78
  };
70
79
  }>;
71
80
  count: number;
72
81
  /** Cursor for the next page. Undefined when on the last page. */
73
82
  nextToken?: string;
74
83
  }
75
- export interface VariableSectionOptions {
84
+ /** @deprecated Use GuidelinesResponse instead. */
85
+ export type VariablesResponse = GuidelinesResponse;
86
+ export interface GuidelineSectionOptions {
76
87
  header: string;
77
88
  }
78
- export interface VariableUpdatePayload {
89
+ /** @deprecated Use GuidelineSectionOptions instead. */
90
+ export type VariableSectionOptions = GuidelineSectionOptions;
91
+ export interface GuidelineUpdatePayload {
79
92
  name?: string;
80
93
  value?: string;
81
94
  description?: string;
@@ -86,14 +99,18 @@ export interface VariableUpdatePayload {
86
99
  separator?: string;
87
100
  historyNote?: string;
88
101
  }
89
- export interface VariableCreatePayload {
102
+ /** @deprecated Use GuidelineUpdatePayload instead. */
103
+ export type VariableUpdatePayload = GuidelineUpdatePayload;
104
+ export interface GuidelineCreatePayload {
90
105
  name: string;
91
106
  value?: string;
92
107
  description?: string;
93
108
  tags?: string[];
94
109
  secure?: boolean;
95
110
  }
96
- export interface VariableHistoryEntry {
111
+ /** @deprecated Use GuidelineCreatePayload instead. */
112
+ export type VariableCreatePayload = GuidelineCreatePayload;
113
+ export interface GuidelineHistoryEntry {
97
114
  id: string;
98
115
  originalActionId: string;
99
116
  type: string;
@@ -109,16 +126,22 @@ export interface VariableHistoryEntry {
109
126
  [key: string]: PropertyValue;
110
127
  };
111
128
  }
112
- export interface VariableHistoryResponse {
129
+ /** @deprecated Use GuidelineHistoryEntry instead. */
130
+ export type VariableHistoryEntry = GuidelineHistoryEntry;
131
+ export interface GuidelineHistoryResponse {
113
132
  actionId: string;
114
- history: VariableHistoryEntry[];
133
+ history: GuidelineHistoryEntry[];
115
134
  count: number;
116
135
  }
117
- export interface VariableHistoryOptions {
136
+ /** @deprecated Use GuidelineHistoryResponse instead. */
137
+ export type VariableHistoryResponse = GuidelineHistoryResponse;
138
+ export interface GuidelineHistoryOptions {
118
139
  /** Max number of history records to return (default: 20, max: 50).
119
140
  * Each entry includes the full variable content snapshot, so use a small limit (3-5) in token-sensitive contexts. */
120
141
  limit?: number;
121
142
  }
143
+ /** @deprecated Use GuidelineHistoryOptions instead. */
144
+ export type VariableHistoryOptions = GuidelineHistoryOptions;
122
145
  export interface CollectionsResponse {
123
146
  actions: Array<{
124
147
  id: string;
@@ -213,9 +236,12 @@ export interface CollectionHistoryResponse {
213
236
  changes: CollectionPropertyDiff;
214
237
  }>;
215
238
  }
216
- export interface SmartContextOptions {
239
+ export interface SmartGuidelinesOptions {
217
240
  message: string;
218
- variableIds?: string[];
241
+ /** Filter to specific guideline IDs. */
242
+ guidelineIds?: string[];
243
+ /** Resolve guideline names to IDs server-side (case-insensitive match). */
244
+ guidelineNames?: string[];
219
245
  tags?: string[];
220
246
  excludeTags?: string[];
221
247
  model?: string;
@@ -223,14 +249,20 @@ export interface SmartContextOptions {
223
249
  mode?: 'fast' | 'full' | 'auto';
224
250
  /** Minimum cosine similarity score (0-1) for fast mode results. Lower values return more results. Default: 0.4 for supplementary, 0.7 for critical. */
225
251
  minScore?: number;
252
+ /** Session ID for conversation continuity. */
253
+ sessionId?: string;
226
254
  }
227
- export interface SmartContextAnalysis {
255
+ /** @deprecated Use SmartGuidelinesOptions instead. */
256
+ export type SmartContextOptions = SmartGuidelinesOptions;
257
+ export interface SmartGuidelinesAnalysis {
228
258
  taskUnderstanding: string;
229
259
  qualityDimensions: string[];
230
260
  refinedTask: string;
231
261
  }
232
- export interface SmartContextSelection {
233
- variableId: string;
262
+ /** @deprecated Use SmartGuidelinesAnalysis instead. */
263
+ export type SmartContextAnalysis = SmartGuidelinesAnalysis;
264
+ export interface SmartGuidelinesSelection {
265
+ guidelineId: string;
234
266
  name?: string;
235
267
  score?: number;
236
268
  reason?: string;
@@ -240,10 +272,12 @@ export interface SmartContextSelection {
240
272
  mode?: string;
241
273
  sections?: string[];
242
274
  }
243
- export interface SmartContextUsage {
275
+ /** @deprecated Use SmartGuidelinesSelection instead. */
276
+ export type SmartContextSelection = SmartGuidelinesSelection;
277
+ export interface SmartGuidelinesUsage {
244
278
  durationMs: number;
245
279
  tokensUsed?: number;
246
- variablesScanned?: number;
280
+ guidelinesScanned?: number;
247
281
  selectedCount?: number;
248
282
  preFilter?: {
249
283
  total: number;
@@ -252,17 +286,21 @@ export interface SmartContextUsage {
252
286
  durationMs: number;
253
287
  };
254
288
  }
255
- export interface SmartContextResponse {
289
+ /** @deprecated Use SmartGuidelinesUsage instead. */
290
+ export type SmartContextUsage = SmartGuidelinesUsage;
291
+ export interface SmartGuidelinesResponse {
256
292
  success: boolean;
257
293
  /** Which routing mode was actually used. */
258
294
  mode: 'fast' | 'full';
259
295
  /** LLM analysis of the task. Null in fast mode. */
260
- analysis?: SmartContextAnalysis | null;
261
- selection: SmartContextSelection[];
262
- supplementary?: SmartContextSelection[];
296
+ analysis?: SmartGuidelinesAnalysis | null;
297
+ selection: SmartGuidelinesSelection[];
298
+ supplementary?: SmartGuidelinesSelection[];
263
299
  compiledContext: string;
264
- usage: SmartContextUsage;
300
+ usage: SmartGuidelinesUsage;
265
301
  }
302
+ /** @deprecated Use SmartGuidelinesResponse instead. */
303
+ export type SmartContextResponse = SmartGuidelinesResponse;
266
304
  /**
267
305
  * Per-MCP tool selection override.
268
306
  * Use enabledTools for an explicit allowlist, or disabledTools for a denylist.
@@ -272,6 +310,38 @@ export interface McpToolSelection {
272
310
  enabledTools?: string[];
273
311
  disabledTools?: string[];
274
312
  }
313
+ /**
314
+ * An attachment sent alongside a prompt or agent run.
315
+ *
316
+ * Two modes:
317
+ * - **Inline (base64):** `data` contains the raw base64-encoded content.
318
+ * - **URL reference:** `url` points to a publicly-accessible or presigned URL.
319
+ *
320
+ * At least one of `data` or `url` must be provided.
321
+ */
322
+ export interface Attachment {
323
+ /** Human-readable filename (e.g. "screenshot.png"). Max 255 chars. */
324
+ name?: string;
325
+ /** MIME type (e.g. "image/png", "application/pdf"). Must be a supported type. */
326
+ mimeType: string;
327
+ /** Base64-encoded content. Required if `url` is not provided. */
328
+ data?: string;
329
+ /** Publicly-accessible URL to the content. Required if `data` is not provided. */
330
+ url?: string;
331
+ }
332
+ /**
333
+ * Supported MIME types for attachments.
334
+ *
335
+ * Images: image/png, image/jpeg, image/gif, image/webp, image/svg+xml
336
+ * Documents: application/pdf, text/plain, text/csv, text/html, text/markdown, application/json
337
+ */
338
+ export declare const SUPPORTED_ATTACHMENT_TYPES: readonly ["image/png", "image/jpeg", "image/gif", "image/webp", "image/svg+xml", "application/pdf", "text/plain", "text/csv", "text/html", "text/markdown", "application/json"];
339
+ /** Max attachments per request. */
340
+ export declare const MAX_ATTACHMENTS_COUNT = 10;
341
+ /** Max size per attachment in bytes (20 MB). */
342
+ export declare const MAX_ATTACHMENT_SIZE_BYTES: number;
343
+ /** Max total attachment payload in bytes (50 MB). */
344
+ export declare const MAX_TOTAL_ATTACHMENTS_BYTES: number;
275
345
  /** Auto-memorize configuration for /prompt. */
276
346
  export interface PromptMemorizeConfig {
277
347
  /** Contact email identifier. */
@@ -284,7 +354,7 @@ export interface PromptMemorizeConfig {
284
354
  type?: 'Contact' | 'Company' | 'User';
285
355
  /**
286
356
  * When true, tool results from research tools (search_companies, tavily, etc.)
287
- * are automatically captured and memorized. Meta tools (smart_context,
357
+ * are automatically captured and memorized. Meta tools (smart_guidelines,
288
358
  * recall_pro, memorize_pro, store_evaluation_log) are excluded.
289
359
  */
290
360
  captureToolResults?: boolean;
@@ -301,6 +371,17 @@ export interface PromptOutputDefinition {
301
371
  /** Unique name for this output (used in <output name="..."> markers). */
302
372
  name: string;
303
373
  }
374
+ /** Multimodal attachment for prompt requests (images, PDFs, documents). */
375
+ export interface PromptAttachment {
376
+ /** Filename (e.g. 'screenshot.png'). Max 255 chars. */
377
+ name?: string;
378
+ /** 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. */
379
+ mimeType: string;
380
+ /** Base64-encoded content. Required if url is not provided. */
381
+ data?: string;
382
+ /** Public URL to the content. Required if data is not provided. */
383
+ url?: string;
384
+ }
304
385
  export interface PromptOptions {
305
386
  prompt?: string;
306
387
  instructions?: Array<string | {
@@ -333,6 +414,16 @@ export interface PromptOptions {
333
414
  };
334
415
  /** Per-MCP tool selection override (allowlist or denylist per MCP) */
335
416
  mcpTools?: McpToolSelection[];
417
+ /**
418
+ * Images or documents to send with the prompt (multimodal input).
419
+ *
420
+ * In multi-step mode (`instructions`), attachments are sent with the
421
+ * **first instruction** only — subsequent steps reference them via
422
+ * conversation history.
423
+ *
424
+ * Limits: max 10 attachments, 20 MB each, 50 MB total.
425
+ */
426
+ attachments?: Attachment[];
336
427
  }
337
428
  /** Prompt response when outputs/evaluation are used. */
338
429
  export interface PromptResponse {
@@ -359,14 +450,27 @@ export interface PromptResponse {
359
450
  completionTokens: number;
360
451
  totalTokens: number;
361
452
  };
453
+ /** Tool calls made during execution (name + args). */
362
454
  toolCalls?: Array<{
363
455
  toolName: string;
456
+ args?: Record<string, unknown>;
457
+ }>;
458
+ /** Tool call return values (name + result). Always present regardless of captureToolResults. */
459
+ toolResults?: Array<{
460
+ toolName: string;
461
+ result: unknown;
364
462
  }>;
463
+ /** Number of AI SDK steps (simple mode). */
365
464
  stepsExecuted?: number;
465
+ /** Number of instruction steps executed (multi-step mode). */
366
466
  instructionsExecuted?: number;
367
467
  };
468
+ /** Per-step breakdown (multi-step mode only). */
368
469
  steps?: Array<{
369
470
  instructionIndex: number;
471
+ /** Instruction prompt that was executed. */
472
+ prompt: string;
473
+ /** Raw response text for this step (may include <output> markers). */
370
474
  text: string;
371
475
  usage?: {
372
476
  promptTokens: number;
@@ -375,10 +479,34 @@ export interface PromptResponse {
375
479
  };
376
480
  toolCalls?: Array<{
377
481
  toolName: string;
482
+ args?: Record<string, unknown>;
378
483
  }>;
379
484
  stepsExecuted: number;
380
485
  }>;
381
486
  }
487
+ export interface TestResponse {
488
+ timestamp: string;
489
+ ip: string;
490
+ userAgent: string;
491
+ userId: string;
492
+ organizationId: string;
493
+ }
494
+ export interface AgentInstructionStep {
495
+ prompt: string;
496
+ order: number;
497
+ }
498
+ export interface AgentResponse {
499
+ id: string;
500
+ type: string;
501
+ payload: {
502
+ name: string;
503
+ instructions: AgentInstructionStep[];
504
+ actions: Array<Record<string, unknown>>;
505
+ aiConfig?: Record<string, unknown>;
506
+ };
507
+ /** Variable names extracted from {{placeholder}} tokens in the agent's instructions. */
508
+ expectedInputs: string[];
509
+ }
382
510
  export interface AgentRunOptions {
383
511
  inputs?: Record<string, unknown>;
384
512
  stream?: boolean;
@@ -387,30 +515,73 @@ export interface AgentRunOptions {
387
515
  recordId?: string;
388
516
  /** Per-MCP tool selection override (allowlist or denylist per MCP) */
389
517
  mcpTools?: McpToolSelection[];
518
+ /**
519
+ * Images or documents to send with the agent run (multimodal input).
520
+ *
521
+ * Limits: max 10 attachments, 20 MB each, 50 MB total.
522
+ */
523
+ attachments?: Attachment[];
390
524
  }
391
- export interface MemorizeProOptions {
525
+ export interface MemorizeOptions {
526
+ /** Content to memorize. */
392
527
  content: string;
528
+ /** Speaker/source label. */
393
529
  speaker?: string;
530
+ /** Timestamp of the content. */
394
531
  timestamp?: string;
532
+ /** Schema hint for extraction. */
395
533
  schema?: Record<string, unknown>;
534
+ /** Action ID for linking. */
396
535
  actionId?: string;
536
+ /** CRM record ID for entity scoping. */
397
537
  record_id?: string;
538
+ /** Email for CRM linking. */
398
539
  email?: string;
540
+ /** Website URL for CRM linking. */
399
541
  website_url?: string;
542
+ /** Enable enhanced dual extraction (structured + free-form). */
400
543
  enhanced?: boolean;
544
+ /** Tags for property selection. */
401
545
  tags?: string[];
546
+ /** Limit extraction to specific collections. */
547
+ collectionIds?: string[];
548
+ /** Max properties to select for extraction. */
402
549
  max_properties?: number;
403
- }
404
- export interface RecallProOptions {
550
+ /** If true, extract without persisting (dry run). */
551
+ skipStorage?: boolean;
552
+ /** If true, skip the secondary write path. */
553
+ skipDualWrite?: boolean;
554
+ /** If true, skip property selection step. */
555
+ skipPropertySelection?: boolean;
556
+ }
557
+ /** @deprecated Use MemorizeOptions instead. */
558
+ export type MemorizeProOptions = MemorizeOptions;
559
+ export interface SmartRecallOptions {
560
+ /** Natural-language query. */
405
561
  query: string;
562
+ /** Max results to return (default: 10). */
406
563
  limit?: number;
564
+ /** Minimum similarity score threshold. */
407
565
  minScore?: number;
566
+ /** CRM record ID for entity scoping. */
408
567
  record_id?: string;
568
+ /** Filter results to a specific entity by email. */
409
569
  email?: string;
570
+ /** Website URL for entity scoping. */
410
571
  website_url?: string;
572
+ /** Entity type filter (e.g. 'Contact', 'Company'). */
411
573
  type?: string;
574
+ /** Scope results to specific collections by ID. */
575
+ collectionIds?: string[];
576
+ /** Scope results to specific collections by name (resolved server-side, case-insensitive). */
577
+ collectionNames?: string[];
578
+ /** Return schema-enforced property values separately from free-form memories. */
412
579
  include_property_values?: boolean;
580
+ /** Enable reflection loop to improve recall coverage (default: true). */
413
581
  enable_reflection?: boolean;
582
+ /** Maximum reflection iterations (default: 2). Only used when enable_reflection is true. */
583
+ max_reflection_rounds?: number;
584
+ /** Generate a synthesized answer from recalled memories. */
414
585
  generate_answer?: boolean;
415
586
  /**
416
587
  * Fast mode: skip reflection loop and answer generation, use minScore 0.3,
@@ -423,6 +594,22 @@ export interface RecallProOptions {
423
594
  * In fast_mode, defaults to 0.3 if not specified.
424
595
  */
425
596
  min_score?: number;
597
+ /** Metadata filters for narrowing results. */
598
+ filters?: Record<string, unknown>;
599
+ }
600
+ /** @deprecated Use SmartRecallOptions instead. */
601
+ export type RecallProOptions = SmartRecallOptions;
602
+ export interface RecallOptions {
603
+ /** Natural-language query. */
604
+ query: string;
605
+ /** CRM record ID for entity scoping. */
606
+ record_id?: string;
607
+ /** Filter results to a specific entity by email. */
608
+ email?: string;
609
+ /** Website URL for entity scoping. */
610
+ website_url?: string;
611
+ /** Additional filters. */
612
+ filters?: Record<string, unknown>;
426
613
  }
427
614
  export interface UpsertOptions {
428
615
  /** Entity type (e.g. 'Contact', 'Company') */
@@ -524,44 +711,130 @@ export interface SmartDigestResponse {
524
711
  tokenEstimate: number;
525
712
  tokenBudget: number;
526
713
  }
527
- export interface ExportOptions {
528
- groups?: Array<{
529
- id: string;
530
- logic: 'AND' | 'OR';
531
- conditions: Array<{
532
- field: string;
533
- operator: string;
534
- value?: PropertyValue;
535
- collectionId?: string;
536
- }>;
537
- }>;
714
+ export interface SearchFilterCondition {
715
+ /** Property system name to filter on. */
716
+ property: string;
717
+ /** Comparison operator (e.g. 'equals', 'contains', 'gt', 'lt'). */
718
+ operator: string;
719
+ /** Value to compare against. */
720
+ value?: PropertyValue;
721
+ /** Scope to a specific collection. */
722
+ collectionId?: string;
723
+ }
724
+ export interface SearchFilterGroup {
725
+ /** Filter conditions within this group. */
726
+ conditions: SearchFilterCondition[];
727
+ }
728
+ export interface SearchOptions {
729
+ /** Filter groups with conditions. To list all records, send one group with empty conditions. */
730
+ groups?: SearchFilterGroup[];
731
+ /** Entity type (e.g. 'Contact', 'Company'). */
538
732
  type?: string;
733
+ /** Scope to a specific entity by email. */
539
734
  email?: string;
735
+ /** Scope to a specific entity by website URL. */
540
736
  websiteUrl?: string;
737
+ /** Scope to a specific record ID. */
541
738
  recordId?: string;
739
+ /** Scope to specific collections. */
542
740
  collectionIds?: string[];
741
+ /** Page number (1-based, default: 1). */
543
742
  page?: number;
743
+ /** Results per page (max 200, default: 50). */
544
744
  pageSize?: number;
745
+ /** Return only totalMatched count. */
545
746
  countOnly?: boolean;
747
+ /** Include property values per record. */
546
748
  returnRecords?: boolean;
749
+ /** Include free-form memories. */
547
750
  includeMemories?: boolean;
751
+ /** Data source: 'lancedb' or 'snapshot' (default: 'lancedb'). */
752
+ dataSource?: 'lancedb' | 'snapshot';
548
753
  }
754
+ /** @deprecated Use SearchOptions instead. */
755
+ export type ExportOptions = SearchOptions;
549
756
  export interface MemoryItem {
550
757
  text: string;
551
758
  createdAt?: string;
552
759
  score?: number;
553
760
  metadata?: Record<string, PropertyValue>;
554
761
  }
555
- export interface ExportResponse {
762
+ export interface SearchResponse {
556
763
  recordIds: string[];
557
764
  totalMatched: number;
558
765
  page: number;
559
766
  pageSize: number;
560
767
  totalPages: number;
768
+ /** Property values per record (when returnRecords is true). */
561
769
  records?: Record<string, Record<string, {
562
770
  value: PropertyValue;
563
771
  collectionId: string;
564
772
  collectionName?: string;
565
773
  }>>;
774
+ /** Main property summary per record. */
775
+ mainProperties?: Record<string, Record<string, string>>;
776
+ /** Free-form memories per record (when includeMemories is true). */
566
777
  memories?: Record<string, MemoryItem[]>;
567
778
  }
779
+ /** @deprecated Use SearchResponse instead. */
780
+ export type ExportResponse = SearchResponse;
781
+ export interface EvaluateMemorizationOptions {
782
+ /** Collection to evaluate against. */
783
+ collectionId: string;
784
+ /** Text to extract from. */
785
+ input: string;
786
+ /** Model for extraction phase. */
787
+ extractionModel?: string;
788
+ /** Model for analysis phase. */
789
+ analysisModel?: string;
790
+ /** Model for schema optimization phase. */
791
+ optimizerModel?: string;
792
+ /** If true, don't persist extracted values. Default: true. */
793
+ skipStorage?: boolean;
794
+ /** Stream response as SSE events. Default: false. */
795
+ stream?: boolean;
796
+ /** Include free-form memories in extraction. Default: false. */
797
+ includeFreeformMemories?: boolean;
798
+ /** CRM scope for entity context. */
799
+ crmKeys?: {
800
+ recordId?: string;
801
+ email?: string;
802
+ websiteUrl?: string;
803
+ };
804
+ }
805
+ export interface EvaluateMemorizationResponse {
806
+ success: boolean;
807
+ phases: Array<{
808
+ phase: string;
809
+ model?: string;
810
+ duration?: number;
811
+ collectionName?: string;
812
+ totalProperties?: number;
813
+ extraction?: {
814
+ propertyValues: Array<{
815
+ propertyId: string;
816
+ propertyName: string;
817
+ value: unknown;
818
+ type: string;
819
+ confidence: number;
820
+ }>;
821
+ duration: number;
822
+ };
823
+ metrics?: Record<string, unknown>;
824
+ optimizedCollection?: {
825
+ properties: Array<{
826
+ propertyId: string;
827
+ propertyName: string;
828
+ description?: string;
829
+ type: string;
830
+ wasModified: boolean;
831
+ changeReason?: string;
832
+ }>;
833
+ };
834
+ }>;
835
+ summary: {
836
+ totalDuration: number;
837
+ propertiesOptimized: number;
838
+ propertiesAttempted: number;
839
+ };
840
+ }
package/dist/types.js CHANGED
@@ -1,3 +1,22 @@
1
1
  "use strict";
2
2
  // --- Utility Types ---
3
3
  Object.defineProperty(exports, "__esModule", { value: true });
4
+ exports.MAX_TOTAL_ATTACHMENTS_BYTES = exports.MAX_ATTACHMENT_SIZE_BYTES = exports.MAX_ATTACHMENTS_COUNT = exports.SUPPORTED_ATTACHMENT_TYPES = void 0;
5
+ /**
6
+ * Supported MIME types for attachments.
7
+ *
8
+ * Images: image/png, image/jpeg, image/gif, image/webp, image/svg+xml
9
+ * Documents: application/pdf, text/plain, text/csv, text/html, text/markdown, application/json
10
+ */
11
+ exports.SUPPORTED_ATTACHMENT_TYPES = [
12
+ 'image/png', 'image/jpeg', 'image/gif', 'image/webp', 'image/svg+xml',
13
+ 'application/pdf',
14
+ 'text/plain', 'text/csv', 'text/html', 'text/markdown',
15
+ 'application/json',
16
+ ];
17
+ /** Max attachments per request. */
18
+ exports.MAX_ATTACHMENTS_COUNT = 10;
19
+ /** Max size per attachment in bytes (20 MB). */
20
+ exports.MAX_ATTACHMENT_SIZE_BYTES = 20 * 1024 * 1024;
21
+ /** Max total attachment payload in bytes (50 MB). */
22
+ exports.MAX_TOTAL_ATTACHMENTS_BYTES = 50 * 1024 * 1024;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@personize/sdk",
3
- "version": "0.3.0",
3
+ "version": "0.5.0",
4
4
  "description": "Official Personize SDK",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",