diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000000..2b9f983aab56b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,195 @@ +# 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 feat/ +``` + +### 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 feat/ +``` + +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` + +### 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 + +### 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 0000000000000..4c54bfea126ef --- /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 0000000000000..55a7c754d6f56 --- /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 0000000000000..aa559cb5b4eb6 --- /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 +}