npm package: @neuronetiq/marketplace-contracts
Description: Contracts for ML Marketplace - Pod I/O, Marketplace API, and Infra Integration
Author: NeuroNetIQ
Latest version: 0.2.0

# @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

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

## Quick Start

### Pod I/O (Inference)

```typescript
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

```typescript
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

```typescript
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:

```typescript
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:

```typescript
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](https://github.com/yourorg/marketplace-contracts/issues)
- Documentation: [Full API documentation](https://docs.yourorg.com/marketplace-contracts)
- Community: [Join our Discord](https://discord.gg/yourorg)