From be6025632e025d0378f4f669cbd829929ae89817 Mon Sep 17 00:00:00 2001 From: agent-a6e6ec231c5f7801 Date: Tue, 21 Apr 2026 10:45:45 +0200 Subject: [PATCH] build(agent): new-agents#a6e6ec iteration --- .../__init__.py | 19 +++ .../governance.py | 134 ++++++++++++++++++ .../tests/test_governance.py | 43 ++++++ 3 files changed, 196 insertions(+) create mode 100644 mercurymesh_federated_reproducible_marke/governance.py create mode 100644 mercurymesh_federated_reproducible_marke/tests/test_governance.py diff --git a/mercurymesh_federated_reproducible_marke/__init__.py b/mercurymesh_federated_reproducible_marke/__init__.py index 84aa4f0..40d2bba 100644 --- a/mercurymesh_federated_reproducible_marke/__init__.py +++ b/mercurymesh_federated_reproducible_marke/__init__.py @@ -10,6 +10,16 @@ Public API (minimal): """ from .core import MarketStateSnapshot, SharedSignals, PlanDelta, AuditLog, FederatedCoordinator, LocalBook +from .governance import ( + FoundationModelBlock, + PlanningPolicyBlock, + PlanDeltaBlock, + DualVariablesBlock, + PrivacyBudgetBlock, + AuditLogBlock, + GoCEntry, + GoC_REGISTRY, +) from .registry import GraphOfContractsRegistry # type: ignore __all__ = [ @@ -20,4 +30,13 @@ __all__ = [ "LocalBook", "FederatedCoordinator", "GraphOfContractsRegistry", + # Governance primitives (minimal surface) + "FoundationModelBlock", + "PlanningPolicyBlock", + "PlanDeltaBlock", + "DualVariablesBlock", + "PrivacyBudgetBlock", + "AuditLogBlock", + "GoCEntry", + "GoC_REGISTRY", ] diff --git a/mercurymesh_federated_reproducible_marke/governance.py b/mercurymesh_federated_reproducible_marke/governance.py new file mode 100644 index 0000000..bd8618b --- /dev/null +++ b/mercurymesh_federated_reproducible_marke/governance.py @@ -0,0 +1,134 @@ +"""Governance primitives for MercuryMesh MVP. + +This module provides a small, production-friendly skeleton for cross-venue +governance components described in the long-term improvement plan. The goal +is to offer a minimal, well-typed representation that can be wired into the +existing FederatedCoordinator and the Graph-of-Contracts registry without +pulling in heavy dependencies. +""" + +from __future__ import annotations + +from dataclasses import dataclass, asdict +from typing import Dict, Any, Optional +import json + + +@dataclass +class FoundationModelBlock: + """High-level block describing a foundation model dependency or contract.""" + name: str + version: str + metadata: Optional[Dict[str, Any]] = None + + def to_dict(self) -> Dict[str, Any]: + return asdict(self) + + def to_json(self) -> str: + return json.dumps(self.to_dict()) + + +@dataclass +class PlanningPolicyBlock: + """Block describing planning policies (e.g., constraints, objectives).""" + policy_id: str + description: str + constraints: Dict[str, Any] + + def to_dict(self) -> Dict[str, Any]: + return asdict(self) + + def to_json(self) -> str: + return json.dumps(self.to_dict()) + + +@dataclass +class PlanDeltaBlock: + """Canonical PlanDelta representation for governance payloads.""" + plan_delta: PlanDelta + note: str = "" # optional human-readable note + + def to_dict(self) -> Dict[str, Any]: + return {"plan_delta": self.plan_delta.to_dict(), "note": self.note} + + def to_json(self) -> str: + return json.dumps(self.to_dict()) + + +@dataclass +class DualVariablesBlock: + """Represents a pair of dual variables for privacy/regularization budgets.""" + duals: Dict[str, float] + total_budget: float + + def to_dict(self) -> Dict[str, Any]: + return asdict(self) + + def to_json(self) -> str: + return json.dumps(self.to_dict()) + + +@dataclass +class PrivacyBudgetBlock: + """Block representing an application-level privacy/DP budget.""" + budgets: Dict[str, float] + global_budget: float + + def to_dict(self) -> Dict[str, Any]: + return asdict(self) + + def to_json(self) -> str: + return json.dumps(self.to_dict()) + + +@dataclass +class AuditLogBlock: + """Tamper-evident provenance micro-log for governance actions.""" + entry: str + signer: str + timestamp: str + contract_id: str + version: int + + def to_dict(self) -> Dict[str, Any]: + return asdict(self) + + def to_json(self) -> str: + return json.dumps(self.to_dict()) + + +@dataclass +class GoCEntry: + """GoC (Governance-on-Chain) compatible per-message metadata envelope.""" + name: str + version: str + timestamp: str + nonce: str + signer: str + payload: Dict[str, Any] + + def to_dict(self) -> Dict[str, Any]: + return asdict(self) + + def to_json(self) -> str: + return json.dumps(self.to_dict()) + + +class GoCRegistry: + """Tiny in-process registry for adapters/modules with governance metadata.""" + + def __init__(self) -> None: + self.adapters: Dict[str, GoCEntry] = {} + + def register_adapter(self, name: str, entry: GoCEntry) -> None: + self.adapters[name] = entry + + def get_adapter(self, name: str) -> Optional[GoCEntry]: + return self.adapters.get(name) + + def list_adapters(self) -> Dict[str, GoCEntry]: + return dict(self.adapters) + + +# Lightweight default registry instance for quick MVP wiring +GoC_REGISTRY = GoCRegistry() diff --git a/mercurymesh_federated_reproducible_marke/tests/test_governance.py b/mercurymesh_federated_reproducible_marke/tests/test_governance.py new file mode 100644 index 0000000..dc29b99 --- /dev/null +++ b/mercurymesh_federated_reproducible_marke/tests/test_governance.py @@ -0,0 +1,43 @@ +import json +from mercurymesh_federated_reproducible_marke.governance import ( + FoundationModelBlock, + PlanningPolicyBlock, + PlanDeltaBlock, + DualVariablesBlock, + PrivacyBudgetBlock, + AuditLogBlock, + GoCEntry, + GoC_REGISTRY, + GoCRegistry, +) +from mercurymesh_federated_reproducible_marke.core import PlanDelta + + +def test_governance_blocks_serialization(): + fmb = FoundationModelBlock(name="FoundationX", version="0.1.0", metadata={"opt": True}) + pb = PlanningPolicyBlock("pol-1", "example policy", {"max_steps": 100}) + delta = PlanDelta({"A": 1.0}, "2026-01-01T00:00:00Z", "tester", "root", 0.0) + pdb = PlanDeltaBlock(delta, note="phase0") + dvar = DualVariablesBlock({"lambda": 0.5}, 1.0) + pbudget = PrivacyBudgetBlock({"A": 0.1}, 1.0) + alog = AuditLogBlock("delta_applied", "tester", "2026-01-01T00:00:00Z", "root", 1) + assert fmb.to_json() + assert pb.to_json() + assert pdb.to_json() + assert dvar.to_json() + assert pbudget.to_json() + assert alog.to_json() + +def test_goc_registry_basic(): + entry = GoCEntry( + name="adapter-a", + version="v0.1", + timestamp="2026-01-01T00:00:00Z", + nonce="abc123", + signer="tester", + payload={"foo": "bar"}, + ) + GoC_REGISTRY.register_adapter("adapter-a", entry) + assert GoC_REGISTRY.get_adapter("adapter-a") is not None + # ensure serializable + assert entry.to_json()