Source code for discussion_helper.cli

"""
The command line — ``discussion-helper``.

Module summary
--------------
Two commands, and the second one is why this file is worth reading.

``talk`` opens the microphone and holds a conversation. ``rehearse`` holds the
same conversation with the microphone, the model and the sound card replaced
by fakes — the same loop, the same floor handling, the same interruption
logic, running in a second with nothing installed. It is how you check that
*this package* works before deciding whether the room does.

That distinction matters more than it looks. When a voice agent misbehaves,
the first question is always "is it the loop or is it the hardware", and
without something like ``rehearse`` the only way to ask it is to change one
thing and listen again.

One command line, one parser. Until 0.4.0 these two commands were declared
twice — two parsers over one shared handler table, the second reachable under
a name that advertised the parsing library — and keeping the pair in step cost
more than the second door was worth.

Author
------
Warith HARCHAOUI — https://linkedin.com/in/warith-harchaoui
"""

from __future__ import annotations

import asyncio
import json
import sys
from collections.abc import Callable
from typing import TypeVar

import click

from discussion_helper import __version__
from discussion_helper.discussion import Discussion, Policy
from discussion_helper.types import Conversation

_Command = TypeVar("_Command", bound=Callable[..., None])


def _common(function: _Command) -> _Command:
    """The flags both commands share, applied once rather than twice."""
    function = click.option(
        "--no-barge-in",
        is_flag=True,
        default=False,
        help="Strict half-duplex: the user may not interrupt. Correct on a "
        "speakerphone, where every reply would otherwise interrupt itself.",
    )(function)
    function = click.option(
        "--grace",
        type=float,
        default=0.35,
        show_default=True,
        metavar="SECONDS",
        help="How long after the agent starts speaking before an interruption "
        "is believed. Absorbs the agent's own voice when there is no echo "
        "cancellation.",
    )(function)
    function = click.option(
        "--max-sentences",
        type=int,
        default=0,
        show_default=True,
        help="Cap on reply length. 0 means no cap.",
    )(function)
    function = click.option(
        "--json",
        "as_json",
        is_flag=True,
        default=False,
        help="Write the transcript and the latency breakdown as JSON.",
    )(function)
    return function


@click.group(
    context_settings={"help_option_names": ["-h", "--help"]},
    help=(
        "Hold a spoken conversation: listen, answer, speak — and stop the moment the user cuts in."
    ),
    epilog=(
        # The `\b` keeps click from reflowing the block under it into one
        # paragraph, which is what turns an examples list into prose.
        "\b\n"
        "Examples:\n"
        "  discussion-helper rehearse 'bonjour' 'ça va ?'   # no hardware\n"
        "  discussion-helper talk --voice ff_siwis\n"
        "  discussion-helper talk --no-barge-in             # strict half-duplex\n"
        "\n"
        "KNOWLEDGE.md explains the latency budget, turn detection and why echo\n"
        "decides your defaults."
    ),
)
# Read from the package, not from the installed distribution's metadata.
# `package_name=` alone sends click to importlib.metadata, which reports
# whatever was last pip-installed -- a step behind the code in every editable
# checkout. Measured while there were still two doors: click said 0.1.0 and
# the module said 0.2.0, in the same tree.
# ``-V`` as well as ``--version``, because the short form is the one people
# actually type, and ``-v`` is spoken for by verbosity elsewhere in the suite.
@click.version_option(__version__, "-V", "--version", package_name="discussion-helper")
def cli() -> None:  # pragma: no cover - click dispatches
    """Front door over the two commands."""


def _policy(
    *,
    no_barge_in: bool,
    grace: float,
    max_sentences: int,
    silence_timeout: float = 0.0,
) -> Policy:
    """The policy the shared flags describe."""
    return Policy(
        allow_barge_in=not no_barge_in,
        barge_in_grace_s=grace,
        max_reply_sentences=max_sentences,
        silence_timeout_s=silence_timeout,
    )


