argus-echo 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. argus_echo-0.1.0/.copier-answers.yml +22 -0
  2. argus_echo-0.1.0/.dockerignore +15 -0
  3. argus_echo-0.1.0/.env.example +99 -0
  4. argus_echo-0.1.0/.github/workflows/ci.yml +27 -0
  5. argus_echo-0.1.0/.github/workflows/engines.yml +81 -0
  6. argus_echo-0.1.0/.github/workflows/release.yml +171 -0
  7. argus_echo-0.1.0/.github/workflows/suite.yml +14 -0
  8. argus_echo-0.1.0/.gitignore +15 -0
  9. argus_echo-0.1.0/.suite-rules-baseline.json +8 -0
  10. argus_echo-0.1.0/CHANGELOG.md +45 -0
  11. argus_echo-0.1.0/CLAUDE.md +79 -0
  12. argus_echo-0.1.0/LICENSE +21 -0
  13. argus_echo-0.1.0/Makefile +27 -0
  14. argus_echo-0.1.0/PKG-INFO +139 -0
  15. argus_echo-0.1.0/README.md +113 -0
  16. argus_echo-0.1.0/compose.yaml +237 -0
  17. argus_echo-0.1.0/docs/api.md +213 -0
  18. argus_echo-0.1.0/docs/miso-api.md +373 -0
  19. argus_echo-0.1.0/docs/miso-config.md +155 -0
  20. argus_echo-0.1.0/docs/new-engine.md +65 -0
  21. argus_echo-0.1.0/docs/qwen.md +87 -0
  22. argus_echo-0.1.0/docs/voice-cloning.md +86 -0
  23. argus_echo-0.1.0/docs/whisper.md +84 -0
  24. argus_echo-0.1.0/docs/xtts.md +49 -0
  25. argus_echo-0.1.0/engines/miso/.dockerignore +6 -0
  26. argus_echo-0.1.0/engines/miso/.gitignore +52 -0
  27. argus_echo-0.1.0/engines/miso/.python-version +1 -0
  28. argus_echo-0.1.0/engines/miso/Dockerfile +49 -0
  29. argus_echo-0.1.0/engines/miso/LICENSE +27 -0
  30. argus_echo-0.1.0/engines/miso/README.md +222 -0
  31. argus_echo-0.1.0/engines/miso/generator.py +385 -0
  32. argus_echo-0.1.0/engines/miso/miso_server.py +2752 -0
  33. argus_echo-0.1.0/engines/miso/models.py +297 -0
  34. argus_echo-0.1.0/engines/miso/moshi_compat.py +47 -0
  35. argus_echo-0.1.0/engines/miso/pyproject.toml +39 -0
  36. argus_echo-0.1.0/engines/miso/requirements-test.txt +15 -0
  37. argus_echo-0.1.0/engines/miso/requirements.txt +14 -0
  38. argus_echo-0.1.0/engines/miso/run_server.sh +27 -0
  39. argus_echo-0.1.0/engines/miso/test_admin_uploads.py +184 -0
  40. argus_echo-0.1.0/engines/miso/test_clone_id_safety.py +102 -0
  41. argus_echo-0.1.0/engines/miso/test_clone_pipeline.py +546 -0
  42. argus_echo-0.1.0/engines/miso/test_gen_lock.py +224 -0
  43. argus_echo-0.1.0/engines/miso/test_generator_safety.py +91 -0
  44. argus_echo-0.1.0/engines/miso/test_health.py +22 -0
  45. argus_echo-0.1.0/engines/miso/test_language.py +61 -0
  46. argus_echo-0.1.0/engines/miso/test_lifecycle.py +264 -0
  47. argus_echo-0.1.0/engines/miso/test_sampling_params.py +136 -0
  48. argus_echo-0.1.0/engines/miso/test_storage_safety.py +91 -0
  49. argus_echo-0.1.0/engines/miso/test_utterance_shaping.py +282 -0
  50. argus_echo-0.1.0/engines/miso/uv.lock +2106 -0
  51. argus_echo-0.1.0/engines/miso/watermarking.py +87 -0
  52. argus_echo-0.1.0/engines/qwen/.dockerignore +2 -0
  53. argus_echo-0.1.0/engines/qwen/Dockerfile +43 -0
  54. argus_echo-0.1.0/engines/qwen/requirements-test.txt +13 -0
  55. argus_echo-0.1.0/engines/qwen/tests/test_admin_auth.py +55 -0
  56. argus_echo-0.1.0/engines/qwen/tests/test_clones.py +614 -0
  57. argus_echo-0.1.0/engines/qwen/tests/test_gpu_residue.py +150 -0
  58. argus_echo-0.1.0/engines/qwen/tests/test_health.py +34 -0
  59. argus_echo-0.1.0/engines/qwen/tests/test_stream.py +287 -0
  60. argus_echo-0.1.0/engines/qwen/tests/test_tts_server.py +653 -0
  61. argus_echo-0.1.0/engines/qwen/tts_server.py +2040 -0
  62. argus_echo-0.1.0/engines/whisper/.dockerignore +2 -0
  63. argus_echo-0.1.0/engines/whisper/Dockerfile +39 -0
  64. argus_echo-0.1.0/engines/whisper/requirements-test.txt +12 -0
  65. argus_echo-0.1.0/engines/whisper/requirements.txt +12 -0
  66. argus_echo-0.1.0/engines/whisper/stt_server.py +762 -0
  67. argus_echo-0.1.0/engines/whisper/tests/test_stt_server.py +360 -0
  68. argus_echo-0.1.0/engines/wyoming/Dockerfile +24 -0
  69. argus_echo-0.1.0/engines/wyoming/asr_bridge.py +237 -0
  70. argus_echo-0.1.0/engines/wyoming/requirements.txt +3 -0
  71. argus_echo-0.1.0/engines/wyoming/tests/test_asr_bridge.py +222 -0
  72. argus_echo-0.1.0/engines/wyoming/tests/test_tts_bridge.py +192 -0
  73. argus_echo-0.1.0/engines/wyoming/tts_bridge.py +331 -0
  74. argus_echo-0.1.0/engines/xtts/.dockerignore +2 -0
  75. argus_echo-0.1.0/engines/xtts/Dockerfile +60 -0
  76. argus_echo-0.1.0/engines/xtts/requirements-test.txt +13 -0
  77. argus_echo-0.1.0/engines/xtts/tests/test_gpu_residue.py +121 -0
  78. argus_echo-0.1.0/engines/xtts/tests/test_health.py +20 -0
  79. argus_echo-0.1.0/engines/xtts/tests/test_xtts_audit.py +225 -0
  80. argus_echo-0.1.0/engines/xtts/tests/test_xtts_clones.py +165 -0
  81. argus_echo-0.1.0/engines/xtts/tests/test_xtts_server.py +688 -0
  82. argus_echo-0.1.0/engines/xtts/xtts_server.py +1961 -0
  83. argus_echo-0.1.0/gpu-tenant.yaml +58 -0
  84. argus_echo-0.1.0/pyproject.toml +61 -0
  85. argus_echo-0.1.0/src/argus_echo/__init__.py +16 -0
  86. argus_echo-0.1.0/src/argus_echo/_version.py +24 -0
  87. argus_echo-0.1.0/src/argus_echo/assets/jfk.flac +0 -0
  88. argus_echo-0.1.0/src/argus_echo/check.py +226 -0
  89. argus_echo-0.1.0/src/argus_echo/cli.py +46 -0
  90. argus_echo-0.1.0/src/argus_echo/contract/__init__.py +36 -0
  91. argus_echo-0.1.0/src/argus_echo/contract/stt.py +120 -0
  92. argus_echo-0.1.0/src/argus_echo/contract/tts.py +79 -0
  93. argus_echo-0.1.0/src/argus_echo/py.typed +0 -0
  94. argus_echo-0.1.0/tests/test_check.py +102 -0
  95. argus_echo-0.1.0/tests/test_repo_rules.py +54 -0
  96. argus_echo-0.1.0/tests/test_smoke.py +8 -0
  97. argus_echo-0.1.0/tests/test_stt.py +130 -0
