Skip to content

Commit 2da5262

Browse files
sorydimasorydima
committed
Initial commit ..
1 parent d8b51e6 commit 2da5262

47 files changed

Lines changed: 4164 additions & 2 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
pull_request:
7+
branches: [ main ]
8+
9+
jobs:
10+
rust:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
- uses: dtolnay/rust-toolchain@stable
15+
with:
16+
components: clippy, rustfmt
17+
- name: Cache cargo
18+
uses: actions/cache@v3
19+
with:
20+
path: |
21+
~/.cargo/registry
22+
~/.cargo/git
23+
target
24+
key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
25+
- name: Check formatting
26+
run: cargo fmt --check
27+
- name: Clippy
28+
run: cargo clippy -- -D warnings
29+
- name: Build
30+
run: cargo build --all-features
31+
- name: Run tests
32+
run: cargo test --all-features
33+
34+
python:
35+
runs-on: ubuntu-latest
36+
steps:
37+
- uses: actions/checkout@v4
38+
- uses: actions/setup-python@v5
39+
with:
40+
python-version: '3.10'
41+
- name: Install maturin
42+
run: pip install maturin
43+
- name: Build Python bindings
44+
run: cd python && maturin develop
45+
- name: Run Python tests (if any)
46+
run: cd python && python -c "import offline_first_autonomy; print('Module loaded successfully')"

‎ARCHITECTURE.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Architecture Overview
2+
3+
## Vision
4+
Offline-First Multi-Agent Autonomy SDK enables a group of robots to operate collaboratively without a central server, using local state machines, conflict‑free replicated data types (CRDTs) for state synchronization, opportunistic mesh networking, and bounded consensus.
5+
6+
## Core Principles
7+
1. **Offline‑first** – Every agent remains fully functional when disconnected.
8+
2. **Decentralized** – No single point of failure; peer‑to‑peer communication.
9+
3. **Eventually consistent** – State converges across the swarm via CRDTs.
10+
4. **Resource‑aware** – Agents monitor and adapt to local constraints (CPU, battery, bandwidth).
11+
5. **Pluggable transport** – Support for various network layers (Wi‑Fi, Bluetooth, LoRa, etc.).
12+
13+
## High‑Level Architecture
14+
15+
```mermaid
16+
graph TB
17+
subgraph "Agent Node"
18+
AC[Agent Core]
19+
LP[Local Planner]
20+
SS[State Sync CRDT]
21+
MT[Mesh Transport]
22+
RM[Resource Monitor]
23+
24+
AC --> LP
25+
AC --> SS
26+
AC --> MT
27+
AC --> RM
28+
SS --> MT
29+
MT --> SS
30+
end
31+
32+
subgraph "Swarm"
33+
N1[Agent 1]
34+
N2[Agent 2]
35+
N3[Agent 3]
36+
N1 -- Mesh Network --> N2
37+
N2 -- Mesh Network --> N3
38+
N3 -- Mesh Network --> N1
39+
end
40+
41+
subgraph "External"
42+
SIM[Simulation Gazebo/ROS2]
43+
CLI[Python CLI]
44+
SIM --> AC
45+
CLI --> AC
46+
end
47+
```
48+
49+
## Component Responsibilities
50+
51+
### 1. Mesh Transport
52+
- **Purpose**: Reliable, unordered, peer‑to‑peer message passing over ad‑hoc networks.
53+
- **Features**:
54+
- Discovery (mDNS, manual peer list)
55+
- Connection management (TCP, WebRTC, QUIC)
56+
- Message routing (flooding, greedy perimeter)
57+
- Quality‑of‑Service (priority, retransmission)
58+
- **Technology**: Rust crate built on `libp2p` or `smol‑net`.
59+
60+
### 2. State Sync (CRDT)
61+
- **Purpose**: Maintain a shared, eventually‑consistent key‑value store across agents.
62+
- **Features**:
63+
- CRDT‑based map (`aw‑map`, `lseq‑tree`)
64+
- Conflict‑free merge of concurrent updates
65+
- Tombstone‑free garbage collection
66+
- Version vectors / dotted version vectors
67+
- **Technology**: Rust crate leveraging `automerge` or custom CRDT implementation.
68+
69+
### 3. Local Planner
70+
- **Purpose**: Execute autonomous tasks based on local state and shared swarm intent.
71+
- **Features**:
72+
- Finite‑state machine (FSM) definition and execution
73+
- Task scheduling and interruption
74+
- Integration with ROS2 navigation stack
75+
- **Technology**: Rust crate with `behavior‑tree` or `smach`‑like DSL.
76+
77+
### 4. Resource Monitor
78+
- **Purpose**: Observe local hardware constraints and adjust agent behavior.
79+
- **Metrics**: CPU usage, battery level, network latency, memory pressure.
80+
- **Actions**: Throttle planning frequency, reduce communication rate, switch to low‑power mode.
81+
82+
### 5. Agent Core
83+
- **Purpose**: Glue component that orchestrates the above modules.
84+
- **Lifecycle**: Initialization, event loop, graceful shutdown.
85+
- **API**: Exposes a unified Rust trait and Python binding.
86+
87+
## Data Flow
88+
1. Agent starts, joins mesh network via Transport.
89+
2. Agent subscribes to shared CRDT keys (e.g., `swarm/goal`).
90+
3. Local Planner reads local CRDT copy and decides next action.
91+
4. Actions may update CRDT (e.g., `agent/status = moving`).
92+
5. Transport propagates CRDT deltas to neighbors.
93+
6. Resource Monitor may throttle outgoing messages if battery low.
94+
7. On network partition, each agent continues with its last known state; merge occurs when connectivity resumes.
95+
96+
## Development Roadmap
97+
98+
### Phase 1 – Foundation (Current)
99+
- Mesh Transport (basic peer discovery + messaging)
100+
- State Sync (single‑type CRDT map)
101+
- Integration test with two nodes
102+
103+
### Phase 2 – Autonomy
104+
- Local Planner FSM
105+
- Resource Monitor skeleton
106+
- Python bindings for all components
107+
108+
### Phase 3 – Realism
109+
- ROS2 integration
110+
- Gazebo simulation with multiple robots
111+
- Performance benchmarking
112+
113+
### Phase 4 – Production
114+
- CI/CD, packaging (Debian, PyPI, crates.io)
115+
- Comprehensive documentation
116+
- Security audit
117+
118+
## Technology Stack
119+
- **Language**: Rust (core), Python (bindings & high‑level API)
120+
- **Networking**: `libp2p‑rust` or custom `smol‑net`
121+
- **CRDT**: `automerge‑rs` or custom implementation
122+
- **Simulation**: ROS2 Humble, Gazebo Classic / Ignition
123+
- **Build**: Cargo workspace, `pyo3`, `maturin`
124+
- **CI**: GitHub Actions, `cargo‑test`, `pytest`
125+
126+
## Directory Layout
127+
See `README.md` for the exact folder structure.
128+
129+
## Contributing
130+
Please read `CONTRIBUTING.md` (to be created) for guidelines on code style, testing, and pull requests.
131+
132+
---
133+
*Last updated: 2026‑03‑26*

