aitbc/docs/advanced/05_development/11_marketplace-backend-analysis.md

Marketplace Backend Analysis

Current Implementation Status

✅ Implemented Features

1. Basic Marketplace Offers

• Endpoint: GET /marketplace/offers
• Service: MarketplaceService.list_offers()
• Status: ✅ Implemented (returns mock data)
• Notes: Returns hardcoded mock offers, not from database

2. Marketplace Statistics

• Endpoint: GET /marketplace/stats
• Service: MarketplaceService.get_stats()
• Status: ✅ Implemented
• Features:
  • Total offers count
  • Open capacity
  • Average price
  • Active bids count

3. Marketplace Bids

• Endpoint: POST /marketplace/bids
• Service: MarketplaceService.create_bid()
• Status: ✅ Implemented
• Features: Create bids with provider, capacity, price, and notes

4. Miner Offer Synchronization

• Endpoint: POST /marketplace/sync-offers
• Service: Creates offers from registered miners
• Status: ✅ Implemented (admin only)
• Features:
  • Syncs online miners to marketplace offers
  • Extracts GPU capabilities from miner attributes
  • Creates offers with pricing, GPU model, memory, etc.

5. Miner Offers List

• Endpoint: GET /marketplace/miner-offers
• Service: Lists offers created from miners
• Status: ✅ Implemented
• Features: Returns offers with detailed GPU information

❌ Missing Features (Expected by CLI)

1. GPU-Specific Endpoints

The CLI expects a /v1/marketplace/gpu/ prefix for all operations, but these are NOT IMPLEMENTED:

• POST /v1/marketplace/gpu/register - Register GPU in marketplace
• GET /v1/marketplace/gpu/list - List available GPUs
• GET /v1/marketplace/gpu/{gpu_id} - Get GPU details
• POST /v1/marketplace/gpu/{gpu_id}/book - Book/reserve a GPU
• POST /v1/marketplace/gpu/{gpu_id}/release - Release a booked GPU
• GET /v1/marketplace/gpu/{gpu_id}/reviews - Get GPU reviews
• POST /v1/marketplace/gpu/{gpu_id}/reviews - Add GPU review

2. GPU Booking System

• Status: ❌ Not implemented
• Missing Features:
  • GPU reservation/booking logic
  • Booking duration tracking
  • Booking status management
  • Automatic release after timeout

3. GPU Reviews System

• Status: ❌ Not implemented
• Missing Features:
  • Review storage and retrieval
  • Rating aggregation
  • Review moderation
  • Review-per-gpu association

4. GPU Registry

• Status: ❌ Not implemented
• Missing Features:
  • Individual GPU registration
  • GPU specifications storage
  • GPU status tracking (available, booked, offline)
  • GPU health monitoring

5. Order Management

• Status: ❌ Not implemented
• CLI expects: GET /v1/marketplace/orders
• Missing Features:
  • Order creation from bookings
  • Order tracking
  • Order history
  • Order status updates

6. Pricing Information

• Status: ❌ Not implemented
• CLI expects: GET /v1/marketplace/pricing/{model}
• Missing Features:
  • Model-specific pricing
  • Dynamic pricing based on demand
  • Historical pricing data
  • Price recommendations

🔧 Data Model Issues

1. MarketplaceOffer Model Limitations

Current model lacks GPU-specific fields:

class MarketplaceOffer(SQLModel, table=True):
    id: str
    provider: str  # Miner ID
    capacity: int  # Number of concurrent jobs
    price: float  # Price per hour
    sla: str
    status: str  # open, closed, etc.
    created_at: datetime
    attributes: dict  # Contains GPU info but not structured

Missing GPU-specific fields:

• gpu_id: Unique GPU identifier
• gpu_model: GPU model name
• gpu_memory: GPU memory in GB
• gpu_status: available, booked, offline
• booking_expires: When current booking expires
• total_bookings: Number of times booked
• average_rating: Aggregated review rating

2. No Booking/Order Models

Missing models for:

• GPUBooking: Track GPU reservations
• GPUOrder: Track completed GPU usage
• GPUReview: Store GPU reviews
• GPUPricing: Store pricing tiers

📊 API Endpoint Comparison

CLI Command	Expected Endpoint	Implemented	Status
aitbc marketplace gpu register	POST /v1/marketplace/gpu/register	❌	Missing
aitbc marketplace gpu list	GET /v1/marketplace/gpu/list	❌	Missing
aitbc marketplace gpu details	GET /v1/marketplace/gpu/{id}	❌	Missing
aitbc marketplace gpu book	POST /v1/marketplace/gpu/{id}/book	❌	Missing
aitbc marketplace gpu release	POST /v1/marketplace/gpu/{id}/release	❌	Missing
aitbc marketplace reviews	GET /v1/marketplace/gpu/{id}/reviews	❌	Missing
aitbc marketplace review add	POST /v1/marketplace/gpu/{id}/reviews	❌	Missing
aitbc marketplace orders list	GET /v1/marketplace/orders	❌	Missing
aitbc marketplace pricing	GET /v1/marketplace/pricing/{model}	❌	Missing

🚀 Recommended Implementation Plan

Phase 1: Core GPU Marketplace

1. Create GPU Registry Model:

   class GPURegistry(SQLModel, table=True):
       gpu_id: str = Field(primary_key=True)
       miner_id: str
       gpu_model: str
       gpu_memory_gb: int
       cuda_version: str
       status: str  # available, booked, offline
       current_booking_id: Optional[str] = None
       booking_expires: Optional[datetime] = None
       attributes: dict = Field(default_factory=dict)
   

2. Implement GPU Endpoints:

   • Add /v1/marketplace/gpu/ router
   • Implement all CRUD operations for GPUs
   • Add booking/unbooking logic

3. Create Booking System:

   class GPUBooking(SQLModel, table=True):
       booking_id: str = Field(primary_key=True)
       gpu_id: str
       client_id: str
       job_id: Optional[str]
       duration_hours: float
       start_time: datetime
       end_time: datetime
       total_cost: float
       status: str  # active, completed, cancelled
   

Phase 2: Reviews and Ratings

1. Review System:

   class GPUReview(SQLModel, table=True):
       review_id: str = Field(primary_key=True)
       gpu_id: str
       client_id: str
       rating: int = Field(ge=1, le=5)
       comment: str
       created_at: datetime
   

2. Rating Aggregation:

   • Add average_rating to GPURegistry
   • Update rating on each new review
   • Implement rating history tracking

Phase 3: Orders and Pricing

1. Order Management:

   class GPUOrder(SQLModel, table=True):
       order_id: str = Field(primary_key=True)
       booking_id: str
       client_id: str
       gpu_id: str
       status: str
       created_at: datetime
       completed_at: Optional[datetime]
   

2. Dynamic Pricing:

   class GPUPricing(SQLModel, table=True):
       id: str = Field(primary_key=True)
       model_name: str
       base_price: float
       current_price: float
       demand_multiplier: float
       updated_at: datetime
   

🔍 Integration Points

1. Miner Registration

• When miners register, automatically create GPU entries
• Sync GPU capabilities from miner registration
• Update GPU status based on miner heartbeat

2. Job Assignment

• Check GPU availability before job assignment
• Book GPU for job duration
• Release GPU on job completion or failure

3. Billing Integration

• Calculate costs from booking duration
• Create orders from completed bookings
• Handle refunds for early releases

📝 Implementation Notes

1. API Versioning: Use /v1/marketplace/gpu/ as expected by CLI
2. Authentication: Use existing API key system
3. Error Handling: Follow existing error patterns
4. Metrics: Add Prometheus metrics for GPU operations
5. Testing: Create comprehensive test suite
6. Documentation: Update OpenAPI specs

🎯 Priority Matrix

Feature	Priority	Effort	Impact
GPU Registry	High	Medium	High
GPU Booking	High	High	High
GPU List/Details	High	Low	High
Reviews System	Medium	Medium	Medium
Order Management	Medium	High	Medium
Dynamic Pricing	Low	High	Low

💡 Quick Win

The fastest way to make the CLI work is to:

1. Create a new router /v1/marketplace/gpu/
2. Implement basic endpoints that return mock data
3. Map existing marketplace offers to GPU format
4. Add simple in-memory booking tracking

This would allow the CLI to function while the full backend is developed.