[Feat] Served Laya as a decision model (--model laya-served)

[cacheline999]

Why

Closes #20. --model laya loads Laya in every process, so each CLI run and each MCP call pays the load and nothing shares a warm model. system1-omni can now keep Laya warm in a worker (ThinkFlowLab/system1-omni#30), and this PR lets agents use it.

How

s1a/decision_models/served.py is the new backend. Open it first.

• ServedLayaClient posts to /v1/systemone and owns the connection handling:

  • one deadline per decision (LAYA_SERVED_TIMEOUT_S, default 5 s);
  • one retry on a dropped connection, a 502 or a 504;
  • one retry after Retry-After on a 503;
  • one X-Request-Id per decision, reused on the retry;
  • every other status mapped to MODEL_CALL_FAILED or MODEL_SERVICE_CONFIG_ERROR.

• ServedLayaModel builds the same body as in-process Laya with laya_question(). It shares the full-window check with LayaModel, now check_window() in laya.py.

• It also records who answered: Decision.model is <checkpoint>@<revision>. The details come from the response's served_by when a server sends one. Otherwise they come from the worker's /health, re-read after 30 s, since the worker reports there when Laya falls back to the CPU. Plain laya-serve reports less, so the record keeps routing.repo for it.

• The contract is written down in docs/served-laya.md, as design and trade-offs. There are two OpenAPI 3.1 specs in docs/api/:

  • laya-systemone.current.openapi.yaml is today's servers, checked against recorded traffic;
  • laya-systemone.openapi.yaml is the target, with problem+json errors, served_by, Server-Timing and /readyz.

  The gap between the two belongs to system1-omni; section 4 of the doc lists where each part would go.

What

• --model laya-served works on every agent, on decide, on the rails and in MCP decide. tests/test_served_laya_registration.py fails if a new list offers laya without it.
• Environment variables:
  • LAYA_SERVED_URL is required: the worker, omni-jev or laya-serve.
  • Optional: LAYA_SERVED_MODEL, LAYA_SERVED_API_KEY, LAYA_SERVED_TIMEOUT_S, LAYA_SERVED_MAX_LEN.
  • No cloud key is read.
• Tool-front ticks now keep model for every decision model. A served model's ticks also keep served_by, url, request_id and server_timing.
• Docs: decision-models.md, configuration.md, .env.example, the CHANGELOG, and a run section in served-laya.md.
• The dev extra gains jsonschema, pyyaml and referencing for the spec check (pyproject.toml, uv.lock, CONTRIBUTING). They were already in the environment through mcp and openjiuwen.
• The branch also moves the laya extra to 0.3.20, the version the worker runs.

The worker features used here (warm before listening, a live /health with checkpoint, revision and device) come from ThinkFlowLab/system1-omni#30, which is still open. Against plain laya-serve everything works, with the checkpoint as the only identity. The run section links the recipe on the PR branch until it merges.

Results

ticket_router on an M1 Pro, 3 seeds × 30 tickets per configuration. Laya is checkpoint 55cf4c4 with laya 0.3.20. The worker is system1-omni 3d6cb57 (the head of ThinkFlowLab/system1-omni#30), started with --compile --weights fp16. Details, commands and every decision are in evals/ticket_router/SERVED_LAYA.md.

	correct	p50 ms	p95 ms
in process (--model laya, MPS, fp32)	63/90	88	101
worker, direct	63/90	72	88
worker through omni-jev	63/90	72	76

All three routed every one of the 90 decisions the same. In-process and worker probabilities differ by at most 0.001. In-process Laya is slower here because it runs fp32 and uncompiled, not because of HTTP.

Open questions

• The name laya-served, chosen so records tell served runs from in-process ones.
• The target interface in docs/api/laya-systemone.openapi.yaml. If it looks right, the worker-side parts belong in system1-omni.

Verification

• uv run ruff format --check . && uv run ruff check . && uv run ty check: all pass.

• uv run pytest -q and scripts/smoke.sh: 586 passed and 43 skipped with the laya extra installed; smoke: ok. With torch, laya and transformers blocked from import, the new tests pass (113 passed, 2 skipped), as on CI's core install.

• CHANGELOG.md and the docs say what the code does now.

• New tests run over httpx.MockTransport:

  • the shared DecisionModelContract;
  • each row of the error table;
  • the deadline across a retry and the window check;
  • identity, including the 30 s refresh with a fake clock.

• tests/data/served_laya/ holds 27 responses recorded from the worker, from omni-jev (with the worker up and down) and from laya-serve. They validate against the as-is spec.

• Live on the same M1 Pro and worker:

  check	result
  worker ready	after 37 s
  decide via the CLI and over MCP (stdio)	answered
  injection_guard rail	precision 0.9, recall 0.9
  ticket_router, direct and through omni-jev	21/30
  worker stopped behind omni-jev	fails with the 502 after one retry
  plain laya-serve	answers, with identity reduced to the checkpoint
  CPU worker (--device cpu) with LAYA_API_KEY set	401 without LAYA_SERVED_API_KEY; with it, 21/30 and ticks show cpu, float32, not compiled