Epic: EDAM MCP workflow decomposition

[slobentanzer]

The challenge of applying an MCP-driven agent is to clearly and unambiguously instruct the agent with a multi-step task in order to reduce probabilistic problems in the copilot behaviour. We aim to structure the EDAM MCP approach into:

• an entry point that explains available functions to the copilot
• a set of deterministic functions that allow the copilot to flexibly apply the instructions

This is the parent issue for this decomposition task. Below is a graphical overview of the modules.

flowchart TD
  %% ========= LAYOUT / STYLES =========
  classDef entry fill:#eef8ff,stroke:#2b6cb0,stroke-width:1px,color:#0b3b76
  classDef action fill:#fff7ed,stroke:#c05621,stroke-width:1px,color:#7b341e
  classDef decision fill:#f0fff4,stroke:#2f855a,stroke-width:1px,color:#22543d
  classDef data fill:#f7fafc,stroke:#4a5568,stroke-width:1px,color:#2d3748
  classDef loop fill:#fdf2f8,stroke:#97266d,stroke-width:1px,color:#702459
  classDef check fill:#edf2f7,stroke:#2c5282,stroke-width:1px,color:#2a4365
  classDef output fill:#ebf8ff,stroke:#3182ce,stroke-width:1px,color:#2b6cb0

  %% ========= ENTRY POINT =========
  EP["MCP Entry Point: Overview & Planner<br/><small>• Summarize workflow state<br/>• List available functions & options<br/>• Suggest next step</small>"]:::entry

  %% ========= FUNCTION CATALOG (for copilot) =========
  subgraph Catalog["Function Catalog"]
    direction TB
    F1["describe_workflow()<br/><small>Return summary + function schema</small>"]:::data
    F2["segment_text(text)<br/><small>Decide single vs multi; return list</small>"]:::action
    F3["map_to_edam(item, opts)<br/><small>Semantic search → EDAM term + stats</small>"]:::action
    F4["commonsense_check(item, term)<br/><small>Validate/adjust via EDAM traversal</small>"]:::check
  end

  EP --> Catalog

  %% ========= INPUT =========
  IN["Input text/annotations<br/><small>single term | sentence | paragraph | metadata</small>"]:::data
  EP --> IN

  %% ========= SEGMENTATION =========
  SEG["segment_text(text)"]:::action
  IN --> SEG

  D1{"Single unit<br/>or multiple?"}:::decision
  SEG --> D1

  %% ========= MULTI-ITEM BRANCH =========
  subgraph LOOP["For each item in items"]
    direction TB
    IT["item[i]"]:::data
    MAP["map_to_edam(item, opts)<br/><small>• embedding: bm25 | sbert | e5 | custom<br/>• synth_term: on/off<br/>• k, score_fn, filters<br/>• returns: {term_id, label, score, depth,<br/>children_count, parents, synonyms}</small>"]:::action
    CC["commonsense_check(item, term)<br/><small>• Too generic? → descend to children<br/>• Too specific? → ascend to parents<br/>• Out-of-scope? → flag + suggest nearest broader term</small>"]:::check
    OUTI["validated_item_mapping[i]"]:::output
    IT --> MAP --> CC --> OUTI
  end

  D1 -- "multiple" --> LOOP
  D1 -- "single" --> ONE["item"]:::data

  %% ========= SINGLE-ITEM PATH =========
  MAP1["map_to_edam(item, opts)"]:::action
  CC1["commonsense_check(item, term)"]:::check
  OUT1["validated_item_mapping"]:::output

  ONE --> MAP1 --> CC1 --> OUT1

  %% ========= AGGREGATION / OUTPUT =========
  MERGE["merge_results()<br/><small>Collect mappings + per-item stats</small>"]:::action
  LOOP --> MERGE
  OUT1 --> MERGE

  SUMM["report_summary()<br/><small>• Coverage & confidence<br/>• Adjustments made by traversal<br/>• Unresolved / flagged items<br/>• EDAM stats (depths, children counts)</small>"]:::action

  MERGE --> SUMM

  FINAL["Final Output<br/><small>• Mappings: item → EDAM term_id/label<br/>• Justifications & scores<br/>• Traversal logs (up/down)<br/>• Flags for review</small>"]:::output

  SUMM --> FINAL

  %% ========= OPTIONAL FEEDBACK / ITERATION =========
  FB{"Accept results<br/>or refine options?"}:::decision
  FINAL --> FB

  FB -- "Refine" --> OPTS["update_opts()<br/><small>change embedding, synth_term, thresholds, filters</small>"]:::action
  OPTS --> SEG

  FB -- "Accept" --> DONE["Done"]:::output

Loading

[mirpedrol]

This looks nice @slobentanzer! If I understand well, it's similar to what I proposed in #2 using LangGraph. Are you going to implement it with LangGraph or a different approach?
And is the plan to add it to this same repo?

[slobentanzer]

Hi @mirpedrol, apologies, only now seeing this comment. It is not similar, as we do not impose a deterministic structure on what the system will do (the workflow component of LangGraph instances). Rather, the LLM agent is supposed to decide which of the functions of the MCP it should use. That is a little more flexible than the process orchestration by LangGraph; even though with a very general ReAct framework implemented in LangGraph you could also tackle every problem. But I am not sure this is necessary any more given the way in which tool usage via MCPs is developing. Feel free to ask follow-ups.