# CatOpt-Swarm

CatOpt-Swarm is a validated Python package for safe distributed swarm optimization.
It models robot tasks, contract-tagged deltas, and mission policies in a canonical IR,
then runs a deterministic ADMM-lite coordinator with verification hooks.

## Core Concepts

- `LocalProblem` captures each robot's objective, state, and local limits.
- `PlanDelta` carries contract-tagged updates with sequence and base-version replay guards.
- `SharedVariables` tracks consensus, versioning, and applied sequence state.
- `SafetyPolicy` enforces travel distance, separation, and energy limits.
- `ContractRegistry` stores adapter contracts in a graph and supports conformance checks.

## Behavior

- Deterministic delta ordering and bounded-staleness replay control
- Separation projection to keep robots apart during updates
- Audit logs and convergence certificates per solve
- Verification of consensus consistency, energy budgets, and trace continuity
- Adapter shims for aerial and ground controllers

## Layout

- `catopt_swarm.models`
- `catopt_swarm.registry`
- `catopt_swarm.adapters`
- `catopt_swarm.solver`
- `catopt_swarm.verification`
- `catopt_swarm.cli`

## Install

```bash
python3 -m pip install -e .
```

## Run

```bash
python3 -m catopt_swarm.cli
```

Compatibility entrypoints:

```bash
python3 admm_solver.py
python3 solver.py
```

## Test

```bash
bash test.sh
```

## Demo Coverage

- Two-robot consensus planning
- Adapter conformance checks for aerial and ground controllers
- Graph-based contract registration
- Safety verification after solve
- Delta replay and version tracking

## Status

This repository now covers the core planning, contract, and verification substrate.
ROS/Gazebo integration and richer mission templates remain natural next steps.