rhylthyme 0.1.0
A tool for working with real-time program schedules
Requires Python: >=3.12

# 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:

```bash
# 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](https://www.sciencedirect.com/science/article/abs/pii/S0006899398009263), 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**](docs/FEATURES.md).

---

## 📖 Example Program

Here's a simple breakfast preparation program:

```json
{
  "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

```json
{
  "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

```bash
# 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**](docs/INSTALLATION_GUIDE.md).

---

## 🏃‍♂️ Usage

### CLI Runner

```bash
# 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:

```bash
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:
```bash
rhylthyme-web --port 8080 --debug
```

#### Command Line Visualization

```bash
# 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:

```bash
# 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**](DOCUMENTATION_INDEX.md) - Complete guide to all documentation
- 🎓 [**Getting Started Tutorial**](docs/GETTING_STARTED.md) - Complete beginner's guide with examples
- 🚀 [**Quick Start**](docs/QUICK_START.md) - Get started in minutes  
- 📖 [**Schema Guide**](docs/SCHEMA_GUIDE.md) - Complete schema documentation
- ⚡ [**Features**](docs/FEATURES.md) - Detailed feature descriptions
- 🔧 [**Installation**](docs/INSTALLATION_GUIDE.md) - Detailed setup instructions

### Tool Documentation
- 🎮 [**Program Runner**](docs/RUNNER_README.md) - Interactive execution
- ✅ [**Validator**](docs/VALIDATOR_README.md) - Program validation
- 🌍 [**Environment Catalog**](docs/ENVIRONMENT_CATALOG.md) - Resource management
- 🌐 [**Web Visualizer**](rhylthyme-web/README.md) - DAG visualization
- 📥 [**Importers**](rhylthyme-importers/README.md) - TheMealDB & protocols.io import

### Integration Guides
- 📓 [**Marimo Integration**](docs/MARIMO_README.md) - Notebook interface
- 🔌 [**MCP Server**](rhylthyme-mcp-server/README.md) - Model Context Protocol

---

## 📋 Examples

Explore working examples in the [**rhylthyme-examples**](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](LICENSE) file for details.

---

## 🆘 Support

- **🐛 Issues**: [GitHub Issues](../../issues)
- **💬 Discussions**: [GitHub Discussions](../../discussions)  
- **📖 Documentation**: [Documentation Index](DOCUMENTATION_INDEX.md)
- **📧 Contact**: See individual repository contacts

---

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