@personize/sdk 0.5.3 → 0.6.2

package/README.md

@@ -110,10 +110,32 @@ console.log(ctx.data.compiledContext);
 ### Prompt Execution
 
 ```typescript
-// Simple prompt
+// Simple prompt (defaults to 'pro' tier)
 const response = await client.ai.prompt({
     prompt: 'Summarize our Q4 sales strategy',
 });
+console.log(response.data?.metadata?.creditsCharged); // credits used
+
+// With explicit tier
+const fast = await client.ai.prompt({
+    prompt: 'Quick summary of today',
+    tier: 'basic',   // cheapest, fastest
+});
+
+const premium = await client.ai.prompt({
+    prompt: 'Deep analysis of market trends',
+    tier: 'ultra',   // highest quality model
+});
+
+// BYOK — use your own API key + model + provider (Pro/Enterprise plans only)
+const byok = await client.ai.prompt({
+    prompt: 'Generate a report',
+    openrouterApiKey: 'sk-or-v1-...',  // your OpenRouter key
+    model: 'anthropic/claude-sonnet-4-20250514',
+    provider: 'openrouter',
+});
+// BYOK billing: flat 5 credits/call — no per-token charge, you pay your provider directly
+// Without BYOK, model/provider are rejected — use tier to control quality level
 
 // Multi-step instructions with evaluation
 const result = await client.ai.prompt({
@@ -130,7 +152,6 @@ const analysis = await client.ai.prompt({
     attachments: [
         { name: 'dashboard.png', mimeType: 'image/png', data: base64EncodedImage },
     ],
-    model: 'anthropic/claude-sonnet-4-20250514',
 });
 
 // Multimodal — PDF extraction via URL
@@ -168,14 +189,15 @@ console.log(research.data?.evaluation?.finalScore);
 
 ```typescript
 // Memorize content (dual extraction: structured + free-form)
