gemstone-nexus · Phase 6

GemStone-Nexus — Contract Notes

← Documents

Metadata

iddoc_idtitlecategorysource_pathsummarycontent_hashindexed_at
45CONTRACT-NOTESGemStone-Nexus — Contract NotesreferenceDevResources/docs/contract-notes.mdBehavioral contract for the ported stack. These notes capture what the API and voice loop promise, and what changed during the port from a prior StackOne extraction.4bf0574ce2faa915a344c5aaf4565d2d74dbe93d2026-11-18 16:51:43

Content

# GemStone-Nexus — Contract Notes

Behavioral contract for the ported stack. These notes capture what the API and
voice loop promise, and what changed during the port from a prior StackOne
extraction.

## Provenance

Sourced from a prior StackOne extraction (`backend/app/gemstone/**` and related
`mcp/`, `api/v1/gemstone_ops.py`, `static/gemstone-voice.js`, `voice/`) into a
standalone package under `api/app/`. The origin tree remains frozen and untouched.
The new stack has **no coupling** back to that origin: no cross-repo imports, no
shared ledger, no dependency on `10.0.0.228`.

## Inference modes

| Mode | Chat | TTS | Grounding |
|------|------|-----|-----------|
| `sovereign` (default) | Ollama (local GPU) | Piper (local) | Ledger-grounded only |
| `development` | Gemini (external) | Gemini TTS | Ledger + general knowledge |

- Canonical ops switch: `PUT /api/v1/gemstone/ops/inference-mode` (body `{ "mode": "sovereign" | "development" }`),
  implemented in `api/app/gemstone/ops.py`. Mode is persisted in the ledger
  `GemStoneConfig` table so it survives restarts.
- Convenience aliases also exist on the MCP gemstone router
  (`GET|POST /mcp/gemstone/mode`). Prefer
  `PUT /api/v1/gemstone/ops/inference-mode` for ops automation and health-coupled mode changes.
- Default chat model is `llama3.1:8b` (configurable via `OLLAMA_CHAT_MODEL`).
  This replaces the prior extraction's `tinyllama`, which was a RAM/speed workaround on
  CPU; the T4 GPU removes that constraint.

## HTTP surface

| Route | Purpose |
|-------|---------|
| `GET /` | Chat + voice UI (inline HTML) |
| `GET /health` | Liveness for compose/nginx healthcheck |
| `GET /mcp/health` | Ledger + subsystem health |
| `GET /mcp/state` | Current phase/signals from the ledger |
| `POST /mcp/chat` | Non-streaming chat |
| `POST /mcp/chat/stream` | SSE streaming chat |
| `POST /mcp/write` | Ledger write (allow-listed tables) |
| `PUT /api/v1/gemstone/ops/inference-mode` | **Canonical** switch inference mode (persisted) |
| `GET /api/v1/gemstone/ops/status` | Ops status including inference mode + voice health |
| `GET|POST /mcp/gemstone/mode` | Alias: get/set inference mode |
| `POST /mcp/gemstone/voice/synthesize` | TTS (Piper or Gemini per mode) |
| `GET /mcp/atlas/health` | Phase 2A Atlas Index B health (stub or remote) |
| `POST /mcp/atlas/query` | Atlas context retrieval (MCP Index B client) |
| `POST /mcp/atlas/signal` | Fine-tuning signal write to Atlas Vault |
| `POST /mcp/atlas/recall` | Named/dated session recall |
| `POST /mcp/atlas/index` | Upsert session summary for recall |
| `POST /mcp/gemstone/correction` | Practitioner correction → Atlas signal |

> **Auth note:** The prior StackOne ops endpoints were auth-gated. For the
> standalone stack, auth was removed at the app layer — access control is
> expected at the network edge (nginx / security group). Re-add app auth before
> exposing beyond the intended audience.

## Atlas Vault (Phase 2A)

- GemStone is an **MCP client** to a remote Atlas Vault (MCP Index B).
- Config: `ATLAS_MCP_ENDPOINT`, `ATLAS_MCP_API_KEY`, `ATLAS_MCP_MODE`.
- When the endpoint is unset, an in-process **stub vault** satisfies gates;
  see `DevResources/docs/DOC-Atlas-Index-B.md` for the remote contract and how
  to point at a real vault. No Atlas credentials are present in
  `DATARIGHT_DEV_SECRETS` at Phase 2A close.
## Ledger (standalone)

- Fresh StackOne-pattern SQLite DB, schema in `api/app/ledger/schema.sql`,
  initialized idempotently on startup (`init_db`).