‎CHANGELOG.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Changelog
2+
3+
All notable changes to the Offline‑First Multi‑Agent Autonomy SDK will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
### Added
11+
- Initial project skeleton with Rust workspace and six core crates:
12+
- `common`: shared types, error handling, serialization utilities.
13+
- `mesh‑transport`: mesh networking with libp2p backend, discovery, connection management.
14+
- `state‑sync`: CRDT‑based map with operation‑based deltas and vector clocks.
15+
- `agent‑core`: high‑level agent abstraction integrating transport and state sync.
16+
- `local‑planner`: trait for autonomous decision‑making.
17+
- `resource‑monitor`: trait for system resource tracking.
18+
- Python bindings via PyO3, providing `PyAgent` and `PyMeshTransport` classes.
19+
- Comprehensive documentation: architecture specs, API overview, getting started guide.
20+
- Example applications:
21+
- `simple_sync`: two agents synchronizing a counter.
22+
- `ros2_gazebo`: placeholder for ROS2/Gazebo simulation.
23+
- CI/CD pipeline (GitHub Actions) for Rust and Python.
24+
- Benchmark suite for CRDT map performance (using Criterion).
25+
26+
### Changed
27+
- Refactored mesh transport to resolve mutability mismatch between `Backend` and `Transport` traits.
28+
- Improved error handling with dedicated error types and logging.
29+
- Enhanced CRDT map to generate deltas based on vector clocks, reducing bandwidth.
30+
31+
### Fixed
32+
- Various compilation warnings and clippy lints.
33+
- Inconsistent trait bounds in `Backend` and `Transport`.
34+
35+
### Known Issues
36+
- Libp2p backend discovery may not work out‑of‑the‑box on all platforms.
37+
- Python bindings for `send_to` and `broadcast` currently consume the transport (bug).
38+
- The `MeshTransport::start` method consumes the transport (bug).
39+
- No real‑world multi‑agent simulation yet (only simple examples).
40+
41+
## [0.1.0] - 2026‑03‑26
42+
43+
### Added
44+
- First alpha release of the SDK.
45+
- Basic functionality for offline‑first multi‑agent systems.
46+
- All core components are present and can be integrated.
47+
48+
### Notes
49+
This release is intended for early adopters and developers who want to experiment with the SDK. It is not yet production‑ready, but provides a solid foundation for building decentralized, offline‑first autonomous systems.

0 commit comments

Comments
 (0)