Cloud Quota Manager

Cloud Quota Manager (cqmgr) is being designed to turn live cloud-provider quota evidence into exact, reviewable operator actions without confusing quota with physical capacity.

Its first complete workflows cover Google Cloud accelerator quota for NVIDIA GPUs and TPUs. The CLI, TUI, and structured automation surfaces share the same domain operations, evidence, warnings, and outcomes.

Planned capabilities

• inspect exact effective quota slices and their related constraint sets;
• compare current Spot obtainability advice, historical preemption, and price across exact candidates while preserving candidate identity and evidence;
• preview one exact quota target with its identity, consequences, and fresh provider evidence;
• apply a time-bounded quota request plan deliberately;
• follow reconciliation through explicit granted and fulfilled outcomes;
• preserve honest unknown, incomplete, partial, and unsupported states.

Project status

This repository contains the installable V1 CLI and TUI, shared domain operations, provider adapters, durable local evidence, release qualification, product contracts, and provider research. Live provider reads require an explicit Google Cloud identity and project. Quota-request mutation remains separately guarded by Preview, Review, acknowledgement, and Apply; repository work never authorizes a live mutation by itself.

The implementation baseline is CPython 3.12–3.14, pyproject.toml, uv, Ruff, Pyrefly, Click, and Textual. Once a package is published, the primary installation path is uv tool install cqmgr. The runtime and provider boundaries are defined in the runtime and integration architecture. The supported platform, test, installation, and release gates are defined in the verification and distribution contract.

Start with:

• the V1 product requirements for the complete implementation handoff, safety invariants, acceptance gates, and execution sequence;
• the product context for users, purpose, and design principles;
• the domain glossary for canonical language;
• operator workflows for the shared interaction contract;
• CLI and TUI information architecture for command, navigation, query, and plan-handoff behavior;
• runtime and integration architecture for the Python stack, dependency direction, configuration, authentication, provider adapters, and local plan trust boundary;
• verification and distribution contract for supported platforms, test layers, live-read-only canaries, package installation, and release gates;
• provider research for source-backed constraints;
• GitHub Issues for the live Wayfinder frontier.

The preserved interactive prototype lives on the prototype/operator-workflows branch.

Install and develop

Until cqmgr is published on PyPI, install the local checkout with uv:

uv tool install .
cqmgr --help

After publication, install the isolated command directly from PyPI:

uv tool install cqmgr

Contributors use the committed lock and run the complete local baseline with:

uv sync --locked
uv run ruff format --check .
uv run ruff check .
uv run pyrefly check
uv run lint-imports --no-cache
uv run --locked --no-sync pip-licenses \
  --from mixed \
  --allow-only \
  "3-Clause BSD License;Apache-2.0;Apache-2.0 OR BSD-2-Clause;Apache-2.0 OR BSD-3-Clause;Apache Software License;BSD-2-Clause;BSD-3-Clause;BSD License;MIT;MIT-0;MIT License;MPL-2.0;Mozilla Public License 2.0 (MPL 2.0);PSF-2.0;Python Software Foundation License"
uv export --locked --no-dev --no-emit-project --format requirements-txt --output-file release-requirements.txt
uv run pip-audit --requirement release-requirements.txt --disable-pip
uv run pytest
uv build --clear --no-sources
uv run python scripts/verify_distribution.py dist
uv run python scripts/smoke_tool_install.py dist --python 3.14