build(agent): molt-y#23e5c8 iteration

README.md

@@ -1,25 +1,18 @@
-# CatOpt: Category-Theoretic Compositional Optimizer (MVP)
+# CatOpt: Category-Theoretic Compositional Optimization (MVP)
 
-CatOpt is a lightweight, open-source framework for privacy-preserving, compositional distributed optimization across edge meshes. The MVP emphasizes a minimal, well-structured surface built on category-theory abstractions, enabling edge-to-edge collaboration with offline resilience and vendor interoperability.
+This repository hosts a minimal MVP of CatOpt to verify packaging, imports,
+and a tiny API surface used by the test suite. The real project aims to provide
+a privacy-preserving, compositional distributed optimization framework built on
+category-theory abstractions. This readme documents the current MVP scope and
+how to extend it.
 
-What you get in this MVP
+- MVP surface: a simple add(a, b) function to validate packaging and imports.
-- Local problems expressed by agents (objects)
+- Packaging: aligned with pyproject.toml, using setuptools to build a wheel.
-- Data exchange channels (morphisms) and problem transformers (functors)
+- Extensibility: planned steps include a DSL for local problems, data contracts,
-- Global assembly via Limits/Colimits and a lightweight ADMM-like solver
+  an ADMM-like solver kernel, and adapters for edge devices.
-- Privacy-by-design data contracts and modular adapters
-- A tiny Python runtime surface suitable for rapid prototyping and CI validation
 
-Why this matters
+Usage
-- Composability: add/remove agents without re-deriving the global problem
+- Run tests and build: ./test.sh
-- Privacy: only exchanged, abstracted quantities per contracts
+- Import in Python:
-- Convergence: disciplined, modular solver structure with verifiable properties
+  from catopt_category_theoretic_compositional import add
-- Interoperability: bridges to existing energy/robotics ecosystems via a common DSL
+  assert add(2, 3) == 5
-
-Usage (quick start)
-- The core runtime primitives live in src/catopt_category_theoretic_compositional_/
-- The tiny DSL bridge to contracts lives in src/catopt_category_theoretic_compositional_/dsl.py
-- Importing and testing is kept simple to satisfy the CI gate (see tests/test_basic.py)
-
-For more details, see tests, the MVP runtime, and the protocol DSL (ProtocolContract, build_minimal_contract).
-
-This README is a starting point. As we evolve, we will add more examples, adapters, and end-to-end demos.

src/catopt_category_theoretic_compositional/__init__.py

@@ -1,4 +1,20 @@
-"""Minimal placeholder for CatOpt package (canonical path)."""
+"""CatOpt: Minimal MVP package
+
+This module provides a tiny, dependency-free API surface for the MVP
+of CatOpt used in the tests. The real project will expand this surface
+with category-theory abstractions and a solver; for now we expose a
+single utility function used by the test suite.
+"""
+
+from __future__ import annotations
+
+__all__ = ["add"]
+
 
 def add(a: int, b: int) -> int:
+    """Return the sum of two integers.
+
+    This tiny function is the minimal surface required by tests to verify
+    packaging and importability of the package.
+    """
     return a + b