🕸 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
- Build (
--build): ingest CSV/TSV/GML/JSONL into a named TuringDB graph with automatic numeric type wrapping and commit tracking.
- Query (
--query): run an arbitrary Cypher query against a graph and return results as Markdown, JSON, or TSV.
- Analyse cohort (
--analyse-cohort): run a fixed set of descriptive clinical-cohort analyses (demographics, top conditions & medications, comorbidities, comedications) on a patient-centric graph.
- 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:
- Connect: reach TuringDB at
--host (default localhost:6666); auto-start the daemon if unreachable.
- Ingest: load the input file via
LOAD CSV + CREATE, LOAD GML, or LOAD JSONL inside a versioned change.
- Commit: submit the change and record the commit hash for audit.
- Analyse (if
--analyse-cohort or --demo cohort): run 8 fixed Cypher queries for demographics, conditions, medications, comorbidities, and comedications; aggregate results in pandas.
- Report: write
report.md + summary.json to the output directory. Every report ends with the ClawBio research disclaimer.
CLI Reference
Note for ClawBio reviewers: this skill uses mutually exclusive subcommand
flags (--build, --query, --analyse-cohort, --demo, --stop-server)
rather than the standard --input/--output pattern. This is because it
handles four distinct operations that do not share a single input/output
contract. --out serves the role of --output.
# Build a graph from CSV
python skills/turingdb-graph/turingdb_graph.py \
--build --input data.csv --graph my_graph --node-label PatientRow \
--out /tmp/build-output
# Build from GML
python skills/turingdb-graph/turingdb_graph.py \
--build --input pathway.gml --graph my_pathway --out /tmp/build-output
# Run a Cypher query
python skills/turingdb-graph/turingdb_graph.py \
--query --graph my_graph \
--cypher "MATCH (p:Patient)-[:HAS]->(c:MedicalCondition) RETURN p.displayName, c.displayName LIMIT 10" \
--out /tmp/query-output
# Analyse a patient cohort
python skills/turingdb-graph/turingdb_graph.py \
--analyse-cohort --graph my_graph --top-n 10 --out /tmp/analysis-output
# Run a demo (auto-starts TuringDB if needed)
python skills/turingdb-graph/turingdb_graph.py --demo cohort --out /tmp/demo
python skills/turingdb-graph/turingdb_graph.py --demo pathway --out /tmp/demo
python skills/turingdb-graph/turingdb_graph.py --demo antibody --out /tmp/demo
# Stop the TuringDB daemon
python skills/turingdb-graph/turingdb_graph.py --stop-server
Global flags
| Flag |
Default |
Description |
--host |
http://localhost:6666 |
TuringDB host URL |
--data-dir |
~/.turing |
TuringDB data directory |
--no-auto-start |
off |
Fail fast if the server is not running |
--out |
./output |
Output directory for reports |
Demo
python skills/turingdb-graph/turingdb_graph.py --demo cohort --out /tmp/demo
Expected output: a patient-centric graph with 50 nodes (20 patients, 6 conditions, 7 medications, 4 doctors, 3 hospitals, 8 blood types, 2 genders) and 120 edges, plus a cohort analysis report showing demographics (ages 14-73, mean 48.6), top conditions (Hypertension: 6, Diabetes Type 2: 4), and top medications (Metformin: 4).
All three demos (cohort, pathway, antibody) use synthetic data with no PHI.
Example Queries
- "Build a knowledge graph from my patient CSV and analyse the cohort"
- "What are the top comorbidity pairs in my cohort?"
- "Load this Reactome GML into TuringDB and run a multi-hop query"
- "Which antibodies target BRCA1 and how many citations do they have?"
- "Run the TuringDB cohort demo and show me the report"
Example Output
# Cohort analysis: `demo_cohort`
- **Patients**: 20
- **Ages** (n=20): min 14, max 73, mean 48.6, median 51.0
- **Under 18**: 3
- **Over 65**: 6
## Top 10 conditions
| condition | patients |
|---|---|
| Hypertension | 6 |
| Diabetes Type 2 | 4 |
| Arthritis | 3 |
| Asthma | 3 |
| Cancer | 2 |
| Migraine | 2 |
---
*ClawBio is a research and educational tool. Not a medical device.
This output must not be used for clinical decision-making.*
Output Structure
output_directory/
├── report.md # Markdown report (build summary, cohort analysis, or query results)
├── summary.json # Structured JSON (counts, stats, query metadata)
├── result.json # Query results as JSON (--query only)
├── result.tsv # Query results as TSV (--query only)
└── analysis/ # Subdirectory for cohort analysis (--demo cohort only)
├── report.md
└── summary.json
Algorithm / Methodology
Cohort analyses
All cohort analyses run as fixed Cypher queries that return raw rows, with aggregation performed in pandas. This avoids TuringDB's current GROUP BY limitation and keeps the aggregation logic auditable in Python.
- Patient demographics: count, age min/max/mean/median via
pd.to_numeric. Missing ages excluded, not imputed.
- Top conditions:
MATCH (p:Patient)-[:HAS]->(c:MedicalCondition) returns (patient, condition) pairs; pandas groupby().nunique() counts distinct patients per condition.
- Top medications: same pattern via
:TOOK_MEDICATION edges.
- Comorbidities: cartesian self-join on conditions per patient; self-pairs filtered, pairs normalised via
min()/max() to avoid double-counting, then filtered to pairs co-occurring in >= 2 patients.
- Comedications: same pattern on medications.
- Junior/senior split:
WHERE p.age < 18 and WHERE p.age > 65.
CSV type inference
LOAD CSV values arrive as strings. The skill reads the first 200 rows with pandas dtype detection and wraps integer-like columns with toInteger() and float-like columns with toFloat() at ingest time.
GML property name convention
TuringDB's LOAD GML stores properties with a type suffix: displayName becomes displayName (String). Access via backtick-escaped Cypher: n.`displayName (String)`.
Dependencies
Required:
turingdb >= 1.29; graph database engine (includes native daemon binary)
pandas >= 2.0; data manipulation and cohort aggregation
tabulate >= 0.9; DataFrame.to_markdown() rendering
Optional (HTTP endpoint only):
fastapi >= 0.110; REST API wrapper
uvicorn >= 0.27; ASGI server
pydantic >= 2.0; request validation
Gotchas
- GML property names have a type suffix. After
LOAD GML, properties are stored as displayName (String), not displayName. You must use backtick-escaped access: n.`displayName (String)`. Forgetting this produces "Property type not found" errors.
- TuringDB does not support string comparison with
<. The < operator only works on numeric types. Pair deduplication (e.g. comorbidity pairs) must happen in Python, not in Cypher WHERE clauses.
- TuringDB's GROUP BY returns incorrect aggregations.
RETURN key, count(x) does not group correctly. Always return raw rows and aggregate in pandas with groupby().nunique().
LOAD CSV + CREATE does not deduplicate. Each CSV row creates a new node unconditionally. TuringDB has no MERGE. Pre-dedupe in pandas if you need one-node-per-unique-value.
- Writes outside a change do not persist. Always wrap
CREATE/SET in new_change() ... CHANGE SUBMIT. This is the most common mistake when extending the skill.
- The daemon must match the Python package version. If
turingdb was upgraded but an old daemon is still running, LOAD CSV + CREATE and other v1.29 features will fail. Stop the old daemon first: --stop-server.
Safety
- No patient identifiers in logs or outputs. The skill never echoes raw CSV row content to stdout or to the JSON summary.
--query is the exception — it returns the user's own query results verbatim.
- Synthetic demo data only. All shipped datasets (
demo/cohort.csv, demo/pathway.gml, demo/antibody.csv) are synthetic. No real names, no real medical records, no identifiable demographics.
- Research-use disclaimer. Every markdown report ends with: "ClawBio is a research and educational tool. Not a medical device. This output must not be used for clinical decision-making."
--build is additive, not destructive. Refuses to overwrite an existing graph. Pass a new --graph name or drop the existing one manually.
--query is for trusted operators. It executes arbitrary Cypher. Do not expose the HTTP /query endpoint on an untrusted network without authentication.
- No clinical recommendations. The cohort analyser reports observed co-occurrence patterns — it does not label any pair as a contraindication, interaction, or recommendation.
- Local-first. All data stays on the local machine. No cloud uploads.
Domain Decisions
Graph modelling conventions
- Node labels:
PascalCase (Patient, MedicalCondition, BloodType).
- Edge types:
UPPER_SNAKE_CASE (HAS, TOOK_MEDICATION, IS_TREATED_BY).
- Property keys:
camelCase (displayName, pubmedId).
Versioning
Every --build run executes inside a fresh TuringDB change. After load, the skill issues CHANGE SUBMIT and returns the resulting commit hash in the JSON summary. This makes every build auditable via CALL db.history().
Indexing
The skill does not create indexes automatically. Users who repeatedly run --query against the same graph should create indexes manually — see reference/writing.md.
Agent Boundary
In scope
- Building a TuringDB graph from CSV/TSV/GML/JSONL via
--build.
- Running arbitrary Cypher via
--query.
- Running fixed cohort analyses via
--analyse-cohort.
- Auto-starting a local TuringDB daemon.
- Exposing operations via HTTP (
http_server.py).
Out of scope
- Inferring a biomedical schema from unstructured CSV.
- Deduplicating or merging nodes on ingest.
- Vocabulary normalisation (ATC, ICD, SNOMED, HGNC).
- Statistical inference (p-values, odds ratios, survival curves, enrichment tests).
- Embedding generation or vector search.
- Clinical decision support.
Agent role
The agent (LLM) dispatches this skill and interprets its outputs. It must not rewrite the cohort-analysis Cypher, invent new subcommands, or skip the safety disclaimer. For custom Cypher, point the agent at reference/querying.md, reference/writing.md, and reference/biomedical.md.
Integration with Bio Orchestrator
Trigger conditions: the orchestrator routes here when:
- The user mentions "knowledge graph", "graph database", "Cypher", or "TuringDB"
- The user provides a CSV/GML/JSONL and asks to build or query a graph
- The user asks for cohort-level descriptive analytics (top conditions, comorbidities)
Chaining partners:
rnaseq-de: DE results (gene lists) can be loaded as JSONL nodes for pathway enrichment queries
pubmed-summariser: antibody graph query results can feed into literature searches
clinical-variant-reporter: variant annotations could be loaded as graph nodes for network analysis
Maintenance
- Review cadence: re-evaluate when TuringDB releases a new major version (GROUP BY and string comparison support may change the aggregation strategy).
- Staleness signals: new TuringDB release that changes
LOAD GML property naming, or adds native MERGE/GROUP BY support.
- Deprecation: if TuringDB is discontinued or the Cypher dialect diverges significantly from openCypher.
Citations
- TuringDB; columnar graph database with git-like versioning
- openCypher; query language specification that TuringDB implements a subset of
1---
2name: turingdb-graph
3description: Build, query, and analyse biomedical knowledge graphs in TuringDB, a columnar graph database with git-like versioning.
4license: MIT
5metadata:
6 source: https://skillmd.com/skills/clawbio/turingdb-graph
7 version: 0.1.0
8 author: TuringDB <team@turingdb.ai>
9 domain: graph-analytics
10 tags:
11 - graph-database
12 - knowledge-graph
13 - turingdb
14 - cypher
15 - biomedical
16 - patient-cohort
17 - pathway
18 inputs:
19 - name: input_file
20 type: file
21 format:
22 - csv
23 - tsv
24 - gml
25 - jsonl
26 description: 'Graph source file for --build. CSV/TSV: one node per row (requires --node-label). GML: nodes become GMLNode.
27 JSONL: typed nodes and edges (Neo4j APOC-compatible).'
28 required: false
29 - name: cypher
30 type: string
31 description: Cypher query string for --query. TuringDB supports a subset of openCypher.
32 required: false
33 - name: graph
34 type: string
35 description: Name of the TuringDB graph to target.
36 required: false
37 outputs:
38 - name: report
39 type: file
40 format:
41 - md
42 description: Human-readable markdown report (cohort analyses, query results, graph summaries).
43 - name: summary
44 type: file
45 format:
46 - json
47 description: Structured JSON summary (counts, stats, query results).
48 dependencies:
49 python: '>=3.11'
50 packages:
51 - turingdb>=1.29
52 - pandas>=2.0
53 - fastapi>=0.110
54 - uvicorn>=0.27
55 - pydantic>=2.0
56 - tabulate>=0.9
57 demo_data:
58 - path: demo/cohort.csv
59 description: 20-row synthetic patient cohort (no PHI) with conditions, medications, doctors, hospitals.
60 - path: demo/pathway.gml
61 description: ~25-node synthetic pathway graph (glycolysis-style) with entity classes as labels.
62 - path: demo/antibody.csv
63 description: 15-row synthetic antibody-protein-publication graph (CiteAb-like).
64 endpoints:
65 cli: python skills/turingdb-graph/turingdb_graph.py --demo cohort --out {output_dir}
66 http: uvicorn http_server:app
67 openclaw:
68 requires:
69 bins:
70 - python3
71 always: false
72 emoji: 🕸
73 homepage: https://github.com/ClawBio/ClawBio
74 os:
75 - darwin
76 - linux
77 install:
78 - kind: pip
79 package: turingdb
80 bins:
81 - turingdb
82 - kind: pip
83 package: pandas
84 - kind: pip
85 package: fastapi
86 - kind: pip
87 package: tabulate
88 trigger_keywords:
89 - knowledge graph
90 - biomedical graph
91 - turingdb
92 - cypher query
93 - patient cohort graph
94 - pathway graph
95 - graph database
96 - build a graph from CSV
97 - comorbidity analysis
98 - comedication analysis
99---
100
101# 🕸 TuringDB Graph
102
103You 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.
104
105## Trigger
106
107**Fire this skill when the user says any of:**
108- "build a knowledge graph from this CSV"
109- "load this GML into a graph database"
110- "run a Cypher query against my graph"
111- "analyse my patient cohort graph"
112- "show me the top conditions and medications"
113- "comorbidity analysis" / "comedication analysis"
114- "graph database for biomedical data"
115- "run the TuringDB demo"
116- "pathway graph" / "antibody graph"
117
118**Do NOT fire when:**
119- The user wants a Neo4j or Neptune query — this skill targets TuringDB only
120- The user wants statistical inference (p-values, odds ratios, survival curves) — this skill does descriptive counts only
121- The user wants vocabulary normalisation (ATC, ICD, SNOMED, HGNC) — out of scope
122
123## Why This Exists
124
125- **Without it**: building a biomedical graph from flat files requires hand-writing Cypher, managing the TuringDB daemon lifecycle, and assembling cohort analytics from scratch.
126- **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.
127- **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).
128
129## Core Capabilities
130
1311. **Build** (`--build`): ingest CSV/TSV/GML/JSONL into a named TuringDB graph with automatic numeric type wrapping and commit tracking.
1322. **Query** (`--query`): run an arbitrary Cypher query against a graph and return results as Markdown, JSON, or TSV.
1333. **Analyse cohort** (`--analyse-cohort`): run a fixed set of descriptive clinical-cohort analyses (demographics, top conditions & medications, comorbidities, comedications) on a patient-centric graph.
1344. **Demo** (`--demo`): run an end-to-end example against one of three shipped synthetic datasets (`cohort`, `pathway`, `antibody`).
135
136## Scope
137
138**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.
139
140## Input Formats
141
142| Format | Extension | Required Flags | Notes |
143|--------|-----------|----------------|-------|
144| CSV | `.csv` | `--node-label` | One node per row; columns become properties; integer/float columns auto-wrapped via `toInteger()`/`toFloat()` |
145| TSV | `.tsv` | `--node-label` | Treated as CSV with tab separator |
146| GML | `.gml` | — | All nodes become `GMLNode`, all edges `GMLEdge`, all properties strings. Properties stored with type suffix (e.g. `displayName (String)`) |
147| JSONL | `.jsonl` | — | Typed labels and properties preserved (Neo4j APOC export-compatible) |
148
149## Workflow
150
151When the user asks to build and analyse a graph:
152
1531. **Connect**: reach TuringDB at `--host` (default `localhost:6666`); auto-start the daemon if unreachable.
1542. **Ingest**: load the input file via `LOAD CSV + CREATE`, `LOAD GML`, or `LOAD JSONL` inside a versioned change.
1553. **Commit**: submit the change and record the commit hash for audit.
1564. **Analyse** (if `--analyse-cohort` or `--demo cohort`): run 8 fixed Cypher queries for demographics, conditions, medications, comorbidities, and comedications; aggregate results in pandas.
1575. **Report**: write `report.md` + `summary.json` to the output directory. Every report ends with the ClawBio research disclaimer.
158
159## CLI Reference
160
161> **Note for ClawBio reviewers:** this skill uses mutually exclusive subcommand
162> flags (`--build`, `--query`, `--analyse-cohort`, `--demo`, `--stop-server`)
163> rather than the standard `--input`/`--output` pattern. This is because it
164> handles four distinct operations that do not share a single input/output
165> contract. `--out` serves the role of `--output`.
166
167```bash
168# Build a graph from CSV
169python skills/turingdb-graph/turingdb_graph.py \
170 --build --input data.csv --graph my_graph --node-label PatientRow \
171 --out /tmp/build-output
172
173# Build from GML
174python skills/turingdb-graph/turingdb_graph.py \
175 --build --input pathway.gml --graph my_pathway --out /tmp/build-output
176
177# Run a Cypher query
178python skills/turingdb-graph/turingdb_graph.py \
179 --query --graph my_graph \
180 --cypher "MATCH (p:Patient)-[:HAS]->(c:MedicalCondition) RETURN p.displayName, c.displayName LIMIT 10" \
181 --out /tmp/query-output
182
183# Analyse a patient cohort
184python skills/turingdb-graph/turingdb_graph.py \
185 --analyse-cohort --graph my_graph --top-n 10 --out /tmp/analysis-output
186
187# Run a demo (auto-starts TuringDB if needed)
188python skills/turingdb-graph/turingdb_graph.py --demo cohort --out /tmp/demo
189python skills/turingdb-graph/turingdb_graph.py --demo pathway --out /tmp/demo
190python skills/turingdb-graph/turingdb_graph.py --demo antibody --out /tmp/demo
191
192# Stop the TuringDB daemon
193python skills/turingdb-graph/turingdb_graph.py --stop-server
194```
195
196### Global flags
197
198| Flag | Default | Description |
199|------|---------|-------------|
200| `--host` | `http://localhost:6666` | TuringDB host URL |
201| `--data-dir` | `~/.turing` | TuringDB data directory |
202| `--no-auto-start` | off | Fail fast if the server is not running |
203| `--out` | `./output` | Output directory for reports |
204
205## Demo
206
207```bash
208python skills/turingdb-graph/turingdb_graph.py --demo cohort --out /tmp/demo
209```
210
211Expected output: a patient-centric graph with 50 nodes (20 patients, 6 conditions, 7 medications, 4 doctors, 3 hospitals, 8 blood types, 2 genders) and 120 edges, plus a cohort analysis report showing demographics (ages 14-73, mean 48.6), top conditions (Hypertension: 6, Diabetes Type 2: 4), and top medications (Metformin: 4).
212
213All three demos (`cohort`, `pathway`, `antibody`) use synthetic data with no PHI.
214
215## Example Queries
216
217- "Build a knowledge graph from my patient CSV and analyse the cohort"
218- "What are the top comorbidity pairs in my cohort?"
219- "Load this Reactome GML into TuringDB and run a multi-hop query"
220- "Which antibodies target BRCA1 and how many citations do they have?"
221- "Run the TuringDB cohort demo and show me the report"
222
223## Example Output
224
225```markdown
226# Cohort analysis: `demo_cohort`
227
228- **Patients**: 20
229- **Ages** (n=20): min 14, max 73, mean 48.6, median 51.0
230- **Under 18**: 3
231- **Over 65**: 6
232
233## Top 10 conditions
234
235| condition | patients |
236|---|---|
237| Hypertension | 6 |
238| Diabetes Type 2 | 4 |
239| Arthritis | 3 |
240| Asthma | 3 |
241| Cancer | 2 |
242| Migraine | 2 |
243
244---
245
246*ClawBio is a research and educational tool. Not a medical device.
247This output must not be used for clinical decision-making.*
248```
249
250## Output Structure
251
252```
253output_directory/
254├── report.md # Markdown report (build summary, cohort analysis, or query results)
255├── summary.json # Structured JSON (counts, stats, query metadata)
256├── result.json # Query results as JSON (--query only)
257├── result.tsv # Query results as TSV (--query only)
258└── analysis/ # Subdirectory for cohort analysis (--demo cohort only)
259 ├── report.md
260 └── summary.json
261```
262
263## Algorithm / Methodology
264
265### Cohort analyses
266
267All cohort analyses run as fixed Cypher queries that return raw rows, with aggregation performed in pandas. This avoids TuringDB's current GROUP BY limitation and keeps the aggregation logic auditable in Python.
268
2691. **Patient demographics**: count, age min/max/mean/median via `pd.to_numeric`. Missing ages excluded, not imputed.
2702. **Top conditions**: `MATCH (p:Patient)-[:HAS]->(c:MedicalCondition)` returns `(patient, condition)` pairs; pandas `groupby().nunique()` counts distinct patients per condition.
2713. **Top medications**: same pattern via `:TOOK_MEDICATION` edges.
2724. **Comorbidities**: cartesian self-join on conditions per patient; self-pairs filtered, pairs normalised via `min()`/`max()` to avoid double-counting, then filtered to pairs co-occurring in >= 2 patients.
2735. **Comedications**: same pattern on medications.
2746. **Junior/senior split**: `WHERE p.age < 18` and `WHERE p.age > 65`.
275
276### CSV type inference
277
278`LOAD CSV` values arrive as strings. The skill reads the first 200 rows with pandas dtype detection and wraps integer-like columns with `toInteger()` and float-like columns with `toFloat()` at ingest time.
279
280### GML property name convention
281
282TuringDB's `LOAD GML` stores properties with a type suffix: `displayName` becomes `displayName (String)`. Access via backtick-escaped Cypher: `` n.`displayName (String)` ``.
283
284## Dependencies
285
286**Required**:
287- `turingdb` >= 1.29; graph database engine (includes native daemon binary)
288- `pandas` >= 2.0; data manipulation and cohort aggregation
289- `tabulate` >= 0.9; `DataFrame.to_markdown()` rendering
290
291**Optional** (HTTP endpoint only):
292- `fastapi` >= 0.110; REST API wrapper
293- `uvicorn` >= 0.27; ASGI server
294- `pydantic` >= 2.0; request validation
295
296## Gotchas
297
298- **GML property names have a type suffix.** After `LOAD GML`, properties are stored as `displayName (String)`, not `displayName`. You must use backtick-escaped access: `` n.`displayName (String)` ``. Forgetting this produces "Property type not found" errors.
299- **TuringDB does not support string comparison with `<`.** The `<` operator only works on numeric types. Pair deduplication (e.g. comorbidity pairs) must happen in Python, not in Cypher `WHERE` clauses.
300- **TuringDB's GROUP BY returns incorrect aggregations.** `RETURN key, count(x)` does not group correctly. Always return raw rows and aggregate in pandas with `groupby().nunique()`.
301- **`LOAD CSV + CREATE` does not deduplicate.** Each CSV row creates a new node unconditionally. TuringDB has no `MERGE`. Pre-dedupe in pandas if you need one-node-per-unique-value.
302- **Writes outside a change do not persist.** Always wrap `CREATE`/`SET` in `new_change()` ... `CHANGE SUBMIT`. This is the most common mistake when extending the skill.
303- **The daemon must match the Python package version.** If `turingdb` was upgraded but an old daemon is still running, `LOAD CSV + CREATE` and other v1.29 features will fail. Stop the old daemon first: `--stop-server`.
304
305## Safety
306
307- **No patient identifiers in logs or outputs.** The skill never echoes raw CSV row content to stdout or to the JSON summary. `--query` is the exception — it returns the user's own query results verbatim.
308- **Synthetic demo data only.** All shipped datasets (`demo/cohort.csv`, `demo/pathway.gml`, `demo/antibody.csv`) are synthetic. No real names, no real medical records, no identifiable demographics.
309- **Research-use disclaimer.** Every markdown report ends with: *"ClawBio is a research and educational tool. Not a medical device. This output must not be used for clinical decision-making."*
310- **`--build` is additive, not destructive.** Refuses to overwrite an existing graph. Pass a new `--graph` name or drop the existing one manually.
311- **`--query` is for trusted operators.** It executes arbitrary Cypher. Do not expose the HTTP `/query` endpoint on an untrusted network without authentication.
312- **No clinical recommendations.** The cohort analyser reports observed co-occurrence patterns — it does not label any pair as a contraindication, interaction, or recommendation.
313- **Local-first.** All data stays on the local machine. No cloud uploads.
314
315## Domain Decisions
316
317### Graph modelling conventions
318- **Node labels**: `PascalCase` (`Patient`, `MedicalCondition`, `BloodType`).
319- **Edge types**: `UPPER_SNAKE_CASE` (`HAS`, `TOOK_MEDICATION`, `IS_TREATED_BY`).
320- **Property keys**: `camelCase` (`displayName`, `pubmedId`).
321
322### Versioning
323Every `--build` run executes inside a fresh TuringDB change. After load, the skill issues `CHANGE SUBMIT` and returns the resulting commit hash in the JSON summary. This makes every build auditable via `CALL db.history()`.
324
325### Indexing
326The skill does not create indexes automatically. Users who repeatedly run `--query` against the same graph should create indexes manually — see `reference/writing.md`.
327
328## Agent Boundary
329
330### In scope
331- Building a TuringDB graph from CSV/TSV/GML/JSONL via `--build`.
332- Running arbitrary Cypher via `--query`.
333- Running fixed cohort analyses via `--analyse-cohort`.
334- Auto-starting a local TuringDB daemon.
335- Exposing operations via HTTP (`http_server.py`).
336
337### Out of scope
338- Inferring a biomedical schema from unstructured CSV.
339- Deduplicating or merging nodes on ingest.
340- Vocabulary normalisation (ATC, ICD, SNOMED, HGNC).
341- Statistical inference (p-values, odds ratios, survival curves, enrichment tests).
342- Embedding generation or vector search.
343- Clinical decision support.
344
345### Agent role
346The agent (LLM) dispatches this skill and interprets its outputs. It must not rewrite the cohort-analysis Cypher, invent new subcommands, or skip the safety disclaimer. For custom Cypher, point the agent at `reference/querying.md`, `reference/writing.md`, and `reference/biomedical.md`.
347
348## Integration with Bio Orchestrator
349
350**Trigger conditions**: the orchestrator routes here when:
351- The user mentions "knowledge graph", "graph database", "Cypher", or "TuringDB"
352- The user provides a CSV/GML/JSONL and asks to build or query a graph
353- The user asks for cohort-level descriptive analytics (top conditions, comorbidities)
354
355**Chaining partners**:
356- `rnaseq-de`: DE results (gene lists) can be loaded as JSONL nodes for pathway enrichment queries
357- `pubmed-summariser`: antibody graph query results can feed into literature searches
358- `clinical-variant-reporter`: variant annotations could be loaded as graph nodes for network analysis
359
360## Maintenance
361
362- **Review cadence**: re-evaluate when TuringDB releases a new major version (GROUP BY and string comparison support may change the aggregation strategy).
363- **Staleness signals**: new TuringDB release that changes `LOAD GML` property naming, or adds native `MERGE`/`GROUP BY` support.
364- **Deprecation**: if TuringDB is discontinued or the Cypher dialect diverges significantly from openCypher.
365
366## Citations
367
368- [TuringDB](https://turingdb.ai); columnar graph database with git-like versioning
369- [openCypher](https://opencypher.org); query language specification that TuringDB implements a subset of