Add AssemblyAI CLI (aai)

.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+  # Python dependencies declared in pyproject.toml.
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      python-deps:
+        patterns: ["*"]
+
+  # Keep the SHA-pinned GitHub Actions current.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]

.github/workflows/ci.yml

@@ -0,0 +1,96 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+# Least privilege: CI only needs to read the repo. Actions are pinned to commit
+# SHAs (a moved tag can't silently change what runs); Dependabot keeps them current.
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: lint + typecheck + tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      # PortAudio backs sounddevice; ffmpeg decodes non-WAV/URL audio (the `--sample`
+      # stream tests build a FileSource for the hosted sample, which needs ffmpeg).
+      - name: System deps (PortAudio + ffmpeg)
+        run: sudo apt-get update && sudo apt-get install -y libportaudio2 ffmpeg
+
+      # check.sh lints Markdown via the markdownlint CLI (a Node tool); pin to the
+      # version used locally. The runner ships Node, so a global npm install suffices.
+      - name: markdownlint CLI
+        run: npm install -g markdownlint-cli@0.45.0
+
+      # check.sh runs every tool through `uv run` / `uv build` for a locked,
+      # reproducible env, so uv must be on PATH (installed from PyPI to match the
+      # repo's pip-based, no-new-action posture).
+      - name: Install
+        run: python -m pip install -e ".[dev]" uv
+
+      - name: Lint, typecheck, test
+        run: ./scripts/check.sh
+
+  pre-commit:
+    name: pre-commit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      # PortAudio backs sounddevice; ffmpeg decodes the `--sample` stream source.
+      - name: System deps (PortAudio + ffmpeg)
+        run: sudo apt-get update && sudo apt-get install -y libportaudio2 ffmpeg
+
+      # The local pytest hook runs `python -m pytest`, so the package must be importable.
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+
+      - uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
+
+  build:
+    name: build + twine check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Build wheel + sdist
+        run: |
+          python -m pip install build twine
+          python -m build
+
+      - name: Validate metadata
+        run: twine check dist/*
+
+  audit:
+    name: pip-audit (dependency CVEs)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Audit runtime dependencies for known CVEs
+        run: |
+          python -m pip install -e . pip-audit
+          # Append `--ignore-vuln <ID>` to accept an unfixable transitive advisory.
+          python -m pip_audit

.gitignore

@@ -0,0 +1,21 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Editor/agent and local planning artifacts
+.claude/
+docs/
+
+# Local scratch scripts (often contain live keys)
+transcribe/
+
+# Wrong tool for this project (hatchling + uv); never commit a poetry lock
+poetry.lock

.markdownlint.json

@@ -0,0 +1,4 @@
+{
+  "default": true,
+  "MD013": false
+}

.pre-commit-config.yaml

@@ -0,0 +1,34 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.13
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: pytest
+        name: pytest
+        entry: python -m pytest -q -m "not e2e"
+        language: system
+        types: [python]
+        pass_filenames: false
+        always_run: true
+      - id: pytest-e2e
+        name: pytest-e2e (real API; skips without ASSEMBLYAI_API_KEY + kokoro)
+        entry: python -m pytest -q -m e2e
+        language: system
+        types: [python]
+        pass_filenames: false
+        always_run: true

LICENSE

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