# AGENTS.md

Guidance for AI coding agents working in this repository.

## What this is

`strata-docker`: a bash wrapper (`strata-docker`) that builds and runs the
Intel Arc (SYCL) engine of [Strata](https://github.com/Niko1221/Strata) on a
Slackware host, using upstream's own Docker route. Target: Arc B580 (12 GB,
`xe` driver), model Gyro-M. Host needs only the `xe` driver, Docker and
Python 3.10+ with venv. No oneAPI, Level Zero or compute runtime on the host:
those live in the `strata-sycl-dev` image. Keep it a thin wrapper, do not
reimplement anything upstream's scripts already do.

## How upstream's Intel route works

- There is no prebuilt Intel engine in Strata's releases. The engine is built
  from source in the `strata-sycl-dev` image (`Strata/sycl/tools/Dockerfile`,
  based on a community llama.cpp SYCL image, about 13 GB).
- `setup.sh --backend sycl` runs `setup.py` in a `.venv` on the host, which
  hands over to `sycl/setup_intel.py`. That writes the config and
  `run-<model>.sh`. The server (`sycl/serve/server_intel.py`) runs on the
  host. Only the engine runs in Docker, through `sycl/serve/strata-sycl.sh`.
- `strata-sycl.sh` mounts the checkout's parent directory at `/work`. Hence
  the layout: `Strata/` (checkout) and `Strata-data/` (models, about 92 GB for
  Gyro-M) both inside this repo, gitignored. Symlinks pointing outside the
  mount do not work in the container.
- B580 is PCI id `e20b`, AOT target `bmg-g21`. `setup_intel.py` knows it.
- Gyro is the one family whose experts are not streamed into VRAM: it needs
  35 GB of RAM and VRAM together (Gyro-M). The host has about 30 GiB RAM and a
  12 GB card, so close other programs before starting it.
- Gyro on Arc was tested upstream only on an A750 (`i915`). The B580 is
  untested natively; one WSL2 B580 report saw device loss.
- On `xe`, asking for more VRAM than the card has does not fail: buffers
  spill into RAM and the host can livelock. Never raise `--context` or lower
  `--vram-reserve-mib` past what setup's fit rule picked.
- Pictures are off by default on Battlemage (they reset a B70). Do not pass
  `--vision yes`.
- `docker build --pull` matters: a stale base can carry an ocloc that crashes
  on Battlemage kernels (upstream #3219). `build.sh` checks for it.

## Conventions

- Pin the upstream tag in `ref` (`STRATA_REF` overrides). Bump it
  deliberately, then rerun `image` (if `sycl/tools/Dockerfile` changed) and
  `build`.
- Placeholders only in code, docs, tests and commits.

## Testing

No test suite. Check by hand: `bash -n strata-docker`, then `./strata-docker
build` must end with `BUILD EXIT 0` and `errors: 0`, and `./strata-docker
setup --check` lists what fits.

## Repo facts

- License: GPLv2 only (`LICENSE`, header in each source file).
- Work directly on master.