# CatOpt-Graph MVP

Graph-Calculus-Driven Compositional Optimization Studio for Edge Meshes

Overview
- CatOpt-Graph provides a minimal, pragmatic MVP for compositional optimization across edge meshes. It introduces a lightweight ontology (Objects, Morphisms, Functors) and a tiny ADMM-lite solver that demonstrates delta-sync and reconnection semantics while converging on a simple global constraint.

What you get in this MVP
- Core ontology scaffolding: Object, Morphism, Functor, and a tiny versioned ContractRegistry.
- ADMM-lite solver: asynchronous, two-agent solver with bounded staleness and deterministic reconciliation on reconnects.
- Adapters: rover and habitat stubs that map to a canonical representation.
- Governance scaffolding: lightweight conformance checks and audit-friendly data flow.
- Transport surface: a minimal TLS/REST-like mock transport for MVP testing.
- Tests: unit tests for the ADMM-lite core and contract registry.

How to run
- This project is Python-based. See test.sh for the test runner which also builds the package to validate packaging metadata.
- After cloning, run: bash test.sh

Roadmap (MVP, 8–12 weeks)
- Phase 0: Core ontology, 2 adapters (rover, habitat), ADMM-lite core, delta-sync scaffold.
- Phase 1: Global constraints layer (Limits/Colimits) and governance ledger.
- Phase 2: Bridge to cross-domain runtimes (Open-EnergyMesh/GridVerse-like ecosystems) and a canonical transport.
- Phase 3: HIL validation with Gazebo/ROS and minimal cross-domain demos.

Architecture snapshot
- Core: Objects, Morphisms, Functors, Limits/Colimits skeleton, and a versioned ContractRegistry.
- ADMM-lite: two-agent solver with delta-sync and deterministic reconciliation on reconnects.
- Adapters: rover and habitat stubs exposing a minimal interface readState, exposeLocalProblemData, applyCommand.
- Bridge: mapping between domain LocalProblem data and a canonical CatOpt representation.
- Governance: auditing and contract conformance scaffolds.
- Transport: mock TLS/REST-like surface for MVP integration.
- Tests: unit tests for core components and end-to-end tests for the ADMM-lite flow.

Extending the MVP
- Add new adapters and register them in the ContractRegistry.
- Enhance the bridge with richer to_canonical/from_canonical mappings for domain data.
- Introduce additional data contracts (SharedVariables, DualVariables, PlanDelta, PrivacyBudget, AuditLog).
- Add a lightweight HIL simulation layer (Gazebo/ROS) for offline testing.

Packaging and metadata
- The Python package name is catopt_graph_graph_calculus_driven_compo, as defined in pyproject.toml.
- See pyproject.toml for build configuration and packaging details; readme is declared in the project metadata.

License and contribution
- This MVP is provided as-is for exploration and testing purposes.
- See AGENTS.md for architectural guidance and test commands.

Notes
- This README is a living document. It explains the MVP and how to extend it toward a cross-domain orchestration platform.