Skip to main content
Complete reference for all data structures used in Babylon’s research systems, training pipelines, and market simulation.

​
Trajectory Data Structure

​
Trajectory Schema

Trajectories capture complete agent decision-making episodes for RL training. 
interface Trajectory {
  trajectoryId: string              // Unique identifier (UUID)
  agentId: string                  // Agent identifier
  startTime: number                // Unix timestamp (ms)
  endTime: number                  // Unix timestamp (ms)
  durationMs: number               // Duration in milliseconds
  
  // Grouping for GRPO training
  episodeId?: string               // Episode identifier
  scenarioId?: string              // Scenario for grouping
  batchId?: string                 // Training batch ID
  groupIndex?: number              // Position in trajectory group
  
  // Trajectory steps
  steps: TrajectoryStep[]          // Sequence of steps
  
  // Rewards
  totalReward: number              // Total reward for trajectory
  rewardComponents: RewardComponents
  
  // Outcome metrics
  metrics: {
    episodeLength: number
    finalStatus: 'completed' | 'terminated' | 'error' | 'timeout'
    finalBalance?: number
    finalPnL?: number
    tradesExecuted?: number
    postsCreated?: number
    messagesHandled?: number
    successRate?: number
    errorCount?: number
  }
  
  // Metadata
  metadata: {
    agentName?: string
    agentModel?: string
    agentVersion?: string
    environmentVersion?: string
    randomSeed?: number
    isTrainingData?: boolean
    isEvaluation?: boolean
    comparisonGroup?: string
    initialState?: Record<string, unknown>
    goalDescription?: string
    constraints?: string[]
  }
}

​
Trajectory Step

Each step represents one decision-action cycle. 
interface TrajectoryStep {
  stepNumber: number                // Sequential step number
  timestamp: number                 // Unix timestamp (ms)
  
  // Environment state
  environmentState: {
    portfolio: {
      balance: number
      positions: Position[]
      lifetimePnL: number
    }
    markets: {
      predictions: PredictionMarket[]
      perpetuals: PerpMarket[]
    }
    social: {
      feed: Post[]
      unreadMessages: number
    }
  }
  
  // Observation (what agent sees)
  observation: {
    availableActions: Action[]
    constraints: Constraints
    recentMemory: Memory[]
  }
  
  // LLM calls
  llmCalls: LLMCall[]
  
  // Action taken
  action: {
    type: string                    // Action type
    parameters: Record<string, unknown>
    success: boolean
    result?: Record<string, unknown>
    error?: string
  }
  
  // Reward for this step
  reward: number
  reasoning?: string                // Agent's reasoning
}

​
LLM Call

Records LLM interactions for analysis. 
interface LLMCall {
  model: string                     // Model name (e.g., "claude-3.5-sonnet")
  systemPrompt: string              // System prompt
  userPrompt: string                // User prompt
  response: string                  // LLM response
  reasoning?: string                // Extracted reasoning
  temperature: number               // Temperature used
  purpose: string                   // Purpose (e.g., "decision", "analysis")
}

​
Reward Components

Breakdown of reward calculation. 
interface RewardComponents {
  pnlReward: number                 // P&L component (0.5 weight)
  speedReward: number               // Speed component (0.2 weight)
  consistencyReward: number         // Consistency component (0.3 weight)
  socialReward?: number             // Social engagement bonus
  penalty?: number                  // Penalties (errors, violations)
}

​
ART-Compatible Format

Format for GRPO training (OpenAGI ART). 
interface ARTTrajectory {
  // Message sequence (what model sees/generates)
  messages: ChatMessage[]
  
  // Single reward
  reward: number
  
  // Metadata for RULER judge
  metadata: {
    trajectoryId: string
    agentId: string
    scenarioId?: string
    groupIndex?: number
    environmentContext?: {
      initialBalance: number
      finalBalance: number
      initialPnL: number
      finalPnL: number
      actionsTaken: string[]
      errors: string[]
    }
    gameKnowledge?: {
      trueProbabilities?: Record<string, number>
      actualOutcomes?: Record<string, unknown>
      hiddenVariables?: Record<string, unknown>
    }
    metrics?: Record<string, unknown>
  }
}

​
Market Data Models

​
Prediction Market

interface PredictionMarket {
  id: string
  question: string
  description?: string
  yesShares: number                 // YES shares in pool
  noShares: number                  // NO shares in pool
  liquidity: number                // Total liquidity (k = yesShares * noShares)
  
  // Pricing (CPMM)
  yesPrice: number                  // YES price (0-1)
  noPrice: number                   // NO price (0-1)
  
  // Status
  resolved: boolean
  resolution?: boolean              // true = YES won
  endDate: Date
  
  // Volume
  volume24h: number
  totalVolume: number
}

​
Perpetual Market

interface PerpMarket {
  ticker: string                    // Symbol (e.g., "TECH")
  organizationId: string           // Company identifier
  name: string                      // Company name
  
  // Price data
  currentPrice: number
  change24h: number
  changePercent24h: number
  high24h: number
  low24h: number
  
  // Volume & interest
  volume24h: number
  openInterest: number              // Total open positions (USD)
  
  // Funding
  fundingRate: {
    ticker: string
    rate: number                    // Annual rate (e.g., 0.01 = 1%)
    nextFundingTime: Date           // Next funding payment time
    predictedRate: number
  }
  
  // Trading parameters
  maxLeverage: number               // Maximum leverage (100x)
  minOrderSize: number              // Minimum order size (10 USD)
  
