mcard 0.1.25

MCard: Local-first Content Addressable Storage with Content Type Detection

MCard

MCard is a local-first, content-addressable storage platform with cryptographic integrity, temporal ordering, and a Polynomial Type Runtime (PTR) that orchestrates polyglot execution. It gives teams a verifiable data backbone without sacrificing developer ergonomics or observability.

---

Highlights

• 🔐 Hash-verifiable storage: SHA-256 hashing, handle registry with history, immutable audit trail output.
• ♻️ Deterministic execution: PTR mediates 8 polyglot runtimes (Python, JavaScript, Rust, C, WASM, Lean, R, Julia).
• 📊 Enterprise ready: Structured logging, CI/CD pipeline, security auditing, 99%+ automated test coverage.
• 🧠 AI-native extensions: GraphRAG engine, optional LLM runtime, and optimized multimodal vision (moondream).
• 🧰 Developer friendly: Rich Python API, TypeScript SDK, BMAD-driven TDD workflow, numerous examples.
• 📐 Algorithm Benchmarks: Sine comparison (Taylor vs Chebyshev) across Python, C, and Rust.
• ⚡ High Performance: Optimized test suite (~37s) with runtime caching and session-scoped fixtures.

For the long-form narrative and chapter roadmap, see docs/Narrative_Roadmap.md. Architectural philosophy is captured in docs/architecture/Monadic_Duality.md.

---

Quick Start (Python)

git clone https://github.com/xlp0/MCard_TDD.git
cd MCard_TDD
./activate_venv.sh          # installs uv & dependencies
uv run pytest -q -m "not slow"  # run the fast Python test suite
uv run python -m mcard.ptr.cli run chapters/chapter_01_arithmetic/addition.yaml

Create and retrieve a card:

from mcard import MCard, default_collection

card = MCard("Hello MCard")
hash_value = default_collection.add(card)
retrieved = default_collection.get(hash_value)
print(retrieved.get_content(as_text=True))

Quick Start (JavaScript / WASM)

See mcard-js/README.md for build, testing, and npm publishing instructions for the TypeScript implementation.

---

Polyglot Runtime Matrix

Runtime	Status	Notes
Python	✅	Reference implementation, CLM runner
JavaScript	✅	Node + browser (WASM) + Full RAG Support
Rust	✅	High-performance adapter & WASM target
C	✅	Low-level runtime integration
WASM	✅	Edge and sandbox execution
Lean	⚙️	Formal verification pipeline (experimental)
R	✅	Statistical computing runtime
Julia	✅	High-performance scientific computing

---

Project Structure (abridged)

MCard_TDD/
├── mcard/            # Python package (engines, models, PTR)
├── mcard-js/         # TypeScript implementation & npm package
├── chapters/         # CLM specifications (polyglot demos)
├── docs/             # Architecture, PRD, guides, reports
├── scripts/          # Automation & demo scripts
├── tests/            # >450 automated tests
└── requirements.txt / pyproject.toml

---

Documentation

• Product requirements: docs/prd.md
• Architecture overview: docs/architecture.md
• Monad–Polynomial philosophy: docs/architecture/Monadic_Duality.md
• Narrative roadmap & chapters: docs/Narrative_Roadmap.md
• Logging system: docs/LOGGING_GUIDE.md
• PTR & CLM reference: docs/CLM_Language_Specification.md, docs/PCard%20Architecture.md
• Reports & execution summaries: docs/reports/

---

Testing

# Python Suite
uv run pytest -q                 # Run all tests (~37s)
uv run pytest -q -m "not slow"   # Run fast tests only (~34s)
uv run pytest -m "not network"   # Skip tests requiring LLM/Ollama

# JavaScript Suite
npm --prefix mcard-js test

---

Contributing

1. Fork the repository and create a feature branch.
2. Run the tests (uv run pytest, npm test in mcard-js).
3. Submit a pull request describing your change and tests.

We follow the BMAD (Red/Green/Refactor) loop – see BMAD_GUIDE.md.

---

License

This project is licensed under the MIT License – see LICENSE.

For release notes, check CHANGELOG.md.