AnswerCoalesce

A web service and query workbench for the Answer Coalesce service for ARAGORN.

This service accepts TRAPI queries and returns coalesced answers using graph and property enrichment.

A live version of the API can be found here.

Web UI

The built-in workbench is served at / and /ui. It provides two independent query modes:

• Enrichment resolves a pasted or incrementally assembled set of names and CURIEs, retrieves their semantic types from NodeNorm, and finds concepts enriched across that set.
• EDGAR accepts one resolved concept, learns enrichment rules from its local neighborhood, and applies those rules to rank inferred answers.

Both modes show ranked summaries first. Selecting a result opens its inferred relationship, score, p-value when present, provenance, and supporting auxiliary graphs. The full TRAPI response can also be downloaded.

EDGAR results are separated into its three processing stages: directly known matches, learned enrichment rules, and newly inferred entities. The new entities view is selected by default.

EDGAR's directly known matches apply the complete query relationship, including every requested qualifier. The result cards and detail views display the qualifiers retained on direct and supporting evidence edges.

The UI uses same-origin proxy endpoints for Name Resolver and NodeNorm. Their upstream locations can be overridden with NAME_RESOLVER_URL, NODE_NORMALIZER_URL, and IDENTITY_SERVICE_TIMEOUT.

Relationship qualifiers are entered in the second query step as repeatable qualifier type/value pairs. The rows form one TRAPI qualifier set, so every listed qualifier must match. This supports qualified predicates, object aspect and direction, species context, and other Biolink qualifier types.

Query Types

Inference (EDGAR): Single-curie queries with knowledge_type: "inferred". Finds enriched associations via graph structure and chemical properties. Use the EDGAR tab in the built-in workbench.

Multi-Curie (MCQ): Queries with set_interpretation: "MANY" and member_ids. Finds shared enrichments across a set of input curies. Use the Enrichment tab in the built-in workbench.

Sample Inference Query

{
  "message": {
    "query_graph": {
      "nodes": {
        "input": {"categories": ["biolink:Disease"], "ids": ["MONDO:0004975"]},
        "output": {"categories": ["biolink:Drug"]}
      },
      "edges": {
        "edge_0": {
          "subject": "output",
          "object": "input",
          "predicates": ["biolink:treats"],
          "knowledge_type": "inferred",
          "qualifier_constraints": [{"qualifier_set": [
            {"qualifier_type_id": "biolink:species_context_qualifier",
             "qualifier_value": "NCBITaxon:9606"}
          ]}]
        }
      }
    }
  },
  "parameters": {
    "pvalue_threshold": 1e-05,
    "max_rules": 100,
    "predicate_constraint_style": "exclude",
    "predicate_constraints": ["biolink:causes", "biolink:biomarker_for"]
  }
}

Sample MCQ Query

{
  "message": {
    "query_graph": {
      "nodes": {
        "input": {
          "categories": ["biolink:Gene"],
          "ids": ["uuid:1"],
          "member_ids": ["NCBIGene:5111", "NCBIGene:8856", "NCBIGene:5290"],
          "set_interpretation": "MANY"
        },
        "output": {"categories": ["biolink:ChemicalEntity"]}
      },
      "edges": {
        "edge_0": {
          "subject": "input",
          "object": "output",
          "predicates": ["biolink:related_to"]
        }
      }
    }
  }
}

Parameters

Parameter	Type	Default	Description
pvalue_threshold	float	1e-5	Maximum p-value for enrichment results
max_results	int	2000	Maximum number of results returned
max_rules	int	100	Maximum enrichment rules evaluated per inference query
predicate_constraints	list[str]	[]	Predicates to include or exclude from enrichment
predicate_constraint_style	str	"exclude"	"include" or "exclude" — how to apply predicate_constraints
property_constraints	list[str]	[]	Property types to constrain property enrichment
node_constraints	list[str]	[]	Semantic types to constrain output nodes

Query edges also support qualifier_constraints (e.g. species_context_qualifier, object_aspect_qualifier, object_direction_qualifier).

Deployment

Local

uv venv --python 3.12
uv pip install -r requirements.txt
uv run python -m src.graph_coalescence.build_duckdb \
  --nodes /path/to/nodes.jsonl \
  --edges /path/to/edges.jsonl \
  --output answer-coalesce.duckdb
export AC_DUCKDB_PATH=$PWD/answer-coalesce.duckdb
uv run uvicorn src.server:APP --host 0.0.0.0 --port 6380

The builder defaults to a 6 GB DuckDB memory cap and 20 GB maximum temporary spill space. Runtime queries default to a 1 GB cap. These limits can be changed with AC_DUCKDB_BUILD_MEMORY_LIMIT, AC_DUCKDB_BUILD_MAX_TEMP_DIRECTORY_SIZE, and AC_DUCKDB_QUERY_MEMORY_LIMIT.

Docker

docker-compose build
docker-compose up -d

Kubernetes

Kubernetes configurations and helm charts can be found at: https://github.com/helxplatform/translator-devops/answer-coalesce

Building the Graph Database

The AC DuckDB database is built directly from KGX JSONL on Hatteras via a Slurm pipeline. See src/ac_pipeline/README.md.

For the database schema and the complete set-input and EDGAR query flows, see docs/duckdb-architecture.md.

Testing

uv run --isolated --with-requirements requirements-test.txt \
  pytest -m "not nongithub" tests/

# Profiling
PYTHONPATH=. python tests/test_profiling.py infer MONDO:0004975 biolink:treats biolink:Disease biolink:Drug --object
PYTHONPATH=. python tests/test_profiling.py mcq NCBIGene:5111,NCBIGene:8856,NCBIGene:5290 biolink:related_to biolink:Gene biolink:ChemicalEntity

Usage

http://"host name or IP":"port"/docs