@personize/sdk 0.6.2 → 0.6.5

package/README.md

@@ -38,6 +38,7 @@ console.log(me.data.plan.limits);
 | **AI** | | |
 | POST | `/api/v1/ai/smart-guidelines` | `client.ai.smartGuidelines(opts)` |
 | POST | `/api/v1/prompt` | `client.ai.prompt(opts)` |
+| POST | `/api/v1/prompt` (stream) | `client.ai.promptStream(opts)` |
 | **Memory** | | |
 | POST | `/api/v1/memorize` | `client.memory.memorize(opts)` |
 | POST | `/api/v1/smart-recall` | `client.memory.smartRecall(opts)` |
@@ -45,6 +46,7 @@ console.log(me.data.plan.limits);
 | POST | `/api/v1/search` | `client.memory.search(opts)` |
 | POST | `/api/v1/batch-memorize` | `client.memory.memorizeBatch(opts)` |
 | POST | `/api/v1/smart-memory-digest` | `client.memory.smartDigest(opts)` |
+| POST | `/api/v1/memory/properties` | `client.memory.properties(opts)` |
 | **Guidelines** | | |
 | GET | `/api/v1/guidelines` | `client.guidelines.list()` |
 | POST | `/api/v1/guidelines` | `client.guidelines.create(payload)` |
@@ -185,6 +187,97 @@ console.log(research.data?.outputs?.company_profile);
 console.log(research.data?.evaluation?.finalScore);
 ```
 
+### Streaming Prompt Execution
+
+`promptStream()` returns an async generator that yields Server-Sent Events as they arrive. Use this for real-time UI updates, progressive output delivery, or when you need structured outputs as soon as each one finishes generating.
+
+```typescript
+import type { PromptSSEEvent } from '@personize/sdk';
+
+// Stream with structured outputs — events arrive as each output closes
+for await (const event of client.ai.promptStream({
+    prompt: 'Generate a hero section and social proof for our landing page',
+    outputs: [
+        { name: 'hero' },
+        { name: 'social_proof' },
+    ],
+})) {
+    switch (event.type) {
+        case 'text':
+            // Raw LLM text chunks (everything outside <output> markers)
+            process.stdout.write(event.chunk);
+            break;
+
+        case 'output':
+            // A named output extracted — fired once per output as soon as </output> closes
+            // event.data is already parsed (JSON object or plain string)
+            console.log(`Output "${event.name}":`, event.data);
+            break;
+
+        case 'done':
+            // Final event — includes all outputs, evaluation, and metadata
+            console.log('All outputs:', event.outputs);
+            console.log('Metadata:', event.metadata);
+            break;
+
+        case 'error':
+            // Non-fatal error during streaming
+            console.error('Stream error:', event.message);
+            break;
+    }
+}
+```
+
+**SSE Event Types:**
+
+| Event | Frequency | Description |
+| :--- | :--- | :--- |
+| `text` | Many per response | Plain text chunks from the LLM |
+| `output` | Once per named output | Extracted output (JSON or string) — fired as soon as `</output>` closes |
+| `step_complete` | Once per instruction step | Multi-step mode: step metadata |
+| `done` | Once at end | Final reconciliation with all outputs + metadata |
+| `error` | 0 or more | Non-fatal streaming errors |
+
+**Options:**
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `streamTimeout` | number | `120000` | Overall stream timeout in ms |
+| `signal` | AbortSignal | — | External abort signal for cancellation |
+
+All other `PromptOptions` parameters (`outputs`, `context`, `instructions`, `tier`, `memorize`, `evaluate`, etc.) are supported.
+
+**Cancellation:**
+
+```typescript
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 5000); // cancel after 5s
+
+for await (const event of client.ai.promptStream({
+    prompt: '...',
+    signal: controller.signal,
+})) {
+    // ...
+}
+```
+
+#### Entity Identifiers
+
+All memory endpoints support multiple CRM key types for entity scoping:
+
+| Key | Use case |
+|-----|----------|
+| `email` | Contact lookup |
+| `websiteUrl` | Company lookup |
+| `recordId` | Direct record ID |
+| `customKeyName` + `customKeyValue` | Custom CRM field (e.g. `hubspot_id`) |
+| `phoneNumber` | Phone-based lookup |
+| `postalCode` | Location-based lookup |
+| `deviceId` | Device-based lookup |
+| `contentId` | Content-based lookup |
+
+You can pass multiple keys simultaneously for better matching.
+
 ### Memory (RAG)
 
 ```typescript
