Local Development¶

Guide to setting up and running Adaptive Sentience locally for development.

Prerequisites¶

Required Software¶

Python 3.9+
Git
Code editor (VS Code, PyCharm, etc.)

Optional Software¶

Docker (for containerized testing)
Redis (for shared state in multi-gateway setups)
PostgreSQL (for persistent storage)

Initial Setup¶

1. Clone Repository¶

git clone https://github.com/adaptivesentience/agent_mesh.git
cd agent_mesh

2. Create Virtual Environment¶

# Create venv
python3 -m venv venv

# Activate (macOS/Linux)
source venv/bin/activate

# Activate (Windows)
venv\Scripts\activate

3. Install Dependencies¶

# Install production dependencies
pip install -r requirements.txt

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

4. Configure Environment¶

# Copy example config
cp .env.example .env

# Edit .env with your settings
nano .env

Running Locally¶

Terminal 1: Gateway¶

# Activate venv
source venv/bin/activate

# Set environment variables
export DWO_NODE_LAT=37.7749
export DWO_NODE_LON=-122.4194
export DWO_NODE_ACCURACY_M=50

# Start gateway
python -m gateway.http_gateway --host 127.0.0.1 --port 8787 --dev-token

Expected output:

============================================================
Gateway Starting
============================================================
Host: http://127.0.0.1:8787
Dev token: enabled
Trust mode: TOFU
============================================================
INFO:     Uvicorn running on http://127.0.0.1:8787

Terminal 2: Edge Node¶

# Activate venv
source venv/bin/activate

# Start edge node
cd edge_node
NODE_PORT=8000 python node.py

Expected output:

============================================================
Edge Node Starting
============================================================
Node ID: local:abc123
Host: 0.0.0.0:8000
============================================================
INFO:     Uvicorn running on http://0.0.0.0:8000

Terminal 3: Test Commands¶

# Activate venv
source venv/bin/activate

# Health checks
curl http://127.0.0.1:8787/health
curl http://127.0.0.1:8000/health

# Mesh scan
curl http://127.0.0.1:8787/v1/mesh_scan | jq

# Tool call
curl -X POST http://127.0.0.1:8787/v1/tool/call \
  -H "Content-Type: application/json" \
  -d '{
    "target": {"kind": "local"},
    "tool_name": "pii_redact",
    "tool_args": {"text": "Contact john@example.com"}
  }' | jq

Development Workflow¶

Watch for Changes¶

Use tools like watchdog or nodemon equivalent:

# Install watchdog
pip install watchdog

# Watch and restart gateway on changes
watchmedo auto-restart --patterns="*.py" --recursive \
  python -m gateway.http_gateway --host 127.0.0.1 --port 8787 --dev-token

Hot Reload (FastAPI)¶

FastAPI supports hot reload in development:

# Gateway with auto-reload
uvicorn gateway.http_gateway:app --reload --host 127.0.0.1 --port 8787

# Edge node with auto-reload
cd edge_node
uvicorn node:app --reload --host 0.0.0.0 --port 8000

IDE Setup¶

VS Code¶

Recommended extensions: - Python - Pylance - autopep8 - GitLens

Settings (.vscode/settings.json):

{
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": true,
  "python.formatting.provider": "black",
  "python.testing.pytestEnabled": true,
  "editor.formatOnSave": true,
  "editor.rulers": [100]
}

Launch configuration (.vscode/launch.json):

href="#__codelineno-12-1">{ "version": "0.2.0", "configurations": [ { "name": "Gateway", "type": "python", "request": "launch", "module": "gateway.http_gateway", "args": ["--host", "127.0.0.1", "--port", "8787", "--dev-token"], "env": { "DWO_NODE_LAT": "37.7749", "DWO_NODE_LON": "-122.4194" } }, { "name": "Edge Node", "type": "python", "request": "launch", "program": "${workspaceFolder}/edge_node/node.py", "cwd": "${workspaceFolder}/edge_node", "env": { "NODE_PORT": "8000" } }, { "name": "pytest", "type": "python", "request": "launch", "module": "pytest", "args": ["-v"] } ] }

PyCharm¶

Run Configurations:

