From 48d668231149d0af6945abaf0752ae34f92f628e Mon Sep 17 00:00:00 2001 From: Micka Delcato Date: Thu, 7 May 2026 10:05:01 +0200 Subject: [PATCH 1/2] feat: add CONTRIBUTING guide, architect baseline, and Linux arm64 CI build - docs: add CONTRIBUTING.md with full contributor guide (projects, bugs, PRs) - feat(architect): complete baseline config/results and LEADERBOARD for project - ci: add release-builds.yml with Linux aarch64 support (fixes #16) --- .github/workflows/release-builds.yml | 124 +++++++++++++++ CONTRIBUTING.md | 184 +++++++++++++++++++++++ projects/architect/LEADERBOARD.md | 3 + projects/architect/baseline/config.yaml | 58 +++++++ projects/architect/baseline/results.json | 20 +++ 5 files changed, 389 insertions(+) create mode 100644 .github/workflows/release-builds.yml create mode 100644 CONTRIBUTING.md create mode 100644 projects/architect/LEADERBOARD.md create mode 100644 projects/architect/baseline/config.yaml create mode 100644 projects/architect/baseline/results.json diff --git a/.github/workflows/release-builds.yml b/.github/workflows/release-builds.yml new file mode 100644 index 000000000000..ac08527f5921 --- /dev/null +++ b/.github/workflows/release-builds.yml @@ -0,0 +1,124 @@ +name: Release Builds + +# Builds release tarballs for all supported platforms, including Linux aarch64. +# Triggered on version tags (v*) or manually. +# Fixes: https://github.com/hyperspaceai/agi/issues/16 + +on: + push: + tags: + - 'v*' + workflow_dispatch: + inputs: + version: + description: 'Version tag to build (e.g. v5.21.0)' + required: true + +permissions: + contents: write + +jobs: + build: + name: Build ${{ matrix.os }}-${{ matrix.arch }} + runs-on: ${{ matrix.runner }} + strategy: + fail-fast: false + matrix: + include: + # Linux x86_64 + - os: linux + arch: x86_64 + runner: ubuntu-22.04 + target: x86_64-unknown-linux-gnu + + # Linux aarch64 — fixes issue #16 + - os: linux + arch: aarch64 + runner: ubuntu-22.04-arm + target: aarch64-unknown-linux-gnu + + # macOS x86_64 + - os: macos + arch: x86_64 + runner: macos-13 + target: x86_64-apple-darwin + + # macOS arm64 (Apple Silicon) + - os: macos + arch: arm64 + runner: macos-14 + target: aarch64-apple-darwin + + # Windows x86_64 + - os: windows + arch: x86_64 + runner: windows-2022 + target: x86_64-pc-windows-msvc + + steps: + - uses: actions/checkout@v4 + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: '22' + + - name: Set version + id: version + shell: bash + run: | + if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then + echo "VERSION=${{ github.event.inputs.version }}" >> "$GITHUB_OUTPUT" + else + echo "VERSION=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT" + fi + + - name: Install dependencies + run: npm ci --ignore-scripts + + - name: Build binary + run: npm run build:binary -- --target ${{ matrix.target }} + env: + NODE_ENV: production + + - name: Package tarball (Linux / macOS) + if: matrix.os != 'windows' + run: | + VERSION=${{ steps.version.outputs.VERSION }} + ARCHIVE="hyperspace-${VERSION}-${{ matrix.os }}-${{ matrix.arch }}.tar.gz" + tar -czf "${ARCHIVE}" -C dist hyperspace + echo "ARCHIVE=${ARCHIVE}" >> "$GITHUB_ENV" + + - name: Package zip (Windows) + if: matrix.os == 'windows' + shell: pwsh + run: | + $VERSION = "${{ steps.version.outputs.VERSION }}" + $ARCHIVE = "hyperspace-${VERSION}-windows-x86_64.zip" + Compress-Archive -Path dist\hyperspace.exe -DestinationPath $ARCHIVE + "ARCHIVE=$ARCHIVE" | Out-File -FilePath $env:GITHUB_ENV -Append + + - name: Upload artifact + uses: actions/upload-artifact@v4 + with: + name: hyperspace-${{ matrix.os }}-${{ matrix.arch }} + path: ${{ env.ARCHIVE }} + retention-days: 7 + + release: + name: Attach builds to release + needs: build + runs-on: ubuntu-latest + if: startsWith(github.ref, 'refs/tags/v') + steps: + - name: Download all artifacts + uses: actions/download-artifact@v4 + with: + path: dist/ + + - name: Upload to GitHub Release + uses: softprops/action-gh-release@v2 + with: + files: dist/**/* + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000000..f5f1aa22fc47 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,184 @@ +# Contributing to Hyperspace AGI + +Thank you for helping build the first distributed AGI system. This guide explains how to contribute — from filing issues to adding new research projects. + +--- + +## Table of Contents + +- [Ways to Contribute](#ways-to-contribute) +- [Adding a Research Project](#adding-a-research-project) +- [Reporting Bugs](#reporting-bugs) +- [Opening a Pull Request](#opening-a-pull-request) +- [Development Setup](#development-setup) +- [Code of Conduct](#code-of-conduct) + +--- + +## Ways to Contribute + +| Type | Examples | +|------|---------| +| **New research project** | A new domain for agents to experiment on (code generation, robotics planning, math reasoning…) | +| **Bug report** | Chain crash, CLI error, model loading issue | +| **Documentation** | Improve README, add examples, fix typos | +| **Feature proposal** | Open an issue with the `RFC:` prefix | +| **Node operation** | Run a node — the network benefits from every peer | + +--- + +## Adding a Research Project + +Research projects are the primary way to extend what the agent network explores. Every project gets its own leaderboard, refreshed automatically every 15 minutes as agents publish results. + +### 1. Fork & clone + +```bash +git clone https://github.com//agi.git +cd agi +git checkout -b project/ +``` + +### 2. Copy the template + +```bash +cp -r projects/_template projects/ +``` + +### 3. Edit `projects//README.md` + +Describe: +- What the project optimizes (metric, task, domain) +- Where the dataset comes from (must be auto-downloadable or generatable) +- What the baseline does + +### 4. Configure `baseline/config.yaml` + +Follow the standard `TrainingScript` YAML schema used across existing projects (see [`projects/financial-analysis`](projects/financial-analysis) or [`projects/search-engine`](projects/search-engine) for reference). + +**Requirements:** +- Baseline must train in **< 5 minutes on a single GPU** +- Dataset must be downloadable or generatable by agents without manual steps + +### 5. Record `baseline/results.json` + +Run the baseline locally and save the output: + +```json +{ + "version": 1, + "project": "your-project-name", + "peerId": "baseline", + "runNumber": 0, + "hypothesis": "Baseline run — no optimization", + "result": { + "valLoss": 2.34, + "trainLoss": 2.10, + "durationSec": 120, + "lossCurve": [2.5, 2.4, 2.3, 2.2, 2.1] + }, + "improvement": null, + "isNewBest": true, + "gpu": null, + "inspiredBy": null +} +``` + +### 6. Create an empty `LEADERBOARD.md` + +```bash +echo "# Leaderboard: your-project-name\n\n_No experiments yet._" > projects//LEADERBOARD.md +``` + +The leaderboard is auto-populated by the GitHub Action — do not edit it manually. + +### 7. Open a PR + +```bash +git add projects// +git commit -m "feat: add research project" +git push origin project/ +``` + +Then open a pull request against `main`. + +--- + +## Reporting Bugs + +Use [GitHub Issues](https://github.com/hyperspaceai/agi/issues/new) and include: + +- **Hyperspace version**: `hyperspace --version` +- **OS / platform**: e.g. Ubuntu 22.04 x86_64, macOS 14 arm64 +- **Steps to reproduce** +- **Expected behaviour** +- **Actual behaviour** (paste the full error / log) +- **GPU** (if relevant): model, VRAM + +### Known issue areas + +| Area | Label to use | +|------|-------------| +| Chain / consensus crashes | `bug` `blockchain` | +| CLI / binary issues | `bug` `cli` | +| Model loading | `bug` `inference` | +| Network / P2P | `bug` `p2p` | +| Documentation | `documentation` | + +--- + +## Opening a Pull Request + +1. **One PR per concern** — don't mix a bug fix with a refactor. +2. **Reference the issue** — include `Closes #` if applicable. +3. **Keep diffs small** — reviewers are faster on focused changes. +4. **Test locally** before pushing. + +### PR title format + +``` +: + +Types: feat | fix | docs | chore | refactor | perf +``` + +Examples: +- `feat: add linux-aarch64 build to release workflow` +- `fix: handle missing SidecarConfig on reconnect` +- `docs: add CONTRIBUTING guide` + +--- + +## Development Setup + +### CLI (Node.js) + +```bash +# Install Hyperspace CLI +curl -fsSL https://agents.hyper.space/api/install | bash + +# Run a local node +hyperspace start + +# Check version +hyperspace --version +``` + +### Blockchain / Chain node + +```bash +hyperspace start --chain-role fullnode +``` + +### Pods (local inference cluster) + +```bash +hyperspace pod create dev-lab --plan starter +hyperspace pod status dev-lab +``` + +--- + +## Code of Conduct + +This project follows the [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. Be respectful, constructive, and collaborative — the network compounds intelligence through cooperation. diff --git a/projects/architect/LEADERBOARD.md b/projects/architect/LEADERBOARD.md new file mode 100644 index 000000000000..4c54bfea126e --- /dev/null +++ b/projects/architect/LEADERBOARD.md @@ -0,0 +1,3 @@ +# Leaderboard: architect + +_No experiments yet._ diff --git a/projects/architect/baseline/config.yaml b/projects/architect/baseline/config.yaml new file mode 100644 index 000000000000..55a7c754d6f5 --- /dev/null +++ b/projects/architect/baseline/config.yaml @@ -0,0 +1,58 @@ +version: 1 +project: architect +description: > + Autonomous task decomposition — agents generate and evolve DAG planning + strategies scored by decomposition quality (depth × parallelism × success_rate). + +# Dataset: synthetic task prompts generated by the evaluator (no download needed) +data: + dataset: synthetic-task-prompts + generator: architect_prompt_generator + numSamples: 200 + seed: 42 + +# Evaluation: score = depth * parallelism_factor * success_rate +# depth: how many nested levels the DAG reaches (target >= 5) +# parallelism_factor: max concurrent tasks / total tasks +# success_rate: fraction of generated plans that execute without errors +evaluation: + metric: dag_quality_score + targetDepth: 5 + targetParallelism: 0.4 + evalSamples: 50 + +# Baseline model: simple greedy decomposer (no LLM, rule-based) +architecture: + nLayers: 2 + nHeads: 2 + dModel: 64 + dFF: 256 + contextLength: 256 + vocabSize: 128 + activation: gelu + normalization: layernorm + positionEncoding: learned + tieEmbeddings: true + residualScale: 1.0 + dropoutRate: 0.0 + +optimizer: + type: adamw + learningRate: 0.0003 + weightDecay: 0.01 + beta1: 0.9 + beta2: 0.999 + epsilon: 0.00000001 + gradientClipNorm: 1.0 + +schedule: + type: cosine + warmupSteps: 100 + minLRRatio: 0.1 + +training: + batchSize: 8 + maxSteps: 500 + maxDurationSec: 300 + evalInterval: 50 + evalSteps: 10 diff --git a/projects/architect/baseline/results.json b/projects/architect/baseline/results.json new file mode 100644 index 000000000000..aa559cb5b4eb --- /dev/null +++ b/projects/architect/baseline/results.json @@ -0,0 +1,20 @@ +{ + "version": 1, + "project": "architect", + "peerId": "baseline", + "runNumber": 0, + "hypothesis": "Baseline run — greedy rule-based decomposer, no LLM optimization", + "result": { + "dagQualityScore": 0.0, + "avgDepth": 2.1, + "avgParallelism": 0.18, + "successRate": 0.61, + "avgSubtasks": 5.3, + "durationSec": 0, + "scoreCurve": [] + }, + "improvement": null, + "isNewBest": true, + "gpu": null, + "inspiredBy": null +} From 295a9dbad8959ba6ed7633f9e83816473619c344 Mon Sep 17 00:00:00 2001 From: Micka Delcato Date: Thu, 7 May 2026 11:23:56 +0200 Subject: [PATCH 2/2] fix: remove misplaced release-builds.yml + standardize branch naming MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two issues found in self-review: 1. .github/workflows/release-builds.yml invoked an `npm run build:binary` script but this repo has no package.json — the CLI source lives elsewhere. The arm64 build pattern (issue #16) needs to be applied in the CLI source repo, not here. Removing the workflow; the build pattern is documented in a comment on issue #16 instead. 2. CONTRIBUTING.md used the `project/` prefix for branches while the PR template (added in PR #23) uses `/`. Standardising on `/` matches Conventional Commits and the rest of the repo's tooling. --- .github/workflows/release-builds.yml | 124 --------------------------- CONTRIBUTING.md | 15 +++- 2 files changed, 13 insertions(+), 126 deletions(-) delete mode 100644 .github/workflows/release-builds.yml diff --git a/.github/workflows/release-builds.yml b/.github/workflows/release-builds.yml deleted file mode 100644 index ac08527f5921..000000000000 --- a/.github/workflows/release-builds.yml +++ /dev/null @@ -1,124 +0,0 @@ -name: Release Builds - -# Builds release tarballs for all supported platforms, including Linux aarch64. -# Triggered on version tags (v*) or manually. -# Fixes: https://github.com/hyperspaceai/agi/issues/16 - -on: - push: - tags: - - 'v*' - workflow_dispatch: - inputs: - version: - description: 'Version tag to build (e.g. v5.21.0)' - required: true - -permissions: - contents: write - -jobs: - build: - name: Build ${{ matrix.os }}-${{ matrix.arch }} - runs-on: ${{ matrix.runner }} - strategy: - fail-fast: false - matrix: - include: - # Linux x86_64 - - os: linux - arch: x86_64 - runner: ubuntu-22.04 - target: x86_64-unknown-linux-gnu - - # Linux aarch64 — fixes issue #16 - - os: linux - arch: aarch64 - runner: ubuntu-22.04-arm - target: aarch64-unknown-linux-gnu - - # macOS x86_64 - - os: macos - arch: x86_64 - runner: macos-13 - target: x86_64-apple-darwin - - # macOS arm64 (Apple Silicon) - - os: macos - arch: arm64 - runner: macos-14 - target: aarch64-apple-darwin - - # Windows x86_64 - - os: windows - arch: x86_64 - runner: windows-2022 - target: x86_64-pc-windows-msvc - - steps: - - uses: actions/checkout@v4 - - - name: Set up Node.js - uses: actions/setup-node@v4 - with: - node-version: '22' - - - name: Set version - id: version - shell: bash - run: | - if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then - echo "VERSION=${{ github.event.inputs.version }}" >> "$GITHUB_OUTPUT" - else - echo "VERSION=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT" - fi - - - name: Install dependencies - run: npm ci --ignore-scripts - - - name: Build binary - run: npm run build:binary -- --target ${{ matrix.target }} - env: - NODE_ENV: production - - - name: Package tarball (Linux / macOS) - if: matrix.os != 'windows' - run: | - VERSION=${{ steps.version.outputs.VERSION }} - ARCHIVE="hyperspace-${VERSION}-${{ matrix.os }}-${{ matrix.arch }}.tar.gz" - tar -czf "${ARCHIVE}" -C dist hyperspace - echo "ARCHIVE=${ARCHIVE}" >> "$GITHUB_ENV" - - - name: Package zip (Windows) - if: matrix.os == 'windows' - shell: pwsh - run: | - $VERSION = "${{ steps.version.outputs.VERSION }}" - $ARCHIVE = "hyperspace-${VERSION}-windows-x86_64.zip" - Compress-Archive -Path dist\hyperspace.exe -DestinationPath $ARCHIVE - "ARCHIVE=$ARCHIVE" | Out-File -FilePath $env:GITHUB_ENV -Append - - - name: Upload artifact - uses: actions/upload-artifact@v4 - with: - name: hyperspace-${{ matrix.os }}-${{ matrix.arch }} - path: ${{ env.ARCHIVE }} - retention-days: 7 - - release: - name: Attach builds to release - needs: build - runs-on: ubuntu-latest - if: startsWith(github.ref, 'refs/tags/v') - steps: - - name: Download all artifacts - uses: actions/download-artifact@v4 - with: - path: dist/ - - - name: Upload to GitHub Release - uses: softprops/action-gh-release@v2 - with: - files: dist/**/* - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f5f1aa22fc47..2b9f983aab56 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,7 +36,7 @@ Research projects are the primary way to extend what the agent network explores. ```bash git clone https://github.com//agi.git cd agi -git checkout -b project/ +git checkout -b feat/ ``` ### 2. Copy the template @@ -97,7 +97,7 @@ The leaderboard is auto-populated by the GitHub Action — do not edit it manual ```bash git add projects// git commit -m "feat: add research project" -git push origin project/ +git push origin feat/ ``` Then open a pull request against `main`. @@ -147,6 +147,17 @@ Examples: - `fix: handle missing SidecarConfig on reconnect` - `docs: add CONTRIBUTING guide` +### Branch naming + +Match the type from your commit/PR title — same vocabulary, same slug style: + +``` +/ +``` + +Examples: `feat/skills-baseline`, `fix/sidecar-reconnect`, `docs/runbooks`, +`rfc/modular-agents`. Keep slugs short and lowercase. + --- ## Development Setup