> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lokutor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python Quickstart

> Python quickstart: install lokutor, synthesize speech to a WAV file or the speakers, run a voice agent through the microphone, register callbacks, and handle tool calls.

## Installation

Python 3.8 or later.

```bash theme={null}
pip install "lokutor[audio]"   # includes PyAudio for the speakers and microphone used below
```

PyAudio needs PortAudio: `brew install portaudio` (macOS) or `sudo apt install portaudio19-dev` (Debian/Ubuntu). Without local audio, `pip install lokutor` is enough.

```bash theme={null}
export LOKUTOR_API_KEY=sk_your_key_here
```

## TTS to a WAV file

```python theme={null}
import os
import wave
from lokutor import TTSClient, VoiceStyle, Language

client = TTSClient(api_key=os.environ["LOKUTOR_API_KEY"])
chunks = []

client.synthesize(
    text="Hello from Lokutor.",
    voice=VoiceStyle.F1,
    language=Language.ENGLISH,
    on_audio=chunks.append,
    play=False,
    block=True,
)

with wave.open("hello.wav", "wb") as f:
    f.setnchannels(1)
    f.setsampwidth(2)
    f.setframerate(44100)
    f.writeframes(b"".join(chunks))
```

Use `play=True` instead to hear it through your speakers.

## Voice Agent

```python theme={null}
from lokutor import VoiceAgentClient, VoiceStyle, Language
import os

client = VoiceAgentClient(
    api_key=os.environ['LOKUTOR_API_KEY'],
    prompt="You are a helpful assistant.",
    voice=VoiceStyle.F1,
    language=Language.ENGLISH,
)

client.start_conversation()  # talk through your microphone; Ctrl+C to stop
```

## Events

`client.on(event, callback)` registers a callback directly — it is **not** a decorator (it takes the callback as its second argument and returns the client, not a decorator function), so `@client.on('transcription')` above a `def` will raise a `TypeError`. Call it like this instead:

```python theme={null}
def on_transcription(text):
    print(f"You: {text}")

def on_response(text):
    print(f"Agent: {text}")

def on_status(status):
    print(f"Status: {status}")

client.on('transcription', on_transcription)
client.on('response', on_response)
client.on('status', on_status)
```

Or, equivalently, pass the callbacks directly into the constructor as `on_transcription=`, `on_response=`, `on_status=`, etc. — see the [Python API Reference](/sdks/python/reference).

## Transcript

```python theme={null}
history = client.get_transcript()
text = client.get_transcript_text()
```

## Dynamic prompts

```python theme={null}
client.update_prompt("You are now a technical expert.")
```

## Tool calls

```python theme={null}
def on_tool_call(name, arguments, call_id):
    # arguments is a JSON string
    client.submit_tool_result(call_id, {"ok": True})

client.on('tool_call', on_tool_call)
```

Register the tools themselves with `tools=[...]` in the constructor ([Tool Calling](/sdk/tool-calling)).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.