langchain-flowspeech 0.1.0__tar.gz

langchain_flowspeech-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package
+        run: python -m pip install -e ".[test]"
+      - name: Run tests
+        run: python -m pytest
+

langchain_flowspeech-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build package
+        run: |
+          python -m pip install build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

langchain_flowspeech-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+.pytest_cache/
+__pycache__/
+*.egg-info/
+build/
+dist/
+*.pyc
+.env
+.env.*
+

langchain_flowspeech-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FlowSpeech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

langchain_flowspeech-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: langchain-flowspeech
+Version: 0.1.0
+Summary: LangChain tools for FlowSpeech text-to-speech generation.
+Project-URL: Homepage, https://flowspeech.io/
+Project-URL: Documentation, https://flowspeech.io/docs
+Project-URL: Source, https://github.com/waeckerlinfederowicz66-sketch/langchain-flowspeech
+Project-URL: Issues, https://github.com/waeckerlinfederowicz66-sketch/langchain-flowspeech/issues
+Author-email: FlowSpeech <support@flowspeech.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-voice,flowspeech,langchain,text-to-speech,tts
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: langchain-core<2.0,>=0.3
+Requires-Dist: pydantic<3,>=2
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: respx>=0.21; extra == 'test'
+Description-Content-Type: text/markdown
+
+# langchain-flowspeech
+
+`langchain-flowspeech` provides LangChain tools for generating text-to-speech audio with [FlowSpeech](https://flowspeech.io/).
+
+FlowSpeech is a context-aware text-to-speech service for human-like narration with emotion control, pause control, and multi-speaker voice configuration.
+
+## Installation
+
+```bash
+pip install langchain-flowspeech
+```
+
+## Authentication
+
+Create a FlowSpeech API key in your FlowSpeech account, then export it:
+
+```bash
+export FLOWSPEECH_API_KEY="..."
+```
+
+Do not commit API keys, cookies, session tokens, or provider credentials.
+
+## Usage
+
+```python
+from langchain_flowspeech import FlowSpeechTextToSpeechTool
+
+tool = FlowSpeechTextToSpeechTool()
+
+result = tool.invoke({
+    "text": "Welcome to FlowSpeech. This audio is generated from a LangChain tool.",
+    "voice_name": "Kore",
+    "output_path": "flowspeech-demo.wav",
+})
+
+print(result["output_path"])
+print(result["mime_type"])
+print(result["quota"])
+```
+
+## Multi-Speaker Speech
+
+```python
+from langchain_flowspeech import FlowSpeechSpeaker, FlowSpeechTextToSpeechTool
+
+tool = FlowSpeechTextToSpeechTool()
+
+result = tool.invoke({
+    "text": "Speaker A: We can make this sound natural.\nSpeaker B: Great, let's use different voices.",
+    "speakers": [
+        FlowSpeechSpeaker(speaker="Speaker A", voice_name="Kore"),
+        FlowSpeechSpeaker(speaker="Speaker B", voice_name="Puck"),
+    ],
+    "output_path": "conversation.wav",
+})
+```
+
+## API Surface
+
+The package uses the public FlowSpeech API:
+
+- `GET /api/ai/text-to-speech/quota`
+- `POST /api/ai/text-to-speech`
+
+Responses include base64-encoded audio and metadata such as MIME type, sample rate, channel count, bit depth, and quota information.
+
+## Development
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e ".[test]"
+pytest
+```
+
+## Publishing
+
+This project is ready for PyPI packaging. Build locally with:
+
+```bash
+python -m pip install build
+python -m build
+```
+
+For GitHub Actions trusted publishing, configure a PyPI trusted publisher for `waeckerlinfederowicz66-sketch/langchain-flowspeech`, then add a publishing workflow with `id-token: write`.
+
+## Safety
+
+This repository intentionally contains no secrets. Tests use mocked HTTP responses.

langchain_flowspeech-0.1.0/README.md

@@ -0,0 +1,89 @@
+# langchain-flowspeech
+
+`langchain-flowspeech` provides LangChain tools for generating text-to-speech audio with [FlowSpeech](https://flowspeech.io/).
+
+FlowSpeech is a context-aware text-to-speech service for human-like narration with emotion control, pause control, and multi-speaker voice configuration.
+
+## Installation
+
+```bash
+pip install langchain-flowspeech
+```
+
+## Authentication
+
+Create a FlowSpeech API key in your FlowSpeech account, then export it:
+
+```bash
+export FLOWSPEECH_API_KEY="..."
+```
+
+Do not commit API keys, cookies, session tokens, or provider credentials.
+
+## Usage
+
+```python
+from langchain_flowspeech import FlowSpeechTextToSpeechTool
+
+tool = FlowSpeechTextToSpeechTool()
+
+result = tool.invoke({
+    "text": "Welcome to FlowSpeech. This audio is generated from a LangChain tool.",
+    "voice_name": "Kore",
+    "output_path": "flowspeech-demo.wav",
+})
+
+print(result["output_path"])
+print(result["mime_type"])
+print(result["quota"])
+```
+
+## Multi-Speaker Speech
+
+```python
+from langchain_flowspeech import FlowSpeechSpeaker, FlowSpeechTextToSpeechTool
+
+tool = FlowSpeechTextToSpeechTool()
+
+result = tool.invoke({
+    "text": "Speaker A: We can make this sound natural.\nSpeaker B: Great, let's use different voices.",
+    "speakers": [
+        FlowSpeechSpeaker(speaker="Speaker A", voice_name="Kore"),
+        FlowSpeechSpeaker(speaker="Speaker B", voice_name="Puck"),
+    ],
+    "output_path": "conversation.wav",
+})
+```
+
+## API Surface
+
+The package uses the public FlowSpeech API:
+
+- `GET /api/ai/text-to-speech/quota`
+- `POST /api/ai/text-to-speech`
+
+Responses include base64-encoded audio and metadata such as MIME type, sample rate, channel count, bit depth, and quota information.
+
+## Development
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e ".[test]"
+pytest
+```
+
+## Publishing
+
+This project is ready for PyPI packaging. Build locally with:
+
+```bash
+python -m pip install build
+python -m build
+```
+
+For GitHub Actions trusted publishing, configure a PyPI trusted publisher for `waeckerlinfederowicz66-sketch/langchain-flowspeech`, then add a publishing workflow with `id-token: write`.
+
+## Safety
+
+This repository intentionally contains no secrets. Tests use mocked HTTP responses.

langchain_flowspeech-0.1.0/docs/langchain/flowspeech.mdx

@@ -0,0 +1,62 @@
+# FlowSpeech
+
+[FlowSpeech](https://flowspeech.io/) is a context-aware text-to-speech service for generating human-like narration with voice, emotion, pause, and multi-speaker controls.
+
+This package provides a LangChain tool that calls the FlowSpeech text-to-speech API and saves the generated audio to a local WAV file.
+
+## Installation
+
+```bash
+pip install langchain-flowspeech
+```
+
+## Credentials
+
+Create a FlowSpeech API key in your FlowSpeech account and set it as an environment variable:
+
+```bash
+export FLOWSPEECH_API_KEY="..."
+```
+
+## Instantiation
+
+```python
+from langchain_flowspeech import FlowSpeechTextToSpeechTool
+
+tool = FlowSpeechTextToSpeechTool()
+```
+
+## Invocation
+
+```python
+result = tool.invoke({
+    "text": "Generate natural speech from a LangChain tool.",
+    "voice_name": "Kore",
+    "output_path": "flowspeech-demo.wav",
+})
+
+print(result["output_path"])
+```
+
+## Multi-Speaker Invocation
+
+```python
+from langchain_flowspeech import FlowSpeechSpeaker, FlowSpeechTextToSpeechTool
+
+tool = FlowSpeechTextToSpeechTool()
+
+result = tool.invoke({
+    "text": "Speaker A: We can make this sound natural.\nSpeaker B: Great, let's use different voices.",
+    "speakers": [
+        FlowSpeechSpeaker(speaker="Speaker A", voice_name="Kore"),
+        FlowSpeechSpeaker(speaker="Speaker B", voice_name="Puck"),
+    ],
+    "output_path": "conversation.wav",
+})
+```
+
+## API Reference
+
+- `FlowSpeechTextToSpeechTool`
+- `FlowSpeechClient`
+- `FlowSpeechSpeaker`

langchain_flowspeech-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-flowspeech"
+version = "0.1.0"
+description = "LangChain tools for FlowSpeech text-to-speech generation."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "FlowSpeech", email = "support@flowspeech.io" }
+]
+keywords = ["flowspeech", "langchain", "text-to-speech", "tts", "ai-voice"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Multimedia :: Sound/Audio :: Speech",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "httpx>=0.27",
+  "langchain-core>=0.3,<2.0",
+  "pydantic>=2,<3",
+]
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8",
+  "respx>=0.21",
+]
+
+[project.urls]
+Homepage = "https://flowspeech.io/"
+Documentation = "https://flowspeech.io/docs"
+Source = "https://github.com/waeckerlinfederowicz66-sketch/langchain-flowspeech"
+Issues = "https://github.com/waeckerlinfederowicz66-sketch/langchain-flowspeech/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/langchain_flowspeech"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