-// Tip: prepend identity field hints to ensure demographic properties are captured
-await client.memory.memorize({
-    content: 'Also extract First Name, Company Name, and Job Title if mentioned.\n\nMeeting notes: John prefers email contact. He is VP of Sales at Acme Corp.',
+// Response includes recordId for immediate use in recall/digest calls
+const memorized = await client.memory.memorize({
+    content: 'Meeting notes: John prefers email contact. He is VP of Sales at Acme Corp.',
     speaker: 'Sales Rep',
     enhanced: true,
     tags: ['meetings'],
     email: 'john@example.com',
 });
+console.log(memorized.data?.recordId); // REC#<hex> — deterministic, use for recall/digest
 
 // Smart recall — advanced recall with reflection
 const results = await client.memory.smartRecall({
@@ -186,11 +208,38 @@ const results = await client.memory.smartRecall({
     generate_answer: true,
 });
 
-// Fast recall — low-latency mode (~500ms)
+// Fast recall — low-latency mode (~500ms), guaranteed min 10 results
 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)
+});
+
+// Custom keys — bring your own identifier for any entity type
+// Use customKeyName/customKeyValue when email or websiteUrl don't apply.
+// The recordId is generated deterministically from orgId + type + key — same key always resolves to the same record.
+await client.memory.memorize({
+    content: 'Student enrolled in Advanced AI course. GPA 3.8, Dean\'s List.',
+    type: 'Student',
+    customKeyName: 'studentNumber',
+    customKeyValue: 'S-2024-1234',
+    enhanced: true,
+});
+
+// More examples: LinkedIn profiles, web pages, code files, products...
+await client.memory.memorize({ content: '...', type: 'Person',  customKeyName: 'linkedinUrl',  customKeyValue: 'https://linkedin.com/in/johndoe' });
+await client.memory.memorize({ content: '...', type: 'Webpage', customKeyName: 'pageUrl',      customKeyValue: 'https://docs.example.com/api/auth' });
+await client.memory.memorize({ content: '...', type: 'File',    customKeyName: 'filePath',     customKeyValue: 'src/auth/oauth.ts' });
+await client.memory.memorize({ content: '...', type: 'Product', customKeyName: 'sku',          customKeyValue: 'PRD-X100-BLK' });
+
+// Recall by the same custom key — no need to know the recordId
+const student = await client.memory.smartRecall({
+    query: 'What courses is this student enrolled in?',
+    type: 'Student',
+    customKeyName: 'studentNumber',
+    customKeyValue: 'S-2024-1234',
+    fast_mode: true,
 });
 
 // Direct recall — DynamoDB lookup: properties + freeform memories (no AI, type required)
@@ -202,7 +251,15 @@ const direct = await client.memory.recall({
 // direct.data.memories — structured properties from Snapshot
 // direct.data.freeformMemories — AI-extracted memories from Freeform table
 
-// Search/filter records by property conditions
+// Direct recall by custom key
+const student = await client.memory.recall({
+    query: 'Academic record',
+    type: 'Student',
+    customKeyName: 'studentNumber',
+    customKeyValue: 'S-2024-1234',
+});
+
+// Search/filter records by property conditions — works with any type value
 const found = await client.memory.search({
     groups: [{
         conditions: [{ property: 'company-name', operator: 'equals', value: 'Acme Corp' }],
@@ -211,6 +268,23 @@ const found = await client.memory.search({
     pageSize: 50,
 });
 
+// Search across a custom entity type
+const deansList = await client.memory.search({
+    type: 'Student',
+    returnRecords: true,
+    groups: [{
+        conditions: [{ property: 'gpa', operator: 'GTE', value: 3.5 }],
+    }],
+});
+
+// Access property values: records[recordId][propertyName].value (plain string)
+for (const [recordId, props] of Object.entries(found.data?.records ?? {})) {
+    const email = props['email']?.value;           // plain string — whatever was stored
+    const company = props['company-name']?.value;
+    console.log(`${recordId}: ${email} at ${company}`);
+}
+// Note: 'email' and 'company-name' must match the property names in your collection definition
+
 // 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.
@@ -218,6 +292,9 @@ await client.memory.memorizeBatch({
     source: 'Hubspot',
     mapping: {
         entityType: 'contact',
+        // email: 'email' means "use the 'email' field from each row as the contact identifier"
+        // The value must match the key name in your rows array (e.g., row.email)
+        // Use websiteUrl instead for Company records, or recordId for direct ID matching
         email: 'email',
         properties: {
             email:     { sourceField: 'email',    collectionId: 'col_std', collectionName: 'Standard', extractMemories: false },
@@ -230,6 +307,25 @@ await client.memory.memorizeBatch({
     ],
 });
 
+// Batch sync with custom keys — for non-Contact/Company entity types
+await client.memory.memorizeBatch({
+    source: 'University DB',
+    mapping: {
+        entityType: 'Student',
+        customKeyName: 'studentNumber',   // the identifier name
+        customKey: 'student_id',          // source field in rows holding the value
+        properties: {
+            full_name: { sourceField: 'name',   collectionId: 'col_std', collectionName: 'Standard', extractMemories: false },
+            gpa:       { sourceField: 'gpa',    collectionId: 'col_std', collectionName: 'Standard', extractMemories: false },
+            notes:     { sourceField: 'notes',  collectionId: 'col_gen', collectionName: 'Generated', extractMemories: true },
+        },
+    },
+    rows: [
+        { student_id: 'S-2024-1234', name: 'Alice Chen', gpa: '3.8', notes: 'Dean\'s List, AI research focus' },
+        { student_id: 'S-2024-5678', name: 'Bob Park', gpa: '3.5', notes: 'Full-stack internship at Stripe' },
+    ],
+});
+
 // Smart memory digest — compiled context for an entity
 const digest = await client.memory.smartDigest({
     email: 'john@acme.com',
@@ -296,6 +392,97 @@ const evaluation = await client.evaluate.memorizationAccuracy({
 console.log(evaluation.data.summary.propertiesOptimized);
 ```
 
+## Tiers & Pricing
+
+### Generate Tiers (Prompt)
+
+| Tier | Input Credits/1K tokens | Output Credits/1K tokens | Best For |
+| :--- | :--- | :--- | :--- |
+| `basic` | 1.0 | 2.0 | High-volume, simple tasks |
+| `pro` | 1.0 | 3.0 | Balanced quality & cost (default) |
+| `ultra` | 1.0 | 5.0 | Complex reasoning, highest quality |
+
+### Memorize Tiers
+
+| Tier | Credits/1K tokens | Best For |
+| :--- | :--- | :--- |
+| `basic` | 1 | Bulk imports, simple data |
+| `pro` | 3 | General use (default) |
+| `pro_fast` | 5 | Pro quality, lower latency |
+| `ultra` | 12 | Maximum extraction quality |
+
+### Retrieval (Recall & Smart Guidelines)
+
+| Operation | Mode | Credits/Call |
+| :--- | :--- | :--- |
+| Smart Recall | `fast_mode: true` | 1 |
+| Smart Recall | `fast_mode: false` (deep) | 1 |
+| 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.
+
+1 credit = $0.01.
+
+### Direct Providers
+
+### BYOK (Bring Your Own Key)
+
+Pro and Enterprise plans can pass their own API key. Billing switches to a flat **5 credits per call** (no per-token charge — you pay your provider directly).
+
+When using BYOK, you **must** provide both `model` and `provider`. Without BYOK, `model` and `provider` are rejected — use `tier` to control quality level.
+
+```typescript
+// BYOK: must specify all three
+await client.ai.prompt({
+    prompt: '...',
+    openrouterApiKey: 'sk-or-v1-...',
+    model: 'anthropic/claude-sonnet-4-20250514',
+    provider: 'openrouter',
+});
+
+// Without BYOK: use tier (model/provider auto-selected)
+await client.ai.prompt({
+    prompt: '...',
+    tier: 'pro',  // basic, pro (default), ultra
+});
+```
+
+**Error cases:**
+- `model`/`provider` without `openrouterApiKey` → `400 BYOK required`
+- `openrouterApiKey` without `model`/`provider` → `400 model and provider required`
+- BYOK on a plan that doesn't allow it → `403 byok_not_allowed`
+
+Response metadata includes `byok: true` and `creditsCharged` reflecting the flat 5-credit charge.
+
+## 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**.
+
+**Do:**
+- Use specific, descriptive queries that match the language of stored data
+- Include entity names, property names, or domain-specific terms
+- Example: `"John Smith role title company background"` instead of `"Tell me about this contact"`
+
+**Don't:**
+- Use vague meta-queries like `"What do we know?"` or `"Tell me everything"`
+- Use task-oriented queries like `"open tasks pending action items"` when only profile data was memorized
+
+**Example — AI pipeline pattern:**
+```typescript
+// BAD: vague query → low similarity scores → few or no results
+const bad = await client.memory.smartRecall({ query: 'Tell me about this contact', email });
+
+// GOOD: specific query targeting stored data types
+const good = await client.memory.smartRecall({
+    query: `${contactName} role company background interests preferences`,
+    email,
+    fast_mode: true,
+});
+```
+
+**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.
+
 ## Configuration
 
 | Option | Type | Required | Description |
@@ -315,6 +502,19 @@ const client = new Personize({
 });
 ```
 
+## Migration from 0.5.x
+
+**New in 0.6.0:**
+
+| Feature | Details |
+| :--- | :--- |
+| `tier` on `PromptOptions` | Select generate tier: `basic`, `pro` (default), `ultra` |
+| `tier` on `MemorizeOptions` / `BatchMemorizeOptions` | Select memorize tier: `basic`, `pro`, `pro_fast`, `ultra` |
+| `openrouterApiKey` on `PromptOptions` | BYOK — use your own API key (Pro/Enterprise plans). Requires `model` + `provider`. |
+| `model` / `provider` on `PromptOptions` | Custom model/provider selection. **Requires BYOK** (`openrouterApiKey`). Without BYOK, use `tier`. |
+| `creditsCharged` in response metadata | Credits consumed by the request |
+| SmartGuidelines `mode: 'full'` → `mode: 'deep'` | Renamed for consistency. `'full'` still accepted for backward compatibility. |
+
 ## Migration from 0.3.x
 
 **Breaking changes in 0.4.0:**

package/dist/types.d.ts

@@ -245,8 +245,8 @@ export interface SmartGuidelinesOptions {
     tags?: string[];
     excludeTags?: string[];
     model?: string;
-    /** Routing mode: "fast" for instant embedding-only (~200ms), "full" for deep LLM routing (~3s), "auto" to let the system decide. Default: "auto". */
-    mode?: 'fast' | 'full' | 'auto';
+    /** Routing mode: "fast" for instant embedding-only (~200ms), "deep" for LLM routing (~3s), "auto" to let the system decide. "full" is accepted as alias for "deep". Default: "auto". */
+    mode?: 'fast' | 'deep' | 'full' | 'auto';
     /** Minimum cosine similarity score (0-1) for fast mode results. Lower values return more results. Default: 0.4 for supplementary, 0.7 for critical. */
     minScore?: number;
     /** Session ID for conversation continuity. */
@@ -290,8 +290,10 @@ export interface SmartGuidelinesUsage {
 export type SmartContextUsage = SmartGuidelinesUsage;
 export interface SmartGuidelinesResponse {
     success: boolean;
-    /** Which routing mode was actually used. */
-    mode: 'fast' | 'full';
+    /** Which routing mode was actually used. "full" may appear for backward compat (equivalent to "deep"). */
+    mode: 'fast' | 'deep' | 'full';
+    /** Credits charged for this request. */
+    creditsCharged?: number;
     /** LLM analysis of the task. Null in fast mode. */
     analysis?: SmartGuidelinesAnalysis | null;
     selection: SmartGuidelinesSelection[];
@@ -389,8 +391,14 @@ export interface PromptOptions {
         maxSteps?: number;
     }>;
     stream?: boolean;
+    /** LLM model. Requires BYOK (`openrouterApiKey`). Without BYOK, use `tier` instead — model is auto-selected. */
     model?: string;
+    /** LLM provider: 'openai' | 'anthropic' | 'google' | 'xai' | 'deepseek' | 'openrouter'. Requires BYOK (`openrouterApiKey`). Without BYOK, provider is auto-selected by tier. */
     provider?: string;
+    /** Generate tier: 'basic' (fast/cheap), 'pro' (balanced, default), 'ultra' (highest quality). Determines default model and credit rate. Used when no BYOK key is provided. */
+    tier?: 'basic' | 'pro' | 'ultra';
+    /** Bring Your Own Key: pass your own OpenRouter (or direct provider) API key. When provided, `model` and `provider` are required. Time-based billing instead of per-token. Requires Pro or Enterprise plan. */
+    openrouterApiKey?: string;
     context?: string;
     sessionId?: string;
     /**
@@ -441,6 +449,12 @@ export interface PromptResponse {
     metadata?: {
         model: string;
         provider: string;
+        /** Generate tier used for billing. */
+        tier?: 'basic' | 'pro' | 'ultra';
+        /** Credits charged for this request. 1 credit = $0.01. */
+        creditsCharged?: number;
+        /** True when BYOK (Bring Your Own Key) billing was applied. */
+        byok?: boolean;
         usage?: {
             promptTokens: number;
             completionTokens: number;
@@ -521,6 +535,8 @@ export interface AgentRunOptions {
 export interface MemorizeOptions {
     /** Content to memorize. */
     content: string;
+    /** Memorize tier: 'basic' (fast), 'pro' (balanced, default), 'pro_fast' (pro speed), 'ultra' (highest extraction). */
+    tier?: 'basic' | 'pro' | 'pro_fast' | 'ultra';
     /** Speaker/source label. */
     speaker?: string;
     /** Timestamp of the content. */
@@ -535,6 +551,16 @@ export interface MemorizeOptions {
     email?: string;
     /** Website URL for CRM linking. */
     website_url?: string;
+    /** Entity type (e.g. 'Contact', 'Company', 'Student', 'Webpage'). */
+    type?: string;
+    /**
+     * Custom key name — for entity types with domain-specific unique IDs.
+     * Examples: 'studentNumber', 'linkedinUrl', 'employeeId', 'pageUrl', 'productSku'.
+     * Used with customKeyValue to identify the record when email/websiteUrl don't apply.
+     */
+    customKeyName?: string;
+    /** Custom key value — the unique identifier value (e.g. 'S12345', 'https://linkedin.com/in/johndoe'). */
+    customKeyValue?: string;
     /** Enable enhanced dual extraction (structured + free-form). */
     enhanced?: boolean;
     /** Tags for property selection. */
@@ -571,6 +597,10 @@ export interface SmartRecallOptions {
     websiteUrl?: string;
     /** Entity type filter (e.g. 'Contact', 'Company'). */
     type?: string;
+    /** Custom key name — for entity types with domain-specific unique IDs. */
+    customKeyName?: string;
+    /** Custom key value — the unique identifier value. */
+    customKeyValue?: string;
     /** Scope results to specific collections by ID. */
     collectionIds?: string[];
     /** Scope results to specific collections by name (resolved server-side, case-insensitive). */
@@ -594,6 +624,11 @@ export interface SmartRecallOptions {
      * In fast_mode, defaults to 0.3 if not specified.
      */
     min_score?: number;
+    /**
+     * Guarantee at least this many results even if they fall below min_score.
+     * In fast_mode, defaults to 10. Set to 0 to disable (strict score cutoff).
+     */
+    min_results?: number;
     /** Metadata filters for narrowing results. */
     filters?: Record<string, unknown>;
 }
@@ -614,6 +649,10 @@ export interface RecallOptions {
     website_url?: string;
     /** Website URL (camelCase alias). */
     websiteUrl?: string;
+    /** Custom key name — for entity types with domain-specific unique IDs. */
+    customKeyName?: string;
+    /** Custom key value — the unique identifier value. */
+    customKeyValue?: string;
     /** Additional filters. */
     filters?: Record<string, unknown>;
 }
@@ -628,12 +667,19 @@ export interface BatchMemorizePropertyMapping {
     extractMemories?: boolean;
 }
 export interface BatchMemorizeMapping {
-    /** Entity type (e.g. 'contact', 'company') */
+    /** Entity type (e.g. 'contact', 'company', 'Student', 'Webpage') */
     entityType: string;
     /** Source field name that contains the email (e.g. 'email') */
     email?: string;
     /** Source field name that contains the website URL (e.g. 'company_website_url') */
     website?: string;
+    /**
+     * Custom key name — the identifier name for custom entity types (e.g. 'studentNumber', 'linkedinUrl').
+     * Use with `customKey` to specify which source field holds the identifier value.
+     */
+    customKeyName?: string;
+    /** Source field name that contains the custom key value (e.g. 'student_id', 'linkedin_url') */
+    customKey?: string;
     /** Run name for tracking (e.g. 'hubspot Sync (contact) - <uuid>') */
     runName?: string;
     /** Property mappings: target property name → mapping config */
@@ -642,6 +688,8 @@ export interface BatchMemorizeMapping {
 export interface BatchMemorizeOptions {
     /** Source system label (e.g. 'Hubspot', 'Salesforce') */
     source: string;
+    /** Memorize tier: 'basic' | 'pro' | 'pro_fast' | 'ultra'. Default: 'pro'. */
+    tier?: 'basic' | 'pro' | 'pro_fast' | 'ultra';
     /** Mapping configuration for the sync */
     mapping: BatchMemorizeMapping;
     /** Array of source data rows (key-value objects matching sourceField names) */

package/package.json

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