ilo 0.8.2

ilo — a programming language for AI agents
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

# Approach 3: AST-Level Generation

Skip text entirely. The agent emits AST node IDs, not text tokens.
Each generation step picks a node type from the valid set.

## How it works

The runtime defines registries that map integer IDs to names. The agent generates instructions using integer IDs. Registry comments at the top of each program document the mappings.

## File Structure

```
; fn <name>(<params>) -> <return-type>
; Vars: 0=<name> 1=<name> ...
; Tools: 0=<name> 1=<name> ...
; Fields: 0=<name> 1=<name> ...
<instructions>
```

Registry comments (`;` prefix) map IDs to human-readable names. The VM uses integer IDs only.

## Value Expressions

Values appear as operands in instructions:

| Form | Meaning | Example |
|------|---------|---------|
| `REF <var-id>` | Reference a variable slot | `REF 0` |
| `LIT 0 "<string>"` | String literal | `LIT 0 "hello"` |
| `LIT 1 <number>` | Number literal | `LIT 1 42` |
| `LIT 2 nil` | Nil literal | `LIT 2 nil` |
| `FIELD <var-id> <field-id>` | Field access | `FIELD 0 2` |

## Instructions

### LET — bind a value to a variable slot

```
LET <dst-var-id> <expr>
```

Expression can be a CALL, arithmetic, CONCAT, OBJ, etc.

### CALL — invoke a tool

```
CALL <tool-id> <arg-count> <field-id> <value> ...
```

Example: `CALL 0 1 0 REF 0` = call tool 0, 1 arg, field 0 = variable 0.

### RET, RET_OK, RET_ERR — return a value

```
RET <expr>          -- return raw value
RET_OK <expr>       -- return ok(value)
RET_ERR <expr>      -- return err(value)
```

### IF — conditional branch

```
IF <condition> <then-stmt-count>
  <then-body instructions...>
```

The count tells the VM how many instructions follow in the branch.

### MATCH — pattern match on result type

```
MATCH <var-id> <arm-count>
  ERR <bind-id> <stmt-count>
    <err-body instructions...>
  OK <bind-id> <stmt-count>
    <ok-body instructions...>
```

### FOR — iterate over a list

```
FOR <iteration-var-id> <list-ref> <stmt-count>
  <body instructions...>
```

### MATCH_MAP — discrete value mapping

```
MATCH_MAP <var-ref> <case-count> <key1> <val1> <key2> <val2> ...
```

Example: `MATCH_MAP REF 2 3 "gold" 20 "silver" 10 "bronze" 5`

### OBJ — construct an object

```
OBJ <field-count> <field-id1> <val1> <field-id2> <val2> ...
```

### MERGE — update an object with new fields

```
MERGE <obj-ref> <field-id> <val> ...
```

### Arithmetic and Logic

```
ADD <a> <b>
SUB <a> <b>
MUL <a> <b>
GTE <a> <b>
NOT <a>
CONCAT <a> <b>
```

## Error Handling

Done via `MATCH` with `ERR` and `OK` arms. For compensate/rollback, the ERR arm calls the rollback tool before returning error. No special `compensate` instruction.

## Complete Example

```
; fn notify(user-id: text, message: text) -> result nil, text
; Vars: 0=user-id 1=message 2=user 3=sent
; Tools: 0=get-user 1=send-email
; Fields: 0=user-id 1=email 2=verified 3=subject 4=body
LET 2 CALL 0 1 0 REF 0
MATCH 2 2
  ERR 4 1
    RET_ERR CONCAT LIT 0 "User lookup failed: " REF 4
  OK 5 4
    IF NOT FIELD 5 2 1
      RET_ERR LIT 0 "Email not verified"
    LET 3 CALL 1 3 1 FIELD 5 1 3 LIT 0 "Notification" 4 REF 1
    MATCH 3 2
      ERR 6 1
        RET_ERR CONCAT LIT 0 "Send failed: " REF 6
      OK 7 1
        RET_OK LIT 2 nil
```