Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,11 @@ test:

# Run spell checking
spell:
uv run codespell --skip=metaData,notebooks,htmlcov,*.json --ignore-words-list=EHR
uv run codespell --skip=metaData,notebooks,htmlcov,*.json,./TCT/schemas --ignore-words-list=EHR

# Run spell checking interactively (allows fixing)
spell-fix:
uv run codespell --interactive 3 --skip=metaData,notebooks,htmlcov,*.json --ignore-words-list=EHR
uv run codespell --interactive 3 --skip=metaData,notebooks,htmlcov,*.json,./TCT/schemas --ignore-words-list=EHR

# Run linting
lint:
Expand Down
17 changes: 17 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,22 @@ uv sync --extra mcp --extra langfuse

## Python, CLI, and MCP interfaces

### Experimental explainable query workflows

TCT can execute explicit query workflows and return a portable evidence bundle:
the recipe, complete provider responses, filter decisions, and row lineage through
joins. `validate_query_workflow`, `run_query_workflow`, and
`replay_query_workflow` expose this through MCP and the CLI; Python callers use
`TCT.validate_workflow`, `TCT.run_workflow`, and `TCT.replay_workflow`.
Offline replay recomputes transformations using saved responses. Live reruns are
explicit and may change when remote data changes. Existing tools keep their
return formats and are not automatically instrumented as workflows.

See [workflow recipes and limitations](TCT/interfaces/WORKFLOWS.md) and the
[synthetic offline pathway example](examples/workflows/offline_pathway.json).

### Shared operations

TCT exposes one curated set of well-documented operations through three
interfaces:

Expand Down Expand Up @@ -248,6 +264,7 @@ Python names in snake_case.
| MetaKG extension | `add-custom-api-to-metakg`, `add-plover-apis-to-metakg` |
| TRAPI query preparation and execution | `optimize-query-for-api`, `query-knowledge-provider`, `parallel-query-apis` |
| Graph finding | `neighborhood-finder`, `path-finder` |
| Explainable workflows | `validate-query-workflow`, `run-query-workflow`, `replay-query-workflow` |
| Legacy compatibility | `trapi-query-endpoint` |

`trapi-query-endpoint` preserves the existing public tool contract but is a
Expand Down
6 changes: 6 additions & 0 deletions TCT/TCT.py
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
from .execution import capture_operation
from dataclasses import dataclass
from typing import Any, Optional, TypeAlias, Union

