API Reference

API Reference¶

Back to Home

This reference captures public APIs exposed by the simulator, CLI, and forthcoming web services. Keep it synchronized with code annotations so integrators can rely on accurate usage notes.

Simulation control surface {#simulation-control}¶

Document CLI commands, Python entry points, and HTTP endpoints (when available) that control the distributed simulation. Reference versioning, authentication, and rate limits as they come online.

Rate Limiting {#rate-limiting}¶

The distributed server implements rate limiting to prevent abuse and ensure fair resource allocation. All limits are per worker per 60-second window:

• Assignment endpoint: 20 requests (1 request per 3 seconds)
• Results endpoint: 15 requests (1 request per 4 seconds)
• Heartbeat endpoint: 20 requests (1 request per 3 seconds)
• Default endpoints: 200 requests (general purpose limit)

When rate limits are exceeded, the server returns HTTP 429 (Too Many Requests) with the detail "Rate limit exceeded". Rate limit counters reset every 60 seconds.

CLI Commands {#cli}¶

The bytebiota console entry (src/bytebiota/__main__.py) exposes subcommands for simulation control, monitoring, and analysis.

Core Commands¶

• server — Start the distributed coordinator
• worker — Start a distributed worker
• config — Display or apply configuration presets
• export-diversity — Export diversity metrics to CSV
• tune — Access the hybrid tuning CLI namespace

Worker Command {#worker-command}¶

Start a distributed worker that connects back to the server via WebSocket.

Usage:

python -m bytebiota worker [OPTIONS]

Notable options:
- --preset [minimal|background|standard|full|auto] - Resource limits preset (default: auto)
- --batch-size INTEGER - Override the fixed batch size used in addition to adaptive merging
- --target-interval-seconds INTEGER - Override the adaptive batching target interval (default: 300)
- --min-batch-size INTEGER / --max-batch-size INTEGER - Bounds for adaptive batch sizing
- --verbose - Emit detailed worker diagnostics

Adaptive batching is always enabled (the legacy --no-adaptive-batching switch has been removed), and tuning acceptance now follows the server-authoritative runtime flag runtime.accept_worker_tuning instead of a CLI toggle.

Web API Endpoints {#web-api}¶

The web API is organized into service modules for better maintainability and modularity:

Service Architecture {#service-architecture}¶

• Analytics Service (analytics_service.py) - Advanced data analysis and insights
• Simulation API Service (simulation_api_service.py) - Simulation control and organism data
• Monitoring API Service (monitoring_api_service.py) - System health and distributed metrics
• UI Routes Service (ui_routes_service.py) - Web interface page routes

Analytics Endpoints {#analytics-api}¶

The analytics API provides comprehensive insights into simulation behavior and ecosystem dynamics.

GET /api/analytics/population-forecast¶

Get population forecasting data with multiple model support.

Parameters:
- horizon (string): Forecast horizon, default "30d"
- model (string): Forecasting model ("arima", "exponential", "linear"), default "arima"

Response:

{
  "model": "arima",
  "horizon": "30d",
  "labels": ["-10d", "-9d", ..., "+6d"],
  "historical": [642, 641, ...],
  "forecast": [636, 635, ...],
  "confidence_upper": [640, 639, ...],
  "confidence_lower": [632, 631, ...],
  "trend": "stable",
  "accuracy": 0.95,
  "volatility": 1.55,
  "current_population": 642
}

GET /api/analytics/extinction-risk¶

Get extinction risk assessment for all species.

Parameters:
- threshold (float): Risk threshold, default 0.1

Response:

{
  "riskDistribution": {"low": 3, "medium": 3, "high": 3},
  "atRiskSpecies": [
    {
      "name": "Copyloopus iterator (Digitalis Symbiota)",
      "riskProbability": 0.95,
      "population": 1
    }
  ]
}

GET /api/analytics/resource-scarcity¶

Get resource scarcity predictions and current usage.

Parameters:
- resource (string): Resource type, default "memory"

Response:

{
  "resources": [
    {
      "name": "Memory",
      "scarcityTime": "5+ days",
      "status": "ok",
      "currentUsage": "1284 MB (est.)",
      "perOrganism": "2.0 MB (est.)",
      "population": 642
    }
  ]
}

GET /api/analytics/mutation-pressure¶

Get mutation pressure analysis data.

Response:

{
  "labels": ["0h", "2h", "4h", ...],
  "mutationRates": [45, 47, 43, ...],
  "beneficialRate": [0.15, 0.18, 0.12, ...],
  "totalMutations": [300, 320, 280, ...],
  "beneficialMutations": [45, 58, 34, ...]
}

GET /api/analytics/behavioral-clusters¶

Get behavioral clustering analysis.

Parameters:
- algorithm (string): Clustering algorithm, default "kmeans"
- k (int): Number of clusters, default 5

Response:

{
  "clusters": [
    {
      "points": [
        {"x": 0.3, "y": 0.7, "organism_id": 123}
      ]
    }
  ],
  "xAxisLabel": "Reproduction Rate",
  "yAxisLabel": "Survival Rate",
  "total_organisms": 50
}

GET /api/analytics/temporal-patterns¶

Get temporal pattern analysis.

Parameters:
- pattern_type (string): Pattern type, default "seasonal"

Response:

{
  "patterns": [
    {
      "type": "population_stability",
      "strength": 0.85,
      "description": "Population shows high stability (variance: 12.3)"
    }
  ]
}

GET /api/analytics/network-analysis¶

Get network analysis of species relationships.

Parameters:
- centrality (string): Centrality measure, default "betweenness"

Response:

{
  "nodes": [
    {
      "id": "Digitalis_Anomalica_Replicatus_vulgaris",
      "name": "Replicatus vulgaris (Digitalis Anomalica)",
      "centrality": 0.8,
      "connections": 5,
      "population": 80
    }
  ],
  "edges": [
    {
      "source": "node1",
      "target": "node2",
      "weight": 0.6
    }
  ]
}

GET /api/analytics/correlation-matrix¶

Get correlation matrix between simulation variables.

Response:

{
  "variables": ["Population", "Memory", "Energy", "Diversity", "Age", "Errors"],
  "matrix": [
    [1.0, 0.85, 0.72, ...],
    [0.85, 1.0, 0.68, ...],
    ...
  ]
}

GET /api/analytics/fitness-landscape¶

Get fitness landscape visualization data.

Response:

{
  "landscape": "Fitness landscape with 15 species",
  "species": [
    {
      "name": "Replicatus vulgaris (Digitalis Anomalica)",
      "fitness": 0.8,
      "x": 0.3,
      "y": 0.7,
      "population": 80,
      "kingdom": "Digitalis Anomalica"
    }
  ]
}

GET /api/analytics/insights¶

Get automated insights and recommendations.

Parameters:
- confidence_threshold (float): Minimum confidence for insights, default 0.8

Response:

{
  "insights": [
    {
      "title": "Ecosystem Stability",
      "description": "The digital ecosystem shows high stability with 9 species and 642 total organisms.",
      "confidence": 0.85,
      "recommendation": "Continue monitoring for any disruptive events."
    }
  ]
}

Organism Icons {#organism-icons}¶

GET /api/organism/{organism_id}/icon¶

Generate or retrieve an icon for a specific organism.

Parameters:
- organism_id (int): The ID of the organism

Response:

{
  "icon_path": "static/icons/Replicatus_vulgaris_Digitalis_Anomalica.svg",
  "icon_url": "/static/icons/Replicatus_vulgaris_Digitalis_Anomalica.svg"
}

Error Responses:
- 404: Organism not found
- 500: Icon generation failed

Taxonomy Data {#taxonomy-api}¶

GET /api/taxonomy/species¶

Retrieve all species classification data from the seed bank with full taxonomy information.

Response:

{
  "species": [
    {
      "id": 0,
      "genome_hash": "0bde9fec",
      "genome_size": 64,
      "classification": {
        "domain": "ByteBiota",
        "kingdom": "Digitalis Anomalica",
        "phylum": "Polymorphid",
        "class": "Migrata",
        "order": "Linearis",
        "family": "Standardidae",
        "genus": "Replicatus",
        "species": "Replicatus vulgaris"
      },
      "behavioral_traits": ["replication_capable", "memory_allocator"],
      "opcode_profile": {
        "template": 15.2,
        "data_movement": 25.8,
        "arithmetic_logic": 12.1,
        "comparison_flags": 8.3,
        "control_flow": 18.7,
        "call_return": 5.2,
        "system_calls": 7.1,
        "stack": 3.4,
        "environment": 2.8,
        "register_adjust": 1.4
      },
      "notes": [
        "Exhibits replication capability",
        "Memory allocator behavior",
        "Genome size: 64 bytes",
        "Valid opcodes: 58",
        "Invalid opcodes: 6",
        "Dominant opcode family: data_movement (25.8%)"
      ]
    }
  ],
  "summary": {
    "Digitalis Anomalica::Replicatus vulgaris": {
      "kingdom": "Digitalis Anomalica",
      "species": "Replicatus vulgaris",
      "count": 3
    }
  }
}

Fields:
- species: Array of species entries from the seed bank
- id: Unique identifier for the species entry
- genome_hash: MD5 hash of the genome (first 8 characters)
- genome_size: Size of the genome in bytes
- classification: Full taxonomic classification hierarchy
- behavioral_traits: List of detected behavioral characteristics
- opcode_profile: Percentage breakdown of opcode family usage
- notes: Additional analysis notes and statistics
- summary: Counts of organisms per kingdom/species combination

GET /api/organism/{organism_id}¶

Get detailed information about a specific organism.

Parameters:
- organism_id (int): The ID of the organism

Response:

{
  "id": 0,
  "genome_hash": "0bde9fec",
  "genome_hex": "00 01 02 ...",
  "classification": {...},
  "behavioral_traits": [...],
  "opcode_profile": {...},
  "genome_size": 64
}