echoact 0.1.0__py3-none-any.whl

echoact/jobs/request.py

@@ -0,0 +1,300 @@
+"""What a generation request is, and what makes one valid.
+
+Every entry path validates here.  F-37 requires the GUI, REST, and MCP to
+apply the same limits and the same support policy, and the cheapest way to
+guarantee that is to give them one function rather than three that agree
+today.
+
+Nothing in this module touches the engine, the database, or the disk: it
+answers "would this be accepted?", which is exactly what F-88's pre-flight
+estimate needs and what the job engine needs before it takes the slot.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..domain import (
+    Gender,
+    JobKind,
+    Language,
+    RequestPath,
+    RetentionMode,
+    Segment,
+    SpeakingStyle,
+    VoiceSettings,
+)
+from ..errors import Code, EchoActError
+from ..models.manifest import Manifest, ModelEntry
+from ..policy import (
+    BOUNDED_WAIT_CEILING_S,
+    ESTIMATE_REAL_TIME_FACTOR,
+    MAX_INPUT_CODEPOINTS,
+)
+from ..text.segment import estimate_seconds, segment_text
+from ..util import ids
+
+
+@dataclass(frozen=True, slots=True)
+class JobRequest:
+    """One accepted-or-refused generation request.
+
+    ``idempotency_key`` is not optional.  A.3 records why: with a single
+    generation slot, a client that retries after a slow or dropped response
+    would otherwise queue a second rendering of the same text behind the
+    first, and automated clients retry as a matter of course.  The GUI mints
+    one per press for the same reason -- a double-click is a retry too.
+    """
+
+    text: str
+    settings: VoiceSettings
+    request_path: RequestPath
+    owner_client_id: str
+    idempotency_key: str
+    kind: JobKind = JobKind.SPEECH
+    retention: RetentionMode = RetentionMode.ONE_OFF
+    client_label: str | None = None
+    #: F-88.  ``None`` means answer as soon as the job is accepted.
+    wait_s: float | None = None
+
+    def digest(self) -> str:
+        """F-49's request-match discriminator.
+
+        Hashed rather than stored: 4.2 keeps "only the information needed
+        for duplicate prevention ... with no source text", so the record
+        must be able to tell "same content" from "different content"
+        without holding the content.
+        """
+        from ..db.store import request_match_digest
+
+        return request_match_digest(
+            self.kind.value,
+            self.text,
+            repr(sorted(self.settings.to_dict().items())),
+            self.retention.value,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Estimate:
+    """F-88's pre-flight answer.
+
+    Explicitly approximate, and derived from the throughput A.5 measured
+    rather than from a trial synthesis: the requirement says an estimate
+    must not create a job or load a model.
+    """
+
+    valid: bool
+    codepoints: int
+    segment_count: int
+    audio_ms: int
+    synthesis_ms: int
+    first_audio_ms: int
+    slot_free: bool
+    model_ready: bool
+    approximate: bool = True
+    problems: tuple[dict[str, Any], ...] = field(default_factory=tuple)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "valid": self.valid,
+            "codepoints": self.codepoints,
+            "segment_count": self.segment_count,
+            "audio_ms": self.audio_ms,
+            "synthesis_ms": self.synthesis_ms,
+            "first_audio_ms": self.first_audio_ms,
+            "slot_free": self.slot_free,
+            "model_ready": self.model_ready,
+            "approximate": self.approximate,
+            "problems": list(self.problems),
+        }
+
+
+def validate_text(text: str) -> str:
+    """F-03.  Returns the text unchanged when it is acceptable.
+
+    Whitespace-only input is refused rather than trimmed: A.5 found the
+    engine raising on it, so this is the guard the requirement says it is,
+    and trimming would quietly change the offsets every segment range is
+    measured against.
+    """
+    if not text or not text.strip():
+        raise EchoActError(Code.INPUT_EMPTY)
+    if len(text) > MAX_INPUT_CODEPOINTS:
+        raise EchoActError(
+            Code.INPUT_TOO_LONG,
+            detail={"codepoints": len(text), "limit": MAX_INPUT_CODEPOINTS},
+        )
+    return text
+
+
+def validate_settings(settings: VoiceSettings, manifest: Manifest) -> ModelEntry:
+    """F-04 through F-08.
+
+    Nothing is substituted.  F-54 is explicit that unknown models and
+    options are not arbitrarily replaced, so every mismatch is an error
+    naming what was wrong rather than a silent correction.
+    """
+    settings.validate()  # tempo range, F-07
+
+    if not manifest.has(settings.model_id):
+        raise EchoActError(
+            Code.MODEL_UNKNOWN,
+            detail={"model_id": settings.model_id, "known": list(manifest.model_ids)},
+        )
+    entry = manifest.get(settings.model_id)
+
+    if settings.language is not Language.AUTO and not entry.supports_language(settings.language):
+        raise EchoActError(
+            Code.LANGUAGE_UNKNOWN,
+            detail={
+                "language": settings.language.value,
+                "supported": [lang.value for lang in entry.languages],
+            },
+        )
+    if not isinstance(settings.style, SpeakingStyle):
+        raise EchoActError(Code.STYLE_UNKNOWN, detail={"style": str(settings.style)})
+
+    voice = next((v for v in entry.voices if v.voice_id == settings.voice_id), None)
+    if voice is None:
+        raise EchoActError(
+            Code.VOICE_UNKNOWN,
+            detail={
+                "voice_id": settings.voice_id,
+                "available": [v.voice_id for v in entry.voices],
+            },
+        )
+    if voice.gender is not settings.gender:
+        # F-06 selects a gender and then a voice within it; a request whose
+        # two halves disagree is a mistake to report, not one to resolve by
+        # picking a side.
+        raise EchoActError(
+            Code.VOICE_GENDER_MISMATCH,
+            detail={"voice_id": voice.voice_id, "voice_gender": voice.gender.value},
+        )
+    return entry
+
+
+def validate_request(request: JobRequest, manifest: Manifest) -> ModelEntry:
+    """Everything a request must satisfy before it can take the slot."""
+    if request.kind is None:
+        raise EchoActError(Code.JOB_KIND_MISSING)
+    if not isinstance(request.kind, JobKind):
+        raise EchoActError(Code.JOB_KIND_UNKNOWN, detail={"kind": str(request.kind)})
+    if not request.idempotency_key or not request.idempotency_key.strip():
+        raise EchoActError(Code.IDEMPOTENCY_KEY_MISSING)
+    if request.wait_s is not None and request.wait_s < 0:
+        raise EchoActError(
+            Code.INTERNAL, "A wait cannot be negative.", detail={"wait_s": request.wait_s}
+        )
+    validate_text(request.text)
+    return validate_settings(request.settings, manifest)
+
+
+def clamp_wait(wait_s: float | None, *, ceiling_s: float = BOUNDED_WAIT_CEILING_S) -> float:
+    """4.1's bounded wait.
+
+    The service never waits longer than the caller asked *and* never longer
+    than the owner's ceiling, so this takes the smaller of the two rather
+    than substituting the default for an out-of-range value.
+    """
+    if wait_s is None:
+        return 0.0
+    return max(0.0, min(float(wait_s), ceiling_s))
+
+
+def plan_segments(text: str, settings: VoiceSettings) -> list[Segment]:
+    """F-81, with fresh identifiers so the plan can be stored as-is."""
+    segments = segment_text(text, settings)
+    for seg in segments:
+        if not seg.segment_id:
+            seg.segment_id = ids.segment_id()
+    return segments
+
+
+def estimate(
+    text: str,
+    settings: VoiceSettings,
+    manifest: Manifest,
+    *,
+    slot_free: bool,
+    model_ready: bool,
+    real_time_factor: float = ESTIMATE_REAL_TIME_FACTOR,
+) -> Estimate:
+    """F-88's pre-flight estimate.
+
+    Answers even when the request is invalid: a caller asking "would this
+    work?" is best served by the reasons it would not, all of them, rather
+    than by the first exception.  That is also why validation problems are
+    collected instead of raised.
+    """
+    problems: list[dict[str, Any]] = []
+    for check in (
+        lambda: validate_text(text),
+        lambda: validate_settings(settings, manifest),
+    ):
+        try:
+            check()
+        except EchoActError as exc:
+            problems.append({"code": exc.code.value, "message": exc.message, **exc.detail})
+
+    if problems:
+        return Estimate(
+            valid=False,
+            codepoints=len(text),
+            segment_count=0,
+            audio_ms=0,
+            synthesis_ms=0,
+            first_audio_ms=0,
+            slot_free=slot_free,
+            model_ready=model_ready,
+            problems=tuple(problems),
+        )
+
+    segments = segment_text(text, settings)
+    tempo = settings.tempo
+    audio_s = 0.0
+    first_s = 0.0
+    for i, seg in enumerate(segments):
+        seconds = estimate_seconds(seg.spoken_text, seg.language, tempo)
+        seconds += seg.trailing_silence_ms / 1000.0
+        audio_s += seconds
+        if i == 0:
+            first_s = seconds
+
+    synthesis_s = audio_s * real_time_factor
+    # Time to the first sound, which is what F-12 makes the interesting
+    # number: the first segment has to be synthesised before anything plays,
+    # and a model that is not resident has to be loaded first.  The load is
+    # not included here -- F-88 says an estimate never waits on model
+    # preparation, so quoting it would describe a different operation.
+    first_audio_s = first_s * real_time_factor
+
+    return Estimate(
+        valid=True,
+        codepoints=len(text),
+        segment_count=len(segments),
+        audio_ms=int(round(audio_s * 1000)),
+        synthesis_ms=int(round(synthesis_s * 1000)),
+        first_audio_ms=int(round(first_audio_s * 1000)),
+        slot_free=slot_free,
+        model_ready=model_ready,
+    )
+
+
+def resolve_gender_voice(entry: ModelEntry, gender: Gender, voice_id: str | None) -> str:
+    """The first voice of a gender, for a caller that named only a gender.
+
+    Used by the GUI when the user switches gender, never to paper over an
+    invalid request: F-54 forbids substituting an unknown option, and this
+    is only reached when no voice was named at all.
+    """
+    voices = entry.voices_for(gender)
+    if not voices:
+        raise EchoActError(Code.VOICE_UNKNOWN, detail={"gender": gender.value})
+    if voice_id:
+        for v in voices:
+            if v.voice_id == voice_id:
+                return v.voice_id
+    return voices[0].voice_id

echoact/mcp/__main__.py

@@ -0,0 +1,50 @@
+"""Entry point for the MCP server process.
+
+Started by the MCP client, per F-58.  It never starts EchoAct -- F-52 is
+explicit -- and it exits with a message rather than waiting when the app
+is not there to talk to.
+
+Diagnostics go to stderr, which the revision this implements requires:
+its logging feature is deprecated and §2.11 says so.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from ..errors import EchoActError
+from .client import RestClient
+from .config import from_environment
+from .server import build, preflight
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    try:
+        connection = from_environment(args)
+    except EchoActError as exc:
+        print(f"[echoact-mcp] {exc.code.value}: {exc.message}", file=sys.stderr, flush=True)
+        return 2
+
+    rest = RestClient(connection)
+    try:
+        preflight(rest)
+    except EchoActError as exc:
+        # Distinct and non-retrying, per F-52.  Exiting rather than
+        # serving is the honest answer: every tool would fail the same
+        # way, and a client that saw tools listed would reasonably expect
+        # them to work.
+        print(f"[echoact-mcp] {exc.code.value}: {exc.message}", file=sys.stderr, flush=True)
+        rest.close()
+        return 3
+
+    server = build(connection, client=rest)
+    try:
+        server.run(transport="stdio", show_banner=False)
+    finally:
+        rest.close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

