dpg-gauges/codex/AGENTS.md

AGENTS.md

Current status

Step 3 completed and verified with automated checks. Ready to start Step 4.

Completed steps

Initial setup before Step 1:

• uv package metadata exists.
• Runtime dependency dearpygui is installed.
• Dev dependencies pytest, ruff, and pyright are installed.
• Required package skeleton exists under src/dpg_gauges/.
• examples/, tests/, and docs/ directories exist.
• pyproject.toml is configured for Python 3.11+, Ruff, and Pyright.

Step 1 - Public API contract and pure core:

• Public API exports are defined in src/dpg_gauges/__init__.py.
• Public exceptions are defined in src/dpg_gauges/exceptions.py.
• Shared public dataclasses and type aliases are defined in src/dpg_gauges/types.py.
• Pure gauge configuration dataclasses are defined in src/dpg_gauges/gauges.py.
• Pure scale helpers are defined in src/dpg_gauges/scales.py.
• Lightweight theme/style presets are defined in src/dpg_gauges/themes.py.
• GUI-dependent public functions are import-safe stubs for Step 1.
• Step 1 tests cover public imports, dataclass construction, clamp/normalize math, tick generation, threshold validation, formatting, and missing-gauge stubs.

Current step

Step 4 - Digital, bar, level, and status gauges.

Step 3 - Widget shell and renderer foundation:

Implemented during Step 3:

• Added Dear PyGui widget shell creation for gauge context managers when a DPG context is active.
• Kept pure registration behavior when no DPG context has been created.
• Added a renderer foundation that measures drawlist size, redraws stable placeholder background/frame/value text, schedules animation frames, and exposes renderer debug fields.
• Added draw layer bookkeeping.
• Added lightweight gauge_panel and gauge_grid containers.
• Added Step 3 examples and smoke tests.

Step 2 - State, sizing, animation, and smoothing model:

Implemented during Step 2:

• Added DpgGaugesConfig, configure(...) wiring, GaugeState, DirtyFlags, and the global gauge registry.
• Runtime API functions now mutate logical state for values, config updates, thresholds, markers, visibility, and deletion without Dear PyGui calls.
• Added pure sizing helpers for requested/measured size, last non-zero size preservation, square rects, and stretch rects.
• Added pure animation interpolation helpers and smoothing progression helpers.
• Added debug state reporting for registered gauges.
• Added Step 2 tests for registry behaviour, clamped/displayed separation, dirty flags, sizing, animation, smoothing, and invalid values.

Design decisions

• Package is managed with uv.
• Public import is import dpg_gauges as dpgg.
• Package target is Python 3.11+.
• The package is Dear PyGui-only, but pure configuration/state helpers should avoid Dear PyGui imports where practical.
• Widget creation and Dear PyGui item operations are GUI-thread-only.
• Runtime value/configuration updates are intended to be called from the GUI thread.
• High-frequency updates should be smoothed/coalesced so gauges remain readable and flicker-free.
• Out-of-range values clamp to min/max and display the clamped value.
• Gauges are display-only for the first release.
• Thresholds and redline zones are visual only; they do not trigger events.
• The public API should feel like normal Dear PyGui context-manager usage.
• Each completed build step must be checked, documented in this file, and committed before starting the next step.

Known issues

Manual visual example checks were not run in this headless session.

Commands used

• Read codex-old/README.md, codex-old/FEATURES.md, codex-old/ARCHITECTURE.md, codex-old/STEPS.md, and codex-old/AGENTS.md.
• Inspected /home/hector/projects/dpg-map package, examples, tests, docs, and pyproject structure.
• Created the initial codex/ instruction documents for dpg-gauges.
• Read codex/README.md, codex/FEATURES.md, codex/ARCHITECTURE.md, codex/STEPS.md, and codex/AGENTS.md.
• Completed missing pre-Step-1 skeleton files and directories.
• Ran uv run python -c "import dpg_gauges; print(dpg_gauges.__name__)".
• Ran uv run ruff check ..
• Ran uv run ruff format ..
• Read all files under codex/.
• Implemented Step 1 public API exports and pure core modules.
• Added tests/test_step1_core.py.
• Ran uv run pytest.
• Ran uv run ruff check ..
• Ran uv run ruff format --check ..
• Ran uv run pyright.
• Read codex/FEATURES.md, codex/ARCHITECTURE.md, codex/STEPS.md, and codex/AGENTS.md before Step 2 changes.
• Implemented Step 2 state, sizing, animation, smoothing, runtime API, diagnostics, tests, and README status update.
• Ran uv run pytest.
• Ran uv run ruff check ..
• Ran uv run ruff format --check ..
• Ran uv run pyright.
• Updated instructions to require a commit after each completed step.
• Read codex/FEATURES.md, codex/ARCHITECTURE.md, codex/STEPS.md, and codex/AGENTS.md before Step 3 changes.
• Implemented Step 3 widget shells, renderer foundation, draw layer bookkeeping, layout helpers, examples, smoke tests, README status update, and diagnostics renderer fields.
• Ran uv run pytest.
• Ran uv run ruff check ..
• Ran uv run ruff format ..
• Ran uv run ruff format --check ..
• Ran uv run pyright.

Next action

Implement Step 4.