From 2cf5127e815967dee30593a2f40ef24049e6d4b2 Mon Sep 17 00:00:00 2001 From: mvelasqu Date: Thu, 21 May 2026 11:10:24 -0600 Subject: [PATCH 1/2] feat: add agent markdown for better integration call --- AGENT.md | 110 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 AGENT.md diff --git a/AGENT.md b/AGENT.md new file mode 100644 index 0000000..d4bac57 --- /dev/null +++ b/AGENT.md @@ -0,0 +1,110 @@ +# plexosdb Agent Guide + +Quick operating contract for humans and agents working in this repository. This +is a README-level guide, not full system documentation. + +## North Star + +- Think a lot before changing code. Understand the system, then act. +- Collaborate in the open. Explain intent, tradeoffs, and risks. +- Prefer correct-by-construction designs over patch-on-patch fixes. +- Prioritize performance when selecting designs, algorithms, and data + structures. +- This is a model-processing and SQLite-focused application: watch query and + transform costs, measure behavior on representative fixtures, and avoid + unnecessary memory churn. +- Leave the codebase simpler than you found it. + +## Team Collaboration Rules + +- Assume concurrent work by other agents or humans. +- Treat `git status` and `git diff` as read-only context. +- Never revert or overwrite work you did not author. +- If a command hangs for more than 5 minutes, stop, capture context, and report. +- Prefer these repository-standard commands: + - `uv sync --all-groups` for a complete local dev environment + - `uv run prek run --show-diff-on-failure --color=always --all-files --hook-stage pre-push` + for CI-equivalent pre-push hooks + - `uv run ty check --output-format github ./src/plexosdb` for type checks + - `uv run pytest --cov --cov-report=xml` for test + coverage checks + - `uv run pytest benchmarks/ -k "not xlarge_300k" --benchmark-only --benchmark-json=benchmark-results.json --no-cov` + for benchmark runs + - `uv run sphinx-build docs/source/ docs/_build/` for docs build verification +- Before pushing, run the relevant CI-equivalent checks locally for changed + areas to catch failures early. + +## Engineering Workflow + +Use red-green-refactor for all non-trivial changes: + +1. Red: write or update a failing test that proves the behavior gap. +2. Green: implement the smallest correct change to pass. +3. Refactor: simplify while preserving behavior and keeping tests green. + +Additional expectations: + +- Start from first principles, not bandaids. +- No breadcrumbs. If you delete or move code, do not leave a comment in the old + place. No "moved to X", no "relocated". Just remove it. +- Research official docs before introducing new patterns or dependencies. +- Keep modules focused, remove dead code, and avoid unnecessary abstraction. +- Leave each area better than how you found it. + +## Testing Standards + +- Test a lot. If behavior changes, tests must prove it. +- Prefer deterministic unit and integration tests over brittle ad hoc checks. +- Avoid mocking internal/domain behavior when feasible; use boundary doubles + only when required (filesystem, network, time, subprocess, external services). +- Prefer fixture files under `tests/fixtures` and `tests/data` over large inline + literals. +- Add regression coverage for every bug fix. +- Unless the user asks otherwise, run only tests you added or modified. +- Run broader suites when risk is high or before major integration points. + +## Documentation Contract + +- Document everything that affects users, operators, or contributors. +- If the documentation does not exist, the feature does not exist. +- Documentation is a live document and must ship with code changes. +- Update README, docs pages, examples, and migration notes as needed. +- New APIs and behavior changes require updated docs in the same change. + +## Python Best Practices + +- Use `uv` with `pyproject.toml` for dependency management and command + execution. +- Run Python commands via `uv run`. +- Require explicit type hints and structured return types. +- Prefer dataclasses, TypedDicts, and focused domain objects over loose + dictionaries. +- Keep signatures clear and avoid overly wide positional-argument APIs. +- Name functions so the action and target object are explicit. +- Avoid broad `try/except` blocks and catch-all exception handling. +- Let errors surface with clear types and fail fast at boundaries. +- Keep hot paths and repeated DB operations efficient. + +## Python Testing + +- Use `pytest` with function-based tests and fixtures. +- Avoid class-based test organization unless there is a compelling reason. +- Keep tests readable and focused on a single behavior per test. + +## Commit Style + +- Use Conventional Commits (for example, `feat:`, `fix:`, `docs:`, `test:`). + +## Dependency Policy + +- Add dependencies only when necessary. +- Choose actively maintained libraries with strong ecosystem adoption. +- Validate maintenance, API quality, and long-term fit before adding. + +## Final Handoff + +Before marking work complete: + +1. List what changed and why. +2. List commands/tests run and their result. +3. List documentation updates made. +4. Call out follow-ups, risks, or open questions. From 91f891d94df1c34e1dd9ac75ff955269e275eff3 Mon Sep 17 00:00:00 2001 From: mvelasqu Date: Sat, 6 Jun 2026 20:00:40 -0600 Subject: [PATCH 2/2] fix: update agents file contents and run formatter --- AGENT.md | 110 ----------------------------- AGENTS.md | 10 +++ tests/test_plexosdb_copy_object.py | 16 ++--- 3 files changed, 14 insertions(+), 122 deletions(-) delete mode 100644 AGENT.md create mode 100644 AGENTS.md diff --git a/AGENT.md b/AGENT.md deleted file mode 100644 index d4bac57..0000000 --- a/AGENT.md +++ /dev/null @@ -1,110 +0,0 @@ -# plexosdb Agent Guide - -Quick operating contract for humans and agents working in this repository. This -is a README-level guide, not full system documentation. - -## North Star - -- Think a lot before changing code. Understand the system, then act. -- Collaborate in the open. Explain intent, tradeoffs, and risks. -- Prefer correct-by-construction designs over patch-on-patch fixes. -- Prioritize performance when selecting designs, algorithms, and data - structures. -- This is a model-processing and SQLite-focused application: watch query and - transform costs, measure behavior on representative fixtures, and avoid - unnecessary memory churn. -- Leave the codebase simpler than you found it. - -## Team Collaboration Rules - -- Assume concurrent work by other agents or humans. -- Treat `git status` and `git diff` as read-only context. -- Never revert or overwrite work you did not author. -- If a command hangs for more than 5 minutes, stop, capture context, and report. -- Prefer these repository-standard commands: - - `uv sync --all-groups` for a complete local dev environment - - `uv run prek run --show-diff-on-failure --color=always --all-files --hook-stage pre-push` - for CI-equivalent pre-push hooks - - `uv run ty check --output-format github ./src/plexosdb` for type checks - - `uv run pytest --cov --cov-report=xml` for test + coverage checks - - `uv run pytest benchmarks/ -k "not xlarge_300k" --benchmark-only --benchmark-json=benchmark-results.json --no-cov` - for benchmark runs - - `uv run sphinx-build docs/source/ docs/_build/` for docs build verification -- Before pushing, run the relevant CI-equivalent checks locally for changed - areas to catch failures early. - -## Engineering Workflow - -Use red-green-refactor for all non-trivial changes: - -1. Red: write or update a failing test that proves the behavior gap. -2. Green: implement the smallest correct change to pass. -3. Refactor: simplify while preserving behavior and keeping tests green. - -Additional expectations: - -- Start from first principles, not bandaids. -- No breadcrumbs. If you delete or move code, do not leave a comment in the old - place. No "moved to X", no "relocated". Just remove it. -- Research official docs before introducing new patterns or dependencies. -- Keep modules focused, remove dead code, and avoid unnecessary abstraction. -- Leave each area better than how you found it. - -## Testing Standards - -- Test a lot. If behavior changes, tests must prove it. -- Prefer deterministic unit and integration tests over brittle ad hoc checks. -- Avoid mocking internal/domain behavior when feasible; use boundary doubles - only when required (filesystem, network, time, subprocess, external services). -- Prefer fixture files under `tests/fixtures` and `tests/data` over large inline - literals. -- Add regression coverage for every bug fix. -- Unless the user asks otherwise, run only tests you added or modified. -- Run broader suites when risk is high or before major integration points. - -## Documentation Contract - -- Document everything that affects users, operators, or contributors. -- If the documentation does not exist, the feature does not exist. -- Documentation is a live document and must ship with code changes. -- Update README, docs pages, examples, and migration notes as needed. -- New APIs and behavior changes require updated docs in the same change. - -## Python Best Practices - -- Use `uv` with `pyproject.toml` for dependency management and command - execution. -- Run Python commands via `uv run`. -- Require explicit type hints and structured return types. -- Prefer dataclasses, TypedDicts, and focused domain objects over loose - dictionaries. -- Keep signatures clear and avoid overly wide positional-argument APIs. -- Name functions so the action and target object are explicit. -- Avoid broad `try/except` blocks and catch-all exception handling. -- Let errors surface with clear types and fail fast at boundaries. -- Keep hot paths and repeated DB operations efficient. - -## Python Testing - -- Use `pytest` with function-based tests and fixtures. -- Avoid class-based test organization unless there is a compelling reason. -- Keep tests readable and focused on a single behavior per test. - -## Commit Style - -- Use Conventional Commits (for example, `feat:`, `fix:`, `docs:`, `test:`). - -## Dependency Policy - -- Add dependencies only when necessary. -- Choose actively maintained libraries with strong ecosystem adoption. -- Validate maintenance, API quality, and long-term fit before adding. - -## Final Handoff - -Before marking work complete: - -1. List what changed and why. -2. List commands/tests run and their result. -3. List documentation updates made. -4. Call out follow-ups, risks, or open questions. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..11f0848 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,10 @@ +# AGENTS.md + +- Assume concurrent human/agent work; never revert or overwrite changes you did not author. +- This repo processes model data into SQLite; watch query/transform cost, memory churn, and fixture representativeness. +- Prefer minimal, behavior-proven changes; add regression coverage for bug fixes and use existing fixtures under `tests/fixtures` or `tests/data` when practical. +- No breadcrumbs after deleting or moving code; remove the old code/comment instead of leaving relocation notes. +- Use `uv sync --all-groups` for setup. For changed areas, run the narrow relevant check first; before broad handoff use `uv run prek run --show-diff-on-failure --color=always --all-files --hook-stage pre-push` when feasible. +- Type-check package changes with `uv run ty check --output-format github ./src/plexosdb`. +- Test package changes with `uv run pytest --cov --cov-report=xml`; benchmark-sensitive changes may need `uv run pytest benchmarks/ -k "not xlarge_300k" --benchmark-only --benchmark-json=benchmark-results.json --no-cov`. +- Build docs for user/operator-facing documentation changes with `uv run sphinx-build docs/source/ docs/_build/`. diff --git a/tests/test_plexosdb_copy_object.py b/tests/test_plexosdb_copy_object.py index 51ccbe8..c2263bf 100644 --- a/tests/test_plexosdb_copy_object.py +++ b/tests/test_plexosdb_copy_object.py @@ -60,12 +60,8 @@ def test_copy_object_copies_date_from_and_date_to(db_base: PlexosDB): date_to=date_to, ) - original_date_from = db.query( - "SELECT date FROM t_date_from WHERE data_id = ?", (original_data_id,) - ) - original_date_to = db.query( - "SELECT date FROM t_date_to WHERE data_id = ?", (original_data_id,) - ) + original_date_from = db.query("SELECT date FROM t_date_from WHERE data_id = ?", (original_data_id,)) + original_date_to = db.query("SELECT date FROM t_date_to WHERE data_id = ?", (original_data_id,)) assert original_date_from == [(date_from.isoformat(),)] assert original_date_to == [(date_to.isoformat(),)] @@ -77,12 +73,8 @@ def test_copy_object_copies_date_from_and_date_to(db_base: PlexosDB): new_data_id = new_data_ids[0] assert new_data_id != original_data_id - copied_date_from = db.query( - "SELECT date FROM t_date_from WHERE data_id = ?", (new_data_id,) - ) - copied_date_to = db.query( - "SELECT date FROM t_date_to WHERE data_id = ?", (new_data_id,) - ) + copied_date_from = db.query("SELECT date FROM t_date_from WHERE data_id = ?", (new_data_id,)) + copied_date_to = db.query("SELECT date FROM t_date_to WHERE data_id = ?", (new_data_id,)) assert copied_date_from == [(date_from.isoformat(),)] assert copied_date_to == [(date_to.isoformat(),)]