Skip to content

Development‐Guide

Jump to bottom
AGI Corp edited this page Mar 8, 2026 · 1 revision

Development Guide

🛠️ Overview

This guide walks through setting up the Web4AGI development environment, testing protocols, debugging procedures, and contributing to the codebase.

💻 Prerequisites

System Requirements

  • OS: macOS 13+, Ubuntu 20.04+, or Windows 11 with WSL2
  • Node.js: v18.0.0 or higher
  • Python: 3.10 or higher
  • Docker: 24.0+ (optional but recommended)
  • Git: 2.38+

Required Accounts & Keys

  1. Sentient Foundation API - Sign up at sentientfoundation.ai
  2. x402 Wallet - Create at x402.org
  3. Ethereum Testnet ETH - Get from Goerli faucet
  4. OpenAI API - For fallback models

🚀 Local Setup

Step 1: Clone the Repository

git clone https://github.com/AGI-Corporation/Web4AGI.git
cd Web4AGI

Step 2: Install Node.js Dependencies

# Install frontend dependencies
npm install

# Verify Next.js works
npm run build

Step 3: Set Up Python Environment

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install Python dependencies
pip install -r requirements.txt

# Install development dependencies
pip install -r requirements-dev.txt

Step 4: Configure Environment Variables

# Copy example environment file
cp .env.example .env

# Edit with your values
nano .env

Required variables:

# Sentient Foundation
SENTIENT_API_KEY=sf-your-key-here
SENTIENT_BASE_URL=https://api.sentientfoundation.ai/v1
SENTIENT_MODEL=sentient-70b

# x402 Protocol (Use testnet keys for development)
X402_PRIVATE_KEY=0x-your-private-key
X402_GATEWAY=https://goerli.x402.org/api/v1
X402_NETWORK=goerli

# Route.X MCP
ROUTE_X_BASE=http://localhost:8001
MCP_SERVER_URL=ws://localhost:8001/mcp

# Database
DATABASE_URL=postgresql://localhost:5432/web4agi_dev
REDIS_URL=redis://localhost:6379

# Ethereum
ETH_RPC_URL=https://goerli.infura.io/v3/your-infura-key
USLC_CONTRACT_ADDRESS=0x-testnet-usdc-address

Step 5: Start Local Services

# Start PostgreSQL and Redis using Docker
docker-compose up -d postgres redis

# Run database migrations
alembic upgrade head

# Seed test data
python scripts/seed_dev_data.py

Step 6: Start Development Servers

# Terminal 1: Backend API
python src/main.py --reload

# Terminal 2: MCP Server (Route.X)
python src/mcp_server.py

# Terminal 3: Frontend
npm run dev

# Terminal 4: Agent workers (optional)
python src/agent_worker.py --parcels 5

Step 7: Verify Setup

# Check API health
curl http://localhost:8001/health

# Check MCP server
curl http://localhost:8001/mcp/status

# Open dashboard
open http://localhost:3000

🔧 Project Structure

Web4AGI/
├── src/
│   ├── agents/              # Agent core logic
│   │   ├── parcel_agent.py  # Main agent class
│   │   ├── trading.py       # Trading logic
│   │   ├── contracts.py     # Smart contract interaction
│   │   └── memory.py        # Agent memory management
│   ├── api/                 # FastAPI routes
│   │   ├── parcels.py       # Parcel CRUD endpoints
│   │   ├── trades.py        # Trading endpoints
│   │   ├── contracts.py     # Contract endpoints
│   │   └── websocket.py     # WS real-time feed
│   ├── blockchain/          # Web3 integration
│   │   ├── wallet.py        # x402 wallet
│   │   ├── contracts/       # Solidity contracts
│   │   └── stablecoin.py    # USDC/USDT management
│   ├── mcp/                 # MCP server
│   │   ├── server.py        # MCP server setup
│   │   ├── tools.py         # Tool definitions
│   │   └── resources.py     # Resource handlers
│   ├── models/              # Database models
│   ├── main.py              # FastAPI app entry
│   └── agent_worker.py      # Agent process runner
├── frontend/
│   ├── app/                 # Next.js App Router
│   ├── components/          # React components
│   ├── hooks/               # Custom React hooks
│   └── lib/                 # Utility functions
├── contracts/               # Hardhat Solidity project
├── tests/                   # All test files
│   ├── unit/
│   ├── integration/
│   └── e2e/
├── scripts/                 # Utility scripts
├── docker-compose.yml
├── requirements.txt
├── package.json
└── .env.example

