Restructure the package, modernize the tooling, and refactor Qube

.claude/rules/dependency_management.md

@@ -0,0 +1,52 @@
+---
+description: Standards for declaring, installing, and maintaining Python project dependencies.
+---
+
+# Dependency Management
+
+## 1. Single Source of Truth
+
+- Declare ALL dependencies in **`pyproject.toml`** under `[project]` (PEP 621).
+- Do NOT maintain a separate hand-written `requirements.txt` for runtime dependencies. If a `requirements.txt` is kept, it should contain only `-e .` for backward compatibility.
+
+## 2. Dependency Groups
+
+| Group | Section | Install command | Purpose |
+|-------|---------|-----------------|---------|
+| **Runtime** | `[project].dependencies` | `pip install .` | Required for the package to function. |
+| **Dev** | `[project.optional-dependencies].dev` | `pip install -e ".[dev]"` | Testing, linting, type-checking, coverage. |
+| **Docs** | `[project.optional-dependencies].docs` | `pip install -e ".[docs]"` | Sphinx and documentation extensions. |
+
+## 3. Version Constraints
+
+- Specify **minimum** compatible versions for direct dependencies (e.g., `numpy>=2.2.0`).
+- Do NOT pin exact versions (`==`) in library projects; exact pinning belongs in lock files or application deployments.
+- For dev/docs dependencies, specify minimum versions to ensure consistent tool behavior across contributors.
+
+## 4. Adding or Updating Dependencies
+
+1. Add the dependency to the correct section in `pyproject.toml`.
+2. Run `pip install -e ".[dev]"` (or the relevant group) to verify installation.
+3. Run the full test suite and type-check to confirm compatibility.
+4. Commit the `pyproject.toml` change with a `build:` commit type.
+
+## 5. Security and Maintenance
+
+- Run `pip audit` in CI to catch known vulnerabilities.
+- Enable automated dependency update tooling (Dependabot, Renovate).
+- Review update PRs for breaking changes before merging.
+- Periodically remove unused dependencies to reduce attack surface.
+
+## 6. Tooling Configuration
+
+Consolidate all tool configuration into `pyproject.toml` where supported:
+
+| Tool | Section |
+|------|---------|
+| pytest | `[tool.pytest.ini_options]` |
+| coverage | `[tool.coverage.run]`, `[tool.coverage.report]` |
+| mypy | `[tool.mypy]`, `[[tool.mypy.overrides]]` |
+| ruff | `[tool.ruff]`, `[tool.ruff.lint]` — use explicit `select = [...]` for E, F, W, I, UP, B, SIM, C4, A, N, PT, RUF (see python) |
+| setuptools_scm | `[tool.setuptools_scm]` |
+
+Do NOT create separate config files (`.coveragerc`, `.mypy.ini`, `.flake8`, `setup.cfg`) when the tool supports `pyproject.toml`.

.claude/rules/doc_dev_guide.md

