From 15167763e7153b4a67a7d30a443520a35378b6bd Mon Sep 17 00:00:00 2001 From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> Date: Sat, 31 May 2025 10:13:44 -0400 Subject: [PATCH] Update AGENTS.md with detailed execution command guidelines Clarify the usage of the `startup.sh` wrapper for running Python scripts, emphasizing the importance of module execution and correct import resolution. Include examples for preferred script invocation and reinforce the need to avoid running `refresh_data.py` in environments without internet access. Adjust language for clarity and consistency throughout the document. --- AGENTS.md | 49 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 37 insertions(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c29546d..e0fb706 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,13 +1,30 @@ # AGENTS.md — Guidance for OpenAI Codex ## Execution Commands -- **Always** invoke Python scripts via the startup wrapper, which installs dependencies globally and then runs your code under the system Python: - +- **Always** invoke Python scripts via the `startup.sh` wrapper, which installs dependencies globally and then runs your code under the system Python. In particular, don’t run a `.py` file directly if it uses imports like `from scripts.common …`. Instead, run it as a module or let `startup.sh` handle it. For example: + ```bash + # Preferred: let startup.sh dispatch to scripts.lagged_oil_unrate_chart_styled ./startup.sh --offset --end --extend-years + + # Or explicitly in module mode, so that 'scripts' is on PYTHONPATH: + ./startup.sh python -m scripts.lagged_oil_unrate_chart_styled --offset --end --extend-years ```` -* **Never** call `refresh_data.py` from within a Task Command. This environment has **no internet access**, so attempts to fetch external data will fail. Data in `data/fred.db` must already be present. +* Running a script this way ensures that `import scripts.common` (and other `scripts.*` imports) resolve correctly. + +* If you ever need to call a different script, still invoke it under `./startup.sh`, for example: + + ```bash + # Custom-chart example: + ./startup.sh python -m scripts.custom_chart --series UNRATE DCOILWTICO --start 2000-01-01 --end 2020-12-31 + ``` + +* **Never** call `refresh_data.py` from within a Task Command. This environment has **no internet access**, so attempts to fetch external data will fail. Data in `data/fred.db` must already be present. If you need to refresh data, run it only in an internet-connected shell: + + ```bash + python scripts/refresh_data.py --series UNRATE DCOILWTICO --start 1973-01-01 + ``` ## Policy for Handling UNRATE Null Values @@ -20,7 +37,7 @@ When generating the UNRATE vs. Oil chart, the UNRATE series may include a `NaN` ```python last_date = unrate.last_valid_index() ``` - * Truncate both `unrate` and `oil` so that any trailing `NaN` row in `unrate` (and corresponding index in `oil`) is removed: + * Truncate both `unrate` and `oil` so that any trailing `NaN` row in `unrate` (and the corresponding index in `oil`) is removed: ```python unrate = unrate.loc[:last_date] @@ -35,7 +52,13 @@ When generating the UNRATE vs. Oil chart, the UNRATE series may include a `NaN` 3. **Implementation in `lagged_oil_unrate_chart_styled.py`** - * Right after `unrate, oil = fetch_series(start_dt, end_dt, args.db)`, insert: + * Right after: + + ```python + unrate, oil = fetch_series(start_dt, end_dt, args.db) + ``` + + insert: ```python last_date = unrate.last_valid_index() @@ -67,7 +90,7 @@ Future extensions will add additional custom chart scripts under `scripts/`, all ./startup.sh ``` - Installs/upgrades dependencies globally and runs the default lagged‐oil chart with an 18‐month offset. + Installs/upgrades dependencies globally and runs the default lagged-oil chart with an 18-month offset. * **Custom plot**: @@ -75,13 +98,15 @@ Future extensions will add additional custom chart scripts under `scripts/`, all ./startup.sh --offset 12 --end 2025-05-31 --extend-years 5 ``` + (Equivalent to `./startup.sh python -m scripts.lagged_oil_unrate_chart_styled --offset 12 --end 2025-05-31 --extend-years 5`.) + * **Data refresh (offline environments)**: * **Do not** run `refresh_data.py` in Codex/CI — data must already be in `data/fred.db`. - * To update data in an internet‐connected shell, run: + * To update data in an internet-connected shell, run: ```bash - python scripts/refresh_data.py + python scripts/refresh_data.py --series UNRATE DCOILWTICO ``` * **Run tests**: @@ -92,15 +117,15 @@ Future extensions will add additional custom chart scripts under `scripts/`, all ### Argument Rules -* If the first token starts with `--`, it’s forwarded to the default chart script. -* If the first token names a `.py` script, it’s executed via `python