🧪 Testing

Running All Tests

# Python tests
pytest tests/ -v --cov=src

# Frontend tests
npm test

# Smart contract tests
cd contracts && npx hardhat test

Unit Tests

# Test specific module
pytest tests/unit/test_agent.py -v
pytest tests/unit/test_trading.py -v

# With coverage report
pytest tests/unit/ --cov=src --cov-report=html
open htmlcov/index.html

Integration Tests

# Requires running services
pytest tests/integration/ -v

# MCP integration tests
pytest tests/integration/test_mcp.py -v

End-to-End Tests

# Start all services first
docker-compose up -d

# Run E2E tests
npm run test:e2e

# Playwright tests
npx playwright test

🐛 Debugging

Common Issues

Agent Not Starting

# Check logs
tail -f logs/agent.log

# Debug mode
LOG_LEVEL=DEBUG python src/agent_worker.py

# Test Sentient Foundation connectivity
python -c "from src.agents.parcel_agent import test_connection; test_connection()"

Wallet Connection Issues

# Verify x402 connection
python -c "
from src.blockchain.wallet import ParcelWallet
w = ParcelWallet(os.getenv('X402_PRIVATE_KEY'))
print('Balance:', w.get_balance())
"

MCP Server Not Responding

# Check Route.X server status
curl http://localhost:8001/health

# Restart MCP server
pkill -f mcp_server.py && python src/mcp_server.py &

# Test MCP tools
python -c "
from src.mcp.server import test_tools
test_tools()
"

Debug Logging

import logging
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s %(name)s %(levelname)s %(message)s'
)

# Enable specific module debug logs
logging.getLogger('web4agi.agent').setLevel(logging.DEBUG)
logging.getLogger('web4agi.trading').setLevel(logging.DEBUG)
logging.getLogger('web4agi.mcp').setLevel(logging.DEBUG)

🚀 Deployment

Docker Deployment

# Build images
docker-compose build

# Start production stack
docker-compose -f docker-compose.prod.yml up -d

# Scale agents
docker-compose -f docker-compose.prod.yml scale agent-worker=10

Environment Configuration for Production

# Switch to mainnet
X402_GATEWAY=https://x402.org/api/v1
X402_NETWORK=mainnet

# Use production Sentient model
SENTIENT_MODEL=sentient-70b

# Production database
DATABASE_URL=postgresql://prod-host:5432/web4agi

🤝 Contributing

Workflow

  1. Fork the repository on GitHub
  2. Create a feature branch: git checkout -b feature/my-feature
  3. Write tests for your changes
  4. Implement your feature or fix
  5. Run all tests: pytest && npm test
  6. Commit with descriptive message: git commit -m 'feat: add parcel teleportation'
  7. Push to your fork: git push origin feature/my-feature
  8. Open a Pull Request against main

Commit Convention

feat: add new feature
fix: resolve bug in trading engine
docs: update API reference
test: add tests for wallet integration
refactor: optimize agent decision loop
chore: update dependencies

Code Standards

# Python formatting
black src/ tests/
flake8 src/ tests/
mypy src/

# JavaScript/TypeScript
npm run lint
npm run format

📚 Related Pages

🌐 Sapient OS ~AGI Corp Wiki

📖 Getting Started

🤖 Core Systems

💰 Economy & Blockchain

📝 Reference

🔗 External Links

🚨 Open Issues

Clone this wiki locally