Epic: Multi-Assistant Delegation (Cross-Community Routing)

[neuromechanist]

Summary

Enable community assistants to delegate queries to peer assistants when a question falls outside their domain. For example, if a user asks the HED assistant about BIDS data organization, the HED assistant can route that sub-question to the BIDS assistant, which has the actual knowledge, tools, and documentation.

Motivation

Research communities overlap significantly. HED users work with BIDS, EEGLAB users need HED annotations, BIDS users want to know about specific tool integrations. Currently, each assistant is isolated and can only say "I don't know about that" or hallucinate answers outside its domain. Cross-community delegation lets assistants leverage the full platform's knowledge while maintaining domain expertise boundaries.

Design Decisions

• Explicit peers: Each community declares which other communities it can delegate to in its config.yaml (not automatic/all-to-all)
• Depth limit = 1: A delegated assistant cannot delegate further (prevents chains/loops)
• Context passing: The delegated assistant receives relevant conversation context, not just the isolated question
• Attributed responses: Delegated answers are clearly attributed to the source assistant in the response

Phases

Phase 1: Community Awareness and Config Schema

Goal: Communities can declare peer relationships and the system knows about them.

• Add peers section to CommunityConfig schema:

  peers:
    - id: bids
      description: "Brain Imaging Data Structure - data organization and standards"
      delegation_hint: "Delegate questions about BIDS directory structure, dataset organization, metadata files, and BIDS validation"
    - id: eeglab
      description: "EEGLAB - EEG analysis and processing"
      delegation_hint: "Delegate questions about EEG signal processing, EEGLAB functions, and plugin usage"

• Inject peer descriptions into the assistant's system prompt so it knows when delegation is appropriate
• Add validation: peer IDs must reference registered communities
• Add tests for config loading with peers

Phase 2: Delegation Tool and Execution

Goal: Assistants can actually invoke peer assistants and return attributed answers.

• Auto-generate ask_{peer_id}_assistant tool for each declared peer:

  @tool
  def ask_bids_assistant(question: str) -> str:
      """Ask the BIDS assistant about BIDS-specific topics.
      Delegate questions about BIDS directory structure, dataset organization,
      metadata files, and BIDS validation."""

• Delegation execution:
  • Create a temporary peer assistant instance using the registry
  • Pass conversation context (trimmed recent messages + the delegation question)
  • Use the same API key and model selection from the parent request
  • Set a delegation_depth flag to prevent recursive delegation (depth=1 max)
  • Enforce a timeout for delegated calls
• Return format includes attribution metadata:

  {
    "answer": "...",
    "delegations": [
      {"community_id": "bids", "question": "...", "tools_used": [...]}
    ]
  }

• Add delegation info to the response so the primary assistant can attribute: "According to the BIDS assistant: ..."
• Add observability: log delegation events, track delegation token usage separately
• Tests: delegation happy path, depth limit enforcement, missing peer handling, timeout

Phase 3: Smart Entry Point (Optional / Future)

Goal: A community-agnostic /ask endpoint that auto-routes to the best assistant.

• New /ask endpoint (no community prefix)
• Lightweight routing using community descriptions from registry
• Could be a simple LLM classifier call or keyword matching
• Falls back to a general response if no community matches
• Enables a "universal assistant" for users who don't know which community to ask

Technical Considerations

• API key passthrough: Delegated calls reuse the parent request's API key (BYOK or platform key); no separate auth needed
• Cost tracking: Delegation token usage should be tracked and attributed to the delegating community's request
• Tool namespacing: Peer assistants run in their own context; no tool name collision risk since delegation creates a separate assistant instance
• Session isolation: Delegated calls do not create or modify chat sessions; they are stateless sub-invocations
• Rate limiting: Delegation adds latency and token cost; consider limiting delegations per request (e.g., max 2)
• Error handling: If a peer assistant fails or times out, the primary assistant should gracefully note the failure rather than erroring the whole request

Out of Scope

• Multi-turn delegated conversations (delegation is single-turn Q&A)
• Automatic peer discovery (peers must be explicitly declared)
• Delegation depth > 1 (no chaining)
• Shared sessions across communities