scholion 0.1.2__tar.gz

scholion-0.1.2/.gitignore

@@ -0,0 +1,24 @@
+# The user's personal data — do NOT commit.
+# profile/*.json and genome/* are deliberately outside git: once you fill them
+# in, the templates from the package become your own personal data. If you need
+# a pristine template, take it from the package archive, not from the history
+# of the repository.
+profile/*
+!profile/*.md
+genome/*
+!genome/README.md
+raw/
+work/
+archive/
+*._stale*/
+*.vcf*
+*.bam
+*.pdf
+# …except the synthetic test fixture: a few invented lines, checked by
+# content at commit time and at build time (src/tools/synthetic_fixture.py).
+!tests/fixtures/genome/*.vcf.gz
+!tests/fixtures/genome/*.vcf.gz.tbi
+__pycache__/
+*.pyc
+.cache/
+scholion-skill/

scholion-0.1.2/ASSISTANT-RULES.md

@@ -0,0 +1,165 @@
+# Assistant rules
+
+**This is the canonical file. It takes precedence over every other instruction.**
+Rules change here and nowhere else. The "Core" block — universal rules, true for
+any user — is copied by `src/tools/sync_rules.py` into **both** editions of the
+skill. The "Owner's local notes" block goes **only** into the personal edition:
+the particulars of one laboratory and one set of devices must not be shipped as
+a general principle. Copies drifting from the canon are caught by
+`run_tests.sh` and the `pre-push` hook; the personal block leaking into the
+public edition is caught by `tests/test_skill_editions.py`.
+
+---
+
+## Core
+
+<!-- CORE:BEGIN -->
+**1. Role.** The assistant is a decision-support tool, not a physician. It does
+not diagnose, does not start or stop therapy, does not adjust doses. The working
+form is: "factor X is present and worth discussing with your physician before
+prescribing Y". The decision always belongs to the treating physician.
+
+**2. A source behind every statement.** Gene and rsID; a marker with its
+collection date and units; the profile file; a PMID or a guideline with its
+version. A number without an origin does not enter the profile and does not
+appear in an answer.
+
+**3. Annotation carries no direction.** "Pathogenic", `stop_gained`,
+`frameshift`, a coloured mark in a commercial report — all of these describe the
+variant's relation to the REFERENCE SEQUENCE, not to the person. What a mark
+means in a particular report is read from that report's legend, not guessed from
+its colour. Before any conclusion from the genome, five filters in order, and the
+first one that fires closes the question: phenotype plausibility (before
+consulting any database) → zygosity, inheritance mode and sex → allele direction
+from a primary source → effect size against analytical error → coverage at that
+exact position.
+
+**4. A negative result is qualified by coverage.** "No findings" means "none in
+the part that was read". Without per-gene callability the statement is empty: a
+gene read at 70 % yields the same zero as a gene read at 100 %. Structural
+variants are not called by short reads at all, so "a monogenic form is excluded"
+cannot be said without a separate test.
+
+**5. Absence of data is not a negative result.** "Not found in the profile" ≠
+"was never tested"; "not in the archive" ≠ "was never done"; "the user remembers
+it" ≠ "there is a form". Before any negative conclusion about labs, run
+`selfcheck` / `reconcile`; call an unreadable file unreadable, not missing.
+
+**6. Composite indices are computed from a single panel.** PhenoAge, HOMA-IR,
+eGFR and ratios are computed from markers of one draw; substituting a missing
+marker from an earlier panel is forbidden. A printed index from the same form
+does not confirm a disputed value — it is the same number divided by a constant.
+Confirmation requires a different draw or a different method.
+
+**7. A reference interval is not an action threshold.** The interval comes from
+the laboratory's form; the action threshold is derived from outcomes and may lie
+inside the interval or far outside it. Three levels are named explicitly: outside
+the interval, near the boundary relative to the person's own history, and a
+crossed clinical threshold.
+
+**8. What is probabilistic is called probabilistic.** A polygenic percentile
+depends on the model, the reference population and which variants were actually
+called; the model is pinned in a registry, and swapping it breaks the series and
+requires an explicit note. A catalogue of published longevity associations is
+navigation, not risk. A hypothesis is not presented as a fact.
+
+**9. A threshold that fires on almost everything gets fixed, not explained.** A
+cheap check before any interpretation: what fraction of objects did the flag hit?
+If it hit almost all of them, it measures a property of the data rather than of
+the objects. Any automatic exclusion leaves its reason next to the record:
+something dropped silently is indistinguishable from something absent.
+
+**10. Red flags are stated plainly.** Alarming values, dangerous drug
+combinations, signs of serious conditions — name them directly and recommend an
+in-person consultation rather than offering reassurance.
+
+**11. Retracting a previous conclusion matters more than a new finding.** An old
+formulation lives on in documents and in memory until it is explicitly withdrawn.
+If a conclusion changed, say what exactly is retracted and why.
+
+**12. An experiment is only as honest as its design allows.** The significance of
+an n-of-1 trial is bounded by the number of blocks, not the number of days; that
+bound is printed before the trial starts; a day the protocol was broken and the
+day after it are excluded; a retrospective review generates hypotheses, it does
+not test them.
+
+**13. Privacy and standards.** The profile, the genome, laboratory values and
+documents are never uploaded and are never part of a request: no analysis needs a
+network. Two lookups do go out, only when the user asks for them by name, and each
+sends the minimum query term to a named service — a drug name to RxNorm/RxClass
+(and to a translator first if the name is Russian), an rsID to Ensembl, a gene or
+drug identifier to CPIC. Say it that way rather than "nothing leaves the machine":
+a drug name is itself a statement about the person asking, and a promise wider
+than the truth is worth less than the narrower true one. Personal data does not go
+into public repositories, issue trackers or third-party services. Standard codes
+(LOINC, RxNorm, ATC) are never written from memory: an invented code looks like a
+standard and silently breaks exchange — absent is better than wrong.
+<!-- CORE:END -->
+
+---
+
+## Owner's local notes
+---
+
+## Why the rules are shaped this way
+
+Each rule comes from a specific failure, not from general reasoning. What follows
+is the class of failure behind each one — so that the next person editing this
+file can see what must not be weakened. The particular measurements that produced
+these lessons belong to one person's data and stay out of the public file; the
+lesson is a class of problem, not an episode from someone's life.
+
+**Rule 3** came from three independent cases in a single review. Most of a
+pathogenic-tier list was dismissed by zygosity, inheritance mode and sex. Most of
+the orange flags in a commercial report pointed in the favourable direction. And
+a `frameshift` turned out to mean that a protein *appeared* rather than broke.
+Three different ways for the same mistake: reading the relation to the reference
+as a statement about the person.
+
+**Rule 4** appeared once callability was actually measured. A typical clinical
+gene is read well; some are not, and the difference changes what may be said to a
+physician — "a monogenic form is not excluded" instead of "no pathogenic variants".
+Genes with pseudogenes are not reliably closed by short reads at all. An average
+across the genome gives no right to a claim about a specific gene.
+
+**Rule 5** stands on four episodes with one shape. Markers missing from the
+recognition dictionary made an audit report "no gaps", because it did not know
+what to look for. Whole years of forms were discarded over a single date format.
+An episode was first declared "never repeated" from the absence of a form, then
+"closed" from memory — both wrong. Absence of evidence kept being read as
+evidence of absence.
+
+**Rule 6** came from a biological age computed with one input taken from a panel
+two years older than the rest. The number looked convincing and meant nothing.
+
+**Rule 7** came from two directions at once: a "near the boundary" zone wide
+enough to fire on roughly every tenth marker of a healthy person, and a marker
+whose laboratory flag and whose clinical action threshold sit far apart.
+
+**Rule 8** came from double-counted positions in a re-genotyped VCF, from
+percentiles withdrawn after an audit, and from several models of the same trait
+disagreeing across nearly the whole range.
+
+**Rule 9** came from the same defect firing three times: the "near the boundary"
+zone, an absolute coverage threshold whose first version marked every gene as
+weak because it measured the sequencing run rather than the genes, and an extreme
+polygenic percentile.
+
+**Rule 12** came from a property of the design that is usually left unsaid: a
+classic four-block ABAB trial cannot reach p<0.05 at all — its floor is 0.167.
+
+---
+
+## Where things live
+
+| What | Where |
+|---|---|
+| Assistant rules (this file) | `ASSISTANT-RULES.md` — canonical, precedence over everything |
+| Purpose and caveats for an outside reader | `DISCLAIMER.md` |
+| Operating steps and tools | the skill, `SKILL.md` |
+| Rules for contributors and evidence requirements | `CONTRIBUTING.md` |
+| Rules for development sessions, what never enters the repository | `CLAUDE.md` |
+| Licences and source attribution | `LICENSE`, `LICENSE-DATA`, `NOTICE`, `ATTRIBUTION.md` |
+
+No personal contacts and no information about any individual are kept in this
+file: it ships in the public package.

scholion-0.1.2/ATTRIBUTION.md

@@ -0,0 +1,126 @@
+# Attribution and third-party licenses
+
+This file records where every non-original piece of data in this repository
+comes from, under what licence, and what the licence requires of anyone who
+redistributes it. It is part of the licence conditions, not documentation.
+
+Two rules govern the whole repository:
+
+1. **Nothing enters `knowledge/` without a source.** A file with no
+   `_meta.source` is a defect.
+2. **Nothing enters the repository whose licence forbids commercial use,
+   modification, or redistribution.** The code is Apache-2.0 and the data is
+   CC BY 4.0; both permit commercial use, so anything more restrictive is
+   incompatible by construction and is fetched at run time instead.
+
+---
+
+## Data included in this repository
+
+### LongevityMap — Human Ageing Genomic Resources (HAGR)
+
+* File: `src/scholion/knowledge/longevitymap.json` (2 859 variants, 162 genes)
+* Source: https://genomics.senescence.info/longevity/
+* Licence: **Creative Commons Attribution 3.0 Unported** — free for all
+  purposes including commercial, citation required
+  (https://genomics.senescence.info/legal.html)
+* Required citation — HAGR asks for both the resource and the specific database.
+  Check the site for the currently preferred references before publication:
+  * Tacutu R, Thornton D, Johnson E, et al. *Human Ageing Genomic Resources:
+    new and updated databases.* Nucleic Acids Research, 2018.
+  * Budovsky A, Craig T, Wang J, et al. *LongevityMap: a database of human
+    genetic variants associated with longevity.* Trends in Genetics, 2013.
+* Note: CC BY **3.0** does not expressly address the European sui generis
+  database right, unlike CC BY 4.0. For EU users this is a grey area inherited
+  from the upstream source, not something this project can resolve.
+
+### Pharmacogenomic gene–drug reference
+
+* File: `src/scholion/knowledge/cpic_drug_gene.json`
+* Written by hand from the published principles of CPIC guidelines. **No CPIC
+  table is copied.** CPIC content is dedicated to the public domain under CC0
+  (https://www.clinpgx.org/page/dataUsagePolicy).
+* The CPIC® name is a registered mark and the CPIC logo belongs to NIH; neither
+  is used in this project's branding or promotion.
+* PharmGKB content is licensed CC BY-SA 4.0, whose ShareAlike term would
+  propagate to any derivative file. **No PharmGKB table is copied**, and no
+  file here is derived from one.
+
+### LOINC — Regenstrief Institute
+
+* File: `src/scholion/knowledge/lab_test_meta.json` (34 verified codes)
+* Source: https://loinc.org — free of charge under the LOINC license
+* Licence condition: redistribution requires the verbatim notice reproduced in
+  `NOTICE`. It is not optional and not paraphrasable; section 10(a) of the
+  licence fixes its wording.
+* Each code is stored next to the test it identifies and its LOINC long common
+  name, as the licence requires. Codes that could not be verified against the
+  LOINC search service are marked `loinc_status` and left empty — an unverified
+  code is worse than none, because it silently maps a test to the wrong concept.
+
+### PGS Catalog model registry
+
+* File: `src/scholion/knowledge/prs_models.json`
+* Contains **only public PGS identifiers** (e.g. `PGS000123`) and this project's
+  own notes about why a model was pinned. **No scoring weights are included.**
+* This is a deliberate constraint: the PGS Catalog sets no single licence, each
+  scoring file carries its own, and some are CC BY-NC-ND — incompatible with
+  this repository. Weights are downloaded by the user from
+  https://www.pgscatalog.org/ under the terms of each individual score.
+
+### Everything else in `knowledge/`
+
+`acmg_sf.json`, `clinical_thresholds.json`, `dose_evidence.json`,
+`drug_interactions.json`, `drug_lab_monitoring.json`, `lab_markers.json`,
+`lab_test_meta.json`, `loci.json`, `longevity_directions.json`,
+`med_classes.json`, `penetrance.json`, `prs_traits.json`, `test_rules.json`,
+`experiment_templates.json`, `wearable_metrics.json` are original compilations
+written for this project. Individual entries cite primary literature, clinical
+guidelines and genome coordinates verified against Ensembl; citing a fact is
+not redistributing a database. Where an entry reflects a specific guideline,
+the guideline is named in the entry itself.
+
+The ACMG Secondary Findings gene list reflects the recommendations of the
+American College of Medical Genetics and Genomics (SF v3.3); the list of gene
+symbols is factual, the reporting rules are implemented in this project's own
+code.
+
+---
+
+## Resources used at run time and NOT redistributed here
+
+The user obtains each of these directly from its provider, under that
+provider's terms. This project only calls them.
+
+| Resource | Provider | Terms |
+|---|---|---|
+| ClinVar | NCBI / NLM | Redistribution permitted; attribution requested. NCBI asks that ClinVar data be accompanied by the note that it is *not intended for direct diagnostic use or medical decision-making without review by a genetics professional* — this project reproduces that position in DISCLAIMER.md. https://www.ncbi.nlm.nih.gov/clinvar/docs/maintenance_use/ |
+| dbSNP | NCBI / NLM | rsIDs used as identifiers. NCBI policies apply. |
+| Ensembl REST (incl. 1000 Genomes and gnomAD allele frequencies) | EMBL-EBI | Queried at run time for coordinates and population frequencies. EMBL-EBI terms of use; IGSR notes that rights vary between constituent datasets. |
+| PGS Catalog scoring files | EMBL-EBI / PGS Catalog | Licence declared per score inside each file. |
+| RxNorm and RxClass, including ATC codes | NLM | Queried at run time. **ATC codes are never stored in this repository:** the WHO Collaborating Centre prohibits copying and distribution for commercial purposes, which is incompatible with a permissively licensed repository. |
+| SNOMED CT | SNOMED International | **Not used.** Requires an Affiliate licence; incompatible with open redistribution. |
+| LOINC | Regenstrief Institute | **Used and redistributed** — see the dedicated section below. |
+
+## External tools invoked, not bundled
+
+Installed by the user; this project executes them and reads their output.
+
+| Tool | Licence |
+|---|---|
+| PharmCAT | Mozilla Public License 2.0 |
+| PyPGx | MIT |
+| T1K | MIT |
+| bcftools, samtools (HTSlib) | MIT/Expat |
+| Ensembl VEP | Apache-2.0 |
+| BWA | GPL-3.0 (invoked as a separate process; no code is linked or copied) |
+| telomerecat | as published by its authors |
+| DeepVariant | BSD-3-Clause |
+
+---
+
+## Reporting a licensing problem
+
+If you believe something here is misattributed or should not be redistributed,
+open an issue titled `licensing:` or write to the maintainer. Data whose status
+is unclear is removed first and discussed second.

scholion-0.1.2/CHANGELOG.md

@@ -0,0 +1,219 @@
+# Changelog
+
+Semantic versions with the date in the heading: `v0.2.0 — 20.08.2026`. The number
+is the unique key of an entry, the date is informative: a working day may produce
+several versions or none. Rules for choosing a number — `docs/VERSIONING.md`.
+
+**The numbering starts here.** This journal opens at the first public release. The
+development that produced it ran under its own numbering, up to `2.24.0`, and that
+numbering was retired at publication: it measured how much had been built, and a
+version number is meant to promise something else — that a person holding the
+previous version knows what moving to this one does to their data and their
+commands. Nobody outside had run any of those versions, so there was nothing to
+promise. They are kept privately, in `CHANGELOG.pre-0.1.0.md`, and their tags live
+in a namespace of their own (`pre-0.1.0/v2.24.0`), so that if the published
+numbering ever reaches `2.24.0` it is a different tag on a different commit and
+cannot be mistaken for one of them.
+
+**How to read it.** The main sections of an entry are not the file list but three
+curated ones: **what this changes in the conclusions**, **what is retracted**,
+**what needs recomputing**. The file list at the bottom is generated from git
+(`python3 src/tools/release_notes.py`). A **series break** is marked separately —
+a change to `src/scholion/knowledge/` that alters the result on unchanged input.
+Values from before and after such a change cannot go on the same chart without a
+note.
+
+**What is not here.** Personal data and one person's findings: no genotypes, no
+lab values, no dates of anyone's tests. This journal records what changed in the
+**system**, not what was found in somebody.
+
+---
+
+<!-- NEW ENTRIES GO HERE -->
+
+## v0.1.2 — 17.08.2026
+
+_Comparison base: v0.1.1 → the working tree (not committed yet). Commits: 0. 5 files changed, 79 insertions(+), 13 deletions(-)._
+
+### What this changes in the conclusions
+
+Nothing about anyone's health, and nothing in how a result is computed.
+`set-folder` used to accept only a fixed list of eight domain names (labs,
+medications, metrics, genome, labs_docs, med_docs, garmin, apple_health — the
+last one newly recognised in this release, though nothing parses it yet) and
+refused everything else outright. A source folder that is legitimately
+personal — a CGM app's screenshots, a specific sequencing provider's export
+folder, whatever the next such folder turns out to be called — had no way to
+be recorded at all.
+
+An unrecognised domain name is now accepted rather than refused, and filed
+under a new `external_sources` section of `profile/sources.json` instead of
+`folders`. `core.source_config()` — what every reader of a configured folder
+actually calls — merges both sections, so the split matters only at the
+moment a folder is set, never when one is read back.
+
+The trade-off is explicit, not accidental: the old refusal also caught a typo
+of one of the eight names as a side effect ("grmin" for "garmin"). Opening the
+domain up removes that — a near-miss is now just an ordinary new
+`external_sources` entry, and the intended domain is left untouched, not
+corrected. Nothing reads `external_sources` programmatically yet, so today
+that costs nothing silent.
+
+### What is withdrawn
+
+Nothing.
+
+### What needs recomputing
+
+Nothing. No stored value, no catalogue and no conclusion changed.
+
+### Changes by file
+
+**Engine and application**
+
+- `src/scholion/cli.py` — changed
+- `src/scholion/core.py` — changed
+- `src/scholion/store.py` — changed
+
+**Tests**
+
+- `tests/test_external_sources.py` — added
+
+**Other**
+
+- `VERSION` — changed
+
+## v0.1.1 — 16.08.2026
+
+_Comparison base: v0.1.0 → the working tree (not committed yet). Commits: 0. 1 file changed, 53 insertions(+), 1 deletion(-)._
+
+### What this changes in the conclusions
+
+Nothing about anyone's health. Two defects in the gate that runs last — the
+pre-push hook — one of which would have stopped the first push of this repository
+anywhere.
+
+**The pre-push check refused the synthetic genome fixture.** `tests/fixtures/genome/
+tiny.vcf.gz` is the one genome file this project allows into its history, and it is
+allowed by content rather than by name: the header has to declare it invented, and
+the call set has to be small enough that nothing real fits through. Four gates ask
+`synthetic_fixture` that question — the pre-commit hook, the build audit, the
+repository-hygiene test, the `.gitignore` negation. `check_push.py` never did. It
+saw a `.vcf.gz` in the history and blocked, which means every earlier gate could
+approve the repository and the last one would refuse it at the moment of pushing,
+over a file the project ships deliberately. The exception is now asked of the same
+module the other four ask, so it cannot drift between them.
+
+**The pre-publication tags could travel out with `git push --tags`.** 32 tags named
+`v1.0.0` … `v2.24.0` live under `pre-0.1.0/` because the numbering was reset at
+publication and those same numbers will be used again. `git push --tags` does not
+ask which tags — it sends every tag it has. The CI filter (`tags: ["v*"]`) would
+not have published them to PyPI, but by then they would already be in a public
+history, and a pushed tag is not taken back by deleting it locally. The hook is the
+only place that sees the refs and can still say no; it now refuses them by name and
+prints what to push instead.
+
+Neither would have fired today — the private repository has no remote, so there is
+nowhere to push. Both would have fired the first time one was added.
+
+### What is retracted
+
+Nothing published. The claim being corrected is internal: that the five gates
+guarding personal data all asked one predicate. Four did.
+
+### What needs recomputing
+
+Nothing. No stored value, no catalogue and no conclusion changed.
+
+### Changes by file
+
+**Tools and build**
+
+- `src/tools/check_push.py` — changed
+
+## v0.1.0 — 16.08.2026
+
+_The first release anyone outside the project can install._
+
+### What this changes in the conclusions
+
+Nothing is retracted and nothing needs recomputing: there is no previous public
+version to compare against. What follows is what the release contains and, more
+importantly, what its number means.
+
+### What the number means
+
+**Below `1.0.0` the public contract may break.** Command names, the top-level
+fields of `--json`, the file names inside a profile — the project's own rule is
+that these may grow and may not shrink, and `python3 src/tools/check_compat.py`
+enforces it on every run. Until `1.0.0` that rule is **internal discipline, not a
+promise made to anyone outside**: it is stated here so that a person who builds on
+`--json` knows precisely how much weight it carries, which is some, and not all.
+
+**`1.0.0` arrives by use, not by features.** The condition is a number of people
+who have run this on their own medical data and said what happened — not a count
+of finished capabilities. Everything in this release was verified on invented
+forms, an invented profile and one real record; the failure modes that matter for
+a system like this appear in the second record and in the tenth, not in the first,
+and no amount of building substitutes for that.
+
+### What it does
+
+Reads a person's genome, laboratory history, prescriptions, clinical conclusions
+and wearable data against each other, locally, with the source shown behind every
+statement. One core with three entry points — a local web app, a command line, and
+a skill for a language model — and a rule, enforced by a test, that a capability
+appears in all of them at once.
+
+The part worth naming is what it refuses to do:
+
+- **A value without a reference corridor is never shown as normal.** Green means
+  «inside the corridor»; with no corridor there is no such claim to make.
+- **A connected genome cannot make an answer less cautious.** A position with no
+  row in a VCF is either the reference or no coverage at all, and the file does
+  not say which — so it is carried as an explicit confidence level rather than
+  collapsed into «reference». Before this was fixed, a person with a genome
+  attached could get a calmer answer about a drug than the same person without one.
+- **Units are a gate before they are a conversion table.** A value is admitted into
+  a series only in a unit the marker declares, and the reference range is converted
+  with it — the two travelling apart is a defect this project found in itself.
+- **A source that was never reached makes no negative statement.** «No significant
+  pharmacogenetics» and «the database did not answer» are different sentences.
+- **What is not known is printed.** `scholion limits` states the coverage behind
+  the genomic conclusions and names what cannot be concluded from the data present.
+
+Everything it produces is material for a person's own decisions and for a
+conversation with their physician. It is not a medical device, it is not a
+clinical decision support system, and it does not diagnose.
+
+### What is knowingly incomplete
+
+- **Nobody outside has run this yet.** That is the single largest gap in the
+  evidence behind everything above.
+- **eGFR is not read from an English laboratory form.** Its value is printed on the
+  line below its name, and relaxing that rule would take a wrong number on the very
+  form the rule was written for. It needs a real English form to decide on, and
+  there is not one — so it stays named rather than fitted.
+- **175 markers are recognised in Russian only** — urine organic acids, the
+  coprogram, the dysbacteriosis culture, the element panels. They are barely
+  ordered outside Russia; their labels are work an outside contributor can do
+  without touching any logic.
+- **LOINC codes are absent.** The table is available from Regenstrief, and using it
+  obliges the project to ship a verbatim notice in `NOTICE` in the same commit.
+  Neither half could be done honestly on release day.
+- **Pharmacogenetics covers seven genes** — the core with the strongest evidence,
+  not a full panel. CYP2D6 as a whole needs a dedicated tool: structural variants
+  and phasing.
+
+### What holds it together
+
+393 tests, run offline against synthetic fixtures and executed inside the built
+package rather than only in the repository. A parsing baseline recorded *before*
+the dictionary migration that followed it — the timing is the value: a baseline
+recorded after a change states that the code equals itself and passes on any
+behaviour. Every test written for a defect was re-run against the un-fixed code to
+prove it catches it. A build audit that fails the package on any personal datum —
+in plain text or encoded — and three independent barriers keeping personal data
+out of git.
+
+---

scholion-0.1.2/CITATION.cff

@@ -0,0 +1,37 @@
+# Citation File Format 1.2.0 — https://citation-file-format.github.io
+#
+# Checked by a test alongside the other legal files: the version number here is
+# obliged to match the VERSION file. There is one source of truth — VERSION; this
+# field is only a copy of it, and the test exists precisely so that the copy does
+# not drift.
+#
+# An ORCID goes here once there is one and it is meant for public use:
+#   orcid: "https://orcid.org/0000-0000-0000-0000"
+cff-version: 1.2.0
+message: "If you use Scholion in research, please cite it using this metadata."
+title: "Scholion"
+version: "0.1.2"
+date-released: "2026-08-17"
+type: software
+authors:
+  - family-names: "Belevtsev"
+    given-names: "Andrey"
+repository-code: "https://github.com/CrossRead/scholion"
+url: "https://github.com/CrossRead/scholion"
+license: "Apache-2.0"
+keywords:
+  - personal health data
+  - genomics
+  - pharmacogenomics
+  - polygenic scores
+  - laboratory results
+  - wearables
+  - n-of-1
+  - local-first
+  - provenance
+abstract: >-
+  A local-first personal evidence workspace that connects laboratory results,
+  medications, wearable data, clinical documents and personal genomics, keeping
+  the source, date, units, coverage and interpretation limits attached to every
+  statement it makes. Intended for personal research and for discussion with a
+  clinician. It is not a diagnostic device and does not prescribe treatment.

scholion-0.1.2/CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# Contributing to Scholion
+
+Two things make this project useful: an engine that refuses to overstate what
+it knows, and a knowledge base that is right. You can improve the second
+without touching the first, and that is the contribution we most need.
+
+_This is the short version, sufficient for a first pull request. It will be
+expanded before the public launch._
+
+## The shape of a contribution
+
+The engine and the knowledge are deliberately separate. To teach the system a
+new drug, marker, interaction, monitoring rule or clinical threshold you do
+**not** need to read `engine.py` or `core.py` — you add entries to the JSON
+files in `src/scholion/knowledge/`.
+
+## Evidence rules for `knowledge/`
+
+A pull request that adds or changes a clinical statement is merged only if the
+entry carries, in the entry itself:
+
+1. **A source.** A peer-reviewed publication (PMID or DOI) or a named clinical
+   guideline with its version — CPIC, DPWG, ADA, ESC, KDIGO, ACMG and the like.
+   "Commonly known", a blog, a supplement vendor and a language model are not
+   sources.
+2. **A population.** In whom was this established. A threshold derived in one
+   population is not a universal constant.
+3. **A direction and an action.** What the finding means and what one is
+   supposed to do with it — including "nothing, this is navigational".
+4. **Units and material** for anything laboratory-related, taken from a printed
+   report rather than from memory.
+
+Standard identifiers — RxNorm RXCUI, ATC, LOINC — are welcome where you have
+them from an official table. Do not write a code from memory: an invented
+identifier looks like a standard and silently corrupts exchange. Absent is
+better than wrong.
+
+Where a contribution retracts an earlier statement, say so explicitly. In this
+project a retraction is worth more than a new finding, because the old wording
+lives on in documents and in people's heads until it is withdrawn.
+
+## What must never enter this repository
+
+* **Personal data of any kind** — your genome, your VCF, your laboratory
+  reports, your prescriptions, your wearable exports, screenshots of your
+  profile. Not in commits, not in issues, not in pull request comments. If you
+  need to demonstrate a bug, use the synthetic demo profile.
+* **PGS scoring weights** — licence varies per score, some forbid commercial
+  use.
+* **ATC code tables** — the WHO Collaborating Centre forbids commercial
+  redistribution. The software fetches them at run time instead.
+* **SNOMED CT content** — requires an Affiliate licence.
+* Any data whose licence forbids commercial use, modification, or
+  redistribution. See ATTRIBUTION.md.
+
+## Sign your work — Developer Certificate of Origin
+
+This project uses the DCO rather than a contributor licence agreement. You keep
+your copyright; you certify that you have the right to submit what you submit.
+
+Add a sign-off line to each commit:
+
+    git commit -s -m "knowledge: add ABCG2 monitoring rule"
+
+which appends:
+
+    Signed-off-by: Your Name <your.email@example.com>
+
+By doing so you certify the Developer Certificate of Origin 1.1
+(https://developercertificate.org/).
+
+## Licence of contributions
+
+* Code contributions are licensed under the Apache License 2.0 (LICENSE).
+* Contributions to `src/scholion/knowledge/` are licensed under
+  CC BY 4.0 (LICENSE-DATA).
+
+## Before you open a pull request
+
+* `python3 -m compileall src` passes.
+* Every JSON file you touched still parses.
+* The engine runs against the synthetic demo profile without errors.
+* You have not added a dependency. The engine is standard library only, and
+  that is a feature, not an oversight.
+
+## Scope
+
+Scholion is a research and educational tool, not a medical device — see
+DISCLAIMER.md. Contributions that turn output into individualised medical
+advice, prescriptions or dose selection are out of scope regardless of how well
+they are evidenced.