Korben

Hackable personal assistant

About Korben

What is Korben?

Korben is a hackable framework designed for power users who want to automate their day-to-day tasks. It makes it dead-simple to utilize AI agents for personal flows. Its built on Prefect and ControlFlow and is designed to be simple to start with a multitude of common capabilities, yet powerful and easy to extend for your own use cases.

Philosophy

  • Simple but Powerful: Clean APIs with sophisticated capabilities, organized into tasks and flows
  • State Management: Built-in tracking to resume workflows seamlessly
  • Developer-Friendly: Python-based with sensible defaults
  • Composability First: Generic tasks that combine into powerful workflows

Core Technologies

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

Built-in Flows - Use Cases

Daily Podcast Download / Analysis / Transcription / Send-To-Email

Automatically download podcasts from RSS feeds, transcribe them using Whisper, extract key insights using AI, and email formatted summaries. Perfect for staying on top of your favorite podcasts without the time commitment.

Daily Security Intelligence

Pull the latest cybersecurity stories from Mallory API, generate AI summaries, and get them delivered to your inbox. Stay informed about security trends without drowning in feeds.

Extend the framework! Build Custom Workflows

Build your own workflows by composing generic tasks like read_file, extract_wisdom, markdown_to_html, and send_email. The composable architecture makes it easy to create sophisticated pipelines.

Architecture

Korben follows a simple pattern:

  1. Tasks (src/core/tasks/) - Independent units of work with a simple run(**kwargs) interface
  2. Flows (src/core/flows/) - Orchestrate tasks using ControlFlow’s @cf.flow decorator
  3. Registry (src/core/registry.py) - Central mapping of names to tasks and flows
  4. CLI (korben.py) - Simple command-line interface to run anything

This makes it trivial to add new capabilities while keeping the codebase maintainable.

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 <repo-url>
cd korben
pdm install

# Configure - basic configuration
cp config/core.yml.example config/core.yml
export PERSONAL_EMAIL="[email protected]"
export POSTMARK_API_KEY="your-api-key"

# Configure - optional task configuration
export MALLORY_API_KEY="your key here" # https://mallory.ai

# Run a workflow
pdm run python3 ./korben.py --flow podcasts

Check out the documentation for detailed setup and usage instructions.