@personize/sdk 0.4.0 → 0.5.1

package/README.md

@@ -1,6 +1,6 @@
 # Personize SDK
 
-The official Node.js/TypeScript SDK for the Personize Product API. Authenticate with your secret key to access variables, smart context, RAG memory, prompt execution, agents, and evaluation tools.
+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.
 
 ## Installation
 
@@ -36,7 +36,7 @@ console.log(me.data.plan.limits);
 | GET | `/api/v1/test` | `client.test()` |
 | GET | `/api/v1/me` | `client.me()` |
 | **AI** | | |
-| POST | `/api/v1/ai/smart-context` | `client.ai.smartContext(opts)` |
+| POST | `/api/v1/ai/smart-guidelines` | `client.ai.smartGuidelines(opts)` |
 | POST | `/api/v1/prompt` | `client.ai.prompt(opts)` |
 | **Memory** | | |
 | POST | `/api/v1/memorize` | `client.memory.memorize(opts)` |
@@ -47,14 +47,14 @@ console.log(me.data.plan.limits);
 | POST | `/api/v1/upsert` | `client.memory.upsertBatch(opts)` |
 | POST | `/api/v1/batch-memorize` | `client.memory.memorizeBatch(opts)` |
 | POST | `/api/v1/smart-memory-digest` | `client.memory.smartDigest(opts)` |
-| **Variables** | | |
-| GET | `/api/v1/variables` | `client.variables.list()` |
-| POST | `/api/v1/variables` | `client.variables.create(payload)` |
-| GET | `/api/v1/variables/:id/structure` | `client.variables.getStructure(id)` |
-| GET | `/api/v1/variables/:id/section` | `client.variables.getSection(id, opts)` |
-| PATCH | `/api/v1/variables/:id` | `client.variables.update(id, payload)` |
-| DELETE | `/api/v1/variables/:id` | `client.variables.delete(id)` |
-| GET | `/api/v1/actions/:id/history` | `client.variables.history(id)` |
+| **Guidelines** | | |
+| GET | `/api/v1/guidelines` | `client.guidelines.list()` |
+| POST | `/api/v1/guidelines` | `client.guidelines.create(payload)` |
+| GET | `/api/v1/guidelines/:id/structure` | `client.guidelines.getStructure(id)` |
+| GET | `/api/v1/guidelines/:id/section` | `client.guidelines.getSection(id, opts)` |
+| PATCH | `/api/v1/guidelines/:id` | `client.guidelines.update(id, payload)` |
+| DELETE | `/api/v1/guidelines/:id` | `client.guidelines.delete(id)` |
+| GET | `/api/v1/actions/:id/history` | `client.guidelines.history(id)` |
 | **Collections** | | |
 | GET | `/api/v1/collections` | `client.collections.list()` |
 | POST | `/api/v1/collections` | `client.collections.create(payload)` |
@@ -72,35 +72,35 @@ All endpoints require `Authorization: Bearer sk_live_...` and count against your
 
 ## Usage
 
-### Variables
+### Guidelines
 
 ```typescript
-// List all variables
-const vars = await client.variables.list();
+// List all guidelines
+const vars = await client.guidelines.list();
 
-// Create a variable
-await client.variables.create({ name: 'ICP', value: '...', tags: ['sales'] });
+// Create a guideline
+await client.guidelines.create({ name: 'ICP', value: '...', tags: ['sales'] });
 
-// Update a variable
-await client.variables.update(variableId, { value: 'new content' });
+// Update a guideline
+await client.guidelines.update(guidelineId, { value: 'new content' });
 
-// Get variable structure (headings)
-const structure = await client.variables.getStructure(variableId);
+// Get guideline structure (headings)
+const structure = await client.guidelines.getStructure(guidelineId);
 
 // Get a specific section
-const section = await client.variables.getSection(variableId, { header: '## Pricing' });
+const section = await client.guidelines.getSection(guidelineId, { header: '## Pricing' });
 
-// Delete a variable
-await client.variables.delete(variableId);
+// Delete a guideline
+await client.guidelines.delete(guidelineId);
 
 // Version history
-const history = await client.variables.history(variableId, { limit: 5 });
+const history = await client.guidelines.history(guidelineId, { limit: 5 });
 ```
 
