freq-pick 0.1.0__tar.gz

freq_pick-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

freq_pick-0.1.0/AGENTS.md

@@ -0,0 +1,156 @@
+# AGENTS.md
+
+This file guides agentic coding assistants working in this repository.
+
+## Repository Overview
+
+- Project: `freq-pick`
+- Language: Python
+- Python version: 3.13 (from `pyproject.toml`)
+- Package manager: `uv` (authoritative)
+- Build backend: hatchling (authoritative)
+- Current entry point: `main.py`
+- Source tree: `src/` currently empty
+
+## Authoritative Rules (carry into all work)
+
+These are sourced from `docs/python_toolbox.md` and `docs/agent_executor_instructions_v_1.md`.
+
+- Use `uv` for all installs and runs. Do not use `pip`, `venv`, or `conda`.
+- Treat handoff documents as the only contract; do not invent requirements.
+- If requirements are ambiguous, stop and report the blocker.
+- Run required tests without asking permission when executing a handoff.
+- Do not skip the Definition of Done; report failures and stop.
+- Avoid reflection or string-based magic (`getattr`, `setattr`, dynamic wiring).
+- Keep modules and functions small and conceptually focused.
+
+## Cursor / Copilot Rules
+
+- No `.cursor/rules/`, `.cursorrules`, or `.github/copilot-instructions.md` found.
+
+## Commands: Build / Lint / Test
+
+The repository does not currently define tool configs in `pyproject.toml`.
+Follow the toolbox defaults if tools are installed.
+
+### Environment Setup
+
+- Install dependencies: `uv sync`
+- Add dependency: `uv add <package>`
+- Add dev dependency: `uv add --dev <package>`
+
+### Build
+
+- Build package: `uv build`
+
+### Format
+
+- Format all code: `uv run black .`
+
+### Type Check
+
+- Run mypy: `uv run mypy .`
+
+### Lint (optional, only if introduced)
+
+- Run ruff: `uv run ruff check .`
+
+### Test
+
+- Run all tests: `uv run pytest`
+
+### Test: Single File
+
+- Run a file: `uv run pytest tests/test_example.py`
+
+### Test: Single Test
+
+- Run a test by node id:
+  `uv run pytest tests/test_example.py::test_name`
+
+### Test: By Keyword
+
+- Run matching tests:
+  `uv run pytest -k "keyword"`
+
+## Code Style Guidelines
+
+The project is minimal; follow the defaults below unless a handoff overrides them.
+
+### Formatting
+
+- Use Black defaults for formatting.
+- Prefer explicit, readable code over clever expressions.
+- Avoid dense comprehensions when a simple loop is clearer.
+
+### Imports
+
+- Standard library imports first, third-party next, local imports last.
+- One import per line when it improves clarity.
+- Avoid wildcard imports.
+- Keep imports minimal and local to the module that uses them.
+
+### Typing
+
+- Type hints are required for new or modified public APIs.
+- Avoid `Any` unless justified and localized.
+- Prefer explicit types to dynamic behavior.
+- Public dataclasses and functions should be fully typed.
+
+### Naming
+
+- Use `snake_case` for functions and variables.
+- Use `PascalCase` for classes and dataclasses.
+- Use `UPPER_CASE` for module constants.
+- Name variables for intent, not type (`freq_hz`, not `arr1`).
+
+### Error Handling
+
+- Validate inputs early and raise `ValueError` for bad arguments.
+- Prefer explicit exceptions over silent fallback.
+- In CLI entry points, convert errors to non-zero exits.
+- Do not swallow exceptions unless the caller explicitly needs it.
+
+### Structure and Size
+
+- Keep files focused by concept (core logic, UI, IO, CLI).
+- Keep functions small and single-purpose.
+- Avoid multi-responsibility "god" modules.
+
+### Reflection / Magic
+
+- Do not use reflection or string-based wiring.
+- Avoid dynamic attribute access and `getattr`/`setattr`.
+- Prefer explicit dependencies and direct method calls.
+
+### Testing Conventions
+
+- Tests live in `tests/`.
+- Name test files `test_*.py`.
+- Prefer small, deterministic tests with synthetic data.
+- For matplotlib tests, use the Agg backend when headless.
+
+## Project Layout (recommended by toolbox)
+
+```text
+project-root/
+├── pyproject.toml
+├── README.md
+├── src/
+│   └── freq_pick/
+│       ├── __init__.py
+│       ├── core.py
+│       ├── mpl_ui.py
+│       ├── artifacts.py
+│       └── cli.py
+├── tests/
+│   └── test_*.py
+└── docs/
+```
+
+## Notes for Agents
+
+- Repository currently contains only `main.py` as a placeholder.
+- No tests exist yet; create tests when adding new behavior.
+- Keep dependency list minimal (the handoff allows numpy + matplotlib).
+- Use `uv run <command>` for any execution.