- Default path `LEDGER_DB`: local dev `./data/ledger.db`; container
  `/app/data/ledger.db`; AWS `/mnt/docker-data/gemstone/ledger.db`
  (persistent EBS). All overridable via env.
- `gather_context` (RAG) reads `ContextIndex`, `RulesEngine`, `Glossary`,
  `DecisionLog`, `Abstract`; defensive against empty/missing tables on a fresh DB.
- Embeddings run on local Ollama (`nomic-embed-text`); a deterministic
  **hash-stub fallback** is retained for when Ollama is unavailable.

## Voice loop

Two distinct conversational engines, chosen by inference mode:

### Sovereign (wake-word turn loop)
- Client: `web/gemstone-voice.js` — Web Speech API for wake-phrase + capture,
  falls back to Whisper STT. Wake/end phrases from `GEMSTONE_*` env.
- Server: Whisper STT container + Piper TTS container.
- Turn-based: "Hey Gemstone" → capture → transcribe → answer → speak → idle.
  Wake-word gating is intentional here (hands-free field mode).
- Whisper hardening: uploads under `WHISPER_MIN_AUDIO_BYTES` (default 2000) and
  ffmpeg-undecodable clips (short taps / silence / false VAD) return
  `{"text":"","no_speech":true}` with HTTP 200 — not a 502. Only a genuine
  Whisper outage (connection/timeout) returns 503 (`WhisperUnavailable`). The
  STT model sent to faster-whisper-server is now `WHISPER_MODEL` (large-v3), not
  the `whisper-1` alias.
- **Latency (2026-07 measured on live):** Whisper CUDA cold start was ~20–24s STT;
  warm STT ~0.7s. Gemini TTS default was ~1.8s/chunk; Piper `en_US-lessac-medium`
  stream first-chunk ~0.18s. Turn-based path now defaults to Piper fast voice,
  keeps Whisper warm via API keepalive (`WHISPER_WARM_INTERVAL_SEC`), uses 450ms
  utterance silence (was 800), and prefetches sentence TTS while playing. Gemini
  Live continuous path is unchanged.

### Development / External (Gemini Live full-duplex — PRIMARY)
- Client: `web/gemstone-live.js` (`GemStoneLive`) — continuous mic capture
  (PCM16 16 kHz) and streamed assistant playback (PCM16 24 kHz). No wake word:
  enabling Conversation in Dev/External starts a continuous session that stays
  ACTIVE; only a generous idle timeout (15 min) ends it. This replaces the
  premature "Session ended — say Hey Gemstone" behavior for desktop conversation.
- Server bridge: `api/app/ws/gemstone_live.py` at `ws(s)://…/ws/gemstone/live`
  proxies the browser to Gemini Live (`BidiGenerateContent`). The Gemini API key
  never reaches the browser. Server-side VAD + barge-in: Gemini's `interrupted`
  signal is forwarded so the client flushes playback and keeps listening.
- Models churn/retire fast. Default `GEMINI_LIVE_MODEL=gemini-3.1-flash-live-preview`
  with `GEMINI_LIVE_MODEL_FALLBACKS`; the bridge auto-tries candidates on connect
  (retired `gemini-live-2.5-flash-preview` / `gemini-2.0-flash-live-001` shut down
  2025-12-09). Real-time Google Search grounding is added when
  `GEMSTONE_DEV_REALTIME_DATA` is on.
- Requires `GEMINI_API_KEY` in the API container env (host `.env`, sourced from
  `DATARIGHT_DEV_SECRETS`). Live is advertised in `/mcp/gemstone/voice/config`
  (`live.available`) only when mode=development AND the key is present.
- Streaming chat over SSE requires nginx to disable buffering on
  `/mcp/chat/stream` (configured in `nginx/nginx.conf`). WebSocket upgrade for
  `/ws/` paths must be proxied by nginx.

## Known-good settings preserved

- `OLLAMA_READ_TIMEOUT=45`
- `OLLAMA_MAX_CONTEXT_CHARS=6000`
- Wake phrases, silence timeouts, Piper voice — see `.env.example`.
- Gemini secrets pattern: `APP_SECRETS_ARN` (AWS) or `.env` (local dev).

## Intentionally not ported

- The prior extraction's Atlas ledger, Postgres embeddings, and non-GemStone services
  (webapp, workers, MQTT, Redis) — replaced by the standalone SQLite ledger.
- Cross-app navigation in the original inline HTML — removed for the standalone UI.