# NebulaForge Architecture and Contribution Guide

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.

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.

Getting Started
- Install Python dependencies via test.sh which runs packaging checks and tests.
- Run unit tests with pytest.

Contribution Rules
- Follow PEP 8 where applicable; keep modules small and focused.
- Add tests for new functionality; ensure all tests pass before proposing changes.
- Update AGENTS.md if you introduce new major components or interfaces.

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.

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.