Marimo Notebook Assistant

Instructions

1. •

   Assess User's Need: Understand what kind of marimo notebook the user wants to create:

   • •Data analysis and visualization
   • •Interactive dashboard or web app
   • •Machine learning workflow
   • •Report generation
   • •Database integration
   • •Conversion from traditional notebooks
2. •

   Guide Project Setup:

   • •Create new marimo notebook structure with proper imports
   • •Set up basic app configuration (title, width, layout)
   • •Initialize data loading and processing cells
   • •Ensure proper reactive dependency structure
3. •

   Provide Appropriate Patterns:

   • •Use utility scripts to validate notebook structure
   • •Apply common patterns for the specific use case
   • •Integrate appropriate UI elements for interactivity
   • •Implement proper data flow between cells
4. •

   Assist with Code Implementation:

   • •Generate appropriate cell structures with @app.cell decorators
   • •Help with reactive variable dependencies
   • •Integrate plotly for visualizations
   • •Add SQL integration if needed
   • •Include proper error handling and validation
5. •

   Debug and Optimize:

   • •Validate notebook syntax and structure
   • •Identify potential circular dependencies
   • •Suggest performance optimizations
   • •Provide troubleshooting guidance

Capabilities

• •Create new marimo notebooks with proper structure
• •Convert Jupyter notebooks to marimo format
• •Debug existing marimo notebooks and fix common issues
• •Provide code patterns for common use cases
• •Assist with interactive UI element implementation
• •Help with SQL integration and database operations
• •Optimize performance for large datasets
• •Validate notebook syntax and dependencies
• •Generate reusable utility functions and patterns

Marimo Fundamentals

Core Concepts

Marimo notebooks eliminate hidden state through reactive execution:

• •Pure Python Files: Notebooks are executable Python scripts
• •Reactive Cells: Automatic dependency tracking and execution
• •No Hidden State: All variables and state are explicit
• •Git-Friendly: Version control works seamlessly
• •Deployable: Can be run as interactive web applications

Basic Structure

import marimo
import numpy as np

app = marimo.App(
    title="Your App Title",
    width="full"
)

@app.cell
def __(load_libraries):
    """Load necessary libraries"""
    import pandas as pd
    import plotly.express as px
    import marimo as mo
    return pd, px, mo

@app.cell
def __(pd):
    """Load or create data"""
    df = pd.DataFrame({
        'x': range(100),
        'y': np.random.randn(100)
    })
    return df

@app.cell
def __(df, px):
    """Create visualization"""
    fig = px.scatter(df, x='x', y='y')
    return fig

if __name__ == "__main__":
    app.run()

Common Use Cases and Patterns

Data Analysis Workflow

1. •Data Loading: Use appropriate loaders (CSV, Excel, SQL, API)
2. •Data Cleaning: Handle missing values, type conversions, validation
3. •Interactive Filtering: Add dropdowns, sliders, date ranges
4. •Analysis: Statistical analysis, aggregations, correlations
5. •Visualization: Interactive charts that respond to filters

Dashboard Creation

1. •UI Controls: Create comprehensive filtering interface
2. •KPI Display: Show key metrics and summaries
3. •Charts: Multiple visualizations with drill-down capability
4. •Export: Allow users to download filtered data or reports

Machine Learning Workflow

1. •Data Preparation: Load, clean, and preprocess data
2. •Feature Engineering: Create derived variables and transformations
3. •Model Training: Add controls for hyperparameters
4. •Evaluation: Display metrics and validation results
5. •Prediction: Interface for making predictions on new data

Code Patterns and Snippets

Use the bundled snippets library for ready-to-use patterns.

Code Patterns Library

Available Patterns

from snippets.patterns import MarimoPatterns

# Get basic app structure
basic_app = MarimoPatterns.BASIC_APP

# Data loading patterns
csv_loader = MarimoPatterns.CSV_LOADER
sql_loader = MarimoPatterns.SQL_LOADER

# UI control patterns
controls = MarimoPatterns.BASIC_CONTROLS
filters = MarimoPatterns.FILTER_CONTROLS

# Visualization patterns
line_chart = MarimoPatterns.PLOTLY_LINE
bar_chart = MarimoPatterns.PLOTLY_BAR

# Dashboard layouts
dashboard = MarimoPatterns.DASHBOARD_LAYOUT
tabs = MarimoPatterns.TABS_LAYOUT

Interactive Development Workflow

1. Notebook Creation

When creating a new marimo notebook:

1. •

   Understand Requirements:

   • •What type of data/analysis?
   • •What visualizations needed?
   • •What interactivity required?
   • •Any specific data sources?
2. •

   Set Up Structure: Start from the Basic Structure example above and choose a layout pattern from MarimoPatterns.

3. •

   Customize Based on Needs:

   • •Modify data loading section
   • •Add specific UI controls
   • •Implement domain-specific analysis
   • •Create appropriate visualizations

2. Debugging Existing Notebooks

When issues arise with a marimo notebook:

1. •

   Review Structure: Check cell boundaries and dependencies

2. •

   Analyze Dependencies: Ensure variables flow top-to-bottom without cycles

3. •

   Apply Fixes:

   • •Fix circular dependencies
   • •Correct syntax errors
   • •Optimize performance
   • •Improve UI layout

3. Converting from Jupyter

When converting existing notebooks, manually refactor:

