From 92610587540574579d0190a47cb63457842508df Mon Sep 17 00:00:00 2001
From: aitbc <aitbc@keisanki.net>
Date: Sun, 3 May 2026 23:13:40 +0200
Subject: [PATCH] docs: add blockchain, edge GPU, and multi-modal RL router
 documentation

Added comprehensive documentation for the three newly implemented routers:
- Blockchain Router: RPC proxy endpoints for blockchain data integration
- Edge GPU Router: GPU management using nvidia-smi discovery
- Multi-modal RL Router: AI service proxy for job management

Includes endpoint descriptions, proxy behavior, and error handling details.
---
 docs/apps/coordinator/coordinator-api.md | 41 ++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/docs/apps/coordinator/coordinator-api.md b/docs/apps/coordinator/coordinator-api.md
index ada0f2c7..a41c560f 100644
--- a/docs/apps/coordinator/coordinator-api.md
+++ b/docs/apps/coordinator/coordinator-api.md
@@ -25,6 +25,47 @@ The coordinator now exposes read-only explorer data under `/v1/explorer` for `ap
 
 Set `VITE_DATA_MODE=live` and `VITE_COORDINATOR_API` in the explorer web app to consume these APIs.
 
+## Blockchain Router
+
+The blockchain router provides RPC proxy endpoints for blockchain data integration:
+
+- `GET /v1/status` – Blockchain status (proxies to blockchain RPC `/rpc/head`)
+- `GET /v1/sync-status` – Blockchain synchronization status (proxies to `/rpc/syncStatus`)
+- `GET /v1/blocks/{height}` – Get block by height (proxies to `/rpc/blocks/{height}`)
+- `GET /v1/blocks/hash/{block_hash}` – Get block by hash (proxies to `/rpc/blocks/hash/{block_hash}`)
+- `GET /v1/transactions/{tx_hash}` – Get transaction by hash (proxies to `/rpc/transactions/{tx_hash}`)
+- `GET /v1/accounts/{address}` – Get account balance and state (proxies to `/rpc/accounts/{address}`)
+- `GET /v1/validators` – List validators (derived from PoA proposer)
+- `GET /v1/supply` – Get token supply (calculated from genesis allocations)
+- `GET /v1/state/dump` – Get state dump (recent blocks snapshot)
+
+All endpoints use `AITBCHTTPClient` to proxy requests to the blockchain node RPC (default port 8006). When the RPC is unavailable, endpoints return mock data or error responses.
+
+## Edge GPU Router
+
+The edge GPU router provides GPU management endpoints using nvidia-smi for discovery:
+
+- `GET /v1/edge-gpu/profiles` – List available GPU profiles (uses nvidia-smi to detect GPUs)
+- `GET /v1/edge-gpu/metrics/{gpu_id}` – Get GPU metrics (utilization, memory, temperature via nvidia-smi)
+- `POST /v1/edge-gpu/discover` – Discover and register edge GPUs for a miner
+- `POST /v1/edge-gpu/optimize` – Optimize ML inference request for edge GPU
+- `POST /v1/edge-gpu/metrics` – Submit GPU metrics
+
+GPU discovery uses `subprocess` to run `nvidia-smi` commands and parse the output. Returns empty results if nvidia-smi is unavailable or no GPUs are present.
+
+## Multi-modal RL Router
+
+The multi-modal RL router proxies to the AI service for job management:
+
+- `POST /v1/multi-modal-rl/jobs` – Submit a job for execution (proxies to AI service `/jobs`)
+- `GET /v1/multi-modal-rl/jobs/{job_id}` – Get job status (proxies to AI service `/jobs/{job_id}`)
+- `GET /v1/multi-modal-rl/jobs/{job_id}/result` – Get job result (proxies to AI service `/jobs/{job_id}/result`)
+- `POST /v1/multi-modal-rl/jobs/{job_id}/cancel` – Cancel a job (proxies to AI service `/jobs/{job_id}/cancel`)
+- `GET /v1/multi-modal-rl/jobs` – List jobs with filtering (proxies to AI service `/jobs`)
+- `GET /v1/multi-modal-rl/health` – Health check (proxies to AI service `/health`)
+
+All endpoints use `AITBCHTTPClient` to proxy requests to the AI service (default port 8106). When the AI service is unavailable, endpoints return error responses indicating the service is unreachable.
+
 ## Development Setup
 
 1. Create a virtual environment in `apps/coordinator-api/.venv`.