---
title: IRis Compiler Optimization Environment
emoji: ⚡
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
app_port: 8000
base_path: /web
tags:
  - openenv
---

# IRis Compiler Optimization Environment

An OpenEnv environment where an **LLM agent selects LLVM optimization passes** to minimize execution time of C programs compiled for **RISC-V architecture**. The agent builds a sequence of compiler passes, then compiles and measures performance against standard optimization level baselines (O0-O3).

## Quick Start

```python
from compiler_env import CompilerAction, CompilerEnv

with CompilerEnv.from_docker_image("compiler_env-env:latest") as env:
    # Start episode - picks a C program and computes baselines
    result = env.reset()
    print(f"Program: {result.observation.data['program']}")
    print(f"O3 baseline: {result.observation.data['baselines']['O3']}s")

    # Build a pass sequence
    for pass_name in ["mem2reg", "simplifycfg", "instcombine", "licm", "gvn"]:
        result = env.step(CompilerAction(action=f"add_pass:{pass_name}"))
        print(f"Added {pass_name}, reward so far: {result.reward}")

    # Compile and measure
    result = env.step(CompilerAction(action="compile_and_measure"))
    print(f"Execution time: {result.observation.data['execution_time']}s")
    print(f"Final reward: {result.reward}")
```

## How It Works

1. **reset()** picks a C program (random from 200 training programs, or a fixed eval task)
2. The environment compiles it with `-O0`, `-O1`, `-O2`, `-O3` and measures each on QEMU -> **baselines**
3. The agent calls tools to build an optimization pass sequence
4. **compile_and_measure** runs the full pipeline: `clang -> opt (agent's passes) -> llc -> gcc -> qemu`
5. Reward is based on how the agent's execution time compares to baselines

## Action Space

| Action | Format | Description |
|--------|--------|-------------|
| `add_pass` | `add_pass:<pass_name>` | Add an LLVM pass to the sequence |
| `compile_and_measure` | `compile_and_measure` | Compile & run, ends episode |
| `get_program_info` | `get_program_info` | Get program name + baselines |
| `list_passes` | `list_passes` | List all 44 valid LLVM passes |
| `get_current_sequence` | `get_current_sequence` | Get current pass sequence |

## Observation

**CompilerObservation** fields:
- **data** (dict) - Action-specific data (baselines, sequences, execution times, etc.)
- **status** (str) - `"success"`, `"error"`, `"invalid_pass"`, `"failed"`
- **message** (str) - Human-readable description
- **reward** (float) - Cumulative episode reward
- **done** (bool) - Whether the episode has ended

## Reward Structure (Partial Progress)

| Event | Reward |
|-------|--------|
| Valid pass added | +0.05 |
| Invalid pass attempted | -0.2 |
| Missing pass argument | -0.1 |
| Beat O3 baseline | +1.0 |
| Beat O2 baseline | +0.5 |
| Beat O1 baseline | +0.3 |
| Beat O0 baseline | +0.1 |
| Compilation failure | -0.5 |

## Evaluation Tasks

| Task ID | Program | Difficulty |
|---------|---------|------------|
| `easy` | `01_insertion_sort.c` | Simple sorting algorithm |
| `medium` | `08_strassen_matrix.c` | Matrix multiplication |
| `hard` | `114_polynomial_multiply_fft.c` | FFT-based polynomial multiply |

## System Requirements

The Docker image includes all needed tools:
- **clang** + **llvm** (opt, llc) - LLVM compilation toolchain
- **gcc-riscv64-linux-gnu** - RISC-V cross-compiler
- **qemu-user** (qemu-riscv64) - RISC-V binary emulation

## Building & Deploying

```bash
# Build Docker image
docker build -t compiler_env-env:latest -f server/Dockerfile .

# Deploy to HF Spaces
openenv push
```

## Running Locally

```bash
# Start the server
uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
```

## Project Structure

```
compiler_env/
|-- __init__.py                      # Module exports
|-- README.md                        # This file
|-- openenv.yaml                     # OpenEnv manifest
|-- pyproject.toml                   # Dependencies
|-- client.py                        # CompilerEnv WebSocket client
|-- models.py                        # CompilerAction & CompilerObservation
|-- inference.py                     # Baseline script (OpenAI API)
|-- training_programs/               # 200 C programs
|   |-- 01_insertion_sort.c
|   |-- 08_strassen_matrix.c
|   |-- 114_polynomial_multiply_fft.c
|   +-- ... (197 more)
+-- server/
    |-- __init__.py
    |-- compiler_env_environment.py  # Core environment logic
    |-- app.py                       # FastAPI app (HTTP + WebSocket)
    |-- requirements.txt
    +-- Dockerfile
```