illuma-agents 1.0.44 → 1.0.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "illuma-agents",
-  "version": "1.0.44",
+  "version": "1.0.47",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/common/enum.ts

@@ -163,6 +163,7 @@ export enum Callback {
 export enum Constants {
   OFFICIAL_CODE_BASEURL = 'https://api.illuma.ai/v1',
   EXECUTE_CODE = 'execute_code',
+  CREATE_PRESENTATION = 'create_presentation',
   TOOL_SEARCH = 'tool_search',
   PROGRAMMATIC_TOOL_CALLING = 'run_tools_with_code',
   WEB_SEARCH = 'web_search',

package/src/index.ts

@@ -11,8 +11,8 @@ export * from './graphs';
 /* Tools */
 export * from './tools/Calculator';
 export * from './tools/CodeExecutor';
+export * from './tools/PresentationTool';
 export * from './tools/BrowserTools';
-export * from './tools/DesktopTools';
 export * from './tools/ProgrammaticToolCalling';
 export * from './tools/ToolSearch';
 export * from './tools/handlers';

package/src/tools/PresentationTool.ts

@@ -0,0 +1,356 @@
+import { z } from 'zod';
+import { config } from 'dotenv';
+import fetch, { RequestInit } from 'node-fetch';
+import { HttpsProxyAgent } from 'https-proxy-agent';
+import { tool, DynamicStructuredTool } from '@langchain/core/tools';
+import { getEnvironmentVariable } from '@langchain/core/utils/env';
+import type * as t from '@/types';
+import { EnvVar, Constants } from '@/common';
+import { getCodeBaseURL } from './CodeExecutor';
+
+config();
+
+// =============================================================================
+// PRESENTATION TOOL CONSTANTS
+// =============================================================================
+
+const PRESENTATIONS_ENDPOINT = `${getCodeBaseURL()}/presentations/create`;
+
+// =============================================================================
+// SCHEMA DEFINITIONS
+// =============================================================================
+
+/**
+ * Position and size model (matches code-executor PptxPositionModel)
+ */
+const PositionSchema = z.object({
+  left: z.number().describe('Left position in points'),
+  top: z.number().describe('Top position in points'),
+  width: z.number().describe('Width in points'),
+  height: z.number().describe('Height in points'),
+});
+
+/**
+ * Font styling model
+ */
+const FontSchema = z.object({
+  name: z.string().default('Arial').describe('Font family name'),
+  size: z.number().default(16).describe('Font size in points'),
+  italic: z.boolean().optional().describe('Italic text'),
+  color: z.string().default('000000').describe('Hex color without #'),
+  font_weight: z.number().optional().default(400).describe('400 = normal, 600+ = bold'),
+});
+
+/**
+ * Fill/background color model
+ */
+const FillSchema = z.object({
+  color: z.string().describe('Hex color without #'),
+  opacity: z.number().optional().default(1.0),
+});
+
+/**
+ * Spacing/margin model
+ */
+const SpacingSchema = z.object({
+  top: z.number().default(0),
+  bottom: z.number().default(0),
+  left: z.number().default(0),
+  right: z.number().default(0),
+});
+
+/**
+ * Paragraph model
+ */
+const ParagraphSchema = z.object({
+  text: z.string().describe('Text content (can contain basic HTML like <b>, <i>)'),
+  alignment: z.enum(['left', 'center', 'right', 'justify']).optional(),
+  font: FontSchema.optional(),
+  spacing: SpacingSchema.optional(),
+  line_height: z.number().optional(),
+});
+
+/**
+ * Picture source model
+ */
+const PictureSchema = z.object({
+  is_network: z.boolean().default(false).describe('True if path is a URL'),
+  path: z.string().describe('Image file path or URL'),
+});
+
+/**
+ * Object fit settings for images
+ */
+const ObjectFitSchema = z.object({
+  fit: z.enum(['contain', 'cover', 'fill']).optional(),
+  focus: z.array(z.number()).optional().describe('Focus point [x%, y%]'),
+});
+
+/**
+ * Text box shape
+ */
+const TextBoxShapeSchema = z.object({
+  shape_type: z.literal('textbox').default('textbox'),
+  position: PositionSchema,
+  paragraphs: z.array(ParagraphSchema).describe('Text paragraphs in the box'),
+  margin: SpacingSchema.optional(),
+  fill: FillSchema.optional(),
+  text_wrap: z.boolean().optional().default(true),
+});
+
+/**
+ * Auto shape (rectangle, rounded rectangle, etc.)
+ */
+const AutoShapeSchema = z.object({
+  shape_type: z.literal('autoshape').default('autoshape'),
+  autoshape_type: z.string().default('RECTANGLE').describe('Shape type: RECTANGLE, ROUNDED_RECTANGLE, OVAL, etc.'),
+  position: PositionSchema,
+  paragraphs: z.array(ParagraphSchema).optional(),
+  margin: SpacingSchema.optional(),
+  fill: FillSchema.optional(),
+  border_radius: z.number().optional(),
+});
+
+/**
+ * Picture shape
+ */
+const PictureShapeSchema = z.object({
+  shape_type: z.literal('picture').default('picture'),
+  position: PositionSchema,
+  picture: PictureSchema,
+  margin: SpacingSchema.optional(),
+  clip: z.boolean().optional().default(true),
+  opacity: z.number().optional(),
+  shape: z.enum(['rectangle', 'circle']).optional(),
+  object_fit: ObjectFitSchema.optional(),
+});
+
+/**
+ * Connector/line shape
+ */
+const ConnectorSchema = z.object({
+  shape_type: z.literal('connector').default('connector'),
+  connector_type: z.string().default('STRAIGHT').describe('STRAIGHT, ELBOW, CURVE'),
+  position: PositionSchema,
+  thickness: z.number().optional().default(0.5),
+  color: z.string().optional().default('000000'),
+});
+
+/**
+ * Union of all shape types
+ */
+const ShapeSchema = z.discriminatedUnion('shape_type', [
+  TextBoxShapeSchema,
+  AutoShapeSchema,
+  PictureShapeSchema,
+  ConnectorSchema,
+]);
+
+/**
+ * Slide model
+ */
+const SlideSchema = z.object({
+  background: FillSchema.optional().describe('Slide background color'),
+  note: z.string().optional().describe('Speaker notes for this slide'),
+  shapes: z.array(ShapeSchema).describe('Shapes on this slide'),
+});
+
+/**
+ * Brand settings for consistent theming
+ */
+const BrandSettingsSchema = z.object({
+  primary_color: z.string().default('000033').describe('Primary brand color'),
+  secondary_color: z.string().default('666666').describe('Secondary color'),
+  accent_color: z.string().default('0066CC').describe('Accent color'),
+  background_color: z.string().default('FFFFFF').describe('Background color'),
+  font_heading: z.string().default('Arial').describe('Heading font'),
+  font_body: z.string().default('Arial').describe('Body font'),
+  logo_url: z.string().optional().describe('Company logo URL'),
+  company_name: z.string().optional().describe('Company name'),
+  chart_colors: z.array(z.string()).optional().describe('Chart color palette'),
+});
+
+/**
+ * Full presentation model
+ */
+const PresentationSchema = z.object({
+  name: z.string().optional().describe('Presentation name'),
+  width: z.number().default(1280).describe('Slide width in points'),
+  height: z.number().default(720).describe('Slide height in points'),
+  slides: z.array(SlideSchema).describe('Array of slides'),
+  shapes: z.array(ShapeSchema).optional().describe('Global shapes (on all slides)'),
+});
+
+/**
+ * Main tool input schema
+ */
+const CreatePresentationToolSchema = z.object({
+  presentation: PresentationSchema.describe(
+    'The complete presentation structure with slides and shapes'
+  ),
+  brand: BrandSettingsSchema.optional().describe(
+    'Brand settings for consistent theming'
+  ),
+});
+
+// =============================================================================
+// RESPONSE TYPES
+// =============================================================================
+
+interface CreatePresentationResult {
+  success: boolean;
+  file_id: string;
+  filename: string;
+  session_id: string;
+  message?: string;
+}
+
+// =============================================================================
+// TOOL PARAMETERS
+// =============================================================================
+
+export interface PresentationToolParams {
+  apiKey?: string;
+  [EnvVar.CODE_API_KEY]?: string;
+  user_id?: string;
+}
+
+// =============================================================================
+// TOOL CREATION
+// =============================================================================
+
+/**
+ * Creates a presentation generation tool for LangChain agents.
+ * 
+ * This tool allows agents to create PowerPoint presentations by providing
+ * structured slide data. The presentation is generated by the code-executor
+ * service and returned as a downloadable file.
+ * 
+ * Architecture notes:
+ * - Charts and complex visualizations should be rendered as images on the client
+ * - The tool accepts image URLs/paths for chart/table screenshots
+ * - Text boxes, shapes, and images are supported as native PPTX elements
+ */
+function createPresentationTool(
+  params: PresentationToolParams = {}
+): DynamicStructuredTool<typeof CreatePresentationToolSchema> {
+  const apiKey =
+    params[EnvVar.CODE_API_KEY] ??
+    params.apiKey ??
+    getEnvironmentVariable(EnvVar.CODE_API_KEY) ??
+    '';
+  
+  if (!apiKey) {
+    throw new Error('No API key provided for presentation tool.');
+  }
+
+  const description = `
+Create a PowerPoint presentation from structured slide data.
+
+USE THIS TOOL WHEN:
+- User asks for a PowerPoint, PPTX, or presentation file
+- User wants to export content as a presentation
+
+SLIDE STRUCTURE:
+Each slide contains shapes: textbox, autoshape, picture, connector.
+- textbox: Text with paragraphs and formatting
+- autoshape: Colored shapes (rectangles, rounded rectangles) with optional text
+- picture: Images from URLs or file paths
+- connector: Lines and connectors
+
+STANDARD SLIDE DIMENSIONS:
+- Width: 1280 points (13.33 inches)
+- Height: 720 points (7.5 inches)
+
+LAYOUT TIPS:
+- Title: position ~{left: 80, top: 40, width: 1120, height: 80}
+- Content area: position ~{left: 80, top: 140, width: 1120, height: 520}
+- Leave margins of ~80 points on sides
+
+NOTES:
+- Charts/tables should be rendered as images and included via picture shapes
+- Use brand settings for consistent theming across slides
+- Generated file is auto-delivered to the user (no download links needed)
+`.trim();
+
+  return tool<typeof CreatePresentationToolSchema>(
+    async ({ presentation, brand }, config) => {
+      const { session_id } = (config.toolCall ?? {}) as {
+        session_id?: string;
+      };
+
+      const requestBody = {
+        presentation,
+        brand,
+        session_id,
+      };
+
+      try {
+        const fetchOptions: RequestInit = {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'User-Agent': 'Ranger/1.0',
+            'X-API-Key': apiKey,
+          },
+          body: JSON.stringify(requestBody),
+        };
+
+        if (process.env.PROXY != null && process.env.PROXY !== '') {
+          fetchOptions.agent = new HttpsProxyAgent(process.env.PROXY);
+        }
+
+        const response = await fetch(PRESENTATIONS_ENDPOINT, fetchOptions);
+        
+        if (!response.ok) {
+          const errorText = await response.text();
+          throw new Error(`Presentation creation failed: ${response.status} - ${errorText}`);
+        }
+
+        const result: CreatePresentationResult = await response.json();
+        
+        if (!result.success) {
+          throw new Error(`Presentation creation failed: ${result.message}`);
+        }
+
+        const slideCount = presentation.slides.length;
+        const formattedOutput = `
+Presentation created successfully!
+- Slides: ${slideCount}
+- File ID: ${result.file_id}
+- Filename: ${result.filename}
+
+The PowerPoint file is ready for download.
+`.trim();
+
+        // Return content and artifact (like code executor)
+        // The artifact contains file info for client-side handling
+        return [
+          formattedOutput,
+          {
+            session_id: result.session_id,
+            file_id: result.file_id,
+            filename: result.filename,
+            type: 'presentation',
+            files: [{
+              id: result.file_id,
+              name: result.filename,
+            }],
+          },
+        ];
+      } catch (error) {
+        throw new Error(
+          `Presentation creation error:\n\n${(error as Error | undefined)?.message}`
+        );
+      }
+    },
+    {
+      name: Constants.CREATE_PRESENTATION,
+      description,
+      schema: CreatePresentationToolSchema,
+      responseFormat: Constants.CONTENT_AND_ARTIFACT,
+    }
+  );
+}
+
+export { createPresentationTool, CreatePresentationToolSchema };

package/dist/cjs/tools/DesktopTools.cjs

@@ -1,270 +0,0 @@
-'use strict';
-
-var zod = require('zod');
-var tools = require('@langchain/core/tools');
-
-/**
- * Desktop tool names - keep in sync with Ranger Desktop Electron app
- * These tools execute locally in the Electron app, NOT on the server
- */
-const EDesktopTools = {
-    SCREENSHOT: 'computer_screenshot',
-    CLICK: 'computer_click',
-    DOUBLE_CLICK: 'computer_double_click',
-    RIGHT_CLICK: 'computer_right_click',
-    TYPE: 'computer_type',
-    KEY: 'computer_key',
-    KEY_COMBO: 'computer_key_combo',
-    SCROLL: 'computer_scroll',
-    DRAG: 'computer_drag',
-    GET_ACTIVE_WINDOW: 'computer_get_active_window',
-    GET_MOUSE_POSITION: 'computer_get_mouse_position',
-    CLIPBOARD_READ: 'clipboard_read',
-    CLIPBOARD_WRITE: 'clipboard_write',
-    CLIPBOARD_PASTE: 'clipboard_paste',
-    WAIT: 'computer_wait',
-};
-/**
- * Check if desktop capability is available based on request headers or context
- * The Ranger Desktop Electron app sets these headers when connected:
- * - X-Ranger-Desktop: true
- * - X-Ranger-Desktop-Capable: true
- */
-function hasDesktopCapability(req) {
-    if (!req?.headers) {
-        return false;
-    }
-    const desktopApp = req.headers['x-ranger-desktop'];
-    const desktopCapable = req.headers['x-ranger-desktop-capable'];
-    return desktopApp === 'true' || desktopCapable === 'true';
-}
-// Tool schemas
-const ScreenshotSchema = zod.z.object({});
-const ClickSchema = zod.z.object({
-    x: zod.z.number().describe('X coordinate to click'),
-    y: zod.z.number().describe('Y coordinate to click'),
-});
-const DoubleClickSchema = zod.z.object({
-    x: zod.z.number().describe('X coordinate to double-click'),
-    y: zod.z.number().describe('Y coordinate to double-click'),
-});
-const RightClickSchema = zod.z.object({
-    x: zod.z.number().describe('X coordinate to right-click'),
-    y: zod.z.number().describe('Y coordinate to right-click'),
-});
-const TypeSchema = zod.z.object({
-    text: zod.z.string().describe('Text to type'),
-});
-const KeySchema = zod.z.object({
-    key: zod.z
-        .string()
-        .describe('Key to press (e.g., "Enter", "Tab", "Escape", "Backspace", "Delete", "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Home", "End", "PageUp", "PageDown", "F1"-"F12")'),
-});
-const KeyComboSchema = zod.z.object({
-    keys: zod.z
-        .array(zod.z.string())
-        .describe('Array of keys to press together (e.g., ["Control", "c"] for copy, ["Alt", "Tab"] for window switch)'),
-});
-const ScrollSchema = zod.z.object({
-    x: zod.z.number().describe('X coordinate to scroll at'),
-    y: zod.z.number().describe('Y coordinate to scroll at'),
-    deltaX: zod.z.number().optional().describe('Horizontal scroll amount (pixels)'),
-    deltaY: zod.z.number().describe('Vertical scroll amount (pixels, negative = up, positive = down)'),
-});
-const DragSchema = zod.z.object({
-    startX: zod.z.number().describe('Starting X coordinate'),
-    startY: zod.z.number().describe('Starting Y coordinate'),
-    endX: zod.z.number().describe('Ending X coordinate'),
-    endY: zod.z.number().describe('Ending Y coordinate'),
-});
-const GetActiveWindowSchema = zod.z.object({});
-const GetMousePositionSchema = zod.z.object({});
-const ClipboardReadSchema = zod.z.object({});
-const ClipboardWriteSchema = zod.z.object({
-    text: zod.z.string().describe('Text to write to clipboard'),
-});
-const ClipboardPasteSchema = zod.z.object({});
-const WaitSchema = zod.z.object({
-    ms: zod.z.number().describe('Milliseconds to wait'),
-});
-/**
- * Format desktop action result for LLM consumption
- */
-function formatResultForLLM(result, action) {
-    if (!result.success && result.error) {
-        return `Desktop action "${action}" failed: ${result.error}`;
-    }
-    const parts = [];
-    if (result.screenshot) {
-        parts.push(`Screenshot captured (${result.screenshot.width}x${result.screenshot.height})`);
-        // The base64 image will be handled separately by the message formatter
-    }
-    if (result.activeWindow) {
-        parts.push(`**Active Window:**`);
-        parts.push(`  - Title: ${result.activeWindow.title}`);
-        parts.push(`  - App: ${result.activeWindow.app}`);
-        if (result.activeWindow.bounds) {
-            const b = result.activeWindow.bounds;
-            parts.push(`  - Position: (${b.x}, ${b.y})`);
-            parts.push(`  - Size: ${b.width}x${b.height}`);
-        }
-    }
-    if (result.mousePosition) {
-        parts.push(`**Mouse Position:** (${result.mousePosition.x}, ${result.mousePosition.y})`);
-    }
-    if (result.clipboard !== undefined) {
-        parts.push(`**Clipboard Content:** ${result.clipboard}`);
-    }
-    if (parts.length === 0) {
-        parts.push(`Desktop action "${action}" completed successfully.`);
-    }
-    return parts.join('\n');
-}
-/**
- * Create desktop automation tools for the agent
- * These tools allow AI to control the user's desktop when Ranger Desktop is running
- */
-function createDesktopTools(options = {}) {
-    const { waitForResult } = options;
-    const tools$1 = [];
-    /**
-     * Helper to create tool function that optionally waits for results
-     * The toolCallId is extracted from the RunnableConfig passed by LangChain
-     */
-    const createToolFunction = (action) => {
-        return async (args, config) => {
-            const toolCallId = config?.toolCall?.id ??
-                `desktop_${Date.now()}_${Math.random().toString(36).slice(2)}`;
-            // Create marker for Electron app
-            const marker = {
-                requiresDesktopExecution: true,
-                action,
-                args,
-                toolCallId,
-            };
-            // If no callback, return marker immediately (Electron handles via SSE interception)
-            if (!waitForResult) {
-                return JSON.stringify(marker);
-            }
-            // With callback: wait for actual results from Electron app
-            try {
-                const result = await waitForResult(action, args, toolCallId);
-                return formatResultForLLM(result, action);
-            }
-            catch (error) {
-                const errorMessage = error instanceof Error ? error.message : String(error);
-                return `Desktop action "${action}" failed: ${errorMessage}`;
-            }
-        };
-    };
-    // computer_screenshot
-    tools$1.push(tools.tool(createToolFunction(EDesktopTools.SCREENSHOT), {
-        name: EDesktopTools.SCREENSHOT,
-        description: 'Take a screenshot of the entire screen. Use this to see what is currently displayed on the desktop.',
-        schema: ScreenshotSchema,
-    }));
-    // computer_click
-    tools$1.push(tools.tool(createToolFunction(EDesktopTools.CLICK), {
-        name: EDesktopTools.CLICK,
-        description: 'Click the mouse at the specified screen coordinates. Use screenshot first to identify the target location.',
-        schema: ClickSchema,
-    }));
-    // computer_double_click
-    tools$1.push(tools.tool(createToolFunction(EDesktopTools.DOUBLE_CLICK), {
-        name: EDesktopTools.DOUBLE_CLICK,
-        description: 'Double-click the mouse at the specified screen coordinates.',
-        schema: DoubleClickSchema,
-    }));
-    // computer_right_click
-    tools$1.push(tools.tool(createToolFunction(EDesktopTools.RIGHT_CLICK), {
-        name: EDesktopTools.RIGHT_CLICK,
-        description: 'Right-click the mouse at the specified screen coordinates to open context menus.',
-        schema: RightClickSchema,
-    }));
-    // computer_type
-    tools$1.push(tools.tool(createToolFunction(EDesktopTools.TYPE), {
-        name: EDesktopTools.TYPE,
-        description: 'Type text using the keyboard. Make sure the target input field is focused first (use click).',
-        schema: TypeSchema,
-    }));
-    // computer_key
-    tools$1.push(tools.tool(createToolFunction(EDesktopTools.KEY), {
-        name: EDesktopTools.KEY,
-        description: 'Press a single key on the keyboard (Enter, Tab, Escape, arrow keys, function keys, etc.).',
-        schema: KeySchema,
-    }));
-    // computer_key_combo
-    tools$1.push(tools.tool(createToolFunction(EDesktopTools.KEY_COMBO), {
-        name: EDesktopTools.KEY_COMBO,
-        description: 'Press a key combination (e.g., Ctrl+C to copy, Ctrl+V to paste, Alt+Tab to switch windows).',
-        schema: KeyComboSchema,
-    }));
-    // computer_scroll
-    tools$1.push(tools.tool(createToolFunction(EDesktopTools.SCROLL), {
-        name: EDesktopTools.SCROLL,
-        description: 'Scroll at the specified screen coordinates. Use negative deltaY to scroll up, positive to scroll down.',
-        schema: ScrollSchema,
-    }));
-    // computer_drag
-    tools$1.push(tools.tool(createToolFunction(EDesktopTools.DRAG), {
-        name: EDesktopTools.DRAG,
-        description: 'Drag the mouse from one position to another (for moving windows, selecting text, etc.).',
-        schema: DragSchema,
-    }));
-    // computer_get_active_window
-    tools$1.push(tools.tool(createToolFunction(EDesktopTools.GET_ACTIVE_WINDOW), {
-        name: EDesktopTools.GET_ACTIVE_WINDOW,
-        description: 'Get information about the currently active window (title, application name, position, size).',
-        schema: GetActiveWindowSchema,
-    }));
-    // computer_get_mouse_position
-    tools$1.push(tools.tool(createToolFunction(EDesktopTools.GET_MOUSE_POSITION), {
-        name: EDesktopTools.GET_MOUSE_POSITION,
-        description: 'Get the current mouse cursor position on screen.',
-        schema: GetMousePositionSchema,
-    }));
-    // clipboard_read
-    tools$1.push(tools.tool(createToolFunction(EDesktopTools.CLIPBOARD_READ), {
-        name: EDesktopTools.CLIPBOARD_READ,
-        description: 'Read the current contents of the system clipboard.',
-        schema: ClipboardReadSchema,
-    }));
-    // clipboard_write
-    tools$1.push(tools.tool(createToolFunction(EDesktopTools.CLIPBOARD_WRITE), {
-        name: EDesktopTools.CLIPBOARD_WRITE,
-        description: 'Write text to the system clipboard.',
-        schema: ClipboardWriteSchema,
-    }));
-    // clipboard_paste
-    tools$1.push(tools.tool(createToolFunction(EDesktopTools.CLIPBOARD_PASTE), {
-        name: EDesktopTools.CLIPBOARD_PASTE,
-        description: 'Paste the clipboard contents (equivalent to Ctrl+V). Use clipboard_write first to set the content.',
-        schema: ClipboardPasteSchema,
-    }));
-    // computer_wait
-    tools$1.push(tools.tool(createToolFunction(EDesktopTools.WAIT), {
-        name: EDesktopTools.WAIT,
-        description: 'Wait for the specified number of milliseconds. Use this to wait for UI animations or loading.',
-        schema: WaitSchema,
-    }));
-    return tools$1;
-}
-/**
- * Get all desktop tool names
- */
-function getDesktopToolNames() {
-    return Object.values(EDesktopTools);
-}
-/**
- * Check if a tool name is a desktop tool
- */
-function isDesktopTool(name) {
-    return Object.values(EDesktopTools).includes(name);
-}
-
-exports.EDesktopTools = EDesktopTools;
-exports.createDesktopTools = createDesktopTools;
-exports.getDesktopToolNames = getDesktopToolNames;
-exports.hasDesktopCapability = hasDesktopCapability;
-exports.isDesktopTool = isDesktopTool;
-//# sourceMappingURL=DesktopTools.cjs.map