Content warning: this repository discusses suicide, self-harm, psychiatric crisis, and other mental health harms in direct, clinical language. Entries quote published research, including descriptions of people's experiences.
If you are thinking about suicide or are otherwise in crisis, contact local emergency services. In the United States, call or text 988 (Suicide & Crisis Lifeline), or chat at 988lifeline.org. Outside the United States, findahelpline.com lists free, confidential services by country. See also SUPPORT.md.
A library that traces how a conversation with an AI can help or harm a person's mental health, one step at a time. It maps the behaviors anyone can point to in a transcript, how they combine into pathways, the context that changes those pathways, and the impacts they lead to. Every link says how strong its evidence is, including when there is none yet.
Status: pre-1.0. Most entries are still drafts, and entries/CHANGELOG.md gives the counts in each release. Loading, querying, and schema and reference validation work. See Current Status.
The library is for research on, and evaluation of, AI systems in mental health contexts. It is not a clinical tool, a crisis service, or a medical device, and nothing in it is medical advice.
- Do not use it to diagnose, screen or assess a person, or to make decisions about anyone's care.
- An entry is a definition, worded so that a transcript can be checked against it. It records that a claim is asserted, with its standing. It does not establish that any AI system behaves that way or that any harm occurred.
The repository holds three things: a schema that defines what a pathway or behavior is, the entries that instantiate it, and the code that loads and queries them.
schema/ the contract ──┐
├──► src/coralmap/ ──► viewer/
entries/ the content ──┘ reads both renders the result
| Part | What it is |
|---|---|
schema/ |
The JSON Schemas an entry must satisfy, generated from the models in src/coralmap/models/ |
entries/ |
The pathways, behaviors, impacts and sources themselves |
src/coralmap/ |
Loader, query, and validation API |
viewer/ |
Next.js front end that renders the catalog and its graph |
The code reads anything that conforms to the schema, so entries can change without code changes.
CoralMind writes the entries. Its Psychological Expert Council, a group of clinicians and researchers, informs the library's structure and tests it against contested cases; docs/AUTHORING.md describes how entries are written. Entries are distinct from evaluation data: test cases, transcripts and scores are generated by running coralmind/toolkit against this library and live in that repository.
pip install coralmapThe runtime dependencies are pydantic and pyyaml. The wheel includes the
catalog, so load() works without a checkout.
pixi install # Python, dev tools, and the package itself, editable
pixi run hooks-install
pixi run check # lint, format, types, schema drift, notebook outputs, testsPixi manages the dev environment and every task. It provisions Node as well as Python, so building the viewer needs nothing else installed:
pixi run -e viewer viewer-dev # http://localhost:3000
pixi run lab # JupyterLab on notebooks/pixi task list shows everything available. The main tasks:
| Task | Does |
|---|---|
pixi run check |
Lint, format, types, schema drift, entry indentation, empty notebook outputs, tests |
pixi run notebooks |
Execute the tutorial notebooks; fails when one has saved output |
pixi run notebooks-clear |
Remove saved notebook outputs; the pre-commit hook does this on commit |
pixi run check-entries |
Checks that entry YAML parses and is indented correctly |
pixi run test |
Fast tests only |
pixi run test-all |
All tests, including the slow ones that load the real catalog |
pixi run lint-fix / format |
Fix lint, format |
pixi run generate-json-schemas |
Regenerate schema/ after a model change |
pixi run -e viewer viewer-build |
Build the viewer against current entries |
pixi run lab |
JupyterLab with the library tutorials |
To load a checkout instead of the bundled entries:
export CORALMIND_KL_PATH=~/Code/coralmind/knowledge-libraryfrom coralmap import load
kl = load()
kl.version, kl.digest # release id + content hash
kl.pathways.leading_to("Impact-12") # the impact-first slice
kl.pathways.filter(composition_type="omission", standing="theorized")
kl.pathway("Pathway-5").observations # parts resolved to entries
kl.pathway("Pathway-5").preconditions # the parts that gate the claim
kl.pathway("Pathway-6").counterpart_owed # what handling it well looks like
kl.behavior("AiBehavior-12")
kl.validate() # cross-reference integritykl.version is the package version and identifies the release. kl.digest
is a hash of the content and identifies exactly which entries were loaded,
including from a working copy. Record both when you report results, so a
change in a measured rate can be traced to a model change or to an edited
entry.
The snapshot load() returns is immutable, so two reports that cite the same
version and digest were read against the same catalog.
Each directory below has a README describing what belongs there.
knowledge-library/
├── entries/ the catalog; see its README
├── schema/ JSON Schemas, generated from the models, not hand-edited
├── src/coralmap/ loader, query, validate
├── notebooks/ Jupyter tutorials, saved without outputs; `pixi run lab`
├── viewer/ Next.js catalog and network graph
├── tests/ code tests and checks over entries/
├── docs/ authoring guide and model reference
└── scripts/ schema generation and library report
Entries change only at catalog releases; entries/CHANGELOG.md says what each release changed.
The read path is implemented: load(), the entry collections and pathway
views, contract(), and validate(). The viewer reads entries/ directly
through its own TypeScript ingest.
Versions follow Conventional Commits.
When a pull request is squash-merged, its title is the commit message;
otherwise each commit that lands on main counts.
| Commit | Before 1.0.0 | From 1.0.0 |
|---|---|---|
fix: |
patch 0.1.0 → 0.1.1 |
patch |
feat: |
minor 0.1.0 → 0.2.0 |
minor |
feat!: or BREAKING CHANGE: |
minor | major |
docs:, chore:, ci:, test:, style:, refactor: |
no release | no release |
A breaking refactor!: bumps the minor component until 1.0.0. After a merge
to main, Release Please opens or updates a release pull request that sets
the version in pyproject.toml, src/coralmap/__init__.py, and
CITATION.cff, and writes CHANGELOG.md. Merging that pull request tags
vX.Y.Z, publishes the GitHub release, and uploads the package to PyPI as
coralmap.
PyPI publishing uses a trusted publisher rather than a token: owner
coralmind, repository knowledge-library, workflow release.yml,
environment pypi. The GitHub environment pypi must exist before the first
release.
Release Please authenticates as a GitHub App so that its release pull request
runs CI. Install the app on this repository with read and write access to
contents and pull requests. Then set the repository variable
RELEASE_PLEASE_CLIENT_ID to the app's client ID and the secret
RELEASE_PLEASE_PRIVATE_KEY to its private key.
| Repository | Relationship |
|---|---|
coralmind/toolkit |
Evaluates AI systems against this library, which it loads through this package. Its data-repository/ holds the test cases, transcripts and scores that evaluation generates |
coralmind/.github |
Org-wide community files: Code of Conduct, contributing guide, security policy, support, and issue forms |
Code in src/, viewer/, scripts/, tests/, notebooks, and the software
documentation is MIT.
A contribution is licensed under MIT, and the contributor also grants a patent
license for it on the terms of Apache License 2.0 section 3.
The catalog in entries/, schema/, and docs/AUTHORING.md, and the guide in
viewer/content/, are
CC BY-NC 4.0.
The coralmap wheel on PyPI bundles entries/ and schema/, so the
installed package contains CC BY-NC 4.0 content as well as MIT code.
The non-commercial terms apply to that content wherever it is installed.
The CoralMind name and logo are trademarks of CoralMind and are not licensed for reuse. A source entry describes a third-party work; that work stays under its own license.
Text in quote fields is quoted from cited works, with the source and the page or section, and belongs to its rights holders. It is not licensed under CC BY-NC 4.0.
Open a content report if the catalog misstates what a cited source says, cites a source for a claim it does not support, or attributes something to the wrong source. Give the entry id (for example kl-000244) as the item, and the source id if you know it.
Some reports have a private route:
- You wrote or hold rights in a cited work. You can open a content report like anyone else, or email compliance@coralmind.org with "Cited work" in the subject line to raise a concern privately. Email is the only route for asking us to shorten or remove a quoted passage. Name the work and the entry.
- A passage or description could identify a research participant or another real person. Report it as described in the security policy.
Do not include personal information about anyone else. We review every report and reply, and record each change to the catalog in the changelog.
Contribution guidelines are still being written, and until they are, this repository does not accept pull requests. Bug reports, content reports, and ideas are welcome as issues. If you would like to contribute expertise, such as your knowledge, data, tools, or experience, reach out through the contact form on our website.
Community files are inherited from coralmind/.github: Code of Conduct, contributing guide, security policy, support, issue forms, and pull request template.
To propose a change to an entry, see docs/AUTHORING.md.