@personize/sdk 0.5.2 → 0.6.1

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: time-based (10 credits base + 10/extra minute) instead of per-token
+// 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,12 @@ 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)
 });
 
 // Direct recall — DynamoDB lookup: properties + freeform memories (no AI, type required)
@@ -296,6 +319,95 @@ 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` | 0.2 | 0.4 | High-volume, simple tasks |
+| `pro` | 0.5 | 1.0 | Balanced quality & cost (default) |
+| `ultra` | 1.0 | 2.5 | Complex reasoning, highest quality |
+
+### Memorize Tiers
+
+| Tier | Credits/1K tokens | Best For |
+| :--- | :--- | :--- |
+| `basic` | 1.0 | Bulk imports, simple data |
+| `pro` | 2.5 | General use (default) |
+| `pro_fast` | 3.5 | Pro quality, lower latency |
+| `ultra` | 7.0 | Maximum extraction quality |
+
+### Retrieval (Recall & Smart Guidelines)
+
+| Operation | Mode | Credits/Call |
+| :--- | :--- | :--- |
+| Smart Recall | `fast_mode: true` | 0.1 |
+| Smart Recall | `fast_mode: false` (deep) | 0.2 |
+| Smart Guidelines | `mode: 'fast'` | 0.1 |
+| Smart Guidelines | `mode: 'deep'` | 0.5 |
+
+1 credit = $0.01.
+
+### Direct Providers
+
+### BYOK (Bring Your Own Key)
+
+Pro and Enterprise plans can pass their own API key. Billing switches to time-based: **10 credits base + 10 credits per additional minute**.
+
+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 time-based billing.
+
+## 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 +427,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. */
@@ -561,10 +577,14 @@ export interface SmartRecallOptions {
     minScore?: number;
     /** CRM record ID for entity scoping. */
     record_id?: string;
+    /** CRM record ID (camelCase alias). */
+    recordId?: string;
     /** Filter results to a specific entity by email. */
     email?: string;
     /** Website URL for entity scoping. */
     website_url?: string;
+    /** Website URL (camelCase alias). */
+    websiteUrl?: string;
     /** Entity type filter (e.g. 'Contact', 'Company'). */
     type?: string;
     /** Scope results to specific collections by ID. */
@@ -590,6 +610,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>;
 }
@@ -602,10 +627,14 @@ export interface RecallOptions {
     type: string;
     /** CRM record ID for entity scoping. */
     record_id?: string;
+    /** CRM record ID (camelCase alias). */
+    recordId?: string;
     /** Filter results to a specific entity by email. */
     email?: string;
     /** Website URL for entity scoping. */
     website_url?: string;
+    /** Website URL (camelCase alias). */
+    websiteUrl?: string;
     /** Additional filters. */
     filters?: Record<string, unknown>;
 }
@@ -634,6 +663,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) */
@@ -646,20 +677,32 @@ export interface BatchMemorizeOptions {
 export interface SmartDigestOptions {
     /** CRM record ID */
     record_id?: string;
+    /** CRM record ID (camelCase alias). */
+    recordId?: string;
     /** Contact email */
     email?: string;
     /** Company website URL */
     website_url?: string;
+    /** Website URL (camelCase alias). */
+    websiteUrl?: string;
     /** Entity type ('Contact', 'Company'). Auto-inferred if omitted. */
     type?: string;
     /** Max tokens for compiled context (default: 1000) */
     token_budget?: number;
+    /** Max tokens (camelCase alias). */
+    tokenBudget?: number;
     /** Max free-form memories to include (default: 20) */
     max_memories?: number;
+    /** Max memories (camelCase alias). */
+    maxMemories?: number;
     /** Include DynamoDB property snapshot (default: true) */
     include_properties?: boolean;
+    /** Include properties (camelCase alias). */
+    includeProperties?: boolean;
     /** Include LanceDB free-form memories (default: true) */
     include_memories?: boolean;
+    /** Include memories (camelCase alias). */
+    includeMemories?: boolean;
 }
 export interface SmartDigestResponse {
     success: boolean;

package/package.json

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