Korben

Hackable personal assistant

About Korben

What is Korben?

Korben is a hackable personal automation framework designed for power users who want to automate their day-to-day tasks with AI agents. Built on ControlFlow and Prefect, it features an auto-discovery plugin system that makes extending the framework trivial.

Create a folder with tasks.py or flows.py, and Korben automatically discovers and registers your functions. No configuration files to edit, no manual registry updates - it just works. Bing badda boom!

Philosophy

  • Zero-Config Extensibility: Auto-discovery means you just write code and it works
  • Simple but Powerful: Clean APIs with sophisticated capabilities
  • Batteries Included: Pre-built plugins for common automation needs
  • Composability First: Generic tasks that combine into powerful workflows
  • State Management: Built-in tracking to resume workflows seamlessly
  • Developer-Friendly: Python-based with sensible defaults

Core Technologies

  • ControlFlow: AI agent framework for orchestrating LLM-powered tasks
  • Prefect: Workflow orchestration with optional cloud deployment
  • OpenAI Whisper: Audio transcription
  • Python 3.13+: Modern Python with type hints and async support

Built-in Plugins & Use Cases

Korben ships with several ready-to-use plugins:

Podcasts Plugin

Complete workflow for podcast automation:

  • Download from RSS/Apple Podcasts feeds
  • Transcribe using Whisper
  • Extract insights with AI (extract_wisdom)
  • Convert to formatted HTML
  • Email summaries automatically

Perfect for staying on top of your favorite podcasts without the time commitment.

Mallory Plugin

Daily security intelligence:

  • Fetch latest cybersecurity stories from Mallory API
  • Generate AI summaries
  • Email formatted reports

Stay informed about security trends without drowning in feeds.

Movies Plugin

Discover trending movies:

  • Query TMDB with genre, rating, date filters
  • Get popular/trending movies
  • Email formatted recommendations with ratings and descriptions

Books Plugin

Find and recommend books:

  • Search ISBNdb by query, subject, or author
  • Get book details including synopsis, ISBN, publisher
  • Email formatted book recommendations

Utilities Plugin

Composable building blocks for custom workflows:

  • extract_wisdom - AI-powered insight extraction
  • markdown_to_html - Format conversion
  • send_email - Email delivery via Postmark
  • read_file / write_file - File I/O operations

Email & Slack Plugins

Notification and delivery:

  • Email via Postmark API
  • Slack webhooks for notifications

Build Custom Plugins

Creating new plugins is trivial with auto-discovery:

# Create plugin directory
mkdir -p src/plugins/weather

# Add tasks.py
cat > src/plugins/weather/tasks.py << 'EOF'
def get_forecast(**kwargs):
    """Get weather forecast for a location."""
    location = kwargs.get('location', 'San Francisco')
    return f"Weather for {location}: Sunny, 75°F"
EOF

# Done! Automatically discovered and ready to use
python korben.py --list  # Shows: get_forecast
python korben.py --task get_forecast --location "Paris"

No registry edits, no configuration files - just write code and run!

Architecture

Korben uses a plugin-based architecture with auto-discovery:

Plugin Structure

Each plugin is a self-contained directory in src/plugins/:

src/plugins/
├── movies/
│   ├── __init__.py          # Plugin marker
│   ├── tasks.py             # Task implementations (auto-registered)
│   ├── flows.py             # Workflows (auto-registered)
│   ├── lib.py               # Plugin-specific libraries
│   ├── config.yml.example   # Configuration template
│   └── README.md            # Documentation
├── podcasts/
├── books/
├── mallory/
└── utilities/

Auto-Discovery System

Zero configuration needed! The system automatically:

  1. Scans src/plugins/ for plugin directories
  2. Imports tasks.py and flows.py from each plugin
  3. Discovers all public functions via introspection
  4. Registers them in global TASKS and FLOWS dictionaries

Convention:

  • ✅ All public functions in tasks.py → registered as tasks
  • ✅ All public functions in flows.py → registered as flows
  • ✅ Flow names ending with _workflow → suffix auto-removed
  • ❌ Functions starting with _ → private (not registered)

Plugin Dependencies

Plugins can declare dependencies:

__dependencies__ = ['utilities', 'email']

The system validates dependencies exist before registration and disables plugins with missing dependencies, preventing runtime errors.

Component Layers

  1. Plugins (src/plugins/) - Self-contained modules with tasks and flows
  2. Registry (src/registry.py) - Auto-populated via plugin discovery
  3. CLI (korben.py) - Simple command-line interface to run anything
  4. Core Utilities (src/lib/) - Shared utilities (config access, etc.)

This architecture makes adding new capabilities trivial while keeping the codebase maintainable. Just create a folder and write code!

Why “Korben”?

Named for Korben Dallas: galactic cabbie, multipass legend, and proud owner of sci-fi’s boldest haircut. This framework can’t get you a flying taxi or a Leeloo, but it will automate your life in style. Big bada boom!

Open Source

Korben is MIT licensed and built in the open. Contributions welcome!

Getting Started

# Clone and install
git clone https://github.com/korbenai/korben
cd korben/local/korben
pdm install

# Configure core settings
cp config/core.yml.example config/core.yml

# Set environment variables (add to ~/.zshrc or ~/.bashrc)
export PERSONAL_EMAIL="[email protected]"
export POSTMARK_API_KEY="your-postmark-api-key"
export MALLORY_API_KEY="your-mallory-api-key"      # Optional
export TMDB_API_KEY="your-tmdb-api-key"            # Optional - themoviedb.org
export ISBNDB_API_KEY="your-isbndb-api-key"        # Optional - isbndb.com

# Configure plugins (optional)
cp src/plugins/podcasts/config.yml.example src/plugins/podcasts/config.yml
vim src/plugins/podcasts/config.yml

# List available tasks and flows
pdm run python3 ./korben.py --list

# Run workflows
pdm run python3 ./korben.py --flow podcast
pdm run python3 ./korben.py --flow mallory_stories
pdm run python3 ./korben.py --flow trending_movies

# Run individual tasks
pdm run python3 ./korben.py --task extract_wisdom --text "Your text..."

Optional: Deploy to Prefect Cloud

For scheduled execution and monitoring:

# Login to Prefect Cloud (free tier)
prefect cloud login

# Deploy workflows (daily at 6 AM PST)
pdm run python3 deployments/prefect_cloud.py

# Start worker
prefect worker start --pool default-pool

Check out the GitHub repository for detailed documentation, examples, and plugin development guides.