@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 +162 -43
- package/dist/client.d.ts +44 -22
- package/dist/client.js +59 -25
- package/dist/types.d.ts +310 -37
- package/dist/types.js +19 -0
- package/package.json +1 -1
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
|
|
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
|
|
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
|
-
|
|
|
33
|
-
|
|
|
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
|
-
|
|
|
42
|
-
| POST | `/api/v1/
|
|
43
|
-
| POST | `/api/v1/
|
|
44
|
-
| POST | `/api/v1/
|
|
45
|
-
| POST | `/api/v1/
|
|
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
|
-
###
|
|
75
|
+
### Guidelines
|
|
56
76
|
|
|
57
77
|
```typescript
|
|
58
|
-
// List all
|
|
59
|
-
const vars = await client.
|
|
78
|
+
// List all guidelines
|
|
79
|
+
const vars = await client.guidelines.list();
|
|
60
80
|
|
|
61
|
-
// Create a
|
|
62
|
-
await client.
|
|
81
|
+
// Create a guideline
|
|
82
|
+
await client.guidelines.create({ name: 'ICP', value: '...', tags: ['sales'] });
|
|
63
83
|
|
|
64
|
-
// Update a
|
|
65
|
-
await client.
|
|
84
|
+
// Update a guideline
|
|
85
|
+
await client.guidelines.update(guidelineId, { value: 'new content' });
|
|
66
86
|
|
|
67
|
-
// Get
|
|
68
|
-
const structure = await client.
|
|
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.
|
|
91
|
+
const section = await client.guidelines.getSection(guidelineId, { header: '## Pricing' });
|
|
72
92
|
|
|
73
|
-
// Delete a
|
|
74
|
-
await client.
|
|
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
|
|
100
|
+
### Smart Guidelines
|
|
78
101
|
|
|
79
102
|
```typescript
|
|
80
|
-
const ctx = await client.ai.
|
|
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
|
-
//
|
|
141
|
-
const results = await client.memory.
|
|
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
|
-
//
|
|
148
|
-
const
|
|
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
|
-
|
|
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 —
|
|
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: {
|
|
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://
|
|
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
|
|
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,
|
|
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
|
-
|
|
19
|
+
guidelines: {
|
|
16
20
|
/**
|
|
17
|
-
* GET /api/v1/
|
|
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<
|
|
24
|
+
list: (options?: ListOptions) => Promise<ApiResponse<GuidelinesResponse>>;
|
|
21
25
|
/**
|
|
22
|
-
* GET /api/v1/
|
|
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/
|
|
30
|
+
* GET /api/v1/guidelines/:id/section — Get a section of a guideline by header
|
|
27
31
|
*/
|
|
28
|
-
getSection: (id: string, options:
|
|
32
|
+
getSection: (id: string, options: GuidelineSectionOptions) => Promise<ApiResponse>;
|
|
29
33
|
/**
|
|
30
|
-
* PATCH /api/v1/
|
|
34
|
+
* PATCH /api/v1/guidelines/:id — Partial update to a guideline
|
|
31
35
|
*/
|
|
32
|
-
update: (id: string, payload:
|
|
36
|
+
update: (id: string, payload: GuidelineUpdatePayload) => Promise<ApiResponse>;
|
|
33
37
|
/**
|
|
34
|
-
* POST /api/v1/
|
|
38
|
+
* POST /api/v1/guidelines — Create a new guideline
|
|
35
39
|
*/
|
|
36
|
-
create: (payload:
|
|
40
|
+
create: (payload: GuidelineCreatePayload) => Promise<ApiResponse>;
|
|
37
41
|
/**
|
|
38
|
-
* DELETE /api/v1/
|
|
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
|
|
46
|
+
* GET /api/v1/actions/:id/history — Get version history for a guideline
|
|
43
47
|
*/
|
|
44
|
-
history: (id: string, options?:
|
|
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-
|
|
76
|
+
* POST /api/v1/ai/smart-guidelines — Smart guidelines routing. Selects relevant organizational guidelines for a task.
|
|
73
77
|
*/
|
|
74
|
-
|
|
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/
|
|
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:
|
|
109
|
+
memorize: (data: MemorizeOptions) => Promise<ApiResponse>;
|
|
101
110
|
/**
|
|
102
|
-
* POST /api/v1/
|
|
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
|
-
|
|
114
|
+
smartRecall: (data: SmartRecallOptions) => Promise<ApiResponse>;
|
|
105
115
|
/**
|
|
106
|
-
* POST /api/v1/
|
|
116
|
+
* POST /api/v1/recall — Direct memory lookup (no reflection).
|
|
107
117
|
*/
|
|
108
|
-
|
|
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.
|
|
11
|
+
this.guidelines = {
|
|
12
12
|
/**
|
|
13
|
-
* GET /api/v1/
|
|
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/
|
|
28
|
+
const response = await this.client.get('/api/v1/guidelines', { params });
|
|
29
29
|
return response.data;
|
|
30
30
|
},
|
|
31
31
|
/**
|
|
32
|
-
* GET /api/v1/
|
|
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/
|
|
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/
|
|
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/
|
|
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/
|
|
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/
|
|
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/
|
|
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/
|
|
64
|
+
const response = await this.client.post('/api/v1/guidelines', payload);
|
|
65
65
|
return response.data;
|
|
66
66
|
},
|
|
67
67
|
/**
|
|
68
|
-
* DELETE /api/v1/
|
|
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/
|
|
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
|
|
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-
|
|
144
|
+
* POST /api/v1/ai/smart-guidelines — Smart guidelines routing. Selects relevant organizational guidelines for a task.
|
|
145
145
|
*/
|
|
146
|
-
|
|
147
|
-
const response = await this.client.post('/api/v1/ai/smart-
|
|
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/
|
|
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/
|
|
204
|
+
const response = await this.client.post('/api/v1/memorize', data);
|
|
197
205
|
return response.data;
|
|
198
206
|
},
|
|
199
207
|
/**
|
|
200
|
-
* POST /api/v1/
|
|
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/
|
|
219
|
+
const response = await this.client.post('/api/v1/recall', data);
|
|
204
220
|
return response.data;
|
|
205
221
|
},
|
|
206
222
|
/**
|
|
207
|
-
* POST /api/v1/
|
|
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
|
-
|
|
210
|
-
const response = await this.client.post('/api/v1/
|
|
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://
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
84
|
+
/** @deprecated Use GuidelinesResponse instead. */
|
|
85
|
+
export type VariablesResponse = GuidelinesResponse;
|
|
86
|
+
export interface GuidelineSectionOptions {
|
|
76
87
|
header: string;
|
|
77
88
|
}
|
|
78
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
129
|
+
/** @deprecated Use GuidelineHistoryEntry instead. */
|
|
130
|
+
export type VariableHistoryEntry = GuidelineHistoryEntry;
|
|
131
|
+
export interface GuidelineHistoryResponse {
|
|
113
132
|
actionId: string;
|
|
114
|
-
history:
|
|
133
|
+
history: GuidelineHistoryEntry[];
|
|
115
134
|
count: number;
|
|
116
135
|
}
|
|
117
|
-
|
|
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
|
|
239
|
+
export interface SmartGuidelinesOptions {
|
|
217
240
|
message: string;
|
|
218
|
-
|
|
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
|
-
|
|
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
|
-
|
|
233
|
-
|
|
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
|
-
|
|
275
|
+
/** @deprecated Use SmartGuidelinesSelection instead. */
|
|
276
|
+
export type SmartContextSelection = SmartGuidelinesSelection;
|
|
277
|
+
export interface SmartGuidelinesUsage {
|
|
244
278
|
durationMs: number;
|
|
245
279
|
tokensUsed?: number;
|
|
246
|
-
|
|
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
|
-
|
|
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?:
|
|
261
|
-
selection:
|
|
262
|
-
supplementary?:
|
|
296
|
+
analysis?: SmartGuidelinesAnalysis | null;
|
|
297
|
+
selection: SmartGuidelinesSelection[];
|
|
298
|
+
supplementary?: SmartGuidelinesSelection[];
|
|
263
299
|
compiledContext: string;
|
|
264
|
-
usage:
|
|
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 (
|
|
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
|
|
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
|
-
|
|
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
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
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
|
|
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;
|