CultureMech

CultureMech is a versioned knowledge base of microbial culture-media recipes. It combines LinkML validation, ontology grounding, provenance, deduplication, browser exports, and static recipe pages.

Corpus snapshot

The tracked corpus currently contains 15,910 normalized records and 6,320 merged records.

Normalized category	Records
algae	254
archaea	746
bacterial	14,329
fungal	126
solutions	0
specialized	455
Total normalized	15,910
Total merged	6,320

These are different layers, not competing recipe totals. Normalized records preserve source-specific formulations; merged records are deduplicated canonical outputs. Run just update-readme-stats after corpus changes. CI runs just check-readme-stats to prevent this block from drifting.

Install

Development and CI use Python 3.13, pinned in .python-version, with uv plus just. Package metadata continues to permit Python 3.10 through 3.14; CI tests the maintained 3.13 runtime.

git clone https://github.com/CultureBotAI/CultureMech.git
cd CultureMech
uv sync --frozen --extra dev
just --list

Data architecture

CultureMech has four data layers:

1. data/raw/ — immutable source payloads.
2. data/raw_yaml/ — mechanical, source-shaped YAML conversions.
3. data/normalized_yaml/ — authoritative curated and validated records.
4. data/merge_yaml/merged/ — reproducible deduplicated records.

The normalized layer is authoritative for source-specific curation and browser data. The merged layer is authoritative for canonical recipe pages. Generated app/data.js and pages/ outputs must be rebuilt, not hand-edited or committed. See Data Layers for provenance and regeneration details.

Common workflows

Validate one tracked record:

just validate-schema data/normalized_yaml/bacterial/lb_medium.yaml

Run repository checks:

just test-fast          # isolated unit and smoke tests
just test-corpus        # tracked-corpus invariants
just test-integration   # optional checkout/service boundaries
just test               # full suite with coverage floor
just validate-strict
just assign-ids-check
just check-id-catalog

Build the browser and recipe pages:

just build-browser
just gen-pages
just gen-media-pages
just serve-browser

Render one recipe while editing:

just gen-page data/normalized_yaml/bacterial/lb_medium.yaml

The output is written beneath pages/single/. The renderer is also available as culturemech render --file ... after installation.

Contributing

Start with the Quick Start, then read the Contributing Guide. New curation uses the orthogonal composition_type, nutritional_class, and functional_role axes while keeping the compatibility medium_type consistent with composition_type. Preserve round-trip YAML formatting and append a curation-history event for substantive record changes.

Useful references:

• Schema
• Quick Reference
• Data Layers
• Recipe ID lifecycle
• Unmapped Ingredients Guide
• Archived project-status snapshot
• Archived gas-mapping snapshot

Archived documents describe completed work at a point in time; they are not the current corpus status.

Ownership, citation, and license

The canonical repository is CultureBotAI/CultureMech. Use GitHub Issues for bugs and GitHub Discussions for broader questions.

Citation metadata is provided in CITATION.cff.

Project-authored data, records, annotations, mappings, data exports and narrative documentation are licensed under CC BY 4.0. Project-authored code, scripts, tests, schemas and website templates are licensed under BSD-3-Clause. See LICENSE for scope and attribution.

Third-party material retains its own licenses and notices. Preserve upstream attribution and source-specific terms when redistributing a record or subset. Previously released material remains available under its original license.