Assembling the Complete System

Every preceding lesson in this unit built one piece of a voice application: transcription, upload handling, timestamps, meeting workflows, synthesis, architecture decisions, long-audio handling, and tool calling. This lesson assembles those pieces into a single, coherent, end-to-end command-line voice application — a working program that accepts a spoken question as an audio file, reasons about it (including calling a tool when appropriate), and produces a spoken answer as an audio file. The goal is not to introduce new API concepts, but to show how the pieces fit together into a realistic, structured codebase, since real applications are judged as much by their overall organization as by any single component's correctness.

Project Structure

A voice application like this benefits from separating concerns into distinct modules rather than one large script, mirroring how you would organize any production Python project:

voice_app/
    __init__.py
    config.py
    transcription.py
    synthesis.py
    tools.py
    assistant.py
    cli.py

Each file has a single, clear responsibility: config.py holds shared configuration, transcription.py and synthesis.py wrap the STT and TTS calls respectively, tools.py defines the available tool functions and their schemas, assistant.py contains the conversation and tool-calling loop, and cli.py is the thin command-line entry point that ties everything together. This separation is what makes each piece independently testable using the dependency-injection patterns from earlier lessons, and it means a future change — swapping which model is used, adding a new tool, changing the voice — touches only one file rather than requiring changes scattered across a monolithic script.

config.py

from openai import OpenAI

MODEL_NAME = "gpt-5.6-terra"
DEFAULT_VOICE = "alloy"
MAX_UPLOAD_BYTES = 25 * 1024 * 1024

client = OpenAI()

Centralizing configuration values like MODEL_NAME and DEFAULT_VOICE in one place, rather than repeating the string literal "gpt-5.6-terra" throughout the codebase, means changing models later (a near-certainty over an application's lifetime) requires editing one line instead of hunting through every file for hardcoded references. The single shared client instance is imported wherever needed, rather than each module constructing its own, which keeps client configuration (API keys, timeouts, retry settings) consistent across the whole application.

transcription.py

from pathlib import Path
from openai import APIError

from .config import client, MODEL_NAME, MAX_UPLOAD_BYTES


class TranscriptionError(Exception):
    pass


def transcribe_audio_file(file_path: str) -> str:
    path = Path(file_path)

    if not path.exists():
        raise TranscriptionError(f"Audio file not found: {file_path}")

    if path.stat().st_size > MAX_UPLOAD_BYTES:
        raise TranscriptionError(f"Audio file exceeds the {MAX_UPLOAD_BYTES} byte limit")

    try:
        with path.open("rb") as audio_file:
            transcript = client.audio.transcriptions.create(
                model=MODEL_NAME,
                file=audio_file,
            )
    except APIError as exc:
        raise TranscriptionError(f"Transcription failed: {exc}") from exc

    return transcript.text

This directly reuses the validation-then-transcribe pattern from Lesson 2, now pulling client and MODEL_NAME from the shared config module rather than defining them locally. This is a small but meaningful benefit of the module structure: the transcription logic does not need to know or care how the client was configured, only that a correctly configured one is available to import.

synthesis.py

from pathlib import Path

from .config import client, MODEL_NAME, DEFAULT_VOICE


def synthesize_reply(text: str, output_path: str, voice: str = DEFAULT_VOICE) -> None:
    response = client.audio.speech.create(
        model=MODEL_NAME,
        voice=voice,
        input=text,
    )
    Path(output_path).write_bytes(response.read())

This mirrors the synthesis function from Lesson 6, again reusing shared configuration rather than duplicating constants. Keeping this function narrow — it does exactly one thing, synthesize text to an audio file — makes it trivial to test in isolation and easy to reuse if a future feature needs to synthesize speech somewhere else in the application.

tools.py

import json


def get_order_status(order_id: str) -> dict:
    fake_database = {
        "A100": {"status": "shipped", "eta_days": 2},
        "A200": {"status": "processing", "eta_days": 5},
    }
    return fake_database.get(order_id, {"status": "not_found"})


TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "get_order_status",
            "description": "Look up the current status and estimated delivery time for an order.",
            "parameters": {
                "type": "object",
                "properties": {
                    "order_id": {"type": "string", "description": "The order identifier, e.g. A100."}
                },
                "required": ["order_id"],
            },
        },
    }
]

