StarCodex

Dynamic Coding for Starlink Measurement Analysis and Experiment Automation

English | 简体中文

Motivation

Starlink measurements continuously arrive from heterogeneous applications, regions, time periods, and link conditions. Turning these measurements into reliable data audits, profile descriptions, hard-case benchmarks, risk windows, figures, and case studies requires analysis programs that can evolve with the observed data and remain connected to measurement evidence.

Overview

StarCodex is a dynamic coding harness for turning newly available Starlink measurements into executable and validated analysis artifacts. It detects gaps in the current analysis state, formulates a structured coding task, asks Codex to generate or repair an analysis program, and accepts the resulting artifact only after layered validation.

Its core capabilities include:

• state-aware analysis-gap detection;
• structured coding-task construction;
• Codex CLI generation and repair;
• code, data, measurement, and output validation;
• persistent Artifact Memory; and
• streaming preparation of fixed-duration segments from StarNet archives.

Workflow

For each measurement batch, StarCodex follows five steps:

1. Detect missing data, profile, feature, failure, or experiment analysis.
2. Formulate the selected gap as a structured coding task and artifact contract.
3. Generate an executable analysis program with Codex.
4. Validate and repair the program using explicit validation feedback.
5. Commit accepted artifacts to Artifact Memory and update the analysis state.

Installation

git clone https://github.com/luopeng69131/StarCodex.git
cd StarCodex
python -m pip install -e .

StarCodex requires Python 3.10 or later. The reference package has no mandatory third-party Python dependencies.

Quick Start

1. Run the complete workflow locally

The deterministic demo backend exercises task construction, artifact execution, validation, state update, and Artifact Memory without requiring an LLM account.

starcodex demo --workspace outputs/demo

2. Run with Codex

Install and authenticate the Codex CLI, then run:

starcodex run \
  --batch examples/demo_batch.json \
  --workspace outputs/codex \
  --backend codex \
  --reasoning-effort high

The generated program, validation feedback, accepted output, and state changes remain in the selected workspace for inspection.

3. Prepare StarNet measurements

Obtain the public measurements by following the instructions in the ConnectedSystemsLab/StarNet repository, place the downloaded ZIP archives in one directory, and run:

starcodex prepare-starnet \
  --data-root /path/to/starnet-archives \
  --output outputs/starnet

The processor streams the archives and exports:

• valid_segments.csv: valid fixed-duration measurement segments and summaries;
• processing_audit.json: archive, run, rejection, and region counts.

The default protocol uses 10-minute segments with at least 300 throughput and 300 latency samples. See Dataset Protocol for the exact logic.

Repository Layout

StarCodex/
├── src/starcodex/          # Core harness and data processor
├── examples/               # Minimal measurement-batch input
├── tests/                  # Contract and workflow tests
├── docs/                   # Architecture and dataset guides
├── assets/                 # Paper concept and framework figures
└── .github/workflows/      # Continuous integration

Acknowledgements

StarCodex uses measurements released by the StarNet project. Please cite the original StarNet work when using its dataset.