106 lines
4.2 KiB
Markdown
106 lines
4.2 KiB
Markdown
# Nexus — Scope & Acceptance Criteria
|
|
|
|
**Issue:** #1208
|
|
**Date:** 2026-03-23
|
|
**Status:** Initial implementation complete; teaching/RL harness deferred
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
The **Nexus** is a persistent conversational space where Timmy lives with full
|
|
access to his live memory. Unlike the main dashboard chat (which uses tools and
|
|
has a transient feel), the Nexus is:
|
|
|
|
- **Conversational only** — no tool approval flow; pure dialogue
|
|
- **Memory-aware** — semantically relevant memories surface alongside each exchange
|
|
- **Teachable** — the operator can inject facts directly into Timmy's live memory
|
|
- **Persistent** — the session survives page refreshes; history accumulates over time
|
|
- **Local** — always backed by Ollama; no cloud inference required
|
|
|
|
This is the foundation for future LoRA fine-tuning, RL training harnesses, and
|
|
eventually real-time self-improvement loops.
|
|
|
|
---
|
|
|
|
## Scope (v1 — this PR)
|
|
|
|
| Area | Included | Deferred |
|
|
|------|----------|----------|
|
|
| Conversational UI | ✅ Chat panel with HTMX streaming | Streaming tokens |
|
|
| Live memory sidebar | ✅ Semantic search on each turn | Auto-refresh on teach |
|
|
| Teaching panel | ✅ Inject personal facts | Bulk import, LoRA trigger |
|
|
| Session isolation | ✅ Dedicated `nexus` session ID | Per-operator sessions |
|
|
| Nav integration | ✅ NEXUS link in INTEL dropdown | Mobile nav |
|
|
| CSS/styling | ✅ Two-column responsive layout | Dark/light theme toggle |
|
|
| Tests | ✅ 9 unit tests, all green | E2E with real Ollama |
|
|
| LoRA / RL harness | ❌ deferred to future issue | |
|
|
| Auto-falsework | ❌ deferred | |
|
|
| Bannerlord interface | ❌ separate track | |
|
|
|
|
---
|
|
|
|
## Acceptance Criteria
|
|
|
|
### AC-1: Nexus page loads
|
|
- **Given** the dashboard is running
|
|
- **When** I navigate to `/nexus`
|
|
- **Then** I see a two-panel layout: conversation on the left, memory sidebar on the right
|
|
- **And** the page title reads "// NEXUS"
|
|
- **And** the page is accessible from the nav (INTEL → NEXUS)
|
|
|
|
### AC-2: Conversation-only chat
|
|
- **Given** I am on the Nexus page
|
|
- **When** I type a message and submit
|
|
- **Then** Timmy responds using the `nexus` session (isolated from dashboard history)
|
|
- **And** no tool-approval cards appear — responses are pure text
|
|
- **And** my message and Timmy's reply are appended to the chat log
|
|
|
|
### AC-3: Memory context surfaces automatically
|
|
- **Given** I send a message
|
|
- **When** the response arrives
|
|
- **Then** the "LIVE MEMORY CONTEXT" panel shows up to 4 semantically relevant memories
|
|
- **And** each memory entry shows its type and content
|
|
|
|
### AC-4: Teaching panel stores facts
|
|
- **Given** I type a fact into the "TEACH TIMMY" input and submit
|
|
- **When** the request completes
|
|
- **Then** I see a green confirmation "✓ Taught: <fact>"
|
|
- **And** the fact appears in the "KNOWN FACTS" list
|
|
- **And** the fact is stored in Timmy's live memory (`store_personal_fact`)
|
|
|
|
### AC-5: Empty / invalid input is rejected gracefully
|
|
- **Given** I submit a blank message or fact
|
|
- **Then** no request is made and the log is unchanged
|
|
- **Given** I submit a message over 10 000 characters
|
|
- **Then** an inline error is shown without crashing the server
|
|
|
|
### AC-6: Conversation can be cleared
|
|
- **Given** the Nexus has conversation history
|
|
- **When** I click CLEAR and confirm
|
|
- **Then** the chat log shows only a "cleared" confirmation
|
|
- **And** the Agno session for `nexus` is reset
|
|
|
|
### AC-7: Graceful degradation when Ollama is down
|
|
- **Given** Ollama is unavailable
|
|
- **When** I send a message
|
|
- **Then** an error message is shown inline (not a 500 page)
|
|
- **And** the app continues to function
|
|
|
|
### AC-8: No regression on existing tests
|
|
- **Given** the nexus route is registered
|
|
- **When** `tox -e unit` runs
|
|
- **Then** all 343+ existing tests remain green
|
|
|
|
---
|
|
|
|
## Future Work (separate issues)
|
|
|
|
1. **LoRA trigger** — button in the teaching panel to queue a fine-tuning run
|
|
using the current Nexus conversation as training data
|
|
2. **RL harness** — reward signal collection during conversation for RLHF
|
|
3. **Auto-falsework pipeline** — scaffold harness generation from conversation
|
|
4. **Bannerlord interface** — Nexus as the live-memory bridge for in-game Timmy
|
|
5. **Streaming responses** — token-by-token display via WebSocket
|
|
6. **Per-operator sessions** — isolate Nexus history by logged-in user
|