@@ -199,21 +292,20 @@ const memorized = await client.memory.memorize({
 });
 console.log(memorized.data?.recordId); // REC#<hex> — deterministic, use for recall/digest
 
-// Smart recall — advanced recall with reflection
+// Smart recall — deep mode (default): reflection + answer generation, ~10-20s, 2 credits
 const results = await client.memory.smartRecall({
     query: 'What does John prefer?',
     limit: 5,
     minScore: 0.7,
-    enable_reflection: true,
-    generate_answer: true,
+    mode: 'deep',
 });
 
-// Fast recall — low-latency mode (~500ms), guaranteed min 10 results
+// Smart recall — fast mode: skips reflection, ~500ms, 1 credit
 const fast = await client.memory.smartRecall({
     query: 'contact info for John',
     email: 'john@example.com',
-    fast_mode: true,
-    // min_results: 10 (default in fast_mode — always returns top N even below score threshold)
+    mode: 'fast',
+    // min_results: 10 (default in fast mode — always returns top N even below score threshold)
 });
 
 // Custom keys — bring your own identifier for any entity type
@@ -239,7 +331,7 @@ const student = await client.memory.smartRecall({
     type: 'Student',
     customKeyName: 'studentNumber',
     customKeyValue: 'S-2024-1234',
-    fast_mode: true,
+    mode: 'fast',
 });
 
 // Direct recall — DynamoDB lookup: properties + freeform memories (no AI, type required)
@@ -285,6 +377,47 @@ for (const [recordId, props] of Object.entries(found.data?.records ?? {})) {
 }
 // Note: 'email' and 'company-name' must match the property names in your collection definition
 
+// --- Advanced Search Patterns ---
+
+// Key-only lookup: find a record by email without needing property conditions
+const byEmail = await client.memory.search({
+    email: 'sarah@acme.com',
+    returnRecords: true,
+});
+
+// Key-only lookup: find a record by custom key (no groups needed)
+const byStudentNumber = await client.memory.search({
+    type: 'Student',
+    customKeyName: 'studentNumber',
+    customKeyValue: 'S-2024-1234',
+    returnRecords: true,
+});
+
+// Secondary key: find Students where email is a secondary attribute (not the primary key)
+// Works because memorize stores all CRM keys on every LanceDB row
+const studentByEmail = await client.memory.search({
+    type: 'Student',
+    email: 'alice@university.edu',
+    returnRecords: true,
+});
+
+// Cross-type search: find ALL records with this email across ALL entity types
+// Returns Contacts, Students, Employees — whatever has this email
+const crossType = await client.memory.search({
+    email: 'john@acme.com',
+    returnRecords: true,
+});
+
+// Property-value lookup: find records by a stored property (e.g. LinkedIn URL)
+// Use this when the lookup key is a property value, not a CRM identifier
+const byLinkedIn = await client.memory.search({
+    type: 'Contact',
+    returnRecords: true,
+    groups: [{
+        conditions: [{ property: 'linkedin_url', operator: 'EQ', value: 'https://linkedin.com/in/johndoe' }],
+    }],
+});
+
 // Batch sync — unified call with per-property extractMemories control
 // IMPORTANT: Set extractMemories: true on rich text fields (notes, transcripts, descriptions)
 // to enable AI extraction and semantic search. Without it, only structured storage occurs.
@@ -336,6 +469,38 @@ console.log(digest.data?.compiledContext); // ready-to-use markdown for LLM prom
 
 ```
 
+### Get Record Properties
+
+Fetch current property values for a record, joined with collection schema descriptions and the `update` flag.
+
+```typescript
+// Get specific properties with schema info
+const result = await client.memory.properties({
+  email: 'john@acme.com',
+  propertyNames: ['Tasks', 'Lifecycle Stage'],
+  nonEmpty: true,
+});
+
+for (const prop of result.data.properties) {
+  console.log(`${prop.name}: ${JSON.stringify(prop.value)}`);
+  console.log(`  Type: ${prop.type}, Update: ${prop.update}`);
+  console.log(`  Description: ${prop.description}`);
+}
+```
+
+Each property includes:
+- `value` — current value
+- `description` — from the collection schema, tells AI how to interpret/update
+- `update` — `true` means replaceable (use `memory.update()` with `propertyValue`), `false` means append-only (use `arrayPush`)
+- `type` — property type (`text`, `number`, `boolean`, `array`, `date`, `options`)
+- `collectionName` — which collection this property belongs to
+
+Options:
+- `propertyNames` — filter to specific properties (recommended to save tokens)
+- `includeDescriptions` — join with collection schema (default: `true`)
+- `nonEmpty` — exclude null/empty values (default: `false`)
+- Identifiers: `email`, `websiteUrl`, `recordId`, `customKeyName`+`customKeyValue`
+
 ### Agents
 
 ```typescript
