diff --git a/.gitea/workflows/api-endpoint-tests.yml b/.gitea/workflows/api-endpoint-tests.yml index 1bcad28c..fc2d7623 100644 --- a/.gitea/workflows/api-endpoint-tests.yml +++ b/.gitea/workflows/api-endpoint-tests.yml @@ -4,7 +4,7 @@ on: push: branches: [main, develop] paths: - - 'apps/agent-coordinator/**' + - 'apps/coordinator-api/**' - 'apps/exchange/**' - 'apps/wallet/**' - 'scripts/ci/test_api_endpoints.py' @@ -95,13 +95,13 @@ jobs: service_host="" for candidate in "${host_candidates[@]}"; do - code=$(curl -so /dev/null -w '%{http_code}' "http://$candidate:9001/health" 2>/dev/null) || code=0 + code=$(curl -so /dev/null -w '%{http_code}' "http://$candidate:8011/health" 2>/dev/null) || code=0 if [ "$code" -gt 0 ] && [ "$code" -lt 600 ]; then service_host="$candidate" break fi - code=$(curl -so /dev/null -w '%{http_code}' "http://$candidate:9001/v1/health" 2>/dev/null) || code=0 + code=$(curl -so /dev/null -w '%{http_code}' "http://$candidate:8011/v1/health" 2>/dev/null) || code=0 if [ "$code" -gt 0 ] && [ "$code" -lt 600 ]; then service_host="$candidate" break @@ -119,7 +119,7 @@ jobs: echo "services_available=true" > "${{ env.WORKSPACE }}/status" # Check only the services needed for API endpoint tests (exclude blockchain RPC) - for port in 9001 8001 8003; do + for port in 8011 8001 8003; do port_ready=0 for i in $(seq 1 15); do code=$(curl -so /dev/null -w '%{http_code}' "http://$service_host:$port/health" 2>/dev/null) || code=0 diff --git a/.gitea/workflows/integration-tests.yml b/.gitea/workflows/integration-tests.yml index f3f29109..ca7b12df 100644 --- a/.gitea/workflows/integration-tests.yml +++ b/.gitea/workflows/integration-tests.yml @@ -89,7 +89,7 @@ jobs: run: | echo "Waiting for services..." services_available=true - for port in 9001 8001 8003 8006; do + for port in 8011 8001 8003 8006; do port_ready=0 for i in $(seq 1 15); do code=$(curl -so /dev/null -w '%{http_code}' "http://localhost:$port/health" 2>/dev/null) || code=0 @@ -144,7 +144,7 @@ jobs: run: | cd "${{ env.WORKSPACE }}/repo" source venv/bin/activate - export PYTHONPATH="$PWD/cli:$PWD/apps/agent-coordinator/src:$PWD/apps/wallet/src:$PWD/apps/exchange/src:$PYTHONPATH" + export PYTHONPATH="$PWD/cli:$PWD/apps/coordinator-api/src:$PWD/apps/wallet/src:$PWD/apps/exchange/src:$PYTHONPATH" # Skip if services not available if [ "${{ steps.wait-services.outputs.services_available }}" != "true" ]; then diff --git a/.gitea/workflows/production-tests.yml b/.gitea/workflows/production-tests.yml index 0a549ea2..a255e8a9 100644 --- a/.gitea/workflows/production-tests.yml +++ b/.gitea/workflows/production-tests.yml @@ -5,7 +5,7 @@ on: branches: [main, develop] paths: - 'tests/production/**' - - 'apps/agent-coordinator/**' + - 'apps/coordinator-api/**' - '.gitea/workflows/production-tests.yml' pull_request: branches: [main, develop] @@ -73,20 +73,20 @@ jobs: - name: Start agent coordinator run: | cd "${{ env.WORKSPACE }}/repo" - export PYTHONPATH="apps/agent-coordinator/src:$PYTHONPATH" + export PYTHONPATH="apps/coordinator-api/src:$PYTHONPATH" - echo "Ensuring default port 9001 is available..." + echo "Ensuring default port 8011 is available..." pkill -f "uvicorn app.main:app" 2>/dev/null || true if command -v lsof >/dev/null 2>&1; then - pids=$(lsof -tiTCP:9001 -sTCP:LISTEN || true) + pids=$(lsof -tiTCP:8011 -sTCP:LISTEN || true) if [ -n "$pids" ]; then - echo "⚠️ Port 9001 already in use by PID(s): $pids; terminating" + echo "⚠️ Port 8011 already in use by PID(s): $pids; terminating" kill $pids 2>/dev/null || true sleep 2 fi - if lsof -tiTCP:9001 -sTCP:LISTEN >/dev/null 2>&1; then - echo "❌ Port 9001 is still in use; aborting startup" - lsof -iTCP:9001 -sTCP:LISTEN || true + if lsof -tiTCP:8011 -sTCP:LISTEN >/dev/null 2>&1; then + echo "❌ Port 8011 is still in use; aborting startup" + lsof -iTCP:8011 -sTCP:LISTEN || true exit 1 fi fi @@ -94,38 +94,38 @@ jobs: # Start agent coordinator in background nohup env PYTHONUNBUFFERED=1 venv/bin/uvicorn app.main:app \ --host 0.0.0.0 \ - --port 9001 \ + --port 8011 \ --log-level info \ - > /tmp/agent-coordinator.log 2>&1 & + > /tmp/coordinator-api.log 2>&1 & - echo $! > /tmp/agent-coordinator.pid + echo $! > /tmp/coordinator-api.pid sleep 2 - if ! kill -0 "$(cat /tmp/agent-coordinator.pid)" 2>/dev/null; then - echo "❌ Agent coordinator exited during startup" - cat /tmp/agent-coordinator.log + if ! kill -0 "$(cat /tmp/coordinator-api.pid)" 2>/dev/null; then + echo "❌ Coordinator API exited during startup" + cat /tmp/coordinator-api.log exit 1 fi - echo "✅ Agent coordinator started (PID: $(cat /tmp/agent-coordinator.pid))" + echo "✅ Coordinator API started (PID: $(cat /tmp/coordinator-api.pid))" - - name: Wait for agent coordinator ready + - name: Wait for coordinator API ready run: | - echo "Waiting for agent coordinator on port 9001..." + echo "Waiting for coordinator API on port 8011..." for i in $(seq 1 30); do - code=$(curl -so /dev/null -w '%{http_code}' "http://localhost:9001/health" 2>/dev/null) || code=0 + code=$(curl -so /dev/null -w '%{http_code}' "http://localhost:8011/health" 2>/dev/null) || code=0 if [ "$code" -ge 200 ] && [ "$code" -lt 600 ]; then - echo "✅ Agent coordinator ready (HTTP $code)" + echo "✅ Coordinator API ready (HTTP $code)" exit 0 fi sleep 2 done - echo "❌ Agent coordinator not ready" - cat /tmp/agent-coordinator.log + echo "❌ Coordinator API not ready" + cat /tmp/coordinator-api.log exit 1 - name: Run production tests run: | cd "${{ env.WORKSPACE }}/repo" - export PYTHONPATH="apps/agent-coordinator/src:$PYTHONPATH" + export PYTHONPATH="apps/coordinator-api/src:$PYTHONPATH" # Test both chains export CHAINS="ait-mainnet,ait-testnet" @@ -138,20 +138,20 @@ jobs: echo "✅ Production tests completed" - - name: Agent coordinator logs + - name: Print coordinator API logs if: always() run: | - if [ -f /tmp/agent-coordinator.log ]; then - echo "=== Agent Coordinator Logs ===" - cat /tmp/agent-coordinator.log + if [ -f /tmp/coordinator-api.log ]; then + echo "=== Coordinator API Logs ===" + cat /tmp/coordinator-api.log fi - - name: Cleanup + - name: Cleanup coordinator API if: always() run: | - if [ -f /tmp/agent-coordinator.pid ]; then - kill $(cat /tmp/agent-coordinator.pid) 2>/dev/null || true - rm -f /tmp/agent-coordinator.pid + if [ -f /tmp/coordinator-api.pid ]; then + kill $(cat /tmp/coordinator-api.pid) 2>/dev/null || true + rm -f /tmp/coordinator-api.pid fi pkill -f "uvicorn app.main:app" 2>/dev/null || true redis-cli shutdown 2>/dev/null || true diff --git a/.gitea/workflows/python-tests.yml b/.gitea/workflows/python-tests.yml index 747030a5..4c2aa70d 100644 --- a/.gitea/workflows/python-tests.yml +++ b/.gitea/workflows/python-tests.yml @@ -76,7 +76,7 @@ jobs: venv/bin/python -m pip install -e packages/py/aitbc-sdk/ venv/bin/python -m pip install -e packages/py/aitbc-agent-sdk/ - export PYTHONPATH="$PWD/apps/agent-coordinator/src:$PWD/apps/blockchain-node/src:$PWD/apps/wallet/src:$PWD/packages/py/aitbc-crypto/src:$PWD/packages/py/aitbc-sdk/src:$PWD/packages/py/aitbc-agent-sdk/src:$PWD:$PYTHONPATH" + export PYTHONPATH="$PWD/apps/coordinator-api/src:$PWD/apps/blockchain-node/src:$PWD/apps/wallet/src:$PWD/packages/py/aitbc-crypto/src:$PWD/packages/py/aitbc-sdk/src:$PWD/packages/py/aitbc-agent-sdk/src:$PWD:$PYTHONPATH" venv/bin/python -m pytest tests/archived_phase_tests/ \ tests/cross_phase/ \ @@ -90,16 +90,16 @@ jobs: run: | cd "${{ env.WORKSPACE }}/repo" - export PYTHONPATH="$PWD/apps/agent-coordinator:$PWD/apps/agent-coordinator/src:$PWD/packages/py/aitbc-crypto/src:$PWD/packages/py/aitbc-sdk/src:$PWD:$PYTHONPATH" + export PYTHONPATH="$PWD/apps/coordinator-api:$PWD/apps/coordinator-api/src:$PWD/packages/py/aitbc-crypto/src:$PWD/packages/py/aitbc-sdk/src:$PWD:$PYTHONPATH" # Test if packages are importable venv/bin/python -c "import aitbc_crypto; print('✅ aitbc_crypto imported')" venv/bin/python -c "import aitbc_sdk; print('✅ aitbc_sdk imported')" - venv/bin/python -c "import src.app; print('✅ agent-coordinator src.app imported')" - venv/bin/python -c "import app; print('✅ agent-coordinator app imported')" + venv/bin/python -c "import src.app; print('✅ coordinator-api src.app imported')" + venv/bin/python -c "import app; print('✅ coordinator-api app imported')" venv/bin/python -m pytest \ - apps/agent-coordinator/tests/test_communication.py \ + apps/coordinator-api/tests/test_communication.py \ packages/py/aitbc-crypto/tests/ \ packages/py/aitbc-sdk/tests/ \ -c /dev/null --rootdir "$PWD" --import-mode=importlib \ diff --git a/docs/apps/coordinator/coordinator-api.md b/docs/apps/coordinator/coordinator-api.md index 39535184..a421d314 100644 --- a/docs/apps/coordinator/coordinator-api.md +++ b/docs/apps/coordinator/coordinator-api.md @@ -4,6 +4,18 @@ FastAPI service that accepts client compute jobs, matches miners, and tracks job lifecycle for the AITBC network. +## API Versioning + +All business logic endpoints use the `/v1` prefix for consistent versioning. The API structure follows `/v1/{router}/{endpoint}` pattern. + +### Endpoint Structure + +- **Business logic endpoints**: `/v1/{router}/{endpoint}` (e.g., `/v1/marketplace/offers`, `/v1/governance/proposals`) +- **CLI compatibility routes**: `/api/v1/{router}/{endpoint}` (e.g., `/api/v1/agents/executions`) - for CLI tools +- **Infrastructure endpoints**: No prefix (e.g., `/health`, `/docs`, `/metrics`) - for system operations + +This structure enables future versioning (`/v2`, etc.) while maintaining CLI compatibility and keeping infrastructure endpoints unversioned. + ## Marketplace Extensions Stage 2 introduces public marketplace endpoints exposed under `/v1/marketplace`: diff --git a/docs/architecture/3_coordinator-api.md b/docs/architecture/3_coordinator-api.md index e49ac030..1fdf26c3 100644 --- a/docs/architecture/3_coordinator-api.md +++ b/docs/architecture/3_coordinator-api.md @@ -35,7 +35,15 @@ SQLite database with Alembic migrations ## API Reference -The Coordinator API provides RESTful endpoints for all major operations. +The Coordinator API provides RESTful endpoints for all major operations. All business logic endpoints use the `/v1` prefix for consistent versioning. + +### API Versioning Structure + +- **Business logic endpoints**: `/v1/{router}/{endpoint}` (e.g., `/v1/client/jobs`, `/v1/miner/register`) +- **CLI compatibility routes**: `/api/v1/{router}/{endpoint}` (e.g., `/api/v1/agents/executions`) - for CLI tools +- **Infrastructure endpoints**: No prefix (e.g., `/health`, `/docs`, `/metrics`) - for system operations + +This structure enables future versioning (`/v2`, etc.) while maintaining CLI compatibility. ### Client Endpoints