-### Smart Context
+### Smart Guidelines
 
 ```typescript
-const ctx = await client.ai.smartContext({
+const ctx = await client.ai.smartGuidelines({
     message: 'Write a sales sequence for our top 3 ICPs',
     tags: ['sales'],
     excludeTags: ['internal'],
@@ -307,7 +307,7 @@ console.log(evaluation.data.summary.propertiesOptimized);
 | Option | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | `secretKey` | string | Yes | Your secret key (`sk_live_...`). |
-| `baseURL` | string | No | Custom API endpoint (default: `https://api.personize.ai`). |
+| `baseURL` | string | No | Custom API endpoint (default: `https://agent.personize.ai`). |
 | `timeout` | number | No | Request timeout in ms (default: `30000`). |
 | `maxRetries` | number | No | Max retry attempts for 429/5xx errors (default: `3`). |
 | `retryDelay` | number | No | Base delay in ms for exponential backoff (default: `1000`). |
@@ -340,75 +340,16 @@ const client = new Personize({
 - `client.memory.search(opts)` — Search/filter records with `property`-based conditions
 - `client.evaluate.memorizationAccuracy(opts)` — Three-phase memorization evaluation
 - `attachments` on `PromptOptions` — Multimodal support (images, PDFs, documents)
-- `sessionId` on `SmartContextOptions` — Progressive context delivery across multi-step workflows
+- `sessionId` on `SmartGuidelinesOptions` — Progressive context delivery across multi-step workflows
 - New fields on `MemorizeOptions`: `collectionIds`, `skipStorage`, `skipDualWrite`, `skipPropertySelection`
 - New fields on `SmartRecallOptions`: `max_reflection_rounds`, `filters`
 
 ## Skills
 
-The SDK ships with AI-assistant skills in `skills/` that teach Claude Code, Codex, and Cursor how to use the SDK for common workflows.
+AI-assistant skills for Claude Code, Codex, and Cursor are available separately:
 
-### Integration Builder (`skills/integrations/`)
-
-Build CRM/database sync integrations. Connect Salesforce, HubSpot, Postgres, or any data source to Personize memory with batch memorization and scheduled deployment.
-
-```
-skills/integrations/
-├── CLAUDE.md                  # Main skill instructions
-├── templates/
-│   ├── salesforce.md          # Salesforce connector pattern
-│   ├── hubspot.md             # HubSpot connector pattern
-│   └── postgres.md            # Postgres/MySQL pattern
-└── deploy/
-    ├── Dockerfile             # Container deployment
-    ├── render.yaml            # Render cron service
-    └── github-action.yml      # GitHub Actions schedule
-```
-
-### Governance (`skills/governance/`)
-
-Manage variables as code — maintain a `governance/variables/` folder of `.md` files and sync them to the Personize API.
-
-```
-skills/governance/
-├── CLAUDE.md                  # Main skill instructions
-├── sync.ts                    # CLI sync script
-└── github-action.yml          # CI sync on push
-```
-
-### AI Content Pipelines (`skills/content-pipelines/`)
-
-Build intelligent, memory-powered AI systems that follow a 10-step agentic loop: **Observe → Remember → Recall → Reason → Plan → Decide → Generate → Act → Update → Repeat**. Includes ready-to-run recipe scripts for product intelligence memorization, smart notifications, web page personalization, cold outreach, and more — plus channel delivery templates for SendGrid, Slack, Twilio, and generic webhooks.
-
-```
-skills/content-pipelines/
-├── CLAUDE.md                              # Main skill instructions (10-step loop)
-├── recipes/
-│   ├── product-intelligence.ts            # Memorize everything: usage, ML, searches, content, uploads, telemetry
-│   ├── smart-notification.ts              # Uniquely personalized alerts via smartDigest
-│   ├── web-personalization.ts             # AI generates UI variable values for personalized web pages
-│   ├── cold-outreach-sequence.ts          # 3-email cold outreach with sequence tracking
-│   ├── meeting-prep-brief.ts              # On-demand meeting prep brief generator
-│   ├── product-usage-alert.ts             # Usage monitoring + smart alerts
-│   ├── health-check-message.ts            # Customer health assessment + check-in
-│   └── batch-pipeline.ts                  # Configurable generic batch pipeline
-└── channels/
-    ├── sendgrid.md                        # Email delivery (SendGrid, SES, Resend)
-    ├── slack.md                           # Slack webhooks + Web API
-    ├── twilio.md                          # SMS + WhatsApp via Twilio
-    └── webhook.md                         # Generic HTTP POST (in-app, CRM, Zapier)
+```bash
+npx skills add personizeai/personize-skills --all
 ```
 
-### n8n Workflow Builder (`skills/n8n-workflows/`)
-
-Generate importable n8n workflow JSON files that sync data between Personize and 400+ apps — no code required. Supports batch sync in (source → Personize), sync out (Personize → destination), webhook-triggered real-time ingestion, and per-record AI enrichment.
-
-```
-skills/n8n-workflows/
-├── CLAUDE.md                                # Main skill instructions
-└── templates/
-    ├── hubspot-to-personize.json            # HubSpot contacts → Personize
-    ├── gsheets-to-personize.json            # Google Sheets → Personize
-    ├── webhook-to-personize.json            # Webhook → Personize (real-time)
-    └── personize-to-slack.json              # Personize → Slack digest
-```
+See [personizeai/personize-skills](https://github.com/personizeai/personize-skills) for the full catalog.

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { PersonizeConfig, ApiResponse, MeResponse, TestResponse, ListOptions, VariablesResponse, VariableSectionOptions, VariableUpdatePayload, VariableCreatePayload, VariableHistoryResponse, VariableHistoryOptions, CollectionsResponse, CollectionCreatePayload, CollectionUpdatePayload, CollectionHistoryOptions, CollectionHistoryResponse, SmartContextOptions, SmartContextResponse, PromptOptions, PromptResponse, AgentRunOptions, AgentResponse, MemorizeOptions, SmartRecallOptions, RecallOptions, SearchOptions, SearchResponse, UpsertOptions, UpsertBatchOptions, 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, AgentRunOptions, AgentResponse, MemorizeOptions, SmartRecallOptions, RecallOptions, SearchOptions, SearchResponse, UpsertOptions, UpsertBatchOptions, BatchMemorizeOptions, SmartDigestOptions, SmartDigestResponse, EvaluateMemorizationOptions, EvaluateMemorizationResponse } from './types';
 export declare class Personize {
     private client;
     private _organizationId?;
@@ -16,36 +16,36 @@ export declare class Personize {
      * GET /api/v1/me — Current context (org, user, plan)
      */
     me(): Promise<ApiResponse<MeResponse>>;
-    variables: {
+    guidelines: {
         /**
-         * GET /api/v1/variables — List variables for the organization (paginated).
+         * GET /api/v1/guidelines — List guidelines for the organization (paginated).
          * Pass `limit` and `nextToken` for cursor-based pagination.
          */
-        list: (options?: ListOptions) => Promise<ApiResponse<VariablesResponse>>;
+        list: (options?: ListOptions) => Promise<ApiResponse<GuidelinesResponse>>;
         /**
-         * GET /api/v1/variables/:id/structure — Get variable headings
+         * GET /api/v1/guidelines/:id/structure — Get guideline headings
          */
         getStructure: (id: string) => Promise<ApiResponse>;
         /**
-         * GET /api/v1/variables/:id/section — Get a section of a variable by header
+         * GET /api/v1/guidelines/:id/section — Get a section of a guideline by header
          */
-        getSection: (id: string, options: VariableSectionOptions) => Promise<ApiResponse>;
+        getSection: (id: string, options: GuidelineSectionOptions) => Promise<ApiResponse>;
         /**
-         * PATCH /api/v1/variables/:id — Partial update to a variable
+         * PATCH /api/v1/guidelines/:id — Partial update to a guideline
          */
-        update: (id: string, payload: VariableUpdatePayload) => Promise<ApiResponse>;
+        update: (id: string, payload: GuidelineUpdatePayload) => Promise<ApiResponse>;
         /**
-         * POST /api/v1/variables — Create a new variable
+         * POST /api/v1/guidelines — Create a new guideline
          */
-        create: (payload: VariableCreatePayload) => Promise<ApiResponse>;
+        create: (payload: GuidelineCreatePayload) => Promise<ApiResponse>;
         /**
-         * DELETE /api/v1/variables/:id — Delete a variable
+         * DELETE /api/v1/guidelines/:id — Delete a guideline
          */
         delete: (id: string) => Promise<ApiResponse>;
         /**
-         * GET /api/v1/actions/:id/history — Get version history for a variable
+         * GET /api/v1/actions/:id/history — Get version history for a guideline
          */
-        history: (id: string, options?: VariableHistoryOptions) => Promise<ApiResponse<VariableHistoryResponse>>;
+        history: (id: string, options?: GuidelineHistoryOptions) => Promise<ApiResponse<GuidelineHistoryResponse>>;
     };
     collections: {
         /**
@@ -73,9 +73,9 @@ export declare class Personize {
     };
     ai: {
         /**
-         * POST /api/v1/ai/smart-context — Semantic context routing
+         * POST /api/v1/ai/smart-guidelines — Smart guidelines routing. Selects relevant organizational guidelines for a task.
          */
-        smartContext: (options: SmartContextOptions) => Promise<ApiResponse<SmartContextResponse>>;
+        smartGuidelines: (options: SmartGuidelinesOptions) => Promise<ApiResponse<SmartGuidelinesResponse>>;
         /**
          * POST /api/v1/prompt — Execute a prompt with tools, output extraction, and evaluation.
          *

package/dist/client.js

@@ -8,9 +8,9 @@ const axios_1 = __importDefault(require("axios"));
 const errors_1 = require("./errors");
 class Personize {
     constructor(config) {
-        this.variables = {
+        this.guidelines = {
             /**
-             * GET /api/v1/variables — List variables for the organization (paginated).
+             * GET /api/v1/guidelines — List guidelines for the organization (paginated).
              * Pass `limit` and `nextToken` for cursor-based pagination.
              */
             list: async (options) => {
@@ -25,32 +25,32 @@ class Personize {
                     params.tags = Array.isArray(options.tags) ? options.tags.join(',') : options.tags;
                 if (options?.excludeTags)
                     params.excludeTags = Array.isArray(options.excludeTags) ? options.excludeTags.join(',') : options.excludeTags;
-                const response = await this.client.get('/api/v1/variables', { params });
+                const response = await this.client.get('/api/v1/guidelines', { params });
                 return response.data;
             },
             /**
-             * GET /api/v1/variables/:id/structure — Get variable headings
+             * GET /api/v1/guidelines/:id/structure — Get guideline headings
              */
             getStructure: async (id) => {
-                const response = await this.client.get(`/api/v1/variables/${id}/structure`);
+                const response = await this.client.get(`/api/v1/guidelines/${id}/structure`);
                 return response.data;
             },
             /**
-             * GET /api/v1/variables/:id/section — Get a section of a variable by header
+             * GET /api/v1/guidelines/:id/section — Get a section of a guideline by header
              */
             getSection: async (id, options) => {
-                const response = await this.client.get(`/api/v1/variables/${id}/section`, {
+                const response = await this.client.get(`/api/v1/guidelines/${id}/section`, {
                     params: { header: options.header },
                 });
                 return response.data;
             },
             /**
-             * PATCH /api/v1/variables/:id — Partial update to a variable
+             * PATCH /api/v1/guidelines/:id — Partial update to a guideline
              */
             update: async (id, payload) => {
                 const organizationId = await this.getOrganizationId();
                 const { historyNote, ...rest } = payload;
-                const response = await this.client.patch(`/api/v1/variables/${id}`, {
+                const response = await this.client.patch(`/api/v1/guidelines/${id}`, {
                     organizationId,
                     historyNote,
                     payload: rest,
@@ -58,21 +58,21 @@ class Personize {
                 return response.data;
             },
             /**
-             * POST /api/v1/variables — Create a new variable
+             * POST /api/v1/guidelines — Create a new guideline
              */
             create: async (payload) => {
-                const response = await this.client.post('/api/v1/variables', payload);
+                const response = await this.client.post('/api/v1/guidelines', payload);
                 return response.data;
             },
             /**
-             * DELETE /api/v1/variables/:id — Delete a variable
+             * DELETE /api/v1/guidelines/:id — Delete a guideline
              */
             delete: async (id) => {
-                const response = await this.client.delete(`/api/v1/variables/${id}`);
+                const response = await this.client.delete(`/api/v1/guidelines/${id}`);
                 return response.data;
             },
             /**
-             * GET /api/v1/actions/:id/history — Get version history for a variable
+             * GET /api/v1/actions/:id/history — Get version history for a guideline
              */
             history: async (id, options) => {
                 const organizationId = await this.getOrganizationId();
@@ -141,10 +141,10 @@ class Personize {
         };
         this.ai = {
             /**
-             * POST /api/v1/ai/smart-context — Semantic context routing
+             * POST /api/v1/ai/smart-guidelines — Smart guidelines routing. Selects relevant organizational guidelines for a task.
              */
-            smartContext: async (options) => {
-                const response = await this.client.post('/api/v1/ai/smart-context', options);
+            smartGuidelines: async (options) => {
+                const response = await this.client.post('/api/v1/ai/smart-guidelines', options);
                 return response.data;
             },
             /**
@@ -285,7 +285,7 @@ class Personize {
         this.maxRetries = config.maxRetries ?? 3;
         this.retryDelay = config.retryDelay ?? 1000;
         this.client = axios_1.default.create({
-            baseURL: config.baseURL || 'https://api.personize.ai',
+            baseURL: config.baseURL || 'https://agent.personize.ai',
             timeout: config.timeout ?? 30000,
             headers: {
                 'Authorization': `Bearer ${config.secretKey}`,

package/dist/types.d.ts

@@ -58,24 +58,37 @@ export interface ListOptions {
     /** When true, strip the full `value` field for lighter payloads. */
     summary?: boolean;
 }
-export interface VariablesResponse {
+/** Inferred governance scope for a guideline — determines when it is proactively included in SmartContext results. */
+export interface GovernanceScope {
+    /** True if this guideline applies to virtually all agent tasks (e.g., core company values, universal compliance). */
+    alwaysOn: boolean;
+    /** Action/domain keywords that trigger inclusion (e.g., "email", "pricing", "deploy"). */
+    triggerKeywords: string[];
+}
+export interface GuidelinesResponse {
     actions: Array<{
         id: string;
         type: string;
         payload: {
             name: string;
             value: string;
-            [key: string]: PropertyValue;
+            /** Auto-inferred governance scope (read-only). Present when the guideline has been analyzed. */
+            governanceScope?: GovernanceScope;
+            [key: string]: PropertyValue | GovernanceScope | string[] | undefined;
         };
     }>;
     count: number;
     /** Cursor for the next page. Undefined when on the last page. */
     nextToken?: string;
 }
-export interface VariableSectionOptions {
+/** @deprecated Use GuidelinesResponse instead. */
+export type VariablesResponse = GuidelinesResponse;
+export interface GuidelineSectionOptions {
     header: string;
 }
-export interface VariableUpdatePayload {
+/** @deprecated Use GuidelineSectionOptions instead. */
+export type VariableSectionOptions = GuidelineSectionOptions;
+export interface GuidelineUpdatePayload {
     name?: string;
     value?: string;
     description?: string;
@@ -86,14 +99,18 @@ export interface VariableUpdatePayload {
     separator?: string;
     historyNote?: string;
 }
-export interface VariableCreatePayload {
+/** @deprecated Use GuidelineUpdatePayload instead. */
+export type VariableUpdatePayload = GuidelineUpdatePayload;
+export interface GuidelineCreatePayload {
     name: string;
     value?: string;
     description?: string;
     tags?: string[];
     secure?: boolean;
 }
-export interface VariableHistoryEntry {
+/** @deprecated Use GuidelineCreatePayload instead. */
+export type VariableCreatePayload = GuidelineCreatePayload;
+export interface GuidelineHistoryEntry {
     id: string;
     originalActionId: string;
     type: string;
@@ -109,16 +126,22 @@ export interface VariableHistoryEntry {
         [key: string]: PropertyValue;
     };
 }
-export interface VariableHistoryResponse {
+/** @deprecated Use GuidelineHistoryEntry instead. */
+export type VariableHistoryEntry = GuidelineHistoryEntry;
+export interface GuidelineHistoryResponse {
     actionId: string;
-    history: VariableHistoryEntry[];
+    history: GuidelineHistoryEntry[];
     count: number;
 }
-export interface VariableHistoryOptions {
+/** @deprecated Use GuidelineHistoryResponse instead. */
+export type VariableHistoryResponse = GuidelineHistoryResponse;
+export interface GuidelineHistoryOptions {
     /** Max number of history records to return (default: 20, max: 50).
      * Each entry includes the full variable content snapshot, so use a small limit (3-5) in token-sensitive contexts. */
     limit?: number;
 }
+/** @deprecated Use GuidelineHistoryOptions instead. */
+export type VariableHistoryOptions = GuidelineHistoryOptions;
 export interface CollectionsResponse {
     actions: Array<{
         id: string;
@@ -213,9 +236,12 @@ export interface CollectionHistoryResponse {
         changes: CollectionPropertyDiff;
     }>;
 }
-export interface SmartContextOptions {
+export interface SmartGuidelinesOptions {
     message: string;
-    variableIds?: string[];
+    /** Filter to specific guideline IDs. */
+    guidelineIds?: string[];
+    /** Resolve guideline names to IDs server-side (case-insensitive match). */
+    guidelineNames?: string[];
     tags?: string[];
     excludeTags?: string[];
     model?: string;
@@ -226,13 +252,17 @@ export interface SmartContextOptions {
     /** Session ID for conversation continuity. */
     sessionId?: string;
 }
-export interface SmartContextAnalysis {
+/** @deprecated Use SmartGuidelinesOptions instead. */
+export type SmartContextOptions = SmartGuidelinesOptions;
+export interface SmartGuidelinesAnalysis {
     taskUnderstanding: string;
     qualityDimensions: string[];
     refinedTask: string;
 }
-export interface SmartContextSelection {
-    variableId: string;
+/** @deprecated Use SmartGuidelinesAnalysis instead. */
+export type SmartContextAnalysis = SmartGuidelinesAnalysis;
+export interface SmartGuidelinesSelection {
+    guidelineId: string;
     name?: string;
     score?: number;
     reason?: string;
@@ -242,10 +272,12 @@ export interface SmartContextSelection {
     mode?: string;
     sections?: string[];
 }
-export interface SmartContextUsage {
+/** @deprecated Use SmartGuidelinesSelection instead. */
+export type SmartContextSelection = SmartGuidelinesSelection;
+export interface SmartGuidelinesUsage {
     durationMs: number;
     tokensUsed?: number;
-    variablesScanned?: number;
+    guidelinesScanned?: number;
     selectedCount?: number;
     preFilter?: {
         total: number;
@@ -254,17 +286,21 @@ export interface SmartContextUsage {
         durationMs: number;
     };
 }
-export interface SmartContextResponse {
+/** @deprecated Use SmartGuidelinesUsage instead. */
+export type SmartContextUsage = SmartGuidelinesUsage;
+export interface SmartGuidelinesResponse {
     success: boolean;
     /** Which routing mode was actually used. */
     mode: 'fast' | 'full';
     /** LLM analysis of the task. Null in fast mode. */
-    analysis?: SmartContextAnalysis | null;
-    selection: SmartContextSelection[];
-    supplementary?: SmartContextSelection[];
+    analysis?: SmartGuidelinesAnalysis | null;
+    selection: SmartGuidelinesSelection[];
+    supplementary?: SmartGuidelinesSelection[];
     compiledContext: string;
-    usage: SmartContextUsage;
+    usage: SmartGuidelinesUsage;
 }
+/** @deprecated Use SmartGuidelinesResponse instead. */
+export type SmartContextResponse = SmartGuidelinesResponse;
 /**
  * Per-MCP tool selection override.
  * Use enabledTools for an explicit allowlist, or disabledTools for a denylist.
@@ -274,6 +310,38 @@ export interface McpToolSelection {
     enabledTools?: string[];
     disabledTools?: string[];
 }
+/**
+ * An attachment sent alongside a prompt or agent run.
+ *
+ * Two modes:
+ * - **Inline (base64):** `data` contains the raw base64-encoded content.
+ * - **URL reference:** `url` points to a publicly-accessible or presigned URL.
+ *
+ * At least one of `data` or `url` must be provided.
+ */
+export interface Attachment {
+    /** Human-readable filename (e.g. "screenshot.png"). Max 255 chars. */
+    name?: string;
+    /** MIME type (e.g. "image/png", "application/pdf"). Must be a supported type. */
+    mimeType: string;
+    /** Base64-encoded content. Required if `url` is not provided. */
+    data?: string;
+    /** Publicly-accessible URL to the content. Required if `data` is not provided. */
+    url?: string;
+}
+/**
+ * Supported MIME types for attachments.
+ *
+ * Images: image/png, image/jpeg, image/gif, image/webp, image/svg+xml
+ * Documents: application/pdf, text/plain, text/csv, text/html, text/markdown, application/json
+ */
+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"];
+/** Max attachments per request. */
+export declare const MAX_ATTACHMENTS_COUNT = 10;
+/** Max size per attachment in bytes (20 MB). */
+export declare const MAX_ATTACHMENT_SIZE_BYTES: number;
+/** Max total attachment payload in bytes (50 MB). */
+export declare const MAX_TOTAL_ATTACHMENTS_BYTES: number;
 /** Auto-memorize configuration for /prompt. */
 export interface PromptMemorizeConfig {
     /** Contact email identifier. */
@@ -286,7 +354,7 @@ export interface PromptMemorizeConfig {
     type?: 'Contact' | 'Company' | 'User';
     /**
      * When true, tool results from research tools (search_companies, tavily, etc.)
-     * are automatically captured and memorized. Meta tools (smart_context,
+     * are automatically captured and memorized. Meta tools (smart_guidelines,
      * recall_pro, memorize_pro, store_evaluation_log) are excluded.
      */
     captureToolResults?: boolean;
@@ -443,6 +511,12 @@ export interface AgentRunOptions {
     recordId?: string;
     /** Per-MCP tool selection override (allowlist or denylist per MCP) */
     mcpTools?: McpToolSelection[];
+    /**
+     * Images or documents to send with the agent run (multimodal input).
+     *
+     * Limits: max 10 attachments, 20 MB each, 50 MB total.
+     */
+    attachments?: Attachment[];
 }
 export interface MemorizeOptions {
     /** Content to memorize. */
@@ -493,6 +567,10 @@ export interface SmartRecallOptions {
     website_url?: string;
     /** Entity type filter (e.g. 'Contact', 'Company'). */
     type?: string;
+    /** Scope results to specific collections by ID. */
+    collectionIds?: string[];
+    /** Scope results to specific collections by name (resolved server-side, case-insensitive). */
+    collectionNames?: string[];
     /** Return schema-enforced property values separately from free-form memories. */
     include_property_values?: boolean;
     /** Enable reflection loop to improve recall coverage (default: true). */

package/dist/types.js

@@ -1,3 +1,22 @@
 "use strict";
 // --- Utility Types ---
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_TOTAL_ATTACHMENTS_BYTES = exports.MAX_ATTACHMENT_SIZE_BYTES = exports.MAX_ATTACHMENTS_COUNT = exports.SUPPORTED_ATTACHMENT_TYPES = void 0;
+/**
+ * Supported MIME types for attachments.
+ *
+ * Images: image/png, image/jpeg, image/gif, image/webp, image/svg+xml
+ * Documents: application/pdf, text/plain, text/csv, text/html, text/markdown, application/json
+ */
+exports.SUPPORTED_ATTACHMENT_TYPES = [
+    'image/png', 'image/jpeg', 'image/gif', 'image/webp', 'image/svg+xml',
+    'application/pdf',
+    'text/plain', 'text/csv', 'text/html', 'text/markdown',
+    'application/json',
+];
+/** Max attachments per request. */
+exports.MAX_ATTACHMENTS_COUNT = 10;
+/** Max size per attachment in bytes (20 MB). */
+exports.MAX_ATTACHMENT_SIZE_BYTES = 20 * 1024 * 1024;
+/** Max total attachment payload in bytes (50 MB). */
+exports.MAX_TOTAL_ATTACHMENTS_BYTES = 50 * 1024 * 1024;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@personize/sdk",
-    "version": "0.4.0",
+    "version": "0.5.1",
     "description": "Official Personize SDK",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -18,11 +18,11 @@
     },
     "repository": {
         "type": "git",
-        "url": "https://github.com/hataheri/personize-sdk.git"
+        "url": "https://github.com/personizeai/personize-sdk.git"
     },
     "homepage": "https://personize.ai",
     "bugs": {
-        "url": "https://github.com/hataheri/personize-sdk/issues"
+        "url": "https://github.com/personizeai/personize-sdk/issues"
     },
     "keywords": [
         "personize",