@@ -415,12 +580,12 @@ console.log(evaluation.data.summary.propertiesOptimized);
 
 | Operation | Mode | Credits/Call |
 | :--- | :--- | :--- |
-| Smart Recall | `fast_mode: true` | 1 |
-| Smart Recall | `fast_mode: false` (deep) | 1 |
+| Smart Recall | `mode: 'fast'` | 1 |
+| Smart Recall | `mode: 'deep'` | 2 |
 | Smart Guidelines | `mode: 'fast'` | 1 |
 | Smart Guidelines | `mode: 'deep'` | 1 |
 
-All read operations (recall, smart recall, smart guidelines, smart context) charge a flat **1 credit per call** regardless of mode. Mode choice affects latency and depth, not cost.
+Smart Recall cost depends on mode: fast = 1 credit, deep = 2 credits. All other read operations (recall, smart guidelines, smart context) charge a flat **1 credit per call**.
 
 1 credit = $0.01.
 
@@ -455,6 +620,33 @@ await client.ai.prompt({
 
 Response metadata includes `byok: true` and `creditsCharged` reflecting the flat 5-credit charge.
 
+## Smart Recall Modes
+
+The `mode` parameter controls smart recall behavior:
+
+| Mode | Latency | Credits | Description |
+| :--- | :--- | :--- | :--- |
+| `"fast"` | ~500ms | 1 | Skips reflection and answer generation. Returns raw vector results with guaranteed minimum count. |
+| `"deep"` | ~10-20s | 2 | Enables reflection + answer generation for higher-quality, synthesized responses. |
+
+Default is `"deep"`. The `mode` parameter takes precedence over the individual `enable_reflection`, `generate_answer`, and `fast_mode` flags. If `mode` is set, those flags are ignored.
+
+#### Recency Bias
+
+Use `prefer_recent` to boost recent memories with exponential decay:
+
+```typescript
+const result = await client.memory.smartRecall({
+  query: "what changed on this contact recently?",
+  email: "john@acme.com",
+  mode: "deep",
+  prefer_recent: true,
+  recency_half_life_days: 30, // aggressive: 30-day half-life
+});
+```
+
+Default half-life is 90 days. A memory 90 days old scores ~37% of its original relevance. Set to 7-30 for "what happened this week/month" queries.
+
 ## Best Practices: Query Crafting for smartRecall
 
 The `smartRecall` endpoint uses vector similarity search. Query quality directly impacts result relevance. When building AI pipelines that call `smartRecall`, the **AI agent is responsible for crafting embedding-friendly queries**.
@@ -477,11 +669,11 @@ const bad = await client.memory.smartRecall({ query: 'Tell me about this contact
 const good = await client.memory.smartRecall({
     query: `${contactName} role company background interests preferences`,
     email,
-    fast_mode: true,
+    mode: 'fast',
 });
 ```
 
-**Guaranteed minimum results:** In `fast_mode`, `smartRecall` guarantees at least 10 results (configurable via `min_results`) even when scores fall below the threshold. This ensures your AI workflow always has context to reason about — it can then decide whether the data is sufficient or not.
+**Guaranteed minimum results:** In `mode: 'fast'`, `smartRecall` guarantees at least 10 results (configurable via `min_results`) even when scores fall below the threshold. This ensures your AI workflow always has context to reason about — it can then decide whether the data is sufficient or not.
 
 ## Configuration
 
@@ -502,6 +694,22 @@ const client = new Personize({
 });
 ```
 
+## Migration from 0.6.2
+
+**New in 0.6.3:**
+
+| Feature | Details |
+| :--- | :--- |
+| `evaluationCriteria` on `PromptOptions` | Compatibility alias for `evaluate: { criteria, serverSide: true }` |
+| `message` on `RecallOptions` / `SmartRecallOptions` | Compatibility alias for `query` |
+| Legacy `memory.recall()` routing | If you call `recall()` with legacy advanced-recall-style inputs (`message`, `limit`, omitted `type`, collection-name scoping), the SDK routes to `/smart-recall` automatically |
+| Shorthand semantic `memory.search()` | `search({ query, limit, collectionName })` is accepted and routed to `/smart-recall` when no filter groups are provided |
+| `collectionName` / `collectionNames` on `memorize()` | Collection names are resolved client-side into `collectionIds` |
+| Legacy collection payload aliases | `collections.create()` now accepts `name`, `slug`, `description`, array `options`, and `updateSemantics` |
+| `records` shorthand on `memorizeBatch()` | Accepts record-style input and normalizes it client-side into `memorize()` + `/batch-memorize` calls |
+
+See [SDK_0_6_3_COMPATIBILITY_CHANGES.md](SDK_0_6_3_COMPATIBILITY_CHANGES.md) for the full design notes and tradeoffs.
+
 ## Migration from 0.5.x
 
 **New in 0.6.0:**

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { PersonizeConfig, ApiResponse, MeResponse, TestResponse, ListOptions, GuidelinesResponse, GuidelineSectionOptions, GuidelineUpdatePayload, GuidelineCreatePayload, GuidelineHistoryResponse, GuidelineHistoryOptions, CollectionsResponse, CollectionCreatePayload, CollectionUpdatePayload, CollectionHistoryOptions, CollectionHistoryResponse, SmartGuidelinesOptions, SmartGuidelinesResponse, PromptOptions, PromptResponse, AgentRunOptions, AgentResponse, MemorizeOptions, SmartRecallOptions, RecallOptions, SearchOptions, SearchResponse, BatchMemorizeOptions, SmartDigestOptions, SmartDigestResponse, EvaluateMemorizationOptions, EvaluateMemorizationResponse } from './types';
+import { PersonizeConfig, ApiResponse, MeResponse, TestResponse, ListOptions, GuidelinesResponse, GuidelineSectionOptions, GuidelineUpdatePayload, GuidelineCreatePayload, GuidelineHistoryResponse, GuidelineHistoryOptions, CollectionsResponse, CollectionCreatePayload, CollectionUpdatePayload, CollectionHistoryOptions, CollectionHistoryResponse, SmartGuidelinesOptions, SmartGuidelinesResponse, PromptOptions, PromptResponse, PromptStreamOptions, PromptSSEEvent, AgentRunOptions, AgentResponse, MemorizeOptions, SmartRecallOptions, RecallOptions, RecallResponse, SearchOptions, SearchResponse, BatchMemorizeOptions, SmartDigestOptions, SmartDigestResponse, EvaluateMemorizationOptions, EvaluateMemorizationResponse, UpdatePropertyOptions, UpdateResult, BulkUpdateOptions, BulkUpdateResult, PropertyHistoryOptions, PropertyHistoryResult, QueryPropertiesOptions, QueryPropertiesResult, DeleteMemoriesOptions, DeleteRecordOptions, DeletionResult, CancelDeletionOptions, CancelDeletionResult, FilterByPropertyOptions, FilterByPropertyResult, GetPropertiesOptions, GetPropertiesResponse } from './types';
 export declare class Personize {
     private client;
     private _organizationId?;
@@ -8,6 +8,26 @@ export declare class Personize {
     constructor(config: PersonizeConfig);
     private resolveIdentity;
     private getOrganizationId;
+    private normalizePropertyOptions;
+    private inferEntityTypeFromKeys;
+    private listAllCollections;
+    private resolveCollectionIdsByName;
+    private normalizeCollectionCreatePayload;
+    private attachArrayMetadata;
+    private normalizeGuidelinesListResponse;
+    private normalizeCollectionsListResponse;
+    private normalizePromptOptions;
+    private normalizeMemorizeOptions;
+    private normalizeSmartRecallOptions;
+    private isLegacyRecallRequest;
+    private normalizeLegacyRecallToSmartRecall;
+    private normalizeRecallOptions;
+    private buildSearchGroupsFromFilters;
+    private normalizeSearchRequest;
+    private normalizeSearchResponse;
+    private normalizeRecallResponse;
+    private isBatchRecordProperty;
+    private memorizeBatchFromRecords;
     /**
      * GET /api/v1/test — Verify API key is valid. Returns request metadata and resolved identity.
      */
@@ -85,6 +105,28 @@ export declare class Personize {
          * Use `memorize` to auto-save outputs and tool results to memory.
          */
         prompt: (options: PromptOptions) => Promise<ApiResponse<PromptResponse>>;
+        /**
+         * POST /api/v1/prompt (stream: true) — Stream prompt execution as Server-Sent Events.
+         *
+         * Returns an async generator that yields SSE events as they arrive:
+         * - `text`: plain text chunks from the LLM
+         * - `output`: a named output extracted when its </output> marker closes
+         * - `step_complete`: fired after each instruction step (multi-step mode)
+         * - `done`: final event with all outputs, evaluation, and metadata
+         * - `error`: non-fatal error during streaming
+         *
+         * @example
+         * ```ts
+         * for await (const event of personize.ai.promptStream({
+         *   prompt: 'Write a hero section',
+         *   outputs: [{ name: 'headline' }, { name: 'subtitle' }],
+         * })) {
+         *   if (event.type === 'output') console.log(event.name, event.data);
+         *   if (event.type === 'done') console.log('Finished:', event.metadata);
+         * }
+         * ```
+         */
+        promptStream: (options: PromptStreamOptions) => AsyncGenerator<PromptSSEEvent>;
     };
     agents: {
         /**
@@ -111,11 +153,11 @@ export declare class Personize {
          * POST /api/v1/smart-recall — Advanced recall with reflection (RAG).
          * Supports reflection loops for improved coverage, answer generation, and entity scoping.
          */
-        smartRecall: (data: SmartRecallOptions) => Promise<ApiResponse>;
+        smartRecall: (data: SmartRecallOptions) => Promise<ApiResponse<RecallResponse>>;
         /**
          * POST /api/v1/recall — Direct memory lookup (no reflection).
          */
-        recall: (data: RecallOptions) => Promise<ApiResponse>;
+        recall: (data: RecallOptions) => Promise<ApiResponse<RecallResponse>>;
         /**
          * POST /api/v1/search — Filter and search records by property conditions.
          * Returns matching record IDs with optional property values and memories.
@@ -132,6 +174,61 @@ export declare class Personize {
          * Combines DynamoDB properties + LanceDB memories into a token-budgeted markdown block.
          */
         smartDigest: (data: SmartDigestOptions) => Promise<ApiResponse<SmartDigestResponse>>;
+        /**
+         * POST /api/v1/memory/update — Update a single property or freeform memory.
+         *
+         * For property updates: pass `propertyName` + `propertyValue` (or array operations).
+         * For freeform edits: pass `memoryId` + `text`.
+         * Use `expectedVersion` for optimistic concurrency (409 on mismatch).
+         */
+        update: (data: UpdatePropertyOptions) => Promise<ApiResponse<UpdateResult>>;
+        /**
+         * POST /api/v1/memory/bulk-update — Update multiple properties on a record in one request.
+         * Use `expectedVersion` for optimistic concurrency (checked before any writes).
+         */
+        bulkUpdate: (data: BulkUpdateOptions) => Promise<ApiResponse<BulkUpdateResult>>;
+        /**
+         * POST /api/v1/memory/delete — Soft-delete memories (30-day recovery window).
+         * Deleted items are excluded from all reads. Use `cancelDeletion` to restore.
+         */
+        delete: (data: DeleteMemoriesOptions) => Promise<ApiResponse<DeletionResult>>;
+        /**
+         * POST /api/v1/memory/delete-record — Soft-delete all memories for a record (30-day recovery).
+         */
+        deleteRecord: (data: DeleteRecordOptions) => Promise<ApiResponse<DeletionResult>>;
+        /**
+         * POST /api/v1/memory/cancel-deletion — Cancel a pending soft-delete within the 30-day window.
+         * Returns 409 DELETION_FINALIZED if the window has expired.
+         */
+        cancelDeletion: (data: CancelDeletionOptions) => Promise<ApiResponse<CancelDeletionResult>>;
+        /**
+         * POST /api/v1/memory/property-history — Query property change history for a record.
+         * Supports filtering by property name, time range, and cursor-based pagination.
+         */
+        propertyHistory: (data: PropertyHistoryOptions) => Promise<ApiResponse<PropertyHistoryResult>>;
+        /**
+         * POST /api/v1/memory/query-properties — LLM-powered search across property values.
+         * Finds records where a property value matches a natural-language query.
+         */
+        queryProperties: (data: QueryPropertiesOptions) => Promise<ApiResponse<QueryPropertiesResult>>;
+        /**
+         * POST /api/v1/memory/filter-by-property — Deterministic property filter (no LLM, no token cost).
+         * Finds records where property values match structured conditions.
+         *
+         * @example
+         * ```ts
+         * const result = await client.memory.filterByProperty({
+         *   conditions: [{ propertyName: 'deal_stage', operator: 'equals', value: 'closed_won' }],
+         *   type: 'Company',
+         *   limit: 100,
+         * });
+         * ```
+         */
+        filterByProperty: (data: FilterByPropertyOptions) => Promise<ApiResponse<FilterByPropertyResult>>;
+        /**
+         * POST /api/v1/properties — Get record properties with schema descriptions.
+         */
+        properties: (data: GetPropertiesOptions) => Promise<ApiResponse<GetPropertiesResponse>>;
     };
     evaluate: {
         /**