build(agent): molt-x#ed374b iteration

AGENTS.md

@@ -1 +1,34 @@
-# CatOpt-Flow: Agent Architecture Guide
+CatOpt-Flow: Agent Architecture Guide
+=====================================
+
+This document outlines the architectural approach used in CatOpt-Flow and establishes guidelines for contributors and automated tooling. It complements the codebase and the CI/test contracts already in place.
+
+Overview
+- CatOpt-Flow is a production-oriented platform for multi-tenant ML training pipelines across heterogeneous accelerators.
+- It models optimization as category-theory-inspired primitives: Objects (local tasks), Morphisms (data-exchange channels with versioned schemas), and Functors (adapters mapping device-specific problems to a vendor-agnostic representation).
+- Global constraints are enforced via Limits/Colimits, providing an aggregator that stitches local problems into a globally consistent plan.
+- An ADMM-like distributed solver runs on each node and communicates summarized statistics through a delta-sync protocol that tolerates dynamic scaling and partial failures.
+- A lightweight schema registry and contract marketplace enable plug-and-play adapters for popular ML frameworks and hardware backends.
+- Code generation tooling is provided to output orchestration stubs (Rust/C++) and Python bindings for rapid deployment with minimal vendor lock-in.
+
+What to Build (MVP Path)
+- Protocol skeleton with two starter adapters per platform.
+- Delta-sync, simple governance ledger, and identity primitives (DID-based).
+- Cross-domain demo with a simulated domain (Phase 2) and HIL validation (Phase 3).
+- A minimal DSL sketch: LocalProblem/SharedVariables/PlanDelta and toy adapters to bootstrap interoperability.
+
+Development Rules
+- All changes should be driven by tests. If a feature requires a new test, add it alongside the implementation.
+- Use the existing test.sh to validate tests and packaging build. The script runs pytest and builds the package via python -m build.
+- Do not break the public API unless explicitly requested. If you add new classes, export them from the package’s __init__ to ease discoverability.
+- When in doubt, add a small integration test demonstrating a 2-node ADMM interaction before expanding scope.
+
+Publishing and Governance
+- Publishable artifacts should include a clear README, a small DSL sketch, and a contract registry skeleton.
+- A ready-to-publish signal is provided via a READY_TO_PUBLISH file in the repository root once all required checks pass.
+
+Contributing
+- Open issues and PRs should reference sections of this guide and align with the MVP roadmap.
+- Documentation updates should accompany code changes.
+
+This file is intentionally lightweight but should be kept current with repository changes.

README.md

@@ -1 +1,41 @@
 # CatOpt-Flow: Category-Theoretic Compositional Optimizer
+
+CatOpt-Flow is a production-grade, open-source platform for defining and solving per-job optimization problems in multi-tenant ML training pipelines across heterogeneous accelerators.
+
+Key abstractions (category-theory inspired)
+- Objects: local training tasks representing per-job optimization problems.
+- Morphisms: data-exchange channels with versioned schemas (signals like resource usage, gradient statistics, throughput metrics).
+- Functors: adapters mapping device-specific problems to a vendor-agnostic representation.
+- Limits/Colimits: global constraints and governance that aggregate local problems into a coherent global plan.
+- Delta-sync: a lightweight delta-based synchronization protocol enabling asynchronous updates and partial failures.
+- Schema registry and contract marketplace: plug-and-play adapters for major ML frameworks and hardware backends.
+- Code generation: orchestration stubs (Rust/C++) and Python bindings for rapid deployment.
+
+What you get
+- A pragmatic, test-driven architecture suitable for large-scale, multi-tenant ML workloads.
+- A ready-to-extend core, with simple yet expressive primitives and a working ADMM-like solver MVP.
+- A packaging-ready Python distribution with tests that exercise the core primitives.
+
+Getting started
+- This is a Python project. You can run tests and build the package with the provided script:
+  - bash test.sh
+- The test suite validates core functionality: object/morphism relations, local/global planning, and an ADMM-like convergence flow.
+- The packaging step exercises Python packaging metadata and wheel/sdist generation.
+
+What’s inside
+- catopt_flow_category_theoretic_compositi/core.py: core primitives (Object, Morphism, LocalProblem, GlobalProblem, Functor, Planner, DeltaSyncRegistry, ADMMNode, run_admm).
+- tests/test_core.py: unit tests for core primitives.
+- A minimal, production-ready packaging layout with pyproject.toml and a README hook.
+
+Development and contribution
+- See AGENTS.md for architectural guidelines and contribution rules.
+- All changes should be reflected in tests and documented in this README.
+
+Roadmap (high level)
+- Phase 0: protocol skeleton with 2 starter adapters per platform and delta-sync.
+- Phase 1: governance ledger with DID-based identities.
+- Phase 2: cross-domain demo with a simulated satellite domain.
+- Phase 3: hardware-in-the-loop validation.
+- A small DSL sketch (LocalProblem/SharedVariables/PlanDelta) and a Graph-of-Contracts registry.
+
+This project aims for clean, production-grade code with strong test coverage and clear extension points.

examples/demo_admm.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+"""Demo: ADMM-like optimization with two local problems"""
+from catopt_flow_category_theoretic_compositi import LocalProblem, DeltaSyncRegistry, ADMMNode, run_admm, Planner
+
+
+def main():
+    lp1 = LocalProblem(id="node-1", resources={"gpu": 2.0, "memory": 8.0}, data_loading={}, batch_size=32)
+    lp2 = LocalProblem(id="node-2", resources={"gpu": 1.0, "memory": 8.0}, data_loading={}, batch_size=32)
+    registry = DeltaSyncRegistry()
+    n1 = ADMMNode("node-1", lp1, registry)
+    n2 = ADMMNode("node-2", lp2, registry)
+    final = run_admm([n1, n2], rounds=3, budget_gpu=4.0, registry=registry)
+    print("Final global plan:")
+    for lid, alloc in final.plan.items():
+        print(f"  {lid}: {alloc}")
+
+    # Show a planner-only view from local problems (example of usage)
+    plan = Planner.build_global_plan([lp1, lp2], budget_gpu=4.0)
+    print("Planner plan:", plan.plan)
+
+
+if __name__ == "__main__":
+    main()