AVAILABLE_FUNCTIONS = {"get_order_status": get_order_status}


def call_tool(function_name: str, arguments_json: str):
    if function_name not in AVAILABLE_FUNCTIONS:
        raise KeyError(f"Unknown tool requested: {function_name}")
    arguments = json.loads(arguments_json)
    result = AVAILABLE_FUNCTIONS[function_name](**arguments)
    return json.dumps(result)

This module isolates everything related to tool definitions and execution, directly extending the pattern from Lesson 9. call_tool wraps the guarded lookup, argument parsing, and execution into one function, giving assistant.py a single clean entry point rather than needing to know the details of JSON parsing or dictionary lookups itself. Adding a new tool to this application means adding one function, one schema entry in TOOLS, and one entry in AVAILABLE_FUNCTIONS — no changes needed anywhere else in the codebase.

assistant.py

from .config import client, MODEL_NAME
from .tools import TOOLS, call_tool


def get_assistant_reply(conversation_history: list[dict]) -> str:
    response = client.chat.completions.create(
        model=MODEL_NAME,
        messages=conversation_history,
        tools=TOOLS,
    )
    message = response.choices[0].message

    if message.tool_calls:
        conversation_history.append(message.model_dump())

        for tool_call in message.tool_calls:
            result_json = call_tool(tool_call.function.name, tool_call.function.arguments)
            conversation_history.append({
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": result_json,
            })

        follow_up = client.chat.completions.create(
            model=MODEL_NAME,
            messages=conversation_history,
            tools=TOOLS,
        )
        final_content = follow_up.choices[0].message.content
        conversation_history.append({"role": "assistant", "content": final_content})
        return final_content

    conversation_history.append({"role": "assistant", "content": message.content})
    return message.content

This is the same tool-calling conversation loop built in Lesson 9, now delegating tool execution entirely to call_tool from tools.py rather than inlining the lookup and execution logic directly. This module's only responsibility is managing the conversation flow — deciding when a tool call is needed and feeding results back — while the actual mechanics of what a tool does and how it is invoked live entirely in tools.py. This separation is what allows either module to change independently: adding a new tool never requires touching assistant.py, and changing the conversation loop's structure never requires touching tools.py.

cli.py

import sys

from .transcription import transcribe_audio_file, TranscriptionError
from .synthesis import synthesize_reply
from .assistant import get_assistant_reply


def run(audio_input_path: str, audio_output_path: str) -> int:
    conversation_history = [
        {"role": "system", "content": "You are a helpful voice assistant for an online store."}
    ]

    try:
        user_text = transcribe_audio_file(audio_input_path)
    except TranscriptionError as exc:
        print(f"Error: {exc}", file=sys.stderr)
        return 1

    print(f"User said: {user_text}")
    conversation_history.append({"role": "user", "content": user_text})

    reply_text = get_assistant_reply(conversation_history)
    print(f"Assistant replied: {reply_text}")

    synthesize_reply(reply_text, audio_output_path)
    print(f"Spoken reply written to: {audio_output_path}")
    return 0


if __name__ == "__main__":
    if len(sys.argv) != 3:
        print("Usage: python -m voice_app.cli <input_audio_path> <output_audio_path>", file=sys.stderr)
        sys.exit(1)

    exit_code = run(sys.argv[1], sys.argv[2])
    sys.exit(exit_code)

run is the orchestration function tying every module together: transcribe, converse (with tool calling handled transparently inside get_assistant_reply), then synthesize. It returns an integer exit code (0 for success, 1 for failure) rather than raising an exception or calling sys.exit directly, which keeps run itself testable as an ordinary function — a test can call run(...) and check its return value, without needing to catch a SystemExit or worry about the process actually terminating. The if __name__ == "__main__": block is what turns this into a runnable command-line tool: it reads command-line arguments from sys.argv, validates that exactly the expected number were provided, calls run, and only then translates the result into an actual process exit via sys.exit(exit_code). This separation between "the logic" (run) and "the command-line wiring" (the __main__ block) is standard practice for any CLI tool, since it keeps the core logic reusable outside of a command-line context — for example, from a web server or a test suite — without dragging along command-line-specific concerns like argument parsing.

