From e1c6ec64e16a6bdb2990f497a7dab3ac300d8ddb Mon Sep 17 00:00:00 2001 From: michael trestman Date: Tue, 23 Jun 2026 09:15:17 -0700 Subject: [PATCH 1/3] rip out docs and replace w links --- README.md | 6 ++ docs/local_testing.md | 9 --- miners/README.md | 166 +----------------------------------------- validator/README.md | 6 ++ 4 files changed, 16 insertions(+), 171 deletions(-) delete mode 100644 docs/local_testing.md create mode 100644 validator/README.md diff --git a/README.md b/README.md index 60d13a6e..6089347d 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,11 @@ # Ridges +## Documentation + +- **Miners:** [docs.ridges.ai/guides/miner-setup](https://docs.ridges.ai/guides/miner-setup) +- **Validators:** [docs.ridges.ai/guides/validator-setup](https://docs.ridges.ai/guides/validator-setup) +- **Full docs:** [docs.ridges.ai](https://docs.ridges.ai) + ## Development Guide ### Requirements diff --git a/docs/local_testing.md b/docs/local_testing.md deleted file mode 100644 index 84a0c4ab..00000000 --- a/docs/local_testing.md +++ /dev/null @@ -1,9 +0,0 @@ -# Local Testing - -`ridges` supports a relaxed local Harbor runner for miner testing. - -Use `docs/harbor_local_testing.md` for the current runtime boundary: -- validators execute promoted `harbor_remote_task` specs only -- local Harbor task experimentation is available through: - - `ridges miner run-local` - - the Python API at `miners.run_local_task(...)` diff --git a/miners/README.md b/miners/README.md index 4f79d888..83e4afe4 100644 --- a/miners/README.md +++ b/miners/README.md @@ -24,160 +24,10 @@ Run your miner locally before you ship it to the subnet. --- -## Install - -```bash -pip install -e ".[miner]" -``` - -```bash -uv sync --extra miner -``` - -Run these from the repo root. - ---- - -## Quickstart - -### 1. Setup your workspace - -```bash -ridges miner setup -``` - -Writes your local miner config and prepares a workspace for runs, cache, and provider env. - -### 2. Configure inference - -Fill the generated file: - -```bash -/.env.miner -``` - -Start from the checked-in template: - -```bash -miners/env.miner.example -``` - -Supported providers: -- OpenRouter -- Targon -- Chutes - -### 3. Run a task locally - -```bash -ridges miner run-local -``` - -Pick a dataset, choose a problem, and run your local `agent.py` end-to-end. - ---- - -## CLI - -### `ridges miner setup` - -Create or update your miner config and provider selection. - -```bash -ridges miner setup -``` - -### `ridges miner run-local` - -Run one Harbor task locally against your miner. - -```bash -ridges miner run-local -``` - -Scripted mode: - -```bash -ridges miner run-local \ - --task-path /path/to/task-or-task.tar.gz \ - --agent-path /path/to/agent.py \ - --provider openrouter \ - --non-interactive -``` - -### `ridges miner cleanup` - -Prune cached extracted task archives from local runs. - -```bash -ridges miner cleanup -``` - -Preview first: - -```bash -ridges miner cleanup --dry-run -``` - -### `ridges upload` - -Upload your local `agent.py` to the platform. - -```bash -ridges upload --file agent.py -``` - -Uploads now require: -- an OpenRouter runtime API key -- an OpenRouter management key - -Provide them with flags: - -```bash -ridges upload \ - --file agent.py \ - --openrouter-api-key sk-or-v1-... \ - --openrouter-management-key sk-or-v1-... -``` - -Or export them in your shell before running upload: - -```bash -export RIDGES_OPENROUTER_API_KEY=sk-or-v1-... -export RIDGES_OPENROUTER_MANAGEMENT_KEY=sk-or-v1-... -``` - -The management key is only used for platform upload validation. It is not required for `ridges miner run-local`. - ---- - -## Configuration - -The miner CLI reads provider settings from: - -1. your current shell environment -2. `/.env.miner` - -The workspace file is the easiest path for most miners. - -### `.env.miner` - -```bash -# OpenRouter -RIDGES_OPENROUTER_API_KEY= -RIDGES_OPENROUTER_BASE_URL=https://openrouter.ai/api/v1 - -# Targon -RIDGES_TARGON_API_KEY= -RIDGES_TARGON_BASE_URL= - -# Chutes -RIDGES_CHUTES_API_KEY= -RIDGES_CHUTES_INFERENCE_BASE_URL= -RIDGES_CHUTES_EMBEDDING_BASE_URL= -``` - -If no provider is configured yet, `ridges miner setup` / `ridges miner run-local` will guide you and create the file for you. +- [Miner setup](https://docs.ridges.ai/guides/miner-setup) +- [Local testing](https://docs.ridges.ai/guides/local-testing) +- [Submit your agent](https://docs.ridges.ai/guides/submit) +- [Agent contract](https://docs.ridges.ai/guides/agent-contract) --- @@ -206,14 +56,6 @@ miners/ --- -## Notes - -- `ridges miner run-local` is for fast local iteration, not validator-equivalent execution. -- Your local agent still uses the normal Ridges miner contract: `agent_main(input) -> str`. -- For deeper runtime details, see `docs/harbor_local_testing.md` and `docs/sandbox.md`. - ---- -
Advanced: custom sandbox proxy endpoint diff --git a/validator/README.md b/validator/README.md new file mode 100644 index 00000000..5e8df454 --- /dev/null +++ b/validator/README.md @@ -0,0 +1,6 @@ +# Ridges Validator + +- [Setup guide](https://docs.ridges.ai/guides/validator-setup) +- [Network configuration](https://docs.ridges.ai/guides/validator-networks) +- [Config reference](https://docs.ridges.ai/guides/validator-config) +- [FAQ](https://docs.ridges.ai/guides/validator-faq) From bfe1096db04fc388fd9b34f492cb70c07f35a124 Mon Sep 17 00:00:00 2001 From: michael trestman Date: Tue, 23 Jun 2026 09:33:36 -0700 Subject: [PATCH 2/3] wip --- README.md | 238 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 234 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 6089347d..6044a239 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,162 @@ # Ridges -## Documentation -- **Miners:** [docs.ridges.ai/guides/miner-setup](https://docs.ridges.ai/guides/miner-setup) -- **Validators:** [docs.ridges.ai/guides/validator-setup](https://docs.ridges.ai/guides/validator-setup) -- **Full docs:** [docs.ridges.ai](https://docs.ridges.ai) +Ridges is an Bittensor subnet that acts as an open source agent competition platform, where miners both compete and collaborate on a software engineering agent. Validators pull submitted code and run it on benchmark problems, evaluating the output. The highest-scoring agent earns emissions. + +**Docs:** [docs.ridges.ai](https://docs.ridges.ai) + + +## CLI + +### `ridges miner setup` + +Create or update your miner config and provider selection. + +```bash +ridges miner setup +``` + +### `ridges miner run-local` + +Run one Harbor task locally against your miner. + +```bash +ridges miner run-local +``` + +Scripted mode: + +```bash +ridges miner run-local \ + --task-path /path/to/task-or-task.tar.gz \ + --agent-path /path/to/agent.py \ + --provider openrouter \ + --non-interactive +``` + +### `ridges miner cleanup` + +Prune cached extracted task archives from local runs. + +```bash +ridges miner cleanup +``` + +Preview first: + +```bash +ridges miner cleanup --dry-run +``` + +### `ridges upload` + +Upload your local `agent.py` to the platform. + +```bash +ridges upload --file agent.py +``` + +Uploads now require: +- an OpenRouter runtime API key +- an OpenRouter management key + +Provide them with flags: + +```bash +ridges upload \ + --file agent.py \ + --openrouter-api-key sk-or-v1-... \ + --openrouter-management-key sk-or-v1-... +``` + +Or export them in your shell before running upload: + +```bash +export RIDGES_OPENROUTER_API_KEY=sk-or-v1-... +export RIDGES_OPENROUTER_MANAGEMENT_KEY=sk-or-v1-... +``` + +The management key is only used for platform upload validation. It is not required for `ridges miner run-local`. + +--- + +## Configuration + +The miner CLI reads provider settings from: + +1. your current shell environment +2. `/.env.miner` + +The workspace file is the easiest path for most miners. + +### `.env.miner` + +```bash +# OpenRouter +RIDGES_OPENROUTER_API_KEY= +RIDGES_OPENROUTER_BASE_URL=https://openrouter.ai/api/v1 + +# Targon +RIDGES_TARGON_API_KEY= +RIDGES_TARGON_BASE_URL= + +# Chutes +RIDGES_CHUTES_API_KEY= +RIDGES_CHUTES_INFERENCE_BASE_URL= +RIDGES_CHUTES_EMBEDDING_BASE_URL= +``` + +If no provider is configured yet, `ridges miner setup` / `ridges miner run-local` will guide you and create the file for you. + +--- + +## Python API + +The CLI is the main path, but you can script local runs too. + +```python +from miners import LocalInferenceClient, LocalInferenceConfig, run_local_task +``` + +Use `run_local_task(...)` to launch a local Harbor run from Python. +Inside a local-testing `agent.py`, use `LocalInferenceClient.from_env()` and return the generated diff from `agent_main(input) -> str`. + +--- + +## What Matters In This Folder + +```text +miners/ +├── cli/ # CLI entrypoints and command flows +├── env.miner.example # provider env template +├── inference_client.py # local provider-backed inference helper +└── local_harbor.py # Python API for local task runs +``` + +--- + +## Notes + +- `ridges miner run-local` is for fast local iteration, not validator-equivalent execution. +- Your local agent still uses the normal Ridges miner contract: `agent_main(input) -> str`. +- For deeper runtime details, see `docs/harbor_local_testing.md` and `docs/sandbox.md`. + +--- + +
+Advanced: custom sandbox proxy endpoint + +If you need to point local runs at a sandbox-proxy-compatible endpoint instead of OpenRouter / Targon / Chutes: + +- set `RIDGES_CUSTOM_SANDBOX_PROXY_URL` in `/.env.miner` +- use provider `custom` +- support `POST /api/inference` +- support `POST /api/embedding` + +
+ + +>>>>>>> Stashed changes ## Development Guide @@ -51,3 +203,81 @@ For the validator, create a `.env` file in the `validator/` directory based on t ```bash python -m validator.src.main ``` + +# Ridges Miner CLI + +``` + · · · + . . · ´ ` · . . · ´ ` · . . + . · · ` . + . ·´ `· . + + /\ + /**\ + /****\ /\ + / \ /**\ + / /\ / \ /\ /\ /\ /\ /\/\/\ /\ + / / \ / \ / \/\/ \/ \ /\/ \/\ /\ /\/ / / \/ \ + / / \/ /\ \ / \ \ / \/ / / \/ \/ \ / \ \ + / / \/ \/\ \ / \ / / \ +__/__/_______/___/__\___\__________________________________________________ + +``` + +Run your miner locally before you ship it to the subnet. + +`miners/` is the CLI + Python toolkit for testing `agent.py`, wiring inference providers, and running Harbor tasks with the same miner-facing contract used by Ridges. + +--- + +## Install + +```bash +pip install -e ".[miner]" +``` + +```bash +uv sync --extra miner +``` + +Run these from the repo root. + +--- + +## Quickstart + +### 1. Setup your workspace + +```bash +ridges miner setup +``` + +Writes your local miner config and prepares a workspace for runs, cache, and provider env. + +### 2. Configure inference + +Fill the generated file: + +```bash +/.env.miner +``` + +Start from the checked-in template: + +```bash +miners/env.miner.example +``` + +Supported providers: +- OpenRouter +- Targon +- Chutes + +### 3. Run a task locally + +```bash +ridges miner run-local +``` + +Pick a dataset, choose a problem, and run your local `agent.py` end-to-end. + From 549e44db08becbd3a58030998ab1bba634e2ea01 Mon Sep 17 00:00:00 2001 From: michael trestman Date: Tue, 23 Jun 2026 10:22:03 -0700 Subject: [PATCH 3/3] docs changes --- README.md | 214 ++++++++++++++++---------------------------- api/REAMDE.md | 48 ++++++++++ validator/README.md | 2 + 3 files changed, 127 insertions(+), 137 deletions(-) create mode 100644 api/REAMDE.md diff --git a/README.md b/README.md index 6044a239..71d198bc 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,83 @@ Ridges is an Bittensor subnet that acts as an open source agent competition plat **Docs:** [docs.ridges.ai](https://docs.ridges.ai) +``` + · · · + . . · ´ ` · . . · ´ ` · . . + . · · ` . + . ·´ `· . + + /\ + /**\ + /****\ /\ + / \ /**\ + / /\ / \ /\ /\ /\ /\ /\/\/\ /\ + / / \ / \ / \/\/ \/ \ /\/ \/\ /\ /\/ / / \/ \ + / / \/ /\ \ / \ \ / \/ / / \/ \/ \ / \ \ + / / \/ \/\ \ / \ / / \ +__/__/_______/___/__\___\__________________________________________________ + +``` + + +--- + +## Getting started as a miner + +Read the [miner's guide](https://docs.ridges.ai/guides/) before you get started! + +Run your miner locally before you ship it to the subnet! + +`miners/` is the CLI + Python toolkit for testing `agent.py`, wiring inference providers, and running Harbor tasks with the same miner-facing contract used by Ridges. + + +```bash +pip install -e ".[miner]" +``` + +```bash +uv sync --extra miner +``` + +Run these from the repo root. + +--- + +## 1. Setup your workspace + +```bash +ridges miner setup +``` + +Writes your local miner config and prepares a workspace for runs, cache, and provider env. + +## 2. Configure inference + +Fill the generated file: + +```bash +/.env.miner +``` + +Start from the checked-in template: + +```bash +miners/env.miner.example +``` + +Supported providers: +- OpenRouter +- Targon +- Chutes + +## 3. Run a task locally + +```bash +ridges miner run-local +``` + +Pick a dataset, choose a problem, and run your local `agent.py` end-to-end. + ## CLI @@ -78,9 +155,6 @@ export RIDGES_OPENROUTER_MANAGEMENT_KEY=sk-or-v1-... The management key is only used for platform upload validation. It is not required for `ridges miner run-local`. ---- - -## Configuration The miner CLI reads provider settings from: @@ -95,15 +169,6 @@ The workspace file is the easiest path for most miners. # OpenRouter RIDGES_OPENROUTER_API_KEY= RIDGES_OPENROUTER_BASE_URL=https://openrouter.ai/api/v1 - -# Targon -RIDGES_TARGON_API_KEY= -RIDGES_TARGON_BASE_URL= - -# Chutes -RIDGES_CHUTES_API_KEY= -RIDGES_CHUTES_INFERENCE_BASE_URL= -RIDGES_CHUTES_EMBEDDING_BASE_URL= ``` If no provider is configured yet, `ridges miner setup` / `ridges miner run-local` will guide you and create the file for you. @@ -156,128 +221,3 @@ If you need to point local runs at a sandbox-proxy-compatible endpoint instead o
->>>>>>> Stashed changes - -## Development Guide - -### Requirements - -- Python 3.12+ -- Docker (for running dependencies like Postgres and S3 locally) -- UV (for managing Python dependencies) - -### Setting up the development environment - -Install dependencies (including dev tools): - -```bash -uv sync --extra dev -``` - -Install the pre-commit hooks so ruff runs automatically before each commit: - -```bash -uv run pre-commit install -``` - -To run the hooks manually against all files at any time: - -```bash -uv run pre-commit run --all-files -``` - -### Running the services locally - -In order to run the services locally you can use the provided `docker-compose.yml` file to start the Postgres database, the Adobe S3 mock and the API service. - -Before starting the services, make sure to update the `POSTGRES_USER`, `POSTGRES_PASSWORD`, and `POSTGRES_DB` environment variables in `docker-compose.yml` with your desired values. - -You also need to create a `.env` file in the `api/` directory based on the provided `.env.example` and fill in the required environment variables. - -```bash -docker compose up -d -``` - -For the validator, create a `.env` file in the `validator/` directory based on the provided `.env.example` and fill in the required environment variables. Depending on the "MODE" env variable value you might start a "Screener" or a "Validator" - -```bash -python -m validator.src.main -``` - -# Ridges Miner CLI - -``` - · · · - . . · ´ ` · . . · ´ ` · . . - . · · ` . - . ·´ `· . - - /\ - /**\ - /****\ /\ - / \ /**\ - / /\ / \ /\ /\ /\ /\ /\/\/\ /\ - / / \ / \ / \/\/ \/ \ /\/ \/\ /\ /\/ / / \/ \ - / / \/ /\ \ / \ \ / \/ / / \/ \/ \ / \ \ - / / \/ \/\ \ / \ / / \ -__/__/_______/___/__\___\__________________________________________________ - -``` - -Run your miner locally before you ship it to the subnet. - -`miners/` is the CLI + Python toolkit for testing `agent.py`, wiring inference providers, and running Harbor tasks with the same miner-facing contract used by Ridges. - ---- - -## Install - -```bash -pip install -e ".[miner]" -``` - -```bash -uv sync --extra miner -``` - -Run these from the repo root. - ---- - -## Quickstart - -### 1. Setup your workspace - -```bash -ridges miner setup -``` - -Writes your local miner config and prepares a workspace for runs, cache, and provider env. - -### 2. Configure inference - -Fill the generated file: - -```bash -/.env.miner -``` - -Start from the checked-in template: - -```bash -miners/env.miner.example -``` - -Supported providers: -- OpenRouter -- Targon -- Chutes - -### 3. Run a task locally - -```bash -ridges miner run-local -``` - -Pick a dataset, choose a problem, and run your local `agent.py` end-to-end. - diff --git a/api/REAMDE.md b/api/REAMDE.md new file mode 100644 index 00000000..b8e12045 --- /dev/null +++ b/api/REAMDE.md @@ -0,0 +1,48 @@ + +# Development Guide + +## Requirements + +- Python 3.12+ +- Docker (for running dependencies like Postgres and S3 locally) +- UV (for managing Python dependencies) + +## Setting up the development environment + +Install dependencies (including dev tools): + +```bash +uv sync --extra dev +``` + +Install the pre-commit hooks so ruff runs automatically before each commit: + +```bash +uv run pre-commit install +``` + +To run the hooks manually against all files at any time: + +```bash +uv run pre-commit run --all-files +``` + +## Running the services locally + +In order to run the services locally you can use the provided `docker-compose.yml` file to start the Postgres database, the Adobe S3 mock and the API service. + +Before starting the services, make sure to update the `POSTGRES_USER`, `POSTGRES_PASSWORD`, and `POSTGRES_DB` environment variables in `docker-compose.yml` with your desired values. + +You also need to create a `.env` file in the `api/` directory based on the provided `.env.example` and fill in the required environment variables. + +```bash +docker compose up -d +``` + +For the validator, create a `.env` file in the `validator/` directory based on the provided `.env.example` and fill in the required environment variables. Depending on the "MODE" env variable value you might start a "Screener" or a "Validator" + +```bash +python -m validator.src.main +``` + + diff --git a/validator/README.md b/validator/README.md index 5e8df454..af4bff71 100644 --- a/validator/README.md +++ b/validator/README.md @@ -1,5 +1,7 @@ # Ridges Validator +Starting from a fresh Ubuntu server? Run [`setup/setup-validator.sh`](../setup/setup-validator.sh) to installs Docker, PM2, uv, clones the repo, and start the validator in one shot. + - [Setup guide](https://docs.ridges.ai/guides/validator-setup) - [Network configuration](https://docs.ridges.ai/guides/validator-networks) - [Config reference](https://docs.ridges.ai/guides/validator-config)