gh-jezweb-claude-skills-skills-google-gemini-api/references/code-execution-patterns.md

Code Execution Patterns

Complete guide to using code execution with Google Gemini API for computational tasks, data analysis, and problem-solving.

---

What is Code Execution?

Code Execution allows Gemini models to generate and execute Python code to solve problems requiring computation, enabling the model to:

• Perform precise mathematical calculations
• Analyze data with pandas/numpy
• Generate charts and visualizations
• Implement algorithms
• Process files and data structures

---

How It Works

1. Model receives prompt requiring computation
2. Model generates Python code to solve the problem
3. Code executes in sandbox (secure, isolated environment)
4. Results return to model for incorporation into response
5. Model explains results in natural language

---

Enabling Code Execution

Basic Setup (SDK)

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash', // Or gemini-2.5-pro
  contents: 'Calculate the sum of first 50 prime numbers',
  config: {
    tools: [{ codeExecution: {} }] // Enable code execution
  }
});

Basic Setup (Fetch)

const response = await fetch(
  `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-goog-api-key': env.GEMINI_API_KEY,
    },
    body: JSON.stringify({
      tools: [{ code_execution: {} }],
      contents: [{ parts: [{ text: 'Calculate...' }] }]
    }),
  }
);

---

Available Python Packages

Standard Library

• math, statistics, random
• datetime, time, calendar
• json, csv, re
• collections, itertools, functools

Data Science

• numpy - numerical computing
• pandas - data analysis and manipulation
• scipy - scientific computing

Visualization

• matplotlib - plotting and charts
• seaborn - statistical visualization

Note: This is a limited sandbox environment - not all PyPI packages are available.

---

Response Structure

Parsing Code Execution Results

for (const part of response.candidates[0].content.parts) {
  // Inline text
  if (part.text) {
    console.log('Text:', part.text);
  }

  // Generated code
  if (part.executableCode) {
    console.log('Language:', part.executableCode.language); // "PYTHON"
    console.log('Code:', part.executableCode.code);
  }

  // Execution results
  if (part.codeExecutionResult) {
    console.log('Outcome:', part.codeExecutionResult.outcome); // "OUTCOME_OK" or "OUTCOME_FAILED"
    console.log('Output:', part.codeExecutionResult.output);
  }
}

Example Response

{
  "candidates": [{
    "content": {
      "parts": [
        { "text": "I'll calculate that for you." },
        {
          "executableCode": {
            "language": "PYTHON",
            "code": "primes = []\nnum = 2\nwhile len(primes) < 50:\n  if is_prime(num):\n    primes.append(num)\n  num += 1\nprint(sum(primes))"
          }
        },
        {
          "codeExecutionResult": {
            "outcome": "OUTCOME_OK",
            "output": "5117\n"
          }
        },
        { "text": "The sum is 5117." }
      ]
    }
  }]
}

---

Common Patterns

1. Mathematical Calculations

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: 'Calculate the 100th Fibonacci number',
  config: { tools: [{ codeExecution: {} }] }
});

Prompting Tip: Use phrases like "generate and run code" or "calculate using code" to explicitly request code execution.

2. Data Analysis

const prompt = `
  Analyze this sales data:

  month,revenue,customers
  Jan,50000,120
  Feb,62000,145
  Mar,58000,138

  Calculate:
  1. Total revenue
  2. Average revenue per customer
  3. Month-over-month growth rate

  Use pandas or numpy for analysis.
`;

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: prompt,
  config: { tools: [{ codeExecution: {} }] }
});

3. Chart Generation

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: 'Create a bar chart showing prime number distribution by last digit (0-9) for primes under 100',
  config: { tools: [{ codeExecution: {} }] }
});

Note: Chart image data appears in codeExecutionResult.output (base64 encoded in some cases).

4. Algorithm Implementation

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: 'Implement quicksort and sort this list: [64, 34, 25, 12, 22, 11, 90]. Show the sorted result.',
  config: { tools: [{ codeExecution: {} }] }
});

5. File Processing (In-Memory)

const csvData = `name,age,city
Alice,30,NYC
Bob,25,LA
Charlie,35,Chicago`;

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: `Parse this CSV data and calculate average age:\n\n${csvData}`,
  config: { tools: [{ codeExecution: {} }] }
});

---

Chat with Code Execution

Multi-Turn Computational Conversations

const chat = await ai.chats.create({
  model: 'gemini-2.5-flash',
  config: { tools: [{ codeExecution: {} }] }
});

// First turn
let response = await chat.sendMessage('I have a data analysis question');
console.log(response.text);

// Second turn (will use code execution)
response = await chat.sendMessage(`
  Calculate statistics for: [12, 15, 18, 22, 25, 28, 30]
  - Mean
  - Median
  - Standard deviation
`);

for (const part of response.candidates[0].content.parts) {
  if (part.text) console.log(part.text);
  if (part.executableCode) console.log('Code:', part.executableCode.code);
  if (part.codeExecutionResult) console.log('Results:', part.codeExecutionResult.output);
}

---

Error Handling

Checking Execution Outcome

for (const part of response.candidates[0].content.parts) {
  if (part.codeExecutionResult) {
    if (part.codeExecutionResult.outcome === 'OUTCOME_OK') {
      console.log('✅ Success:', part.codeExecutionResult.output);
    } else if (part.codeExecutionResult.outcome === 'OUTCOME_FAILED') {
      console.error('❌ Execution failed:', part.codeExecutionResult.output);
    }
  }
}

Common Execution Errors

Timeout:

Error: Execution timed out after 30 seconds

Solution: Simplify computation or reduce data size.

Import Error:

ModuleNotFoundError: No module named 'requests'

Solution: Use only available packages (numpy, pandas, matplotlib, seaborn, scipy).

Syntax Error:

SyntaxError: invalid syntax

Solution: Model generated invalid code - try rephrasing prompt or regenerating.

---

Best Practices

✅ Do

1. Be Explicit: Use phrases like "generate and run code" to trigger code execution
2. Provide Data: Include data directly in prompt for analysis
3. Specify Output: Ask for specific calculations or metrics
4. Use Available Packages: Stick to numpy, pandas, matplotlib, scipy
5. Check Outcome: Always verify outcome === 'OUTCOME_OK'

❌ Don't

1. Network Access: Code cannot make HTTP requests
2. File System: No persistent file storage between executions
3. Long Computations: Timeout limits apply (~30 seconds)
4. External Dependencies: Can't install new packages
5. State Persistence: Each execution is isolated (no global state)

---

Limitations

Sandbox Restrictions

• No Network Access: Cannot call external APIs
• No File I/O: Cannot read/write to disk (in-memory only)
• Limited Packages: Only pre-installed packages available
• Execution Timeout: ~30 seconds maximum
• No State: Each execution is independent

Supported Models

✅ Works with:

• gemini-2.5-pro
• gemini-2.5-flash

❌ Does NOT work with:

• gemini-2.5-flash-lite (no code execution support)
• Gemini 1.5 models (use Gemini 2.5)

---

Advanced Patterns

Iterative Analysis

const chat = await ai.chats.create({
  model: 'gemini-2.5-flash',
  config: { tools: [{ codeExecution: {} }] }
});

// Step 1: Initial analysis
let response = await chat.sendMessage('Analyze data: [10, 20, 30, 40, 50]');

// Step 2: Follow-up based on results
response = await chat.sendMessage('Now calculate the variance');

// Step 3: Visualization
response = await chat.sendMessage('Create a histogram of this data');

Combining with Function Calling

const weatherFunction = {
  name: 'get_current_weather',
  description: 'Get weather for a city',
  parametersJsonSchema: {
    type: 'object',
    properties: { city: { type: 'string' } },
    required: ['city']
  }
};

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: 'Get weather for NYC, LA, Chicago. Calculate the average temperature.',
  config: {
    tools: [
      { functionDeclarations: [weatherFunction] },
      { codeExecution: {} }
    ]
  }
});

// Model will:
// 1. Call get_current_weather for each city
// 2. Generate code to calculate average
// 3. Return result

Data Transformation Pipeline

const prompt = `
  Transform this data:
  Input: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

  Pipeline:
  1. Filter odd numbers
  2. Square each number
  3. Calculate sum
  4. Return result

  Use code to process.
`;

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: prompt,
  config: { tools: [{ codeExecution: {} }] }
});

---

Optimization Tips

1. Clear Instructions

❌ Vague:

contents: 'Analyze this data'

✅ Specific:

contents: 'Calculate mean, median, and standard deviation for: [12, 15, 18, 22, 25]'

2. Provide Complete Data

const csvData = `...complete dataset...`;
const prompt = `Analyze this CSV data:\n\n${csvData}\n\nCalculate total revenue.`;

3. Request Code Explicitly

contents: 'Generate and run code to calculate the factorial of 20'

4. Handle Large Datasets

For large data, consider:

• Sampling (analyze subset)
• Aggregation (group by categories)
• Pagination (process in chunks)

---

Troubleshooting

Code Not Executing

Symptom: Response has text but no executableCode

Causes:

1. Code execution not enabled (tools: [{ codeExecution: {} }])
2. Model decided code wasn't necessary
3. Using gemini-2.5-flash-lite (doesn't support code execution)

Solution: Be explicit in prompt: "Use code to calculate..."

Timeout Errors

Symptom: OUTCOME_FAILED with timeout message

Causes: Computation too complex or data too large

Solution:

• Simplify algorithm
• Reduce data size
• Use more efficient approach

Import Errors

Symptom: ModuleNotFoundError

Causes: Trying to import unavailable package

Solution: Use only available packages (numpy, pandas, matplotlib, seaborn, scipy)

---

References

• Official Docs: https://ai.google.dev/gemini-api/docs/code-execution
• Templates: See code-execution.ts for working examples
• Available Packages: See "Available Python Packages" section above