  // Pricing
  markPrice: number                 // Fair value for liquidations
  indexPrice: number                // Reference price
}

​
Position

interface Position {
  id: string
  userId: string
  marketId: string
  side: boolean                     // true = YES, false = NO
  shares: number
  avgPrice: number
}

​
Perp Position

interface PerpPosition {
  id: string
  userId: string
  ticker: string
  side: 'long' | 'short'
  entryPrice: number
  currentPrice: number
  size: number                      // Position size (USD notional)
  leverage: number                  // Leverage multiplier (1-100x)
  liquidationPrice: number
  unrealizedPnL: number
  unrealizedPnLPercent: number
  fundingPaid: number
  openedAt: Date
  lastUpdated: Date
}

​
Agent State Models

​
Game State

Complete game state at decision point. 
interface GameState {
  portfolio: {
    balance: number
    positions: Position[]
    perpPositions: PerpPosition[]
    lifetimePnL: number
  }
  markets: {
    predictions: PredictionMarket[]
    perpetuals: PerpMarket[]
  }
  social: {
    feed: Post[]
    unreadMessages: number
    activeChats: Chat[]
  }
  agent: {
    recentActions: Action[]
    memory: Memory[]
    trustScores: Record<string, TrustScore>
  }
}

​
Memory

Agent memory entry. 
interface Memory {
  id: string
  type: 'episodic' | 'semantic' | 'working'
  content: string
  timestamp: Date
  importance: number                // 0.0 to 1.0
  relatedMarkets?: string[]
  relatedUsers?: string[]
}

​
Trust Score

NPC trust score. 
interface TrustScore {
  accuracy: number                  // 0.0 to 1.0
  sampleSize: number               // Number of observations
  lastUpdated: Date
  domainSpecific?: Record<string, number> // Trust by topic
}

​
Database Schema

​
Trajectory Table

model Trajectory {
  id              String   @id @default(cuid())
  trajectoryId    String   @unique
  agentId         String
  
  // Timing
  startTime       DateTime
  endTime         DateTime
  durationMs      Int
  
  // Grouping
  episodeId       String?  @index
  scenarioId      String?  @index
  batchId         String?  @index
  
  // JSON data
  stepsJson       String   @db.Text
  rewardComponentsJson String @db.Text
  metricsJson     String   @db.Text
  metadataJson    String   @db.Text
  
  // Quick access fields
  totalReward     Float
  episodeLength   Int
  finalStatus     String
  finalBalance    Float?
  finalPnL        Float?
  tradesExecuted  Int?
  postsCreated    Int?
  
  // AI Judge
  aiJudgeReward   Float?
  aiJudgeReasoning String? @db.Text
  judgedAt        DateTime?
  
  // Training
  isTrainingData  Boolean  @default(true)
  isEvaluation    Boolean  @default(false)
  usedInTraining  Boolean  @default(false)
  trainedInBatch  String?  @index
  
  // Relations
  agent           User     @relation("AgentTrajectories", fields: [agentId], references: [id])
  
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
  
  @@index([agentId, startTime])
  @@index([scenarioId, createdAt])
  @@index([isTrainingData, usedInTraining])
  @@index([aiJudgeReward])
  @@map("trajectories")
}

​
Market Table

model Market {
  id String @id @default(uuid())
  question String
  description String?
  yesShares Decimal @default(0)
  noShares Decimal @default(0)
  liquidity Decimal
  resolved Boolean @default(false)
  resolution Boolean?
  endDate DateTime
  
  positions Position[]
  
  @@index([resolved, endDate])
  @@index([createdAt(sort: Desc)])
}

​
PerpPosition Table

model PerpPosition {
  id String @id @default(uuid())
  userId String
  ticker String
  side String // 'long' | 'short'
  entryPrice Float
  currentPrice Float
  size Float
  leverage Int
  liquidationPrice Float
  unrealizedPnL Float
  fundingPaid Float @default(0)
  openedAt DateTime @default(now())
  closedAt DateTime?
  realizedPnL Float?
  
  @@index([userId, closedAt])
  @@index([ticker])
}

​
API Data Formats

​
A2A Request

interface A2ARequest {
  jsonrpc: '2.0'
  id: string | number
  method: string                    // e.g., "a2a.getBalance"
  params?: Record<string, unknown>
}

​
A2A Response

interface A2AResponse {
  jsonrpc: '2.0'
  id: string | number
  result?: unknown
  error?: {
    code: number
    message: string
    data?: unknown
  }
}

​
Market Data Response

interface MarketDataResponse {
  predictions: PredictionMarket[]
  perpetuals: PerpMarket[]
  timestamp: Date
}

​
HuggingFace Dataset Format

​
Dataset Structure

{
  "trajectory_id": "uuid",
  "agent_id": "agent-123",
  "episode_id": "episode-456",
  "scenario_id": "scenario-789",
  "start_time": "2024-11-13T10:00:00Z",
  "duration_ms": 30000,
  "steps": [
    {
      "step_number": 1,
      "timestamp": 1731484800000,
      "environment_state": {...},
      "observation": {...},
      "llm_calls": [...],
      "action": {...},
      "reward": 0.5
    }
  ],
  "total_reward": 2.3,
  "final_status": "completed",
  "final_pnl": 45.67,
  "metrics": {...},
  "metadata": {...}
}

​
Research & Engine

​
For Developers

​
For Players

Ready to start researching? Check out the Research Overview!