Result-class API and module split (v0.3.0)

[natalie-23-gill]

Summary

This PR introduces a result-class API for TCT's knowledge-graph finders, splits TCT.py into focused modules, adds multi-hop TRAPI queries and edge-attribute extraction. Bumps version to 0.3.0. These are features ported over from GeneSet_Translator and are aimed at making building on tools on top of TCT easier.

Neighborhood_finder() and Path_finder() now return typed result objects instead of long tuples:

nb = TCT.Neighborhood_finder("MONDO:0008170", ["biolink:Drug"], resources=resources)

nb.input_node_id        # str
nb.knowledge_graph      # KnowledgeGraph (dict-like, wraps raw TRAPI edges)
nb.parsed               # ParsedKnowledgeGraph
nb.ranked               # pandas DataFrame

G = nb.to_networkx(resolve_names=True, include_attributes=True)

Existing tuple-unpacking still works (with a DeprecationWarning), so this is backward compatible.

What's in this PR

New: result API (results.py)

• KnowledgeGraph, ParsedKnowledgeGraph, NeighborhoodResult, PathResult, and dataframe_to_graph().
• .to_networkx() on every result type. resolve_names=True adds label and biolink categories to nodes; include_attributes=True adds publications, supporting text, and confidence scores to edges.
• .to_dataframe(), .parse(), .rank(), and dict-like access on the graph wrappers.

New: query and attribute helpers

• attribute_extraction.py - publications, supporting text, and confidence scores from TRAPI edge attributes, including nested study results.
• HopSpec + build_multi_hop_query() in trapi.py for chained multi-hop queries.

Refactor

• TCT.py reduced from 2,314 to 1,492 lines, with plotting extracted to visualization.py.
• translator_resources.py - TranslatorResources replaces the (APInames, metaKG, API_predicates) triplet. Legacy kwargs still work with a deprecation warning.
• Finder quality-of-life: a verbose flag, a clear ValueError on unresolvable input nodes, and TranslatorNode.name as an alias for .label.

Upstream sync

• Merged main (43 commits), with tests added for the new upstream modules to keep the coverage gate passing.
• Fixed a TypeError in format_query_json_for_pathfinder_with_constraints() when constraints=None (a bare if after the None guard should have been elif).

Docs

• New CHANGELOG.md, in Keep a Changelog format. Documents this release and back-fills the eight prior ones from 0.1.0 onward, reconstructed from git history.
• New consuming_results page documenting the result contract: result fields, to_networkx() node/edge attributes, and ranked columns.
• API reference pages now generated by sphinx-apidoc and wired into docs/Makefile, covering eight modules that previously had no page, including results.py.

Suggested review order

64 files, but weighted toward tests (+5,940 lines) and notebooks (+2,085); library source is +1,912.

1. TCT/results.py - the core of the PR; everything follows from this contract.
2. docs/source/consuming_results.md - the same contract in prose.
3. TCT/TCT.py - largest diff, but mostly code moving out to the new modules.
4. TCT/attribute_extraction.py, translator_resources.py, trapi.py - small and self-contained.
5. TCT/visualization.py - near-verbatim move.
6. Tests and notebooks

Backward compatibility

Tuple-unpacking, legacy APInames/metaKG/API_predicates kwargs, and the Neiborhood_finder alias all still work with deprecation warnings. parse_KG() and rank_by_primary_infores() accept both raw dicts and result objects.

Three intentional behavior changes:

• Finders no longer print to stdout by default; pass verbose=True to restore.
• An unresolvable input node raises ValueError instead of a bare AttributeError.
• extract_publications() normalizes bare PubMed ids (12345) to PMID:12345.

Testing

Full suite run against live Translator APIs: 394 passed, 1 skipped, 4 failed. Docs build verified with make html. No new ruff findings.

The 4 failures are all in test_nodenorm.py and reproduce on current main, so they are not caused by this PR. Both come from Node Normalizer production drift: /status no longer returns babel_version, and UNII:8HB6JQ9DFT now resolves to botulinum toxin type a rather than the expected Dysport. Happy to fix these here, though the corrected expectations are arguably yours to choose.

Notes for maintainers

• Please tag v0.3.0 on merge (the published v0.2.0 predates results.py, so no released version carries this API).
• This branch's Neighborhood_finder/Path_finder and the upstream TCT_neighborhood_finder/TCT_pathfinder modules currently coexist. Unifying them is left as follow-up to keep this PR reviewable.
• Happy to split into sequential PRs if you'd prefer smaller reviews.