Repository navigation
Add opt-in explainable query workflows, evidence capture and snapshot replay - #68
Open
kennethbruskiewicz wants to merge 9 commits into
Open
kennethbruskiewicz wants to merge 9 commits into
kennethbruskiewicz wants to merge 9 commits into
Conversation
… tests The vendored TRAPI schemas are checksum-pinned upstream files, so codespell now skips TCT/schemas instead of editing them. NameRes on Babel 2026jul22 reports Solr stats at the top level and indexes ~331M names (2025sep1 had ~425M under "solr"). The status test accepts both shapes and uses a 300M sanity floor. Node Annotator no longer returns clinical_approval for CHEBI:15377. The expectation drops the volatile warning and clinical fields, matching #63. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Resolve the conflict in TCT/interfaces/mcp.py with #64 (FastMCP-only server). The tool wrapper keeps this branch's optional `execution` argument and its handling of recording, validation and I/O errors. It now raises FastMCP's ToolError and registers the readOnlyHint/openWorldHint annotations from #64. The four tools added on this branch (validate_query_workflow, run_query_workflow, replay_query_workflow, evidence) join _READ_ONLY_TOOLS. None of them changes the structures passed in, which is the criterion #64 uses, and its annotation test expects every non-mutating tool to be listed. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This was referenced Nov 16, 2026
kennethbruskiewicz
marked this pull request as ready for review
November 16, 2026 20:43
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This branch adds an experimental, opt-in layer for explainable queries on top of the toolkit. It covers composing queries, keeping the evidence behind each answer, and replaying that evidence without live services. Everything is off by default. With nothing enabled, existing functions return the same values as before.
The work follows the CLI/MCP telemetry split that landed in #55 and is now rebased onto it.
What's included
Query workflows (
TCT/workflow.py,TCT/interfaces/WORKFLOWS.md)Recipes are JSON DAGs of named operations. References pass data between steps, and no arbitrary Python runs. Each output row keeps its lineage, and remote TRAPI responses are kept whole rather than flattened into merged edges. A run can be saved as a portable evidence snapshot.
examples/workflows/offline_pathway.jsonshows a recipe that runs fully offline.Evidence capture and rollup (
TCT/evidence.py,TCT/service_capture.py)Buffered HTTP calls to NameRes, NodeNorm, MetaKG, KP info and TRAPI endpoints are observed without replacing their response objects. A deterministic rollup summarizes the captured evidence per query, and golden fixtures under
tests/fixtures/rollup/pin its output.Execution controls and recording (
TCT/execution.py,TCT/journal.py)A scoped execution context sets timeouts, recording and caching for a block of calls. Recording writes immutable artifacts and a transactional index to a local store when it's turned on.
TRAPI representations and validation (
TCT/trapi_representation.py,TCT/trapi_validation.py)Shared query tools can return optional TRAPI views of their native results. Each view lists the limits of the conversion, such as merged edges that can't recover provider bindings. Validation runs offline against the upstream TRAPI 1.5.0 and 2.0.0-beta2 schemas. Those schemas are vendored under
TCT/schemas/with their Apache-2.0 license and checked against pinned SHA-256 checksums. They account for about 3.4k of the added lines.Response caching and snapshot replay (
TCT/response_cache.py)HTTP response reuse is opt-in. The cache key canonicalizes only JSON object key order. Arrays, query IDs, predicate order, URLs and literal values are kept as sent. Snapshots replay deterministically, though a replayed snapshot isn't proof that an answer is correct.
The MCP and CLI tool surfaces (
TCT/interfaces/tools.py,mcp.py,cli.py) expose the new options. The MCP contract tests cover the added parameters.Testing
A local
pytestrun gives 336 passed and 1 skipped, and codespell passes.Three live-service tests started failing after
mainlast went green on Sep 16. The cause is upstream changes, not this branch. A plainrequests.getshows the same responses.solr.test_nameres_statusnow accepts both shapes and uses a 300M floor.clinical_approvalfor CHEBI:15377. The expectation drops the volatile warning and clinical fields, the same change as draft test: review runtime isolation and Node Annotator expectations #63.Codespell skips
TCT/schemas/, since those files are checksum-pinned upstream copies and their typos come from TRAPI itself.Open questions
TCTpackage or in a separate optional extra.🤖 Generated with Claude Code