maestro-economics 0.5.2

Economics runtime and implementation reference for agents: workspace-first compute, run(ctx), and cloud execution guidance.

maestro-economics

maestro-economics is the canonical repository for the Maestro economics skill, the mecon CLI, the run(ctx) runtime contract, and the Modal worker used by RA Compute.

This repo exists to keep four things aligned:

• agent guidance
• packaging and PyPI release
• workspace/runtime execution
• cloud worker implementation

Scope

This repository currently contains:

• mecon CLI for setup, workspace tracking, sync, submit, watch, logs, download
• run(ctx) runtime with progress, logs, checkpoints, data loading, and transform helpers
• Modal worker entrypoints for GPU execution
• economics method registry and analysis scaffolding
• agent skill documentation used to guide professor-facing and agent-facing workflows

Canonical flow

The contract is doctor-first. Treat the host plugin or skill, the Python runtime, and the local workspace as separate layers that must be refreshed and verified in order.

# 1. Refresh the host plugin or skill for this repo.
#    Use the host-native install or refresh command when available.

# 2. Upgrade the runtime package.
python3 -m pip install --upgrade maestro-economics

# 3. Run the readiness gate immediately.
mecon doctor

# 4. If doctor says the API key is missing:
mecon setup
mecon doctor

# 5. If doctor says the workspace is missing or incomplete:
mecon workspace init
mecon add run.py data.parquet
mecon sync
mecon doctor

# 6. Only submit after doctor passes.
mecon submit run.py --gpu l4
mecon watch <job_id>
mecon logs -f <job_id>
mecon sync

download still exists, but workspace mode should normally use sync to pull output/ artifacts back.

mecon doctor is the gate. It checks API configuration, connectivity, run.py, run(ctx), workspace manifest state, tracked files, and sync state. Use mecon doctor --json when a host or automation layer needs machine-readable results.

Worker contract

Jobs must expose run(ctx).

def run(ctx):
    ctx.log("Loading data")
    ctx.progress(0.1, "Loading data")

    # read from ctx.data_dir
    # write artifacts to ctx.output_dir

    ctx.save_checkpoint(step=1)
    ctx.progress(1.0, "Done")
    return {"diagnostics": {"converged": True}}

Available helpers:

• ctx.progress(pct, message)
• ctx.log(message)
• ctx.save_checkpoint(**arrays)
• ctx.load_checkpoint()
• ctx.has_checkpoint
• ctx.data_dir
• ctx.output_dir
• ctx.config
• ctx.gpu

Install and verify

python3 -m pip install -e .
pytest -q
python3 -m compileall src/maestro_economics

Plugin packaging

This repository now includes root-level plugin manifests for both ecosystems:

• Claude Code: .claude-plugin/plugin.json
• Claude marketplace: .claude-plugin/marketplace.json
• Codex: .codex-plugin/plugin.json

The repository itself is the plugin root. A separate Codex marketplace catalog is intentionally not added here because this repo is a single plugin source, not a multi-plugin catalog.

Claude Code bootstrap:

/plugin marketplace add maestro-ai-stack/maestro-economics
/plugin marketplace update maestro-economics
/plugin install maestro-economics@maestro-economics
/reload-plugins

If Claude reports Plugin "maestro-economics" not found in marketplace "maestro-economics", the local marketplace cache is stale or incomplete. Repair it with:

/plugin marketplace remove maestro-economics
/plugin marketplace add maestro-ai-stack/maestro-economics
/plugin install maestro-economics@maestro-economics
/reload-plugins

Bootstrap rule

/help/compute should stay bootstrap-only. It must tell the agent to:

1. refresh or install the host plugin or skill
2. upgrade the maestro-economics runtime package
3. run mecon doctor
4. follow the installed skill only after the doctor output identifies the next missing step

Do not duplicate the full workspace and submit flow on the website. The installed skill is the only operational source of truth.

Repository rule

Do not introduce a second runtime repo. If the skill, CLI, PyPI package, and worker drift apart again, the product becomes unreliable immediately.