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

docs: enhance Ollama GPU test workflow, reorganize project structure, and fix pytest warnings

Browse Source 
- Upgrade ollama-gpu-provider skill to v2.0 with complete test workflow documentation
- Add comprehensive troubleshooting, monitoring commands, and CI/CD integration examples
- Update client.py default coordinator port from 8000 to 18000
- Clear currentissue.md and add usage guidelines for issue tracking
- Create dev-utils/ directory and move aitbc-pythonpath.pth from root
- Create docs/guides/ and docs
This commit is contained in:
oib
2026-01-29 13:20:09 +01:00
parent ff4554b9dd
commit b9688dacf3
18 changed files with 1247 additions and 129 deletions
Download Patch File Download Diff File Expand all files Collapse all files

218
.windsurf/skills/ollama-gpu-provider/SKILL.md
View File

@@ -1,39 +1,215 @@
---
name: ollama-gpu-provider
description: End-to-end Ollama prompt payment test against the GPU miner provider
version: 1.0.0
author: Cascade
tags: [gpu, miner, ollama, payments, receipts, test]
title: Ollama GPU Provider Complete Test Workflow
description: Complete end-to-end test workflow for Ollama GPU inference jobs including client submission, miner processing, receipt generation, payment processing, and blockchain recording
version: 2.0
author: AITBC Team
tags: [ollama, gpu, miner, testing, workflow, blockchain, payment]
---
# Ollama GPU Provider Test Skill
# Ollama GPU Provider Complete Test Workflow
This skill runs an end-to-end client → coordinator → GPU miner → receipt flow using an Ollama prompt.
This skill provides a comprehensive test workflow for verifying the entire Ollama GPU inference pipeline from client job submission through blockchain transaction recording.
## Overview
The test submits a prompt (default: "hello") to the coordinator via the host proxy, waits for completion, and verifies that the job result and signed receipt are returned.
The complete flow includes:
1. Client submits inference job to coordinator
2. GPU miner picks up and processes job via Ollama
3. Miner submits result with metrics
4. Coordinator generates signed receipt
5. Client processes payment to miner
6. Transaction recorded on blockchain
## Prerequisites
- Host GPU miner running and registered (RTX 4060 Ti + Ollama)
- Incus proxy forwarding `127.0.0.1:18000` → container `127.0.0.1:8000`
- Coordinator running in container (`coordinator-api.service`)
- Receipt signing key configured in `/opt/coordinator-api/src/.env`
## Test Command
### Required Services
- Coordinator API running on port 18000
- GPU miner service running (`aitbc-host-gpu-miner.service`)
- Ollama service running on port 11434
- Blockchain node accessible (local: 19000 or remote: aitbc.keisanki.net/rpc)
- Home directory wallets configured
### Configuration
```bash
python3 cli/test_ollama_gpu_provider.py --url http://127.0.0.1:18000 --prompt "hello"
# Verify services
./scripts/aitbc-cli.sh health
curl -s http://localhost:11434/api/tags
systemctl status aitbc-host-gpu-miner.service
```
## Expected Outcome
## Test Options
- Job reaches `COMPLETED`
- Output returned from Ollama
- Receipt present with a `receipt_id`
### Option 1: Basic API Test (No Payment)
```bash
# Simple test without blockchain
python3 cli/test_ollama_gpu_provider.py \
--url http://127.0.0.1:18000 \
--prompt "What is the capital of France?" \
--model llama3.2:latest
```
## Notes
### Option 2: Complete Workflow with Home Directory Users
```bash
# Full test with payment and blockchain
cd /home/oib/windsurf/aitbc/home
python3 test_ollama_blockchain.py
```
- Use `--timeout` to allow longer runs for large models.
- If the receipt is missing, verify `receipt_signing_key_hex` is set and restart the coordinator.
### Option 3: Manual Step-by-Step
```bash
# 1. Submit job
cd /home/oib/windsurf/aitbc/home
job_id=$(../cli/client.py submit inference \
--prompt "What is the capital of France?" \
--model llama3.2:latest | grep "Job ID" | awk '{print $3}')
# 2. Monitor progress
watch -n 2 "../cli/client.py status $job_id"
# 3. Get result and receipt
curl -H "X-Api-Key: REDACTED_CLIENT_KEY" \
"http://127.0.0.1:18000/v1/jobs/$job_id/result" | python3 -m json.tool
# 4. Process payment (manual)
miner_addr=$(cd miner && python3 wallet.py address | grep Address | awk '{print $3}')
amount=0.05 # Based on receipt
cd client && python3 wallet.py send $amount $miner_addr "Payment for job $job_id"
# 5. Record earnings
cd ../miner && python3 wallet.py earn $amount --job $job_id --desc "Inference job"
# 6. Check blockchain
curl -s "http://aitbc.keisanki.net/rpc/transactions" | \
python3 -c "import sys, json; data=json.load(sys.stdin); \
[print(f\"TX: {t['tx_hash']} - Block: {t['block_height']}\") \
for t in data.get('transactions', []) \
if 'receipt_id' in str(t.get('payload', {}))]"
```
## Expected Results
| Step | Expected Output | Verification |
|------|----------------|--------------|
| Job Submission | Job ID returned, state = QUEUED | `client.py status` shows job |
| Processing | State → RUNNING, miner assigned | Miner logs show job pickup |
| Completion | State = COMPLETED, output received | Result endpoint returns data |
| Receipt | Generated with price > 0 | Receipt has valid signature |
| Payment | Client balance ↓, miner ↑ | Wallet balances update |
| Blockchain | Transaction recorded | TX hash searchable |
## Monitoring Commands
```bash
# Real-time miner logs
sudo journalctl -u aitbc-host-gpu-miner.service -f
# Recent receipts
curl -H "X-Api-Key: REDACTED_CLIENT_KEY" \
http://127.0.0.1:18000/v1/explorer/receipts?limit=5
# Wallet balances
cd /home/oib/windsurf/aitbc/home && \
echo "Client:" && cd client && python3 wallet.py balance && \
echo "Miner:" && cd ../miner && python3 wallet.py balance
# Blockchain transactions
curl -s http://aitbc.keisanki.net/rpc/transactions | python3 -m json.tool
```
## Troubleshooting
### Job Stuck in QUEUED
```bash
# Check miner service
systemctl status aitbc-host-gpu-miner.service
# Restart if needed
sudo systemctl restart aitbc-host-gpu-miner.service
# Check miner registration
curl -H "X-Api-Key: REDACTED_ADMIN_KEY" \
http://127.0.0.1:18000/v1/admin/miners
```
### No Receipt Generated
```bash
# Verify receipt signing key
grep receipt_signing_key_hex /opt/coordinator-api/src/.env
# Check job result for receipt
curl -H "X-Api-Key: REDACTED_CLIENT_KEY" \
http://127.0.0.1:18000/v1/jobs/<job_id>/result | jq .receipt
```
### Payment Issues
```bash
# Check wallet addresses
cd /home/oib/windsurf/aitbc/home/client && python3 wallet.py address
cd /home/oib/windsurf/aitbc/home/miner && python3 wallet.py address
# Verify transaction
python3 wallet.py transactions
```
### Blockchain Not Recording
```bash
# Check node availability
curl -s http://aitbc.keisanki.net/rpc/health
# Search for receipt
curl -s "http://aitbc.keisanki.net/rpc/transactions" | \
grep <receipt_id>
```
## Test Data Examples
### Sample Job Result
```json
{
"result": {
"output": "The capital of France is Paris.",
"model": "llama3.2:latest",
"tokens_processed": 8,
"execution_time": 0.52,
"gpu_used": true
},
"receipt": {
"receipt_id": "8c4db70a1d413188681e003f0de7342f",
"units": 2.603,
"unit_price": 0.02,
"price": 0.05206
}
}
```
### Sample Blockchain Transaction
```json
{
"tx_hash": "0xabc123...",
"block_height": 12345,
"sender": "aitbc18f75b7eb7e2ecc7567b6",
"recipient": "aitbc1721d5bf8c0005ded6704",
"amount": 0.05206,
"payload": {
"receipt_id": "8c4db70a1d413188681e003f0de7342f"
}
}
```
## Integration with CI/CD
```yaml
# GitHub Actions example
- name: Run Ollama GPU Provider Test
run: |
cd /home/oib/windsurf/aitbc/home
python3 test_ollama_blockchain.py --timeout 300
```
## Related Files
- `/home/oib/windsurf/aitbc/home/test_ollama_blockchain.py` - Complete test script
- `/home/oib/windsurf/aitbc/cli/test_ollama_gpu_provider.py` - Basic API test
- `/home/oib/windsurf/aitbc/.windsurf/skills/blockchain-operations/` - Blockchain management
- `/home/oib/windsurf/aitbc/docs/infrastructure.md` - Infrastructure details