@@ -0,0 +1,122 @@
+---
+description: Format, layout, and completeness rules for the developer/contributor guide of a Python package, covering repository layout, class diagrams, per-module prose, and the API reference.
+paths:
+  - "docs/**/*.rst"
+  - "docs/**/*.md"
+---
+
+# Developer Guide
+
+The developer guide is the manual for people who **modify, extend, build, test,
+or release** the package. It explains how the code is organized, how the pieces
+cooperate, and how to work on it safely. Build on `doc_python` (Sphinx,
+cross-references, prose, build discipline). Assume a competent Python developer
+who is new to *this* codebase; favor architecture and contracts over restating
+what the code already says.
+
+## 1. File Layout
+
+- Live under `docs/` (commonly a `dev_guide/` subdirectory) as reStructuredText.
+- A single landing page (e.g. `dev_guide.rst`) holds a 1-2 sentence audience
+  statement and a `toctree` (deep `:maxdepth:`) listing the chapters in reading
+  order, ending with the API reference and the contribution guide.
+- Organize chapters by subsystem, plus cross-cutting chapters (introduction,
+  architecture/class hierarchy, extending, conventions). Name files with a
+  shared prefix (`dev_guide_<topic>.rst`).
+- The landing page is reachable from the documentation root `toctree`.
+
+## 2. Required Chapters
+
+- **Introduction** — who the guide is for, how it differs from the user guide,
+  and a package overview (what it does, the runtime and key dependencies).
+- **Repository layout** — an annotated directory tree (a `::` literal block)
+  with a one-line comment on each significant directory and top-level file,
+  and a statement of which part is the importable public package versus
+  supporting code.
+- **Environment setup** — how to get a working development checkout:
+    - Clone, virtual-environment creation, and an editable install with the dev
+      extras (`pip install -e ".[dev]"`).
+    - Every environment variable needed to run, test, or build, with defaults.
+    - How to run the package's entry points locally, including a smoke test.
+    - How to run the test suite: the default invocation, how to include slower
+      or integration tiers, parallel/CI-matching flags, running a single
+      file/test, and coverage. Note the test layout and any required markers.
+    - How to run linters, type checks, formatters, and the docs build, plus any
+      one-command wrapper that runs them all.
+    - The CI/CD pipeline (what runs on which trigger) and the release process.
+    - The contribution workflow, or a pointer to the contribution guide.
+- **Architecture / class hierarchy** — see Section 3.
+- **Per-subsystem chapters** — see Section 4.
+- **Extending the system** — see Section 5.
+- **Coding conventions** — the project's style and quality rules, or a pointer
+  to where they live.
+- **API reference** — see Section 6.
+
+## 3. Architecture and Class Diagrams
+
+- Include at least one **class diagram** (a Mermaid `classDiagram` or
+  equivalent) showing the principal classes, their key public members, and the
+  relationships between them (inheritance, composition, "produces"/"consumes").
+- Mark abstract classes and dataclasses; show the methods that define each
+  abstract contract.
+- Follow every diagram with narrative prose that walks each group of classes in
+  turn — a diagram alone is not documentation.
+- Cross-reference every class named in the narrative per `doc_python` Section 5.
+  Do NOT cross-reference inside the diagram block itself.
+- Keep the diagram in sync with the code: a renamed or removed class invalidates
+  the diagram and must be fixed in the same change.
+
+## 4. Per-Subsystem / Per-Module Prose
+
+Each subsystem chapter MUST give a reader enough to navigate and modify that
+code without reverse-engineering it. Include:
+
+- **Overview** — the subsystem's responsibility and how it fits the overall
+  flow, with a cross-reference to the module(s) it documents.
+- **Per-class / per-file description** — prose for each significant class or
+  module: its role, the abstract contract it defines or implements (list the
+  methods subclasses must provide and what each returns), notable attributes,
+  and how instances are created and used. Describe behavior and contracts, not a
+  line-by-line restatement of the source.
+- **Concrete subclasses / implementations** — enumerate the shipping
+  implementations of each abstract base and what distinguishes each.
+- **Important invariants** — thread-safety and concurrency constraints, caching
+  and shared mutable state, ordering requirements, and units/conventions for
+  any quantity that is easy to get wrong. State these explicitly where they
+  apply.
+- **API-reference pointer** — end the chapter with a link to the autodoc page(s)
+  for the subsystem.
+
+## 5. Extending the System
+
+- Provide a step-by-step recipe for each documented extension point (adding a
+  plugin, backend, subclass, data source, etc.): which base class to inherit,
+  which methods to implement and their contracts, where to put the file, and how
+  to register it so the package discovers it.
+- Include a minimal, correct code skeleton for each recipe in a
+  `.. code-block:: python` directive.
+- Cross-reference the relevant subsystem chapter and the base classes involved
+  rather than duplicating their contracts.
+
+## 6. API Reference
+
+- Generate the API reference from docstrings with `autodoc`; do not hand-write
+  API descriptions that will drift from the code.
+- Provide an API-reference landing page with a `toctree`, plus one page per
+  top-level package/subpackage. On each page use `automodule` directives with
+  `:members:`, `:undoc-members:`, and `:show-inheritance:` so the full public
+  surface (including as-yet-undocumented members) is visible.
+- Cover the entire importable public API: when a new public module is added,
+  add a corresponding API-reference entry in the same change, or it will be
+  silently absent from the rendered surface.
+- The quality of these pages is bounded by docstring quality (`doc_python`
+  Section 4); thin docstrings produce a thin API reference.
+
+## 7. Build Discipline
+
+The developer guide is the heaviest user of cross-references, autodoc, and
+diagrams, so it is the most prone to silent breakage. It MUST build clean under
+both `sphinx-build -W` (warnings as errors) and `sphinx-build -n` (nitpicky)
+per `doc_python` Section 6 before delivering — every cross-reference resolving,
+every `automodule` importing (mock heavy optional imports in `conf.py` rather
+than dropping modules from the reference), and every diagram rendering.