langchain_flowspeech-0.1.0/src/langchain_flowspeech/__init__.py

@@ -0,0 +1,17 @@
+from langchain_flowspeech.client import (
+    FlowSpeechApiError,
+    FlowSpeechClient,
+    FlowSpeechQuota,
+    FlowSpeechSpeaker,
+    FlowSpeechTtsResult,
+)
+from langchain_flowspeech.tools import FlowSpeechTextToSpeechTool
+
+__all__ = [
+    "FlowSpeechApiError",
+    "FlowSpeechClient",
+    "FlowSpeechQuota",
+    "FlowSpeechSpeaker",
+    "FlowSpeechTextToSpeechTool",
+    "FlowSpeechTtsResult",
+]

langchain_flowspeech-0.1.0/src/langchain_flowspeech/client.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import base64
+import os
+from pathlib import Path
+from typing import Any
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class FlowSpeechApiError(RuntimeError):
+    """Raised when the FlowSpeech API returns an error response."""
+
+    def __init__(self, message: str, *, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class FlowSpeechSpeaker(BaseModel):
+    """Voice assignment for a single-speaker or multi-speaker request."""
+
+    speaker: str | None = Field(default=None, description="Speaker label in the input text.")
+    voice_name: str = Field(default="Kore", description="FlowSpeech voice name.")
+
+    def to_api(self) -> dict[str, str]:
+        payload = {"voiceName": self.voice_name}
+        if self.speaker:
+            payload["speaker"] = self.speaker
+        return payload
+
+
+class FlowSpeechQuota(BaseModel):
+    limit: int | None = None
+    used: int | None = None
+    remaining: int | None = None
+    reset_at: str | None = Field(default=None, alias="resetAt")
+    is_guest: bool | None = Field(default=None, alias="isGuest")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class FlowSpeechTtsResult(BaseModel):
+    audio_base64: str = Field(alias="audioBase64")
+    mime_type: str | None = Field(default=None, alias="mimeType")
+    quota: FlowSpeechQuota | None = None
+    sample_rate: int | None = Field(default=None, alias="sampleRate")
+    num_channels: int | None = Field(default=None, alias="numChannels")
+    bits_per_sample: int | None = Field(default=None, alias="bitsPerSample")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    @property
+    def audio_bytes(self) -> bytes:
+        return base64.b64decode(self.audio_base64)
+
+    def save(self, path: str | Path) -> Path:
+        output_path = Path(path)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_bytes(self.audio_bytes)
+        return output_path
+
+
+class FlowSpeechClient:
+    """Small HTTP client for the public FlowSpeech text-to-speech API."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str = "https://flowspeech.io",
+        timeout: float = 80.0,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self.api_key = api_key or os.getenv("FLOWSPEECH_API_KEY")
+        if not self.api_key:
+            raise FlowSpeechApiError(
+                "FlowSpeech API key is required. Set FLOWSPEECH_API_KEY or pass api_key."
+            )
+        self.base_url = base_url.rstrip("/")
+        self._client = http_client or httpx.Client(timeout=timeout)
+        self._owns_client = http_client is None
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "FlowSpeechClient":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": "langchain-flowspeech/0.1.0",
+        }
+
+    def check_quota(self) -> FlowSpeechQuota:
+        response = self._client.get(
+            f"{self.base_url}/api/ai/text-to-speech/quota",
+            headers=self._headers(),
+        )
+        payload = self._read_response(response)
+        quota = payload.get("data", {}).get("quota")
+        if not isinstance(quota, dict):
+            raise FlowSpeechApiError("FlowSpeech quota response did not include quota data.")
+        return FlowSpeechQuota.model_validate(quota)
+
+    def generate_speech(
+        self,
+        *,
+        text: str,
+        speakers: list[FlowSpeechSpeaker] | None = None,
+        voice_name: str = "Kore",
+        original_text: str | None = None,
+    ) -> FlowSpeechTtsResult:
+        if not text.strip():
+            raise ValueError("text must not be empty")
+
+        speaker_payload = speakers or [FlowSpeechSpeaker(voice_name=voice_name)]
+        response = self._client.post(
+            f"{self.base_url}/api/ai/text-to-speech",
+            headers=self._headers(),
+            json={
+                "text": text,
+                "originalText": original_text or text,
+                "speakers": [speaker.to_api() for speaker in speaker_payload],
+            },
+        )
+        payload = self._read_response(response)
+        data = payload.get("data")
+        if not isinstance(data, dict) or not data.get("audioBase64"):
+            raise FlowSpeechApiError("FlowSpeech response did not include audioBase64.")
+        return FlowSpeechTtsResult.model_validate(data)
+
+    @staticmethod
+    def _read_response(response: httpx.Response) -> dict[str, Any]:
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise FlowSpeechApiError(
+                "FlowSpeech API returned a non-JSON response.",
+                status_code=response.status_code,
+            ) from exc
+
+        if response.status_code >= 400:
+            message = payload.get("message") if isinstance(payload, dict) else None
+            raise FlowSpeechApiError(
+                message or f"FlowSpeech API returned HTTP {response.status_code}.",
+                status_code=response.status_code,
+            )
+
+        if not isinstance(payload, dict) or payload.get("code") != 0:
+            message = payload.get("message") if isinstance(payload, dict) else None
+            raise FlowSpeechApiError(message or "FlowSpeech API returned an error.")
+
+        return payload

langchain_flowspeech-0.1.0/src/langchain_flowspeech/tools.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Type
+
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field, PrivateAttr
+
+from langchain_flowspeech.client import FlowSpeechClient, FlowSpeechSpeaker
+
+
+class FlowSpeechTextToSpeechInput(BaseModel):
+    text: str = Field(description="Text or speaker-labelled dialogue to synthesize.")
+    voice_name: str = Field(default="Kore", description="Default FlowSpeech voice name.")
+    speakers: list[FlowSpeechSpeaker] | None = Field(
+        default=None,
+        description="Optional explicit speaker-to-voice assignments for dialogue.",
+    )
+    output_path: str = Field(
+        default="flowspeech-output.wav",
+        description="Local path where the generated WAV audio should be saved.",
+    )
+
+
+class FlowSpeechTextToSpeechTool(BaseTool):
+    """LangChain tool that generates speech audio with FlowSpeech."""
+
+    name: str = "flowspeech_text_to_speech"
+    description: str = (
+        "Generate human-like text-to-speech audio with FlowSpeech and save it as a WAV file."
+    )
+    args_schema: Type[BaseModel] = FlowSpeechTextToSpeechInput
+
+    api_key: str | None = Field(default=None, exclude=True)
+    base_url: str = "https://flowspeech.io"
+    timeout: float = 80.0
+
+    _client: FlowSpeechClient | None = PrivateAttr(default=None)
+
+    def _get_client(self) -> FlowSpeechClient:
+        if self._client is None:
+            self._client = FlowSpeechClient(
+                api_key=self.api_key,
+                base_url=self.base_url,
+                timeout=self.timeout,
+            )
+        return self._client
+
+    def _run(
+        self,
+        text: str,
+        voice_name: str = "Kore",
+        speakers: list[FlowSpeechSpeaker] | None = None,
+        output_path: str = "flowspeech-output.wav",
+        **_: Any,
+    ) -> dict[str, Any]:
+        result = self._get_client().generate_speech(
+            text=text,
+            voice_name=voice_name,
+            speakers=speakers,
+        )
+        saved_path = result.save(output_path)
+        return {
+            "output_path": str(Path(saved_path)),
+            "mime_type": result.mime_type,
+            "sample_rate": result.sample_rate,
+            "num_channels": result.num_channels,
+            "bits_per_sample": result.bits_per_sample,
+            "quota": result.quota.model_dump(by_alias=True) if result.quota else None,
+        }
+
+    async def _arun(self, *_: Any, **__: Any) -> dict[str, Any]:
+        raise NotImplementedError("FlowSpeechTextToSpeechTool currently supports sync use.")

langchain_flowspeech-0.1.0/tests/test_client.py

@@ -0,0 +1,89 @@
+import base64
+
+import httpx
+import pytest
+
+from langchain_flowspeech import FlowSpeechApiError, FlowSpeechClient, FlowSpeechSpeaker
+
+
+def test_generate_speech_sends_public_api_shape() -> None:
+    captured = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["url"] = str(request.url)
+        captured["auth"] = request.headers.get("authorization")
+        captured["json"] = request.read().decode()
+        return httpx.Response(
+            200,
+            json={
+                "code": 0,
+                "message": "ok",
+                "data": {
+                    "audioBase64": base64.b64encode(b"RIFFdemo").decode(),
+                    "mimeType": "audio/L16;rate=24000",
+                    "sampleRate": 24000,
+                    "numChannels": 1,
+                    "bitsPerSample": 16,
+                    "quota": {
+                        "limit": 10000,
+                        "used": 10,
+                        "remaining": 9990,
+                        "resetAt": "2026-07-31T15:59:59.999Z",
+                        "isGuest": False,
+                    },
+                },
+            },
+        )
+
+    transport = httpx.MockTransport(handler)
+    with httpx.Client(transport=transport) as http_client:
+        client = FlowSpeechClient(
+            api_key="test-key",
+            base_url="https://flowspeech.io",
+            http_client=http_client,
+        )
+        result = client.generate_speech(
+            text="Speaker A: Hello",
+            speakers=[FlowSpeechSpeaker(speaker="Speaker A", voice_name="Kore")],
+        )
+
+    assert captured["url"] == "https://flowspeech.io/api/ai/text-to-speech"
+    assert captured["auth"] == "Bearer test-key"
+    assert '"originalText":"Speaker A: Hello"' in captured["json"]
+    assert '"speaker":"Speaker A"' in captured["json"]
+    assert result.audio_bytes == b"RIFFdemo"
+    assert result.quota is not None
+    assert result.quota.remaining == 9990
+
+
+def test_check_quota() -> None:
+    def handler(_: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            json={
+                "code": 0,
+                "data": {
+                    "quota": {
+                        "limit": 100,
+                        "used": 25,
+                        "remaining": 75,
+                        "resetAt": "2026-07-31T15:59:59.999Z",
+                        "isGuest": False,
+                    }
+                },
+            },
+        )
+
+    with httpx.Client(transport=httpx.MockTransport(handler)) as http_client:
+        client = FlowSpeechClient(api_key="test-key", http_client=http_client)
+        quota = client.check_quota()
+
+    assert quota.limit == 100
+    assert quota.remaining == 75
+
+
+def test_requires_api_key(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("FLOWSPEECH_API_KEY", raising=False)
+
+    with pytest.raises(FlowSpeechApiError, match="API key is required"):
+        FlowSpeechClient()

langchain_flowspeech-0.1.0/tests/test_tools.py

@@ -0,0 +1,36 @@
+import base64
+
+import httpx
+
+from langchain_flowspeech.client import FlowSpeechClient
+from langchain_flowspeech.tools import FlowSpeechTextToSpeechTool
+
+
+def test_tool_saves_audio(tmp_path) -> None:
+    def handler(_: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            json={
+                "code": 0,
+                "data": {
+                    "audioBase64": base64.b64encode(b"RIFFtool").decode(),
+                    "mimeType": "audio/L16;rate=24000",
+                    "sampleRate": 24000,
+                    "numChannels": 1,
+                    "bitsPerSample": 16,
+                },
+            },
+        )
+
+    output_path = tmp_path / "speech.wav"
+    tool = FlowSpeechTextToSpeechTool(api_key="test-key")
+    tool._client = FlowSpeechClient(
+        api_key="test-key",
+        http_client=httpx.Client(transport=httpx.MockTransport(handler)),
+    )
+
+    result = tool.invoke({"text": "Hello from FlowSpeech", "output_path": str(output_path)})
+
+    assert output_path.read_bytes() == b"RIFFtool"
+    assert result["output_path"] == str(output_path)
+    assert result["sample_rate"] == 24000