97
.windsurf/workflows/issue-management.md Normal file
View File

@@ -0,0 +1,97 @@
---
description: Workflow for managing and documenting issues from current to resolved
---
# Issue Management Workflow
This workflow handles the lifecycle of issues from identification to resolution and archival.
## Prerequisites
// turbo
- Ensure you have write access to the docs directory
- Check if the issue is already tracked in docs/currentissue.md
## Steps
### 1. Identify New Issue
```bash
# Check if currentissue.md already exists and has content
cat /home/oib/windsurf/aitbc/docs/currentissue.md
```
### 2. Document Issue in currentissue.md
If tracking a new issue:
- Add section with clear, descriptive title
- Include date, status, description
- List affected components
- Document attempted fixes
- Update status regularly
### 3. Monitor Progress
- Update the issue status as work progresses
- Add resolution details when fixed
- Include code changes, configuration updates, etc.
### 4. When Issue is Resolved
```bash
# Move to issues folder with machine-readable name
mv /home/oib/windsurf/aitbc/docs/currentissue.md \
/home/oib/windsurf/aitbc/docs/issues/YYYY-MM-DD_brief-description.md
# Example:
# mv docs/currentissue.md docs/issues/2026-01-29_cross-site-sync-resolved.md
```
### 5. Create New Empty currentissue.md
```bash
# Create fresh currentissue.md
cat > /home/oib/windsurf/aitbc/docs/currentissue.md << 'EOF'
# Current Issues
*No current issues to report.*
---
## Usage Guidelines
When tracking a new issue:
1. Add a new section with a descriptive title
2. Include the date and current status
3. Describe the issue, affected components, and any fixes attempted
4. Update status as progress is made
5. Once resolved, move this file to `docs/issues/` with a machine-readable name
## Recent Resolved Issues
See `docs/issues/` for resolved issues and their solutions.
EOF
```
## Naming Convention for Archived Issues
Use format: `YYYY-MM-DD_brief-description.md`
- Date: Year-Month-Day of resolution
- Description: Brief, lowercase, hyphen-separated summary
- Examples:
- `2026-01-29_cross-site-sync-resolved.md`
- `2026-01-15_pytest-warnings-fixed.md`
- `2026-01-10_database-migration-issue.md`
## Best Practices
1. **For Complex Issues**: Use `docs/currentissue.md` as the central tracking document
2. **Regular Updates**: Update status daily for active issues
3. **Detailed Resolution**: Document root cause and solution clearly
4. **Cross-References**: Link to related code changes, PRs, or documentation
5. **Archive Promptly**: Move resolved issues within 24 hours of resolution
## Integration with Other Workflows
- Use with `/docs` workflow to keep documentation current
- Reference resolved issues in `docs/done.md`
- Link technical details in `docs/reports/` as needed
## Memory Aid
Remember: For hard-to-track or complex issues spanning multiple components, always use `docs/currentissue.md` as the single source of truth for current status and resolution progress.

