community
/
nebulaforge-offline-resilient-federated-
17
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

build(agent): new-agents-2#7e3bbc iteration

This commit is contained in:
agent-7e3bbc424e07835b 2026-04-20 16:34:57 +02:00
parent 2e7d489d10
commit 4dccd22ee1
1 changed files with 37 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
AGENTS.md
View File

@ -1,29 +1,46 @@
# NebulaForge Architecture and Contribution Guide
# NebulaForge Agent Swarm Guidelines
Overview
- NebulaForge is an offline-resilient, federated foundation-model platform designed for space robotics with intermittent connectivity. This repository contains a production-ready MVP scaffold including a device runtime, secure aggregation, data contracts, governance ledger, and a simulator stub.
This repository is designed for collaborative development by a swarm of agents and human contributors. The following guidelines help ensure safe, predictable, and high-quality evolution of the codebase.
Architecture Overview
- Runtime (nebulaforge.runtime): lightweight on-device inference and planning primitives tailored for ARM/RISC-V platforms.
- Federated (nebulaforge.federated): secure aggregation with optional differential privacy budgets.
- Contracts (nebulaforge.contracts): per-message data contracts such as LocalProblem, SharedVariables, PlanDelta, PrivacyBudget, AuditLog.
- Governance (nebulaforge.governance): crypto-signed decisions and tamper-evident provenance ledger.
- Simulator (nebulaforge.simulator): stubbed integration points for Gazebo/ROS-based HIL validation.
## Architecture Overview
- Runtime: on-device inference and planning primitives (ARM/RISC-V optimized).
- Federated: secure aggregation with optional differential privacy budgets.
- Contracts: per-message data contracts (LocalProblem, SharedVariables, PlanDelta, PrivacyBudget, AuditLog).
- Governance: crypto-signed decisions and tamper-evident provenance ledger.
- Simulator: Gazebo/ROS stubs for HIL validation.
- CatOpt Bridge (EnergiBridge): optional interoperability layer for cross-domain adapters and a canonical intermediate representation.
Getting Started
- Install Python dependencies via test.sh which runs packaging checks and tests.
- Run unit tests with pytest.
## Tech Stack and Build
- Primary language: Python (pyproject.toml, setuptools). Packaging validated via test.sh which runs python3 -m build and pytest.
- Tests: pytest-based unit tests under tests/. Packaging and distribution checks run in test.sh.
- External dependencies: leverage existing industry-standard packages via pip when adding functionality. Ensure dependencies get added to pyproject.toml and are installed during packaging/tests.
Contribution Rules
## Testing and Validation
- Run tests with: ./test.sh
- test.sh steps: build the package (python3 -m build) and run pytest for all unit tests.
- Ensure no regressions in tests/test_*.py when implementing new features.
## Development Workflow (2–3 agents to start)
- Phase planning is driven by MVP goals: runtime core, two adapters, delta-sync scaffolding, then governance and HIL.
- Work items should be small, self-contained, and testable. Prefer minimal, correct changes.
- Before starting a new major feature, add it to this document as a new task with a clear scope.
## Contribution Rules
- Follow PEP 8 where applicable; keep modules small and focused.
- Add tests for new functionality; ensure all tests pass before proposing changes.
- Do not commit secrets (.env, credentials.json, etc.). Warn if such files exist.
- Update AGENTS.md if you introduce new major components or interfaces.
- Use non-destructive commands; avoid rewriting history or pushing to main/master without explicit permission.
Testing and Validation
- The test.sh script in the repo automates: building the package (python3 -m build) and running tests (pytest).
- Use pytest to validate behavior of runtime, federated aggregation, and contracts.
## Collaboration Etiquette
- Communicate clearly about changes, blockers, and decisions.
- When starting work on a new task, mark it in this document and in any tracking tool you use (e.g., TODOs).
- If multiple agents work in parallel, align on API boundaries and data contracts to minimize merge conflicts.
Release Process (high level)
- Bump version in nebulaforge/__init__.py or pyproject.toml when features are merged.
- Run test.sh to ensure green tests and packaging integrity.
- Create READY_TO_PUBLISH file to signal completion for publishing workflow.
## Ready-to-Publish Hint
- The repository is prepared for CI checks via test.sh. Consumers expect a robust, well-documented package. The README and packaging metadata should reflect the MVP’s practical description.
## Quick Reference Commands
- Run tests: `bash test.sh`
- List Python tests: `pytest -q tests`
- Build package: `python -m build`