botstadia-interface 0.2.0

BotStadia's shared contracts: arena and agent WIT worlds, arena declarations, payloads, bundles, the policy shell's ONNX contract, replay archives, metrics files and player messages.
Documentation 
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

# botstadia-interface

The contracts between [BotStadia](https://botstadia.com)'s pieces, in one crate.

| Module | What it is |
|---|---|
| `declaration` | What an arena says about itself: inputs, outputs, bounds, no-action, control rate, budgets, wire sizes, stats, per-turn series and events. `Declaration::problems` lists anything incomplete. |
| `payload` | The per-turn input and output encoding, and the one validity rule for an output: structure, finiteness and declared bounds. Nothing is clamped. |
| `bundle` | A bot's bundle: its manifest (`botstadia.toml`), the bot kinds, and the limits on models and size. |
| `policy` | The policy shell's ONNX contract, version 1: names, metadata keys, the memory pair, and the one map from a policy's `[-1, 1]` onto declared bounds, pinned by `tests/policy-golden.json` (which `botstadia-train` checks too). |
| `archive` | The replay archive: one session's frames, for the arena's player. |
| `metrics` | The metrics file beside it: series, events, stats and the result, for the site. |
| `copy` | An arena's `arena.toml`: its name and site copy. |
| `player` | The messages between the site and an arena's player frame. |

The WIT worlds are in `wit/`: `botstadia:arena` for arena engines and `botstadia:agent` for bots. Features generate bindings for them:

| Feature | For |
|---|---|
| `arena-guest` | Arena engines (`wasm32-wasip2`), exported with `export_arena!` |
| `agent-guest` | Bots (`wasm32-wasip2`), exported with `export_agent!` |
| `host` | Anything that runs arenas and bots, on wasmtime |
| `toml` | Reading and writing `arena.toml` |
| `bundle` | Reading and writing a bundle's `botstadia.toml` |

## Developing

```sh
task check   # every target and feature set
task lint    # fmt + clippy -D warnings
task test
```

To build a consumer against a local checkout, add an untracked patch to that consumer (for example in its git-ignored `.cargo/config.toml`):

```toml
[patch.crates-io]
botstadia-interface = { path = "/path/to/botstadia-interface" }
```

## Changes

- **0.2.0:** the `agent` world is `botstadia:agent@0.2.0`, adding the `declaration` import (every arena's names, types, shapes and bounds) and the `models` import (each bundled model's inputs, outputs and charge), so one program, the policy shell, can serve every arena and model. New `bundle` and `policy` modules.
- **0.1.0:** first release.

## Licence

MIT or Apache-2.0, at your choice.