freq_pick-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 placerte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

freq_pick-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: freq-pick
+Version: 0.1.0
+Summary: Add your description here
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Description-Content-Type: text/markdown
+
+# freq-pick
+
+Interactive frequency picker for a single spectrum. The API accepts a precomputed
+frequency axis and magnitude array, launches a matplotlib UI, and returns a
+deterministic list of selected bin indices and frequencies. Optional PNG/JSON
+artifacts capture the selection.
+
+## Install
+
+```bash
+uv sync
+```
+
+## API (primary)
+
+```python
+from pathlib import Path
+import numpy as np
+
+from freq_pick.core import Spectrum
+from freq_pick.core import pick_freqs_matplotlib
+
+f_hz = np.linspace(0.0, 200.0, 1001)
+mag = np.sin(f_hz / 10.0) ** 2
+
+spectrum = Spectrum(f_hz=f_hz, mag=mag, display_domain="linear")
+selection = pick_freqs_matplotlib(
+    spectrum,
+    user_snap_hz=0.5,
+    xlim=(0.0, 200.0),
+    title="Demo",
+    title_append="[1/5]",
+    artifact_dir=Path("artifacts"),
+    artifact_stem="demo",
+)
+
+print(selection.selected_idx)
+print(selection.selected_hz)
+```
+
+### Controls
+
+- `shift + drag` rectangle: select max magnitude in the rectangle
+- `q`: commit and quit
+- `Esc`: cancel
+- `c`: clear selection
+- `x`: delete nearest selected peak to cursor
+- `l`: toggle y scale (linear/dB)
+- `h`: toggle help overlay
+
+## CLI
+
+```bash
+uv run freq-pick \
+  --in spectrum.npz \
+  --out artifacts \
+  --stem run1 \
+  --snap-hz 0.5 \
+  --domain dB \
+  --xlim 0 200 \
+  --title "Spec A" \
+  --title-append "[3/10]"
+```
+
+Input `.npz` must include `f_hz` and `mag` arrays.
+
+## Artifacts
+
+When `artifact_dir` and `artifact_stem` are provided, the picker writes:
+
+- `{stem}_pick.png`
+- `{stem}_pick.json`
+
+JSON keys:
+
+- `schema_version`
+- `selected_hz`
+- `selected_idx`
+- `settings`
+- `spectrum_meta`
+- `display_domain`
+
+## Development
+
+```bash
+uv run pytest
+```

freq_pick-0.1.0/README.md

