build(agent): new-agents-2#7e3bbc iteration

AGENTS.md

@@ -19,3 +19,13 @@ Guidance for contributors
 - Do not change the MVP skeleton without explicit intent to expand functionality.
 - Ensure test.sh remains executable and tests cover basic import/build scenarios.
 - Update AGENTS.md as the architecture evolves.
+
+New MVP scaffolds (current status):
+- Added lightweight DSL primitives (src/catopt_category_theoretic_compositional/dsl.py)
+- Added minimal contracts primitives (src/catopt_category_theoretic_compositional/contracts.py)
+- Added a tiny solver kernel (src/catopt_category_theoretic_compositional/solver.py)
+- Exposed new API in package __init__ (LocalProblem, SharedVariables, PlanDelta, admm_update)
+
+How to explore:
+- Import surface: from catopt_category_theoretic_compositional import LocalProblem, SharedVariables, PlanDelta, admm_update
+- Use admm_update(local, shared) as a tiny, deterministic update example.

src/catopt_category_theoretic_compositional/__init__.py

@@ -8,7 +8,10 @@ single utility function used by the test suite.
 
 from __future__ import annotations
 
-__all__ = ["add"]
+from .dsl import LocalProblem, SharedVariables, PlanDelta
+from .solver import admm_update
+
+__all__ = ["add", "LocalProblem", "SharedVariables", "PlanDelta", "admm_update"]
 
 
 def add(a: int, b: int) -> int:

src/catopt_category_theoretic_compositional/contracts.py

@@ -1,90 +1,62 @@
-"""CatOpt Contracts: Minimal primitives for Local Problems and exchanges.
+"""Contracts: lightweight data-contract primitives for CatOpt (minimal).
 
-This module provides lightweight dataclasses that sketch the API surface
+These dataclasses are intentionally small and import-time friendly to keep
-for CatOpt's data contracts. The goal is to be expressive enough for MVP wiring
+the MVP stable while enabling eventual extensions for privacy contracts,
-without pulling in heavy dependencies.
+audits, and governance.
 """
 
 from __future__ import annotations
 
-from dataclasses import dataclass, asdict
+from dataclasses import dataclass, asdict, field
-from typing import Any, Dict, List, Optional
+from typing import Dict, Optional
 import json
 
 
 @dataclass
-class LocalProblem:
+class LocalProblemContract:
-    """Represents a device-level optimization problem.
+    id: str
-
+    domain: str
-    - variables: a map of decision variables and their current values/roles
+    objective: str
-    - objective: a serializable representation of the local objective
+    constraints: list[str]
-    - constraints: list of constraints (expressions or callables in a real system)
-    - privacy_preferences: optional hints for privacy-preserving exchanges
-    """
-
-    variables: Dict[str, Any]
-    objective: Any
-    constraints: List[Any]
-    privacy_preferences: Optional[Dict[str, Any]] = None
 
     def to_json(self) -> str:
-        return json.dumps(asdict(self), default=str)
+        return json.dumps(asdict(self))
+
+    @classmethod
+    def from_json(cls, payload: str) -> "LocalProblemContract":
+        data = json.loads(payload)
+        return cls(id=data["id"], domain=data.get("domain", ""), objective=data.get("objective", ""), constraints=data.get("constraints", []))
 
 
 @dataclass
-class SharedVariables:
+class SharedVariablesContract:
-    """Variables shared across agents for coordination (e.g., aggregates)."""
-
-    variables: Dict[str, Any]
     version: int
-    contract_id: str
+    contract_id: Optional[str] = None
-    encryption_schema: Optional[str] = None
+    payload: Dict[str, float] = field(default_factory=dict)
 
     def to_json(self) -> str:
-        return json.dumps(asdict(self), default=str)
+        return json.dumps(asdict(self))
+
+    @classmethod
+    def from_json(cls, payload: str) -> "SharedVariablesContract":
+        data = json.loads(payload)
+        return cls(version=data["version"], contract_id=data.get("contract_id"), payload=data.get("payload", {}))
 
 
 @dataclass
-class DualVariables:
+class PlanDeltaContract:
-    """Lagrange-like multipliers used in coordination."""
+    delta: Dict[str, float]
-
+    timestamp: str
-    multipliers: Dict[str, float]
-
-    def to_json(self) -> str:
-        return json.dumps(asdict(self), default=str)
-
-
-@dataclass
-class PlanDelta:
-    """Proposed updates to the local problem in a delta-sync step."""
-
-    delta: Dict[str, Any]
-    timestamp: float
     author: str
-    contract_id: str
+    contract_id: Optional[str] = None
-    privacy_budget: Optional[Dict[str, Any]] = None
-    proofs: Optional[List[str]] = None
 
     def to_json(self) -> str:
-        return json.dumps(asdict(self), default=str)
+        return json.dumps(asdict(self))
+
+    @classmethod
+    def from_json(cls, payload: str) -> "PlanDeltaContract":
+        data = json.loads(payload)
+        return cls(delta=data["delta"], timestamp=data["timestamp"], author=data["author"], contract_id=data.get("contract_id"))
 
 
-@dataclass
+__all__ = ["LocalProblemContract", "SharedVariablesContract", "PlanDeltaContract"]
-class AuditLog:
-    """Immutable-ish audit log for governance and replay protection."""
-
-    entries: List[Dict[str, Any]]
-
-    def to_json(self) -> str:
-        return json.dumps(asdict(self), default=str)
-
-
-@dataclass
-class PolicyBlock:
-    """Safety and data-exposure policy block attached to exchanges."""
-
-    safety_constraints: List[str]
-    data_exposure_rules: List[str]
-
-    def to_json(self) -> str:
-        return json.dumps(asdict(self), default=str)

src/catopt_category_theoretic_compositional/dsl.py

@@ -0,0 +1,69 @@
+"""CatOpt DSL primitives (minimal MVP scaffolding).
+
+This module provides lightweight, serializable representations for the local
+optimization problems and exchange artifacts that participate in the
+CatOpt protocol. It is intentionally small but stable to enable safe expansion
+in future iterations.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, asdict
+from typing import Dict, List, Optional
+import json
+
+
+@dataclass
+class LocalProblem:
+    id: str
+    domain: str
+    objective: str
+    constraints: List[str] = field(default_factory=list)
+    variables: Optional[Dict[str, float]] = None
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self))
+
+    @classmethod
+    def from_json(cls, payload: str) -> "LocalProblem":
+        data = json.loads(payload)
+        return cls(
+            id=data["id"],
+            domain=data.get("domain", "unknown"),
+            objective=data.get("objective", ""),
+            constraints=data.get("constraints", []),
+            variables=data.get("variables"),
+        )
+
+
+@dataclass
+class SharedVariables:
+    version: int
+    signals: Dict[str, float] = field(default_factory=dict)
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self))
+
+    @classmethod
+    def from_json(cls, payload: str) -> "SharedVariables":
+        data = json.loads(payload)
+        return cls(version=data["version"], signals=data.get("signals", {}))
+
+
+@dataclass
+class PlanDelta:
+    delta: Dict[str, float]
+    timestamp: str
+    author: str
+    contract_id: Optional[str] = None
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self))
+
+    @classmethod
+    def from_json(cls, payload: str) -> "PlanDelta":
+        data = json.loads(payload)
+        return cls(delta=data["delta"], timestamp=data["timestamp"], author=data["author"], contract_id=data.get("contract_id"))
+
+
+__all__ = ["LocalProblem", "SharedVariables", "PlanDelta"]

