# Axial Coach — a cognitive coworker on Sauna

**Sauna × ElevenLabs hackathon.** A coworker that doesn't just remember *what* a
student did — it understands *how they think*, and coaches on it: proactively, for
the whole support system around the learner, in voice.

> **Axial** maps how a student thinks — a set of connected cognitive skills across
> six domains, scored from a diagnostic. The scoring is **deterministic and
> explainable**: every insight traces back through typed skill-to-skill dependencies
> (the *"because-trail"*). No AI decides a score.

This project connects Axial to **Sauna** as a custom **MCP** connector, so Sauna can
reason and act on a student's real cognitive profile from any surface — and gives it
a **voice** with **ElevenLabs**.

**Axial gives the substance. Sauna gives the hands. ElevenLabs gives the voice.**

---

## What it does

Once Axial is connected to Sauna (one URL — see below), Sauna can:

- **Explain, grounded.** "What should this student work on first, and why?" → Sauna
  answers from the real leverage + because-trail — naming the *specific* skills a
  focus unlocks. Nothing hallucinated.
- **Serve two audiences from one model.** The same profile becomes:
  - 🎮 **A gamified quest for the student** — a weekly mission, small daily wins with
    XP and a streak, encouragement anchored to a real strength. (Confidence through
    constant small wins.)
  - 🌱 **A holistic report for the parent** — status across **all six** thinking
    domains plus the week's focus and its *cross-domain ripple* — evidence that one
    small habit grows skills in multiple areas. (Holistic development, not one score.)
- **Run proactively.** A Sauna scheduled task re-pulls the live Axial profile every
  week and regenerates both — working while you're offline, not waiting to be asked.
- **Speak.** In Sauna, the coach answers in voice (ElevenLabs).

## How it's built

```
        ┌───────────────────────────────┐        Sauna (web / iMessage / Slack / email)
        │  Axial engine  (proprietary,  │         • connect via one MCP URL
        │  NOT in this repo)            │         • calls the tools, reasons, acts
        └──────────────┬────────────────┘         • speaks the answer (ElevenLabs)
                       │ run once, offline                 ▲
                       ▼                                   │ MCP (JSON-RPC over HTTP)
        maya-axial.json  (precomputed,        ┌────────────┴─────────────┐
        citation-free snapshot, 1 student) ──▶│  server.mjs   POST /mcp  │
                                              │  6 read-only tools       │
                                              └──────────────────────────┘
```

The Axial engine runs **once, offline**, and its output for one sample student is
cached in `maya-axial.json`. `server.mjs` serves slices of that snapshot over MCP —
so the coworker gets Axial's real, explainable intelligence without the engine or
taxonomy ever leaving Axial.

**MCP tools** (all read-only, plain-language, no internal ids):
`get_cognitive_profile`, `get_bottlenecks` (with because-trail), `recommend_methods`,
`get_weekly_focus`, `get_student_quest` (gamified), `get_parent_report` (holistic 6 domains).

## Run it

```bash
node server.mjs                     # starts http://localhost:8787  (/mcp)
cloudflared tunnel --url http://localhost:8787   # get a public https URL
```

Then in Sauna: **Connections → Add a Connection → MCP Server → paste `https://<tunnel>/mcp`**.
Sauna probes the server, discovers the tools, and you can ask it about the student.

*(The optional `POST /tts` route is a standalone ElevenLabs proxy; it needs
`ELEVENLABS_API_KEY` in the environment. In the demo, voice comes from Sauna's
built-in ElevenLabs, so this route isn't required.)*

## Sponsors

- **Sauna** — the multiplayer AI coworker. Custom MCP connector; proactive scheduled
  runs; the two-audience coaching; voice.
- **ElevenLabs** — the coach's voice.

## A note on IP

Axial's scoring engine, its full cognitive taxonomy, and the cited research behind it
are **proprietary and deliberately not included here**. This repository contains only
the Sauna integration and a **precomputed, citation-free snapshot for one sample
demo student** (no real student data, no effect sizes, no sources). It is a hackathon
demo, not the Axial product.