feat: add topological flow reasoning for mechanistic queries

[bhavyakeerthi3]

Summary

Implements Topological Flow Reasoning to handle mechanistic biological queries (e.g. "What happens after protein phosphorylation?") that standard RAG cannot answer correctly.

Fixes #143

Motivation

RAG retrieval returns keyword-matched snippets with no awareness of reaction ordering. Biological pathways have strict causal sequences — a hallucinated causal chain is worse than no answer because it sounds authoritative. This PR makes the agent verify causal claims against the Reactome Graph before responding.

Key Changes

File	Change
src/tools/reactome_topology.py	New tool — fetches reaction participants and preceding/subsequent events from Reactome Content Service API
src/agent/tasks/flow_reasoner.py	New task node — curator-level prompt that treats graph data as ground truth
src/agent/profiles/cross_database.py	Added identify_flow and verify_mechanism nodes to agent graph
tests/test_flow_reasoning.py	Integration tests for all three new nodes

How It Works

User query ("what happens after X?")
        ↓
CrossDatabaseGraphBuilder detects flow keywords
        ↓
identify_flow → extracts Stable IDs, fetches topology context
        ↓
verify_mechanism → grounds causal chain against Reactome Graph
        ↓
Verified answer returned

Resilience

Added import fallbacks for AttributeInfo to handle varied LangChain environments without breaking existing functionality.

Test Results

tests/test_flow_reasoning.py::test_identify_flow        PASSED
tests/test_flow_reasoning.py::test_verify_mechanism     PASSED
tests/test_flow_reasoning.py::test_decide_next_steps    PASSED

Relation to Other PRs

• Independent of feat(mcp): connect Reactome MCP server to LangGraph agent with LangChain tool wrappers #137 and feat: add LLM-based query router for RAG, MCP search, and MCP analysis #142 — no shared dependencies, can be reviewed in isolation
• Complements feat: add hallucination grader and fix web search dead branch #123 (hallucination grader) — the flow_context gathered here provides the exact evidence needed for faithfulness grading on mechanistic sequences

[adamjohnwright]

Closing as superseded by #153, which is your own later version of this work — same feature, same core files (flow_reasoner.py, reactome_topology.py), and further along. Reviewing both would be reviewing the same idea twice, so #153 is the one staying open.

Since the review will happen there, one finding that applies to both and is worth flagging now rather than at merge time:

src/util/langchain_compat.py should come out. It is a triple-nested try/except around importing AttributeInfo, ending in a fallback that defines a stub class of the same name if every import fails. That last branch is the concern: if the import is genuinely unavailable, the code carries on with an object that is not the real AttributeInfo, and whatever goes wrong afterwards will not point back here.

It is also no longer necessary. main settled this during the LangChain 1.x migration — src/retrievers/reactome/metadata_info.py imports it directly:

from langchain_classic.chains.query_constructor.schema import AttributeInfo

When this PR was opened that import path was genuinely in flux, so the shim was a reasonable response at the time. It just is not the problem any more.

Worth knowing before rebasing #153: main has moved 140 commits since this branch's base, including the retriever rewrite and the LangChain 1.x migration, so it will need reworking rather than a straight rebase.

Thank you for the work — it is going forward on #153.