cwms-tools 0.1.0__tar.gz

cwms_tools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian Connelly
+
+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.

cwms_tools-0.1.0/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: cwms-tools
+Version: 0.1.0
+Summary: Agent-friendly tools (MCP server and CLI) for the USACE Corps Water Management System (CWMS) Data API.
+Keywords: cwms,usace,mcp,cli,water,hydrology,agent
+Author: Brian Connelly
+Author-email: Brian Connelly <bdc@bconnelly.net>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Hydrology
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: cwms-python>=1.0.7
+Requires-Dist: fastmcp>=3
+Requires-Dist: typer>=0.15
+Requires-Dist: pydantic>=2
+Requires-Dist: platformdirs>=4
+Requires-Dist: diskcache>=5
+Requires-Dist: anyio>=4
+Requires-Dist: python-dateutil>=2.9
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/briandconnelly/cwms-tools
+Project-URL: Repository, https://github.com/briandconnelly/cwms-tools
+Project-URL: Issues, https://github.com/briandconnelly/cwms-tools/issues
+Project-URL: Changelog, https://github.com/briandconnelly/cwms-tools/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# cwms-tools
+
+[![CI](https://github.com/briandconnelly/cwms-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/briandconnelly/cwms-tools/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/cwms-tools.svg)](https://pypi.org/project/cwms-tools/)
+[![Python](https://img.shields.io/pypi/pyversions/cwms-tools.svg)](https://pypi.org/project/cwms-tools/)
+
+Read-only, agent-friendly tools for the U.S. Army Corps of Engineers'
+[CWMS Data API](https://cwms-data.usace.army.mil/cwms-data/). `cwms-tools` wraps the official
+[`cwms-python`](https://github.com/HydrologicEngineeringCenter/cwms-python) client with two surfaces that share one behavioral
+core:
+
+- an [MCP](https://modelcontextprotocol.io/) server for agent runtimes such as Claude Code, Codex, and custom
+  MCP clients
+- a non-interactive CLI with compact JSON output, stable exit codes, and a
+  machine-readable schema
+
+The goal is simple: let agents answer common hydrologic questions with one task
+call instead of a brittle chain of raw API lookups.
+
+## What It Does
+
+- Resolves natural place names to canonical CWMS locations, with ghost-location
+  filtering and co-located sensor hints.
+- Describes a place in one call: location record, project metadata when
+  available, published parameters, publishers, and latest data timestamp.
+- Reads the latest value or bounded history for CWMS time series parameters.
+- Optionally classifies the latest value against CWMS Location Levels when
+  callers opt in with `--with-status` or `with_status=true`.
+- Browses one office's catalog by state or bounding box.
+- Finds publishers for a parameter across cached or explicitly requested
+  offices.
+- Serves a bundled CWMS orientation document as MCP resources so agents can load
+  background material selectively.
+
+## Install
+
+```bash
+uv add cwms-tools
+# or:  pipx install cwms-tools
+```
+
+To run from a checkout instead:
+
+```bash
+git clone https://github.com/briandconnelly/cwms-tools.git
+cd cwms-tools
+uv sync
+uv run cwms-tools --help
+```
+
+## CLI Quick Start
+
+The CLI is designed for non-interactive callers. When stdout is not a TTY,
+machine mode is enabled automatically: compact JSON on stdout, diagnostics on
+stderr, no color, no prompts, and no progress UI. You can force that profile
+with `--machine` or `--json`.
+
+```bash
+# Inspect the resolved session and upstream API root.
+uv run cwms-tools whoami
+
+# Print the command tree, output classes, exit codes, environment inputs,
+# MCP tools, and MCP resources as a stable machine-readable contract.
+uv run cwms-tools schema
+
+# Print a SHA-256 fingerprint over the agent-visible capability surface.
+uv run cwms-tools fingerprint
+
+# Resolve a place name to ranked CWMS locations.
+uv run cwms-tools place search "Fort Peck" --office NWDM
+
+# Describe one place: location, project metadata, parameters, publishers,
+# freshness, and partial-result flags.
+uv run cwms-tools place describe NWDM/FTPK
+
+# List parameters published at a place.
+uv run cwms-tools place parameters NWDM/FTPK
+
+# Read the latest elevation value. Status lookup is skipped by default because
+# CWMS Location Levels calls can be slow.
+uv run cwms-tools value get NWDM/FTPK/Elev
+
+# Opt in to threshold classification when status context matters.
+uv run cwms-tools value get NWDM/FTPK/Elev --with-status
+
+# Read a bounded history window.
+uv run cwms-tools value history NWDM/FTPK/Elev \
+  --begin 2026-05-16T00:00:00Z \
+  --end 2026-05-17T00:00:00Z
+
+# Browse an office catalog by state.
+uv run cwms-tools region browse --office SWT --state OK
+
+# Find publishers reporting a parameter in selected offices.
+uv run cwms-tools publisher for-parameter Elev --office NWDM --office SWT
+```
+
+Useful global flags:
+
+- `--machine` / `--json`: compact structured output for agents and scripts.
+- `--no-cache`: bypass the on-disk catalog cache for one invocation.
+- `--isolated`: bypass cache and ignore `CWMS_TOOLS_*` environment variables.
+- `--version`: print the installed `cwms-tools` version.
+
+Exit codes are part of the CLI contract:
+
+| Exit | Meaning |
+| ---: | --- |
+| `0` | success |
+| `2` | usage or invalid field |
+| `3` | not found or publisher unavailable |
+| `4` | session unconfigured |
+| `6` | rate limited |
+| `7` | timeout |
+| `9` | upstream error or catalog cursor invalidation |
+| `11` | wrapper bug |
+| `12` | ghost location or ghost office |
+
+## MCP Quick Start
+
+Use stdio for local agent runtimes:
+
+```bash
+uv run cwms-tools mcp serve --transport stdio
+```
+
+Use streamable HTTP for shared or remote deployment:
+
+```bash
+uv run cwms-tools mcp serve --transport streamable-http --host 127.0.0.1 --port 8765
+```
+
+Claude Code config example:
+
+```jsonc
+{
+  "mcpServers": {
+    "cwms-tools": {
+      "command": "uv",
+      "args": ["run", "cwms-tools", "mcp", "serve", "--transport", "stdio"]
+    }
+  }
+}
+```
+
+The MCP server exposes task-level tools rather than raw endpoint mirrors:
+
+| Tool | Purpose |
+| --- | --- |
+| `cwms_search_places` | Resolve an ambiguous place name to ranked locations. |
+| `cwms_describe_place` | Read location, project, parameter, publisher, and freshness data in one call. |
+| `cwms_list_parameters` | List parameters published at a location, grouped by publisher. |
+| `cwms_get_value` | Read the latest observation, optionally with threshold status. |
+| `cwms_get_history` | Read raw observations across a bounded time window. |
+| `cwms_browse_region` | Browse one office's locations, optionally by state or bounding box. |
+| `cwms_publishers_for_parameter` | List publishers reporting a parameter across selected offices. |
+| `cwms_get_overview_section` | Read bundled CWMS orientation content. |
+
+Resources:
+
+- `cwms://capabilities`: server version, fingerprint, tools, and resources.
+- `cwms://overview`: index of bundled CWMS overview sections.
+- `cwms://overview/{section_id}{?detail}`: summary or full section body.
+- `cwms://overview/{section_id}/chunk/{chunk_id}`: one large-section chunk.
+
+## Configuration
+
+`cwms-tools` works anonymously by default. Environment variables are optional:
+
+| Variable | Purpose |
+| --- | --- |
+| `CWMS_TOOLS_API_ROOT` | Override the CWMS Data API root. |
+| `CWMS_TOOLS_CACHE_DIR` | Override the disk cache location. |
+| `CWMS_TOOLS_WORKERS` | Set bounded worker concurrency. |
+| `CWMS_TOOLS_REPO_URL` | Override the repository URL advertised in the user agent. |
+| `CWMS_TOOLS_USER_AGENT_EXTRA` | Append extra text to the user agent. |
+| `CWMS_TOOLS_OPERATOR_EMAIL` | Send a contact email via the `From` header. |
+| `CWMS_TOOLS_MAX_RPS` | Declared for rate-limit policy; not enforced in v0.1.0. |
+| `CWMS_API_KEY` | Reserved secret input for authenticated CDA deployments. |
+| `CWMS_TOKEN` | Reserved secret input for authenticated CDA deployments. |
+
+Inspect the resolved configuration without making a data call:
+
+```bash
+uv run cwms-tools env
+uv run cwms-tools config show --resolved
+```
+
+## CWMS Notes
+
+CWMS is USACE's Corps Water Management System: the operational data platform for
+federal reservoirs, flood-control dams, navigation locks, hydropower projects,
+and environmental monitoring stations.
+
+Two upstream data-shape issues come up often:
+
+- **Ghost records.** Some catalog locations do not publish time-series data.
+  Search and browse responses expose `parameter_count`, `parameters`, and
+  `data_at` repair hints so agents can move to the data-bearing sibling.
+- **Northwestern Division stubs.** `NWO`, `NWK`, `NWS`, `NWP`, and `NWW` are
+  near-empty CDA stubs. Use `NWDM` for Missouri River data and `NWDP` for
+  Pacific Northwest data. Error envelopes include repair hints when a stub is
+  targeted.
+
+## Upstream Etiquette
+
+The CWMS Data API is a shared public service. `cwms-tools` identifies itself
+with a descriptive `User-Agent`, caps concurrent requests, honors
+`Retry-After`, avoids background scans, and does not cache live time-series
+values. If you operate CDA and see problematic traffic from this client, please
+open an issue at <https://github.com/briandconnelly/cwms-tools/issues>.
+
+## Development
+
+```bash
+uv sync
+uv run prek run --all-files
+uv run pytest --cov=cwms_tools
+uv run ty check
+```
+
+The test suite uses unit tests and mocked CDA responses. Live CDA integration
+tests are marked `integration` and are skipped unless explicitly selected.
+
+Before opening a substantial PR, please open an issue to discuss the intended
+change. The package is still pre-release, and the CLI/MCP schema contract is
+the main compatibility surface.
+
+## License
+
+[MIT](LICENSE)

cwms_tools-0.1.0/README.md

@@ -0,0 +1,231 @@
+# cwms-tools
+
+[![CI](https://github.com/briandconnelly/cwms-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/briandconnelly/cwms-tools/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/cwms-tools.svg)](https://pypi.org/project/cwms-tools/)
+[![Python](https://img.shields.io/pypi/pyversions/cwms-tools.svg)](https://pypi.org/project/cwms-tools/)
+
+Read-only, agent-friendly tools for the U.S. Army Corps of Engineers'
+[CWMS Data API](https://cwms-data.usace.army.mil/cwms-data/). `cwms-tools` wraps the official
+[`cwms-python`](https://github.com/HydrologicEngineeringCenter/cwms-python) client with two surfaces that share one behavioral
+core:
+
+- an [MCP](https://modelcontextprotocol.io/) server for agent runtimes such as Claude Code, Codex, and custom
+  MCP clients
+- a non-interactive CLI with compact JSON output, stable exit codes, and a
+  machine-readable schema
+
+The goal is simple: let agents answer common hydrologic questions with one task
+call instead of a brittle chain of raw API lookups.
+
+## What It Does
+
+- Resolves natural place names to canonical CWMS locations, with ghost-location
+  filtering and co-located sensor hints.
+- Describes a place in one call: location record, project metadata when
+  available, published parameters, publishers, and latest data timestamp.
+- Reads the latest value or bounded history for CWMS time series parameters.
+- Optionally classifies the latest value against CWMS Location Levels when
+  callers opt in with `--with-status` or `with_status=true`.
+- Browses one office's catalog by state or bounding box.
+- Finds publishers for a parameter across cached or explicitly requested
+  offices.
+- Serves a bundled CWMS orientation document as MCP resources so agents can load
+  background material selectively.
+
+## Install
+
+```bash
+uv add cwms-tools
+# or:  pipx install cwms-tools
+```
+
+To run from a checkout instead:
+
+```bash
+git clone https://github.com/briandconnelly/cwms-tools.git
+cd cwms-tools
+uv sync
+uv run cwms-tools --help
+```
+
+## CLI Quick Start
+
+The CLI is designed for non-interactive callers. When stdout is not a TTY,
+machine mode is enabled automatically: compact JSON on stdout, diagnostics on
+stderr, no color, no prompts, and no progress UI. You can force that profile
+with `--machine` or `--json`.
+
+```bash
+# Inspect the resolved session and upstream API root.
+uv run cwms-tools whoami
+
+# Print the command tree, output classes, exit codes, environment inputs,
+# MCP tools, and MCP resources as a stable machine-readable contract.
+uv run cwms-tools schema
+
+# Print a SHA-256 fingerprint over the agent-visible capability surface.
+uv run cwms-tools fingerprint
+
+# Resolve a place name to ranked CWMS locations.
+uv run cwms-tools place search "Fort Peck" --office NWDM
+
+# Describe one place: location, project metadata, parameters, publishers,
+# freshness, and partial-result flags.
+uv run cwms-tools place describe NWDM/FTPK
+
+# List parameters published at a place.
+uv run cwms-tools place parameters NWDM/FTPK
+
+# Read the latest elevation value. Status lookup is skipped by default because
+# CWMS Location Levels calls can be slow.
+uv run cwms-tools value get NWDM/FTPK/Elev
+
+# Opt in to threshold classification when status context matters.
+uv run cwms-tools value get NWDM/FTPK/Elev --with-status
+
+# Read a bounded history window.
+uv run cwms-tools value history NWDM/FTPK/Elev \
+  --begin 2026-05-16T00:00:00Z \
+  --end 2026-05-17T00:00:00Z
+
+# Browse an office catalog by state.
+uv run cwms-tools region browse --office SWT --state OK
+
+# Find publishers reporting a parameter in selected offices.
+uv run cwms-tools publisher for-parameter Elev --office NWDM --office SWT
+```
+
+Useful global flags:
+
+- `--machine` / `--json`: compact structured output for agents and scripts.
+- `--no-cache`: bypass the on-disk catalog cache for one invocation.
+- `--isolated`: bypass cache and ignore `CWMS_TOOLS_*` environment variables.
+- `--version`: print the installed `cwms-tools` version.
+
+Exit codes are part of the CLI contract:
+
+| Exit | Meaning |
+| ---: | --- |
+| `0` | success |
+| `2` | usage or invalid field |
+| `3` | not found or publisher unavailable |
+| `4` | session unconfigured |
+| `6` | rate limited |
+| `7` | timeout |
+| `9` | upstream error or catalog cursor invalidation |
+| `11` | wrapper bug |
+| `12` | ghost location or ghost office |
+
+## MCP Quick Start
+
+Use stdio for local agent runtimes:
+
+```bash
+uv run cwms-tools mcp serve --transport stdio
+```
+
+Use streamable HTTP for shared or remote deployment:
+
+```bash
+uv run cwms-tools mcp serve --transport streamable-http --host 127.0.0.1 --port 8765
+```
+
+Claude Code config example:
+
+```jsonc
+{
+  "mcpServers": {
+    "cwms-tools": {
+      "command": "uv",
+      "args": ["run", "cwms-tools", "mcp", "serve", "--transport", "stdio"]
+    }
+  }
+}
+```
+
+The MCP server exposes task-level tools rather than raw endpoint mirrors:
+
+| Tool | Purpose |
+| --- | --- |
+| `cwms_search_places` | Resolve an ambiguous place name to ranked locations. |
+| `cwms_describe_place` | Read location, project, parameter, publisher, and freshness data in one call. |
+| `cwms_list_parameters` | List parameters published at a location, grouped by publisher. |
+| `cwms_get_value` | Read the latest observation, optionally with threshold status. |
+| `cwms_get_history` | Read raw observations across a bounded time window. |
+| `cwms_browse_region` | Browse one office's locations, optionally by state or bounding box. |
+| `cwms_publishers_for_parameter` | List publishers reporting a parameter across selected offices. |
+| `cwms_get_overview_section` | Read bundled CWMS orientation content. |
+
+Resources:
+
+- `cwms://capabilities`: server version, fingerprint, tools, and resources.
+- `cwms://overview`: index of bundled CWMS overview sections.
+- `cwms://overview/{section_id}{?detail}`: summary or full section body.
+- `cwms://overview/{section_id}/chunk/{chunk_id}`: one large-section chunk.
+
+## Configuration
+
+`cwms-tools` works anonymously by default. Environment variables are optional:
+
+| Variable | Purpose |
+| --- | --- |
+| `CWMS_TOOLS_API_ROOT` | Override the CWMS Data API root. |
+| `CWMS_TOOLS_CACHE_DIR` | Override the disk cache location. |
+| `CWMS_TOOLS_WORKERS` | Set bounded worker concurrency. |
+| `CWMS_TOOLS_REPO_URL` | Override the repository URL advertised in the user agent. |
+| `CWMS_TOOLS_USER_AGENT_EXTRA` | Append extra text to the user agent. |
+| `CWMS_TOOLS_OPERATOR_EMAIL` | Send a contact email via the `From` header. |
+| `CWMS_TOOLS_MAX_RPS` | Declared for rate-limit policy; not enforced in v0.1.0. |
+| `CWMS_API_KEY` | Reserved secret input for authenticated CDA deployments. |
+| `CWMS_TOKEN` | Reserved secret input for authenticated CDA deployments. |
+
+Inspect the resolved configuration without making a data call:
+
+```bash
+uv run cwms-tools env
+uv run cwms-tools config show --resolved
+```
+
+## CWMS Notes
+
+CWMS is USACE's Corps Water Management System: the operational data platform for
+federal reservoirs, flood-control dams, navigation locks, hydropower projects,
+and environmental monitoring stations.
+
+Two upstream data-shape issues come up often:
+
+- **Ghost records.** Some catalog locations do not publish time-series data.
+  Search and browse responses expose `parameter_count`, `parameters`, and
+  `data_at` repair hints so agents can move to the data-bearing sibling.
+- **Northwestern Division stubs.** `NWO`, `NWK`, `NWS`, `NWP`, and `NWW` are
+  near-empty CDA stubs. Use `NWDM` for Missouri River data and `NWDP` for
+  Pacific Northwest data. Error envelopes include repair hints when a stub is
+  targeted.
+
+## Upstream Etiquette
+
+The CWMS Data API is a shared public service. `cwms-tools` identifies itself
+with a descriptive `User-Agent`, caps concurrent requests, honors
+`Retry-After`, avoids background scans, and does not cache live time-series
+values. If you operate CDA and see problematic traffic from this client, please
+open an issue at <https://github.com/briandconnelly/cwms-tools/issues>.
+
+## Development
+
+```bash
+uv sync
+uv run prek run --all-files
+uv run pytest --cov=cwms_tools
+uv run ty check
+```
+
+The test suite uses unit tests and mocked CDA responses. Live CDA integration
+tests are marked `integration` and are skipped unless explicitly selected.
+
+Before opening a substantial PR, please open an issue to discuss the intended
+change. The package is still pre-release, and the CLI/MCP schema contract is
+the main compatibility surface.
+
+## License
+
+[MIT](LICENSE)

cwms_tools-0.1.0/pyproject.toml

@@ -0,0 +1,146 @@
+[project]
+name = "cwms-tools"
+version = "0.1.0"
+description = "Agent-friendly tools (MCP server and CLI) for the USACE Corps Water Management System (CWMS) Data API."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Brian Connelly", email = "bdc@bconnelly.net" },
+]
+keywords = ["cwms", "usace", "mcp", "cli", "water", "hydrology", "agent"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Hydrology",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "cwms-python>=1.0.7",
+    "fastmcp>=3",
+    "typer>=0.15",
+    "pydantic>=2",
+    "platformdirs>=4",
+    "diskcache>=5",
+    "anyio>=4",
+    "python-dateutil>=2.9",
+]
+
+[project.urls]
+Homepage = "https://github.com/briandconnelly/cwms-tools"
+Repository = "https://github.com/briandconnelly/cwms-tools"
+Issues = "https://github.com/briandconnelly/cwms-tools/issues"
+Changelog = "https://github.com/briandconnelly/cwms-tools/blob/main/CHANGELOG.md"
+
+[project.scripts]
+cwms-tools = "cwms_tools.cli.app:app"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "pytest-asyncio>=0.24",
+    "responses>=0.25",
+    "vcrpy>=6",
+    "ruff>=0.15",
+    "ty>=0.0.1a1",
+    "prek>=0.2",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.14,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv]
+package = true
+
+# --------------------------------------------------------------------------
+# Ruff (lint + format)
+# --------------------------------------------------------------------------
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E", "F", "W",      # pycodestyle + pyflakes
+    "I",                # isort
+    "B",                # bugbear
+    "UP",               # pyupgrade
+    "SIM",              # simplify
+    "PIE",              # misc
+    "RUF",              # ruff-specific
+    "PL",               # pylint subset
+    "PT",               # pytest style
+    "TID",              # tidy imports
+    "TCH",              # type-checking imports
+    "ARG",              # unused arguments
+    "PTH",              # use pathlib
+]
+ignore = [
+    "PLR0913",  # too many arguments — common in API wrappers
+    "PLR2004",  # magic value used in comparison — noisy in tests
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Tests get a permissive lint policy: pytest idioms regularly trip checks meant
+# for production code (TID -> inline imports for monkeypatching, PT018 -> compound
+# asserts, PLC0415 -> per-test imports), and ruff's en-dash heuristic fires on
+# normal English in docstrings.
+"tests/**" = ["ARG", "PLR2004", "S101", "TC002", "TC003", "PT018", "PLC0415", "RUF002", "RUF003"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+# --------------------------------------------------------------------------
+# ty (type checker)
+# --------------------------------------------------------------------------
+[tool.ty.src]
+include = ["src", "tests"]
+
+[tool.ty.rules]
+# Strict on our own code; permissive on third-party shapes
+unresolved-import = "warn"
+
+# --------------------------------------------------------------------------
+# pytest
+# --------------------------------------------------------------------------
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--strict-config",
+]
+asyncio_mode = "auto"
+markers = [
+    "integration: live-CDA tests (skipped by default)",
+    "slow: slow tests",
+]
+
+# --------------------------------------------------------------------------
+# coverage
+# --------------------------------------------------------------------------
+[tool.coverage.run]
+source = ["src/cwms_tools"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+]
+fail_under = 80  # v0.1.0 floor; raise toward 95 as wrapper-error paths get hit
+show_missing = true

cwms_tools-0.1.0/src/cwms_tools/__init__.py

@@ -0,0 +1,12 @@
+"""cwms-tools — agent-friendly tools for the USACE CWMS Data API."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("cwms-tools")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

cwms_tools-0.1.0/src/cwms_tools/cli/__init__.py

@@ -0,0 +1 @@
+"""Typer CLI adapter over the core."""