agent.md

Agent Notes

• Use the edit conda environment for ChartPipeline commands: /data/wangzheng/miniconda3/envs/edit/bin/python.
• When invoking Python commands directly, prefer: PYTHONPATH=. /data/wangzheng/miniconda3/envs/edit/bin/python ....
• For rendering, set: PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome and RENDER_LONGEST_SIDE=1600.
• For full pipeline runs in a non-login shell, include both runtime dirs in PATH: export PATH=/data/wangzheng/miniconda3/envs/edit/bin:/data/wangzheng/miniconda3/envs/edit/lib/python3.12/site-packages/playwright/driver:$PATH.
• The post-generation icon/image module is modules.asset_regenerator.asset_regenerator. It runs after infographics_generator, builds one contact sheet containing the full infographic plus all selected SVG <image> assets, calls gpt-image-2, chroma-keys the generated cells, and replaces only the original SVG <image href> / xlink:href values with data URI PNGs.
• During variation repair, do not call gpt-image-2 while iterating on template/data fixes. First regenerate with --modules infographics_generator only, or run asset regeneration with --dry-run if candidate discovery needs checking. Run the real asset_regenerator only after the template-side repair passes structural/rendered validation.
• Keep before/after evidence for each repaired variation. Preserve the original sample SVG/PNG or render a baseline from the unmodified template, then store side-by-side comparison artifacts under an output/chart_repair_comparison_* directory.
• Keep complete code backups for every full variation-repair or style-reference iteration. Before editing a variation, create a timestamped backup directory under backups/ and include every variation template plus every support file that may be changed in the iteration, such as docs, agent notes, pipeline modules, generator utilities, asset-regenerator code, and helper scripts.
• Each complete iteration backup must keep three separate trees:
  • before_head: the original repair-before version from HEAD:<path> for tracked files, or a missing marker for files added during repair work.
  • before: the exact workspace state immediately before the iteration edits begin.
  • after: the exact workspace state after patching, regenerating, verifying, and documenting the iteration.
• Never overwrite an older backup tree. If a file was already modified before the next iteration, preserve that pre-edit copy in before so the new iteration can be separated from earlier repairs. For untracked support files, write a missing marker in before_head, copy the pre-edit file into before, and copy the final file into after.
• Every backup directory must include files.tsv, manifest.md, pre/post git status --short, relevant git diff --stat, generated output paths, comparison evidence paths, verification evidence paths, and whether gpt-image-2 or asset_regenerator was called. The manifest must make clear which tree is the repair-before code and which tree is the current/final code.
• Run it in the pipeline with: --modules infographics_generator asset_regenerator.
• To test without calling the image model: PYTHONPATH=. /data/wangzheng/miniconda3/envs/edit/bin/python -m modules.asset_regenerator.asset_regenerator --svg <final.svg> --png <final.png> --dry-run.
• The image edit call defaults to --model gpt-image-2 --input-fidelity high so the model sees the rendered infographic as context while only regenerating the green contact-sheet asset cells.
• Keep this module scoped to decorative icon/image assets. Do not use it to raster-overwrite the chart, title, labels, axes, legends, data values, chart marks, or background unless explicitly passing --include-background for a controlled experiment.
• For style-reference iterations, compare the current baseline for a variation against existing PNGs under ../chart_template_samples_20260527_083945/gpt_image_2_improved/<variation>. If the variation was repaired in docs/variation_repair_status.md, use the repaired output as the baseline; otherwise use ../data/all_variations_check/template_variations_20260527/<variation>. Choose one simple, readable, low-decoration GPT-improved reference as the style anchor, but do not copy its chart geometry or numeric values when they conflict with source data.
• During style-reference iterations, do not call gpt-image-2; existing GPT-improved PNGs are references only. Keep title/icon/image generation on the existing pipeline path for now.
• For every style-reference iteration, keep a timestamped code backup under backups/, regenerate 5 outputs, write a baseline/reference/after comparison under output/style_ref_comparison_*, verify chart type and data mappings structurally, and record the iteration in docs/style_reference_repair_status.md.