Contribute to Kipine

Overview

Each disease lives in app/data/diseases/{slug}/ and contains 14 JSON files — one per data type. TypeScript interfaces for all types are in src/types/disease.ts.

The three most common contributions are: adding a new source (a published paper), adding a data item (symptom, treatment, hypothesis, etc.), and adding ontology identifiers (HPO, DrugBank, UniProt codes).

Data model

Every disease directory contains these files:

All data items use a string id following the pattern: {disease-slug}-{type}-{descriptive-slug}.

Examples: schnitzler-syndrome-source-a2, schnitzler-syndrome-symptom-chronic-urticarial-rash, schnitzler-syndrome-treatment-anakinra

Add a source

Sources are the foundation — every data item traces back to a source via sourceRefCodes. Open sources.json for the relevant disease and add a new entry.

Required fields: id, type, authors, title, year, evidenceGrade, keyFindings, refCode.

{
  "id": "schnitzler-syndrome-source-b10",
  "type": "journal_article",
  "authors": ["Smith J", "Doe A", "et al."],
  "title": "Title of the publication",
  "year": 2024,
  "evidenceGrade": "B",
  "keyFindings": [
    "Finding 1",
    "Finding 2"
  ],
  "refCode": "B10",
  "journal": "Journal Name",
  "doi": "10.xxxx/xxxxx",
  "pmid": "12345678",
  "category": "pathogenesis",
  "studyType": "cohort_study",
  "sampleSize": 50
}

refCode convention

Each source gets a short refCode (e.g., A2, B7, G1) that other data items reference via their sourceRefCodes array. The letter loosely groups by topic area. Pick the next available code in the relevant letter group, or start a new letter if needed.

Source types

Allowed type values: journal_article, clinical_guideline, case_report, systematic_review, meta_analysis, expert_opinion, registry_data

Categories

Allowed category values: diagnostics, epidemiology, pathogenesis, therapeutics, reviews, genetics, immunology, case_reports

Add data items

Data items (symptoms, treatments, hypotheses, etc.) reference sources through sourceRefCodes.

Adding a symptom

{
  "id": "schnitzler-syndrome-symptom-lymphadenopathy",
  "name": "Lymphadenopathy",
  "frequency": "common",
  "frequencyPercent": 45,
  "severity": "minor",
  "description": "Palpable lymph node enlargement, usually non-tender.",
  "category": "lymphatic",
  "sourceRefCodes": ["A3", "A5"],
  "identifiers": {
    "hpo": "HP:0002716"
  }
}

Frequency values: universal, very_common, common, occasional, rare

Severity values: cardinal, major, minor

Adding a treatment

{
  "id": "schnitzler-syndrome-treatment-drug-name",
  "name": "Drug Name",
  "mechanism": "Mechanism of action",
  "route": "SC 100mg daily",
  "responseRate": "Description of response rate",
  "onset": "Hours–days",
  "line": "1st",
  "evidenceLevel": "green",
  "explanation": "Detailed explanation of how/why this treatment works.",
  "sourceRefCodes": ["G1", "G5"],
  "identifiers": {
    "drugbank": "DB00026",
    "rxnorm": "140587",
    "atc": "L04AC03"
  }
}

evidenceLevel values: green (strong evidence), amber (moderate), default (limited)

Adding a hypothesis

{
  "id": "schnitzler-syndrome-hypothesis-2",
  "statement": "Clear, testable hypothesis statement",
  "domain": "pathogenesis",
  "status": "leading",
  "evidenceScore": 55,
  "studyCount": 10,
  "evidenceFor": ["Supporting point 1", "Supporting point 2"],
  "evidenceAgainst": ["Counter-evidence 1"],
  "firstProposedYear": 2020,
  "firstProposedBy": "Author et al.",
  "sourceRefCodes": ["B7", "C4"]
}

Status values: leading, emerging, challenged, refuted

Ontology identifiers

Adding standardised ontology identifiers makes every data item interoperable with the broader biomedical ecosystem. We use an identifiers object on each item.

Symptoms — HPO

Add an identifiers.hpo field with the Human Phenotype Ontology code.

{
  "id": "schnitzler-syndrome-symptom-recurrent-fever",
  "name": "Recurrent fever",
  "identifiers": {
    "hpo": "HP:0001954"
  }
}

Treatments — DrugBank, RxNorm, ATC

Add identifiers.drugbank, identifiers.rxnorm, and/or identifiers.atc.

{
  "id": "schnitzler-syndrome-treatment-anakinra",
  "name": "Anakinra",
  "identifiers": {
    "drugbank": "DB00026",
    "rxnorm": "140587",
    "atc": "L04AC03"
  }
}

Molecules — UniProt

Add identifiers.uniprot and optionally identifiers.ncbiGene.

{
  "id": "schnitzler-syndrome-molecule-il-1",
  "molecule": "IL-1β",
  "identifiers": {
    "uniprot": "P01584",
    "ncbiGene": "3553"
  }
}

Genes — HGNC, Ensembl, ClinVar

Add identifiers.hgnc, identifiers.ensembl, and optionally identifiers.clinvar for specific variants.

{
  "id": "schnitzler-syndrome-gene-myd88-l265p-somatic",
  "gene": "MYD88",
  "identifiers": {
    "hgnc": "7562",
    "ensembl": "ENSG00000172936",
    "ncbiGene": "4615",
    "clinvar": "28173"
  }
}

Lookup APIs (all free, no auth)

Evidence grades

Every source must have an evidenceGrade:

Validate locally

Before submitting a PR, validate your changes from the app/ directory:

cd app
npm run validate    # Checks JSON schema, required fields, referential integrity
npm run score       # Calculates disease completeness score

Both commands must pass before your PR will be accepted.

Submit a PR

1. Fork the repository
2. Clone your fork and create a branch:

   git checkout -b add-source-smith-2024

3. Edit the relevant JSON files in app/data/diseases/{slug}/
4. Validate locally:

   cd app
   npm run validate && npm run score

5. Commit with a descriptive message:

   git commit -m "Add Smith 2024 cohort study to Schnitzler sources"

6. Push and open a pull request against main

PR templates

GitHub will show template options when you create the PR:

• Add Source — for new publications
• Add Data — for new symptoms, treatments, hypotheses, etc.
• Add Identifiers — for ontology mappings (HPO, DrugBank, UniProt, HGNC)
• Autoresearch Batch — for agent-generated research updates

For AI agents

If you're an AI agent that discovered Kipine through llms.txt or the JSON API:

Read the data

• GET /api/diseases/{slug}.json — complete disease object
• GET /api/diseases/{slug}/{table}.json — individual tables
• GET /api/diseases.json — index of all diseases with record counts
• GET /api/export/{slug}.jsonl — bulk export as newline-delimited JSON

Improve the data

Fork the repo, edit JSON files in app/data/diseases/{slug}/, run npm run validate && npm run score, and open a PR. Use the autoresearch-batch PR template and include before/after quality scores.

Constraints

• Never remove existing data without justification
• Every new fact must cite a source with a DOI or PMID
• Preserve existing IDs
• Follow the JSON schema — run npm run validate
• Verify PMIDs against PubMed before adding: GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=pubmed&id={pmid}&retmode=json