Expand Down Expand Up @@ -356,6 +357,7 @@ def select_concept(sub_list,obj_list,metaKG):
df2 = metaKG.loc[(metaKG['Subject'].isin(obj_list)) & (metaKG['Object'].isin(sub_list))]
df = pd.concat([df1,df2])
return(set(list(df['Predicate'])))
@capture_operation()
def sele_predicates_API(input_node1_category,input_node2_category,metaKG, APInames):
'''
Selects predicates, APIs, and API URLs for the given input node categories.
Expand Down Expand Up @@ -964,6 +966,7 @@ def to_dict(self) -> dict[str, Any]:
_DEFAULT_TRANSLATOR_RESOURCES: Optional[TranslatorResources] = None


@capture_operation()
def get_translator_resources(*, refresh: bool = False) -> TranslatorResources:
"""
Return cached Translator API metadata, loading it on first use.
Expand Down Expand Up @@ -1072,6 +1075,7 @@ def _looks_like_curie(value: str) -> bool:
return ":" in value and " " not in value


@capture_operation()
def _resolve_node(
value: str,
*,
Expand Down Expand Up @@ -1128,6 +1132,7 @@ def _resolve_node(
)


@capture_operation()
def _resolve_nodes(
values: Union[NodeInput, list[NodeInput]],
*,
Expand Down Expand Up @@ -1195,6 +1200,7 @@ def _get_resources(
)


@capture_operation()
def _build_finder_result(
raw_output: dict[str, Any],
*,
Expand Down
4 changes: 4 additions & 0 deletions TCT/TCT_neighborhood_finder.py
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
from .execution import capture_operation
# reviewed by yjzhang, 2026-08-19
from collections import Counter

Expand All @@ -18,6 +19,7 @@
)
from .TCT_pathfinder import generate_score_results, build_query_graph

@capture_operation()
def parse_results_for_neighborhood_finder(start_node_id:str, results:dict,
start_node_categories:list|None=None, end_node_categories:list|None=None,
get_node_info:bool=True,
Expand Down Expand Up @@ -126,6 +128,7 @@ def parse_results_for_neighborhood_finder(start_node_id:str, results:dict,
return output


@capture_operation()
def parse_results_for_neighborhood_finder_multiple_inputs(start_node_ids:list[str], results:dict,
start_node_categories:list|None=None, end_node_categories:list|None=None,
get_node_info:bool=True,
Expand Down Expand Up @@ -216,6 +219,7 @@ def parse_results_for_neighborhood_finder_multiple_inputs(start_node_ids:list[st
output['knowledge_graph']['nodes'][node_id] = {'name': nn.label, 'categories': nn.types}
return output

@capture_operation()
def neighborhood_finder(
node: Union[NodeInput, list[NodeInput]],
neighbor_categories: CategoryList,
Expand Down
20 changes: 16 additions & 4 deletions TCT/TCT_pathfinder.py
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
from .service_capture import capture_request
from .execution import capture_operation
# TCT Pathfinder...
# reviewed by yjzhang, 2026-08-20
import requests
Expand All @@ -23,6 +25,7 @@



@capture_operation()
def format_query_json_for_pathfinder_with_constraints(subject_ids:str,
object_ids:str,
subject_categories=None,
Expand Down Expand Up @@ -114,6 +117,7 @@ def format_query_json_for_pathfinder_with_constraints(subject_ids:str,

return q

@capture_operation()
def build_query_graph(start_node_id:str, end_node_id:str, start_node_categories=None, end_node_categories=None, constraints_path=None):
"""
start_node_categories and end_node_categories are lists of categories.
Expand Down Expand Up @@ -153,6 +157,7 @@ def build_query_graph(start_node_id:str, end_node_id:str, start_node_categories=
return q


@capture_operation()
def generate_score_results(results:dict, method='infores'):
"""
Generates a score dict, and a list of "analyses".
Expand Down Expand Up @@ -191,6 +196,7 @@ def generate_score_results(results:dict, method='infores'):
return graph_scores, graph_scores_formatted


@capture_operation()
def parse_results_for_pathfinder(start_node_id:str, end_node_id:str, result1:dict, result2:dict,
start_node_categories=None, end_node_categories=None,
get_node_info=True,
Expand Down Expand Up @@ -314,6 +320,7 @@ def parse_results_for_pathfinder(start_node_id:str, end_node_id:str, result1:dic


# define a function that uses the query_json as an template and change the ids and categories of the nodes
@capture_operation()
def format_pathfinder_query(node1_id:str, node1_category:str, node2_id:str, node2_category:str) -> dict:
'''
Formats a query to the Pathfinder API.
Expand Down Expand Up @@ -363,6 +370,7 @@ def format_pathfinder_query(node1_id:str, node1_category:str, node2_id:str, node
return query_json


@capture_operation()
def query_aragorn_pathfinder(node1_id:str, node1_category:str, node2_id:str, node2_category:str) -> str:
"""
This queries the ARAGORN Pathfinder API.
Expand All @@ -380,10 +388,11 @@ def query_aragorn_pathfinder(node1_id:str, node1_category:str, node2_id:str, nod
"""
aragorn_endpoint = service_url("aragorn")
query_current = format_pathfinder_query(node1_id, node1_category, node2_id, node2_category)
response = requests.post(aragorn_endpoint, json=query_current)
response = capture_request(requests.post, aragorn_endpoint, json=query_current, cache_kind="trapi", method="post")
return response


@capture_operation()
def query_aragorn_pathfinder_with_constraints(node1_id:str, node1_category:str, node2_id:str, node2_category:str, constraints:list) -> str:
"""
This queries the ARAGORN Pathfinder API with a list of constraints.
Expand All @@ -408,9 +417,10 @@ def query_aragorn_pathfinder_with_constraints(node1_id:str, node1_category:str,
object_categories=node2_category,
constraints=constraints
)
response = requests.post(aragorn_endpoint, json=query_current)
response = capture_request(requests.post, aragorn_endpoint, json=query_current, cache_kind="trapi", method="post")
return response

@capture_operation()
def query_arax_pathfinder(node1_id:str, node1_category:str, node2_id:str, node2_category:str) -> str:
"""
This queries the ARAX Pathfinder API.
Expand All @@ -428,9 +438,10 @@ def query_arax_pathfinder(node1_id:str, node1_category:str, node2_id:str, node2_
"""
ARAX_endpoint = service_url("arax")
query_current = format_pathfinder_query(node1_id, node1_category, node2_id, node2_category)
response = requests.post(ARAX_endpoint, json=query_current)
response = capture_request(requests.post, ARAX_endpoint, json=query_current, cache_kind="trapi", method="post")
return response

@capture_operation()
def query_arax_pathfinder_with_constraints(node1_id:str, node1_category:str, node2_id:str, node2_category:str, constraints:list) -> str:
"""
This queries the ARAX Pathfinder API with a list of constraints.
Expand All @@ -455,9 +466,10 @@ def query_arax_pathfinder_with_constraints(node1_id:str, node1_category:str, nod
object_categories=node2_category,
constraints=constraints
)
response = requests.post(ARAX_endpoint, json=query_current)
response = capture_request(requests.post, ARAX_endpoint, json=query_current, cache_kind="trapi", method="post")
return response

@capture_operation()
def query_TCT_pathfinder(
start: NodeInput,
end: NodeInput,
Expand Down
7 changes: 7 additions & 0 deletions TCT/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@
from .TCT import *

from .translator_node import TranslatorNode as TranslatorNode
from .workflow import (
replay_workflow as replay_workflow,
run_workflow as run_workflow,
validate_workflow as validate_workflow,
)

from .config import (
RuntimeConfig as RuntimeConfig,
Expand All @@ -11,3 +16,5 @@
)

from . import name_resolver as name_resolver, node_normalizer as node_normalizer, node_annotator as node_annotator, trapi as trapi, translator_kpinfo as translator_kpinfo

from .execution import execution as execution
Loading
Loading