alhazen-dismech

alhazen-skill-dismech

An Alhazen skill plugin for the DisMech Disease Mechanism Knowledge Graph — 750+ curated rare and complex disorders with pathophysiology mechanisms, parent hierarchies, and disease terms stored in a TypeDB 3.x graph database.

---

What is DisMech?

DisMech is a curated knowledge base of human disease mechanisms. Each disorder entry contains:

• Name and category (Mendelian, Complex, Infectious, Other)
• Parent categories (disease hierarchy)
• Disease term — preferred MONDO/OMIM identifier and label
• Pathophysiology mechanisms — named, prose-described molecular and cellular mechanisms that explain the disorder

This plugin bulk-ingests those YAML files into TypeDB 3.x, enabling graph queries across diseases, mechanisms, and ontology terms from Claude Code or the included web dashboard.

---

Quick Start

Prerequisites

• Docker — TypeDB runs as a container
• uv — Python environment manager
• Python 3.12 — the typedb-driver package segfaults on Python 3.14 (the current Homebrew default); uv will download 3.12 automatically

1. Clone and initialize

git clone https://github.com/sciknow-io/alhazen-skill-dismech.git
cd alhazen-skill-dismech
make init

make init pulls typedb/typedb:3.8.0, starts the container, creates the dismech database, and loads the TypeQL schema. Safe to run multiple times.

2. Get the disorder data

The knowledge base YAML files live in the dismech repo:

git clone https://github.com/sciknow-io/dismech.git

3. Ingest disorders

make ingest DISORDERS_DIR=/path/to/dismech/kb/disorders

On the first full run this ingests all 605 non-history disorder files (~2770 pathophysiology mechanisms) in about 20 seconds.

4. Query

# Database statistics
make stats
# -> {"success": true, "diseases": 605, "mechanisms": 2770, "disease_terms": 600}

# Look up a specific disease
uv run --project plugins/dismech/skills/dismech --python 3.12 \
  python plugins/dismech/skills/dismech/dismech.py show-disease \
  --name "Achondroplasia"

# Search by gene / term / mechanism keyword
uv run --project plugins/dismech/skills/dismech --python 3.12 \
  python plugins/dismech/skills/dismech/dismech.py search --query "FGFR3"

5. Open the dashboard

make serve    # starts on http://localhost:7777

Open http://localhost:7777 for the interactive dashboard: browse all diseases with category filters, look up individual disease detail cards, and run full-text search.

---

Architecture

dismech/kb/disorders/*.yaml
        │
        ▼  alhazen_core.py init
  TypeDB 3.x (Docker)
        │  schema.tql loaded once
        │
        ▼  dismech.py ingest
  ┌─────────────────────────────────┐
  │  disease entities               │  name (@key), category, parents, synonyms
  │    └── disease-term relations   │  → diseasedescriptor (preferred-term)
  │    └── pathophysiology-rel      │  → pathophysiology (name, description)
  └─────────────────────────────────┘
        │
        ▼  dismech.py serve
  HTTP dashboard + /api/* endpoints

Three-tier ingestion model:

Tier	Entity type	Key attributes	TypeDB relation
1	disease	name (key), category, parents	—
2	diseasedescriptor	preferred-term	disease-term
3	pathophysiology	name, description	pathophysiology-rel

Schema

plugins/dismech/skills/dismech/schema.tql is the TypeQL schema, generated from the LinkML dismech.yaml model via the gen-typedb generator in linkml. It is committed to this repo so no regeneration step is needed at runtime.

One post-generation modification was applied: the @key constraint was removed from owns name on all entity types except disease. The raw generated schema annotates every entity's name attribute as @key (because LinkML identifier: true propagates via inheritance), but mechanism names like "Inflammation" legitimately repeat across many diseases, causing insertion failures. Only disease names are globally unique.

---

CLI Reference

See plugins/dismech/skills/dismech/USAGE.md for the full command reference with all options and example JSON output.