marimo

What this skill does

# 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
```python
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
```python
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 ou