Metadata-Version: 2.5
Name: lokutor-haystack
Version: 0.1.0
Summary: Lokutor text-to-speech and speech-to-text components for Haystack
Project-URL: Homepage, https://lokutor.com
Project-URL: Documentation, https://docs.lokutor.com
Project-URL: Source, https://github.com/lokutor-ai/lokutor-haystack
Project-URL: Issues, https://github.com/lokutor-ai/lokutor-haystack/issues
Author-email: Lokutor AI <contact@lokutor.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: haystack,lokutor,speech-to-text,stt,text-to-speech,tts
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Requires-Dist: haystack-ai>=2.10.0
Requires-Dist: httpx>=0.25
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Description-Content-Type: text/markdown

# lokutor-haystack

[Lokutor](https://lokutor.com) text-to-speech and speech-to-text components for [Haystack](https://haystack.deepset.ai) 2.x.

- `LokutorTextToSpeech`: text to a WAV `ByteStream` (Versa 2.0; voices `F1`-`F5`, `M1`-`M5`, your cloned voices; `en es ca gl eu pt fr it de`).
- `LokutorSpeechToText`: WAV files to `Document`s (Conv 2.0), with optional speaker diarization and word timings.

Get an API key at [app.lokutor.com](https://app.lokutor.com). API docs: [docs.lokutor.com](https://docs.lokutor.com).

## Installation

```bash
pip install lokutor-haystack
```

The key is read from the `LOKUTOR_API_KEY` environment variable (a Haystack `Secret`, so it is never serialized into a pipeline YAML).

## Text to speech

```python
from pathlib import Path
from haystack_integrations.components.audio.lokutor import LokutorTextToSpeech

tts = LokutorTextToSpeech(voice="F1", language="en")
audio = tts.run(text="Hello from Lokutor. [laugh]")["audio"]   # ByteStream, mime_type "audio/wav"
audio.to_file(Path("hello.wav"))
```

`run` also takes `voice` and `language` to override the init values; `run_async` is available. The text may carry [expression tags](https://docs.lokutor.com/api-reference/expression-tags). Limit: 5,000 characters per call. Output is 16-bit PCM, 44.1 kHz, mono WAV.

## Speech to text

```python
from haystack_integrations.components.audio.lokutor import LokutorSpeechToText

stt = LokutorSpeechToText(language="en", diarize=True, include_words=True)
docs = stt.run(sources=["meeting.wav"])["documents"]
print(docs[0].content, docs[0].meta["speakers"])
```

One `Document` per source (paths or `ByteStream`s); `meta` has `file_path`, `language_code`, and with `diarize` the `speakers`, with `include_words` the per-word `words`. **Lokutor decodes WAV only** (PCM 8/16 bit, 8-48 kHz): convert MP3/M4A first. Speaker labels are best on English meetings; short interjections and overlapping speech are less reliable ([details](https://docs.lokutor.com/api-reference/speech-to-text)).

An unreadable file is logged and skipped; an API error (bad key, unsupported audio, no balance) raises `RuntimeError` with Lokutor's message.

## Example pipelines

[`examples/pipeline.py`](examples/pipeline.py) synthesizes a sentence, transcribes the result and indexes the transcript in a document store.

## Development

```bash
pip install -e ".[test]" && pytest                       # unit tests, no network
LOKUTOR_API_KEY=... pytest -m integration                # one tiny live round trip
```

## Licence

Apache-2.0.