Testing the Fully Assembled Application

Because every module was written with dependency injection and clear separation of concerns in mind, the orchestration logic in run can be tested by substituting fake versions of the underlying transcription, assistant, and synthesis functions:

def test_run_produces_expected_flow(monkeypatch):
    calls = {"synthesize_args": None}

    def fake_transcribe(path):
        assert path == "input.wav"
        return "What is the status of order A100?"

    def fake_get_reply(history):
        assert history[-1]["content"] == "What is the status of order A100?"
        return "Order A100 has shipped and should arrive in 2 days."

    def fake_synthesize(text, output_path, voice="alloy"):
        calls["synthesize_args"] = (text, output_path)

    monkeypatch.setattr("voice_app.cli.transcribe_audio_file", fake_transcribe)
    monkeypatch.setattr("voice_app.cli.get_assistant_reply", fake_get_reply)
    monkeypatch.setattr("voice_app.cli.synthesize_reply", fake_synthesize)

    from voice_app.cli import run
    exit_code = run("input.wav", "output.mp3")

    assert exit_code == 0
    assert calls["synthesize_args"] == (
        "Order A100 has shipped and should arrive in 2 days.",
        "output.mp3",
    )
    print("PASS: run_produces_expected_flow")

This test uses monkeypatch (a standard pytest fixture for temporarily replacing an attribute for the duration of a test) to substitute fake implementations of the three functions run depends on, each defined inline with assert statements confirming it receives the arguments the real flow should produce at that stage. This tests the entire orchestration logic — the sequence of transcribe, converse, synthesize, and how their outputs and inputs chain together — without a single real API call, real audio file, or real network connection anywhere in the test. This is the payoff of the modular structure and dependency-injection discipline maintained throughout this unit: the most important integration logic in the entire application is fully testable in milliseconds, deterministically, as part of an ordinary automated test suite.

Extending the Application

This structure scales naturally in directions a real project would need. Adding conversation persistence across separate program invocations means saving and loading conversation_history to a file or database at the start and end of run. Adding the long-audio handling from Lesson 8 means checking the input file's duration in transcribe_audio_file and routing to a chunking implementation when it exceeds a threshold. Migrating from the pipeline architecture to a Realtime-based architecture, as discussed in Lesson 7, would primarily affect assistant.py and the way cli.py orchestrates the flow, while tools.py's tool definitions could largely be reused unchanged — a concrete illustration of why keeping tool definitions in their own module, decoupled from the specific conversation architecture, pays off if the application's architecture ever needs to evolve.

Common Mistakes

Writing the entire pipeline as one long script with no module boundaries, which causes the codebase to become difficult to test, difficult to extend, and difficult for a second developer to understand quickly. The module separation shown here is not bureaucratic overhead — it directly enables the fast, dependency-free testing demonstrated above.

Hardcoding configuration values like model names and voices in multiple files, which causes inconsistency and tedious, error-prone updates when a value needs to change. Centralize shared configuration, as done in config.py.

Mixing command-line argument handling with core application logic, which causes the core logic to become difficult to reuse or test outside of a command-line context. Keep a thin CLI wrapper (cli.py's __main__ block) separate from the actual orchestration function (run).

Best Practices

Structure a multi-component audio application into single-responsibility modules, mirroring the structure demonstrated here: transcription, synthesis, tool definitions, conversation orchestration, and command-line wiring each in their own file.

Design every function to accept its dependencies (a client, a configuration value, another function) explicitly, rather than reaching for global state internally, so that dependency injection for testing — the pattern used consistently across every lesson in this unit — remains possible throughout the application, not just in isolated examples.

Return structured results and exit codes from orchestration logic rather than calling sys.exit or printing directly inside it. This keeps the core logic testable and reusable outside of the specific context (a command-line invocation) it was originally written for.