athola/research

Research Session Orchestrator

Run a full multi-source research session: classify the domain, dispatch parallel agents, synthesize findings, and output a formatted report.

When NOT To Use

• Drilling into one subtopic of an active session (use tome:dig)
• Merging findings already gathered (use tome:synthesize)

Workflow

Step 1: Classify Domain

Run the domain classifier on the topic:

from tome.scripts.domain_classifier import classify
result = classify(topic)
# result.domain, result.triz_depth, result.channel_weights

If confidence < 0.6, ask the user to confirm or override the domain classification before proceeding.

Step 2: Plan Research

from tome.scripts.research_planner import plan
research_plan = plan(result)
# research_plan.channels, research_plan.weights, research_plan.triz_depth

Step 3: Create Session

from tome.session import SessionManager
mgr = SessionManager(Path.cwd())
session = mgr.create(topic, result.domain, result.triz_depth, research_plan.channels)

Step 4: Dispatch Agents

Launch research agents in parallel using the Agent tool. Use this mapping:

| Channel | Agent Type | Prompt Includes | |---------|-----------|-----------------| | code | tome:code-searcher | topic | | discourse | tome:discourse-scanner | topic, domain, subreddits | | academic | tome:literature-reviewer | topic, domain | | triz | tome:triz-analyst | topic, domain, triz_depth |

Rules:

• Always dispatch code and discourse agents
• Dispatch academic agent only if "academic" is in research_plan.channels
• Dispatch triz agent only if "triz" is in research_plan.channels AND triz_depth != "light"
• Dispatch all eligible agents in a SINGLE message (parallel, not sequential)

Each agent prompt must include:

1. The topic string
2. The domain classification
3. Any channel-specific context (subreddits for discourse, triz_depth for triz)
4. Instruction to return findings as JSON

Step 5: Collect and Synthesize

After all agents return:

1. Parse each agent's findings into Finding objects
2. Merge using tome.synthesis.merger.merge_findings()
3. Rank using tome.synthesis.ranker.rank_findings()

Step 6: Generate Output

from tome.output.report import format_report, format_brief, format_transcript

# Default to report format
output = format_report(session)

# Save to docs/research/
output_path = f"docs/research/{session.id}-{slug}.md"

Save the session state:

mgr.save(session)

Step 7: Present Results

Display a brief summary to the user:

• Number of findings per channel
• Top 3 findings by relevance
• Path to saved report

Then offer interactive refinement: "Use /tome:dig \"subtopic\" to explore specific areas."

Error Handling

• If an agent fails, continue with remaining agents
• If all agents fail, report the error and suggest manual research approaches
• If synthesis produces 0 findings, state this clearly rather than generating an empty report
• Save session state even on partial failure

Output Format Selection

| Flag | Format | Function | |------|--------|----------| | (default) | report | format_report() | | --format brief | brief | format_brief() | | --format transcript | transcript | format_transcript() |

Exit Criteria

• [ ] Domain classified before agents are dispatched; if confidence < 0.6, user confirmation is requested before proceeding
• [ ] Code and discourse agents always dispatched; academic and triz agents dispatched only when their channels are in the plan; all eligible agents sent in a single parallel message
• [ ] Session saved to docs/research/{session.id}-{slug}.md after synthesis regardless of whether all agents succeeded
• [ ] Top 3 findings by relevance score displayed to the user with the path to the saved report
• [ ] If all agents fail, error reported and manual alternatives suggested; an empty report is never generated