smartvoice 0.2.0__tar.gz

smartvoice-0.2.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

smartvoice-0.2.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include catalog/models.json
+include catalog/router.json
+include config/smartvoice.example.json
+include native/qwen3-tts/LICENSE
+include native/qwen3-tts/UPSTREAM.md
+recursive-include native/qwen3-tts *.c *.h *.S *.inc Makefile LICENSE NOTICE.md

smartvoice-0.2.0/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: smartvoice
+Version: 0.2.0
+Summary: Local speech-to-text and text-to-speech service
+Project-URL: Homepage, https://github.com/dxhome/SmartVoice
+Project-URL: Repository, https://github.com/dxhome/SmartVoice
+Project-URL: Issues, https://github.com/dxhome/SmartVoice/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi<1.0,>=0.115
+Requires-Dist: uvicorn<1.0,>=0.30
+Requires-Dist: python-multipart<1.0,>=0.0.18
+Requires-Dist: langid<2.0,>=1.1.6
+Provides-Extra: inference
+Requires-Dist: sherpa-onnx<2.0,>=1.13.8; extra == "inference"
+Requires-Dist: numpy<3.0,>=1.26; extra == "inference"
+Requires-Dist: av<19.0,>=12.0; extra == "inference"
+Provides-Extra: dev
+Requires-Dist: httpx<1.0,>=0.27; extra == "dev"
+Requires-Dist: jiwer<5.0,>=4.0; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+  <img src="assets/smartvoice-logo.png" alt="SmartVoice logo" width="220">
+  <p><strong>Local speech recognition and synthesis, with language-aware model routing.</strong></p>
+  <p>Multilingual STT and TTS · CPU inference · OpenAPI · No per-request API fee</p>
+</div>
+
+# SmartVoice
+
+SmartVoice is a local speech-to-text (STT) and text-to-speech (TTS) service. It offers both through one OpenAI-style audio API, with models installed and run on your machine.
+
+## Why SmartVoice?
+
+- **One local service for speech:** Transcribe audio and synthesize speech through the same API, without sending media to a cloud provider.
+- **Choose models by language automatically:** Use SmartVoice's virtual model IDs to route each request to an installed model configured for that language.
+- **Works offline after setup:** Install model files once, then run inference locally on CPU with no per-request API fee.
+
+## Capabilities
+
+| Area | Capability |
+|---|---|
+| Platforms | Windows x64 and macOS Apple Silicon, run from source |
+| Inference | sherpa-onnx on Windows x64 and macOS Apple Silicon; native C INT8 Qwen3-TTS on macOS Apple Silicon and Windows x64 |
+| STT | Whisper Base multilingual, SenseVoice Small, Qwen3-ASR 0.6B |
+| TTS | Kokoro 1.1, Matcha Baker, Supertonic 3, Qwen3-TTS 0.6B |
+| Smart routing | Selects an installed model by task and language using an editable priority list; `smartvoice-auto` works for both STT and TTS |
+| API | OpenAPI docs, transcription, speech synthesis, model catalog and runtime status |
+| Model management | Install, uninstall, offline import/export, and resumable downloads |
+| Not yet supported | GPU inference, streaming, Linux/Android, remote access, packaged installers, MCP |
+
+For the architecture principles, implementation overview, per-backend OS/architecture/device/build matrix, and the difference between installed models and inference availability, see [Architecture Summary and Guidelines](doc/architecture-guidelines.md).
+
+SmartVoice supports a subset of OpenAI Audio API conventions; this is not a claim of full API compatibility. See the [API specification](doc/api-spec.md) for request and response details.
+
+## Smart routing
+
+Smart routing selects an installed model using the request task, language, and an ordered, user-editable JSON table. Use `smartvoice-auto` for language-aware routing on either audio endpoint, or pass a concrete model ID to call that model directly.
+
+TTS model priority order:
+
+1. Chinese: Qwen3-TTS → Matcha → Kokoro
+2. German, French, Spanish, Japanese, Korean: Supertonic → Qwen3-TTS
+3. English: Supertonic → Qwen3-TTS → Kokoro
+4. Portuguese, Russian, Italian: Supertonic → Qwen3-TTS
+5. Other supported languages: Supertonic
+
+For STT, the built-in route table prioritizes SenseVoice for Chinese, English, Cantonese, Japanese, and Korean; Qwen3-ASR covers the remaining configured languages, with Whisper as a fallback for selected languages.
+
+SmartVoice routes by the API endpoint and language:
+
+| Request | Virtual model ID | Language source |
+|---|---|---|
+| Transcription | `smartvoice-auto` | Explicit `language`, or automatic detection when omitted or `auto` |
+| Speech synthesis | `smartvoice-auto` | Explicit `language`, or text detection when omitted or `auto` |
+
+The built-in route table is copied to `<data_dir>/router.json` on first startup. Edit it to customize model priorities, then apply changes without restarting:
+
+```bash
+python -m smartvoice router reload
+```
+
+The first installed and verified candidate is selected. An inference failure does not trigger a retry with the next candidate. See the [API specification](doc/api-spec.md) for request details.
+
+## Model catalog
+
+Models use the inference adapter identified in the catalog. Language availability describes catalog capability, not comparative quality; model and voice licenses may differ from SmartVoice's license. The recommended STT models are SenseVoice and Qwen3-ASR. TTS recommendations are reflected in the [Smart routing](#smart-routing) priorities. Supertonic 3 does not support Chinese. Benchmark coverage varies by language, and TTS listening quality has not been rated with MOS.
+
+| Model ID | Task | Languages / voices | Estimated model files | Recommendation |
+|---|---|---|---|---|
+| `stt-whisper-base-multilingual-int8` | STT | Auto detection; English, Chinese, Japanese, Korean, French, German | ~0.16 GB | — |
+| `stt-sensevoice-small-int8` | STT | Chinese, English, Cantonese, Japanese, Korean | ~0.24 GB | Recommended |
+| `stt-qwen3-asr-600m-int8` | STT | 30 language codes including Cantonese; automatic detection | ~0.99 GB | Recommended |
+| `tts-kokoro-multilingual-v1-1-zh-en` | TTS | Chinese, English; 103 speakers | ~0.41 GB | Chinese / English fallback |
+| `tts-matcha-zh-baker` | TTS | Chinese; one voice | ~0.13 GB | Chinese fallback |
+| `tts-supertonic-v3-multilingual-int8` | TTS | 31 languages; no Chinese | ~0.15 GB | Recommended for its supported languages |
+| `tts-qwen3-0-6b-customvoice` | TTS | 10 languages; 9 preset voices | ~2.50 GB | Recommended for Chinese and measured multilingual routes |
+
+Catalog model sizes are estimates of the unpacked model files, rounded to two decimal places in decimal GB; actual disk use can vary slightly. The web test page shows the recorded on-disk size when available and otherwise labels the catalog estimate. Installation may need additional temporary space. Qwen3-TTS 0.6B needs at least 6 GiB free disk space during installation. See [`catalog/models.json`](catalog/models.json) for the byte estimates, exact language codes, sources, and model details.
+
+Melo TTS has been removed from the supported catalog, and Supertonic 3 does not support Chinese. Existing model files are left on disk. If an older `<data_dir>/router.json` references the removed Melo model or routes Supertonic for Chinese, SmartVoice rejects that saved routing table, uses the built-in router, and reports a warning. Remove those stale entries and run `python -m smartvoice router reload` to clear the warning.
+
+For routed STT requests with `language=auto`, SmartVoice uses the Whisper Tiny spoken-language detector when it is installed, then routes to an STT model for the detected language. `python -m smartvoice models install all` installs this detector by default. Without it, SmartVoice falls back to an installed STT model that supports automatic language detection. The detector is not downloaded during service startup. Its availability is reported by `/v1/capabilities`.
+
+## Quick start
+
+SmartVoice requires Python 3.11 or newer and runs inference on CPU. The service binds to `127.0.0.1` by default.
+
+### 1. Install SmartVoice
+
+From a source checkout, create a virtual environment and install the inference dependencies. Windows x64 source builds include the Qwen native runtime, so install the MSYS2 UCRT64 build tools described below before running `pip install`.
+
+macOS:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[inference]"
+```
+
+Windows PowerShell:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -e ".[inference]"
+```
+
+Run these commands from the repository root. You do not need to activate the virtual environment. In the model and server commands below, replace `python` with `.\.venv\Scripts\python.exe` in Windows PowerShell.
+
+On macOS Apple Silicon, the source install builds the native INT8 Qwen3-TTS runtime using Xcode Command Line Tools. On Windows x64, build the native runtime from the source checkout as described below.
+
+#### Build the Qwen3-TTS runtime on Windows
+
+The Windows source deployment builds Qwen3-TTS with MSYS2 UCRT64 GCC and OpenBLAS. Install MSYS2 and its UCRT64 toolchain packages in an elevated MSYS2 UCRT64 terminal before installing SmartVoice:
+
+```bash
+pacman -S --needed make gcc diffutils mingw-w64-ucrt-x86_64-openblas
+```
+
+Then, from the SmartVoice repository root in PowerShell, build the runtime into the source package and check that it starts:
+
+```powershell
+# Omit this if MSYS2 is installed at C:\msys64 or %USERPROFILE%\msys64.
+$env:SMARTVOICE_MSYS2_ROOT = "C:\msys64"
+$env:SMARTVOICE_QWEN_OUTPUT = "$PWD\src\smartvoice\resources\bin"
+.\.venv\Scripts\python.exe .\scripts\build_qwen3_tts_windows.py
+```
+
+The build script runs the native runtime self-test and stages `qwen_tts.exe`, its required runtime DLLs, and license notices in `src/smartvoice/resources/bin` for the editable source checkout. The Windows package build also bundles the runtime in its build output. These generated binaries are local build artifacts and are not committed. If MSYS2 is installed elsewhere, set `SMARTVOICE_MSYS2_ROOT` to that directory. Python source installation remains editable; a SmartVoice wheel is not required.
+
+### 2. Download models
+
+Install a basic STT and TTS model. Model files are downloaded once and stored outside the source checkout, under `~/Library/Application Support/SmartVoice` on macOS or `%LOCALAPPDATA%\SmartVoice` on Windows.
+
+```bash
+python -m smartvoice models install stt-sensevoice-small-int8
+python -m smartvoice models install tts-kokoro-multilingual-v1-1-zh-en
+python -m smartvoice models install-language-id
+```
+
+On macOS Apple Silicon and Windows x64 after building its native runtime, install Qwen3-TTS to use the configured Chinese and multilingual routes:
+
+```bash
+python -m smartvoice models install tts-qwen3-0-6b-customvoice
+```
+
+On Windows, first build the native runtime as described in [Build the Qwen3-TTS runtime on Windows](#build-the-qwen3-tts-runtime-on-windows). Then install the model as above. Without that runtime, the model will be listed as unavailable and other installed TTS models remain usable.
+
+The first model installation requires internet access. After installation, inference runs locally. See [Model catalog](#model-catalog) for supported languages and estimated sizes.
+
+### 3. Start SmartVoice
+
+Start SmartVoice:
+
+```bash
+python -m smartvoice --host 127.0.0.1 --port 8000
+```
+
+Open the [test page](http://127.0.0.1:8000/test) to verify basic STT and TTS functionality with your installed models. Open [API docs](http://127.0.0.1:8000/docs) for endpoint details. Service settings are stored in `<data_dir>/smartvoice.json`; routing priorities are stored separately in `<data_dir>/router.json` and can be reloaded with `python -m smartvoice router reload`.
+
+### 4. Connect an agent or application
+
+In your agent or application's settings, choose **OpenAI-compatible API** and set the SmartVoice API base URL to:
+
+```text
+http://127.0.0.1:8000/v1
+```
+
+## API
+
+The audio endpoints follow a supported subset of the OpenAI Audio API conventions. For request fields, response formats, and errors, see the [API specification](doc/api-spec.md).
+
+### Transcribe audio with routing
+
+```powershell
+curl.exe -F "file=@sample.wav" -F "model=smartvoice-auto" -F "language=auto" `
+  http://127.0.0.1:8000/v1/audio/transcriptions
+```
+
+Supported upload formats include WAV, MP3, M4A, and FLAC. Audio is limited to 25 MiB and 10 minutes by default.
+
+### Synthesize speech with routing
+
+```powershell
+curl.exe -X POST http://127.0.0.1:8000/v1/audio/speech `
+  -H "Content-Type: application/json" `
+  -d '{"model":"smartvoice-auto","input":"Hello from SmartVoice.","language":"auto"}' `
+  --output speech.wav
+```
+
+TTS returns mono WAV audio. Requests support up to 4,000 characters; generated audio is limited to 180 seconds or 32 MiB by default. See `/docs` or the [API specification](doc/api-spec.md) for available parameters, language behavior, and error codes.
+
+## Manage models
+
+The CLI supports `models list`, `install`, `uninstall`, `export`, and `import`. `models list` groups models by installed state, then by STT, TTS, and SmartVoice native; each model shows its availability, and unavailable models include a reason. Availability checks both model-file integrity and the active inference runtime/device. Use `python -m smartvoice models install all` to install every catalog model that is not already installed and the Whisper Tiny language detector. Model downloads run sequentially from their catalog sources; invalid existing model directories are skipped with a repair hint. Installing all models can require several gigabytes of disk space. On Windows x64, Qwen3-TTS is available only when its native runtime has been built; see [Build the Qwen3-TTS runtime on Windows](#build-the-qwen3-tts-runtime-on-windows). Models can also be installed through API download jobs. Exported model packages can be transferred to offline machines and imported there. An installed model cannot be uninstalled while the service is using it.
+
+Install a model with `python -m smartvoice models install <model-id>`. By default, SmartVoice uses the model's catalog source. For Hugging Face models, pass `--source` with a compatible mirror base URL to use another source, such as:
+
+```bash
+python -m smartvoice models install stt-qwen3-asr-600m-int8 --source https://hf-mirror.com
+```
+
+The base URL is combined with the catalog-pinned repository, revision, and file paths. This option is available only when all required model files are hosted on Hugging Face. Downloaded files are still checked against their catalog SHA-256 values.
+
+```bash
+python -m smartvoice models list
+python -m smartvoice models export stt-sensevoice-small-int8 ./sensevoice.smartvoice.zip
+python -m smartvoice models import ./sensevoice.smartvoice.zip
+python -m smartvoice models uninstall stt-sensevoice-small-int8
+```
+
+## Architecture
+
+```text
+Client / Agent ──► Versioned HTTP API ──► Application services
+                         ▲                       │
+                         │                       ▼
+                    Local CLI              Domain contracts
+                                                 │
+                               ┌─────────────────┴─────────────────┐
+                               ▼                                   ▼
+                       Inference port                      Model repository port
+                               │                                   │
+                               ▼                                   ▼
+                    Composite inference provider       Filesystem catalog adapter
+                       ┌───────┴────────┐
+                       ▼                ▼
+                sherpa-onnx       native C INT8 Qwen-TTS
+                   adapter            adapter
+                       │
+                       ▼
+              Platform diagnostics adapter
+```
+
+Callers use versioned API and capability endpoints; inference details stay behind provider and repository interfaces. The source deployment supports CPU inference on Windows x64 and macOS Apple Silicon. Qwen3-TTS uses the native C INT8 adapter on both platforms; Windows x64 source deployments build its runtime with MSYS2 as described above. GPU providers, streaming, Linux and Android runtimes are not available in SmartVoice. See [Architecture Summary and Guidelines](doc/architecture-guidelines.md) for the detailed matrix and model availability semantics.
+
+## Development
+
+```bash
+python -m pip install -e ".[inference,dev]"
+python scripts/test.py ci
+```
+
+Run `python scripts/test.py regression` to execute the full functional suite including real STT/TTS inference. It directly smoke-tests each catalog model installed and available on the current runtime, using one representative language per model; unavailable models are skipped individually. The existing route integration scenarios also run when their optional models and language-ID assets are installed. See [`doc/testing.md`](doc/testing.md) for details and [`benchmarks/README.md`](benchmarks/README.md) for model quality, latency, and concurrency comparisons.
+See [`doc/releasing.md`](doc/releasing.md) for versioning, GitHub Releases, and optional PyPI publishing.
+
+## Repository layout
+
+```text
+catalog/       Model metadata and default router table
+src/           API/CLI entry points, application services, domain contracts, ports, and adapters
+tests/         Unit, API, and optional real-inference tests
+benchmarks/    Benchmark code, configurations, and results
+config/        Example service settings
+doc/           API specification, testing, release, requirements, and design notes
+assets/        Project logo
+```
+
+## License
+
+SmartVoice source code is licensed under the [Apache License 2.0](LICENSE). Model weights, voices, and other third-party assets may have separate license terms; review them before use or redistribution.