echoact/mcp/client.py

@@ -0,0 +1,202 @@
+"""The MCP server's half of the loopback conversation.
+
+F-58 makes the MCP server a client of the local REST service and nothing
+else: no model, no database, no job state.  So this is the whole of its
+machinery, and its one interesting job is translating the ways the
+conversation can fail into the distinct, non-retrying errors F-52 names:
+
+* EchoAct is not running -- the connection is refused.  Distinct because
+  the remedy is to start EchoAct, and because F-52 forbids this process
+  from starting it.
+* REST is turned off -- there is no listener, or one that says so.
+* MCP is disabled in EchoAct -- the service answers, but the owner has
+  not enabled this integration.
+* The credential has expired or been revoked -- authentication fails for
+  a reason the user can act on, which is not the same as being wrong.
+
+Every other failure keeps the service's own error code, because N-24
+makes MCP a projection of REST and a behaviour difference between them a
+defect.  Re-deriving a code here would be exactly that difference.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from ..errors import Code, EchoActError, is_retryable
+from .config import Connection
+
+#: Codes that mean "this process cannot work until something changes",
+#: as opposed to "try again".  F-52 wants these reported as non-retrying.
+TERMINAL_CODES = frozenset(
+    {
+        Code.APP_NOT_RUNNING,
+        Code.SERVICE_OFF,
+        Code.MCP_DISABLED,
+        Code.CREDENTIAL_EXPIRED,
+        Code.CREDENTIAL_REVOKED,
+        Code.UNAUTHENTICATED,
+        Code.HOST_NOT_ALLOWED,
+    }
+)
+
+
+class RestClient:
+    """A thin, synchronous client.  Synchronous on purpose: this process
+    serves one stdio conversation and has nothing to overlap with."""
+
+    def __init__(self, connection: Connection, transport: httpx.BaseTransport | None = None):
+        self.connection = connection
+        self._http = httpx.Client(
+            base_url=connection.api_root,
+            headers=connection.headers(),
+            timeout=connection.timeout_s,
+            transport=transport,
+            follow_redirects=False,
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> RestClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # ------------------------------------------------------------------
+
+    def get(self, path: str, **params: Any) -> dict[str, Any]:
+        return self._json("GET", path, params={k: v for k, v in params.items() if v is not None})
+
+    def post(self, path: str, body: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self._json("POST", path, json=body)
+
+    def get_bytes(self, path: str) -> tuple[bytes, str]:
+        """Fetch a result's audio.  Returns (bytes, media type).
+
+        The MCP server resolves a resource URI on the client's behalf
+        (F-60), so the bytes pass through this process rather than the
+        client being handed an address -- which is what lets §2.11 keep
+        local paths and tokenised URLs out of the protocol entirely.
+        """
+        response = self._send("GET", path, headers={"Accept": "audio/wav"})
+        return response.content, response.headers.get("content-type", "audio/wav")
+
+    # ------------------------------------------------------------------
+
+    def _json(self, method: str, path: str, **kw: Any) -> dict[str, Any]:
+        response = self._send(method, path, **kw)
+        if not response.content:
+            return {}
+        try:
+            body = response.json()
+        except ValueError as exc:
+            raise EchoActError(
+                Code.INTERNAL, "EchoAct returned something that is not JSON.", cause=exc
+            ) from exc
+        return body if isinstance(body, dict) else {"result": body}
+
+    def _send(self, method: str, path: str, **kw: Any) -> httpx.Response:
+        try:
+            response = self._http.request(method, path, **kw)
+        except httpx.ConnectError as exc:
+            # The refused connection is the signal, and it is the one case
+            # this process must never try to fix by starting anything.
+            raise EchoActError(
+                Code.APP_NOT_RUNNING,
+                "EchoAct is not running, or its local service is turned off. "
+                "Start EchoAct and check Settings; this server cannot start it.",
+                cause=exc,
+            ) from exc
+        except httpx.TimeoutException as exc:
+            raise EchoActError(
+                Code.APP_NOT_RUNNING,
+                "EchoAct did not answer on the loopback address.",
+                cause=exc,
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise EchoActError(
+                Code.INTERNAL, f"The local request failed ({type(exc).__name__}).", cause=exc
+            ) from exc
+
+        if response.status_code >= 400:
+            raise self._error(response)
+        return response
+
+    @staticmethod
+    def _error(response: httpx.Response) -> EchoActError:
+        """Carry the service's own code across, rather than inventing one."""
+        payload: dict[str, Any] = {}
+        try:
+            parsed = response.json()
+            if isinstance(parsed, dict):
+                payload = parsed
+        except ValueError:
+            pass
+
+        raw = str(payload.get("code", "")).strip()
+        try:
+            code = Code(raw)
+        except ValueError:
+            code = _code_for_status(response.status_code)
+
+        message = str(payload.get("message", "")) or None
+        retry_after = payload.get("retry_after_s")
+        if retry_after is None and "Retry-After" in response.headers:
+            try:
+                retry_after = float(response.headers["Retry-After"])
+            except ValueError:
+                retry_after = None
+        detail = {k: v for k, v in payload.items() if k not in {"code", "message", "retry_after_s"}}
+        return EchoActError(
+            code,
+            message,
+            detail=detail or None,
+            retry_after_s=float(retry_after) if retry_after is not None else None,
+        )
+
+
+def _code_for_status(status: int) -> Code:
+    """Only reached when the answer carried no code of its own.
+
+    F-57 requires every EchoAct error to carry one, so this is the case
+    where something *else* is listening on the port.  Statuses whose
+    meaning is unambiguous are mapped; the rest stay ``INTERNAL`` rather
+    than being guessed into a precise-looking code that would then be
+    wrong -- 422 in particular means "invalid voice settings" in this
+    contract and nothing at all in a stranger's.
+    """
+    return {
+        401: Code.UNAUTHENTICATED,
+        403: Code.FORBIDDEN,
+        404: Code.NOT_FOUND,
+        410: Code.RESULT_EXPIRED,
+        413: Code.PAYLOAD_TOO_LARGE,
+        429: Code.RATE_LIMITED,
+        503: Code.SERVICE_OFF,
+        507: Code.STORAGE_FULL,
+    }.get(status, Code.INTERNAL)
+
+
+def describe(error: EchoActError) -> dict[str, Any]:
+    """What a tool returns when the call failed.
+
+    Keeps the service's code and adds the one thing an automated caller
+    most needs and F-57 already decided: whether trying again can work.
+    """
+    return {
+        "error": {
+            "code": error.code.value,
+            "message": error.message,
+            "retryable": error.retryable and error.code not in TERMINAL_CODES,
+            **({"retry_after_s": error.retry_after_s} if error.retry_after_s else {}),
+            **({"detail": error.detail} if error.detail else {}),
+        }
+    }
+
+
+def is_terminal(error: EchoActError) -> bool:
+    return error.code in TERMINAL_CODES or not is_retryable(error.code)

