@nxcode/sdk 1.0.1 → 1.0.12

package/dist/nxcode.js

@@ -412,6 +412,46 @@
      * Provides access to AI capabilities through the Nxcode AI Gateway.
      * All AI calls require user authentication and are billed to the user's balance.
      */
+    /**
+     * Convert simplified schema to JSON Schema (Gemini format)
+     */
+    function toJsonSchema(schema) {
+        // Primitive types
+        if (schema === 'string') {
+            return { type: 'STRING' };
+        }
+        if (schema === 'number') {
+            return { type: 'NUMBER' };
+        }
+        if (schema === 'boolean') {
+            return { type: 'BOOLEAN' };
+        }
+        // Array type
+        if (Array.isArray(schema)) {
+            if (schema.length !== 1) {
+                throw new Error('Array schema must have exactly one element type');
+            }
+            return {
+                type: 'ARRAY',
+                items: toJsonSchema(schema[0]),
+            };
+        }
+        // Object type
+        if (typeof schema === 'object' && schema !== null) {
+            const properties = {};
+            const required = [];
+            for (const [key, value] of Object.entries(schema)) {
+                properties[key] = toJsonSchema(value);
+                required.push(key); // All fields required by default
+            }
+            return {
+                type: 'OBJECT',
+                properties,
+                required,
+            };
+        }
+        throw new Error(`Invalid schema type: ${schema}`);
+    }
     class NxcodeAI {
         constructor(apiEndpoint, appId, getToken) {
             this.apiEndpoint = apiEndpoint;
@@ -439,6 +479,13 @@
             const geminiRequest = {
                 contents: this.convertMessagesToGemini(options.messages),
             };
+            // Add structured output config if schema provided
+            if (options.responseSchema) {
+                geminiRequest.generationConfig = {
+                    responseMimeType: 'application/json',
+                    responseSchema: toJsonSchema(options.responseSchema),
+                };
+            }
             const response = await fetch(`${this.apiEndpoint}/api/ai-gateway/v1beta/models/${model}:generateContent`, {
                 method: 'POST',
                 headers: this.getHeaders(token),
@@ -463,6 +510,7 @@
             const result = await this.chat({
                 messages: [{ role: 'user', content: options.prompt }],
                 model: options.model,
+                responseSchema: options.responseSchema,
             });
             return {
                 text: result.content,
@@ -665,6 +713,272 @@
         }
     }
 
+    /**
+     * Nxcode SDK - Agent Module
+     *
+     * Provides AI agents with tool calling capabilities.
+     * Agents can call backend endpoints as tools and maintain conversation history.
+     */
+    // ==================== Helper Functions ====================
+    /**
+     * Convert simple schema to JSON Schema format for Gemini
+     */
+    function toJsonSchemaProperty(schema) {
+        if (schema === 'string')
+            return { type: 'STRING' };
+        if (schema === 'number')
+            return { type: 'NUMBER' };
+        if (schema === 'boolean')
+            return { type: 'BOOLEAN' };
+        if (Array.isArray(schema)) {
+            return {
+                type: 'ARRAY',
+                items: toJsonSchemaProperty(schema[0]),
+            };
+        }
+        if (typeof schema === 'object') {
+            const properties = {};
+            const required = [];
+            for (const [key, value] of Object.entries(schema)) {
+                properties[key] = toJsonSchemaProperty(value);
+                required.push(key);
+            }
+            return { type: 'OBJECT', properties, required };
+        }
+        return { type: 'STRING' };
+    }
+    /**
+     * Convert AgentTool to Gemini function declaration
+     */
+    function toolToGeminiFunction(tool) {
+        const declaration = {
+            name: tool.name,
+            description: tool.description,
+        };
+        // Always include parameters object (even if empty) for Gemini compatibility
+        const properties = {};
+        const required = [];
+        if (tool.parameters) {
+            for (const [key, value] of Object.entries(tool.parameters)) {
+                properties[key] = toJsonSchemaProperty(value);
+                required.push(key);
+            }
+        }
+        declaration.parameters = {
+            type: 'OBJECT',
+            properties,
+            required,
+        };
+        return declaration;
+    }
+    // ==================== Agent Class ====================
+    class Agent {
+        constructor(options, apiEndpoint, appId, getToken) {
+            this.history = [];
+            this.options = {
+                instructions: options.instructions,
+                tools: options.tools,
+                model: options.model || 'fast',
+                maxSteps: options.maxSteps || 10,
+            };
+            this.apiEndpoint = apiEndpoint;
+            this.appId = appId;
+            this.getToken = getToken;
+        }
+        /**
+         * Run the agent with user input
+         */
+        async run(input, callbacks) {
+            const token = this.getToken();
+            if (!token) {
+                throw new Error('Not authenticated. Please login first.');
+            }
+            // Add user message to history
+            this.history.push({ role: 'user', content: input });
+            const toolCalls = [];
+            let totalInputTokens = 0;
+            let totalOutputTokens = 0;
+            let steps = 0;
+            // Agent loop
+            while (steps < this.options.maxSteps) {
+                steps++;
+                console.log(`[Agent] Step ${steps}/${this.options.maxSteps}`);
+                // Call Gemini with tools
+                const response = await this.callGemini(token);
+                console.log(`[Agent] Response:`, response.functionCall ? `function call: ${response.functionCall.name}` : `text: ${response.text?.substring(0, 50)}`);
+                totalInputTokens += response.usage?.inputTokens || 0;
+                totalOutputTokens += response.usage?.outputTokens || 0;
+                // Check if AI wants to call a function
+                const functionCall = response.functionCall;
+                if (functionCall) {
+                    callbacks?.onToolCall?.(functionCall.name, functionCall.args);
+                    // Find the tool
+                    const tool = this.options.tools.find((t) => t.name === functionCall.name);
+                    if (!tool) {
+                        throw new Error(`Unknown tool: ${functionCall.name}`);
+                    }
+                    // Call the tool endpoint
+                    const result = await this.callTool(tool, functionCall.args, token);
+                    callbacks?.onToolResult?.(functionCall.name, result);
+                    // Record tool call
+                    toolCalls.push({
+                        name: functionCall.name,
+                        params: functionCall.args,
+                        result,
+                    });
+                    // Add function call and response to history using raw parts from Gemini
+                    this.history.push({
+                        role: 'model',
+                        content: '',
+                        parts: response.rawParts || [{ functionCall: { name: functionCall.name, args: functionCall.args } }],
+                    });
+                    this.history.push({
+                        role: 'user',
+                        content: '',
+                        parts: [{ functionResponse: { name: functionCall.name, response: result } }],
+                    });
+                    // Continue loop to let AI process the result
+                    console.log(`[Agent] Continuing loop after tool call...`);
+                    continue;
+                }
+                // No function call - AI is done, return the text response
+                const output = response.text || '';
+                // Add assistant response to history
+                this.history.push({ role: 'assistant', content: output });
+                return {
+                    output,
+                    toolCalls,
+                    usage: {
+                        inputTokens: totalInputTokens,
+                        outputTokens: totalOutputTokens,
+                    },
+                };
+            }
+            throw new Error(`Agent exceeded maximum steps (${this.options.maxSteps})`);
+        }
+        /**
+         * Clear conversation history
+         */
+        reset() {
+            this.history = [];
+        }
+        /**
+         * Get current conversation history
+         */
+        getHistory() {
+            return [...this.history];
+        }
+        // ==================== Private Methods ====================
+        async callGemini(token) {
+            // Build contents from history
+            const contents = this.history.map((msg) => {
+                if (msg.parts) {
+                    return {
+                        role: msg.role === 'assistant' ? 'model' : msg.role,
+                        parts: msg.parts,
+                    };
+                }
+                return {
+                    role: msg.role === 'assistant' ? 'model' : 'user',
+                    parts: [{ text: msg.content }],
+                };
+            });
+            // Build tools
+            const tools = [
+                {
+                    functionDeclarations: this.options.tools.map(toolToGeminiFunction),
+                },
+            ];
+            // Build request with tool config to encourage tool use
+            const request = {
+                contents,
+                tools,
+                toolConfig: {
+                    functionCallingConfig: {
+                        mode: 'AUTO', // Let model decide when to use tools
+                    },
+                },
+                systemInstruction: {
+                    parts: [{ text: this.options.instructions }],
+                },
+            };
+            console.log('[Agent] Sending request:', JSON.stringify(request, null, 2));
+            const response = await fetch(`${this.apiEndpoint}/api/ai-gateway/v1beta/models/${this.options.model}:generateContent`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-App-Id': this.appId,
+                    Authorization: `Bearer ${token}`,
+                },
+                body: JSON.stringify(request),
+            });
+            if (!response.ok) {
+                const error = await response.json().catch(() => ({}));
+                throw new Error(error.detail || error.message || 'Agent API call failed');
+            }
+            const data = await response.json();
+            // Parse response
+            const candidate = data.candidates?.[0];
+            const parts = candidate?.content?.parts || [];
+            // Check for function call (support both camelCase and snake_case)
+            for (const part of parts) {
+                const funcCall = part.functionCall || part.function_call;
+                if (funcCall) {
+                    return {
+                        functionCall: {
+                            name: funcCall.name,
+                            args: funcCall.args || {},
+                        },
+                        rawParts: parts, // Save raw parts including thought_signature
+                        usage: {
+                            inputTokens: data.usageMetadata?.promptTokenCount || 0,
+                            outputTokens: data.usageMetadata?.candidatesTokenCount || 0,
+                        },
+                    };
+                }
+            }
+            // Return text response
+            const text = parts.find((p) => p.text)?.text || '';
+            return {
+                text,
+                usage: {
+                    inputTokens: data.usageMetadata?.promptTokenCount || 0,
+                    outputTokens: data.usageMetadata?.candidatesTokenCount || 0,
+                },
+            };
+        }
+        async callTool(tool, params, token) {
+            // Build context to pass to tool
+            const body = {
+                ...params,
+                _context: {
+                    agentId: this.options.instructions.slice(0, 20), // Simple ID
+                    stepIndex: this.history.length,
+                    previousTools: this.history
+                        .filter((m) => m.parts?.some((p) => p.functionResponse))
+                        .map((m) => {
+                        const fr = m.parts?.find((p) => p.functionResponse)?.functionResponse;
+                        return fr ? { name: fr.name, result: fr.response } : null;
+                    })
+                        .filter(Boolean),
+                },
+            };
+            const response = await fetch(tool.endpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${token}`,
+                },
+                body: JSON.stringify(body),
+            });
+            if (!response.ok) {
+                const error = await response.text();
+                return { error: `Tool call failed: ${error}` };
+            }
+            return response.json();
+        }
+    }
+
     /**
      * Nxcode SDK
      *
@@ -929,6 +1243,37 @@
                     await self.ensureInitialized();
                     return self._ai.generateStream(options);
                 },
+                /**
+                 * Create an AI agent with tool calling capabilities
+                 *
+                 * @example
+                 * const agent = Nxcode.ai.createAgent({
+                 *   instructions: 'You are a helpful assistant that can search and send emails.',
+                 *   tools: [
+                 *     {
+                 *       name: 'search_emails',
+                 *       description: 'Search user emails',
+                 *       parameters: { query: 'string' },
+                 *       endpoint: '/api/emails/search'
+                 *     },
+                 *     {
+                 *       name: 'send_email',
+                 *       description: 'Send an email',
+                 *       parameters: { to: 'string', subject: 'string', body: 'string' },
+                 *       endpoint: '/api/emails/send'
+                 *     }
+                 *   ]
+                 * });
+                 *
+                 * const result = await agent.run('Find emails from John and reply to him');
+                 * console.log(result.output);
+                 */
+                createAgent(options) {
+                    if (!self.config) {
+                        throw new Error('Nxcode SDK not configured. Call Nxcode.configure(appId) first.');
+                    }
+                    return new Agent(options, self.apiEndpoint, self.config.appId, () => self._auth?.getToken() || null);
+                },
             };
         }
         // ==================== Utility Methods ====================
@@ -958,6 +1303,7 @@
         window.Nxcode = Nxcode;
     }
 
+    exports.Agent = Agent;
     exports.Nxcode = Nxcode;
     exports.default = Nxcode;