Skip to content

feat: experimental finder APIs and TRAPI constraint fix#44

Open
SkyeAv wants to merge 5 commits into
mainfrom
feat/add-simplified-query-APIs
Open

feat: experimental finder APIs and TRAPI constraint fix#44
SkyeAv wants to merge 5 commits into
mainfrom
feat/add-simplified-query-APIs

Conversation

@SkyeAv

@SkyeAv SkyeAv commented Jul 20, 2026

Copy link
Copy Markdown
Member

Adds a developer-friendly experimental API layer for common Translator finder workflows, plus a TRAPI attribute-constraint fix.

Experimental APIs

  • Adds TCT.experimental with wrappers for pathfinder(...), neighborhood_finder(...), get_translator_resources(...), and clear_translator_resource_cache().
  • Resolves labels and CURIEs through Name Resolver / Node Normalizer.
  • Lazily caches Translator API metadata.
  • Returns parsed FinderResult objects with direct access to query, KG, results, auxiliary graphs, resolved nodes, and raw output.

Fixes

  • Places TRAPI attribute_constraints on the query edge (edges.e00) instead of as an invalid sibling under edges.

Docs

  • Adds notebooks/Experimental_API_tutorial.ipynb.
  • Adds README pointers to the new experimental tutorial.
  • Keeps links to legacy notebooks for fine-grained endpoint, predicate, query, parser, and visualization control.

Tests

  • Adds mocked unit coverage for the experimental API.
  • Updates Node Normalizer tests.
  • Verified with uv run pytest tests/test_experimental.py and uv run pytest.

@SkyeAv SkyeAv added bug Something isn't working documentation Improvements or additions to documentation enhancement New feature or request testing labels Jul 20, 2026
@SkyeAv
SkyeAv requested a review from yjzhang July 20, 2026 19:03
@SkyeAv SkyeAv self-assigned this Jul 20, 2026

@yjzhang yjzhang left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it really necessary to change all the single quotes to double quotes in tests/test_nodenorm.py? Otherwise, this looks good! In the future (not in this PR) we might want to merge the experimental API with the current pathfinder/neighborhood finder.

@SkyeAv

SkyeAv commented Jul 20, 2026

Copy link
Copy Markdown
Member Author

The change to double quotes aren't tests/test_nodenorm.py necessary, they're just an artifact of my IDE. If y'all want I can boot up a different IDE and revert the change? I think they're harmless for now.

Also, I 100% agree that it makes sense to eventually merge the experimental and main APIs. I thought it would be good to get people using the new ones for a little to iron out any kinks before we commit to the switch.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working documentation Improvements or additions to documentation enhancement New feature or request testing

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants