@yourorg/marketplace-contracts

Contracts for ML Marketplace - Pod I/O, Marketplace API, and Infrastructure Integration

Overview

This package provides TypeScript contracts and Zod schemas for the ML Marketplace ecosystem, enabling seamless integration between:

• ML Inference Pods (RunPod, AWS, etc.)
• Marketplace API (Model catalog, deployment management)
• Infrastructure Service (Signal/consensus storage)

Installation

npm install @yourorg/marketplace-contracts
# or
pnpm add @yourorg/marketplace-contracts
# or
yarn add @yourorg/marketplace-contracts

Quick Start

Pod I/O (Inference)

import { SignalInferenceRequest, SignalInferenceResponse } from '@yourorg/marketplace-contracts';

// Create inference request
const request: SignalInferenceRequestT = {
  request_id: 'uuid-here',
  timestamp: '2025-09-02T20:00:00Z',
  symbol: 'EURUSD',
  timeframe: '5m',
  bars: [/* market data */],
  model_config: {
    model_version: '1.0.0',
    features: ['rsi', 'macd', 'bollinger']
  }
};

// Validate request
const result = SignalInferenceRequest.safeParse(request);
if (result.success) {
  // Send to inference pod
  const response = await fetch('/infer', {
    method: 'POST',
    body: JSON.stringify(result.data)
  });
}

Marketplace API

import { CatalogRequest, CatalogResponse } from '@yourorg/marketplace-contracts';

// Request model catalog
const catalogRequest: CatalogRequestT = {
  task: 'signal',
  domain: 'forex',
  sort_by: 'sharpe_ratio',
  sort_order: 'desc',
  limit: 20
};

// Validate and send
const result = CatalogRequest.safeParse(catalogRequest);
if (result.success) {
  const response = await fetch('/api/catalog', {
    method: 'POST',
    body: JSON.stringify(result.data)
  });
}

Infrastructure Integration

import { 
  SignalWrite, 
  withMarketplaceHeaders, 
  makeIdempotencyKey 
} from '@yourorg/marketplace-contracts';

// Create signal write
const signalWrite: SignalWriteT = {
  symbol: 'EURUSD',
  timeframe: '5m',
  decision: 'BUY',
  confidence: 0.85,
  model_version: '1.0.0',
  timestamp: '2025-09-02T20:00:00Z',
  vendor_id: 'vendor_abc',
  deployment_id: 'deployment_xyz'
};

// Generate headers
const headers = withMarketplaceHeaders({
  token: 'your-infra-token',
  contractsVersion: '0.1.0',
  idempotencyKey: makeIdempotencyKey('EURUSD', '5m'),
  vendorId: 'vendor_abc',
  deploymentId: 'deployment_xyz'
});

// Send to infrastructure
const response = await fetch('/api/signals/store', {
  method: 'POST',
  headers,
  body: JSON.stringify(signalWrite)
});

API Reference

Pod I/O Schemas

• SignalInferenceRequest - Input to signal inference pods
• SignalInferenceResponse - Output from signal inference pods
• ConsensusInferenceRequest - Input to consensus inference pods
• ConsensusInferenceResponse - Output from consensus inference pods
• OptimizerRequest - Input to optimization pods
• OptimizerResponse - Output from optimization pods

Marketplace API Schemas

• CatalogModel - Model entry in marketplace catalog
• ModelVersion - Specific model version details
• Deployment - Active deployment information
• Health - Deployment health status
• CatalogRequest - Catalog query parameters
• CatalogResponse - Catalog query results

Infrastructure Write Schemas

• SignalWrite - Signal data for infrastructure
• ConsensusWrite - Consensus data for infrastructure
• BatchSignalWrite - Batch signal writes
• BatchConsensusWrite - Batch consensus writes
• WriteResponse - Infrastructure write response

Helper Functions

• withMarketplaceHeaders() - Generate marketplace headers
• makeIdempotencyKey() - Create idempotency keys
• validateSignalWrite() - Validate signal data
• validateConsensusWrite() - Validate consensus data
• aggregateSignals() - Aggregate signals into consensus

Idempotency

All write operations use 5-second idempotency slots:

import { makeIdempotencyKey } from '@yourorg/marketplace-contracts';

// Generate idempotency key for current 5-second slot
const key = makeIdempotencyKey('EURUSD', '5m');

// Format: "EURUSD:5m:345059280"
// Where 345059280 = Math.floor(Date.now() / 5000)

Headers

Marketplace-to-Infrastructure communications require specific headers:

import { withMarketplaceHeaders } from '@yourorg/marketplace-contracts';

const headers = withMarketplaceHeaders({
  token: 'bearer-token',
  contractsVersion: '0.1.0',
  idempotencyKey: 'EURUSD:5m:345059280',
  vendorId: 'vendor_abc',
  deploymentId: 'deployment_xyz'
});

// Generates:
// {
//   'Authorization': 'Bearer bearer-token',
//   'X-Marketplace-Contracts-Version': '0.1.0',
//   'X-Idempotency-Key': 'EURUSD:5m:345059280',
//   'X-Vendor-ID': 'vendor_abc',
//   'X-Deployment-ID': 'deployment_xyz',
//   'Content-Type': 'application/json'
// }

Version Policy

• Major versions (1.x.x): Breaking changes to schemas
• Minor versions (0.x.x): New features, backward compatible
• Patch versions (0.1.x): Bug fixes, backward compatible

Infrastructure accepts ^0.1.x and rejects major mismatches.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• GitHub Issues: Report bugs and request features
• Documentation: Full API documentation
• Community: Join our Discord