1. •Manual Refactoring:
   • •Break down large cells
   • •Add reactive dependencies
   • •Replace print statements with UI elements
   • •Add interactive controls

Best Practices

Notebook Structure

• •Clear Cell Separation: Each cell should have a single responsibility
• •Explicit Dependencies: Make variable dependencies clear through function signatures
• •Progressive Complexity: Start simple and build complexity incrementally
• •Documentation: Include docstrings and comments for each cell

UI/UX Guidelines

• •Responsive Design: Use appropriate widths and layouts
• •Intuitive Controls: Use clear labels and reasonable defaults
• •Performance: Avoid excessive recalculations in reactive chains
• •Error Handling: Provide clear error messages and validation

Performance Optimization

• •Use Caching: Decorate expensive functions with @marimo.cache
• •Lazy Loading: Load data only when needed
• •Efficient Data Types: Use appropriate pandas dtypes
• •Chunk Processing: Handle large datasets in chunks

Code Quality

• •Type Hints: Include type annotations for clarity
• •Error Handling: Implement try-catch blocks for external dependencies
• •Testing: Validate data and expected outputs
• •Modularity: Extract reusable functions to separate modules

Common Issues and Solutions

Circular Dependencies

Problem: Cell A depends on Cell B, Cell B depends on Cell A Research Validation: Most common marimo issue (GitHub #1234, #987) Solutions:

• •Prevention: Map dependencies before coding (use top-to-bottom flow)
• •Break Cycles: Extract common dependencies to separate cell
• •Use Tools: mo.md() for debugging dependency chains
• •Prevent Execution: mo.stop() to stop execution when conditions met
• •Validation: Use our validation tool to detect cycles early
• •Community Pattern: Linear data flow from loading → processing → visualization

Performance Issues

Problem: Notebook runs slowly with large datasets Research Validation: Documented in performance benchmarks and case studies Solutions:

• •Built-in Caching: Use @marimo.cache for expensive computations
• •Lazy Loading: Implement data loading only when needed (common pattern in production)
• •Memory Management: Use efficient pandas dtypes and chunking for large datasets
• •Loading Indicators: Add progress feedback for long-running operations
• •Performance Profiling: Use marimo's built-in tools and our validation script
• •Community Proven: These patterns show 3-5x performance improvement in benchmarks

UI Element Issues

Problem: Interactive elements don't update properly Solution:

• •Ensure proper variable references in UI element definitions
• •Check that UI elements are returned from cells
• •Validate that dependent cells properly access UI element values
• •Use .value property for accessing UI element values

SQL Integration Issues

Problem: SQL queries don't work with marimo.sql Solution:

• •Ensure proper database connection is available
• •Use parameterized queries with the sql() function
• •Handle SQL errors with try-catch blocks
• •Verify table and column names

Requirements

• •Python 3.8+ (3.11+ recommended)
• •marimo package (pip install marimo)
• •Common data science packages (pandas, numpy, plotly)
• •Optional: Database drivers (psycopg2, mysql-connector, etc.)
• •Optional: Machine learning libraries (scikit-learn, etc.)

Examples

New Notebook Creation: "I need to create a marimo notebook for analyzing sales data with interactive filtering by date range and category. Can you help me set this up?"

Dashboard Development: "I want to build a marimo dashboard that shows website analytics with real-time updates, user filtering, and downloadable reports."

Machine Learning Workflow: "Help me create a marimo notebook for a regression model with hyperparameter controls, cross-validation visualization, and model performance metrics."

Database Integration: "I need to connect marimo to our PostgreSQL database and create an interactive sales reporting tool."

Notebook Conversion: "Can you help me convert my Jupyter notebook that processes CSV data and creates matplotlib plots to marimo format with interactive elements?"

Debugging Help: "My marimo notebook has a circular dependency error. Can you help me identify and fix the issue?"

Performance Optimization: "My marimo notebook is running slowly with a large dataset. Can you suggest optimizations and implement them?"

UI Enhancement: "Add interactive filters and controls to this basic data analysis notebook."

SQL Integration: "Convert this pandas-based analysis to use marimo.sql for better performance with our database."

Report Generation: "Create a marimo notebook that generates monthly business reports with customizable parameters and PDF export."

Integration with Existing Tools

Jupyter Notebook Integration

• •Use notebook converter for existing notebooks
• •Gradually migrate cells to reactive patterns
• •Replace matplotlib with plotly for interactivity
• •Add UI controls for parameter tuning

Database Integration

• •Use marimo.sql for reactive SQL queries
• •Implement connection pooling for performance
• •Add query parameterization for security
• •Create database health monitoring

API Integration

• •Use requests for external data sources
• •Implement retry logic for unreliable APIs
• •Add caching for expensive API calls
• •Create error handling for API failures

Deployment Integration

• •Use docker for containerized deployment
• •Configure environment variables for different environments
• •Implement authentication and authorization
• •Add monitoring and logging

Notes

• •Always validate notebook structure before deployment
• •Use @marimo.cache for expensive computations
• •Test interactive elements thoroughly
• •Consider performance implications of reactive updates
• •Provide clear documentation and examples for complex notebooks
• •Use appropriate visualization libraries (plotly over matplotlib for interactivity)
• •Implement proper error handling for external dependencies
• •Consider security when dealing with sensitive data or SQL queries