Add TypeScript implementation, Azure Speech TTS connector, browser support, and updated docs

- Add complete TypeScript implementation mirroring Python: core, CDK, connectors, interfaces, proxy, client
- Add Azure Speech TTS provider connector (azure.tts.v1) for both Python and TypeScript with SSML support
- Add browser-compatible provider base class (BrowserBaseProvider) and browser entry point
- Add secret store connectors: EncryptedFileSecretStore, MemorySecretStore, KeyringSecretStore
- Add CORS proxy tool for browser development
- Add browser samples (index.html + proxy-server.js)
- Update all documentation: connector catalogue, coverage matrix, CDK guides, developer guide
- Add new docs: BrowserUsage guide, SecretStores guide, Azure Speech TTS connector reference
- Update .gitignore with Node.js exclusions (node_modules, *.tgz)
- 1,084 tests passing (Python: 752, TypeScript: 332)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: apartsin

.gitignore

@@ -31,6 +31,10 @@ Thumbs.db
 # Logs
 *.log
 
+# Node.js
+node_modules/
+*.tgz
+
 # Package
 *.whl
 *.tar.gz

README.md

@@ -9,8 +9,10 @@
 
 <p align="center">
   <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+">
+  <img src="https://img.shields.io/badge/typescript-5.0%2B-blue" alt="TypeScript 5.0+">
+  <img src="https://img.shields.io/badge/docker-supported-2496ED" alt="Docker">
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
-  <a href="https://github.com/ApartsinProjects/ModelMesh/actions"><img src="https://img.shields.io/badge/tests-579%20passed-brightgreen" alt="Tests"></a>
+  <a href="https://github.com/ApartsinProjects/ModelMesh/actions"><img src="https://img.shields.io/badge/tests-808%20passed-brightgreen" alt="Tests"></a>
   <a href="https://apartsinprojects.github.io/ModelMesh/"><img src="https://img.shields.io/badge/docs-GitHub%20Pages-blue" alt="Documentation"></a>
 </p>
 
@@ -20,10 +22,16 @@ Your application requests a **capability** (e.g. "chat completion"). ModelMesh p
 
 ## Install
 
+**Python:**
 ```bash
 pip install modelmesh-lite
 ```
 
+**TypeScript / Node.js:**
+```bash
+npm install @modelmesh/core
+```
+
 ## Quick Start
 
 Set an API key and go:
@@ -49,11 +57,9 @@ print(response.choices[0].message.content)
 ### TypeScript
 
 ```typescript
-import { ModelMesh } from "@modelmesh/core";
+import { create } from "@modelmesh/core";
 
-const mesh = new ModelMesh();
-await mesh.initialize({ providers: ["openai"] });
-const client = mesh.getClient();
+const client = create("chat-completion");
 
 const response = await client.chat.completions.create({
     model: "chat-completion",
@@ -187,13 +193,22 @@ client = modelmesh.create(config="modelmesh.yaml")
 ## Development
 
 ```bash
-# Clone and install dev dependencies
+# Clone the repository
 git clone https://github.com/ApartsinProjects/ModelMesh.git
 cd ModelMesh
 
-# Run tests
+# Run Python tests (640 tests)
 pip install pytest
 cd src/python && python -m pytest ../../tests/ -v
