🌙 Dreamwalker Naming Convention Guide

Complete reference for the Dreamwalker orchestration and MCP tool naming system
Updated: November 20, 2025

📖 Overview

Naming Philosophy

The Dreamwalker naming convention moves away from codename-based naming (Beltalowda, Swarm) to a semantic, descriptive system that clearly communicates purpose and hierarchy.

🎯 Design Goals

  • Clarity: Names immediately communicate function
  • Consistency: Predictable patterns across all tools
  • Discoverability: Easy to find tools via autocomplete
  • Semantic: Names reflect actual behavior, not arbitrary codenames

📊 By The Numbers

  • 2 orchestrator patterns renamed
  • 5 management tools (dreamwalker_*)
  • 8 data tools (dream_of_*)
  • 9 provider tools planned (dreamer_*)
  • 100% backward compatibility maintained

🔄 Migration Status

  • ✅ Core orchestrator classes renamed
  • ✅ Pattern names updated
  • ✅ Management tools renamed
  • ✅ Data tools renamed
  • ⏳ Provider tools (deferred to Phase 5)

🔗 Repository Links

🎭 Orchestration Patterns (dream-*)

Orchestration patterns are named with the dream-* prefix to indicate high-level workflow patterns. These are invoked via MCP tools like dream_research and dream_search.

dream-cascade

Pattern Name MCP: dream_research

Hierarchical research with three-tier cascading synthesis

Three-Tier Architecture:
├─ Workers (8 agents)
│ └─ Parallel execution on subtasks
├─ Mid-Level Synthesis
│ └─ Synthesize worker results
└─ Executive Synthesis
└─ Final strategic synthesis
Previous Name: dreamer-beltalowda
Class: DreamCascadeOrchestrator
File: dream_cascade_orchestrator.py
Best For: Deep research, comprehensive analysis

dream-swarm

Pattern Name MCP: dream_search

Parallel specialized agents for multi-domain search

Agent Types:
├─ Text (general content)
├─ Academic (research papers)
├─ News (current events)
├─ Technical (documentation)
├─ Social (media insights)
└─ ... (8 total types)
Previous Name: dreamer-swarm
Class: DreamSwarmOrchestrator
File: dream_swarm_orchestrator.py
Best For: Focused search, domain expertise

Future Patterns

Additional patterns planned for future implementation:

🛠️ Management Tools (dreamwalker_*)

System management tools use the dreamwalker_* prefix to indicate they manage the orchestration system itself rather than execute workflows.

Why "dreamwalker"?

The dreamwalker prefix represents the system administrator/manager role - walking between and managing the dreams (orchestration patterns). This distinguishes system operations from workflow execution.

📊 Data Tools (dream_of_*)

Data fetching tools use the dream_of_* prefix with a creative semantic: "dreaming of knowledge from Wikipedia", "dreaming of research from arXiv", etc.

Semantic Meaning

The "dream_of" prefix conveys the idea of accessing or querying knowledge from various sources. It's a poetic way to describe data retrieval: the system "dreams" of information from external sources like Census Bureau, arXiv, Semantic Scholar, etc.

Census Bureau Tools

Academic Research Tools

Archive Tools

Future Data Tools

Additional data sources will follow the same pattern:

🤖 Provider Tools (dreamer_*)

LLM provider tools use the dreamer_* prefix with a hybrid approach: one tool per provider with an action parameter.

⏳ Deferred to Phase 5

Provider tools were deferred for incremental implementation. When implemented, they will follow this pattern:

Hybrid Design Pattern

One tool per provider with action parameter:

  • action: "chat" - Text generation
  • action: "stream" - Streaming responses
  • action: "vision" - Image analysis
  • action: "image" - Image generation

This approach is more extensible than separate tools for each capability.

