h3cx/dpg-gauges
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
v1.0.2
dpg-gauges/codex/AGENTS.md

10 KiB
Raw Permalink Blame History

AGENTS.md

Current status

Step 7 completed and verified with automated checks. Step 7 commit and beta tag are pending.

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 7 - Documentation, hardening, and beta release.

Implemented during Step 7:

  • Rewrote README.md with install, minimal examples, dashboard usage, GUI-thread expectations, animation/smoothing, and thresholds/markers.
  • Added docs/GETTING_STARTED.md, docs/EXAMPLES.md, and docs/API_REFERENCE.md.
  • Added docstrings for all public exported callables.
  • Reviewed public API exports and added __version__.
  • Added Step 7 hardening tests for unknown gauges, duplicate tags, invalid ranges, invalid thresholds, invalid markers, non-finite values, deleted updates, hidden sizing, and animation disabled/enabled behavior.
  • Bumped package version to 0.1.0b1.
  • Verified a local editable install from a temporary project.

Step 6 - High-rate updates, animation, and stress examples:

Implemented during Step 6:

  • Runtime updates now start animations using monotonic time for public calls.
  • Optional smoothing now progresses displayed values toward the latest target instead of snapping immediately.
  • Repeated GUI-thread value updates coalesce naturally to the newest target with no explicit queue.
  • Renderer frame scheduling remains guarded so continuous callbacks are scheduled only while animation or smoothing is active.
  • Debug state now includes detailed animation and smoothing fields.
  • Added examples/animations.py, examples/live_high_rate.py, and examples/live_worst_case.py using GUI-thread frame callbacks for Dear PyGui updates.
  • Added Step 6 tests for animation convergence, smoothing reset behaviour, latest-target wins, and renderer scheduling.

Step 5 - Analog, segmented, compass, thermometer, battery, and multi-value gauges:

Implemented during Step 5:

  • Added analog and compass dial rendering with arcs, ticks, tick labels, needles, redline bands, and markers.
  • Added compass heading wraparound for runtime values.
  • Added segmented gauge rendering with active segment calculation.
  • Added thermometer and battery-specific drawlist rendering.
  • Added multi-value gauge rendering.
  • Added Step 5 examples and tests for angle math, tick generation, compass wraparound, segment activation, battery clamp, and multi-value rendering.

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

Implemented during Step 4:

  • Added digital gauge drawlist rendering with formatted value text.
  • Added bar and level gauge rendering with horizontal/vertical fill geometry.
  • Added threshold band and marker drawing for bar/level gauges.
  • Added status light rendering with configured status state colors and text.
  • Added Dear PyGui item callback wiring for gauges with callback=.
  • Added Step 4 examples and tests for geometry, runtime updates, thresholds, markers, and status states.

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/stress example checks for Steps 3, 4, 5, 6, and 7 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.
  • Committed Step 4 with git commit -m "step 4: add digital bar level and status gauges" before starting Step 5.
  • Read codex/FEATURES.md, codex/ARCHITECTURE.md, codex/STEPS.md, and codex/AGENTS.md before Step 5 changes.
  • Implemented Step 5 first catalogue rendering, compass wraparound, examples, README status update, and tests.
  • Ran uv run pytest.
  • Ran uv run ruff check ..
  • Ran uv run ruff format ..
  • Ran uv run ruff format --check ..
  • Ran uv run pyright.
  • Committed Step 6 with git commit -m "step 6: add animation and high rate update stress tests" before starting Step 7.
  • Read codex/FEATURES.md, codex/ARCHITECTURE.md, codex/STEPS.md, and codex/AGENTS.md before Step 7 changes.
  • Implemented Step 7 README/docs, public callable docstrings, hardening tests, version bump, and README/API status updates.
  • Ran uv run python - <<'PY' ... to verify all exported callables have docstrings.
  • Ran uv sync.
  • Ran uv run pytest.
  • Ran uv run ruff check ..
  • Ran uv run ruff format --check ..
  • Ran uv run pyright.
  • Created /tmp/opencode/dpg-gauges-editable-check, ran uv init --bare --name dpg-gauges-editable-check, uv add --editable /home/hector/projects/dpg-gauges, and uv run python -c "import dpg_gauges as dpgg; print(dpgg.__name__)".
  • Committed Step 5 with git commit -m "step 5: complete first gauge catalogue" before starting Step 6.
  • Read codex/FEATURES.md, codex/ARCHITECTURE.md, codex/STEPS.md, and codex/AGENTS.md before Step 6 changes.
  • Implemented Step 6 animation/smoothing scheduling refinements, high-rate examples, README status update, diagnostics fields, and tests.
  • Ran uv run pytest.
  • Ran uv run ruff check ..
  • Ran uv run ruff format ..
  • 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.
  • Committed Step 3 with git commit -m "step 3: add widget shell and renderer foundation" before starting Step 4.
  • Read codex/FEATURES.md, codex/ARCHITECTURE.md, codex/STEPS.md, and codex/AGENTS.md before Step 4 changes.
  • Implemented Step 4 digital, bar, level, and status rendering, threshold/marker drawing, callback wiring, examples, README status update, and tests.
  • Ran uv run pytest.
  • Ran uv run ruff check ..
  • Ran uv run ruff format --check ..
  • Ran uv run pyright.

Next action

Commit Step 7 and tag v0.1.0b1 if requested.

Reference in New Issue View Git Blame Copy Permalink