echoact/mcp/config.py

@@ -0,0 +1,112 @@
+"""How the MCP server is told where EchoAct is and who it is.
+
+F-58 puts the connection details in the MCP *client's* configuration and
+has the app hand them to the user, so this process reads them from its
+environment and its arguments and holds nothing of its own.  There is no
+config file to find, no discovery, and no fallback that would let it work
+without a credential -- N-31's fail-closed rule reaches here too.
+
+The credential is read from the environment rather than from a command
+line by preference: an argument is visible in the process list to every
+program on the machine, and N-17 keeps tokens out of places they can be
+read from.  A ``--token`` argument is still accepted, because some MCP
+client configurations cannot set an environment variable, and the
+docstring is the place to say which is worse.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from ..errors import Code, EchoActError
+from ..policy import REST_HOST, REST_PORT_DEFAULT
+
+ENV_URL = "ECHOACT_URL"
+ENV_TOKEN = "ECHOACT_TOKEN"
+ENV_TIMEOUT = "ECHOACT_TIMEOUT_S"
+
+DEFAULT_TIMEOUT_S = 30.0
+
+
+@dataclass(frozen=True, slots=True)
+class Connection:
+    """Everything this process needs, and nothing it could invent."""
+
+    base_url: str
+    token: str
+    timeout_s: float = DEFAULT_TIMEOUT_S
+
+    @property
+    def api_root(self) -> str:
+        return f"{self.base_url.rstrip('/')}/api/v1"
+
+    def headers(self) -> dict[str, str]:
+        # The Host header is what the service validates before it looks at
+        # the credential (N-17), so it has to be the loopback name the
+        # service expects rather than whatever httpx would infer.
+        return {
+            "Authorization": f"Bearer {self.token}",
+            "Accept": "application/json",
+        }
+
+
+def default_url() -> str:
+    return f"http://{REST_HOST}:{REST_PORT_DEFAULT}"
+
+
+def from_environment(argv: list[str] | None = None) -> Connection:
+    """Read the connection, or refuse to start.
+
+    A missing credential is a configuration error the user must fix, not a
+    condition to retry: F-52 wants distinct, non-retrying errors for the
+    ways this process can be unusable, and starting anonymously is not an
+    option N-31 leaves open.
+    """
+    args = list(argv or [])
+    token = os.environ.get(ENV_TOKEN, "")
+    url = os.environ.get(ENV_URL, "") or default_url()
+
+    for i, arg in enumerate(args):
+        if arg == "--token" and i + 1 < len(args):
+            token = args[i + 1]
+        elif arg.startswith("--token="):
+            token = arg.split("=", 1)[1]
+        elif arg == "--url" and i + 1 < len(args):
+            url = args[i + 1]
+        elif arg.startswith("--url="):
+            url = arg.split("=", 1)[1]
+
+    if not token:
+        raise EchoActError(
+            Code.UNAUTHENTICATED,
+            f"No EchoAct credential. Set {ENV_TOKEN} in this server's configuration; "
+            "EchoAct shows the value once, under Settings.",
+        )
+    if not _is_loopback(url):
+        # N-17 and Section 7: EchoAct is never reachable off this machine,
+        # so a URL that points elsewhere is a misconfiguration to report
+        # rather than an address to try.
+        raise EchoActError(
+            Code.HOST_NOT_ALLOWED,
+            f"EchoAct only listens on the loopback address; {url!r} is not one.",
+        )
+
+    timeout = DEFAULT_TIMEOUT_S
+    raw = os.environ.get(ENV_TIMEOUT)
+    if raw:
+        try:
+            timeout = max(1.0, float(raw))
+        except ValueError:
+            pass
+    return Connection(base_url=url, token=token, timeout_s=timeout)
+
+
+def _is_loopback(url: str) -> bool:
+    from urllib.parse import urlparse
+
+    try:
+        host = (urlparse(url).hostname or "").lower()
+    except ValueError:
+        return False
+    return host in {"127.0.0.1", "localhost", "::1"}