- AGENTS.md: agent instructions and workflow guardrails.
- README.md: repo overview, quick start, and doc links.
- docs/: repository documentation and style guides.
problems: generator scripts, domain libraries, and content banks.data: YAML/CSV/text inputs used by generators.images: static images referenced by question HTML.tests: pytest suites and lint helpers.tools: utilities for audits, index generation, YAML, and images.devel: release and changelog tooling.- source_me.sh: environment setup for Python 3.12.
- pip_requirements.txt: Python dependencies.
- Brewfile: optional Homebrew dependencies.
LICENSE.LGPL_v3: LGPLv3 license text for code.LICENSE.CC_BY_4_0: CC BY 4.0 license text for non-code content.- VERSION: repo version string.
biochemistry-problems: biochemistry generators and libraries.biophysics-problems: biophysics generators (e.g. FRET color problems).biostatistics-problems: statistics and analysis generators.chi_square: chi-square generators with descriptivechi2-filenames andchisquarelib.pyhelpers.cell_biology-problems: cell biology generators.dna_profiling-problems: DNA profiling and gel electrophoresis.inheritance-problems: genetics and inheritance generators.laboratory-problems: lab-focused generators.molecular_biology-problems: molecular biology generators.matching_sets: YAML banks for matching questions.ordering: keyed YAML banks and paired native/MC ordering converters.multiple_choice_statements: YAML banks and tools for statement-based MC questions.- TEMPLATE.py: generator script template.
Domain-specific helper libraries live near the generators that use them.
- aminoacidlib.py: amino acid helpers.
- bufferslib.py: buffer system data.
- sugarlib.py: carbohydrate nomenclature utilities.
- pubchemlib.py: PubChem REST client and caching.
- moleculelib.py: molecule rendering and SMILES helpers.
- chisquarelib.py: chi-square probability helpers and shared tables for arbitrary categories, supplied work (including errors), and calculated worked examples.
- deletionlib.py: deletion mapping helpers.
- genemaplib.py: gene mapping utilities.
- tetradlib.py: tetrad analysis utilities.
- genotypelib.py: genotype formatting helpers.
pedigree_lib: family model, inheritance engine, teaching policy, sources, layout, and renderers.- authored_cases.yml: editable families.
- PEDIGREE_AUTHORING.md: people-and-unions authoring format.
- PEDIGREE_PIPELINE.md: production workflow and cache.
- PEDIGREE_DIFFICULTY.md: workload presets and construction.
- PEDIGREE_BIOLOGY.md: inheritance and teaching gates.
- PEDIGREE_LAYOUT.md: geometry and renderers.
- PEDIGREE_POLISHING.md: bounded repair stages.
- PEDIGREE_RANKING.md: current candidate sorter.
- PEDIGREE_PROBABILITY.md: offspring diagnostic.
- PEDIGREE_GRAPH_ANALYSIS.md: graph diagnostics.
- PEDIGREE_RUBRIC.md: fixed visual-review rubric.
- PEDIGREE_EVIDENCE.md: accumulated review evidence and limits.
- gellib.py: gel electrophoresis helpers.
- CUT_PLACEMENT.md: pedagogical rules for restriction-digest cut placement.
- digest_lib.py: shared restriction-digest CLI and distinct enzyme-name selection.
- dna_render_lib.py: inline-CSS DNA-map primitives for Blackboard image export.
- restrictlib.py: restriction enzyme lookup and analysis.
- seqlib.py: sequence utilities.
- rna_transcribe_lib.py: shared transcription prompts, RNA answers, and distractors for rna_transcribe.py.
treelib: tree generation, sorting, and rendering helpers.
data: YAML/CSV/text inputs used by generators.matching_sets: matching-set YAML banks by topic.multiple_choice_statements: statement-based MC YAML banks and utilities.images: static PNG/JPG assets referenced in question HTML.
- audit_problem_scripts_bptools_framework.py: framework usage audit.
- build_question_function_index.py: question-function index generator.
- build_yaml_question_bank_index.py: YAML bank index generator.
check_yaml.py: YAML validation and pretty-print utility.- add_dbsubject_to_yaml.py: add subject tags to YAML banks.
- find_all_imports.py: import scan utility.
- allow_partial_credit_for_pool.py: Blackboard pool helper.
- contrast_calculator.py: color contrast helper.
- normalize_svg.py: SVG normalization utility.
- sync_membrane_svgs.py: membrane SVG sync helper.
- convertAll.sh: batch conversion script.
- get_function_counts.sh: function count summary.
- gh-md-toc: Markdown table-of-contents generator.
- remove_all_bbq_files.sh: cleanup helper for generated BBQ files.
Release and changelog tooling (sharing changelog_lib.py).
- bump_version.py: version bump helper.
- rotate_changelog.py: changelog rotation per repo policy.
- query_changelog.py: changelog search by date/category/keyword.
- commit_changelog.py: seed commit message from changelog entries.
- flatten_broken_md_links.py: Markdown link repair helper.
- dist_clean.sh: build artifact cleanup.
setup_playwright.sh: Playwright setup.
- test_pyflakes_code_lint.py: repo-wide pyflakes lint gate.
- test_ascii_compliance.py: repo-wide ASCII/ISO compliance gate.
- test_markdown_links.py: local Markdown link validation gate.
- check_ascii_compliance.py: single-file ASCII/ISO compliance check.
- fix_ascii_compliance.py: single-file ASCII/ISO fixer.
- test_bptools.py: core
bptoolstests. - test_lib_imports.py: library import checks using shared test helpers.
libs: library-specific pytest coverage.yaml: YAML validation tests.
Generated outputs are ignored by git (see .gitignore).
bbq-*.txt: Blackboard text upload format question files.bez-*.zip: validated Blackboard pool packages created with--bbexport.qti*.zip: QTI package exports.selftest-*.html: HTML preview files for question self-testing.pyflakes.txt: pyflakes static analysis output.ascii_compliance.txt: ASCII compliance output from tests.*.py[cod]: compiled Python bytecode..DS_Store: macOS folder metadata.*.html: includes generated HTML such asall_gene_trees-3-leaves.html.
All documentation lives in docs/ except for root-level files required by convention.
- CODE_ARCHITECTURE.md: system design, components, and data flow.
- FILE_STRUCTURE.md: directory map and file organization.
- PYTHON_STYLE.md: Python coding style and conventions.
- REPO_STYLE.md: repository-level organization and file placement rules.
- MARKDOWN_STYLE.md: Markdown writing and formatting conventions.
- CHANGELOG.md: chronological user-facing record of changes.
- TODO.md: backlog scratchpad for small tasks.
- QUESTION_AUTHORING_GUIDE.md: guide for writing new question generators.
QUESTION_FUNCTION_INDEX.md: index of question generation functions.YAML_QUESTION_BANK_INDEX.md: index of YAML question banks.- AUTHORS.md: primary maintainers and contributors.
- UNIFICATION_PLAN.md: plan for unifying script interfaces.
Root-level docs (required by convention):
- AGENTS.md: agent instructions and repository workflow guardrails.
- README.md: project purpose, examples, and quick start.
LICENSE.LGPL_v3: LGPLv3 license text for code.LICENSE.CC_BY_4_0: CC BY 4.0 license text for non-code content.
- Copy TEMPLATE.py to the appropriate
problems/*-problems/subdirectory. - Rename to match the question topic using snake_case.
- Update argparse help text, question logic, and output filename.
- Place domain-specific helpers in the corresponding
problems/*-problems/subdirectory. - Use a
*lib.pysuffix for helper libraries when it improves clarity. - Import and use from generator scripts in the same subdirectory.
- Place shared YAML/CSV/text inputs under
data. - Place matching question banks under
matching_sets. - Place statement-based MC banks under
multiple_choice_statements. - Add static images under
images.
- Add pytest tests under
testsorlibsas appropriate. - Add YAML validation tests under
yaml. - Run
pytest tests/(includes the pyflakes, ASCII, and Markdown-link gates) after changes.
- Place new docs under docs/ using SCREAMING_SNAKE_CASE filenames.
- Update CHANGELOG.md when making changes.
- Follow MARKDOWN_STYLE.md for formatting.