SyslogSolution/ra-h-os
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
79895100c07764981a60544bb289777c5a399f89
ra-h-os/docs/6_ui.md
T
“BeeRad” 733d1c3407 Initial commit: RA-H Open Source Edition 
Local-first knowledge management system with BYO API keys.

Features:
- 3-panel UI (Nodes | Focus | Helpers)
- SQLite + sqlite-vec for vector search
- Agent system (Easy/Hard mode orchestrators)
- Content extraction (YouTube, PDF, web)
- Integrate workflow for connection discovery
- Dimension system with auto-assignment

Tech stack:
- Next.js 15 + TypeScript + Tailwind CSS
- Anthropic (Claude) + OpenAI (GPT) via Vercel AI SDK

Setup:
  npm install && npm rebuild better-sqlite3
  scripts/dev/bootstrap-local.sh
  npm run dev

MIT License
2025-12-15 16:14:28 +11:00

4.4 KiB
Raw Blame History

User Interface

3-Panel Layout

RA-H uses a fixed 3-panel desktop layout optimized for knowledge work.

Left Panel: Nodes

Purpose: Browse and manage your knowledge base

Features:

  • Search bar - Cmd+K global search modal
  • Dimension filters - Multi-select dimension tags
  • Node list - Scrollable list of filtered nodes
  • Quick actions - Pin/unpin, delete, open in focus

Node display:

  • Title + description preview
  • Dimension tags
  • Last updated timestamp
  • Pin indicator

Middle Panel: Focus

Purpose: Active workspace for current node(s)

Tabbed interface:

  • Primary tab - Main focused node
  • Additional tabs - Related nodes opened from conversations
  • Tab controls - Close, reorder, switch

Node detail view:

  • Full title and content
  • Metadata (created, updated, type, link)
  • Dimension tags (editable)
  • Edge list (incoming/outgoing connections)
  • Quick Add bar (bottom) - Create related nodes

Content rendering:

  • Markdown support
  • [NODE:id:"title"] auto-links to clickable node references
  • Syntax highlighting for code blocks
  • YouTube embeds (if link present)

Right Panel: Helpers

Purpose: AI conversation interface

Tabbed interface:

  • ra-h tab - Main orchestrator conversation
  • Delegation tabs - Background worker tasks (mini-rah)
  • Tab lifecycle - Manual close only (persist until user closes)

Conversation view:

  • Message history (user + assistant)
  • Tool call visibility (collapsed by default)
  • Token/cost tracking per message
  • Node references auto-linked

Input controls:

  • Text input with Shift+Enter for multiline
  • Submit button
  • Mode toggle (⚡ Easy / 🔥 Hard)
  • Thread reset button

Mode switching:

  • Easy mode: GPT-5 Mini (fast, cheap)
  • Hard mode: Claude Sonnet 4.5 (deep reasoning)
  • Seamless mid-conversation switching
  • localStorage persists user choice

Settings Panel

Access: Settings icon (top-right)

Tabs:

  1. General - App info, version, data location
  2. Agents - View agent configurations (ra-h, ra-h-easy, mini-rah, wise-rah)
  3. Workflows - Available workflows (integrate)
  4. Logs - Activity feed (last 100 entries)
  5. Analytics - Token usage and cost breakdown
  6. API Keys - Configure Anthropic/OpenAI/Tavily keys (beta ships with embedded keys)

Logs view:

  • Table/action filtering
  • Timestamp, table, action, summary
  • Detailed JSON snapshot on click
  • Real-time updates

Analytics view:

  • Total tokens used
  • Total cost (USD)
  • Breakdown by agent
  • Breakdown by thread
  • Average cost per chat

Search (Cmd+K)

Trigger: Cmd+K keyboard shortcut

4-tier relevance ranking:

  1. Exact title match - Highest priority
  2. Title substring - High priority
  3. FTS content match - Medium priority
  4. Semantic embedding - Fallback for conceptual matches

Features:

  • Type-ahead search
  • Instant results (no search button)
  • Click to open node in Focus panel
  • Recent searches preserved (session only)

UI:

  • Modal overlay
  • Search input
  • Results list (grouped by relevance tier)
  • Keyboard navigation (arrow keys, Enter to select)

Quick Add

Location: Bottom of Focus panel

Purpose: Rapidly create nodes related to current focus

Flow:

  1. User types title in Quick Add input
  2. Presses Enter
  3. System creates node via createNode tool
  4. Auto-creates edge from focused node to new node
  5. New node opens in adjacent tab

Features:

  • Single-field input (title only)
  • Inherit dimensions from focused node
  • Automatic edge creation with source='quick_add'
  • Real-time feedback (loading state, success confirmation)

Node References

Format: [NODE:id:"title"]

Rendering:

  • Clickable labels in chat messages
  • Clickable labels in node content
  • Hover tooltip with node preview
  • Click → open node in Focus panel

Usage:

  • Agents automatically use this format
  • Middleware converts to clickable UI elements
  • Enables knowledge graph navigation from conversations

Delegation Tabs

Purpose: Show background worker task progress

Lifecycle:

  • Created when mini-rah delegated
  • Persist until manually closed (no auto-cleanup)
  • Show task, status, summary, result
  • Tool calls visible (collapsed)

Status indicators:

  • queued - Task waiting
  • in_progress - Worker executing
  • completed - Success
  • failed - Error with details

Close behavior:

  • Manual close only (X button)
  • DELETE request to /api/rah/delegations/[sessionId]
  • Permanent deletion from database
Reference in New Issue View Git Blame Copy Permalink