@personize/sdk 0.6.5 → 0.7.0

package/README.md

@@ -109,6 +109,27 @@ const ctx = await client.ai.smartGuidelines({
 console.log(ctx.data.compiledContext);
 ```
 
+#### Content Budget
+
+Control how much guideline content is delivered:
+
+```typescript
+const result = await client.ai.smartGuidelines({
+  message: "write a cold email",
+  maxContentTokens: 5000, // deliver ~2-3 full guidelines, rest as summaries
+});
+
+// Demoted guidelines (over budget) returned with id + description for follow-up
+if (result.data.budgetMetadata?.demotedGuidelines) {
+  for (const g of result.data.budgetMetadata.demotedGuidelines) {
+    // Fetch specific section: client.guidelines.getSection(g.id, { header: "Cold Email" })
+    console.log(`${g.name}: ${g.description} — sections: ${g.sections.join(', ')}`);
+  }
+}
+```
+
+Default: 10,000 tokens. Guidelines too large for the budget are automatically trimmed to relevant sections. Remaining guidelines are returned as summaries with `id`, `description`, and `sections[]` for follow-up via `client.guidelines.getSection()`.
+
 ### Prompt Execution
 
 ```typescript

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, 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';
+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, ResponsesCreateOptions, ResponsesCompletedResult, ChatCompletionsOptions, ChatCompletionResult } from './types';
 export declare class Personize {
     private client;
     private _organizationId?;
@@ -237,4 +237,22 @@ export declare class Personize {
          */
         memorizationAccuracy: (data: EvaluateMemorizationOptions) => Promise<ApiResponse<EvaluateMemorizationResponse>>;
     };
+    responses: {
+        /**
+         * POST /api/v1/responses — Execute step-driven orchestration.
+         *
+         * If tools with execute functions are provided (Record format), the SDK
+         * automatically handles the tool execution loop: execute locally, send
+         * results back, repeat until completed.
+         */
+        create: (options: ResponsesCreateOptions) => Promise<ResponsesCompletedResult>;
+    };
+    chat: {
+        completions: {
+            /**
+             * POST /api/v1/chat/completions — OpenAI-compatible chat completion.
+             */
+            create: (options: ChatCompletionsOptions) => Promise<ChatCompletionResult>;
+        };
+    };
 }

package/dist/client.js

@@ -153,7 +153,13 @@ class Personize {
              * POST /api/v1/ai/smart-guidelines — Smart guidelines routing. Selects relevant organizational guidelines for a task.
              */
             smartGuidelines: async (options) => {
-                const response = await this.client.post('/api/v1/ai/smart-guidelines', options);
+                // Normalize snake_case alias → camelCase
+                const { max_content_tokens, ...rest } = options;
+                const normalized = {
+                    ...rest,
+                    maxContentTokens: rest.maxContentTokens ?? max_content_tokens,
+                };
+                const response = await this.client.post('/api/v1/ai/smart-guidelines', normalized);
                 return response.data;
             },
             /**
@@ -461,6 +467,84 @@ class Personize {
                 return response.data;
             },
         };
+        this.responses = {
+            /**
+             * POST /api/v1/responses — Execute step-driven orchestration.
+             *
+             * If tools with execute functions are provided (Record format), the SDK
+             * automatically handles the tool execution loop: execute locally, send
+             * results back, repeat until completed.
+             */
+            create: async (options) => {
+                // Extract execute functions from tools (they don't get sent to server)
+                let toolSchemas;
+                let executeMap;
+                if (options.tools && !Array.isArray(options.tools)) {
+                    // Record format — extract execute functions
+                    executeMap = new Map();
+                    toolSchemas = [];
+                    for (const [name, def] of Object.entries(options.tools)) {
+                        executeMap.set(name, def.execute);
+                        toolSchemas.push({
+                            type: 'function',
+                            function: { name, description: def.description, parameters: def.parameters },
+                        });
+                    }
+                }
+                else if (Array.isArray(options.tools)) {
+                    toolSchemas = options.tools;
+                }
+                // Build request body (exclude execute functions)
+                const body = { ...options, tools: toolSchemas };
+                // Tool execution loop
+                let maxRounds = 20;
+                while (maxRounds-- > 0) {
+                    const response = await this.client.post('/api/v1/responses', body);
+                    const result = response.data;
+                    if (result.status === 'completed') {
+                        return result;
+                    }
+                    // requires_action — execute tools locally
+                    if (!executeMap || executeMap.size === 0) {
+                        // No execute functions provided — return as-is (caller handles manually)
+                        return result;
+                    }
+                    const toolResults = [];
+                    for (const tc of result.required_action.tool_calls) {
+                        const executeFn = executeMap.get(tc.name);
+                        if (!executeFn) {
+                            toolResults.push({ tool_call_id: tc.id, output: JSON.stringify({ error: `No execute function for tool: ${tc.name}` }) });
+                            continue;
+                        }
+                        try {
+                            const output = await executeFn(tc.args);
+                            toolResults.push({ tool_call_id: tc.id, output: typeof output === 'string' ? output : JSON.stringify(output) });
+                        }
+                        catch (err) {
+                            toolResults.push({ tool_call_id: tc.id, output: JSON.stringify({ error: err.message }) });
+                        }
+                    }
+                    // Send continuation request
+                    body.conversation = result.conversation;
+                    body.conversation_signature = result.conversation_signature;
+                    body.remaining_steps = result.remaining_steps;
+                    body.completed_step_count = result.completed_step_count;
+                    body.tool_results = toolResults;
+                }
+                throw new Error('Tool execution loop exceeded maximum rounds (20)');
+            },
+        };
+        this.chat = {
+            completions: {
+                /**
+                 * POST /api/v1/chat/completions — OpenAI-compatible chat completion.
+                 */
+                create: async (options) => {
+                    const response = await this.client.post('/api/v1/chat/completions', options);
+                    return response.data;
+                },
+            },
+        };
         this.maxRetries = config.maxRetries ?? 3;
         this.retryDelay = config.retryDelay ?? 1000;
         this.client = axios_1.default.create({

package/dist/types.d.ts

@@ -292,6 +292,10 @@ export interface SmartGuidelinesOptions {
     minScore?: number;
     /** Session ID for conversation continuity. */
     sessionId?: string;
+    /** Maximum tokens of guideline content to deliver. The system selects the most relevant guidelines and trims to fit. Default: 10000. */
+    maxContentTokens?: number;
+    /** @deprecated Use maxContentTokens instead. */
+    max_content_tokens?: number;
 }
 /** @deprecated Use SmartGuidelinesOptions instead. */
 export type SmartContextOptions = SmartGuidelinesOptions;
@@ -1367,3 +1371,185 @@ export interface EvaluateMemorizationResponse {
         propertiesAttempted: number;
     };
 }
+export interface StepDefinition {
+    prompt: string;
+    order?: number;
+    tools?: string[];
+    max_steps?: number;
+}
+export interface PersonizeExtensions {
+    governance?: {
+        guideline_ids?: string[];
+        mode?: 'fast' | 'deep';
+    };
+    memory?: {
+        record_id?: string;
+        recall?: boolean;
+    };
+    mcp_integration_ids?: string[];
+    outputs?: Array<{
+        key: string;
+        type: string;
+    }>;
+    memorize?: {
+        record_id?: string;
+        collection?: string;
+        capture_tool_results?: boolean;
+    };
+}
+export interface ClientToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+export interface ResponsesCreateOptions {
+    steps?: StepDefinition[];
+    messages?: Array<{
+        role: string;
+        content: string;
+    }>;
+    tools?: ClientToolDefinition[] | Record<string, {
+        description: string;
+        parameters: Record<string, unknown>;
+        execute: (args: any) => Promise<any>;
+    }>;
+    model?: string;
+    provider?: string;
+    tier?: string;
+    temperature?: number;
+    max_tokens?: number;
+    system_prompt?: string;
+    session_id?: string;
+    llm_api_key?: string;
+    openrouter_api_key?: string;
+    personize?: PersonizeExtensions;
+    attachments?: Array<{
+        name: string;
+        mimeType: string;
+        url?: string;
+        content?: string;
+    }>;
+    conversation?: any[];
+    conversation_signature?: string;
+    remaining_steps?: StepDefinition[];
+    completed_step_count?: number;
+}
+export interface ResponsesToolCall {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+export interface ResponsesStepResult {
+    order: number;
+    text: string;
+    tool_calls: Array<{
+        name: string;
+        args: Record<string, unknown>;
+        result?: unknown;
+    }>;
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+    };
+}
+export interface ResponsesCompletedResult {
+    id: string;
+    status: 'completed';
+    session_id: string;
+    output: Array<{
+        type: string;
+        role: string;
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+    }>;
+    steps: ResponsesStepResult[];
+    outputs?: Record<string, unknown>;
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+    metadata: {
+        tier: string;
+        credits_charged: number;
+        byok?: boolean;
+        model?: string;
+        provider?: string;
+    };
+}
+export interface ResponsesRequiresActionResult {
+    id: string;
+    status: 'requires_action';
+    session_id: string;
+    required_action: {
+        type: 'tool_calls';
+        tool_calls: ResponsesToolCall[];
+    };
+    conversation: any[];
+    remaining_steps: StepDefinition[];
+    completed_step_count: number;
+    conversation_signature: string;
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+export type ResponsesResult = ResponsesCompletedResult | ResponsesRequiresActionResult;
+export interface ChatCompletionsOptions {
+    model?: string;
+    provider?: string;
+    tier?: string;
+    messages: Array<{
+        role: 'system' | 'user' | 'assistant' | 'tool';
+        content: string | null;
+        tool_call_id?: string;
+        tool_calls?: any[];
+    }>;
+    tools?: ClientToolDefinition[];
+    tool_choice?: 'auto' | 'none' | 'required';
+    temperature?: number;
+    max_tokens?: number;
+    llm_api_key?: string;
+    openrouter_api_key?: string;
+    personize?: PersonizeExtensions;
+}
+export interface ChatCompletionChoice {
+    index: number;
+    message: {
+        role: 'assistant';
+        content: string | null;
+        tool_calls?: Array<{
+            id: string;
+            type: 'function';
+            function: {
+                name: string;
+                arguments: string;
+            };
+        }>;
+    };
+    finish_reason: 'stop' | 'tool_calls' | 'length';
+}
+export interface ChatCompletionResult {
+    id: string;
+    object: 'chat.completion';
+    created: number;
+    model: string;
+    choices: ChatCompletionChoice[];
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+    session_id?: string;
+    metadata?: {
+        tier: string;
+        credits_charged: number;
+        byok?: boolean;
+    };
+}

package/package.json

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