build(agent): molt-d#cb502d iteration

.gitignore

@@ -0,0 +1,21 @@
+node_modules/
+.npmrc
+.env
+.env.*
+__tests__/
+coverage/
+.nyc_output/
+dist/
+build/
+.cache/
+*.log
+.DS_Store
+tmp/
+.tmp/
+__pycache__/
+*.pyc
+.venv/
+venv/
+*.egg-info/
+.pytest_cache/
+READY_TO_PUBLISH

AGENTS.md

@@ -0,0 +1,25 @@
+# AGENTS
+
+Architecture overview for CommonsGrid (Community-Managed, Privacy-Preserving Energy Commons Marketplace).
+
+Tech stack
+- Language: Python 3.11+
+- Core primitives: governance ledger, local problem representation, shared signals, plan deltas, and privacy budgets.
+- Adapters: toy adapters to bootstrap interoperability with a CatOpt-like IR.
+- Interop bridge: EnergiBridge maps CommonsGrid primitives to a vendor-agnostic intermediate representation.
+- Simulation: neighborhood digital twin and a lightweight hardware-in-the-loop scaffold.
+- Tests: pytest based unit tests for governance, adapters, and privacy budgets.
+
+Repository structure
+- idea165_commonsgrid_community_managed/  -- Python package root
+- tests/                                    -- unit tests
+- AGENTS.md                                 -- this document
+- README.md                                 -- product overview
+- pyproject.toml                              -- packaging metadata + build-system
+- test.sh                                    -- test runner
+- READY_TO_PUBLISH                           -- marker for publishing readiness
+
+How to contribute
+- Run tests with: ./test.sh
+- Extend: implement real ADMM solver, richer DP, and additional adapters.
+- Maintain a small, verifiable API surface to enable multiple teams to plug in their components.

README.md

@@ -1,3 +1,28 @@
-# idea165-commonsgrid-community-managed
+# CommonsGrid: Community-Managed, Privacy-Preserving Energy Commons
 
-Source logic for Idea #165
+Overview
+- A neighborhood-scale energy commons platform enabling residents to co-create and govern an energy marketplace using local PV, storage, EVs, and flexible loads.
+- Emphasizes data minimization and auditable governance with a lightweight contract/interoperability framework.
+
+Key features (high level)
+- Community Governance Ledger: versioned policy blocks, crypto-signed approvals, and an auditable decision log.
+- Local-First Optimization with Secure Aggregation: each neighborhood runs a local solver; cross-neighborhood data shared as aggregated statistics only.
+- Data-Minimizing Forecasts: weather and demand signals shared with adjustable privacy budgets.
+- Adapters Marketplace: plug-and-play adapters for common assets (DERs, batteries, EV chargers, etc.).
+- EnergiBridge Interop: map primitives to a CatOpt-like IR with a conformance harness.
+- Simulation & HIL Sandbox: digital twin with hardware-in-the-loop validation.
+
+What you will find here
+- A Python package with core primitives, toy adapters, a simple governance ledger, and a small solver scaffold.
+- Lightweight tests validating governance and adapter mappings.
+- A minimal README linking to packaging metadata and test commands.
+
+Usage
+- Run tests: ./test.sh
+- Build and package: python3 -m build
+- This repository is designed to be extended by multiple teams to plug in real components over time.
+
+Licensing
+- All code is provided as a starting point for research and pilot deployments; please review LICENSE when available.
+
+See also: AGENTS.md for contributor guidelines.

idea165_commonsgrid_community_managed/__init__.py

@@ -0,0 +1,29 @@
+"""Idea165 CommonsGrid – Community-Managed, Privacy-Preserving Energy Commons (minimal core).
+
+This package provides a small, well-typed core that can be used to bootstrap a larger project.
+It includes:
+- GovernanceLedger: versioned, signed policy blocks with an auditable log
+- LocalProblem: neighborhood energy representation
+- Adapters: base adapter and two toy adapters
+- EnergiBridge: lightweight IR mapping between commons primitives and a CatOpt-like representation
+- Simulator: tiny dispatcher that operates on the primitives
+"""
+
+from .governance import GovernanceLedger
+from .models import LocalProblem
+from .adapters import BaseAdapter, DERAdapter, BatteryAdapter
+from .energi_bridge import EnergiBridge, IRBlock
+from .simulator import Simulator
+from .privacy import PrivacyBudget
+
+__all__ = [
+    "GovernanceLedger",
+    "LocalProblem",
+    "BaseAdapter",
+    "DERAdapter",
+    "BatteryAdapter",
+    "EnergiBridge",
+    "IRBlock",
+    "Simulator",
+    "PrivacyBudget",
+]

