lib

Imported from green-coding-solutions/green-metrics-tool (lib/AGENTS.md). Install upstream with npx skills add green-coding-solutions/green-metrics-tool --skill lib. Copyright stays with the author.

Lib Agent Guide

lib/ contains the core orchestration and shared implementation used by the CLI, API, cron workers, and tests.

Key files

• scenario_runner.py
  • Main measurement lifecycle, repository checkout, workload execution, provider startup, persistence, cleanup, and post-processing
• job/base.py
  • Queue selection, state transitions, DB persistence, and job object construction
• job/run.py
  • Run-job execution wrapper around ScenarioRunner
• schema_checker.py
  • Validation rules for usage_scenario.yml
• metric_importer.py
  • Imports provider output into DB structures
• phase_stats.py
  • Computes phase-level summaries after a run
• db.py, global_config.py, user.py
  • Shared infrastructure used almost everywhere

Working rules

• Treat ScenarioRunner as the canonical measurement pipeline. Avoid duplicating its logic in API or cron code.
• Do not casually reorder or remove cleanup / post-processing steps in ScenarioRunner; those steps guard persistence and cleanup after partial failures.
• When adding arguments to ScenarioRunner beware that if they contain sensitive information they must be pruned from self._arguments at the end of the `init()``
• When adding fields that must survive from API submission to execution, update job/base.py, job/run.py, and runner.py together.
• Secret usage scenario variables (__GMT_VAR_SECRET_*__) only ever exist in plaintext inside ScenarioRunner.__usage_scenario_variables_resolved. Anything that is persisted or printed must go through self._usage_scenario_variables (encrypted) or utils.filter_sensitive_data(_structure).
• Tests override config through tests/conftest.py; avoid hard-coding production config assumptions.
• lib/c/ and lib/sgx-software-enable/ contain native build artifacts and helpers. Only touch them if the change actually affects native behavior or installation.

Common pitfalls

• Job state changes are part of a queue state machine; preserve the WAITING -> RUNNING -> FINISHED/FAILED semantics unless you are intentionally changing workflow behavior.
• Many helpers are imported widely. Small signature changes here can create broad regressions, so verify impact with targeted tests.