Ontonaut 🚀

Interactive widgets for marimo with pluggable backends

Ontonaut provides beautiful, marimo-compatible widgets for code execution and AI chat with customizable backends. Build domain-specific languages, create custom interpreters, or integrate AI assistants - all within your marimo notebooks!

✨ Features

CodeEditor Widget

• 🎨 Clean, marimo-style UI - Seamless integration with marimo's aesthetic
• 🔌 Pluggable executors - Python, JSON, Calculator, Regex, or your own
• 🛠️ Custom languages - Create DSLs and custom interpreters
• ⌨️ Keyboard shortcuts - Cmd/Ctrl+Enter to run
• 🌓 Light & dark themes - Follows your marimo theme

ChatBot Widget

• 💬 Streaming responses - Real-time, token-by-token output
• 📑 Automatic tabs - Each question creates a new history tab
• 💻 Code formatting - Markdown code blocks render beautifully
• 🤖 Multiple handlers - OpenAI, Anthropic, MCP, or custom
• 🎯 Type-safe - Full type hints throughout

📦 Installation

pip install ontonaut

🚀 Quick Start

CodeEditor

import marimo as mo
from ontonaut import CodeEditor, PythonExecutor

editor = CodeEditor(
    executor=PythonExecutor(),
    code="x = 10\nresult = x * 2",
    theme="dark"
)
editor

ChatBot

from ontonaut import ChatBot, EchoHandler

chatbot = ChatBot(
    handler=EchoHandler(),
    placeholder="Ask me anything...",
    theme="dark"
)
chatbot

📚 Documentation

📖 User Guides

Comprehensive guides for using Ontonaut:

• Quick Start - Get up and running in 5 minutes
• CodeEditor Guide - Complete CodeEditor documentation
• ChatBot Guide - Complete ChatBot documentation
• Executors Reference - Built-in executors
• Handlers Reference - Built-in chat handlers
• Custom Executors - Build your own
• Custom Handlers - Build your own

📓 Interactive Notebooks

Runnable marimo notebooks with examples:

• Getting Started - Basic usage
• ChatBot Guide - Complete chat examples
• OpenAI Integration - AI integration

Run them:

marimo edit book/marimo/01-getting-started.py

🏗️ Architecture Docs

For developers and AI assistants:

• Architecture Overview - System design
• Widget System - anywidget patterns
• Development Guide - Contributing

💡 Examples

Custom DSL

from ontonaut import CodeEditor

def greeting_dsl(code: str) -> str:
    """Simple greeting DSL."""
    lines = code.strip().split("\n")
    results = []

    for line in lines:
        parts = line.split()
        if len(parts) == 2:
            command, name = parts
            if command == "greet":
                results.append(f"Hello, {name}!")
            elif command == "farewell":
                results.append(f"Goodbye, {name}!")

    return "\n".join(results)

editor = CodeEditor(
    executor=greeting_dsl,
    code="greet Alice\nfarewell Bob",
    language="dsl"
)

OpenAI Chat

from ontonaut import ChatBot, OpenAIHandler
import os

chatbot = ChatBot(
    handler=OpenAIHandler(
        api_key=os.getenv("OPENAI_API_KEY"),
        model="gpt-4",
        system_prompt="You are a helpful assistant.",
        temperature=0.7
    ),
    theme="dark"
)

Custom Streaming Handler

def my_handler(message: str):
    """Custom streaming handler."""
    import time

    # Generate code example
    if "code" in message.lower():
        yield "Here's a Python example:\n\n"
        yield "```python\n"
        yield "def greet(name):\n"
        yield "    return f'Hello {name}!'\n"
        yield "```"
    else:
        words = f"You said: {message}".split()
        for word in words:
            yield word + " "
            time.sleep(0.05)

chatbot = ChatBot(handler=my_handler)

🎨 Built-in Components

Executors

• PythonExecutor - Execute Python code
• JSONExecutor - Format and validate JSON
• CalculatorExecutor - Evaluate math expressions
• RegexExecutor - Test regular expressions

Handlers

• EchoHandler - Echo back messages (testing)
• OpenAIHandler - Stream from OpenAI GPT models
• AnthropicHandler - Stream from Anthropic Claude
• MCPHandler - Model Context Protocol integration
• CustomHandler - Wrap any function

⌨️ Keyboard Shortcuts

• Cmd/Ctrl + Enter - Execute/Send
• Tab - Insert 4 spaces

🏗️ Development

Setup

git clone https://github.com/yourusername/ontonaut.git
cd ontonaut
make setup

Commands

make test     # Run tests with coverage
make lint     # Run linters (black, ruff, mypy)
make format   # Format code
make build    # Build package
make clean    # Clean artifacts

Project Structure

ontonaut/
├── src/ontonaut/          # Python package
│   ├── editor.py          # CodeEditor widget
│   ├── chatbot.py         # ChatBot widget
│   ├── executors.py       # Code execution backends
│   ├── handlers.py        # Chat handlers
│   └── static/            # Frontend assets
├── tests/                 # Test suite
├── examples/              # Example notebooks
├── book/
│   ├── markdown/          # User documentation
│   └── marimo/            # Interactive notebooks
├── docs/                  # Architecture documentation
└── scripts/               # Development scripts

🧪 Testing

make test

Coverage: 85%+ across all components

📝 Use Cases

• AI Chat Interfaces - Streaming AI assistants in notebooks
• DSL Prototyping - Test domain-specific language ideas
• Custom Interpreters - Specialized code execution
• Educational Tools - Interactive coding tutorials
• Data Transformation - Custom data processing
• Template Languages - Specialized templating
• Company Integrations - Wrap internal AI APIs

🎯 Roadmap

CodeEditor

• Syntax highlighting
• Code completion
• Multi-file support
• Debugger integration

ChatBot

• Syntax highlighting for code blocks
• Copy-to-clipboard
• Tab persistence
• Export conversations
• Async handler support

🤝 Contributing

Contributions welcome! See docs/README.md for architecture and development guidelines.

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing)
3. Run tests (make test) and linting (make lint)
4. Commit changes
5. Push to branch
6. Open Pull Request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Built with Anywidget
• Designed for marimo
• Inspired by the need for flexible, customizable widgets
• Thanks to the open source community

📚 Learn More

• User Documentation - Complete guides
• Interactive Notebooks - Runnable examples
• Architecture Docs - For developers
• Marimo Documentation
• Anywidget Documentation

🔗 Links

• Homepage: https://github.com/yourusername/ontonaut
• Issues: https://github.com/yourusername/ontonaut/issues
• PyPI: https://pypi.org/project/ontonaut/

---

Made with ❤️ for the marimo and Python communities

Start building your custom widgets today! 🚀