Planned Providers (9)

  • dreamer_anthropic
  • dreamer_openai
  • dreamer_xai
  • dreamer_mistral
  • dreamer_cohere
  • dreamer_gemini
  • dreamer_perplexity
  • dreamer_groq
  • dreamer_huggingface

Example Usage (When Implemented)

# Chat completion
result = await dreamer_openai(
    action="chat",
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}]
)

# Image generation
image = await dreamer_openai(
    action="image",
    prompt="A serene landscape",
    size="1024x1024"
)

# Vision analysis
analysis = await dreamer_anthropic(
    action="vision",
    image_data=base64_image,
    prompt="Describe this image"
)

🔄 Complete Migration Table

Category Old Name New Name Type
Patterns dreamer-beltalowda dream-cascade Pattern Name
dreamer-swarm dream-swarm Pattern Name
Classes BeltalowdaOrchestrator DreamCascadeOrchestrator Python Class
SwarmOrchestrator DreamSwarmOrchestrator Python Class
Management dream_get_orchestration_status dreamwalker_status MCP Tool
dream_cancel_orchestration dreamwalker_cancel MCP Tool
dream_list_orchestrator_patterns dreamwalker_patterns MCP Tool
dream_list_registered_tools dreamwalker_list_tools MCP Tool
dream_execute_registered_tool dreamwalker_execute_tool MCP Tool
Data Tools fetch_census_acs dream_of_census_acs MCP Tool
fetch_census_saipe dream_of_census_saipe MCP Tool
list_census_variables dream_of_census_variables MCP Tool
search_arxiv dream_of_arxiv MCP Tool
search_semantic_scholar dream_of_semantic_scholar MCP Tool
get_semantic_scholar_paper dream_of_semantic_scholar_paper MCP Tool
wayback_search dream_of_wayback MCP Tool
wayback_available_snapshots dream_of_wayback_snapshots MCP Tool

🏗️ Architecture & File Structure

Primary Development Repository

/home/coolhand/shared/
├── orchestration/
│   ├── __init__.py                      (exports + backward compatibility aliases)
│   ├── config.py                        (DreamCascadeConfig, DreamSwarmConfig)
│   ├── base_orchestrator.py            (BaseOrchestrator abstract class)
│   ├── dream_cascade_orchestrator.py   (3-tier hierarchical)
│   ├── dream_swarm_orchestrator.py     (parallel specialized agents)
│   ├── sequential_orchestrator.py      (linear pipeline)
│   ├── conditional_orchestrator.py     (decision tree)
│   └── iterative_orchestrator.py       (refinement loops)
├── mcp/
│   ├── unified_server.py                (main MCP server)
│   ├── data_server.py                   (data fetching tools)
│   ├── providers_server.py              (LLM provider tools)
│   └── ...

Plugin Distribution Repository

/home/coolhand/dreamwalker-mcp/
├── dreamwalker_mcp/
│   ├── mcp/                             (synced from shared/mcp)
│   │   ├── unified_server.py
│   │   ├── data_server.py
│   │   └── ...
│   ├── orchestration/                   (synced from shared/orchestration)
│   │   ├── dream_cascade_orchestrator.py
│   │   ├── dream_swarm_orchestrator.py
│   │   └── ...
│   └── ...
└── .sync-backups/                       (timestamped backups from sync)

Sync Workflow

Primary development happens in /home/coolhand/shared/, then syncs to the marketplace plugin at /home/coolhand/dreamwalker-mcp/ using sync-to-plugin.sh

Sync Script: Automatically adjusts import paths when copying files to the plugin distribution.

Backward Compatibility

# In orchestration/__init__.py:

from .dream_cascade_orchestrator import DreamCascadeOrchestrator
from .dream_swarm_orchestrator import DreamSwarmOrchestrator

# Backward compatibility aliases
BeltalowdaOrchestrator = DreamCascadeOrchestrator
SwarmOrchestrator = DreamSwarmOrchestrator

This ensures existing code using the old names continues to work without modification.

↑ Top