116
.windsurf/workflows/ollama-gpu-test.md Normal file
View File

@@ -0,0 +1,116 @@
---
description: Complete Ollama GPU provider test workflow from client submission to blockchain recording
---
# Ollama GPU Provider Test Workflow
This workflow executes the complete end-to-end test for Ollama GPU inference jobs, including payment processing and blockchain transaction recording.
## Prerequisites
// turbo
- Ensure all services are running: coordinator, GPU miner, Ollama, blockchain node
- Verify home directory wallets are configured
## Steps
### 1. Environment Check
```bash
# Check service health
./scripts/aitbc-cli.sh health
curl -s http://localhost:11434/api/tags
systemctl is-active aitbc-host-gpu-miner.service
```
### 2. Run Complete Test
```bash
# Execute the full workflow test
cd /home/oib/windsurf/aitbc/home
python3 test_ollama_blockchain.py
```
### 3. Verify Results
The test will display:
- Initial wallet balances
- Job submission and ID
- Real-time job progress
- Inference result from Ollama
- Receipt details with pricing
- Payment confirmation
- Final wallet balances
- Blockchain transaction status
### 4. Manual Verification (Optional)
```bash
# Check recent receipts
curl -H "X-Api-Key: REDACTED_CLIENT_KEY" \
http://127.0.0.1:18000/v1/explorer/receipts?limit=3
# Verify blockchain transaction
curl -s http://aitbc.keisanki.net/rpc/transactions | \
python3 -c "import sys, json; data=json.load(sys.stdin); \
[print(f\"TX: {t['tx_hash']} - Block: {t['block_height']}\") \
for t in data.get('transactions', [])[-5:]]"
```
## Expected Output
```
🚀 Ollama GPU Provider Test with Home Directory Users
============================================================
💰 Initial Wallet Balances:
----------------------------------------
Client: 9365.0 AITBC
Miner: 1525.0 AITBC
📤 Submitting Inference Job:
----------------------------------------
Prompt: What is the capital of France?
Model: llama3.2:latest
✅ Job submitted: <job_id>
⏳ Monitoring Job Progress:
----------------------------------------
State: QUEUED
State: RUNNING
State: COMPLETED
📊 Job Result:
----------------------------------------
Output: The capital of France is Paris.
🧾 Receipt Information:
Receipt ID: <receipt_id>
Provider: REDACTED_MINER_KEY
Units: <gpu_seconds> gpu_seconds
Unit Price: 0.02 AITBC
Total Price: <price> AITBC
⛓️ Checking Blockchain:
----------------------------------------
✅ Transaction found on blockchain!
TX Hash: <tx_hash>
Block: <block_height>
💰 Final Wallet Balances:
----------------------------------------
Client: <new_balance> AITBC
Miner: <new_balance> AITBC
✅ Test completed successfully!
```
## Troubleshooting
If the test fails:
1. Check GPU miner service status
2. Verify Ollama is running
3. Ensure coordinator API is accessible
4. Check wallet configurations
5. Verify blockchain node connectivity
## Related Skills
- ollama-gpu-provider - Detailed test documentation
- blockchain-operations - Blockchain node management