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:

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:

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