integrations/qwythos_system_snippet.md

# Qwythos / Pi bridge — spatial tool wiring

The HOA-7 spatial calculator is **not** part of the LLM weights. Qwythos should
call it as a tool and treat the JSON / one-liner as ground-truth geometry.

## Runtime

| Piece | Address |
|-------|---------|
| Qwythos (llama-server) | `http://127.0.0.1:8000/v1` |
| Olympus Pi bridge | `http://127.0.0.1:8642` |
| **spatial-hoa API** | `http://127.0.0.1:8765` |
| CLI on PATH | `spatial-report` |

Enable API at login:

```bash
systemctl --user enable --now spatial-hoa.service
curl -s http://127.0.0.1:8765/health
```

## For Pi bridge (bash tool)

Pi already has `bash`. Instruct the agent:

```text
When the user asks about spatial audio/location/direction of sound or objects,
run one of:
  spatial-report demo-scene -o /tmp/spatial.json && cat /tmp/spatial.json
  spatial-report analyze /path/to.wav --ambix -o /tmp/spatial.json && cat /tmp/spatial.json
  spatial-report analyze /path/to.wav --az DEG --el DEG -o /tmp/spatial.json
  spatial-report vision --boxes '[{"az":0,"el":0,"label":"obj"}]' -o /tmp/v.json
Or HTTP:
  curl -s -X POST http://127.0.0.1:8765/v1/spatial/analyze \
    -H 'Content-Type: application/json' \
    -d '{"mode":"demo_scene","order":3}'
Use the returned one_liner and doa_* fields as factual spatial state.
```

Optional: append that block to the Pi system prompt / AGENTS notes.

## OpenAI tool schema

See `tools/spatial_analyze.openai.json` for a function-calling descriptor
compatible with agents that support tools against a custom executor.

## Coordinates (always)

- Azimuth 0° = front, +90° = left, −90° = right  
- Elevation 0° = horizon, +90° = zenith