Gateway:
Script: gateway.http_gateway
Module name: checked
Parameters: --host 127.0.0.1 --port 8787 --dev-token
Environment variables: DWO_NODE_LAT=37.7749;DWO_NODE_LON=-122.4194
Edge Node:
Script: edge_node/node.py
Working directory: edge_node/
Environment variables: NODE_PORT=8000
Tests:
Target: pytest
Options: -v

Debugging¶

Print Debugging¶

# Add debug prints
print(f"DEBUG: selected node: {selected_node}")

# View output (with -s flag)
pytest -s tests/test_gateway.py

Python Debugger (pdb)¶

# Add breakpoint
import pdb; pdb.set_trace()

# Or use built-in breakpoint()
breakpoint()

pdb commands: - n - next line - s - step into function - c - continue execution - l - list source code - p variable - print variable - q - quit

VS Code Debugger¶

Set breakpoint (click left of line number)
Press F5 or select Run → Start Debugging
Use debug toolbar to step through code

Database Setup (Optional)¶

PostgreSQL¶

For persistent storage:

# Install PostgreSQL
brew install postgresql  # macOS
sudo apt install postgresql  # Linux

# Start PostgreSQL
brew services start postgresql  # macOS
sudo service postgresql start  # Linux

# Create database
createdb agent_mesh

# Configure connection
export DATABASE_URL="postgresql://localhost/agent_mesh"

Redis¶

For shared gateway state:

# Install Redis
brew install redis  # macOS
sudo apt install redis  # Linux

# Start Redis
brew services start redis  # macOS
sudo service redis-server start  # Linux

# Configure connection
export REDIS_URL="redis://localhost:6379"

Docker Development¶

Build Image¶

# Build gateway image
docker build -t agent-mesh-gateway -f Dockerfile.gateway .

# Build edge node image
docker build -t agent-mesh-edge-node -f Dockerfile.edge-node .

Run with Docker Compose¶

# docker-compose.yml

version: '3.8'

services:
  gateway:
    image: agent-mesh-gateway
    ports:
      - "8787:8787"
    environment:
      - DWO_NODE_LAT=37.7749
      - DWO_NODE_LON=-122.4194
      - TRUST_MODE=tofu
    volumes:
      - ./trust:/app/trust
      - ./audit:/app/audit

  edge-node:
    image: agent-mesh-edge-node
    ports:
      - "8000:8000"
    environment:
      - NODE_PORT=8000
    depends_on:
      - gateway

# Start services
docker-compose up

# Stop services
docker-compose down

Common Tasks¶

Running Demos¶

# LLM client demo
python demos/llm_client_demo.py

# Trust pairing demo
python demos/trust_pairing_demo.py

# Map view demo
python demos/map_view_demo.py

Generating Test Data¶

# Generate provisioning bundle
python -m provisioning.generate_keys --output gateway_identity.pem
python -m provisioning.create_bundle \
  --gateway-key gateway_identity.pem \
  --node-id test_node \
  --output bundle.json

Cleaning Up¶

# Remove generated keys
rm -rf keys/ trust/ *.pem

# Remove logs
rm -rf logs/ audit/ *.log

# Remove cache
find . -type d -name __pycache__ -exec rm -rf {} +
find . -type f -name "*.pyc" -delete

Troubleshooting¶

Port Already in Use¶

# Find process using port
lsof -i :8787

# Kill process
kill -9 <PID>

# Or use different port
python -m gateway.http_gateway --port 8788

Import Errors¶

# Ensure venv is activated
source venv/bin/activate

# Reinstall dependencies
pip install -r requirements.txt

# Add project to PYTHONPATH
export PYTHONPATH="${PYTHONPATH}:$(pwd)"

Network Issues¶

# Check gateway is accessible
curl http://127.0.0.1:8787/health

# Check node is accessible
curl http://127.0.0.1:8000/health

# Check multicast
python -c "import socket; s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM); s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1); s.bind(('', 9999)); print('Multicast OK')"

# Disable firewall (temporarily)
sudo ufw disable  # Linux

Performance Profiling¶

Profile Code¶

# Use cProfile
python -m cProfile -s cumtime -m gateway.http_gateway > profile.txt

# Use line_profiler
pip install line_profiler
kernprof -l -v script.py

Memory Profiling¶

# Use memory_profiler
pip install memory_profiler
python -m memory_profiler script.py

Next Steps¶

Contributing - Contribution guidelines
Running Tests - Test suite
Architecture - System architecture
API Reference - API documentation