idea178-metaca-studio/AGENTS.md

Architecture

MetaCA Studio is a small Python-first toolkit to prototype federated evolutionary cellular automata. The repository's current scope is a well-focused, test-covered core providing:

• CARule: rule representation with deterministic fingerprinting for deduping across federated agents.
• CAGrid: 2D toroidal grid with Moore and Von Neumann neighborhoods and a step operator applying CARule transition tables.
• TournamentSelector: an evolutionary selection primitive exposing top-k shares for gossip-style federated exchange.

This agent/design follows a layered architecture:

• metaca.py: core domain objects and algorithms (kept small and well-tested).
• pyproject.toml: packaging metadata to allow building sdist/wheel.
• test.sh: unified test driver used by CI and contributors.

Future work should add separate modules for differentiable simulators (JAX/PyTorch), federation registry (Graph-of-Contracts sketch), adapters (NumPy/JAX/torch), and a lightweight governance ledger.

Tech stack

• Python 3.8+ (core language)
• Packaging: setuptools + wheel via PEP 517/518 (pyproject.toml)
• Tests: simple shell-driven assertions (test.sh). Replace with pytest as codebase grows.

Testing commands

Run the project's test suite and build verification with:

./test.sh

test.sh will run a packaging build (python3 -m build) to verify pyproject metadata and then execute the unit-style tests included in the script.

Contribution rules

• Keep changes minimal and well-scoped. Prefer small, reviewable patches over large rewrites.
• Add tests for every new feature or bugfix using the pattern in test.sh. If you introduce dependencies, add them to pyproject.toml.
• Do not modify files authored by other contributors without discussion.
• Run ./test.sh locally before opening PRs.

Release & publishing

This repository is not marked READY_TO_PUBLISH in this iteration. When claiming readiness:

• Ensure README.md contains a complete project summary and packaging metadata references.
• Ensure pyproject.toml contains accurate metadata and licensing information.
• Add an empty file READY_TO_PUBLISH to the repository root only when the project fully implements the published specification and all tests pass.