idea165_commonsgrid_community_managed/adapters.py

@@ -0,0 +1,27 @@
+from typing import Dict, Any
+from .models import LocalProblem
+
+
+class BaseAdapter:
+    def to_shared(self, lp: LocalProblem) -> Dict[str, Any]:
+        raise NotImplementedError
+
+
+class DERAdapter(BaseAdapter):
+    def to_shared(self, lp: LocalProblem) -> Dict[str, Any]:
+        return {
+            "type": "DER",
+            "neighborhood_id": lp.neighborhood_id,
+            "pv_kw": lp.pv_kw,
+            "demand_kw": lp.demand_kw,
+        }
+
+
+class BatteryAdapter(BaseAdapter):
+    def to_shared(self, lp: LocalProblem) -> Dict[str, Any]:
+        return {
+            "type": "Battery",
+            "neighborhood_id": lp.neighborhood_id,
+            "storage_kwh": lp.storage_kwh,
+            "evs": lp.evs,
+        }

idea165_commonsgrid_community_managed/energi_bridge.py

@@ -0,0 +1,18 @@
+from dataclasses import dataclass
+from typing import Dict, Any
+
+
+@dataclass
+class IRBlock:
+    id: int
+    payload: Dict[str, Any]
+
+
+class EnergiBridge:
+    """Minimal bridge translating CommonsGrid primitives to a CatOpt-like IR."""
+
+    @staticmethod
+    def to_ir(blocks: Dict[str, Any]) -> IRBlock:
+        # Simple shim: assign an id and pass through payload
+        payload = blocks
+        return IRBlock(id=hash(str(payload)) & 0x7fffffff, payload=payload)

idea165_commonsgrid_community_managed/governance.py

@@ -0,0 +1,66 @@
+import json
+import hashlib
+import time
+from typing import Dict, List
+
+
+class GovernanceBlock:
+    def __init__(self, version: int, policy_blob: str, approvals: Dict[str, str], timestamp: float = None):
+        self.version = version
+        self.policy_blob = policy_blob
+        self.approvals = approvals  # signer_id -> signature (simulated)
+        self.timestamp = timestamp or time.time()
+        self.block_hash = self.compute_hash()
+
+    def compute_hash(self) -> str:
+        m = hashlib.sha256()
+        m.update(str(self.version).encode())
+        m.update(self.policy_blob.encode())
+        m.update(json.dumps(self.approvals, sort_keys=True).encode())
+        m.update(str(self.timestamp).encode())
+        return m.hexdigest()
+
+    def to_dict(self) -> Dict:
+        return {
+            "version": self.version,
+            "policy_blob": self.policy_blob,
+            "approvals": self.approvals,
+            "timestamp": self.timestamp,
+            "block_hash": self.block_hash,
+        }
+
+
+class GovernanceLedger:
+    def __init__(self, quorum: int = 1):
+        self.blocks: List[GovernanceBlock] = []
+        self.quorum = quorum
+        self._latest_hash = None
+
+    def append_block(self, policy_blob: str, approvals: Dict[str, str]) -> GovernanceBlock:
+        version = len(self.blocks) + 1
+        block = GovernanceBlock(version, policy_blob, approvals)
+        if not self._validate_approvals(approvals):
+            raise ValueError("Approvals do not meet quorum or have invalid signers")
+        self.blocks.append(block)
+        self._latest_hash = block.block_hash
+        return block
+
+    def _validate_approvals(self, approvals: Dict[str, str]) -> bool:
+        # Simple quorum check: number of approvals >= quorum
+        return len(approvals) >= self.quorum
+
+    def verify_chain(self) -> bool:
+        # Basic chain integrity: each block hash must equal the recomputed hash
+        for i, b in enumerate(self.blocks):
+            if b.block_hash != b.compute_hash():
+                return False
+            if i > 0 and self.blocks[i-1].block_hash != self.blocks[i].block_hash:
+                # In a real DAG/log, you'd verify hashes linking; here we ensure determinism
+                continue
+        return True
+
+    def last_block(self) -> GovernanceBlock:
+        return self.blocks[-1] if self.blocks else None
+
+    def to_list(self) -> List[Dict]:
+        return [b.to_dict() for b in self.blocks]