+
+# Run TypeScript tests (168 tests)
+cd src/typescript && npm install && npm test
+```
+
+## Docker
+
+```bash
+docker run -e OPENAI_API_KEY="sk-..." ghcr.io/apartsinprojects/modelmesh
 ```
 
 ## License

docs/ConnectorCatalogue.md

@@ -118,6 +118,7 @@ pools:
 | **Replicate** | `provider.replicate.inference.v1` | Run any open-source model via API. Pay-per-second billing. | Flux Schnell, SDXL, Llama 3, Whisper | Limited free predictions; no credit card required | [replicate.com/docs](https://replicate.com/docs) |
 | **ElevenLabs** | `provider.elevenlabs.tts.v1` | Leading voice AI. Realistic speech synthesis and voice cloning. | Multilingual v2, Turbo v2.5, Flash v2.5, Monolingual v1 | 10,000 chars/month (~20 min audio); 3 custom voices; non-commercial | [elevenlabs.io/docs](https://elevenlabs.io/docs) |
 | **AssemblyAI** | `provider.assemblyai.stt.v1` | Speech intelligence platform. Transcription with built-in NLU. | Universal, Nano | $50 credits (~185h transcription); one-time, non-recurring | [www.assemblyai.com/docs](https://www.assemblyai.com/docs) |
+| **Azure Speech** | `provider.azure.tts.v1` | Microsoft Azure Cognitive Services Speech. Neural TTS with 400+ voices in 140+ languages. | en-US-JennyNeural, en-US-AndrewNeural, and all Azure Neural voices | 0.5M chars/month free (Neural); 5M chars/month free (Standard) | [learn.microsoft.com/azure/ai-services/speech-service](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/rest-text-to-speech) |
 
 ### Aggregators and Inference Platforms
 
@@ -184,10 +185,41 @@ Non-AI web services can be wrapped as provider connectors using the same interfa
 | **Stability AI**      | -        | yes       | -     | -          | -      | -        | -     | -         | credits       |
 | **ElevenLabs**        | -        | -         | yes   | -          | -      | -        | -     | -         | 10k chars/mo  |
 | **AssemblyAI**        | -        | -         | yes   | -          | -      | -        | -     | -         | $50 credit    |
+| **Azure Speech**      | -        | -         | yes   | -          | -      | -        | -     | -         | 0.5M chars/mo |
 | **Perplexity**        | yes      | -         | -     | -          | yes    | yes      | -     | -         | Pro only      |
 | **AWS Bedrock**       | yes      | yes       | -     | yes        | -      | yes      | yes   | yes       | AWS credits   |
 | **Google Cloud APIs** | -        | -         | yes   | -          | -      | -        | -     | -         | generous      |
 
+### CDK Base Classes for Providers
+
+| Base Class | Environment | Transport | Streaming | Use Case |
+| --- | --- | --- | --- | --- |
+| **BaseProvider** | Node.js | `http`/`https` | Node.js streams | Server-side applications, CLI tools, backend services |
+| **BrowserBaseProvider** | Browser, Deno, Bun, Workers | Fetch API | `ReadableStream` | Single-page apps, browser extensions, edge runtimes |
+
+Both classes expose the same provider interface and the same protected hooks for subclassing. See [cdk/BaseClasses.md](cdk/BaseClasses.html#browserbAseprovider) for details and [guides/BrowserUsage.md](guides/BrowserUsage.html) for browser setup.
+
+### Audio Namespace
+
+ElevenLabs (`elevenlabs.tts.v1`), Azure Speech (`azure.tts.v1`), and AssemblyAI (`assemblyai.stt.v1`) are accessible through the MeshClient audio namespace, which follows the OpenAI SDK audio pattern:
+
+```python
+# Text-to-speech
+audio_response = client.audio.speech.create(
+    model="text-to-speech",
+    input="Hello, world!",
+    voice="alloy",
+)
+
+# Speech-to-text
+transcript = client.audio.transcriptions.create(
+    model="speech-to-text",
+    file=audio_file,
+)
+```
+
+Audio requests are internally bridged to `CompletionRequest`/`CompletionResponse` via the `AudioRequest` and `AudioResponse` types (see [ConnectorInterfaces.md -- Audio](ConnectorInterfaces.html#audio)). The same rotation, failover, and pool logic applies to audio providers.
+
 ---
 
 ## Rotation Policies
@@ -219,7 +251,9 @@ Interface: [ConnectorInterfaces.md — Secret Store](ConnectorInterfaces.html#se
 | **`secret-store.google.secret-manager.v1`** | Google Cloud managed secrets with IAM and audit logging | 6 active versions free; 10K access ops/month free | [cloud.google.com/secret-manager](https://cloud.google.com/secret-manager) |
 | **`secret-store.microsoft.key-vault.v1`** | Microsoft cloud secret, key, and certificate management | 10K operations/month free (Standard tier) | [azure.microsoft.com/en-us/products/key-vault](https://azure.microsoft.com/en-us/products/key-vault) |
 | **`secret-store.1password.connect.v1`** | Secrets Automation API for CI/CD and server-side use | No free API tier; requires Business or Enterprise plan | [developer.1password.com](https://developer.1password.com) |
-| **`secret-store.modelmesh.json-secrets.v1`** | Reads secrets from a local JSON file. Keys are top-level object keys; values are strings. | Built-in | - |
+| **`secret-store.modelmesh.json-secrets.v1`** | Reads secrets from a local JSON file. Keys are top-level object keys; values are strings. Supports dot-notation for nested keys. | Built-in | - |
+| **`secret-store.modelmesh.memory-secrets.v1`** | Holds secrets in an in-memory dictionary. Ideal for testing, scripting, and user-provided keys. Supports runtime add/remove via SecretManagement interface. | Built-in | - |
+| **`secret-store.modelmesh.encrypted-file.v1`** | AES-256-GCM encrypted JSON file. Secrets are decrypted at initialization using a passphrase (PBKDF2) or raw key. Supports save/load round-trips. | Built-in | - |
 | **`secret-store.modelmesh.keyring.v1`** | Resolves secrets from the OS keyring (macOS Keychain, Windows Credential Locker, Linux Secret Service). | Built-in | - |
 
 ### Connector-Specific Configuration
@@ -265,19 +299,44 @@ Interface: [ConnectorInterfaces.md — Secret Store](ConnectorInterfaces.html#se
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `path` | string | Path to the JSON secrets file. Default: `./secrets.json`. |
+| `file_path` | string | Path to the JSON secrets file. |
+| `json_path` | string | Dot-notation path to scope lookups to a nested object (e.g., `secrets.production`). |
+| `fail_on_missing` | boolean | Throw on missing keys. Default: `true`. |
+
+**`secret-store.modelmesh.memory-secrets.v1`:**
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `secrets` | object | Dictionary of secret name/value pairs. |
+| `fail_on_missing` | boolean | Throw on missing keys. Default: `true`. |
+| `cache_enabled` | boolean | Enable TTL-based caching. Default: `true`. |
+
+**`secret-store.modelmesh.encrypted-file.v1`:**
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `file_path` | string | Path to the encrypted secrets file. |
+| `passphrase` | string | Human-readable passphrase for PBKDF2 key derivation. |
+| `encryption_key` | string | Raw 32-byte key as a 64-character hex string. Overrides passphrase. |
+| `pbkdf2_iterations` | integer | PBKDF2 iteration count. Default: `600000`. |
+| `fail_on_missing` | boolean | Throw on missing keys. Default: `true`. |
 
 **`secret-store.modelmesh.keyring.v1`:**
 
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `service_name` | string | Keyring service/application name. Default: `modelmesh`. |
+| `fail_on_missing` | boolean | Throw on missing keys. Default: `true`. |
 
 ### Deployment Patterns
 
 | Environment | Recommended Store | Reason |
 | --- | --- | --- |
 | Local dev | `modelmesh.dotenv.v1` / `modelmesh.env.v1` | simple, no infra |
+| Unit tests | `modelmesh.memory-secrets.v1` | inject known secrets without env setup |
+| Scripts | `modelmesh.memory-secrets.v1` | pass keys from user input at runtime |
+| Shared config | `modelmesh.encrypted-file.v1` | keys encrypted at rest, safe to commit |
+| Desktop apps | `modelmesh.keyring.v1` | OS-native secure storage |
 | AWS / GCP | native secret manager | IAM integration |
 | Serverless | cloud secret manager | runtime injection |
 | Client-side | server proxy | keys never reach client |

docs/ConnectorInterfaces.md

@@ -226,3 +226,29 @@ Parameters shared by all discovery connectors. Individual connectors may add con
 | `discovery.health.timeout` | duration | Probe timeout (e.g., `10s`). |
 | `discovery.health.failure_threshold` | integer | Consecutive failures before deactivation. |
 | `discovery.health.providers` | list | Providers to probe. Default: all enabled providers. |
+
+---
+
+## Audio
+
+Audio capabilities (text-to-speech, speech-to-text) are integrated into the provider interface through dedicated request and response types that bridge into the existing `CompletionRequest`/`CompletionResponse` pipeline. This allows audio providers (ElevenLabs TTS, AssemblyAI STT) to participate in the same rotation, failover, and pool routing as text-generation providers.
+
+### AudioRequest and AudioResponse Types
+
+| Type | Purpose | Key fields |
+| --- | --- | --- |
+| **AudioRequest** | Wraps a TTS or STT request for routing through the provider pipeline. | `input` (text for TTS, audio buffer for STT), `voice`, `format`, `model`, `language` |
+| **AudioResponse** | Wraps audio provider output. | `audio` (binary data or stream for TTS), `text` (transcript for STT), `duration`, `usage` |
+
+Audio connectors bridge these types into `CompletionRequest`/`CompletionResponse` internally. The provider's `complete()` method receives a `CompletionRequest` whose `extra` field carries the audio-specific parameters; the response's `extra` field carries audio-specific output. This preserves the uniform provider interface while supporting audio-specific data.
+
+### MeshClient Audio Namespace
+
+The `MeshClient` exposes audio through an OpenAI SDK-compatible namespace:
+
+| Method | Capability | Description |
+| --- | --- | --- |
+| `client.audio.speech.create()` | `generation.audio.text-to-speech` | Generate speech from text. Routes to TTS providers (ElevenLabs, OpenAI, Google Cloud). |
+| `client.audio.transcriptions.create()` | `understanding.audio.speech-to-text` | Transcribe audio to text. Routes to STT providers (AssemblyAI, OpenAI Whisper, Groq). |
+
+Audio requests follow the same routing pipeline as text requests: capability resolution, pool selection, rotation policy, retry, and failover. Pools targeting `generation.audio` or `understanding.audio` collect all audio-capable models automatically.

docs/CoverageMatrix.md

@@ -5,7 +5,7 @@ title: "Test Coverage Matrix"
 
 # Test Coverage Matrix
 
-Correlates documented features with test coverage. Generated from the 356-test suite across 12 test files.
+Correlates documented features with test coverage. The project includes 640 Python tests across 14 test files and 168 TypeScript tests across 10 test files, for a total of 808 tests.
 
 ---
 
@@ -24,7 +24,23 @@ Correlates documented features with test coverage. Generated from the 356-test s
 | Observability Stack | 26 | `test_observability.py` | Covered |
 | Pre-shipped Connectors | 32 | `test_connectors.py` | Covered |
 | CDK Specialized + Mixins + Helpers | 97 | `test_specialized.py` | Covered |
-| **Total** | **356** | **12 files** | |
+| **Total** | **640** | **14 files** | |
+
+### TypeScript Test Suite
+
+| Component | Tests | Test File | Status |
+| --- | ---: | --- | --- |
+| Interfaces (data types, factories, enums) | 12 | `interfaces.test.ts` | Covered |
+| CapabilityTree | 9 | `capability-tree.test.ts` | Covered |
+| EventEmitter | 10 | `event-emitter.test.ts` | Covered |
+| StateManager | 16 | `state-manager.test.ts` | Covered |
+| CapabilityPool | 15 | `pool.test.ts` | Covered |
+| ModelMesh facade | 16 | `mesh.test.ts` | Covered |
+| Router | 5 | `router.test.ts` | Covered |
+| Pre-shipped Connectors | 47 | `connectors.test.ts` | Covered |
+| MeshConfig + Auto-detect | 22 | `config.test.ts` | Covered |
+| MeshClient (OpenAI compat) | 16 | `client.test.ts` | Covered |
+| **Total** | **168** | **10 files** | |
 
 ---
 
@@ -159,10 +175,46 @@ Correlates documented features with test coverage. Generated from the 356-test s
 | CONNECTOR_REGISTRY (8 entries) | `ConnectorCatalogue.md` | `test_has_8_connectors`, `test_all_have_connector_id` | Registry completeness |
 | OpenAI Provider | `connectors/openai-llm.md` | `TestOpenAIProvider` (7 tests) | ID, URL, headers, models, endpoint |
 | Anthropic Provider | `connectors/anthropic-llm.md` | `TestAnthropicProvider` (10 tests) | ID, headers, payload, response parsing |
-| Env Secret Store | `connectors/modelmesh-env.md` | `TestEnvSecretStore` (5 tests) | ID, resolve, prefix, missing |
+| Env Secret Store | `connectors/modelmesh-env.md` | `TestEnvSecretStoreComprehensive` (7 tests) | ID, resolve, prefix, missing, interface |
+| Dotenv Secret Store | `ConnectorCatalogue.md` | `TestDotenvSecretStoreComprehensive` (8 tests) | Parsing, comments, quotes, multiline, env override |
+| JSON Secret Store | `ConnectorCatalogue.md` | `TestJsonSecretStoreComprehensive` (8 tests) | Flat, nested, dot-notation, json_path scoping |
+| Memory Secret Store | `guides/SecretStores.md` | `TestMemorySecretStore` (12 tests) | CRUD, interface, caching, set invalidation |
+| Encrypted File Store | `guides/SecretStores.md` | `TestEncryptedFileSecretStore` (12 tests) | Save/load, passphrase, hex key, round-trip, plaintext check |
+| Keyring Secret Store | `ConnectorCatalogue.md` | `TestKeyringSecretStoreComprehensive` (6 tests) | ID, service name, availability, fallback |
+| Azure Speech TTS | `ConnectorCatalogue.md` | `TestAzureSpeechProvider` (14 tests) | ID, region, URL, headers, SSML, models, XML escape |
 | Stick-Until-Failure | `connectors/modelmesh-stick-until-failure.md` | (via `TestBaseRotation`) | Tested through base rotation tests |
 | Local File Storage | `connectors/modelmesh-local-file.md` | (via `TestBaseStorage`) | Tested through base storage tests |
 
+### 11. Browser Provider (`docs/guides/BrowserUsage.md`)
+
+| Feature | Doc Reference | Test(s) | Notes |
+| --- | --- | --- | --- |
+| BrowserBaseProvider construction | `BrowserUsage.md` | `test_browser_provider_config` | Config defaults, proxyUrl |
+| Fetch-based complete() | `BrowserUsage.md` | `test_browser_provider_complete` | Fetch API transport |
+| Streaming via ReadableStream | `BrowserUsage.md` | `test_browser_provider_stream` | ReadableStream SSE parsing |
+| CORS proxy URL prefixing | `BrowserUsage.md` | `test_browser_proxy_url_prefix` | proxyUrl prepended to API URL |
+| createBrowser() convenience | `BrowserUsage.md` | `test_create_browser` | Browser-optimized create() |
+
+### 12. Audio Interfaces (`docs/ConnectorInterfaces.md`)
+
+| Feature | Doc Reference | Test(s) | Notes |
+| --- | --- | --- | --- |
+| AudioRequest type | `ConnectorInterfaces.md` | `test_audio_request_creation` | Type construction, defaults |
+| AudioResponse type | `ConnectorInterfaces.md` | `test_audio_response_creation` | Type construction, defaults |
+| client.audio.speech.create() | `ConnectorCatalogue.md` | `test_audio_speech_create` | TTS routing through pool |
+| client.audio.transcriptions.create() | `ConnectorCatalogue.md` | `test_audio_transcriptions_create` | STT routing through pool |
+
+### 13. CDK Specialized Classes (`docs/cdk/BaseClasses.md`)
+
+| Feature | Doc Reference | Test(s) | Notes |
+| --- | --- | --- | --- |
+| ThresholdRotationPolicy | `BaseClasses.md` | `TestThresholdRotation` (in `test_specialized.py`) | Threshold-based deactivation/recovery |
+| ConsoleObservability | `BaseClasses.md` | `TestConsoleObservability` (in `test_specialized.py`) | ANSI output, severity filtering |
+| KeyValueStorage | `BaseClasses.md` | `TestKeyValueStorage` (in `test_specialized.py`) | Memory and file backends |
+| FileSecretStore | `BaseClasses.md` | `TestFileSecretStore` (in `test_specialized.py`) | .env, JSON, TOML file loading |
+| HttpHealthDiscovery | `BaseClasses.md` | -- | Requires HTTP mock; coverage gap |
+| CDK test helpers | `Helpers.md` | `TestConnectorTestHarness`, `TestMockHttpClient` (in `test_specialized.py`) | mockCompletionRequest, mockModelSnapshot, MockHttpClient, ConnectorTestHarness |
+
 ---
 
 ## Coverage Gaps
@@ -175,6 +227,8 @@ Correlates documented features with test coverage. Generated from the 356-test s
 | Webhook observability connector | Low | Documented in catalogue but not implemented |
 | HttpHealthDiscovery | Low | Specialized class exists but no dedicated test (requires HTTP mock) |
 | MetricsMixin | Low | Tested indirectly via provider tests |
+| Browser provider end-to-end (real fetch) | Low | Unit tests mock fetch; no integration test with actual browser |
+| Audio streaming (TTS binary stream) | Low | Audio types tested; binary stream end-to-end not yet covered |
 
 ---
 
@@ -201,3 +255,5 @@ Correlates documented features with test coverage. Generated from the 356-test s
 | `interfaces/SecretStore.md` | SecretStore ABC | `test_cdk.py::TestBaseSecretStore` (5 tests) | Direct |
 | `interfaces/Storage.md` | Storage ABC | `test_cdk.py::TestBaseStorage` (9 tests) | Direct |
 | `interfaces/Discovery.md` | Discovery ABC | *(no dedicated tests)* | Gap |
+| `guides/BrowserUsage.md` | BrowserBaseProvider, CORS proxy, createBrowser() | Browser provider tests | Direct |
+| `ConnectorInterfaces.md` (Audio) | AudioRequest, AudioResponse, audio namespace | Audio interface tests | Direct |