rhylthyme 0.1.0

A tool for working with real-time program schedules

Rhylthyme

🕒 rhylthyme (pronounced "realtime") is a JSON-based workflow language for describing and executing real-time event scheduling.

---

🚀 Quick Start

American Breakfast Example

Here's a simple program that coordinates cooking eggs, bacon, and toast to finish at the same time:

# Navigate to the CLI runner directory
cd rhylthyme-cli-runner

# Validate the breakfast program
python -m rhylthyme_cli_runner.cli validate ../rhylthyme-examples/programs/breakfast_schedule.json

# Run the breakfast program
python -m rhylthyme_cli_runner.cli run ../rhylthyme-examples/programs/breakfast_schedule.json

---

💫 What is Rhylthyme?

Rhylthyme provides a structured way to define real-time programs (schedules) consisting of multiple parallel tracks with sequential steps. Originally designed for time-critical rat experiments, it now accommodates various scheduling scenarios:

• 🍳 Food Production: Restaurant kitchens, bakery operations, meal coordination
• 🔬 Laboratory Research: Experimental protocols, sample processing workflows
• ✈️ Operations Management: Airport scheduling, event planning, logistics
• 🏭 Manufacturing: Assembly lines, quality control, batch processing
• 🎬 Media Production: Film scheduling, broadcast coordination

---

🎯 Key Features

• Multi-track Execution: Run multiple parallel tracks of operations
• Resource Constraints: Enforce equipment/station availability limits
• Actor Constraints: Track and limit human attention/involvement
• Rich Start Triggers: Time-based, dependency-based, or manual triggers
• Buffer Support: Pre/post-step buffers with runtime extension capability
• Variable Durations: Fixed, variable, or indefinite step durations
• Interactive Control: Manual triggers and real-time adjustments
• Environment Catalog: Reusable environment and resource definitions
• Real-time Monitoring: Track progress with adjustable time scaling
• Schema Validation: Comprehensive program validation

For detailed information, see the Features Guide.

---

📖 Example Program

Here's a simple breakfast preparation program:

{
  "programId": "breakfast-prep",
  "name": "Breakfast Preparation",
  "environment": "home-kitchen",
  "startTrigger": {"type": "manual"},
  "tracks": [
    {
      "trackId": "eggs",
      "name": "Scrambled Eggs",
      "steps": [
        {
          "stepId": "fry-eggs",
          "name": "Fry Eggs",
          "startTrigger": {"type": "programStart"},
          "task": "stove-burner",
          "duration": {"type": "fixed", "seconds": 180}
        }
      ]
    }
  ]
}

Environment with Resource Constraints

{
  "environmentId": "home-kitchen",
  "actors": 2,
  "resourceConstraints": [
    {
      "task": "stove-burner",
      "maxConcurrent": 4,
      "actorsRequired": 1.0
    },
    {
      "task": "oven", 
      "maxConcurrent": 1,
      "actorsRequired": 0.5
    }
  ]
}

---

🛠️ Installation

Note: Rhylthyme packages are currently in development and must be installed from local directories.

Quick Installation

# Clone the repository
git clone https://github.com/yourusername/rhylthyme.git
cd rhylthyme

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install core packages
pip install -e ./rhylthyme-spec
pip install -e ./rhylthyme-cli-runner
pip install -e ./rhylthyme-web

# Verify installation
rhylthyme --help

For detailed installation instructions, see the Installation Guide.

---

🏃‍♂️ Usage

CLI Runner

# Validate a program
rhylthyme validate programs/example.json

# Run a program with interactive terminal UI
rhylthyme run programs/example.json

# Run with automatic start and 2x speed
rhylthyme run programs/example.json --auto-start --time-scale 2.0

# Optimize a program schedule
rhylthyme plan programs/example.json optimized.json

# List available environments
rhylthyme environments

# Get help
rhylthyme --help

Interactive Controls

When running a program, use these keyboard controls:

• Space: Start/stop program
• Enter: Trigger manual steps
• Arrow keys: Navigate between steps
• q: Quit
• r: Refresh display

Web Visualizer

Start the web server:

rhylthyme-web

Then open http://localhost:5000 in your browser. You can:

• Upload a local .json or .yaml file
• Paste a URL to load from https
• Try examples with one click

Options:

rhylthyme-web --port 8080 --debug

Command Line Visualization

# Generate and open visualization in browser
rhylthyme-visualize program.json

# Save to specific file without opening browser
rhylthyme-visualize program.json -o output.html --no-browser

Importers

Import schedules from external sources:

# Install importers
pip install -e ./rhylthyme-importers

# Search TheMealDB for recipes
rhylthyme-import search "chicken curry" -i themealdb

# Import a recipe
rhylthyme-import import "52772" -o curry.json --pretty

# Import a random meal
rhylthyme-import mealdb random -o random_meal.json

# Import from protocols.io (requires API token)
export PROTOCOLS_IO_TOKEN="your_token"
rhylthyme-import search "western blot" -i protocolsio

The web chat also supports importing - just ask Claude to "import a recipe for lasagna" or "find me a chicken recipe".

---

📁 Project Structure

rhylthyme/
├── rhylthyme-spec/                # Schema definitions
├── rhylthyme-cli-runner/         # Command-line interface
├── rhylthyme-web/                # Web visualizer & DAG generator
├── rhylthyme-importers/          # Import plugins (TheMealDB, protocols.io)
├── rhylthyme-examples/           # Example programs & environments
├── rhylthyme-docs/               # Documentation website
├── rhylthyme-mcp-server/         # MCP server implementation
├── docs/                         # Core documentation
├── extensions/                   # Extensions and integrations
└── DOCUMENTATION_INDEX.md        # Complete documentation index

---

📚 Documentation

Quick Links

• 📋 Documentation Index - Complete guide to all documentation
• 🎓 Getting Started Tutorial - Complete beginner's guide with examples
• 🚀 Quick Start - Get started in minutes
• 📖 Schema Guide - Complete schema documentation
• ⚡ Features - Detailed feature descriptions
• 🔧 Installation - Detailed setup instructions

Tool Documentation

• 🎮 Program Runner - Interactive execution
• ✅ Validator - Program validation
• 🌍 Environment Catalog - Resource management
• 🌐 Web Visualizer - DAG visualization
• 📥 Importers - TheMealDB & protocols.io import

Integration Guides

• 📓 Marimo Integration - Notebook interface
• 🔌 MCP Server - Model Context Protocol

---

📋 Examples

Explore working examples in the rhylthyme-examples directory:

• breakfast_schedule.json - Simple breakfast coordination
• lab_experiment.json - Laboratory protocol workflow
• bakery_program_example.json - Complex bakery production
• airport_program_example.json - Airport operations scheduling
• rat_psychopharmacology.json - Research experiment timing

---

🤝 Contributing

We welcome contributions! See individual repository README files for specific contribution guidelines.

Getting Started

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests and documentation
5. Submit a pull request

---

📄 License

Apache License 2.0 - see LICENSE file for details.

---

🆘 Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Documentation: Documentation Index
• 📧 Contact: See individual repository contacts

---

Rhylthyme: Making time-critical workflows as smooth as a perfect rhythm. 🎵