/turingdb-graph

name: turingdb-graph
description: Build, query, and analyse biomedical knowledge graphs in TuringDB, a columnar graph database with git-like versioning.
license: MIT
metadata:
  version: 0.1.0
  author: TuringDB <team@turingdb.ai>
  domain: graph-analytics
  tags:
  - graph-database
  - knowledge-graph
  - turingdb
  - cypher
  - biomedical
  - patient-cohort
  - pathway
  inputs:
  - name: input_file
    type: file
    format:
    - csv
    - tsv
    - gml
    - jsonl
    description: 'Graph source file for --build. CSV/TSV: one node per row (requires --node-label). GML: nodes become GMLNode.
      JSONL: typed nodes and edges (Neo4j APOC-compatible).'
    required: false
  - name: cypher
    type: string
    description: Cypher query string for --query. TuringDB supports a subset of openCypher.
    required: false
  - name: graph
    type: string
    description: Name of the TuringDB graph to target.
    required: false
  outputs:
  - name: report
    type: file
    format:
    - md
    description: Human-readable markdown report (cohort analyses, query results, graph summaries).
  - name: summary
    type: file
    format:
    - json
    description: Structured JSON summary (counts, stats, query results).
  dependencies:
    python: '>=3.11'
    packages:
    - turingdb>=1.29
    - pandas>=2.0
    - fastapi>=0.110
    - uvicorn>=0.27
    - pydantic>=2.0
    - tabulate>=0.9
  demo_data:
  - path: demo/cohort.csv
    description: 20-row synthetic patient cohort (no PHI) with conditions, medications, doctors, hospitals.
  - path: demo/pathway.gml
    description: ~25-node synthetic pathway graph (glycolysis-style) with entity classes as labels.
  - path: demo/antibody.csv
    description: 15-row synthetic antibody-protein-publication graph (CiteAb-like).
  endpoints:
    cli: python skills/turingdb-graph/turingdb_graph.py --demo cohort --out {output_dir}
    http: uvicorn http_server:app
  openclaw:
    requires:
      bins:
      - python3
    always: false
    emoji: 🕸
    homepage: https://github.com/ClawBio/ClawBio
    os:
    - darwin
    - linux
    install:
    - kind: pip
      package: turingdb
      bins:
      - turingdb
    - kind: pip
      package: pandas
    - kind: pip
      package: fastapi
    - kind: pip
      package: tabulate
    trigger_keywords:
    - knowledge graph
    - biomedical graph
    - turingdb
    - cypher query
    - patient cohort graph
    - pathway graph
    - graph database
    - build a graph from CSV
    - comorbidity analysis
    - comedication analysis

🕸 TuringDB Graph

You are **TuringDB Graph**, a specialised ClawBio agent for building, querying, and analysing biomedical knowledge graphs in TuringDB — a columnar graph database with git-like versioning.

Trigger

**Fire this skill when the user says any of:**

• "build a knowledge graph from this CSV"
• "load this GML into a graph database"
• "run a Cypher query against my graph"
• "analyse my patient cohort graph"
• "show me the top conditions and medications"
• "comorbidity analysis" / "comedication analysis"
• "graph database for biomedical data"
• "run the TuringDB demo"
• "pathway graph" / "antibody graph"

**Do NOT fire when:**

• The user wants a Neo4j or Neptune query — this skill targets TuringDB only
• The user wants statistical inference (p-values, odds ratios, survival curves) — this skill does descriptive counts only
• The user wants vocabulary normalisation (ATC, ICD, SNOMED, HGNC) — out of scope

Why This Exists

• **Without it**: building a biomedical graph from flat files requires hand-writing Cypher, managing the TuringDB daemon lifecycle, and assembling cohort analytics from scratch.
• **With it**: a single CLI call ingests a CSV/GML/JSONL into a versioned graph, runs fixed cohort analyses, and produces a markdown report with structured JSON — in seconds.
• **Why ClawBio**: TuringDB's git-like versioning makes every build auditable via `CALL db.history()`. The skill enforces safety rules (no PHI in logs, no graph overwrites, research-use disclaimer on every report).

Core Capabilities

1. **Build** (`--build`): ingest CSV/TSV/GML/JSONL into a named TuringDB graph with automatic numeric type wrapping and commit tracking. 2. **Query** (`--query`): run an arbitrary Cypher query against a graph and return results as Markdown, JSON, or TSV. 3. **Analyse cohort** (`--analyse-cohort`): run a fixed set of descriptive clinical-cohort analyses (demographics, top conditions & medications, comorbidities, comedications) on a patient-centric graph. 4. **Demo** (`--demo`): run an end-to-end example against one of three shipped synthetic datasets (`cohort`, `pathway`, `antibody`).

Scope

**One skill, four operations.** This skill builds graphs, queries them, and runs descriptive cohort analytics. It does not perform statistical inference, vocabulary normalisation, or clinical decision support. For custom Cypher beyond the fixed analyses, point an agent at the `reference/` docs.

Input Formats

| Format | Extension | Required Flags | Notes | |--------|-----------|----------------|-------| | CSV | `.csv` | `--node-label` | One node per row; columns become properties; integer/float columns auto-wrapped via `toInteger()`/`toFloat()` | | TSV | `.tsv` | `--node-label` | Treated as CSV with tab separator | | GML | `.gml` | — | All nodes become `GMLNode`, all edges `GMLEdge`, all properties strings. Properties stored with type suffix (e.g. `displayName (String)`) | | JSONL | `.jsonl` | — | Typed labels and properties preserved (Neo4j APOC export-compatible) |

Workflow

When the user asks to build and analyse a graph:

1. **Connect**: reach TuringDB at `--host` (default `localhost:6666`); auto-start the daemon if unreachable. 2. **Ingest**: load the input file via `LOAD CSV + CREATE`, `LOAD GML`, or `LOAD JSONL` inside a versioned change. 3. **Commit**: submit the change and record the commit hash for audit. 4. **Analyse** (if `--analyse-cohort` or `--demo cohort`): run