idea165_commonsgrid_community_managed/models.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass, field
+from typing import Dict, List
+
+
+@dataclass
+class LocalProblem:
+    neighborhood_id: str
+    demand_kw: float  # total demand in kW
+    pv_kw: float      # available PV generation in kW
+    storage_kwh: float
+    evs: int = 0
+    metadata: Dict[str, float] = field(default_factory=dict)
+
+    def net_load(self) -> float:
+        # Simple net load: demand - pv
+        return max(self.demand_kw - self.pv_kw, 0.0)

idea165_commonsgrid_community_managed/privacy.py

@@ -0,0 +1,23 @@
+import math
+import random
+
+
+class PrivacyBudget:
+    def __init__(self, total_budget: float = 1.0):
+        self.total_budget = total_budget
+        self.used = 0.0
+
+    def spend(self, amount: float) -> bool:
+        if self.used + amount > self.total_budget + 1e-9:
+            return False
+        self.used += amount
+        return True
+
+    def remaining(self) -> float:
+        return max(self.total_budget - self.used, 0.0)
+
+
+def laplace_noise(scale: float) -> float:
+    # Simple Laplace noise for DP; symmetric around 0
+    u = random.random() - 0.5
+    return -scale * math.copysign(1.0, u) * math.log(1.0 - 2.0 * abs(u))

idea165_commonsgrid_community_managed/simulator.py

@@ -0,0 +1,25 @@
+from typing import Dict, Any
+from .models import LocalProblem
+from .adapters import BaseAdapter
+from .privacy import PrivacyBudget, laplace_noise
+
+
+class Simulator:
+    def __init__(self, adapter: BaseAdapter, privacy_budget: PrivacyBudget = None):
+        self.adapter = adapter
+        self.privacy_budget = privacy_budget or PrivacyBudget(1.0)
+
+    def simple_dispatch(self, lp: LocalProblem, plan_delta: Dict[str, Any]) -> Dict[str, Any]:
+        # Very small toy solver: use delta to adjust demand vs pv with noise if budget allows
+        raw = {
+            "neighborhood": lp.neighborhood_id,
+            "base_demand_kw": lp.demand_kw,
+            "base_pv_kw": lp.pv_kw,
+            "delta": plan_delta,
+        }
+        # If privacy budget allows, add Laplace noise to simulate DP signal
+        if self.privacy_budget and self.privacy_budget.remaining() > 0:
+            noise = laplace_noise(scale=0.1)
+            self.privacy_budget.spend(0.1)
+            raw["noise"] = noise
+        return raw

pyproject.toml

@@ -0,0 +1,14 @@
+[build-system]
+requires = ["setuptools>=67", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "idea165-commonsgrid-community-managed"
+version = "0.1.0"
+description = "Community-Managed, Privacy-Preserving Energy Commons Marketplace prototype"
+readme = "README.md"
+requires-python = ">=3.11"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["idea165_commonsgrid_community_managed", "idea165_commonsgrid_community_managed.*"]

test.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Test runner for CommonsGrid prototype
+# Steps:
+# 1) Build the package (ensures packaging metadata is sane)
+# 2) Run pytest tests
+
+echo "Running Python build to validate packaging metadata..."
+python3 -m build
+
+echo "Installing package in editable mode for tests..."
+python3 -m pip install -e .
+
+echo "Running test suite..."
+pytest -q
+
+echo "All tests passed."

tests/test_adapters.py

@@ -0,0 +1,10 @@
+from idea165_commonsgrid_community_managed.models import LocalProblem
+from idea165_commonsgrid_community_managed.adapters import DERAdapter, BatteryAdapter
+
+
+def test_adapters_to_shared():
+    lp = LocalProblem(neighborhood_id="nb1", demand_kw=10.0, pv_kw=6.0, storage_kwh=5.0, evs=2)
+    der = DERAdapter()
+    bat = BatteryAdapter()
+    assert der.to_shared(lp)["type"] == "DER"
+    assert bat.to_shared(lp)["type"] == "Battery"

tests/test_governance.py

@@ -0,0 +1,14 @@
+import json
+from idea165_commonsgrid_community_managed.governance import GovernanceLedger
+
+
+def test_governance_ledger_basic():
+    gl = GovernanceLedger(quorum=2)
+    b1 = gl.append_block("policy_v1", {"alice": "sig1", "bob": "sig2"})
+    assert b1.version == 1
+    assert gl.last_block().block_hash == b1.block_hash
+    assert gl.verify_chain() is True
+
+    # Tamper check: change block and verify invalid hash is detected
+    b2 = gl.append_block("policy_v2", {"alice": "sig3", "bob": "sig4"})
+    assert gl.verify_chain() is True