@@ -0,0 +1,87 @@
+# freq-pick
+
+Interactive frequency picker for a single spectrum. The API accepts a precomputed
+frequency axis and magnitude array, launches a matplotlib UI, and returns a
+deterministic list of selected bin indices and frequencies. Optional PNG/JSON
+artifacts capture the selection.
+
+## Install
+
+```bash
+uv sync
+```
+
+## API (primary)
+
+```python
+from pathlib import Path
+import numpy as np
+
+from freq_pick.core import Spectrum
+from freq_pick.core import pick_freqs_matplotlib
+
+f_hz = np.linspace(0.0, 200.0, 1001)
+mag = np.sin(f_hz / 10.0) ** 2
+
+spectrum = Spectrum(f_hz=f_hz, mag=mag, display_domain="linear")
+selection = pick_freqs_matplotlib(
+    spectrum,
+    user_snap_hz=0.5,
+    xlim=(0.0, 200.0),
+    title="Demo",
+    title_append="[1/5]",
+    artifact_dir=Path("artifacts"),
+    artifact_stem="demo",
+)
+
+print(selection.selected_idx)
+print(selection.selected_hz)
+```
+
+### Controls
+
+- `shift + drag` rectangle: select max magnitude in the rectangle
+- `q`: commit and quit
+- `Esc`: cancel
+- `c`: clear selection
+- `x`: delete nearest selected peak to cursor
+- `l`: toggle y scale (linear/dB)
+- `h`: toggle help overlay
+
+## CLI
+
+```bash
+uv run freq-pick \
+  --in spectrum.npz \
+  --out artifacts \
+  --stem run1 \
+  --snap-hz 0.5 \
+  --domain dB \
+  --xlim 0 200 \
+  --title "Spec A" \
+  --title-append "[3/10]"
+```
+
+Input `.npz` must include `f_hz` and `mag` arrays.
+
+## Artifacts
+
+When `artifact_dir` and `artifact_stem` are provided, the picker writes:
+
+- `{stem}_pick.png`
+- `{stem}_pick.json`
+
+JSON keys:
+
+- `schema_version`
+- `selected_hz`
+- `selected_idx`
+- `settings`
+- `spectrum_meta`
+- `display_domain`
+
+## Development
+
+```bash
+uv run pytest
+```

freq_pick-0.1.0/artifacts/demo_pick.json

@@ -0,0 +1,37 @@
+{
+  "display_domain": "dB",
+  "schema_version": "1",
+  "selected_hz": [
+    25.0,
+    60.0,
+    69.5,
+    120.0,
+    175.0
+  ],
+  "selected_idx": [
+    50,
+    120,
+    139,
+    240,
+    350
+  ],
+  "settings": {
+    "crop_to_xlim": true,
+    "df_hz": 0.5,
+    "effective_snap_hz": 1.5,
+    "modifier": "shift",
+    "picker_keymap": {
+      "cancel": "escape",
+      "clear": "c",
+      "commit": "q",
+      "delete_nearest": "x",
+      "help": "h"
+    },
+    "user_snap_hz": 0.5,
+    "xlim": [
+      0.0,
+      200.0
+    ]
+  },
+  "spectrum_meta": {}
+}

freq_pick-0.1.0/docs/agent_executor_instructions_v_1.md

@@ -0,0 +1,73 @@
+# Agent Executor – Instructions (v1)
+
+You are an **execution agent** operating in a structured LLM workflow.
+
+Your role is to implement, test, and report based **only** on written artifacts.
+
+---
+
+## Authority & Scope
+
+- The **handoff document** is the sole contract.
+- Chat history is not authoritative.
+- You do not:
+  - invent requirements
+  - reinterpret scope
+  - make design decisions
+
+If something is ambiguous or missing, **stop and report**.
+
+---
+
+## Your Responsibilities
+
+When given a handoff file:
+
+- Implement all specified specs
+- Follow implementation constraints exactly
+- Create missing tests when required
+- Run all relevant tests without asking permission
+- Satisfy the Definition of Done
+
+Testing is part of execution, not an optional step.
+
+---
+
+## Definition of Done – Enforcement
+
+A task is DONE only if:
+
+- All specified tests are created (if missing)
+- All tests are executed successfully
+- All commands succeed
+- No spec item remains partially implemented
+
+If a DoD item cannot be satisfied:
+
+- Stop execution
+- Report the blocker
+- Do not claim completion
+
+---
+
+## Stop Conditions
+
+Stop when:
+
+- The Definition of Done is fully satisfied, or
+- A blocking ambiguity or failure is encountered and reported
+
+Do not optimize, refactor, or polish unless explicitly requested in the handoff.
+
+---
+
+## Awareness of Upstream Role
+
+- A web client acts as the design authority
+- Your output feeds the next iteration via new handoffs
+- You do not negotiate scope or intent
+
+---
+
+**Status:** Agent Executor Instructions v1
+