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
This commit is contained in:
“BeeRad”
@@ -0,0 +1,174 @@
|
||||
# Tools & Workflows
|
||||
|
||||
## Tool Architecture
|
||||
|
||||
Tools are organized into three categories with role-based access control.
|
||||
|
||||
### Core Tools (All Agents)
|
||||
|
||||
Read-only graph operations available to orchestrators, executors, and planners:
|
||||
|
||||
- **queryNodes** - Search nodes by title/content/dimensions
|
||||
- **getNodesById** - Retrieve full node data by ID array
|
||||
- **queryEdge** - Inspect existing edges between nodes
|
||||
- **searchContentEmbeddings** - Semantic search across chunk embeddings
|
||||
|
||||
### Orchestration Tools (Orchestrators Only)
|
||||
|
||||
Workflow and delegation tools for ra-h and ra-h-easy:
|
||||
|
||||
- **webSearch** - External web search via Tavily
|
||||
- **think** - Internal reasoning/planning (logged to metadata)
|
||||
- **executeWorkflow** - Delegate to wise-rah for predefined workflows
|
||||
- **delegateToMiniRAH** - Spawn mini-rah worker for tasks (deprecated in favor of direct execution)
|
||||
- **delegateToWiseRAH** - Delegate to wise-rah (now replaced by executeWorkflow)
|
||||
|
||||
### Execution Tools (Workers + Orchestrators)
|
||||
|
||||
Write operations and extraction - available to mini-rah, wise-rah, and orchestrators:
|
||||
|
||||
- **createNode** - Create new knowledge nodes
|
||||
- **updateNode** - Append content to existing nodes (append-only enforced at tool level)
|
||||
- **createEdge** - Create relationships between nodes
|
||||
- **updateEdge** - Modify edge metadata
|
||||
- **youtubeExtract** - Extract transcripts from YouTube videos
|
||||
- **websiteExtract** - Extract content from web pages
|
||||
- **paperExtract** - Extract text from PDF papers
|
||||
|
||||
## Tool Access by Agent
|
||||
|
||||
### ra-h / ra-h-easy (Orchestrators)
|
||||
**Tools:** Core + Orchestration + Execution (minus delegation helpers)
|
||||
- Direct write access (createNode, updateNode, createEdge, updateEdge)
|
||||
- Extraction tools (youtube, website, paper)
|
||||
- Workflow execution (executeWorkflow)
|
||||
- External search (webSearch)
|
||||
|
||||
### wise-rah (Planner)
|
||||
**Tools:** Core + webSearch + think + updateNode
|
||||
- **Direct write access** via updateNode (append-only)
|
||||
- **NO delegation** - executes workflows autonomously
|
||||
- Database-wide search capabilities
|
||||
- Minimal tool set for focused workflow execution
|
||||
|
||||
### mini-rah (Executor)
|
||||
**Tools:** Core + Execution + webSearch + think
|
||||
- All read tools
|
||||
- All write tools (createNode, updateNode, createEdge, updateEdge)
|
||||
- All extraction tools
|
||||
- **NO delegation** - leaf workers only
|
||||
|
||||
## Tool Registry
|
||||
|
||||
**Location:** `/src/tools/infrastructure/registry.ts`
|
||||
|
||||
**Structure:**
|
||||
```typescript
|
||||
TOOL_SETS = {
|
||||
core: { queryNodes, getNodesById, queryEdge, searchContentEmbeddings },
|
||||
orchestration: { webSearch, think, delegateToMiniRAH, executeWorkflow, ... },
|
||||
execution: { createNode, updateNode, createEdge, updateEdge, youtubeExtract, websiteExtract, paperExtract }
|
||||
}
|
||||
```
|
||||
|
||||
**Role mappings:**
|
||||
- `ORCHESTRATOR_TOOL_NAMES` - Core + webSearch + think + executeWorkflow + Execution
|
||||
- `EXECUTOR_TOOL_NAMES` - Core + Execution + webSearch + think (no delegation)
|
||||
- `PLANNER_TOOL_NAMES` - Core + webSearch + think + updateNode
|
||||
|
||||
## Workflows
|
||||
|
||||
**Location:** `/src/services/workflows/registry.ts`
|
||||
|
||||
Workflows are **code-first** - defined in registry, not database. Users cannot create custom workflows.
|
||||
|
||||
### Integrate Workflow
|
||||
|
||||
**Key:** `integrate`
|
||||
**Executor:** wise-rah (planner role)
|
||||
**Purpose:** Database-wide connection discovery for focused node
|
||||
**Cost:** ~$0.18/execution (GPT-5, 18 tool calls max)
|
||||
|
||||
**Process (5 steps):**
|
||||
|
||||
1. **Plan** - Call `think` to outline approach
|
||||
2. **Ground** - Identify node type, extract entities (names, projects, concepts), summarize core insight
|
||||
3. **Search** - Database-wide search using extracted entities
|
||||
- Obvious connections: queryNodes for specific names/projects/techniques
|
||||
- Thematic connections: searchContentEmbeddings for shared concepts
|
||||
- Finds 3-8 strong connections (not 20 weak ones)
|
||||
4. **Contextualize** - Brief 1-2 sentence relevance to pinned context
|
||||
5. **Append** - Call updateNode ONCE with Integration Analysis section
|
||||
|
||||
**Output format:**
|
||||
```markdown
|
||||
## Integration Analysis
|
||||
|
||||
[2-3 sentences: what this node is, why it matters, core insight]
|
||||
|
||||
**Database Connections:**
|
||||
- [NODE:123:"Title"] — [why: authorship/shared concept/dependency/contradiction]
|
||||
- [NODE:456:"Title"] — [why: ...]
|
||||
- [continue for 3-8 connections]
|
||||
|
||||
**Relevance:** [1-2 sentences connecting to user's pinned context]
|
||||
```
|
||||
|
||||
**Key features:**
|
||||
- **Database-first search** - Ignores pinned context during search (step 3), uses it only for relevance explanation (step 4)
|
||||
- **Entity extraction** - Grounding step identifies searchable entities before searching
|
||||
- **Append-only** - updateNode enforced at tool level (cannot overwrite)
|
||||
- **Single update** - Calls updateNode EXACTLY once per workflow
|
||||
- **Works for any node type** - Adapts to person/project/paper/idea/video/tweet/technique
|
||||
|
||||
**Invocation:**
|
||||
```typescript
|
||||
// User: "run integrate workflow"
|
||||
// Orchestrator calls: executeWorkflow({ workflow_key: 'integrate' })
|
||||
// System delegates to wise-rah with workflow instructions
|
||||
```
|
||||
|
||||
## Workflow Registry
|
||||
|
||||
**Definition:**
|
||||
```typescript
|
||||
{
|
||||
id: 1,
|
||||
key: 'integrate',
|
||||
displayName: 'Integrate',
|
||||
description: 'Deep analysis and connection-building for focused node',
|
||||
instructions: INTEGRATE_WORKFLOW_INSTRUCTIONS,
|
||||
enabled: true,
|
||||
requiresFocusedNode: true,
|
||||
primaryActor: 'oracle',
|
||||
expectedOutcome: 'Focused node updated with insights; 3-5 high-value edges created'
|
||||
}
|
||||
```
|
||||
|
||||
**Adding new workflows:**
|
||||
1. Create instructions file in `/src/config/workflows/[name].ts`
|
||||
2. Add workflow definition to `WorkflowRegistry.WORKFLOWS`
|
||||
3. Immediately available to orchestrators (no database changes needed)
|
||||
|
||||
## Tool Execution Flow
|
||||
|
||||
**Orchestrator conversation:**
|
||||
1. User sends message → ra-h/ra-h-easy
|
||||
2. Agent calls tools directly (createNode, queryNodes, etc.)
|
||||
3. Agent synthesizes response from tool results
|
||||
4. Response includes [NODE:id:"title"] references for UI rendering
|
||||
|
||||
**Workflow execution:**
|
||||
1. User: "run integrate workflow"
|
||||
2. ra-h/ra-h-easy calls `executeWorkflow({ workflow_key: 'integrate' })`
|
||||
3. System spawns wise-rah session with workflow instructions
|
||||
4. wise-rah executes 5-step process autonomously
|
||||
5. wise-rah returns summary to orchestrator
|
||||
6. Orchestrator shows summary to user
|
||||
|
||||
**Delegation (legacy, rarely used):**
|
||||
1. Orchestrator calls `delegateToMiniRAH({ task, context, expected_outcome })`
|
||||
2. System creates agent_delegations row (status: 'queued')
|
||||
3. Mini-rah spawned in isolated session
|
||||
4. Mini-rah executes task, returns structured summary
|
||||
5. Summary shown in delegation tab (persists until manually closed)
|
||||
Reference in New Issue
Block a user