Skip to main content

​
AI Code Generation

marimo includes AI-powered features to help you create notebooks faster and more efficiently. Generate entire notebooks from natural language prompts or use AI assistance within your existing notebooks.
AI features in marimo use state-of-the-art language models to understand your intent and generate working Python code.

​
Text-to-Notebook

The Text-to-Notebook feature allows you to generate complete marimo notebooks from simple text descriptions.

​
How It Works

1

Describe what you want

Write a natural language description of the notebook you want to create.
2

AI generates the code

marimo’s AI processes your prompt and generates a complete notebook with cells, code, and visualizations.
3

Run and iterate

Open the generated notebook, run it, and make any adjustments you need.

​
Using Text-to-Notebook

You can generate notebooks from the command line: 
marimo new --ai "Create a notebook that loads a CSV file and plots a histogram"
Or use it programmatically: 
from marimo._ai.text_to_notebook import text_to_notebook

prompt = "Create a notebook that analyzes sales data"
notebook_code = text_to_notebook(prompt)

# Save to file
with open("sales_analysis.py", "w") as f:
    f.write(notebook_code)

​
Example Prompts

Here are some example prompts that work well: 
Create a notebook that:
1. Loads a CSV file with sales data
2. Calculates monthly revenue
3. Creates a line chart showing revenue over time
4. Displays summary statistics

​
How AI Generation Works

When you use the text-to-notebook feature:
  1. Your prompt is sent to marimo’s AI API at https://ai.marimo.app/
  2. The API uses OpenAI/Anthropic models to convert your prompt into a notebook
  3. Your prompt is securely stored for caching purposes (fast response times)
  4. No personal data beyond the prompt itself is collected
Before using the AI feature for the first time, you’ll be asked to accept the terms of service. You can revoke consent at any time by modifying ~/.marimo/state.toml.

​
Terms of Service

When you first use the text-to-notebook feature, you’ll see: 
Before using marimo's Text-To-Notebook AI feature, you should know:

1. Your prompt will be sent to marimo's API at `https://ai.marimo.app/`
2. The API uses OpenAI/Anthropic's models to convert your prompt into a notebook
3. Your prompt is securely stored for caching purposes (fast response times)
4. No personal data beyond the prompt itself is collected
5. You can revoke consent at any time by modifying ~/.marimo/state.toml

Do you accept these terms? (y/n)

​
AI Chat Integration

marimo also supports AI chat interfaces through the mo.ui.chat() component.

​
Creating a Chat Interface

import marimo as mo

chat = mo.ui.chat(
    mo.ai.ChatModelConfig(
        model="gpt-4",
        system_message="You are a helpful data science assistant."
    )
)
chat

​
Chat Configuration

Configure the chat model with various options: 
from marimo import ai

config = ai.ChatModelConfig(
    model="gpt-4",  # or "claude-3-5-sonnet", etc.
    system_message="You are an expert Python programmer.",
    temperature=0.7,
    max_tokens=1000
)

chat = mo.ui.chat(config)

​
Chat Messages

Work with chat messages programmatically: 
from marimo import ai

# Create a chat message
message = ai.ChatMessage(
    role="user",
    content="Explain how list comprehensions work"
)

# With attachments
message_with_file = ai.ChatMessage(
    role="user",
    content="Analyze this data",
    attachments=[ai.ChatAttachment(path="data.csv")]
)

​
Configuring AI Providers

marimo supports multiple AI providers. Configure them through environment variables or notebook settings.

​
OpenAI

export OPENAI_API_KEY="your-api-key"

config = mo.ai.ChatModelConfig(
    model="gpt-4",
    api_key="your-api-key"  # or use environment variable
)

​
Anthropic

export ANTHROPIC_API_KEY="your-api-key"

config = mo.ai.ChatModelConfig(
    model="claude-3-5-sonnet-20241022",
    api_key="your-api-key"
)

​
Other Providers

marimo uses PydanticAI under the hood, which supports:
  • OpenAI
  • Anthropic
  • Google Gemini
  • Groq
  • Mistral
  • Custom providers
You can configure custom AI providers by implementing the appropriate interface. See the PydanticAI documentation for details.

​
Zero-Shot Notebook Generation

The text-to-notebook feature uses zero-shot generation, meaning:
  • No examples needed - just describe what you want
  • Works with various domains: data analysis, ML, visualization, web apps
  • Generates complete, runnable notebooks
  • Includes imports, data loading, analysis, and visualization

​
What Gets Generated

A typical generated notebook includes:
1

Imports

All necessary Python libraries (pandas, numpy, matplotlib, etc.)
2

Data Loading

Code to load or generate sample data
3

Analysis

Data processing and analysis logic
4

Visualization

Charts, plots, and interactive elements
5

UI Elements

Interactive widgets like sliders, dropdowns, etc. when appropriate

​
Best Practices

Be Specific

Provide clear, detailed descriptions of what you want the notebook to do.

Include Context

Mention data sources, expected outputs, and any specific libraries to use.

Iterate

Generated notebooks are starting points - review and refine the code.

Test Thoroughly

Always test generated code with your actual data before using in production.

​
Writing Good Prompts

A good prompt includes:
  1. Clear objective: What should the notebook accomplish?
  2. Data description: What kind of data will be used?
  3. Expected outputs: What visualizations or results do you want?
  4. Specific requirements: Any libraries, methods, or constraints?
Example:
Create a notebook that:
- Loads a CSV file with columns: date, product, sales, region
- Filters data for the last 12 months
- Groups by month and region
- Creates an interactive line chart showing sales trends
- Uses plotly for visualization
- Includes a dropdown to select specific regions

​
Troubleshooting

  • Check your internet connection
  • Try a simpler prompt first
  • Make sure you’ve accepted the terms of service
  • Verify that the marimo AI API is accessible
  • Review the generated code for obvious errors
  • Make sure required libraries are installed
  • Try regenerating with a more specific prompt
  • Manually adjust the code as needed
Edit ~/.marimo/state.toml and remove or modify the accepted_text_to_notebook_terms_at field.

​
Privacy and Security

Important: Your prompts are sent to external AI APIs. Don’t include sensitive information, credentials, or proprietary data in your prompts.
What marimo collects:
  • Your text prompts
  • Generated notebook code (for caching)
What marimo does NOT collect:
  • Personal identifying information
  • Your notebook data
  • API keys or credentials
  • File contents from your system
The AI feature is designed for rapid prototyping and learning. Always review and test generated code before using it with real data.

Build docs developers (and LLMs) love

Get started for freeTalk to us