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 the classifier abstains and refines rather than rejecting: result.candidates lists the domains that had keyword support, triz_depth becomes the deepest of those candidates, and channel_weights is a support-weighted blend. Coverage widens on ambiguity instead of narrowing, because a topic spanning several vocabularies is exactly what the cross-domain channel is for.

Report the abstention to the user with the candidate list and let them override the domain. Do not treat a refined plan as a failure; treat it as the classifier declining to guess.

When candidates is empty the topic produced no keyword hits at all. That stays on the cheap two-channel plan, since there is nothing to refine toward and escalating noise wastes budget. If the topic is genuinely researchable, the vocabulary in _DOMAIN_KEYWORDS is missing it: say so rather than forcing a domain.

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:

Rules:

• Dispatch every channel in research_plan.channels, which the planner derives from each card's min_depth: code and discourse at every depth, academic and web from medium, triz from deep
• 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. The channel's card, from render_card(get_card(channel)) in tome.channels.cards. It carries the channel's limitations and points the agent at the envelope its own file documents. Do not dictate a return shape in the prompt: an agent obeys the prompt over its file, and a prompt-invented shape once cost a session its canary record.

The rows above restate the cards. The cards are what the planner gates on, and a drift test holds the two together.

Step 5: Collect and Synthesize

After all agents return:

1. Parse each agent's findings into Finding objects

2. Record what each agent actually searched, before merging anything:

   from tome.synthesis.quality import parse_envelope
   
   for envelope in agent_envelopes:  # one per dispatched agent
       session.query_log.extend(parse_envelope(envelope))

   This is the step that makes an empty channel readable. Findings record what was found; the query log records what was looked for, and without it a channel that errored and a channel that searched a thin topic are the same thing: no findings. Skip this and every channel in the report reads unknown.

3. Merge using tome.synthesis.merger.merge_findings()

4. Rank using tome.synthesis.ranker.rank_findings()

Step 5b: Verify, Then Loop or Stop

from tome.synthesis.verifier import verify_context

check = verify_context(session, passes_run=n)  # max_passes default 2

CONTINUE names the work and why:

• rerun: the channel failed, degraded, left no record, or cannot show it was able to search. Dispatch it again as is.
• reformulate: a venue mismatch. Dispatch it again with the vocabulary the productive channel's findings use.
• add: a thin-field candidate that a retrieval channel never looked at. Dispatch that channel.

Dispatch only those agents, append their envelopes to the same session, merge and rank again, then verify with passes_run raised by one. STOP goes to Step 6. A STOP on the pass budget (max_passes, default 2) still lists the undone work: report it as a gap, never as a finished search. Each check's detail says what it read. See modules/stop-verifier.md for why the decision comes from records and not from a judgment.

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)