AITBC System Flow

Overview Diagram

Component Interactions

Detailed Flow Sequence

1. CLI Wrapper Execution

User Command:

./scripts/aitbc-cli.sh submit inference --prompt "What is machine learning?" --model llama3.2:latest

Internal Process:

1. Bash script (aitbc-cli.sh) parses arguments
2. Sets environment variables:
   • AITBC_URL=http://127.0.0.1:18000
   • CLIENT_KEY=client_dev_key_1
3. Calls Python client: python3 cli/client.py --url $AITBC_URL --api-key $CLIENT_KEY submit inference --prompt "..."

2. Python Client Processing

File: /cli/client.py

Steps:

1. Parse command-line arguments
2. Prepare job submission payload:

   {
     "type": "inference",
     "prompt": "What is machine learning?",
     "model": "llama3.2:latest",
     "client_key": "client_dev_key_1",
     "timestamp": "2025-01-29T14:50:00Z"
   }

3. Coordinator API Call

POST /v1/jobs
Host: 127.0.0.1:18000
Content-Type: application/json
X-Api-Key: client_dev_key_1

{
  "type": "inference",
  "prompt": "What is machine learning?",
  "model": "llama3.2:latest"
}

Coordinator Service (Port 18000):

1. Receives HTTP request
2. Validates API key and job parameters
3. Generates unique job ID: job_123456
4. Creates job record in database
5. Returns initial response:

   {
     "job_id": "job_123456",
     "status": "pending",
     "submitted_at": "2025-01-29T14:50:01Z"
   }

4. Blockchain Transaction

Coordinator → Blockchain Node (RPC Port 26657):

1. Coordinator creates blockchain transaction:

   {
     "type": "submit_job",
     "job_id": "job_123456",
     "client": "client_dev_key_1",
     "payload_hash": "abc123...",
     "reward": "100aitbc"
   }

2. RPC Call to blockchain node:

   curl -X POST http://127.0.0.1:26657 \
     -d '{
       "jsonrpc": "2.0",
       "method": "broadcast_tx_sync",
       "params": {"tx": "base64_encoded_transaction"}
     }'

3. Blockchain validates and includes transaction in next block
4. Transaction hash returned: 0xdef456...

5. Job Queue and Miner Assignment

Coordinator Internal Processing:

1. Job added to pending queue (Redis/Database)
2. Miner selection algorithm runs:
   • Check available miners
   • Select based on stake, reputation, capacity
3. Selected miner: miner_dev_key_1

POST /v1/jobs/assign
Host: 127.0.0.1:18001
Content-Type: application/json
X-Api-Key: admin_dev_key_1

{
  "job_id": "job_123456",
  "job_data": {
    "type": "inference",
    "prompt": "What is machine learning?",
    "model": "llama3.2:latest"
  },
  "reward": "100aitbc"
}

6. Miner Processing

Miner Daemon (Port 18001):

1. Receives job assignment
2. Updates job status to running
3. Notifies coordinator:

   POST /v1/jobs/job_123456/status
   {"status": "running", "started_at": "2025-01-29T14:50:05Z"}

7. Ollama Inference Request

POST /api/generate
Host: 127.0.0.1:11434
Content-Type: application/json

{
  "model": "llama3.2:latest",
  "prompt": "What is machine learning?",
  "stream": false,
  "options": {
    "temperature": 0.7,
    "num_predict": 500
  }
}

Ollama Processing:

1. Loads model into GPU memory
2. Processes prompt through neural network
3. Generates response text
4. Returns result:

   {
     "model": "llama3.2:latest",
     "response": "Machine learning is a subset of artificial intelligence...",
     "done": true,
     "total_duration": 12500000000,
     "prompt_eval_count": 15,
     "eval_count": 150
   }

8. Result Submission to Coordinator

POST /v1/jobs/job_123456/complete
Host: 127.0.0.1:18000
Content-Type: application/json
X-Miner-Key: miner_dev_key_1

{
  "job_id": "job_123456",
  "result": "Machine learning is a subset of artificial intelligence...",
  "metrics": {
    "compute_time": 12.5,
    "tokens_generated": 150,
    "gpu_utilization": 0.85
  },
  "proof": {
    "hash": "hash_of_result",
    "signature": "miner_signature"
  }
}

9. Receipt Generation

Coordinator Processing:

1. Verifies miner's proof
2. Calculates payment: 12.5 seconds × 0.02 AITBC/second = 0.25 AITBC
3. Creates receipt:

   {
     "receipt_id": "receipt_789",
     "job_id": "job_123456",
     "client": "client_dev_key_1",
     "miner": "miner_dev_key_1",
     "amount_paid": "0.25aitbc",
     "result_hash": "hash_of_result",
     "block_height": 12345,
     "timestamp": "2025-01-29T14:50:18Z"
   }

10. Blockchain Receipt Recording

Coordinator → Blockchain (RPC Port 26657):
{
  "type": "record_receipt",
  "receipt": {
    "receipt_id": "receipt_789",
    "job_id": "job_123456",
    "payment": "0.25aitbc"
  }
}

11. Client Polling for Result

CLI Client Status Check:

./scripts/aitbc-cli.sh status job_123456

GET /v1/jobs/job_123456
Host: 127.0.0.1:18000
X-Api-Key: client_dev_key_1

{
  "job_id": "job_123456",
  "status": "completed",
  "result": "Machine learning is a subset of artificial intelligence...",
  "receipt_id": "receipt_789",
  "completed_at": "2025-01-29T14:50:18Z"
}

12. Final Output to User

CLI displays:

Job ID: job_123456
Status: completed
Result: Machine learning is a subset of artificial intelligence...
Receipt: receipt_789
Completed in: 17 seconds
Cost: 0.25 AITBC

System Components Summary

Message Flow Timeline

Error Handling Paths

Security Considerations

• API Keys: Each request authenticated with X-Api-Key header
• Proof of Work: Miner provides cryptographic proof of computation
• Payment Escrow: Tokens held in smart contract until completion
• Rate Limiting: Coordinator limits requests per client

Related Documentation

• Coordinator API Documentation - Detailed API reference for the coordinator service
• Blockchain Node Documentation - Learn about the blockchain node and RPC API
• Miner Documentation - Guide to setting up and running a miner
• Client Documentation - Using the CLI and Python client
• System Components - Overview of all AITBC components
• Full Documentation - Complete technical documentation

Monitoring Points

• Coordinator logs all API calls to /var/log/aitbc/coordinator.log
• Miner logs GPU utilization to /var/log/aitbc/miner.log
• Blockchain logs all transactions to /var/log/aitbc/node.log
• Prometheus metrics available at http://localhost:9090/metrics