miniapppolis-common-utils 5.0.1__tar.gz

miniapppolis_common_utils-5.0.1/.coveragerc

@@ -0,0 +1,6 @@
+[run]
+branch = True
+source = mini_app_polis
+
+[report]
+show_missing = True

miniapppolis_common_utils-5.0.1/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{yml,yaml,json,toml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

miniapppolis_common_utils-5.0.1/.env.example

@@ -0,0 +1,22 @@
+# KaianoApiClient
+KAIANO_API_BASE_URL=https://deejay-marvel-api.up.railway.app
+# This caller's own named API key. The client derives the variable name
+# from machine_name (deejay-cog -> DEEJAY_COG_API_KEY); KAIANO_API_KEY is
+# the fallback for a caller that declares no name.
+KAIANO_API_KEY=
+KAIANO_API_OWNER_ID=dev-owner
+
+# Logging
+LOGGING_LEVEL=DEBUG
+
+# Google APIs
+GOOGLE_CREDENTIALS_JSON=
+
+# Spotify
+SPOTIPY_CLIENT_ID=
+SPOTIPY_CLIENT_SECRET=
+SPOTIPY_REFRESH_TOKEN=
+
+# LLM (optional extra)
+ANTHROPIC_API_KEY=
+OPENAI_API_KEY=

miniapppolis_common_utils-5.0.1/.gitattributes

@@ -0,0 +1,22 @@
+# Lockfiles are generated artefacts, and git must never three-way merge
+# one. A text merge of two lockfiles produces a file that is
+# syntactically plausible and semantically wrong, with no conflict to
+# warn anybody.
+#
+# That is not hypothetical. Two Dependabot branches each added the same
+# new transitive package at different offsets in api-kaianolevine-com's
+# uv.lock; git merged both hunks cleanly and the result carried two
+# identical [[package]] blocks for truststore. uv then refused to parse
+# its own lockfile, every CI run failed, and `uv lock` could not repair
+# it either — it parses the existing lock before rewriting it. The same
+# merge silently reverted an openai constraint in pyproject.toml while
+# keeping the matching lock bump, so main pinned a version its manifest
+# forbade.
+#
+# `-merge` makes git treat these as unmergeable: when both sides change
+# one, the merge conflicts instead of inventing a result. The correct
+# resolution for a lockfile is always to regenerate it, never to
+# reconcile it line by line. This must be committed before the branches
+# that would diverge — git reads the attribute from the merge base.
+
+uv.lock            -merge

miniapppolis_common_utils-5.0.1/.github/dependabot.yml

@@ -0,0 +1,42 @@
+# Automated dependency updates.
+#
+# The fleet audits dependencies on every build (ecosystem-standards
+# SEC-003), which finds what has gone vulnerable but never fixes it.
+# Clearing those by hand does not scale — one repo needed 45 advisories
+# closed in a single sitting. This is the other half: keep dependencies
+# current so the audit has less to find.
+#
+# `commit-message.prefix` is load-bearing, not cosmetic. Dependabot's
+# default subject is "Bump x from y to z", which is not a Conventional
+# Commit. Every repo here releases through semantic-release, so an
+# unprefixed subject both trips VER-001 and cuts no release — the fix
+# would land on main and never reach the registry.
+#
+# Minor and patch updates are grouped into one pull request per
+# ecosystem per week. Majors arrive on their own, because a major is a
+# decision rather than a bump.
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    groups:
+      python-minor-and-patch:
+        update-types: ["minor", "patch"]
+    commit-message:
+      prefix: "fix(deps)"
+      prefix-development: "chore(deps)"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    groups:
+      actions:
+        patterns: ["*"]
+    commit-message:
+      prefix: "ci(deps)"

miniapppolis_common_utils-5.0.1/.github/workflows/ci.yml

@@ -0,0 +1,91 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  # Delegates to the fleet's shared security workflow: gitleaks over
+  # full history, pip-audit against the resolved dependency set, and
+  # semgrep. sbom: false because SEC-005 does not apply to a
+  # shared-library — nothing here is deployed, so there is no build image
+  # for an SBOM to describe. The steps live in mini-app-polis/.github;
+  # see that repo's README for the inputs.
+  security:
+    uses: mini-app-polis/.github/.github/workflows/security.yml@v1
+    with:
+      language: python
+      package-manager: uv
+      sbom: false
+
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Lint
+        run: uv run ruff check src/ tests/
+
+      - name: Format check
+        run: uv run ruff format --check src/ tests/
+
+      - name: Type check
+        run: uv run mypy src/
+
+      - name: Test
+        run: uv run pytest --cov=mini_app_polis --cov-report=term-missing
+
+  release:
+    needs: [test, security]
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+      # PyPI trusted publishing. `uv publish --trusted-publishing always`
+      # exchanges this job's OIDC token for a short-lived PyPI credential,
+      # so there is no API token in Doppler and nothing to rotate. Unlike
+      # the npm path, this is the only credential shape offered here.
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Setup Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: 20
+
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          npm install --no-save semantic-release @semantic-release/commit-analyzer @semantic-release/release-notes-generator @semantic-release/changelog @semantic-release/exec @semantic-release/git @semantic-release/github
+          npx semantic-release

miniapppolis_common_utils-5.0.1/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+# uv / venv
+.venv/
+.uv/
+
+# Testing & coverage
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Ruff
+.ruff_cache/
+
+# mypy
+.mypy_cache/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env
+.env
+.env.*
+!.env.example
+
+# Node (semantic-release CI only — not committed)
+node_modules/
+package-lock.json

miniapppolis_common_utils-5.0.1/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pygrep-hooks
+    rev: v1.10.0
+    hooks:
+      - id: python-check-mock-methods
+      - id: python-use-type-annotations
+  # SEC-001. Same gitleaks the shared security workflow runs in CI, so a
+  # secret is caught before it is committed rather than after it is pushed.
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.28.0
+    hooks:
+      - id: gitleaks

miniapppolis_common_utils-5.0.1/.releaserc.json

@@ -0,0 +1,29 @@
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    [
+      "@semantic-release/changelog",
+      {
+        "changelogFile": "CHANGELOG.md"
+      }
+    ],
+    [
+      "@semantic-release/exec",
+      {
+        "verifyConditionsCmd": "./scripts/verify-pypi-publishing.sh",
+        "prepareCmd": "uv version ${nextRelease.version} && uv lock",
+        "publishCmd": "uv build && uv publish --trusted-publishing always"
+      }
+    ],
+    [
+      "@semantic-release/git",
+      {
+        "assets": ["CHANGELOG.md", "pyproject.toml", "uv.lock"],
+        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ],
+    "@semantic-release/github"
+  ]
+}