.claude/rules/doc_how_to.md

@@ -0,0 +1,95 @@
+---
+description: Format and completeness rules for task-focused how-to articles that walk a user through a single workflow with prerequisites, steps, and troubleshooting.
+paths:
+  - "docs/**/*.rst"
+  - "docs/**/*.md"
+---
+
+# How-To Articles
+
+A how-to article walks a reader through ONE concrete task from start to finish.
+It complements the reference material in `doc_user_guide`: the user guide
+documents every option exhaustively, while a how-to picks one goal and shows the
+shortest correct path to it. Build on `doc_python` (prose conventions, build
+discipline). Where a how-to and the user guide describe the same workflow, keep
+them consistent and link between them rather than duplicating detail.
+
+## 1. Audience and Tone
+
+- Write for someone fluent in `pip` and the command line but unfamiliar with the
+  package internals.
+- Use clear, direct, action-oriented language; define domain-specific terms on
+  first use.
+- Focus on what the reader must do and what they should observe.
+
+## 2. Required Elements
+
+1. **Action-oriented title** — name the task as an action (e.g. "How To Export a
+   Report", not "Report Export Overview").
+2. **Brief introduction** — 1-3 sentences on the purpose and value of the task.
+3. **Prerequisites** — supported Python version, install command, and any
+   required data, environment variables, or prior configuration.
+4. **Numbered steps** — one action per step in logical order, each with the
+   exact API snippet or command-line invocation and a note of what the reader
+   should see after it.
+5. **Expected results** — a summary of the successful end state (output, files
+   created, side effects). Keep this consistent with the per-step observations.
+6. **Troubleshooting** — the common failure modes (import errors, missing data,
+   version or environment mismatches) and their fixes.
+7. **Related material** — next steps and links to the relevant user-guide
+   chapters or other how-to articles.
+
+## 3. Structure
+
+```markdown
+# How To [Action]
+
+[1-3 sentence introduction explaining purpose and value.]
+
+## Prerequisites
+
+- Python >= <version>
+- `pip install <dist-name>`
+- [Any required data, environment variables, or configuration]
+
+## Steps
+
+1. Import the module:
+   ```python
+   from package import SomeClass
+   ```
+2. [Action]. You should see [result].
+3. [Action].
+
+## Expected Results
+
+[Summary of the successful end state — output, files created, etc.]
+
+## Troubleshooting
+
+- **[Problem]**: [Solution].
+
+## Additional Information
+
+[Tips, performance notes, or links to related guides.]
+```
+
+## 4. Converting Technical Content
+
+When turning docstrings, test scripts, or internal notes into a how-to:
+
+1. Identify the user-facing feature or workflow.
+2. Determine the target audience (API user, command-line user, contributor).
+3. Extract the user actions from the technical steps.
+4. Translate internal terminology into user-facing language.
+5. Add runnable examples, expected output, and troubleshooting.
+
+## 5. Diagrams and Figures
+
+- **When to use**: multi-step workflows, data pipelines, or architecture that is
+  clearer as a visual.
+- **Placement**: inline, immediately after the relevant step or section.
+- **Format**: prefer text-based diagrams (e.g. Mermaid, rendered by Sphinx) for
+  process flows; use PNG/SVG for screenshots or data visualizations.
+- **Naming**: descriptive filenames (e.g. `export-pipeline.svg`), with alt text
+  for accessibility.