import { DynamicStructuredTool } from '@langchain/core/tools'; import type * as t from '@/types'; import { Constants } from '@/common'; export declare const ProgrammaticToolCallingSchema: { readonly type: "object"; readonly properties: { readonly code: { readonly type: "string"; readonly minLength: 1; readonly description: "Python code that calls tools programmatically. Tools are available as async functions.\n\nCRITICAL - STATELESS EXECUTION:\nEach call is a fresh Python interpreter. Variables, imports, and data do NOT persist between calls.\nYou MUST complete your entire workflow in ONE code block: query → process → output.\nDO NOT split work across multiple calls expecting to reuse variables.\n\nYour code is auto-wrapped in async context. Just write logic with await—no boilerplate needed.\n\nExample (Complete workflow in one call):\n # Query data\n data = await query_database(sql=\"SELECT * FROM users\")\n # Process it\n df = pd.DataFrame(data)\n summary = df.groupby('region').sum()\n # Output results\n await write_to_sheet(spreadsheet_id=sid, data=summary.to_dict())\n print(f\"Wrote {len(summary)} rows\")\n\nExample (Parallel calls):\n sf, ny = await asyncio.gather(get_weather(city=\"SF\"), get_weather(city=\"NY\"))\n print(f\"SF: {sf}, NY: {ny}\")\n\nRules:\n- EVERYTHING in one call—no state persists between executions\n- Just write code with await—auto-wrapped in async context\n- DO NOT define async def main() or call asyncio.run()\n- Tools are pre-defined—DO NOT write function definitions\n- Only print() output returns to the model"; }; readonly timeout: { readonly type: "integer"; readonly minimum: 1000; readonly maximum: 300000; readonly default: 60000; readonly description: "Maximum execution time in milliseconds. Default: 60 seconds. Max: 5 minutes."; }; }; readonly required: readonly ["code"]; }; export declare const ProgrammaticToolCallingName = Constants.PROGRAMMATIC_TOOL_CALLING; export declare const ProgrammaticToolCallingDescription: string; export declare const ProgrammaticToolCallingDefinition: { readonly name: Constants.PROGRAMMATIC_TOOL_CALLING; readonly description: string; readonly schema: { readonly type: "object"; readonly properties: { readonly code: { readonly type: "string"; readonly minLength: 1; readonly description: "Python code that calls tools programmatically. Tools are available as async functions.\n\nCRITICAL - STATELESS EXECUTION:\nEach call is a fresh Python interpreter. Variables, imports, and data do NOT persist between calls.\nYou MUST complete your entire workflow in ONE code block: query → process → output.\nDO NOT split work across multiple calls expecting to reuse variables.\n\nYour code is auto-wrapped in async context. Just write logic with await—no boilerplate needed.\n\nExample (Complete workflow in one call):\n # Query data\n data = await query_database(sql=\"SELECT * FROM users\")\n # Process it\n df = pd.DataFrame(data)\n summary = df.groupby('region').sum()\n # Output results\n await write_to_sheet(spreadsheet_id=sid, data=summary.to_dict())\n print(f\"Wrote {len(summary)} rows\")\n\nExample (Parallel calls):\n sf, ny = await asyncio.gather(get_weather(city=\"SF\"), get_weather(city=\"NY\"))\n print(f\"SF: {sf}, NY: {ny}\")\n\nRules:\n- EVERYTHING in one call—no state persists between executions\n- Just write code with await—auto-wrapped in async context\n- DO NOT define async def main() or call asyncio.run()\n- Tools are pre-defined—DO NOT write function definitions\n- Only print() output returns to the model"; }; readonly timeout: { readonly type: "integer"; readonly minimum: 1000; readonly maximum: 300000; readonly default: 60000; readonly description: "Maximum execution time in milliseconds. Default: 60 seconds. Max: 5 minutes."; }; }; readonly required: readonly ["code"]; }; }; /** * Normalizes a tool name to Python identifier format. * Must match the Code API's `normalizePythonFunctionName` exactly: * 1. Replace hyphens and spaces with underscores * 2. Remove any other invalid characters * 3. Prefix with underscore if starts with number * 4. Append `_tool` if it's a Python keyword * @param name - The tool name to normalize * @returns Normalized Python-safe identifier */ export declare function normalizeToPythonIdentifier(name: string): string; /** * Extracts tool names that are actually called in the Python code. * Handles hyphen/underscore conversion since Python identifiers use underscores. * @param code - The Python code to analyze * @param toolNameMap - Map from normalized Python name to original tool name * @returns Set of original tool names found in the code */ export declare function extractUsedToolNames(code: string, toolNameMap: Map): Set; /** * Filters tool definitions to only include tools actually used in the code. * Handles the hyphen-to-underscore conversion for Python compatibility. * @param toolDefs - All available tool definitions * @param code - The Python code to analyze * @param debug - Enable debug logging * @returns Filtered array of tool definitions */ export declare function filterToolsByUsage(toolDefs: t.LCTool[], code: string, debug?: boolean): t.LCTool[]; /** * Fetches files from a previous session to make them available for the current execution. * Files are returned as CodeEnvFile references to be included in the request. * @param baseUrl - The base URL for the Code API * @param apiKey - The API key for authentication * @param sessionId - The session ID to fetch files from * @param proxy - Optional HTTP proxy URL * @returns Array of CodeEnvFile references, or empty array if fetch fails */ export declare function fetchSessionFiles(baseUrl: string, apiKey: string, sessionId: string, proxy?: string, userId?: string): Promise; /** * Makes an HTTP request to the Code API. * @param endpoint - The API endpoint URL * @param apiKey - The API key for authentication * @param body - The request body * @param proxy - Optional HTTP proxy URL * @returns The parsed API response */ export declare function makeRequest(endpoint: string, apiKey: string, body: Record, proxy?: string, userId?: string): Promise; /** * Unwraps tool responses that may be formatted as tuples or content blocks. * MCP tools return [content, artifacts], we need to extract the raw data. * @param result - The raw result from tool.invoke() * @param isMCPTool - Whether this is an MCP tool (has mcp property) * @returns Unwrapped raw data (string, object, or parsed JSON) */ export declare function unwrapToolResponse(result: unknown, isMCPTool: boolean): unknown; /** * Executes tools in parallel when requested by the API. * Uses Promise.all for parallel execution, catching individual errors. * Unwraps formatted responses (e.g., MCP tool tuples) to raw data. * @param toolCalls - Array of tool calls from the API * @param toolMap - Map of tool names to executable tools * @returns Array of tool results */ export declare function executeTools(toolCalls: t.PTCToolCall[], toolMap: t.ToolMap): Promise; /** * Formats the completed response for the agent. * @param response - The completed API response * @returns Tuple of [formatted string, artifact] */ export declare function formatCompletedResponse(response: t.ProgrammaticExecutionResponse): [string, t.ProgrammaticExecutionArtifact]; /** * Creates a Programmatic Tool Calling tool for complex multi-tool workflows. * * This tool enables AI agents to write Python code that orchestrates multiple * tool calls programmatically, reducing LLM round-trips and token usage. * * The tool map must be provided at runtime via config.configurable.toolMap. * * @param params - Configuration parameters (apiKey, baseUrl, maxRoundTrips, proxy) * @returns A LangChain DynamicStructuredTool for programmatic tool calling * * @example * const ptcTool = createProgrammaticToolCallingTool({ * apiKey: process.env.CODE_API_KEY, * maxRoundTrips: 20 * }); * * const [output, artifact] = await ptcTool.invoke( * { code, tools }, * { configurable: { toolMap } } * ); */ export declare function createProgrammaticToolCallingTool(initParams?: t.ProgrammaticToolCallingParams): DynamicStructuredTool;