How vortexpixelz/mcore-1 works
1. What this repo is
- mcore-py is the reference Python implementation of the MCORE-1 specification.
- The architecture is centered on a core metrical/state model, then layered with algebra, validation, encodings, overlays, and renderers.
2. Source of truth and documentation boundary
- docs/MCORE-1-v0.1-spec.pdf is the formal specification.
- README.md describes the intended conformance levels and is effectively the public architecture guide.
- The notebooks and root-level scripts act as worked examples and experimental applications rather than the core library.
3. Core domain model
- src/mcore_py/model.py defines the primary data structures: trits, weights, levels, prosodic units, constituents, and budgets.
- src/mcore_py/__init__.py exposes the public API, so consumers can import the model and utility functions from one place.
- This is the main boundary between “user data” and the rest of the system.
4. Algebra and generation
- src/mcore_py/algebra.py contains the trit algebra and pattern enumeration logic.
- This is where the repository’s central invariants live: ternary weights, addition/composition, and completion of partial structures into valid ones.
- Generation flows from a budget or target weight into all admissible patterns.
5. Validation pipeline
- src/mcore_py/checker.py verifies trees/constituents against algebraic constraints.
- The checker is the analysis side of the system: it confirms conservation and well-formedness rather than generating candidates.
- In architecture terms, it sits between the model and any serialization/rendering layer.
6. Surface syntaxes and encodings
- src/mcore_py/mss.py handles the human-readable surface syntax.
- src/mcore_py/tme6.py implements the compact 6-bit opcode encoding.
- src/mcore_py/base64tme.py adds text-safe Base64 serialization on top of TME-6.
- Data can therefore move from human notation to compact binary/text encodings and back.
7. Traditional overlays as extension modules
- src/mcore_py/overlays/ is the extension boundary for tradition-specific or domain-specific semantics.
- quantitative_metrics.py appears to provide the primary prosody overlay; quantum.py and stubs.py suggest additional experimental or placeholder overlays.
- These overlays adapt the same core algebra/model to different interpretation domains without changing the base representation.
8. Rendering/output layer
- src/mcore_py/renderers/terminal.py and token_stream.py are presentation adapters.
- They turn internal structures into terminal-friendly output or token streams, keeping display concerns out of the core checker/algebra code.
- The README notes audio as a future renderer, so this layer is intended to be expandable.
9. CLI as the integration hub
- src/mcore_py/cli.py is the main user-facing orchestration layer.
- It connects parsing, checking, encoding/decoding, completion, and diagnostics into commands like validate, complete, encode, decode, doctor, smoke, and notebook-smoke.
- For architecture diagrams, this is the entry point that binds the library subsystems into a runnable tool.
10. Examples, notebooks, and experimental applications
- notebooks/ and S3_Cosmological_Crystallization_Analysis.ipynb show interactive usage and domain exploration.
- s3_crystallization_analysis.py and S3_Winner_Subset_Characterization.py are standalone analysis scripts, likely downstream consumers of the same model/checker ideas.
- These are application/demo artifacts, not part of the core package boundary.
11. Tests and quality gates
- tests/test_mcore.py and tests/test_quantum_overlay.py validate the core API and overlay behavior.
- tests/test_s3_analysis_scripts.py covers the standalone analysis scripts.
- The notebooks in tests/ suggest some end-to-end or exploratory validation as part of the repo’s quality strategy.
12. Packaging and delivery
- pyproject.toml defines the Python package and development workflow.
- .github/workflows/python-app.yml provides CI automation, so the repo is built and tested in GitHub Actions.
- There is no heavy runtime infrastructure here; the system is primarily a local Python library/CLI with documentation and notebooks around it.
Main entry points: model.py Core model · cli.py CLI · tests Tests · checker.py Checker
Components 18
Docs
Specification and public architecture guidance
Core library
Primary package subsystems
- Core model · Trits, weights, levels, constituents, and budgets
src/mcore_py/model.py - Public API · Top-level exports for consumers
src/mcore_py/__init__.py - Algebra · Trit composition, invariants, and completion logic
src/mcore_py/algebra.py - Checker · Verifies structures against algebraic constraints
src/mcore_py/checker.py - MSS · Human-readable input and output notation
src/mcore_py/mss.py - TME-6 · Compact 6-bit serialization format
src/mcore_py/tme6.py - Base64 TME · Text-safe wrapper around TME-6
src/mcore_py/base64tme.py
Extensions
Tradition-specific overlays and renderers
- Overlays · Domain-specific semantic layers built on the core model
src/mcore_py/overlays - Metrics overlay · Primary quantitative prosody adaptation
src/mcore_py/overlays/quantitative_metrics.py - Quantum overlay · Alternate or experimental overlay semantics
src/mcore_py/overlays/quantum.py - Renderers · Output adapters for terminal and token streams
src/mcore_py/renderers
Apps
CLI, notebooks, and analysis scripts
- CLI · Command entry point for validate, complete, encode, decode, and diagnostics
src/mcore_py/cli.py - Notebooks · Interactive demos and worked examples
notebooks - Analysis scripts · Repo-level domain exploration and characterization scripts
s3_crystallization_analysis.py
Quality
Tests and CI
- Tests · Unit, overlay, and script coverage
tests - CI workflow · GitHub Actions build and test pipeline
.github/workflows/python-app.yml
Connections 24
- README → Spec PDF: documents · README points to the formal spec as source of truth
- Public API → Core model: exports · Package facade exposes the core domain model
- Public API → Algebra: exports · Package facade exposes algebra helpers
- Algebra → Core model: operates on · Algebra uses the core data structures
- Checker → Core model: validates · Checker consumes model objects and trees
- Checker → Algebra: depends on · Validation relies on the algebraic rules
- MSS → Core model: parses · Surface syntax maps to and from core structures
- TME-6 → Core model: serializes · Compact opcode encoding represents model structures
- Base64 TME → TME-6: wraps · Base64 text form is layered on TME-6
- Overlays → Core model: extends · Overlay modules adapt the shared core representation
- Metrics overlay → Overlays: implements · Primary overlay implementation
- Quantum overlay → Overlays: implements · Alternative overlay implementation
- Renderers → Core model: renders · Presentation adapters turn internal structures into output
- CLI → MSS: uses · CLI accepts or emits surface syntax
- CLI → Checker: uses · Validation commands route through the checker
- CLI → Base64 TME: uses · Encode/decode commands use text-safe serialization
- CLI → Overlays: uses · CLI can invoke overlay-aware behavior
- CLI → Renderers: uses · User-facing output is delegated to renderers
- Notebooks → CLI: demonstrates · Interactive examples exercise the package and commands
- Analysis scripts → Core model: analyzes · Standalone scripts use the same core abstractions
- Tests → Checker: covers · Tests verify validation behavior
- Tests → Quantum overlay: covers · Tests verify overlay behavior
- Tests → Analysis scripts: covers · Tests exercise analysis scripts
- CI workflow → Tests: runs · Workflow executes the test suite