def _report(conversation: Conversation, as_json: bool) -> None:
    """Print the transcript, and where the latency went.

    The breakdown is printed even in the human-readable form, because a total
    says a conversation felt slow and nothing about which stage to fix.
    """
    if as_json:
        sys.stdout.write(
            json.dumps(
                {
                    "utterances": [
                        {
                            "speaker": u.speaker,
                            "text": u.text,
                            "interrupted": u.interrupted,
                        }
                        for u in conversation.utterances
                    ],
                    "timings": [t.as_dict() for t in conversation.timings],
                    "interruption_rate": round(conversation.interruption_rate, 3),
                },
                ensure_ascii=False,
                indent=2,
            )
            + "\n"
        )
        return

    for utterance in conversation.utterances:
        mark = " (cut off)" if utterance.interrupted else ""
        who = "you" if utterance.speaker == "user" else "it"
        sys.stdout.write(f"{who:>4}: {utterance.text}{mark}\n")

    if conversation.timings:
        sys.stdout.write("\n")
        for index, timing in enumerate(conversation.timings, start=1):
            sys.stdout.write(
                f"turn {index}: {timing.to_first_audio_s * 1000:.0f} ms to first "
                f"audio, slowest stage {timing.slowest_stage}\n"
            )


@cli.command()
@_common
@click.option("--voice", default="", help="Voice to read with.")
@click.option("--language", default="", help="Language hint.")
@click.option("--device", default=None, help="Microphone name substring.")
@click.option(
    "--silence-timeout",
    type=float,
    default=30.0,
    show_default=True,
    metavar="SECONDS",
    help="Give up after this much silence. An open microphone in an empty "
    "room is an ordinary ending.",
)
def talk(
    no_barge_in: bool,
    grace: float,
    max_sentences: int,
    as_json: bool,
    voice: str,
    language: str,
    device: str | None,
    silence_timeout: float,
) -> None:
    """Hold a conversation at the microphone."""
    from discussion_helper.adapters import LocalResponder, SpeakerVoice, VocalListener

    policy = _policy(
        no_barge_in=no_barge_in,
        grace=grace,
        max_sentences=max_sentences,
        silence_timeout=silence_timeout,
    )

    async def run() -> Conversation:
        async with Discussion(
            VocalListener(language=language, device_name=device),
            LocalResponder(),
            SpeakerVoice(voice=voice, language=language),
            policy,
        ) as discussion:
            return await discussion.run()

    try:
        conversation = asyncio.run(run())
    except RuntimeError as exc:
        # The adapters raise this with the install line for the half that is
        # missing, which is more use than a traceback about a module the
        # reader has never imported.
        sys.stderr.write(f"{exc}\n")
        raise SystemExit(1) from None
    except KeyboardInterrupt:
        sys.stderr.write("\n")
        raise SystemExit(0) from None
    _report(conversation, as_json)


@cli.command()
@_common
@click.argument("turns", nargs=-1)
@click.option(
    "--interrupt-after",
    type=float,
    default=None,
    metavar="SECONDS",
    help="Stage a barge-in this long into the agent's reply.",
)
@click.option(
    "--sentences", type=int, default=3, show_default=True, help="How long the fake reply runs."
)
def rehearse(
    no_barge_in: bool,
    grace: float,
    max_sentences: int,
    as_json: bool,
    turns: tuple[str, ...],
    interrupt_after: float | None,
    sentences: int,
) -> None:
    """Run the same loop with fake parts — no microphone, model or speaker.

    The question a voice agent always raises first is "is it the loop or is it
    the room". This answers it in a second, with nothing installed.
    """
    from discussion_helper.testing import EchoResponder, ScriptedListener, SilentVoice

    discussion = Discussion(
        ScriptedListener(list(turns) or ["bonjour"], interrupt_after_s=interrupt_after),
        EchoResponder(sentences=sentences),
        SilentVoice(seconds_per_sentence=0.2),
        _policy(no_barge_in=no_barge_in, grace=grace, max_sentences=max_sentences),
    )
    _report(asyncio.run(discussion.run()), as_json)


[docs] def main() -> None: """Console-script entry point.""" import os_helper as osh osh.init_logging() cli()
if __name__ == "__main__": # pragma: no cover # `cli()` raises SystemExit with its own code; wrapping `main()` in # sys.exit would only ever pass None, which means 0 whatever happened. main()