buildsol 0.1.1__tar.gz

buildsol-0.1.1/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+node_modules/
+dist/
+*.egg-info/
+*.tgz
+.env
+.env.*
+!.env.example
+.DS_Store

buildsol-0.1.1/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.1
+
+- Prepare npm and PyPI distribution with standard registry installation instructions.
+- No public API or runtime behavior changes from 0.1.0.
+
+## 0.1.0
+
+Initial Python and JavaScript/TypeScript SDK release:
+- Incremental TTS streaming and file downloads, with audio controls preserved.
+- Voice catalogue, consent-required cloning, deletion, controls, dialects and balance.
+- File transcription (JSON/SSE), live WebSocket transcription and translation.
+- Python sync/async clients; Node ESM/CommonJS and TypeScript declarations.
+- Typed API errors, timeouts, cancellation, safe retries and explicit idempotency.

buildsol-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sol
+
+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.

buildsol-0.1.1/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: buildsol
+Version: 0.1.1
+Summary: Official Sol SDK: streaming speech, voices, transcription and translation.
+Project-URL: Homepage, https://www.buildsol.ai
+Project-URL: Documentation, https://www.buildsol.ai/docs#sdks
+Project-URL: Repository, https://github.com/hectordiazgomez/sol-sdks
+Project-URL: Issues, https://github.com/hectordiazgomez/sol-sdks/issues
+Author: Sol
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: typing-extensions>=4.12
+Requires-Dist: websockets<18,>=14
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.14; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Requires-Dist: twine>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Sol Python SDK
+
+Official synchronous and asynchronous Python client. Requires Python 3.10+.
+
+## Install
+
+```sh
+python -m pip install buildsol
+```
+
+Install the official `buildsol` package from [PyPI](https://pypi.org/project/buildsol/). For development, clone this repository and run `pip install -e './python[dev]'`.
+
+Set `SOL_API_KEY` on your server, then:
+
+```python
+from buildsol import Sol
+
+with Sol() as sol:
+    voices = sol.voices.list(country="PE")
+    voice_id = voices["voices"][0]["id"]  # handle an empty catalogue in your app
+    with sol.speech.stream(
+        text="Hola, tu pedido llega mañana.", voice_id=voice_id, speed=1.0
+    ) as audio:
+        print(audio.request_id)
+        audio.save("speech.mp3")
+```
+
+`AudioStream` is an iterator of unchanged `bytes`. Always use its context manager so an early exit closes the connection. `speech.create()` returns `Audio` with `.content`, `.headers`, `.request_id` and `.save(path)` after downloading the full result. `reference_file=` supports multipart references; the JSON `reference_audio=` field is base64 text. Do not combine references with `voice_id`.
+
+## Async and incremental bytes
+
+```python
+import asyncio
+from buildsol import AsyncSol
+
+
+async def main():
+    async with AsyncSol() as sol:
+        async with sol.speech.stream(text="Buenos días.", output_format="pcm") as audio:
+            async for chunk in audio:
+                print(len(chunk))  # forward to your own compatible playback pipeline
+
+
+asyncio.run(main())
+```
+
+## Transcription, translation and voices
+
+```python
+from buildsol import Sol
+
+with Sol() as sol:
+    transcript = sol.transcriptions.create(
+        file="recording.wav",
+        language="es",
+        diarize=True,
+        transcription_style="verbatim",
+        idempotency_key="recording-2026-001",
+    )
+    print(transcript["text"], transcript["billing"])
+    translated = sol.translations.create(
+        text="Buenos días.",
+        source_language="es",
+        target_language="pt",
+        idempotency_key="translation-2026-001",
+    )
+    print(translated["translation"])
+    print(sol.controls.get(), sol.dialects.list(), sol.balance.get())
+
+    # Only with the speaker's permission; creates an account voice:
+    # voice = sol.voices.create(name="Mi voz", audio="reference.wav", consent=True)
+    # sol.voices.get(voice["voice"]["id"])
+    # sol.voices.delete(voice["voice"]["id"])  # irreversible
+```
+
+File inputs accept a path, `Path`, bytes (default filename `audio.wav`), an open binary file, `(filename, bytes)` or `(filename, bytes, content_type)`. Uploads are read into memory once, allowing safe idempotent replay of accepted small uploads. The SDK does not close caller-owned file objects.
+
+File SSE:
+
+```python
+with Sol() as sol:
+    with sol.transcriptions.stream(file="recording.wav", language="es") as events:
+        for event in events:
+            print(event)  # segment, metadata, completed; an error raises APIError
+```
+
+This does not make file transcription real-time. Use a live session for microphone input. See [live_python.py](https://github.com/hectordiazgomez/sol-sdks/blob/main/examples/live_python.py) for concurrent sending, real-time pacing and finalization. `LiveConnection` and `AsyncLiveConnection` can also consume a pre-issued single-use session. Live receive timeout defaults to 30 seconds; close the connection when done. No token is reused or reconnected automatically.
+
+## Configuration and errors
+
+```python
+from buildsol import Sol, APIError, ConnectionError, TimeoutError
+
+with Sol(timeout=120.0, max_retries=2) as sol:
+    try:
+        balance = sol.balance.get(timeout=15.0)
+    except APIError as error:
+        print(error.status_code, error.code, error.request_id)
+    except TimeoutError:
+        print("Request timed out")
+    except ConnectionError:
+        print("Connection interrupted")
+```
+
+Optional `api_key=`, `base_url=` and `http_client=` configure the client. HTTPX's timeout is a per-network-operation timeout (connect/read/write/pool), in seconds. Cancel an async task normally; `async with` releases resources. `AuthenticationError`, `PermissionDeniedError`, `NotFoundError` and `RateLimitError` subclass `APIError`; `.details` and `.headers` retain server information. `ProtocolError` reports malformed server events/JSON. Never log secrets or full audio.
+
+Retries are limited to GET or explicit-idempotency transcription/translation requests; **TTS is never automatically retried**. Partial-stream failures preserve the partial file and raise an error; the caller should remove or label incomplete files. See the repository README for full API coverage, limits, token rules and billing distinctions.

buildsol-0.1.1/README.md

@@ -0,0 +1,107 @@
+# Sol Python SDK
+
+Official synchronous and asynchronous Python client. Requires Python 3.10+.
+
+## Install
+
+```sh
+python -m pip install buildsol
+```
+
+Install the official `buildsol` package from [PyPI](https://pypi.org/project/buildsol/). For development, clone this repository and run `pip install -e './python[dev]'`.
+
+Set `SOL_API_KEY` on your server, then:
+
+```python
+from buildsol import Sol
+
+with Sol() as sol:
+    voices = sol.voices.list(country="PE")
+    voice_id = voices["voices"][0]["id"]  # handle an empty catalogue in your app
+    with sol.speech.stream(
+        text="Hola, tu pedido llega mañana.", voice_id=voice_id, speed=1.0
+    ) as audio:
+        print(audio.request_id)
+        audio.save("speech.mp3")
+```
+
+`AudioStream` is an iterator of unchanged `bytes`. Always use its context manager so an early exit closes the connection. `speech.create()` returns `Audio` with `.content`, `.headers`, `.request_id` and `.save(path)` after downloading the full result. `reference_file=` supports multipart references; the JSON `reference_audio=` field is base64 text. Do not combine references with `voice_id`.
+
+## Async and incremental bytes
+
+```python
+import asyncio
+from buildsol import AsyncSol
+
+
+async def main():
+    async with AsyncSol() as sol:
+        async with sol.speech.stream(text="Buenos días.", output_format="pcm") as audio:
+            async for chunk in audio:
+                print(len(chunk))  # forward to your own compatible playback pipeline
+
+
+asyncio.run(main())
+```
+
+## Transcription, translation and voices
+
+```python
+from buildsol import Sol
+
+with Sol() as sol:
+    transcript = sol.transcriptions.create(
+        file="recording.wav",
+        language="es",
+        diarize=True,
+        transcription_style="verbatim",
+        idempotency_key="recording-2026-001",
+    )
+    print(transcript["text"], transcript["billing"])
+    translated = sol.translations.create(
+        text="Buenos días.",
+        source_language="es",
+        target_language="pt",
+        idempotency_key="translation-2026-001",
+    )
+    print(translated["translation"])
+    print(sol.controls.get(), sol.dialects.list(), sol.balance.get())
+
+    # Only with the speaker's permission; creates an account voice:
+    # voice = sol.voices.create(name="Mi voz", audio="reference.wav", consent=True)
+    # sol.voices.get(voice["voice"]["id"])
+    # sol.voices.delete(voice["voice"]["id"])  # irreversible
+```
+
+File inputs accept a path, `Path`, bytes (default filename `audio.wav`), an open binary file, `(filename, bytes)` or `(filename, bytes, content_type)`. Uploads are read into memory once, allowing safe idempotent replay of accepted small uploads. The SDK does not close caller-owned file objects.
+
+File SSE:
+
+```python
+with Sol() as sol:
+    with sol.transcriptions.stream(file="recording.wav", language="es") as events:
+        for event in events:
+            print(event)  # segment, metadata, completed; an error raises APIError
+```
+
+This does not make file transcription real-time. Use a live session for microphone input. See [live_python.py](https://github.com/hectordiazgomez/sol-sdks/blob/main/examples/live_python.py) for concurrent sending, real-time pacing and finalization. `LiveConnection` and `AsyncLiveConnection` can also consume a pre-issued single-use session. Live receive timeout defaults to 30 seconds; close the connection when done. No token is reused or reconnected automatically.
+
+## Configuration and errors
+
+```python
+from buildsol import Sol, APIError, ConnectionError, TimeoutError
+
+with Sol(timeout=120.0, max_retries=2) as sol:
+    try:
+        balance = sol.balance.get(timeout=15.0)
+    except APIError as error:
+        print(error.status_code, error.code, error.request_id)
+    except TimeoutError:
+        print("Request timed out")
+    except ConnectionError:
+        print("Connection interrupted")
+```
+
+Optional `api_key=`, `base_url=` and `http_client=` configure the client. HTTPX's timeout is a per-network-operation timeout (connect/read/write/pool), in seconds. Cancel an async task normally; `async with` releases resources. `AuthenticationError`, `PermissionDeniedError`, `NotFoundError` and `RateLimitError` subclass `APIError`; `.details` and `.headers` retain server information. `ProtocolError` reports malformed server events/JSON. Never log secrets or full audio.
+
+Retries are limited to GET or explicit-idempotency transcription/translation requests; **TTS is never automatically retried**. Partial-stream failures preserve the partial file and raise an error; the caller should remove or label incomplete files. See the repository README for full API coverage, limits, token rules and billing distinctions.

buildsol-0.1.1/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+[project]
+name = "buildsol"
+version = "0.1.1"
+description = "Official Sol SDK: streaming speech, voices, transcription and translation."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{name = "Sol"}]
+dependencies = ["httpx>=0.27,<1", "websockets>=14,<18", "typing-extensions>=4.12"]
+classifiers = ["Programming Language :: Python :: 3", "Typing :: Typed", "Operating System :: OS Independent"]
+[project.urls]
+Homepage = "https://www.buildsol.ai"
+Documentation = "https://www.buildsol.ai/docs#sdks"
+Repository = "https://github.com/hectordiazgomez/sol-sdks"
+Issues = "https://github.com/hectordiazgomez/sol-sdks/issues"
+[tool.hatch.build.targets.wheel]
+packages = ["src/buildsol"]
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "build>=1.2", "twine>=6", "ruff>=0.9", "mypy>=1.14"]
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

buildsol-0.1.1/src/buildsol/__init__.py

@@ -0,0 +1,37 @@
+"""Official Sol Python SDK. Keep your API key on your server."""
+
+from ._transport import VERSION as __version__
+from .audio import AsyncAudioStream, Audio, AudioStream
+from .client import AsyncSol, Sol
+from .errors import (
+    APIError,
+    AuthenticationError,
+    ConnectionError,
+    NotFoundError,
+    PermissionDeniedError,
+    ProtocolError,
+    RateLimitError,
+    SolError,
+    TimeoutError,
+)
+from .live import AsyncLiveConnection, LiveConnection
+
+__all__ = [
+    "Sol",
+    "AsyncSol",
+    "Audio",
+    "AudioStream",
+    "AsyncAudioStream",
+    "SolError",
+    "APIError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "RateLimitError",
+    "ConnectionError",
+    "TimeoutError",
+    "ProtocolError",
+    "LiveConnection",
+    "AsyncLiveConnection",
+    "__version__",
+]

buildsol-0.1.1/src/buildsol/_async_resources.py

@@ -0,0 +1,254 @@
+from contextlib import asynccontextmanager
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+from typing_extensions import Unpack
+
+from ._transport import Transport, event, form, transport_error, upload
+from .audio import AsyncAudioStream, Audio
+from .types import (
+    Balance,
+    LiveSession,
+    SpeechParams,
+    Transcription,
+    TranscriptionParams,
+    Translation,
+    Upload,
+    VoiceList,
+    VoiceParams,
+    VoiceResult,
+)
+
+
+class Resource:
+    def __init__(self, transport: Transport):
+        self._t = transport
+
+
+class Speech(Resource):
+    @asynccontextmanager
+    async def stream(
+        self,
+        *,
+        reference_file: Upload | None = None,
+        timeout: float | None = None,
+        **params: Unpack[SpeechParams],
+    ):
+        kwargs = (
+            {"json": params}
+            if reference_file is None
+            else {
+                "data": form(params),
+                "files": {"reference_audio": upload(reference_file)},
+            }
+        )
+        response = await self._t.arequest(
+            "POST", "/v1/text-to-speech", timeout=timeout, **kwargs
+        )
+        try:
+            yield AsyncAudioStream(response)
+        finally:
+            await response.aclose()
+
+    async def create(
+        self,
+        *,
+        reference_file: Upload | None = None,
+        timeout: float | None = None,
+        **params: Unpack[SpeechParams],
+    ) -> Audio:
+        async with self.stream(
+            reference_file=reference_file, timeout=timeout, **params
+        ) as stream:
+            content = b"".join([chunk async for chunk in stream])
+            return Audio(content, stream.headers)
+
+
+class Voices(Resource):
+    async def list(
+        self,
+        *,
+        country: str | None = None,
+        gender: str | None = None,
+        age: str | None = None,
+        category: str | None = None,
+        timeout: float | None = None,
+    ) -> VoiceList:
+        return await self._t.ajson(
+            "GET",
+            "/v1/voices",
+            params=form(
+                {"country": country, "gender": gender, "age": age, "category": category}
+            ),
+            timeout=timeout,
+        )
+
+    async def get(self, voice_id: str, *, timeout: float | None = None) -> VoiceResult:
+        return await self._t.ajson(
+            "GET", "/v1/voices/" + quote(voice_id, safe=""), timeout=timeout
+        )
+
+    async def create(
+        self,
+        *,
+        name: str,
+        audio: Upload,
+        consent: bool,
+        timeout: float | None = None,
+        **params: Unpack[VoiceParams],
+    ) -> VoiceResult:
+        return await self._t.ajson(
+            "POST",
+            "/v1/voices",
+            data=form({"name": name, "consent": consent, **params}),
+            files={"audio": upload(audio)},
+            timeout=timeout,
+        )
+
+    async def delete(
+        self, voice_id: str, *, timeout: float | None = None
+    ) -> dict[str, bool]:
+        return await self._t.ajson(
+            "DELETE", "/v1/voices/" + quote(voice_id, safe=""), timeout=timeout
+        )
+
+
+class Controls(Resource):
+    async def get(self, *, timeout: float | None = None) -> dict[str, Any]:
+        return await self._t.ajson("GET", "/v1/tts/controls", timeout=timeout)
+
+
+class Dialects(Resource):
+    async def list(self, *, timeout: float | None = None) -> dict[str, Any]:
+        return await self._t.ajson("GET", "/v1/dialects", timeout=timeout)
+
+
+class BalanceResource(Resource):
+    async def get(self, *, timeout: float | None = None) -> Balance:
+        return await self._t.ajson("GET", "/v1/balance", timeout=timeout)
+
+
+class Transcriptions(Resource):
+    async def create(
+        self,
+        *,
+        file: Upload,
+        idempotency_key: str | None = None,
+        timeout: float | None = None,
+        **params: Unpack[TranscriptionParams],
+    ) -> Transcription:
+        return await self._t.ajson(
+            "POST",
+            "/v1/audio/transcriptions",
+            data=form(params),
+            files={"file": upload(file)},
+            idempotency_key=idempotency_key,
+            timeout=timeout,
+        )
+
+    @asynccontextmanager
+    async def stream(
+        self,
+        *,
+        file: Upload,
+        idempotency_key: str | None = None,
+        timeout: float | None = None,
+        **params: Unpack[TranscriptionParams],
+    ):
+        """SSE transport for a processed file; use live.connect for real-time audio."""
+        response = await self._t.arequest(
+            "POST",
+            "/v1/audio/transcriptions",
+            data=form({**params, "stream": True}),
+            files={"file": upload(file)},
+            idempotency_key=idempotency_key,
+            timeout=timeout,
+        )
+        try:
+            yield _sse(response)
+        finally:
+            await response.aclose()
+
+
+class Translations(Resource):
+    async def create(
+        self,
+        *,
+        text: str,
+        source_language: str,
+        target_language: str,
+        model: str = "sol-v1-preview-translate",
+        idempotency_key: str | None = None,
+        timeout: float | None = None,
+    ) -> Translation:
+        return await self._t.ajson(
+            "POST",
+            "/v1/translate",
+            json={
+                "text": text,
+                "source_language": source_language,
+                "target_language": target_language,
+                "model": model,
+            },
+            idempotency_key=idempotency_key,
+            timeout=timeout,
+        )
+
+
+class Live(Resource):
+    async def create_session(
+        self,
+        *,
+        language: str | None = None,
+        model: str = "sol-transcribe-v1",
+        timeout: float | None = None,
+    ) -> LiveSession:
+        return await self._t.ajson(
+            "POST",
+            "/v1/audio/transcription-sessions",
+            json=form({"model": model, "language": language}),
+            timeout=timeout,
+        )
+
+    @asynccontextmanager
+    async def connect(
+        self,
+        *,
+        session: LiveSession | None = None,
+        language: str | None = None,
+        timeout: float = 30,
+    ):
+        from .live import AsyncLiveConnection
+
+        session = session or await self.create_session(
+            language=language, timeout=timeout
+        )
+        connection = AsyncLiveConnection(session, timeout=timeout)
+        async with connection:
+            yield connection
+
+
+async def _sse(response):
+    data = []
+    completed = False
+    try:
+        async for line in response.aiter_lines():
+            if line == "":
+                if data:
+                    value = event("\n".join(data))
+                    completed |= value.get("type") == "completed"
+                    yield value
+                    data = []
+            elif line.startswith("data:"):
+                data.append(line[5:].removeprefix(" "))
+        if data:
+            value = event("\n".join(data))
+            completed |= value.get("type") == "completed"
+            yield value
+        if not completed:
+            from .errors import ProtocolError
+
+            raise ProtocolError("Transcription stream ended without a completed event")
+    except httpx.TransportError as exc:
+        raise transport_error(exc) from exc