src/catopt_category_theoretic_compositional/solver.py

@@ -1,37 +1,41 @@
-"""Tiny ADMM-inspired solver placeholder for CatOpt MVP."""
+"""A tiny, placeholder ADMM-like solver kernel for CatOpt MVP.
+
+This module provides a minimal function that demonstrates an update step
+between a LocalProblem (DSL) and SharedVariables (contracts). The logic is
+deliberately simple to keep the MVP stable while offering a hook for future
+expansion.
+"""
 
 from __future__ import annotations
 
-from typing import Dict, Any, Tuple
+from typing import Dict
-
+from .dsl import LocalProblem, SharedVariables
-from .contracts import LocalProblem, SharedVariables, DualVariables
 
 
-def admm_step(local: LocalProblem, shared: SharedVariables, dual: DualVariables) -> Tuple[LocalProblem, SharedVariables, DualVariables]:
+def admm_update(local: LocalProblem, shared: SharedVariables, rho: float = 1.0) -> LocalProblem:
-    """Perform a toy ADMM step.
+    """Perform a tiny, deterministic ADMM-like update of a local problem.
 
-    This is a non-production placeholder that demonstrates the kind of update
+    This is a stub implementation intended for demonstration and testing. It
-    you would wire into the MVP. It does not solve the problem; it simply
+    updates a simple primal variable if present, otherwise initializes it.
-    demonstrates structure and state transitions for local and shared data.
     """
-    # Very naive placeholder: push a tiny, deterministic adjustment to a variable
+    # Copy local to avoid mutating input (functional style).
-    # indicating progress in coordination. In a real solver, you'd compute proximal
+    updated = LocalProblem(
-    # updates, dual ascent steps, and consensus enforcement here.
+        id=local.id,
-    if local.variables:
+        domain=local.domain,
-        key = next(iter(local.variables))
+        objective=local.objective,
-        val = local.variables[key]
+        constraints=list(local.constraints),
-        try:
+        variables=dict(local.variables) if local.variables is not None else {},
-            local.variables[key] = val  # no-op baseline; real code would update
+    )
-        except Exception:
-            pass
 
-    # Update a dummy shared signal (e.g., a mean of a shared variable)
+    # Simple, deterministic update to a hypothetical primal variable.
-    for k, v in list(shared.variables.items()):
+    primal = 0.0
-        if isinstance(v, (int, float)):
+    if not isinstance(updated.variables, dict):
-            shared.variables[k] = v * 1.0  # no change; placeholder
+        updated.variables = {}
+    if isinstance(updated.variables, dict):
+        primal = updated.variables.get("primal", 0.0)
+    updated.variables["primal"] = primal + 0.5 * rho
 
-    # Update duals trivially
+    return updated
-    for k in list(dual.multipliers.keys()):
-        dual.multipliers[k] = dual.multipliers[k]
 
-    return local, shared, dual
+
+__all__ = ["admm_update"]