Algo Descriptors

Complete schema reference for Datafye Algo Descriptors.

Overview

An AlgoSpec defines your trading algorithm's execution environment, including:

• Container image and execution parameters

• Resource requirements (CPU, memory)

• Data bindings to DataSpecs

• Environment variables and secrets

• Scheduling and lifecycle management

Schema

Root Structure

apiVersion: datafye.io/v1
kind: AlgoSpec
metadata:
  name: <string>
  description: <string>
mode: live | paper | backtest
container:
  image: <string>
  tag: <string>
  command: [<list>]
  args: [<list>]
  env:
    - name: <string>
      value: <string>
resources:
  limits:
    cpu: <string>
    memory: <string>
  requests:
    cpu: <string>
    memory: <string>
data:
  dataSpec: <string>
scheduling:
  type: continuous | scheduled
  schedule: <cron-expression>

Field: apiVersion

• Type: string

• Required: Yes

• Value: datafye.io/v1

• Description: Schema version for this descriptor

Field: kind

• Type: string

• Required: Yes

• Value: AlgoSpec

• Description: Identifies this as an Algo Descriptor

Field: metadata

• Type: object

• Required: Yes

• Description: Metadata about this algo

metadata.name

• Type: string

• Required: Yes

• Format: lowercase alphanumeric with hyphens (DNS-1123 subdomain)

• Description: Unique identifier for this algo

• Example: momentum-strategy, mean-reversion-v2

metadata.description

• Type: string

• Required: No

• Description: Human-readable description of this algo

• Example: Momentum strategy with trailing stops

Field: mode

• Type: string

• Required: Yes

• Values: live | paper | backtest

• Description: Operating mode for this algo

Mode	Description
live	Real-time production trading
paper	Paper trading with simulated execution
backtest	Historical backtesting

Field: container

• Type: object

• Required: Yes

• Description: Container configuration for algo execution

container.image

• Type: string

• Required: Yes

• Description: Container image name

• Examples:

  • my-algo — Your own container

  • datafye/python-algo — Datafye-provided container

container.tag

• Type: string

• Required: No

• Default: latest

• Description: Container image tag/version

• Example: v1.2.0, latest

container.command

• Type: array of strings

• Required: No

• Description: Entrypoint override

• Example: ["/bin/sh"]

container.args

• Type: array of strings

• Required: No

• Description: Arguments to container entrypoint

• Example: ["python", "algo.py", "--verbose"]

container.env

• Type: array of env objects

• Required: No

• Description: Environment variables

Env object structure:

name: <string>
value: <string>

• name: Environment variable name

• value: Environment variable value

Example:

env:
  - name: LOG_LEVEL
    value: INFO
  - name: STRATEGY_TYPE
    value: momentum

Field: resources

• Type: object

• Required: No

• Description: Resource requirements and limits

resources.limits

• Type: object

• Required: No

• Description: Maximum resources the algo can use

resources.limits.cpu

• Type: string

• Required: No

• Format: <number> (cores) or <number>m (millicores)

• Description: CPU limit

• Examples: 1, 500m, 2

resources.limits.memory

• Type: string

• Required: No

• Format: <number><unit> where unit is Mi, Gi, M, G

• Description: Memory limit

• Examples: 512Mi, 1Gi, 2G

resources.requests

• Type: object

• Required: No

• Description: Minimum resources guaranteed for the algo

resources.requests.cpu

• Type: string

• Required: No

• Format: Same as resources.limits.cpu

• Description: CPU request

resources.requests.memory

• Type: string

• Required: No

• Format: Same as resources.limits.memory

• Description: Memory request

Field: data

• Type: object

• Required: Yes

• Description: Data bindings for this algo

data.dataSpec

• Type: string

• Required: Yes

• Description: Name of the DataSpec to use

• Example: my-trading-data

Note: The referenced DataSpec must exist and be provisioned before starting the algo.

Field: scheduling

• Type: object

• Required: No

• Description: Algo scheduling configuration

scheduling.type

• Type: string

• Required: No

• Default: continuous

• Values: continuous | scheduled

• Description: How the algo should be scheduled

Type	Description
continuous	Algo runs continuously until stopped
scheduled	Algo runs on a cron schedule

scheduling.schedule

• Type: string

• Required: Yes (if type is scheduled)

• Format: Cron expression

• Description: When to run the algo

• Examples:

  • 0 9 * * 1-5 — 9 AM weekdays

  • */5 9-16 * * 1-5 — Every 5 minutes during market hours

  • 0 0 * * * — Daily at midnight