miniapppolis_common_utils-5.0.1/CHANGELOG.md

@@ -0,0 +1,278 @@
+## [5.0.1](https://github.com/mini-app-polis/common-python-utils/compare/v5.0.0...v5.0.1) (2026-09-05)
+
+
+### Bug Fixes
+
+* **release:** verify PyPI trusted publishing before bumping the version ([27d2d6b](https://github.com/mini-app-polis/common-python-utils/commit/27d2d6b5f7bede9927fd12781e5e4b19632563c7))
+
+# [5.0.0](https://github.com/mini-app-polis/common-python-utils/compare/v4.2.1...v5.0.0) (2026-09-05)
+
+
+* feat!: publish to PyPI as miniapppolis-common-utils ([bd1b5d0](https://github.com/mini-app-polis/common-python-utils/commit/bd1b5d026ee3af19fe751663d7d95073cd6034d8))
+
+
+### Bug Fixes
+
+* **git:** never three-way merge a lockfile ([d763070](https://github.com/mini-app-polis/common-python-utils/commit/d763070263baabb2a5c73ac54d8731ab4c33146d))
+
+
+### BREAKING CHANGES
+
+* the distribution is named miniapppolis-common-utils.
+Anything declaring common-python-utils, including by git ref, must be
+updated. See docs/pypi-package-publishing.md.
+
+## [4.2.1](https://github.com/mini-app-polis/common-python-utils/compare/v4.2.0...v4.2.1) (2026-09-04)
+
+
+### Bug Fixes
+
+* **deps:** bump mypy from 1.20.2 to 2.3.1 ([1de6340](https://github.com/mini-app-polis/common-python-utils/commit/1de634093b6dedc3404eabb166cc01f9e65aef5d))
+
+# [4.2.0](https://github.com/mini-app-polis/common-python-utils/compare/v4.1.0...v4.2.0) (2026-09-04)
+
+
+### Bug Fixes
+
+* **api:** stop discarding a query string written into the path ([3b8474b](https://github.com/mini-app-polis/common-python-utils/commit/3b8474b3707dcf37cf2da0530a9e7a4887442716))
+
+
+### Features
+
+* **deps:** automate dependency updates ([3914533](https://github.com/mini-app-polis/common-python-utils/commit/3914533120b6375787960cda39f59ace45a39ef5))
+
+# [4.1.0](https://github.com/mini-app-polis/common-python-utils/compare/v4.0.2...v4.1.0) (2026-09-03)
+
+
+### Features
+
+* **security:** call the shared security workflow, clear 22 advisories ([f4cc791](https://github.com/mini-app-polis/common-python-utils/commit/f4cc791a5671e916b2969b5bdb78937c78ae1189))
+
+## [4.0.2](https://github.com/mini-app-polis/common-python-utils/compare/v4.0.1...v4.0.2) (2026-09-02)
+
+
+### Bug Fixes
+
+* **release:** re-lock as part of the release ([4f4e60e](https://github.com/mini-app-polis/common-python-utils/commit/4f4e60e3089e015ca0649c20341ba860b003327e))
+
+## [4.0.1](https://github.com/mini-app-polis/common-python-utils/compare/v4.0.0...v4.0.1) (2026-09-02)
+
+
+### Bug Fixes
+
+* **deps:** re-lock after the 4.0.0 release ([2694b5f](https://github.com/mini-app-polis/common-python-utils/commit/2694b5fb13f3685c5b07d0f47b30645cc44e49ec))
+
+# [4.0.0](https://github.com/mini-app-polis/common-python-utils/compare/v3.2.0...v4.0.0) (2026-09-02)
+
+
+### Features
+
+* **api:** remove Clerk M2M token minting ([ac5a009](https://github.com/mini-app-polis/common-python-utils/commit/ac5a009102a1c48351623b38434d4690db8a2007))
+
+
+### BREAKING CHANGES
+
+* **api:** KaianoApiClient no longer accepts machine_secret and no
+longer reads KAIANO_API_CLERK_MACHINE_SECRET. Callers must pass machine_name
+(or api_key). A cog without a key now fails rather than falling back to the
+shared fleet identity — that fallback is what made every cog
+indistinguishable in the first place.
+
+# [3.2.0](https://github.com/mini-app-polis/common-python-utils/compare/v3.1.1...v3.2.0) (2026-09-02)
+
+
+### Features
+
+* **api:** derive each machine's API key from its name ([b156cda](https://github.com/mini-app-polis/common-python-utils/commit/b156cda02b9120b42142f517a06fe58c10597670))
+
+## [3.1.1](https://github.com/mini-app-polis/common-python-utils/compare/v3.1.0...v3.1.1) (2026-09-02)
+
+
+### Bug Fixes
+
+* finalizing identity procresses ([dac566d](https://github.com/mini-app-polis/common-python-utils/commit/dac566da76563ca90d3d5c5f89f36b5ea61fc9bb))
+
+# [3.1.0](https://github.com/mini-app-polis/common-python-utils/compare/v3.0.0...v3.1.0) (2026-08-19)
+
+
+### Bug Fixes
+
+* tests ([b7c5ee6](https://github.com/mini-app-polis/common-python-utils/commit/b7c5ee6a45d9138132f7c369e17ceb03ec88a56c))
+
+
+### Features
+
+* **pipeline-status:** allow CRITICAL as a self-reported severity ([5ea69f7](https://github.com/mini-app-polis/common-python-utils/commit/5ea69f7520592bbc24f9a9bc77a8612217904c6d))
+
+# [3.0.0](https://github.com/mini-app-polis/common-python-utils/compare/v2.6.1...v3.0.0) (2026-05-27)
+
+
+### Bug Fixes
+
+* pipeline status ([ce10f25](https://github.com/mini-app-polis/common-python-utils/commit/ce10f25f632231bfa0da6e0711e5a96ba75a27ab))
+* pipeline status ([1eb932a](https://github.com/mini-app-polis/common-python-utils/commit/1eb932a6343be57882cee517027bb35bf4d5ae2d))
+
+
+### Features
+
+* configurable max_tokens with truncation detection in LLM clients ([131fbd7](https://github.com/mini-app-polis/common-python-utils/commit/131fbd7765abfb76225650c986fdf8a9fb2784cc))
+
+
+### BREAKING CHANGES
+
+* callers that previously caught LLMValidationError for
+truncation will need to catch LLMTruncationError instead. The base
+LLMError still catches both. The default max_tokens has doubled from
+8192 to 16384, which may affect API costs for callers that were
+relying on the implicit cap.
+
+Co-authored-by: Cursor <cursoragent@cursor.com>
+
+## [2.6.1](https://github.com/mini-app-polis/common-python-utils/compare/v2.6.0...v2.6.1) (2026-05-17)
+
+
+### Bug Fixes
+
+* updated for transcript cof eval support ([b04e024](https://github.com/mini-app-polis/common-python-utils/commit/b04e024ce49014937612d100d698490c6ed6fbfc))
+
+# [2.6.0](https://github.com/mini-app-polis/common-python-utils/compare/v2.5.0...v2.6.0) (2026-05-17)
+
+
+### Features
+
+* common pipeline eval structure moving to common ([d15df57](https://github.com/mini-app-polis/common-python-utils/commit/d15df575557bb1ff6c3b71195a27c2cb59f2cce4))
+
+# [2.5.0](https://github.com/mini-app-polis/common-python-utils/compare/v2.4.2...v2.5.0) (2026-04-18)
+
+
+### Features
+
+* finalizing on opaque m2m tokens ([93fac4d](https://github.com/mini-app-polis/common-python-utils/commit/93fac4d82f47d402cbda57da8864f55b08db628c))
+
+## [2.4.2](https://github.com/mini-app-polis/common-python-utils/compare/v2.4.1...v2.4.2) (2026-04-17)
+
+
+### Bug Fixes
+
+* debug warning ([9363d91](https://github.com/mini-app-polis/common-python-utils/commit/9363d9115dbea4986c650cf53178434d3ed2a0cb))
+
+## [2.4.1](https://github.com/mini-app-polis/common-python-utils/compare/v2.4.0...v2.4.1) (2026-04-17)
+
+
+### Bug Fixes
+
+* debug ([6c9b474](https://github.com/mini-app-polis/common-python-utils/commit/6c9b474602e6fe6f546e270e58fc387753b25a92))
+
+# [2.4.0](https://github.com/mini-app-polis/common-python-utils/compare/v2.3.0...v2.4.0) (2026-04-17)
+
+
+### Features
+
+* finishing the proper implementation of auth through clerk ([5ec090e](https://github.com/mini-app-polis/common-python-utils/commit/5ec090ec2c63fe6907a4f5ecf144e263d7379498))
+
+# [2.3.0](https://github.com/mini-app-polis/common-python-utils/compare/v2.2.0...v2.3.0) (2026-04-17)
+
+
+### Features
+
+* updating m2m auth ([bdafc21](https://github.com/mini-app-polis/common-python-utils/commit/bdafc218ae267f73c6685e438d884b0bfc4ddc8e))
+
+# [2.2.0](https://github.com/mini-app-polis/common-python-utils/compare/v2.1.3...v2.2.0) (2026-04-17)
+
+
+### Features
+
+* upgrading auth to m2m clerk pattern ([9512b0c](https://github.com/mini-app-polis/common-python-utils/commit/9512b0c4c7ad8c28405389ba1795f84f809eb0ea))
+
+## [2.1.3](https://github.com/mini-app-polis/common-python-utils/compare/v2.1.2...v2.1.3) (2026-04-02)
+
+
+### Bug Fixes
+
+* docstrings, explicit CI coverage, and package identity docs (DOC-006, DOC-009, TEST-006) ([e8e2322](https://github.com/mini-app-polis/common-python-utils/commit/e8e2322bc3b9976dfe82aa6b6fa7d04c00e6152f))
+* remove literal URL from docstring to clear evaluator false positive ([b796e6b](https://github.com/mini-app-polis/common-python-utils/commit/b796e6b4cae304c0d4d635e652a94aadcf598e6b))
+
+## [2.1.2](https://github.com/mini-app-polis/common-python-utils/compare/v2.1.1...v2.1.2) (2026-04-02)
+
+
+### Bug Fixes
+
+* latest ([0557c55](https://github.com/mini-app-polis/common-python-utils/commit/0557c5546c6509322710250dfa8925e9a833957c))
+
+## [2.1.1](https://github.com/mini-app-polis/common-python-utils/compare/v2.1.0...v2.1.1) (2026-03-28)
+
+
+### Bug Fixes
+
+* fix ([768a508](https://github.com/mini-app-polis/common-python-utils/commit/768a508cad7b423e7b4cd70b2f4571eeb070de32))
+
+# [2.1.0](https://github.com/mini-app-polis/common-python-utils/compare/v2.0.0...v2.1.0) (2026-03-27)
+
+
+### Features
+
+* add music normalization module ([9ca9bfb](https://github.com/mini-app-polis/common-python-utils/commit/9ca9bfbd15d75f1ca7277b21924b280b46857e47))
+
+# [2.0.0](https://github.com/mini-app-polis/common-python-utils/compare/v1.3.0...v2.0.0) (2026-03-27)
+
+
+* feat!: rename import namespace from kaiano to mini_app_polis ([642cafa](https://github.com/mini-app-polis/common-python-utils/commit/642cafa2ebe37e96704a350ebec1708abd4dd54b))
+
+
+### BREAKING CHANGES
+
+* all imports change from `from kaiano.x` to `from mini_app_polis.x`
+
+Made-with: Cursor
+
+# [2.0.0] — Breaking: import namespace renamed kaiano → mini_app_polis
+
+All imports change from `from kaiano.x` to `from mini_app_polis.x`.
+
+# [1.3.0](https://github.com/mini-app-polis/common-python-utils/compare/v1.2.0...v1.3.0) (2026-03-27)
+
+
+### Bug Fixes
+
+* build ([f0573b3](https://github.com/mini-app-polis/common-python-utils/commit/f0573b31d7265d744b114396db5341e07f8c7f8a))
+
+
+### Features
+
+* reverting auth ([6e6d013](https://github.com/mini-app-polis/common-python-utils/commit/6e6d013b0e6abb90920f85d77073165891da9338))
+
+# [1.2.0](https://github.com/mini-app-polis/common-python-utils/compare/v1.1.2...v1.2.0) (2026-03-27)
+
+
+### Features
+
+* adding clerk functionality ([02bb6bf](https://github.com/mini-app-polis/common-python-utils/commit/02bb6bf3aee963570c10282374b8ec784c6431d4))
+* adding clerk functionality ([fb5abe6](https://github.com/mini-app-polis/common-python-utils/commit/fb5abe6871b689afa613a63548f230cd76bd5c2b))
+
+## [1.1.2](https://github.com/mini-app-polis/common-python-utils/compare/v1.1.1...v1.1.2) (2026-03-27)
+
+
+### Bug Fixes
+
+* removing warning ([cfe5206](https://github.com/mini-app-polis/common-python-utils/commit/cfe52063457137b3d0058804c3a125e4eb70db0f))
+
+## [1.1.1](https://github.com/mini-app-polis/common-python-utils/compare/v1.1.0...v1.1.1) (2026-03-27)
+
+
+### Bug Fixes
+
+* removing warning ([baa2475](https://github.com/mini-app-polis/common-python-utils/commit/baa2475e8d19e3e4eca3c56c0078fabef6844db3))
+
+# [1.1.0](https://github.com/mini-app-polis/common-python-utils/compare/v1.0.0...v1.1.0) (2026-03-27)
+
+
+### Features
+
+* cleanup and align with ecosystem standards ([c43bdbf](https://github.com/mini-app-polis/common-python-utils/commit/c43bdbfecad43558bedf240673f73dc9060f03fd))
+
+# 1.0.0 (2026-03-27)
+
+
+### Features
+
+* breaking change: cleaning up for build ([2552043](https://github.com/mini-app-polis/common-python-utils/commit/25520430dc22508ea98b351b1d9c7c73c2e739cf))