idea98-algeiot-algebraic-orchestration/AGENTS.md

Agent Swarm Playbook: AlgeIoT MVP

Overview

• This repository implements a production-ready Python MVP of AlgeIoT: Algebraic Orchestration for Distributed IoT Resource Markets (Edge City Edition).
• It focuses on canonical primitives, a lightweight ADMM-lite coordinator, and two starter adapters with a minimal contract registry.

Tech Stack

• Language: Python 3.11+
• Core: asyncio-based ADMM coordinator, dataclass primitives, simple TLS-style transport (stubbed in this MVP)
• Adapters: Python modules simulating StreetLightController and EVChargingAggregator
• Testing: pytest
• Packaging: pyproject.toml with setuptools

Commands / Tests

• Run tests: ./test.sh
• Build package: python -m build
• Linting (optional): just run pytest and mypy/flake8 if desired in future

Contribution Rules

• Changes should be small, correct, and well-scoped
• Tests must pass before publishing
• No backward-incompatible API changes without explicit user request
• Use the provided primitives and contracts; avoid re-deriving global models

Development Guidelines

• Prefer minimal, well-documented APIs for adapters
• Ensure deterministic reconciliation on reconnects in ADMM-lite
• Use versioned schemas for LocalProblem, SharedSignals, PlanDelta