avartha-python-sdk 0.0.1__tar.gz → 0.0.3__tar.gz

avartha_python_sdk-0.0.3/.github/workflows/ci.yml

@@ -0,0 +1,102 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      fuzz_seed:
+        description: Optional seed to replay speech HTTP and WebSocket fuzz inputs
+        type: string
+        default: ''
+  merge_group:
+    types: [checks_requested]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  check:
+    name: Python ${{ matrix.python }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0  # setuptools_scm derives the version from git tags
+          fetch-tags: true
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: python -m pip install -e '.[dev]'
+      - name: Check SDK and local HTTP/WebSocket contracts
+        run: make check PYTEST_ARGS='--junitxml=artifacts/tests/results.xml'
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: tests-python-${{ matrix.python }}
+          path: artifacts/tests/results.xml
+          if-no-files-found: warn
+          retention-days: 14
+
+  preview-fuzz:
+    name: Preview WebSocket compatibility fuzz
+    # Fork and Dependabot PRs cannot access repository secrets. Keep their
+    # offline checks above; never use pull_request_target to run PR code.
+    # Feature branches use the PR run so pushes don't duplicate live workloads.
+    if: >-
+      github.actor != 'dependabot[bot]' &&
+      (github.event_name != 'push' ||
+       github.ref == format('refs/heads/{0}', github.event.repository.default_branch)) &&
+      (github.event_name != 'pull_request' ||
+       github.event.pull_request.head.repo.full_name == github.repository)
+    runs-on: ubuntu-24.04
+    timeout-minutes: 40
+    concurrency:
+      group: preview-websocket-live
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.12'
+          cache: pip
+          cache-dependency-path: |
+            pyproject.toml
+            tests/fixtures/preview/constraints.txt
+      - run: python -m pip install -c tests/fixtures/preview/constraints.txt .
+      - name: Fuzz supported speech HTTP and WebSocket workflows
+        env:
+          AVARTHA_API_KEY: ${{ secrets.AVARTHA_API_KEY }}
+          FUZZ_SEED: ${{ inputs.fuzz_seed || github.run_id }}
+        run: >-
+          python scripts/preview_behavior.py
+          --fuzz-rounds 1 --fuzz-seed "$FUZZ_SEED"
+          --output artifacts/preview-fuzz
+      - name: Publish fuzz summary
+        if: always()
+        run: |
+          if [[ -f artifacts/preview-fuzz/summary.md ]]; then
+            cat artifacts/preview-fuzz/summary.md >> "$GITHUB_STEP_SUMMARY"
+          fi
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        if: always()
+        with:
+          name: preview-websocket-fuzz-${{ github.run_id }}-${{ github.run_attempt }}
+          path: artifacts/preview-fuzz/
+          if-no-files-found: warn
+          retention-days: 14

avartha_python_sdk-0.0.3/.github/workflows/preview-behavior.yml

@@ -0,0 +1,80 @@
+name: Preview WebSocket behavior
+
+on:
+  workflow_dispatch:
+    inputs:
+      scenario:
+        description: Optional exact scenario ID from the contract; empty runs all
+        type: string
+        default: ''
+      llm_model:
+        description: Optional text Realtime model; blank selects the first available
+        type: string
+        default: ''
+      tts_model:
+        description: Preview PCM24k TTS model
+        type: string
+        default: qwen/qwen3-tts-12hz-1.7b-base
+      asr_model:
+        description: Preview PCM16k ASR model
+        type: string
+        default: mistralai/voxtral-mini-4b-realtime-2602
+      voice:
+        description: Voice supported by the selected TTS model
+        type: string
+        default: carol
+
+permissions:
+  contents: read
+
+concurrency:
+  group: preview-websocket-live
+  cancel-in-progress: false
+
+jobs:
+  behavior:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 40
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.12'
+          cache: pip
+          cache-dependency-path: |
+            pyproject.toml
+            tests/fixtures/preview/constraints.txt
+      - run: python -m pip install -c tests/fixtures/preview/constraints.txt .
+      - name: Exercise supported preview WebSocket behaviors
+        env:
+          AVARTHA_API_KEY: ${{ secrets.AVARTHA_API_KEY }}
+          SCENARIO: ${{ inputs.scenario }}
+          LLM_MODEL: ${{ inputs.llm_model }}
+          TTS_MODEL: ${{ inputs.tts_model }}
+          ASR_MODEL: ${{ inputs.asr_model }}
+          VOICE: ${{ inputs.voice }}
+        run: |
+          args=(--tts-model "$TTS_MODEL" --asr-model "$ASR_MODEL" --voice "$VOICE")
+          if [[ -n "$LLM_MODEL" ]]; then
+            args+=(--llm-model "$LLM_MODEL")
+          fi
+          if [[ -n "$SCENARIO" ]]; then
+            args+=(--scenario "$SCENARIO")
+          fi
+          python scripts/preview_behavior.py "${args[@]}"
+      - name: Publish behavioral summary
+        if: always()
+        run: |
+          if [[ -f artifacts/preview-behavior/summary.md ]]; then
+            cat artifacts/preview-behavior/summary.md >> "$GITHUB_STEP_SUMMARY"
+          fi
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        if: always()
+        with:
+          name: preview-websocket-behavior
+          path: artifacts/preview-behavior/
+          if-no-files-found: warn
+          retention-days: 14

{avartha_python_sdk-0.0.1 → avartha_python_sdk-0.0.3}/.github/workflows/publish.yml

@@ -28,7 +28,7 @@ jobs:
           python-version: '3.12'
           cache: pip
           cache-dependency-path: pyproject.toml
-      - run: python -m pip install --upgrade pip build twine
+      - run: python -m pip install --upgrade pip build twine "setuptools-scm>=8,<9"
       - name: Verify version from tag
         # Refuse to build off an untagged commit: setuptools_scm would guess the
         # next version and we would publish a release nobody tagged.
@@ -53,10 +53,15 @@ jobs:
     environment:
       name: pypi
       url: https://pypi.org/p/avartha-python-sdk
-    permissions:
-      # Required for Trusted Publishing; no API token is stored in this repo.
-      id-token: write
     steps:
+      - name: Check PyPI token
+        env:
+          PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          if [ -z "$PYPI_API_TOKEN" ]; then
+            echo "::error::Set PYPI_API_TOKEN in the pypi environment before publishing."
+            exit 1
+          fi
       - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
         with:
           name: python-package-distributions
@@ -64,3 +69,5 @@ jobs:
       - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
         with:
           packages-dir: dist/
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          attestations: false

{avartha_python_sdk-0.0.1 → avartha_python_sdk-0.0.3}/.gitignore

@@ -9,3 +9,5 @@ src/avartha/_version.py
 build/
 dist/
 .env
+*.wav
+artifacts/

{avartha_python_sdk-0.0.1 → avartha_python_sdk-0.0.3}/AGENTS.md

@@ -13,4 +13,9 @@ Only expose platform endpoints verified against avartha/platform. Document
 server prerequisites separately from SDK support. Keep private SDK attribute
 access isolated and pin the dependency range it was tested against.
 
+Keep customer-facing docs free of internal commit IDs, private source links,
+and internal issue references. Record verification provenance with the tests.
+Preserve existing audit and validation records, including their evidence, when
+updating customer-facing guides.
+
 Run `make check` before finishing. Do not add bot attribution to commits or docs.

avartha_python_sdk-0.0.3/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing
+
+Use Python 3.12+ and run `make install-dev` in a virtual environment.
+`make format` applies formatting; `make check` runs lint, type checking, tests,
+and wheel/source builds. Read AGENTS.md for compatibility rules.
+
+Owned protocol primitives must preserve the frozen WebSocket behavior.
+OpenAI and ElevenLabs compatibility is captured in protocol fixtures; neither
+package is needed for development or runtime. Exercise new behavior with real
+local WebSocket tests and those frozen contracts. OpenAI declarations are
+maintained in this repository. To regenerate speech schemas, use
+`make freeze-types FREEZE_ARGS=--elevenlabs-wheel=/path/to/elevenlabs-2.68.0-py3-none-any.whl`;
+the tool reads declarations from that offline wheel without installing or
+importing ElevenLabs. Review changes and third-party notices. Update the
+compatibility matrix when platform support changes; SDK support is separate.
+
+## WebSocket tests in GitHub Actions
+
+The **CI** workflow runs `make check` on Python 3.12, 3.13, and 3.14 for every
+push and pull request. Its **Check SDK and local WebSocket contracts** step
+includes the real loopback socket tests and saves per-test JUnit results in
+`tests-python-*` artifacts. These tests need no live credentials.
+
+Run the full live preview suite on a specific branch with:
+
+```sh
+gh workflow run preview-behavior.yml --ref YOUR_BRANCH
+```
+
+The repository secret `AVARTHA_API_KEY` supplies credentials. The workflow fails
+if any selected scenario fails, and publishes the scenario summary and JSON/JUnit
+reports even on failure. See the [live contract](docs/websocket-behavior.md) for
+its supported scenarios and limits.
+
+## Publishing a release
+
+Versions are derived from Git tags by `setuptools_scm`; a tag such as `v0.0.2`
+produces package version `0.0.2`. Do not edit `pyproject.toml` or
+`avartha.__version__` to set a release version.
+
+Configure publishing once:
+
+1. Create a PyPI API token scoped to the existing `avartha-python-sdk` project.
+2. In the GitHub repository's Settings → Environments, create the `pypi`
+   environment and add an environment secret named `PYPI_API_TOKEN` containing
+   the token. Store the token only as a secret, never in repository files.
+
+For each release:
+
+1. Merge the release changes into `main` and wait for CI on Python 3.12, 3.13,
+   and 3.14 to pass. Run `make check` locally and review the wheel/source archive.
+2. Create and publish a GitHub release with a new version tag targeting the
+   tested commit. For example, use `v0.0.2` for the release after `v0.0.1`.
+3. Wait for **Publish Release to PyPI** to succeed, then verify installation
+   with `python -m pip install avartha-python-sdk==0.0.2`.
+
+Publishing a GitHub release starts the workflow. Pushing a branch or tag alone
+does not publish. Manual workflow runs must select a release tag; the build
+requires its checked-out commit to have an exact tag. Each release must use a
+new version because PyPI does not allow existing distribution files to be
+replaced. The GitHub repository can remain private; uploaded PyPI artifacts
+are public.

{avartha_python_sdk-0.0.1 → avartha_python_sdk-0.0.3}/MANIFEST.in

@@ -1,8 +1,10 @@
-include LICENSE README.md CONTRIBUTING.md Makefile AGENTS.md
+include LICENSE THIRD_PARTY_NOTICES README.md CONTRIBUTING.md Makefile AGENTS.md
 recursive-include docs *.md *.json *.csv
 recursive-include examples *.py
 recursive-include tests *.py
+recursive-include tests/fixtures *.json *.txt *.md
 include .github/workflows/ci.yml
 include .github/workflows/publish.yml
+include .github/workflows/preview-behavior.yml
 include setup.py
 recursive-include scripts *.py

avartha_python_sdk-0.0.3/Makefile

@@ -0,0 +1,30 @@
+PYTHON ?= python
+BUILD_FLAGS ?=
+PREVIEW_ARGS ?=
+FREEZE_ARGS ?=
+PYTEST_ARGS ?=
+.PHONY: install-dev lint format test test-preview test-preview-fuzz build check freeze-types
+install-dev:
+	$(PYTHON) -m pip install -e '.[dev]'
+lint:
+	$(PYTHON) -m ruff check .
+	$(PYTHON) -m ruff format --check .
+	$(PYTHON) -m mypy
+format:
+	$(PYTHON) -m ruff check --fix .
+	$(PYTHON) -m ruff format .
+test:
+	$(PYTHON) -m pytest $(PYTEST_ARGS)
+test-preview:
+	$(PYTHON) scripts/preview_behavior.py $(PREVIEW_ARGS)
+test-preview-fuzz:
+	$(PYTHON) scripts/preview_behavior.py --fuzz-rounds 1 $(PREVIEW_ARGS)
+build:
+	$(PYTHON) -m build $(BUILD_FLAGS)
+check: lint test build
+
+freeze-types:
+	$(PYTHON) scripts/freeze_realtime_types.py $(FREEZE_ARGS)
+	$(PYTHON) -m ruff format src/avartha/types
+	$(PYTHON) -m ruff check --fix --ignore E501 src/avartha/types
+	$(PYTHON) -m ruff format src/avartha/types