qauvern 0.2.0__tar.gz

qauvern-0.2.0/.github/workflows/ci.yaml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: install
+        run: |
+          uv tool install rust-just
+          uv sync
+      - run: just lint
+      - run: just test

qauvern-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,154 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'pyproject.toml'
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.get-version.outputs.version }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Get version from pyproject.toml
+        id: get-version
+        run: |
+          VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Version to release: $VERSION"
+
+      - name: Validate version format
+        run: |
+          VERSION="${{ steps.get-version.outputs.version }}"
+          if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "Error: Invalid version format: $VERSION"
+            exit 1
+          fi
+
+      - name: Check if tag exists
+        run: |
+          VERSION="${{ steps.get-version.outputs.version }}"
+          if git ls-remote --tags origin "v$VERSION" | grep -q .; then
+            echo "Error: Tag v$VERSION already exists"
+            exit 1
+          fi
+
+  test:
+    needs: validate
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          uv tool install rust-just
+          uv sync
+
+      - name: Run tests
+        run: just test
+
+  build:
+    needs: [validate, test]
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build distribution
+        run: uv build
+
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/qauvern/
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  create-release:
+    needs: [validate, publish-to-pypi]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Create and push tag
+        run: |
+          VERSION="${{ needs.validate.outputs.version }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "v$VERSION" -m "Release version $VERSION"
+          git push origin "v$VERSION"
+
+      - name: Extract changelog for this version
+        id: changelog
+        run: |
+          VERSION="${{ needs.validate.outputs.version }}"
+          python3 << 'EOF' > release-notes.md
+          import re
+          import os
+          VERSION = os.environ.get('VERSION', '')
+          with open('CHANGELOG.md', 'r') as f:
+              content = f.read()
+              pattern = rf'## \[{re.escape(VERSION)}\].*?\n(.*?)(?=\n## \[|$)'
+              match = re.search(pattern, content, re.DOTALL)
+              if match:
+                  notes = match.group(1).strip()
+                  print(notes)
+              else:
+                  print(f'Release version {VERSION}')
+          EOF
+          cat release-notes.md
+        env:
+          VERSION: ${{ needs.validate.outputs.version }}
+
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ needs.validate.outputs.version }}
+        run: |
+          gh release create "v$VERSION" \
+            --title "Release v$VERSION" \
+            --notes-file release-notes.md \
+            dist/*

qauvern-0.2.0/.gitignore

@@ -0,0 +1,80 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+env.sh
+env.staging.sh
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+/.claude
+!/.claude/commands
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+config.yaml
+*.log
+openapi.json
+/test_*.py
+/test_*.sh
+env.sh
+env.staging.sh
+/config/

qauvern-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,8 @@
+repos:
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.5.0
+    hooks:
+      - id: detect-secrets
+        args: ['--baseline', '.secrets.baseline']
+        exclude: package.lock.json
+

qauvern-0.2.0/.secrets.baseline

@@ -0,0 +1,141 @@
+{
+  "version": "1.5.0",
+  "plugins_used": [
+    {
+      "name": "ArtifactoryDetector"
+    },
+    {
+      "name": "AWSKeyDetector"
+    },
+    {
+      "name": "AzureStorageKeyDetector"
+    },
+    {
+      "name": "Base64HighEntropyString",
+      "limit": 4.5
+    },
+    {
+      "name": "BasicAuthDetector"
+    },
+    {
+      "name": "CloudantDetector"
+    },
+    {
+      "name": "DiscordBotTokenDetector"
+    },
+    {
+      "name": "GitHubTokenDetector"
+    },
+    {
+      "name": "GitLabTokenDetector"
+    },
+    {
+      "name": "HexHighEntropyString",
+      "limit": 3.0
+    },
+    {
+      "name": "IbmCloudIamDetector"
+    },
+    {
+      "name": "IbmCosHmacDetector"
+    },
+    {
+      "name": "IPPublicDetector"
+    },
+    {
+      "name": "JwtTokenDetector"
+    },
+    {
+      "name": "KeywordDetector",
+      "keyword_exclude": ""
+    },
+    {
+      "name": "MailchimpDetector"
+    },
+    {
+      "name": "NpmDetector"
+    },
+    {
+      "name": "OpenAIDetector"
+    },
+    {
+      "name": "PrivateKeyDetector"
+    },
+    {
+      "name": "PypiTokenDetector"
+    },
+    {
+      "name": "SendGridDetector"
+    },
+    {
+      "name": "SlackDetector"
+    },
+    {
+      "name": "SoftlayerDetector"
+    },
+    {
+      "name": "SquareOAuthDetector"
+    },
+    {
+      "name": "StripeDetector"
+    },
+    {
+      "name": "TelegramBotTokenDetector"
+    },
+    {
+      "name": "TwilioKeyDetector"
+    }
+  ],
+  "filters_used": [
+    {
+      "path": "detect_secrets.filters.allowlist.is_line_allowlisted"
+    },
+    {
+      "path": "detect_secrets.filters.common.is_baseline_file",
+      "filename": ".secrets.baseline"
+    },
+    {
+      "path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies",
+      "min_level": 2
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_indirect_reference"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_likely_id_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_lock_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_not_alphanumeric_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_potential_uuid"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_sequential_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_swagger_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_templated_secret"
+    }
+  ],
+  "results": {
+    "README.md": [
+      {
+        "type": "Secret Keyword",
+        "filename": "README.md",
+        "hashed_secret": "1042188d51afe0c0b267d5c98e5ac2f2c741b28f",
+        "is_verified": false,
+        "line_number": 113
+      }
+    ]
+  },
+  "generated_at": "2026-05-08T20:48:11Z"
+}

qauvern-0.2.0/AGENTS.md

@@ -0,0 +1,65 @@
+# AGENTS.md
+
+This is a Python CLI tool for optimizing IBM Quantum resource allocations across cloud accounts,
+using fairness-based scheduling to rebalance QAU allocations among service instances. See
+`Design.md` for full architecture, algorithm details, and API endpoint documentation.
+
+## Development Setup
+
+Requires [Just](https://just.systems/man/en/) and [uv](https://docs.astral.sh/uv/).
+
+## Running Tests and Linting
+
+Always run both before committing:
+
+```bash
+just lint
+just test
+```
+
+To auto-format:
+
+```bash
+just fmt
+```
+
+## Testing Rules
+
+- **Never make live IBM Cloud API calls to test code.** Use `tests/mock_api.py`, which provides
+  a complete configurable mock of `IBMQuantumAPIClient`.
+- Tests do not require real credentials or network access.
+- The mock supports setting account allocation, per-instance allocations/limits, and usage across
+  five time windows (28d, 14d, 7d, 3d, 24h).
+
+## Committing
+
+All commits must be DCO signed-off. Use `git commit -s`.
+
+## Key Prohibitions
+
+- Do not run `qauvern optimize` against a real account to verify behavior — use `analyze`
+  with `--dry-run` or write a test with `mock_api.py`.
+- Do not hardcode API keys or CRNs in source files.
+
+## Release Process
+
+Releases are automated via GitHub Actions. To release a new version:
+
+1. Update the `version` in `pyproject.toml` (semver format: `X.Y.Z`)
+2. Add a `## [X.Y.Z] - YYYY-MM-DD` section to `CHANGELOG.md` with release notes
+3. Add the version link at the bottom of `CHANGELOG.md`
+4. Merge to `main`
+
+The release workflow triggers on any push to `main` that changes `pyproject.toml`. It will:
+- Validate the version format and check no tag already exists
+- Run the full test suite across all supported Python versions
+- Build the distribution
+- Publish to PyPI via trusted publishing
+- Create a git tag and GitHub Release with changelog notes
+
+PyPI publishing uses trusted publishing (OIDC), configured via the `pypi` GitHub environment.
+
+## Maintenance Rule
+
+After any design change (algorithm, API endpoints, data model, config format), update `Design.md`
+so the project can be reconstructed from that document alone.

qauvern-0.2.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to qauvern will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-05-13
+
+### Added
+
+- Release workflow for automated PyPI publishing via GitHub Actions
+- CI test matrix across Python 3.10, 3.11, 3.12, 3.13, 3.14
+- Python 3.12, 3.13, 3.14 support
+
+## [0.1.0] - 2026-05-06
+
+### Added
+
+- CLI with `analyze`, `optimize`, `configure`, `instances`, `show`, and `create` commands
+- Activity-score-based allocation algorithm with exponential time weighting
+- Rolling-window-aware `net_grants` for additive budget boosts
+- IBM Cloud IAM authentication (API key via `IBMCLOUD_API_KEY`)
+- Regional endpoint support (auto-extracted from CRN)
+- Staging environment support (`--staging` flag)
+- YAML configuration with `configure` command for auto-discovery
+- Configurable minimum allocation floor
+
+[0.2.0]: https://github.com/ibm/qauvern/releases/tag/v0.2.0
+[0.1.0]: https://github.com/ibm/qauvern/releases/tag/v0.1.0

qauvern-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing
+
+## Pre-requisites
+
+- [Just](https://just.systems/man/en/)
+- [uv](https://docs.astral.sh/uv/getting-started/installation/)`
+
+## Signing Commits
+
+All commits must be signed off under the [Developer Certificate of Origin](https://developercertificate.org/).
+Use `git commit -s` (or `--signoff`) to append a `Signed-off-by` trailer to your commit message.
+PRs without sign-off will fail the DCO check.
+
+```bash
+git commit -s -m "Your commit message"
+```
+
+To sign off existing commits, amend or rebase with `--signoff`:
+
+```bash
+git commit --amend --signoff
+git rebase --signoff main
+```
+
+## Pre-commit hooks (detect-secrets)
+
+This project uses `detect-secrets` to prevent accidental commits of sensitive information.
+
+```bash
+uvx pre-commit install
+
+# First time only: create the secrets baseline
+uvx detect-secrets scan > .secrets.baseline
+
+# Verify hooks work
+uvx pre-commit run --all-files
+```
+
+If the hook detects a potential secret, either remove it from your code or add it to the baseline if it's a false positive:
+
+```bash
+uvx detect-secrets scan --baseline .secrets.baseline
+```
+
+## Running Tests
+
+```bash
+# Run all tests
+just test
+
+# Run with coverage
+just test --cov=qauvern --cov-report=term-missing
+
+# Run a specific file
+just test tests/test_models.py
+
+# Verbose output
+just test -v
+```
+
+## Code Quality
+
+```bash
+just fmt
+```
+
+```bash
+just lint
+```