oib/aitbc
1
0
Fork 0
Code Issues Pull Requests Actions 9 Packages Projects Releases Wiki Activity

docs: automated documentation update and phase 8 archiving

Browse Source
This commit is contained in:
oib
2026-02-26 19:17:53 +01:00
parent 825f157749
commit 88971a3216
20 changed files with 4327 additions and 1085 deletions
Download Patch File Download Diff File Expand all files Collapse all files

702
docs/12_issues/completed_phases/15_deployment_guide.md Normal file
View File

@@ -0,0 +1,702 @@
# Agent Economics System Deployment Guide
## Overview
This guide provides comprehensive instructions for deploying the OpenClaw Agent Economics Enhancement system, including all components: Reputation System, Performance-Based Reward Engine, P2P Trading Protocol, Marketplace Analytics Platform, and Certification & Partnership Programs.
## System Architecture
### Components Overview
```
┌─────────────────────────────────────────────────────────────┐
│ Agent Economics System │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Reputation │ │ Rewards │ │ P2P Trading │ │
│ │ System │ │ Engine │ │ Protocol │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Analytics │ │ Certification│ │ Integration & │ │
│ │ Platform │ │ & Partnerships│ │ Testing Layer │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Database Schema
The system uses SQLModel with PostgreSQL as the primary database:
- **Reputation Tables**: `agent_reputations`, `community_feedback`, `economic_profiles`
- **Reward Tables**: `reward_profiles`, `reward_calculations`, `reward_distributions`
- **Trading Tables**: `trade_requests`, `trade_matches`, `trade_negotiations`, `trade_agreements`
- **Analytics Tables**: `market_metrics`, `market_insights`, `analytics_reports`
- **Certification Tables**: `agent_certifications`, `partnership_programs`, `achievement_badges`
## Prerequisites
### System Requirements
- **Operating System**: Linux (Ubuntu 20.04+ recommended)
- **Python**: 3.13.5+
- **Database**: PostgreSQL 14+
- **Memory**: Minimum 8GB RAM (16GB+ recommended)
- **Storage**: Minimum 50GB SSD (100GB+ recommended)
- **Network**: Stable internet connection for blockchain integration
### Software Dependencies
```bash
# Python dependencies
pip install -r requirements.txt
# Database setup
sudo apt-get install postgresql postgresql-contrib
# Additional system packages
sudo apt-get install build-essential libpq-dev
```
### Environment Configuration
Create `.env` file with the following variables:
```env
# Database Configuration
DATABASE_URL=postgresql://username:password@localhost:5432/aitbc_economics
DATABASE_POOL_SIZE=20
DATABASE_MAX_OVERFLOW=30
# Redis Configuration (for caching)
REDIS_URL=redis://localhost:6379/0
REDIS_POOL_SIZE=10
# Blockchain Configuration
BLOCKCHAIN_RPC_URL=http://localhost:8545
BLOCKCHAIN_CONTRACT_ADDRESS=0x1234567890123456789012345678901234567890
BLOCKCHAIN_PRIVATE_KEY=your_private_key_here
# API Configuration
API_HOST=0.0.0.0
API_PORT=8000
API_WORKERS=4
API_TIMEOUT=30
# Analytics Configuration
ANALYTICS_BATCH_SIZE=1000
ANALYTICS_RETENTION_DAYS=90
ANALYTICS_REFRESH_INTERVAL=300
# Security Configuration
SECRET_KEY=your_secret_key_here
JWT_ALGORITHM=HS256
JWT_EXPIRE_MINUTES=1440
# Monitoring Configuration
LOG_LEVEL=INFO
LOG_FORMAT=json
METRICS_PORT=9090
```
## Installation Steps
### 1. Database Setup
```bash
# Create database
sudo -u postgres createdb aitbc_economics
# Create user
sudo -u postgres createuser --interactive aitbc_user
# Grant privileges
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE aitbc_economics TO aitbc_user;"
```
### 2. Schema Migration
```bash
# Run database migrations
python -m alembic upgrade head
# Verify schema
python -m alembic current
```
### 3. Service Configuration
Create systemd service files for each component:
```ini
# /etc/systemd/system/aitbc-reputation.service
[Unit]
Description=AITBC Reputation System
After=network.target postgresql.service
[Service]
Type=exec
User=aitbc
Group=aitbc
WorkingDirectory=/opt/aitbc/apps/coordinator-api
Environment=PYTHONPATH=/opt/aitbc
ExecStart=/opt/aitbc/venv/bin/python -m uvicorn app.routers.reputation:router --host 0.0.0.0 --port 8001
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
```
```ini
# /etc/systemd/system/aitbc-rewards.service
[Unit]
Description=AITBC Reward Engine
After=network.target postgresql.service
[Service]
Type=exec
User=aitbc
Group=aitbc
WorkingDirectory=/opt/aitbc/apps/coordinator-api
Environment=PYTHONPATH=/opt/aitbc
ExecStart=/opt/aitbc/venv/bin/python -m uvicorn app.routers.rewards:router --host 0.0.0.0 --port 8002
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
```
### 4. Load Balancer Configuration
```nginx
# /etc/nginx/sites-available/aitbc-economics
upstream economics_backend {
server 127.0.0.1:8001;
server 127.0.0.1:8002;
server 127.0.0.1:8003;
server 127.0.0.1:8004;
server 127.0.0.1:8005;
}
server {
listen 80;
server_name economics.aitbc.bubuit.net;
location / {
proxy_pass http://economics_backend;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# Timeouts
proxy_connect_timeout 30s;
proxy_send_timeout 30s;
proxy_read_timeout 30s;
}
# Health check endpoint
location /health {
proxy_pass http://economics_backend/health;
access_log off;
}
}
```
### 5. Service Startup
```bash
# Enable and start services
sudo systemctl enable aitbc-reputation
sudo systemctl enable aitbc-rewards
sudo systemctl enable aitbc-trading
sudo systemctl enable aitbc-analytics
sudo systemctl enable aitbc-certification
# Start services
sudo systemctl start aitbc-reputation
sudo systemctl start aitbc-rewards
sudo systemctl start aitbc-trading
sudo systemctl start aitbc-analytics
sudo systemctl start aitbc-certification
# Check status
sudo systemctl status aitbc-*
```
## Configuration Details
### Reputation System Configuration
```python
# config/reputation.py
REPUTATION_CONFIG = {
"trust_score_weights": {
"performance": 0.35,
"reliability": 0.25,
"community": 0.20,
"economic": 0.15,
"temporal": 0.05
},
"reputation_levels": {
"beginner": {"min_score": 0, "max_score": 399},
"novice": {"min_score": 400, "max_score": 599},
"intermediate": {"min_score": 600, "max_score": 799},
"advanced": {"min_score": 800, "max_score": 949},
"master": {"min_score": 950, "max_score": 1000}
},
"update_frequency": 3600, # 1 hour
"batch_size": 100
}
```
### Reward Engine Configuration
```python
# config/rewards.py
REWARD_CONFIG = {
"tiers": {
"bronze": {"min_points": 0, "multiplier": 1.0},
"silver": {"min_points": 1000, "multiplier": 1.2},
"gold": {"min_points": 5000, "multiplier": 1.5},
"platinum": {"min_points": 15000, "multiplier": 2.0},
"diamond": {"min_points": 50000, "multiplier": 3.0}
},
"bonus_types": {
"performance": {"weight": 0.4, "max_multiplier": 2.0},
"loyalty": {"weight": 0.25, "max_multiplier": 1.5},
"referral": {"weight": 0.2, "max_multiplier": 1.3},
"milestone": {"weight": 0.15, "max_multiplier": 1.8}
},
"distribution_frequency": 86400, # 24 hours
"batch_processing_limit": 1000
}
```
### Trading Protocol Configuration
```python
# config/trading.py
TRADING_CONFIG = {
"matching_weights": {
"price": 0.25,
"specifications": 0.20,
"timing": 0.15,
"reputation": 0.15,
"geography": 0.10,
"availability": 0.10,
"service_level": 0.05
},
"settlement_types": {
"immediate": {"fee_rate": 0.01, "processing_time": 300},
"escrow": {"fee_rate": 0.02, "processing_time": 1800},
"milestone": {"fee_rate": 0.025, "processing_time": 3600},
"subscription": {"fee_rate": 0.015, "processing_time": 600}
},
"negotiation_strategies": {
"aggressive": {"concession_rate": 0.02, "tolerance": 0.05},
"balanced": {"concession_rate": 0.05, "tolerance": 0.10},
"cooperative": {"concession_rate": 0.08, "tolerance": 0.15}
}
}
```
## Monitoring and Logging
### Health Check Endpoints
```python
# Health check implementation
@app.get("/health")
async def health_check():
return {
"status": "healthy",
"timestamp": datetime.utcnow().isoformat(),
"version": "1.0.0",
"services": {
"reputation": await check_reputation_health(),
"rewards": await check_rewards_health(),
"trading": await check_trading_health(),
"analytics": await check_analytics_health(),
"certification": await check_certification_health()
}
}
```
### Metrics Collection
```python
# Prometheus metrics setup
from prometheus_client import Counter, Histogram, Gauge
# Request metrics
REQUEST_COUNT = Counter('aitbc_requests_total', 'Total requests', ['method', 'endpoint'])
REQUEST_DURATION = Histogram('aitbc_request_duration_seconds', 'Request duration')
# Business metrics
ACTIVE_AGENTS = Gauge('aitbc_active_agents', 'Number of active agents')
TRANSACTION_VOLUME = Gauge('aitbc_transaction_volume', 'Total transaction volume')
REPUTATION_SCORES = Histogram('aitbc_reputation_scores', 'Reputation score distribution')
```
### Log Configuration
```python
# logging.yaml
version: 1
disable_existing_loggers: false
formatters:
json:
format: '%(asctime)s %(name)s %(levelname)s %(message)s'
class: pythonjsonlogger.jsonlogger.JsonFormatter
handlers:
console:
class: logging.StreamHandler
formatter: json
stream: ext://sys.stdout
file:
class: logging.handlers.RotatingFileHandler
formatter: json
filename: /var/log/aitbc/economics.log
maxBytes: 10485760 # 10MB
backupCount: 5
loggers:
aitbc:
level: INFO
handlers: [console, file]
propagate: false
root:
level: INFO
handlers: [console, file]
```
## Testing and Validation
### Pre-deployment Testing
```bash
# Run unit tests
pytest tests/unit/ -v --cov=app
# Run integration tests
pytest tests/integration/ -v --cov=app
# Run performance tests
pytest tests/performance/ -v --benchmark-only
# Run security tests
pytest tests/security/ -v
```
### Load Testing
```bash
# Install k6 for load testing
curl https://github.com/grafana/k6/releases/download/v0.47.0/k6-v0.47.0-linux-amd64.tar.gz -L | tar xvz
# Run load test
k6 run tests/load/api_load_test.js
```
### Data Validation
```python
# Data validation script
def validate_system_data():
"""Validate system data integrity"""
validation_results = {
"reputation_data": validate_reputation_data(),
"reward_data": validate_reward_data(),
"trading_data": validate_trading_data(),
"analytics_data": validate_analytics_data(),
"certification_data": validate_certification_data()
}
return all(validation_results.values())
```
## Security Considerations
### API Security
```python
# Security middleware
from fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware
from fastapi.middleware.trustedhost import TrustedHostMiddleware
app.add_middleware(HTTPSRedirectMiddleware)
app.add_middleware(TrustedHostMiddleware, allowed_hosts=["*.aitbc.bubuit.net"])
# Rate limiting
from slowapi import Limiter, _rate_limit_exceeded_handler
from slowapi.util import get_remote_address
limiter = Limiter(key_func=get_remote_address)
app.state.limiter = limiter
app.add_exception_handler(429, _rate_limit_exceeded_handler)
@app.get("/api/v1/reputation/{agent_id}")
@limiter.limit("100/minute")
async def get_reputation(agent_id: str):
pass
```
### Database Security
```sql
-- Database security setup
CREATE ROLE aitbc_app WITH LOGIN PASSWORD 'secure_password';
CREATE ROLE aitbc_readonly WITH LOGIN PASSWORD 'readonly_password';
-- Grant permissions
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO aitbc_app;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO aitbc_readonly;
-- Row level security
ALTER TABLE agent_reputations ENABLE ROW LEVEL SECURITY;
CREATE POLICY agent_reputation_policy ON agent_reputations
FOR ALL TO aitbc_app
USING (agent_id = current_setting('app.current_agent_id'));
```
### Blockchain Security
```python
# Blockchain security configuration
BLOCKCHAIN_CONFIG = {
"contract_address": os.getenv("BLOCKCHAIN_CONTRACT_ADDRESS"),
"private_key": os.getenv("BLOCKCHAIN_PRIVATE_KEY"),
"gas_limit": 300000,
"gas_price": 20, # gwei
"confirmations_required": 2,
"timeout_seconds": 300
}
```
## Backup and Recovery
### Database Backup
```bash
#!/bin/bash
# backup_database.sh
BACKUP_DIR="/var/backups/aitbc"
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="$BACKUP_DIR/economics_$DATE.sql"
# Create backup
pg_dump -h localhost -U aitbc_user -d aitbc_economics > $BACKUP_FILE
# Compress backup
gzip $BACKUP_FILE
# Remove old backups (keep last 7 days)
find $BACKUP_DIR -name "*.sql.gz" -mtime +7 -delete
echo "Backup completed: $BACKUP_FILE.gz"
```
### Recovery Procedures
```bash
#!/bin/bash
# restore_database.sh
BACKUP_FILE=$1
RESTORE_DB="aitbc_economics_restore"
if [ -z "$BACKUP_FILE" ]; then
echo "Usage: $0 <backup_file>"
exit 1
fi
# Create restore database
createdb $RESTORE_DB
# Restore from backup
gunzip -c $BACKUP_FILE | psql -h localhost -U aitbc_user -d $RESTORE_DB
echo "Database restored to $RESTORE_DB"
```
## Performance Optimization
### Database Optimization
```sql
-- Database performance tuning
-- PostgreSQL configuration recommendations
-- Memory settings
shared_buffers = 256MB
effective_cache_size = 1GB
work_mem = 4MB
maintenance_work_mem = 64MB
-- Connection settings
max_connections = 200
shared_preload_libraries = 'pg_stat_statements'
-- Logging settings
log_min_duration_statement = 1000
log_checkpoints = on
log_connections = on
log_disconnections = on
```
### Application Optimization
```python
# Performance optimization settings
PERFORMANCE_CONFIG = {
"database_pool_size": 20,
"database_max_overflow": 30,
"cache_ttl": 3600,
"batch_size": 1000,
"async_tasks": True,
"connection_timeout": 30,
"query_timeout": 60
}
```
### Caching Strategy
```python
# Redis caching configuration
CACHE_CONFIG = {
"reputation_cache_ttl": 3600, # 1 hour
"reward_cache_ttl": 1800, # 30 minutes
"trading_cache_ttl": 300, # 5 minutes
"analytics_cache_ttl": 600, # 10 minutes
"certification_cache_ttl": 7200 # 2 hours
}
```
## Troubleshooting
### Common Issues
1. **Database Connection Errors**
```bash
# Check PostgreSQL status
sudo systemctl status postgresql
# Check connection
psql -h localhost -U aitbc_user -d aitbc_economics
```
2. **High Memory Usage**
```bash
# Check memory usage
free -h
# Check process memory
ps aux --sort=-%mem | head -10
```
3. **Slow API Responses**
```bash
# Check API response times
curl -w "@curl-format.txt" -o /dev/null -s "http://localhost:8000/health"
```
### Debug Mode
```python
# Enable debug mode
DEBUG = os.getenv("DEBUG", "false").lower() == "true"
if DEBUG:
logging.basicConfig(level=logging.DEBUG)
app.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
```
## Maintenance
### Regular Maintenance Tasks
```bash
#!/bin/bash
# maintenance.sh
# Database maintenance
psql -h localhost -U aitbc_user -d aitbc_economics -c "VACUUM ANALYZE;"
# Log rotation
logrotate -f /etc/logrotate.d/aitbc
# Cache cleanup
redis-cli FLUSHDB
# Health check
curl -f http://localhost:8000/health || echo "Health check failed"
```
### Scheduled Tasks
```cron
# /etc/cron.d/aitbc-maintenance
# Daily maintenance at 2 AM
0 2 * * * aitbc /opt/aitbc/scripts/maintenance.sh
# Weekly backup on Sunday at 3 AM
0 3 * * 0 aitbc /opt/aitbc/scripts/backup_database.sh
# Monthly performance report
0 4 1 * * aitbc /opt/aitbc/scripts/generate_performance_report.sh
```
## Rollback Procedures
### Application Rollback
```bash
# Rollback to previous version
sudo systemctl stop aitbc-*
git checkout previous_version_tag
pip install -r requirements.txt
sudo systemctl start aitbc-*
```
### Database Rollback
```bash
# Rollback database to previous backup
./restore_database.sh /var/backups/aitbc/economics_20260226_030000.sql.gz
```
## Support and Contact
### Support Channels
- **Technical Support**: support@aitbc.bubuit.net
- **Documentation**: https://docs.aitbc.bubuit.net
- **Status Page**: https://status.aitbc.bubuit.net
- **Community Forum**: https://community.aitbc.bubuit.net
### Emergency Contacts
- **Critical Issues**: emergency@aitbc.bubuit.net
- **Security Issues**: security@aitbc.bubuit.net
- **24/7 Hotline**: +1-555-123-4567
---
**Version**: 1.0.0
**Last Updated**: February 26, 2026
**Next Review**: March 26, 2026