Complete Examples

Example 1: Basic Continuous Algo

apiVersion: datafye.io/v1
kind: AlgoSpec
metadata:
  name: momentum-live
  description: Momentum strategy for live trading
mode: live

container:
  image: my-momentum-algo
  tag: v1.0.0
  args: ["python", "main.py"]
  env:
    - name: LOG_LEVEL
      value: INFO

resources:
  limits:
    cpu: "1"
    memory: 1Gi
  requests:
    cpu: "500m"
    memory: 512Mi

data:
  dataSpec: sip-trading-data

scheduling:
  type: continuous

Example 2: Scheduled Backtest

apiVersion: datafye.io/v1
kind: AlgoSpec
metadata:
  name: mean-reversion-backtest
  description: Nightly backtest of mean reversion strategy
mode: backtest

container:
  image: my-backtest-algo
  tag: latest
  args: ["python", "backtest.py", "--start", "2024-01-01", "--end", "2024-03-31"]
  env:
    - name: BACKTEST_MODE
      value: "true"
    - name: OUTPUT_DIR
      value: /data/results

resources:
  limits:
    cpu: "2"
    memory: 4Gi
  requests:
    cpu: "1"
    memory: 2Gi

data:
  dataSpec: backtest-q1-2024

scheduling:
  type: scheduled
  schedule: "0 0 * * *"  # Daily at midnight

Example 3: Paper Trading with Datafye Container

apiVersion: datafye.io/v1
kind: AlgoSpec
metadata:
  name: paper-testing
  description: Paper trading for strategy validation
mode: paper

container:
  image: datafye/python-algo
  tag: latest
  args: ["python", "/workspace/strategy.py"]
  env:
    - name: STRATEGY_TYPE
      value: momentum
    - name: RISK_MULTIPLIER
      value: "0.5"

resources:
  limits:
    cpu: "500m"
    memory: 512Mi
  requests:
    cpu: "250m"
    memory: 256Mi

data:
  dataSpec: paper-trading-data

scheduling:
  type: continuous

Example 4: High-Frequency Algo with Large Resources

apiVersion: datafye.io/v1
kind: AlgoSpec
metadata:
  name: hft-scalper
  description: High-frequency scalping strategy
mode: live

container:
  image: my-hft-algo
  tag: v2.1.0
  args: ["./hft_main", "--fast-mode"]
  env:
    - name: TICK_PRECISION
      value: "6"
    - name: MAX_POSITION_SIZE
      value: "10000"

resources:
  limits:
    cpu: "4"
    memory: 8Gi
  requests:
    cpu: "2"
    memory: 4Gi

data:
  dataSpec: sip-all-ticks

scheduling:
  type: continuous

Validation Rules

Required Fields

• apiVersion must be datafye.io/v1

• kind must be AlgoSpec

• metadata.name is required

• mode is required

• container.image is required

• data.dataSpec is required

Container Rules

• Image name must be valid (alphanumeric, hyphens, slashes)

• Tag must be valid (alphanumeric, hyphens, dots)

• Command and args arrays cannot be empty if specified

Resource Rules

• CPU format: positive number with optional m suffix

• Memory format: positive number with Mi, Gi, M, or G suffix

• Limits must be >= requests

• Requests cannot exceed available cluster resources

Scheduling Rules

• If type is scheduled, schedule is required

• Cron expression must be valid (5 fields: minute hour day month weekday)

• Continuous algos ignore schedule field

Data Binding Rules

• Referenced DataSpec must exist

• DataSpec mode should match AlgoSpec mode (live/live, paper/paper, backtest/backtest)

Resource Recommendations

By Algo Type

Algo Type	CPU	Memory	Notes
Simple strategy	250m-500m	256Mi-512Mi	Basic indicators
Complex strategy	500m-1	512Mi-1Gi	Multiple indicators
High-frequency	1-4	2Gi-8Gi	Tick-level processing
Backtest (small)	500m-1	1Gi-2Gi	Short history
Backtest (large)	2-4	4Gi-8Gi	Long history, many symbols

Request vs Limit Guidelines

• Requests: Minimum guaranteed resources (used for scheduling)

• Limits: Maximum allowed (prevents resource hogging)

• Best practice: Set requests at 50-70% of limits for burstable workloads

Related Documentation

• Concept guide: Algo Descriptors

• Data binding: Data Descriptors

• Broker integration: Broker Descriptors

• CLI usage: foundry start, trading start