@@ -0,0 +1,22 @@
1
+ # Managed by Copier — do not edit by hand.
2
+ # Run `copier update` in this repo to pull template changes.
3
+ _commit: 87ca4c1
4
+ _src_path: gh:smk762/argus-pkg-template
5
+ author: smk762
6
+ brand_mark: false
7
+ cli_name: argus-echo
8
+ description: 'The Argus suite''s speech servers: Miso, XTTS-v2 and Qwen3-TTS behind
9
+ one HTTP contract, plus a Wyoming bridge'
10
+ dockerfile: Dockerfile
11
+ github_owner: smk762
12
+ has_cli: true
13
+ has_server: false
14
+ image_name: argus-echo
15
+ package_name: argus_echo
16
+ post_test: ''
17
+ project_name: argus-echo
18
+ python_min: '3.11'
19
+ ruff_pin: 0.15.16
20
+ test_extras: dev
21
+ version_build_arg: false
22
+
@@ -0,0 +1,15 @@
1
+ # NOTE: .git is deliberately *not* ignored -- hatch-vcs reads the version from
2
+ # git history at build time. Set `version_build_arg` if you want it excluded.
3
+ .github
4
+ .venv
5
+ venv
6
+ dist
7
+ build
8
+ *.egg-info
9
+ **/__pycache__
10
+ **/*.py[cod]
11
+ .pytest_cache
12
+ .ruff_cache
13
+ .mypy_cache
14
+ .coverage
15
+ htmlcov
@@ -0,0 +1,99 @@
1
+ # Copy to .env. Every value is optional; compose.yaml falls back to the defaults shown.
2
+ # Reference: docs/api.md, docs/miso-config.md, docs/xtts.md, docs/qwen.md.
3
+
4
+ # ── Network ───────────────────────────────────────────────────────────────────
5
+ # Every port is published as ECHO_BIND:<port>. 127.0.0.1 keeps the engines on this
6
+ # machine; 0.0.0.0 or a LAN address serves other machines. Only /admin/* is
7
+ # authenticated, so expose the ports only on a network you trust.
8
+ ECHO_BIND=127.0.0.1
9
+ MISO_PORT=8140
10
+ XTTS_PORT=8141
11
+ QWEN_PORT=8142
12
+ WHISPER_PORT=8144
13
+ WYOMING_XTTS_PORT=10240
14
+ WYOMING_MISO_PORT=10241
15
+ WYOMING_QWEN_PORT=10242
16
+ WYOMING_WHISPER_PORT=10243
17
+ # Image tag compose pulls or builds: `local` builds from source; a release tag pulls ghcr.io/smk762/argus-echo-*.
18
+ ECHO_TAG=local
19
+ NVIDIA_VISIBLE_DEVICES=all
20
+
21
+ # ── Admin ─────────────────────────────────────────────────────────────────────
22
+ # Bearer token for /admin/* on every engine (argus-iris sends it). Empty = admin routes
23
+ # answer 503. Generate with `openssl rand -hex 32`; never commit it.
24
+ ARGUS_ADMIN_TOKEN=
25
+ # 1 opens /admin/* while ARGUS_ADMIN_TOKEN is empty. Local development only.
26
+ ARGUS_ADMIN_INSECURE=
27
+
28
+ # ── Storage (S3 / MinIO) ──────────────────────────────────────────────────────
29
+ # One endpoint, one bucket per engine (clones share key names but not formats).
30
+ # Create the buckets first. *_S3_PUBLIC_URL is the base clients fetch audio from,
31
+ # e.g. http://minio.lan:9000/voice-xtts.
32
+ S3_ENDPOINT_URL=
33
+ S3_ACCESS_KEY_ID=
34
+ S3_SECRET_ACCESS_KEY=
35
+ MISO_S3_BUCKET=voice-miso
36
+ MISO_S3_PUBLIC_URL=
37
+ XTTS_S3_BUCKET=voice-xtts
38
+ XTTS_S3_PUBLIC_URL=
39
+ QWEN_S3_BUCKET=voice-qwen
40
+ QWEN_S3_PUBLIC_URL=
41
+
42
+ # ── Miso ──────────────────────────────────────────────────────────────────────
43
+ HF_TOKEN=
44
+ # Hugging Face cache; point at an existing one to reuse a downloaded checkpoint.
45
+ HF_HOME=./cache/huggingface
46
+ MISO_MODEL=MisoLabs/MisoTTS
47
+ MISO_TTS_TOKENIZER=unsloth/Llama-3.2-1B
48
+ MISO_PRELOAD=0
49
+ # local: files under MISO_DATA_DIR, served by Miso at /media/{key}; s3: the bucket above.
50
+ MISO_STORAGE_BACKEND=local
51
+ MISO_DATA_DIR=./data/miso
52
+ # Base of the audio_url Miso returns with the local backend: the URL clients use.
53
+ MISO_PUBLIC_URL=http://localhost:8140
54
+ MISO_KEEP_ALIVE_GPU=300
55
+ MISO_KEEP_ALIVE_CPU=0
56
+ MISO_NO_CUDA_GRAPH=1
57
+ # Speech-to-text engine that transcribes /clone-voice clips sent without reference_text,
58
+ # e.g. http://whisper:8031 (the whisper profile). Empty: such clones have no transcript.
59
+ MISO_STT_URL=
60
+ MISO_STT_TIMEOUT_S=60
61
+
62
+ # ── XTTS-v2 ───────────────────────────────────────────────────────────────────
63
+ XTTS_DEVICE=cuda:0
64
+ XTTS_PRELOAD=0
65
+ XTTS_KEEP_ALIVE_GPU=120
66
+ XTTS_KEEP_ALIVE_CPU=600
67
+
68
+ # ── Qwen3-TTS ─────────────────────────────────────────────────────────────────
69
+ # 0.6b or 1.7b; also the image build arg (the weights are baked in).
70
+ QWEN_MODEL_SIZE=0.6b
71
+ QWEN_DEVICE=cuda:0
72
+ QWEN_PRELOAD=0
73
+ QWEN_KEEP_ALIVE_GPU=120
74
+ QWEN_KEEP_ALIVE_CPU=600
75
+
76
+ # ── Wyoming bridges ───────────────────────────────────────────────────────────
77
+ # The engine each bridge forwards to (TTS: wyoming-xtts, -miso, -qwen; ASR: wyoming-whisper); defaults are the engine in this compose project.
78
+ WYOMING_XTTS_ENGINE_URL=http://xtts:8031
79
+ WYOMING_MISO_ENGINE_URL=http://miso:8031
80
+ WYOMING_QWEN_ENGINE_URL=http://qwen:8031
81
+ # Qwen built-in speaker the bridge uses when Home Assistant names none.
82
+ WYOMING_QWEN_SPEAKER=ryan
83
+ # The ASR bridge (wyoming-whisper) forwards to the whisper engine's POST /transcribe.
84
+ WYOMING_WHISPER_ENGINE_URL=http://whisper:8031
85
+ # Blank: the language Home Assistant sends, else detect. Seconds to wait for a transcript.
86
+ WYOMING_WHISPER_LANGUAGE=
87
+ WYOMING_WHISPER_TIMEOUT=120
88
+
89
+ # ── Whisper (speech to text) ──────────────────────────────────────────────────
90
+ # compose maps WHISPER_* onto the engine's STT_* variables. Reference: docs/api.md, "Speech to text".
91
+ WHISPER_DEVICE=cuda
92
+ WHISPER_PRELOAD=0
93
+ WHISPER_KEEP_ALIVE_GPU=300
94
+ WHISPER_KEEP_ALIVE_CPU=600
95
+ WHISPER_BEAM_SIZE=5
96
+ WHISPER_MAX_UPLOAD_MB=50
97
+ WHISPER_MAX_SECONDS=600
98
+ WHISPER_QUEUE_TIMEOUT_S=30
99
+ WHISPER_STREAM_MAX_SESSIONS=4
@@ -0,0 +1,27 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [dev, main]
6
+ pull_request:
7
+ branches: [dev, main]
8
+
9
+ concurrency:
10
+ group: ci-${{ github.ref }}
11
+ cancel-in-progress: true
12
+
13
+ permissions:
14
+ contents: read
15
+
16
+ jobs:
17
+ ci:
18
+ uses: smk762/argus-ci/.github/workflows/python-ci.yml@v1
19
+ with:
20
+ ruff-version: "0.15.16"
21
+ test-extras: "dev"
22
+
23
+
24
+ suite-rules:
25
+ # argus-ci suite rules: lint rules that each eliminate a finding class. New violations fail;
26
+ # existing ones are in .suite-rules-baseline.json, which may only shrink.
27
+ uses: smk762/argus-ci/.github/workflows/suite-rules.yml@v1
@@ -0,0 +1,81 @@
1
+ name: Engines
2
+
3
+ # Each engine's unit tests, in that engine's own environment. They stub or mock the models, so no GPU or weights
4
+ # are needed. Miso resolves its locked environment (torch 2.9) from engines/miso/uv.lock; XTTS and Qwen stub torch;
5
+ # Whisper takes a fake model and VAD, so faster-whisper is not installed.
6
+ # Each engine's test dependencies are in its requirements-test.txt, which ai-code-auditor's validate_patch also reads.
7
+
8
+ on:
9
+ push:
10
+ branches: [dev, main]
11
+ pull_request:
12
+ branches: [dev, main]
13
+
14
+ concurrency:
15
+ group: engines-${{ github.ref }}
16
+ cancel-in-progress: true
17
+
18
+ permissions:
19
+ contents: read
20
+
21
+ jobs:
22
+ test:
23
+ runs-on: ubuntu-latest
24
+ strategy:
25
+ fail-fast: false
26
+ matrix:
27
+ engine: [miso, xtts, qwen, whisper]
28
+ defaults:
29
+ run:
30
+ working-directory: engines/${{ matrix.engine }}
31
+ steps:
32
+ - name: Free disk space
33
+ if: matrix.engine == 'miso'
34
+ run: sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc && df -h /
35
+ working-directory: .
36
+ - uses: actions/checkout@v4
37
+ - uses: astral-sh/setup-uv@v6
38
+ - name: ruff (errors only)
39
+ run: uvx ruff@0.15.16 check --select E9,F63,F7,F82 .
40
+ - name: pytest (miso)
41
+ if: matrix.engine == 'miso'
42
+ run: uv run --python 3.11 --with-requirements requirements-test.txt python -m pytest -q
43
+ - name: pytest (${{ matrix.engine }})
44
+ if: matrix.engine != 'miso'
45
+ run: uv run --no-project --python 3.11 --with-requirements requirements-test.txt python -m pytest -q tests
46
+
47
+ wyoming:
48
+ runs-on: ubuntu-latest
49
+ defaults:
50
+ run:
51
+ working-directory: engines/wyoming
52
+ steps:
53
+ - uses: actions/checkout@v4
54
+ - uses: astral-sh/setup-uv@v6
55
+ - name: ruff (errors only)
56
+ run: uvx ruff@0.15.16 check --select E9,F63,F7,F82 .
57
+ - name: imports
58
+ run: uv run --no-project --python 3.11 --with-requirements requirements.txt python -c "import tts_bridge, asr_bridge"
59
+ - name: pytest
60
+ run: uv run --no-project --python 3.11 --with-requirements requirements.txt --with pytest python -m pytest -q tests
61
+
62
+ compose:
63
+ runs-on: ubuntu-latest
64
+ steps:
65
+ - uses: actions/checkout@v4
66
+ - name: Every profile resolves
67
+ run: |
68
+ for p in miso xtts qwen whisper wyoming-xtts wyoming-miso wyoming-qwen wyoming-whisper; do
69
+ docker compose --profile "$p" config -q && echo "$p ok"
70
+ done
71
+
72
+ gpu-tenant:
73
+ # gpu-tenant.yaml must validate as argus-cortex's TenantManifest (argus-iris refuses unknown fields).
74
+ runs-on: ubuntu-latest
75
+ steps:
76
+ - uses: actions/checkout@v4
77
+ - uses: astral-sh/setup-uv@v6
78
+ - run: >-
79
+ uv run --no-project --python 3.12 --with "argus-cortex[yaml]>=0.9,<0.10"
80
+ python -c "from argus_cortex.gpu_wire import load_tenant_manifest as load;
81
+ m = load('gpu-tenant.yaml'); print(m.tenant, [r.name for r in m.residents])"
@@ -0,0 +1,171 @@
1
+ name: Release to PyPI
2
+
3
+ # Top-level (non-reusable) on purpose: PyPI trusted publishing cannot run inside
4
+ # a reusable workflow. Keep this file in sync across the suite via `copier update`.
5
+
6
+ on:
7
+ push:
8
+ tags: ["v*"]
9
+ # Sent by argus-cortex's release workflow. The image installs argus-cortex
10
+ # from the pyproject range at build time, so rebuilding the newest release's
11
+ # image is how a new cortex reaches it. Only the image jobs run: PyPI and the
12
+ # GitHub Release for that tag already exist.
13
+ repository_dispatch:
14
+ types: [cortex-released]
15
+
16
+ permissions:
17
+ contents: read
18
+ id-token: write
19
+
20
+ jobs:
21
+ build:
22
+ # Not on a cortex dispatch, so the PyPI and Release jobs that chain off it
23
+ # skip too.
24
+ if: github.event_name == 'push'
25
+ runs-on: ubuntu-latest
26
+ steps:
27
+ - uses: actions/checkout@v4
28
+ with:
29
+ fetch-depth: 0
30
+ - uses: astral-sh/setup-uv@v6
31
+ with:
32
+ enable-cache: true
33
+ - run: uv build
34
+ - uses: actions/upload-artifact@v4
35
+ with:
36
+ name: dist
37
+ path: dist/
38
+
39
+ test-install:
40
+ runs-on: ubuntu-latest
41
+ needs: build
42
+ strategy:
43
+ matrix:
44
+ python-version: ["3.11", "3.12"]
45
+ steps:
46
+ - uses: actions/download-artifact@v4
47
+ with:
48
+ name: dist
49
+ path: dist/
50
+ - uses: astral-sh/setup-uv@v6
51
+ with:
52
+ enable-cache: true
53
+ - name: Install wheel and smoke-test import
54
+ run: |
55
+ uv venv --python ${{ matrix.python-version }}
56
+ uv pip install dist/*.whl
57
+ uv run --no-sync python -c "import argus_echo; print(f'argus-echo {argus_echo.__version__} OK')"
58
+
59
+ publish-testpypi:
60
+ runs-on: ubuntu-latest
61
+ needs: test-install
62
+ environment: testpypi
63
+ steps:
64
+ - uses: actions/download-artifact@v4
65
+ with:
66
+ name: dist
67
+ path: dist/
68
+ - uses: pypa/gh-action-pypi-publish@release/v1
69
+ with:
70
+ repository-url: https://test.pypi.org/legacy/
71
+
72
+ publish-pypi:
73
+ runs-on: ubuntu-latest
74
+ # Ordered *after* the TestPyPI rehearsal so its outcome is visible first, but
75
+ # deliberately not gated on it. A TestPyPI-only fault — a missing trusted
76
+ # publisher, an index outage — must not silently withhold the real release:
77
+ # that failure mode shipped argus-proof images for two tags with no wheel on
78
+ # PyPI, and nothing surfaced it because publish-image is independent.
79
+ # Only the build + install gate is required; a TestPyPI failure still marks
80
+ # the whole run failed, so the problem stays loud.
81
+ needs: [test-install, publish-testpypi]
82
+ if: "!cancelled() && needs.test-install.result == 'success'"
83
+ environment: pypi
84
+ steps:
85
+ - uses: actions/download-artifact@v4
86
+ with:
87
+ name: dist
88
+ path: dist/
89
+ - uses: pypa/gh-action-pypi-publish@release/v1
90
+
91
+ release-tag:
92
+ # The tag the image jobs build: the pushed one, or on a cortex dispatch the
93
+ # newest final release. A pre-release never moved `latest`, so a dispatch
94
+ # does not rebuild one.
95
+ runs-on: ubuntu-latest
96
+ outputs:
97
+ tag: ${{ steps.tag.outputs.tag }}
98
+ sha: ${{ steps.tag.outputs.sha }}
99
+ steps:
100
+ - uses: actions/checkout@v4
101
+ if: github.event_name == 'repository_dispatch'
102
+ - id: tag
103
+ env:
104
+ CORTEX_VERSION: ${{ github.event.client_payload.version }}
105
+ run: |
106
+ if [ "$GITHUB_EVENT_NAME" != repository_dispatch ]; then
107
+ echo "tag=$GITHUB_REF_NAME" >> "$GITHUB_OUTPUT"
108
+ echo "sha=$GITHUB_SHA" >> "$GITHUB_OUTPUT"
109
+ exit 0
110
+ fi
111
+ refs=$(git ls-remote --tags origin 'refs/tags/v*')
112
+ tag=$(echo "$refs" | sed -n 's|.*refs/tags/\(v[0-9]*\.[0-9]*\.[0-9]*\)\(\^{}\)\{0,1\}$|\1|p' | sort -uV | tail -n1)
113
+ if [ -z "$tag" ]; then
114
+ echo "::notice::No release tag yet, so no image to rebuild for cortex $CORTEX_VERSION."
115
+ exit 0
116
+ fi
117
+ # An annotated tag lists its commit on the peeled ^{} line.
118
+ sha=$(echo "$refs" | awk -v t="refs/tags/$tag" '$2 == t {l = $1} $2 == t "^{}" {p = $1} END {print p ? p : l}')
119
+ echo "Rebuilding $tag ($sha) for cortex $CORTEX_VERSION."
120
+ echo "tag=$tag" >> "$GITHUB_OUTPUT"
121
+ echo "sha=$sha" >> "$GITHUB_OUTPUT"
122
+
123
+ publish-image:
124
+ # One image per engine, ghcr.io/<owner>/argus-echo-<engine>, built from engines/<engine>/.
125
+ # The engines don't install this package; they share its contract, not its code.
126
+ runs-on: ubuntu-latest
127
+ needs: [release-tag, test-install]
128
+ # On a cortex dispatch test-install is skipped (nothing was built for PyPI),
129
+ # so the job runs on the tag alone.
130
+ if: "!cancelled() && needs.release-tag.outputs.tag != '' && (needs.test-install.result == 'success' || github.event_name == 'repository_dispatch')"
131
+ strategy:
132
+ fail-fast: false
133
+ matrix:
134
+ engine: [miso, xtts, qwen, whisper, wyoming]
135
+ permissions:
136
+ contents: read
137
+ packages: write
138
+ steps:
139
+ - name: Free disk space
140
+ # The GPU images carry CUDA torch (and XTTS/Qwen bake their weights): several GB each.
141
+ if: matrix.engine != 'wyoming'
142
+ run: sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc /opt/hostedtoolcache/CodeQL && df -h /
143
+ - uses: actions/checkout@v4
144
+ with:
145
+ ref: ${{ needs.release-tag.outputs.tag }}
146
+ - uses: docker/setup-buildx-action@v3
147
+ - uses: docker/login-action@v3
148
+ with:
149
+ registry: ghcr.io
150
+ username: ${{ github.actor }}
151
+ password: ${{ secrets.GITHUB_TOKEN }}
152
+ - id: meta
153
+ uses: docker/metadata-action@v5
154
+ with:
155
+ images: ghcr.io/${{ github.repository_owner }}/argus-echo-${{ matrix.engine }}
156
+ labels: org.opencontainers.image.revision=${{ needs.release-tag.outputs.sha }}
157
+ tags: |
158
+ type=semver,pattern={{version}},value=${{ needs.release-tag.outputs.tag }}
159
+ type=semver,pattern={{major}}.{{minor}},value=${{ needs.release-tag.outputs.tag }}
160
+ type=raw,value=latest
161
+ - uses: docker/build-push-action@v6
162
+ with:
163
+ context: engines/${{ matrix.engine }}
164
+ push: true
165
+ tags: ${{ steps.meta.outputs.tags }}
166
+ labels: ${{ steps.meta.outputs.labels }}
167
+ # A dispatch rebuilds an unchanged context, so a cached install layer
168
+ # would keep the old argus-cortex.
169
+ no-cache: ${{ github.event_name == 'repository_dispatch' }}
170
+ cache-from: type=gha,scope=${{ matrix.engine }}
171
+ cache-to: type=gha,mode=max,scope=${{ matrix.engine }}
@@ -0,0 +1,14 @@
1
+ name: Suite
2
+ on:
3
+ push:
4
+ branches: [dev, main]
5
+ tags: ["v*"]
6
+ pull_request:
7
+ branches: [dev, main]
8
+
9
+ permissions:
10
+ contents: read
11
+
12
+ jobs:
13
+ suite:
14
+ uses: smk762/argus-ci/.github/workflows/suite-check.yml@v1
@@ -0,0 +1,15 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ dist/
5
+ build/
6
+ *.egg-info/
7
+ .pytest_cache/
8
+ .ruff_cache/
9
+ # hatch-vcs writes this at build time (version derived from git tags)
10
+ src/argus_echo/_version.py
11
+
12
+ # Local config and runtime data
13
+ .env
14
+ cache/
15
+ data/
@@ -0,0 +1,8 @@
1
+ {
2
+ "version": 1,
3
+ "tools": {
4
+ "ruff": "0.15.16",
5
+ "semgrep": "1.180.0"
6
+ },
7
+ "entries": []
8
+ }
@@ -0,0 +1,45 @@
1
+ # Changelog
2
+
3
+ ## [Unreleased]
4
+
5
+ ## [0.1.0] - 2026-11-22
6
+
7
+ ### Added
8
+ - Miso `/clone-voice` fills an empty `reference_text` from the STT engine named by `MISO_STT_URL` (#13): each
9
+ stored clip goes to `POST /transcribe` (with the new `language` form field) within `MISO_STT_TIMEOUT_S`
10
+ (default 60), and `meta.json` records `reference_text_source` (`request`, `stt` or null) and
11
+ `reference_text_stt`. An STT failure refuses the clone (502/503/504) instead of storing it without a transcript.
12
+ `MISO_WHISPER_URL` is read as the old name.
13
+ - Speech to text (#4): the `whisper` engine (faster-whisper, Whisper large-v3-turbo, weights pinned by commit) on
14
+ port 8144 with `POST /transcribe` and a VAD-endpointed `WS /transcribe/stream`, its Compose profile, image and
15
+ `gpu-tenant.yaml` resident (3000 MB). The `stt` contract is `argus_echo.contract.stt`; docs/api.md and
16
+ docs/whisper.md (model comparison with Parakeet).
17
+ - `argus_echo.contract` is a package with one module per capability (`tts`, `stt`); `from argus_echo.contract
18
+ import ...` keeps working. `argus-echo check` runs only the suites an engine's `/health` `capabilities` name
19
+ (none means `tts`), and `--transcribe` posts a bundled public-domain clip to an `stt` engine.
20
+ - Engines salvaged into one repo: Miso TTS 8B (from smk762/voluptas `MisoTTS/`), XTTS-v2 and Qwen3-TTS (from
21
+ smk762/agent-composer `voice-stack/`), and the Wyoming TTS bridge.
22
+ - `compose.yaml` with a profile per engine, published on `ECHO_BIND` (loopback by default) at 8140–8142 and
23
+ 10240–10241.
24
+ - One S3 bucket per engine by default (`voice-miso`, `voice-xtts`, `voice-qwen`): the engines store clones under
25
+ the same keys in different formats.
26
+ - `argus_echo.contract` (shared request fields, PCM stream headers) and `argus-echo check <url>`.
27
+ - `gpu-tenant.yaml` for argus-iris; docs for the shared contract, each engine, and voice cloning.
28
+
29
+ ### Changed
30
+ - Evicting Qwen to the CPU left its speech tokenizer (the codec, one per loaded model) on the GPU: qwen-tts attaches it
31
+ as a plain attribute, which `Module.to()` never reaches. It now moves with the model, and Qwen and XTTS clear
32
+ cuBLAS's workspaces before `empty_cache()`, so an evicted engine holds only its CUDA context. Measured on an RTX
33
+ 3090: Qwen 0.6B CustomVoice evicted 776 → 322 MB, XTTS 336 → 314 MB. `/health`'s `gpu.cuda_context` says whether
34
+ a context is held (#22).
35
+ - XTTS and Qwen refuse to start when `S3_ENDPOINT_URL` is not an http(s) URL or `S3_BUCKET_NAME` is empty, instead
36
+ of failing each `/synthesise` after rendering (#22).
37
+ - Miso's `/synthesise` and `/synthesise/stream` answer `422` for a `language` other than `en` (or a region of it,
38
+ `en-US`, `en_GB`) instead of mispronouncing it (#6).
39
+ - Miso clone archives (`GET /clones/{id}/download`, `POST /clones/import`) carry the prompt as
40
+ `prompt.safetensors` (tensors, with speaker/sample_rate/ref_text in its metadata header) instead of a pickled
41
+ `prompt.pt`. Import never unpickles an upload: `torch.load(weights_only=True)` on the unauthenticated import
42
+ route was remote code execution on Miso's torch 2.4 (CVE-2025-32434). An archive holding only `prompt.pt` is
43
+ refused with `422`; re-export it from a current engine. Stored clones keep loading and download as safetensors.
44
+ - Every engine's `/admin/*` uses argus-cortex's `bearer`: closed (503) while `ARGUS_ADMIN_TOKEN` is unset, unless
45
+ `ARGUS_ADMIN_INSECURE=1`. Miso was open when unset in voluptas.
@@ -0,0 +1,79 @@
1
+ # CLAUDE.md — argus-echo
2
+
3
+ Guidance for AI agents working in this repo. Human-facing usage lives in [README.md](README.md); this file is the orientation an agent needs to change code safely.
4
+
5
+ ## What this is
6
+
7
+ The Argus suite's speech repo: text to speech (Miso TTS 8B, XTTS-v2, Qwen3-TTS), speech to text (Whisper large-v3-turbo) and, later, full-duplex dialogue. Echo has one HTTP contract per capability (`tts`, `stt`; docs/api.md), and each engine names the ones it serves in `/health` `capabilities`. A Wyoming bridge fronts the TTS engines. Each engine is a separate server with its own Python environment in `engines/<engine>/`; `src/argus_echo/` states the contracts in Python and checks a running engine against the capabilities it advertises. The engines were salvaged from smk762/voluptas (Miso) and smk762/agent-composer (`voice-stack/`), which still run them for older apps until those move to echo.
8
+
9
+ Shared code (admin bearer auth, upload caps, `ResidentHealth`, the tenant manifest) lives in **argus-cortex**; import it rather than re-implementing.
10
+
11
+ ## Argus suite
12
+ <!-- argus-suite: keep this block; argus-ci checks for it -->
13
+ This repo is part of the Argus suite. The suite map below lists every sibling and what it owns; check it before
14
+ building something a sibling may already do. **On every release, update this repo's row and capabilities in
15
+ argus-cortex's SUITE.md** (a PR to argus-cortex in the same release).
16
+
17
+ @../argus-core/SUITE.md
18
+
19
+ Not checked out? Read https://github.com/smk762/argus-cortex/blob/dev/SUITE.md
20
+
21
+ ## Must never happen
22
+
23
+ Each row names the test, CI job or lint that enforces it. Add a row for every rule this package must keep, and mark
24
+ it **UNENFORCED** until something checks it. When a rule bites, add a check rather than more prose.
25
+
26
+ | Never | Enforced by |
27
+ |---|---|
28
+ | A hand-edited version | `_version.py` is generated by hatch-vcs and gitignored |
29
+ | A new suite-rule violation (argus-ci's lint catalogue) | CI `suite-rules` job; `.suite-rules-baseline.json` may only shrink |
30
+ | A CLAUDE.md without the argus-suite block | CI `suite` job (argus-ci suite-check) |
31
+ | An engine's `/admin/*` open while `ARGUS_ADMIN_TOKEN` is unset, unless `ARGUS_ADMIN_INSECURE=1` | `engines/miso/test_admin_uploads.py`; xtts/qwen admin tests (CI `engines`) |
32
+ | A `/health` that isn't argus-cortex `ResidentHealth`, or that doesn't name the engine's capabilities | each engine's `test_health` (`engines/miso/test_health.py`, `engines/{xtts,qwen}/tests/test_health.py`, `engines/whisper/tests/test_stt_server.py`; CI `engines`); `argus-echo check` against a running engine |
33
+ | Two engines sharing an S3 bucket (clone keys collide, formats differ) | `tests/test_repo_rules.py::test_no_two_engines_share_an_s3_bucket` (distinct `S3_BUCKET_NAME` defaults and variables in `compose.yaml`) |
34
+ | An engine importing `argus_echo` (their environments conflict) | `tests/test_repo_rules.py::test_no_engine_imports_argus_echo` |
35
+ | `check` sending TTS requests to an engine that advertises only `stt` | `tests/test_stt.py::test_an_stt_engine_gets_no_tts_checks_and_a_read_only_check_loads_nothing` |
36
+ | An STT upload decoded before its byte, format and duration caps (it goes through `argus_cortex.limits.open_audio`) | `engines/whisper/tests/test_stt_server.py` (`test_upload_over_the_cap_is_413_and_never_loads`, `test_not_wav_or_flac_is_400`, `test_audio_over_the_duration_cap_is_413`) |
37
+ | An STT stream holding the model lease while it waits for audio | **UNENFORCED** (by design in `_stream`; needs a test that an idle open stream lets keep-alive evict) |
38
+ | `gpu-tenant.yaml` that iris would refuse | CI `engines` / `gpu-tenant` job |
39
+ | A demote to the CPU that leaves model weights or allocator cache on the GPU (qwen-tts's speech tokenizer, cuBLAS's workspace) | `engines/qwen/tests/test_gpu_residue.py`, `engines/xtts/tests/test_gpu_residue.py` (fakes; the real-GPU figures are in #22's PR) |
40
+ | An engine that starts with an S3 configuration it can't use (empty or non-http endpoint, no bucket, no credentials) | `test_gpu_residue.py` `S3EndpointRefusedAtStartupTest` / `test_an_empty_or_unusable_endpoint_is_refused_at_startup` |
41
+
42
+ ## Layout
43
+
44
+ - `src/argus_echo/contract/` — one module per capability: `tts.py` (request fields, PCM stream headers), `stt.py`; `__init__.py` lists the capabilities (the API surface; see docs/api.md).
45
+ - `src/argus_echo/check.py`, `cli.py` — `argus-echo check <url>`: read-only checks of a running engine, per advertised capability; `--speak` streams one utterance, `--transcribe` sends a bundled clip.
46
+ - `engines/miso/` — Miso server plus the vendored upstream MisoTTS inference code (`models.py`, `moshi_compat.py`, `watermarking.py`, patched `generator.py`), locked by its own `uv.lock`. Flat test files.
47
+ - `engines/xtts/`, `engines/qwen/` — single-file servers with `tests/` (torch stubbed).
48
+ - `engines/whisper/` — speech to text (faster-whisper large-v3-turbo), single-file server with `tests/` (fake model and VAD).
49
+ - `engines/wyoming/` — the Wyoming TTS bridge (CPU).
50
+ - `docs/new-engine.md` — the checklist a new engine follows (copy from `engines/whisper/`).
51
+ - `compose.yaml` — one profile per engine; `gpu-tenant.yaml` — iris residents (no node: placement is the deployment's).
52
+
53
+ ## Commands
54
+
55
+ ```bash
56
+ make install # uv venv + editable install with the "dev" extras
57
+ make test # pytest --tb=short -q
58
+ make lint # ruff check + format --check (pinned ruff 0.15.16)
59
+ make format # ruff format + --fix
60
+ ```
61
+
62
+ Run one test: `uv run --no-sync pytest tests/test_x.py::test_name -q`.
63
+
64
+ ## Conventions & gotchas
65
+
66
+ - **Versioning is git-tag-derived** (`hatch-vcs`). Never hand-edit a version; `src/argus_echo/_version.py` is generated (gitignored). Tag `vX.Y.Z` to release.
67
+ - **`src/` layout, `py.typed`, Pydantic v2, `structlog`.** Ruff line-length 120; keep it clean (`make lint`) before committing.
68
+ - **A change to a contract changes every engine of that capability.** Edit each engine that advertises it and `contract/<capability>.py` together, and say in docs/api.md which engines differ. A new engine adds its capabilities to `/health` and a `test_health` that validates them.
69
+ - **`GET /speakers` loads the model on XTTS and Qwen** (it takes a model lease). Nothing read-only may call it on an unloaded engine; `check` skips it.
70
+ - **Engines keep their own environment variable prefixes** (`MISO_*`, `XTTS_*`, `TTS_*` for Qwen); compose maps `QWEN_*` onto Qwen's `TTS_*`.
71
+ - The engines are linted for errors only (ruff E9/F63/F7/F82); `engines/` is excluded from the package's ruff config until they are cleaned up.
72
+
73
+ ## Branches
74
+
75
+ `dev` is the default branch and the base for every PR. Cut feature branches from `origin/dev` and bring them up to date by merging `origin/dev`, never `main`. Never push work to `main` or open a PR against it, except the release PR from `dev`: `main` must never be ahead of `dev`, with one exception. A release fast-forwards `main` to a `dev` commit that passed CI (`git push origin origin/dev:main`), then tags it. If `main` is protected, the release is a reviewed PR from `dev` into `main`, and merging it leaves a merge commit on `main` alone. That merge commit is the one exception to the rule: it leaves `main` one commit ahead of `dev` with an identical tree. Leave it there and don't merge `main` back into `dev`. Anything else on `main` that `dev` lacks is a mistake (`git diff origin/dev origin/main` must be empty). Once `main` carries such a commit it can't be fast-forwarded, so later releases are PRs too.
76
+
77
+ ## CI / release
78
+
79
+ CI runs via the shared [`argus-ci`](https://github.com/smk762/argus-ci) reusable workflow. Release publishes the `argus-echo` package to PyPI (OIDC trusted publishing) and one image per engine to GHCR (`ghcr.io/smk762/argus-echo-<engine>`) on `v*` tags. `engines.yml` runs each engine's tests in its own environment. Run `copier update` to pull template (CI/release/tooling) changes.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 smk762
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,27 @@
1
+ UV ?= uv
2
+
3
+ .PHONY: help install lint format test build clean
4
+
5
+ help: ## Show this help
6
+ @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf " \033[36m%-12s\033[0m %s\n", $$1, $$2}'
7
+
8
+ install: ## Create venv and install with test extras
9
+ $(UV) venv
10
+ $(UV) pip install -e ".[dev]"
11
+
12
+ lint: ## Ruff check + format check
13
+ $(UV)x ruff@0.15.16 check src/ tests/
14
+ $(UV)x ruff@0.15.16 format --check src/ tests/
15
+
16
+ format: ## Ruff autoformat + autofix
17
+ $(UV)x ruff@0.15.16 format src/ tests/
18
+ $(UV)x ruff@0.15.16 check --fix src/ tests/
19
+
20
+ test: ## Run the test suite
21
+ $(UV) run --no-sync pytest --tb=short -q
22
+
23
+ build: ## Build sdist + wheel
24
+ $(UV) build
25
+
26
+ clean: ## Remove build + cache artifacts
27
+ rm -rf dist build .venv *.egg-info .pytest_cache .ruff_cache src/argus_echo/_version.py