openspeechapi 0.1.0__py3-none-any.whl

openspeech/local_engines/tasks.py

@@ -0,0 +1,71 @@
+"""Task models for local engine operations."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+from openspeech.local_engines.models import EngineAction, TaskStatus
+
+
+def _utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+@dataclass
+class EngineTask:
+    engine: str
+    action: EngineAction
+    runtime: str
+    task_id: str = field(default_factory=lambda: uuid4().hex)
+    status: TaskStatus = TaskStatus.QUEUED
+    phase: str = "queued"
+    message: str = "Task queued."
+    progress: float | None = 0.0
+    eta_seconds: int | None = None
+    error: str | None = None
+    started_at: datetime = field(default_factory=_utc_now)
+    updated_at: datetime = field(default_factory=_utc_now)
+    finished_at: datetime | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def snapshot(self) -> dict[str, Any]:
+        return {
+            "task_id": self.task_id,
+            "engine": self.engine,
+            "action": self.action.value,
+            "runtime": self.runtime,
+            "status": self.status.value,
+            "phase": self.phase,
+            "message": self.message,
+            "progress": self.progress,
+            "eta_seconds": self.eta_seconds,
+            "error": self.error,
+            "started_at": self.started_at.isoformat(),
+            "updated_at": self.updated_at.isoformat(),
+            "finished_at": self.finished_at.isoformat() if self.finished_at else None,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_snapshot(cls, data: dict[str, Any]) -> "EngineTask":
+        task = cls(
+            engine=data["engine"],
+            action=EngineAction(data["action"]),
+            runtime=data["runtime"],
+            task_id=data["task_id"],
+            status=TaskStatus(data["status"]),
+            phase=data.get("phase", "queued"),
+            message=data.get("message", ""),
+            progress=data.get("progress"),
+            eta_seconds=data.get("eta_seconds"),
+            error=data.get("error"),
+            metadata=data.get("metadata", {}),
+        )
+        task.started_at = datetime.fromisoformat(data["started_at"])
+        task.updated_at = datetime.fromisoformat(data["updated_at"])
+        finished_raw = data.get("finished_at")
+        if finished_raw:
+            task.finished_at = datetime.fromisoformat(finished_raw)
+        return task

openspeech/logging_config.py

@@ -0,0 +1,607 @@
+"""Unified logging configuration for OpenSpeechAPI.
+
+Responsibilities:
+- Configure loguru sinks (console + rotating JSONL file) with a consistent
+  field contract so logs can be parsed by humans, LLMs, and log pipelines.
+- Provide contextvars-bound fields (``request_id``, ``session_id``,
+  ``provider``, ``engine``) that automatically decorate every log record
+  emitted under a given async request / task tree.
+- Expose a simple public API (:func:`configure_logging`, :func:`bind_context`,
+  :func:`get_log_settings`) that CLI, server app, client and tests can share.
+
+Field contract (see ``docs/architecture/logging-spec.md`` for full details)::
+
+    ts, level, event, module, message,
+    request_id, session_id, provider, engine,
+    phase, elapsed_ms, ttfb_ms, payload
+
+``event`` is a dotted namespace (e.g. ``ws.first_response``,
+``dispatch.dispatch_total``) and is always set for structured milestone
+records emitted via :mod:`openspeech.telemetry.perf`.  Legacy free-form
+``logger.info("...")`` calls simply leave ``event`` empty.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Iterator
+
+from loguru import logger as _root_logger
+
+# ---------------------------------------------------------------------------
+# Host-integration state
+# ---------------------------------------------------------------------------
+#
+# OpenSpeech can run in one of two modes:
+#
+# * **standalone** (default) — our own console + JSONL file sinks, managed
+#   by :func:`configure_logging`.
+# * **host-managed** — another loguru-based application (e.g. wallex)
+#   wants to own the sinks, and we just emit records with a known tag.
+#
+# The tag is attached to every record emitted through :data:`logger`
+# (the re-exported loguru instance every openspeech module imports). The
+# host can read ``record["extra"]["component"]`` in its own sink to
+# format, filter, or route OpenSpeech records.
+
+_INTEGRATION: dict[str, Any] = {
+    "tag": "openspeech",          # record.extra["component"] value
+    "level": None,                 # optional independent min-level for OS records
+    "host_managed": False,         # True → ensure_configured() is a no-op
+}
+
+# Track sink IDs we own so we can remove them without touching host sinks.
+_OS_SINK_IDS: list[int] = []
+
+
+def _os_patcher(record: dict[str, Any]) -> None:
+    """Stamp every OpenSpeech log record with the configured component tag.
+
+    The value is read from :data:`_INTEGRATION` at emit-time so that
+    :func:`integrate_with_host` can change it at runtime without rebinding
+    the logger reference held by every openspeech module.
+    """
+    record["extra"].setdefault("component", _INTEGRATION["tag"])
+
+
+# Single logger instance shared by the whole openspeech package.  All
+# internal modules must import it as ``from openspeech.logging_config
+# import logger`` so the component tag is guaranteed.
+logger = _root_logger.patch(_os_patcher)
+
+
+# ---------------------------------------------------------------------------
+# Public field contract
+# ---------------------------------------------------------------------------
+
+# Fields that appear on every structured record (populated via contextualize()).
+_CONTEXT_FIELDS: tuple[str, ...] = (
+    "request_id",
+    "session_id",
+    "provider",
+    "engine",
+    "event",
+    "phase",
+    "elapsed_ms",
+    "ttfb_ms",
+)
+
+# Valid perf levels, in order of verbosity.
+_PERF_LEVELS: tuple[str, ...] = ("off", "basic", "verbose")
+
+# Valid log formats.
+_LOG_FORMATS: tuple[str, ...] = ("text", "json")
+
+
+# ---------------------------------------------------------------------------
+# Settings
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class LogSettings:
+    """Resolved logging configuration."""
+
+    level: str = "INFO"
+    format: str = "text"  # "text" for console-friendly, "json" for structured stdout
+    log_dir: Path | None = None  # when set, also write rotating JSONL
+    log_file_name: str = "openspeech.jsonl"
+    rotation: str = "50 MB"
+    retention: str = "14 days"
+    perf: str = "basic"  # off | basic | verbose
+    color: bool | None = None  # None -> auto
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+_CURRENT: LogSettings = LogSettings()
+
+
+def get_log_settings() -> LogSettings:
+    """Return the currently active log settings."""
+    return _CURRENT
+
+
+# ---------------------------------------------------------------------------
+# Context vars (for request_id / session_id / provider / engine propagation)
+# ---------------------------------------------------------------------------
+
+_request_id_var: ContextVar[str | None] = ContextVar("os_request_id", default=None)
+_session_id_var: ContextVar[str | None] = ContextVar("os_session_id", default=None)
+_provider_var: ContextVar[str | None] = ContextVar("os_provider", default=None)
+_engine_var: ContextVar[str | None] = ContextVar("os_engine", default=None)
+
+
+def get_request_id() -> str | None:
+    """Return the request_id currently bound in this async context."""
+    return _request_id_var.get()
+
+
+def get_session_id() -> str | None:
+    return _session_id_var.get()
+
+
+@contextmanager
+def bind_context(
+    *,
+    request_id: str | None = None,
+    session_id: str | None = None,
+    provider: str | None = None,
+    engine: str | None = None,
+    **extra: Any,
+) -> Iterator[dict[str, Any]]:
+    """Bind contextual fields for the duration of the ``with`` block.
+
+    All fields are optional. ``None`` values are ignored (they do not
+    overwrite an outer binding). Returns the resolved context dict so the
+    caller can use it for echoing / tracing if desired.
+
+    This binds both ``loguru.contextualize()`` and Python ``contextvars`` so
+    that:
+    - any ``logger.*`` call inside the block is auto-decorated;
+    - code paths that want to read the current ``request_id`` directly
+      (e.g. to echo on the wire) can call :func:`get_request_id`.
+    """
+    resets: list[tuple[ContextVar[Any], Any]] = []
+    bindings: dict[str, Any] = {}
+
+    if request_id is not None:
+        resets.append((_request_id_var, _request_id_var.set(request_id)))
+        bindings["request_id"] = request_id
+    if session_id is not None:
+        resets.append((_session_id_var, _session_id_var.set(session_id)))
+        bindings["session_id"] = session_id
+    if provider is not None:
+        resets.append((_provider_var, _provider_var.set(provider)))
+        bindings["provider"] = provider
+    if engine is not None:
+        resets.append((_engine_var, _engine_var.set(engine)))
+        bindings["engine"] = engine
+    for k, v in extra.items():
+        if v is not None:
+            bindings[k] = v
+
+    try:
+        with logger.contextualize(**bindings):
+            yield bindings
+    finally:
+        for var, token in reversed(resets):
+            try:
+                var.reset(token)
+            except Exception:
+                pass
+
+
+# ---------------------------------------------------------------------------
+# Formatters
+# ---------------------------------------------------------------------------
+
+
+def _text_format(record: dict[str, Any]) -> str:
+    """Human-friendly single-line format with contextual fields appended."""
+    extra = record.get("extra", {}) or {}
+    ctx_parts = []
+    rid = extra.get("request_id")
+    if rid:
+        ctx_parts.append(f"rid={rid}")
+    prov = extra.get("provider")
+    if prov:
+        ctx_parts.append(f"prov={prov}")
+    event = extra.get("event")
+    if event:
+        ctx_parts.append(f"event={event}")
+    elapsed = extra.get("elapsed_ms")
+    if elapsed is not None:
+        try:
+            ctx_parts.append(f"elapsed_ms={float(elapsed):.2f}")
+        except Exception:
+            ctx_parts.append(f"elapsed_ms={elapsed}")
+    ctx = f" [{' '.join(ctx_parts)}]" if ctx_parts else ""
+
+    # Note: loguru sink receives the already-formatted {message}.  The format
+    # string is parsed by loguru, so we must escape curly braces in user data
+    # elsewhere — but here we return a plain template string.
+    level = record["level"].name
+    time_str = record["time"].strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]
+    name = record["name"]
+    msg = record["message"]
+    return f"{time_str} | {level:<7} | {name}{ctx} | {msg}\n"
+
+
+def _json_serialize(record: dict[str, Any]) -> str:
+    """Serialize a loguru record into one-line JSON.
+
+    Flat schema matching the documented field contract so both humans and
+    LLMs can reliably grep / index.  Unknown fields from ``extra`` are kept
+    under a ``payload`` sub-object to avoid polluting the top level.
+    """
+    extra = dict(record.get("extra") or {})
+    top: dict[str, Any] = {
+        "ts": record["time"].isoformat(),
+        "level": record["level"].name,
+        "module": record["name"],
+        "message": record["message"],
+    }
+    # Elevate well-known fields to top level.
+    for key in _CONTEXT_FIELDS:
+        if key in extra and extra[key] is not None:
+            top[key] = extra.pop(key)
+    # Exception info.
+    exc = record.get("exception")
+    if exc is not None:
+        top["exception"] = {
+            "type": exc.type.__name__ if exc.type else None,
+            "value": str(exc.value) if exc.value else None,
+        }
+    if extra:
+        # Remaining unknown extras are preserved so nothing is silently lost.
+        top["payload"] = extra
+    try:
+        return json.dumps(top, ensure_ascii=False, default=str) + "\n"
+    except Exception as e:
+        # Fallback — never let logging crash the app.
+        return json.dumps(
+            {"ts": top["ts"], "level": "ERROR", "module": "openspeech.logging_config",
+             "message": f"log serialize failed: {e!r}"},
+            ensure_ascii=False,
+        ) + "\n"
+
+
+def _make_console_sink(fmt: str) -> Any:
+    """Return a loguru sink callable that writes to stderr."""
+    if fmt == "json":
+        def _sink(message):
+            sys.stderr.write(_json_serialize(message.record))
+        return _sink
+    # text
+    def _sink(message):
+        sys.stderr.write(_text_format(message.record))
+    return _sink
+
+
+def _make_file_sink_path(log_dir: Path, log_file_name: str) -> Path:
+    log_dir.mkdir(parents=True, exist_ok=True)
+    return log_dir / log_file_name
+
+
+def _attach_jsonl_file_sink(
+    *,
+    file_path: Path,
+    level: str,
+    rotation: str,
+    retention: str,
+) -> None:
+    """Attach a loguru sink that writes structured JSONL with rotation.
+
+    We use loguru's built-in file sink (so rotation / retention / enqueue
+    all continue to work), but route the record through a patcher that
+    stashes the serialized JSON string under ``extra["_jsonl"]`` and
+    renders it via a plain ``{extra[_jsonl]}`` template.  This avoids
+    loguru's format engine misinterpreting ``{"ts":...}`` braces as
+    template placeholders.
+    """
+    def _patcher(record):
+        record["extra"]["_jsonl"] = _json_serialize(record).rstrip("\n")
+
+    sink_id = _root_logger.add(
+        str(file_path),
+        level=level,
+        rotation=rotation,
+        retention=retention,
+        enqueue=True,  # don't block the event loop on disk IO
+        backtrace=False,
+        diagnose=False,
+        serialize=False,
+        format="{extra[_jsonl]}",
+        filter=lambda record: (_patcher(record) or True),
+    )
+    _OS_SINK_IDS.append(sink_id)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def _level_from_env(default: str) -> str:
+    return (os.environ.get("OPENSPEECH_LOG_LEVEL") or default).upper()
+
+
+def _format_from_env(default: str) -> str:
+    v = (os.environ.get("OPENSPEECH_LOG_FORMAT") or default).lower()
+    return v if v in _LOG_FORMATS else default
+
+
+def _perf_from_env(default: str) -> str:
+    v = (os.environ.get("OPENSPEECH_LOG_PERF") or default).lower()
+    return v if v in _PERF_LEVELS else default
+
+
+def _log_dir_from_env(default: Path | None) -> Path | None:
+    raw = os.environ.get("OPENSPEECH_LOG_DIR")
+    if raw:
+        return Path(raw).expanduser()
+    return default
+
+
+def configure_logging(
+    *,
+    level: str | None = None,
+    format: str | None = None,
+    log_dir: str | Path | None = None,
+    log_file_name: str | None = None,
+    perf: str | None = None,
+    color: bool | None = None,
+    rotation: str | None = None,
+    retention: str | None = None,
+    default_log_dir: str | Path | None = "logs",
+) -> LogSettings:
+    """Configure loguru globally. Idempotent — safe to call repeatedly.
+
+    Precedence (highest wins): explicit kwarg → env var → default.
+
+    ``default_log_dir`` controls where the JSONL file is written when no
+    explicit ``log_dir`` is provided. Pass ``None`` to disable file output
+    by default.  Pass ``""`` (empty string) from the CLI to disable
+    explicitly.
+    """
+    resolved_level = (level or _level_from_env("INFO")).upper()
+    resolved_format = (format or _format_from_env("text")).lower()
+    resolved_perf = (perf or _perf_from_env("basic")).lower()
+
+    # Resolve log_dir: explicit arg > env > default. Empty string disables.
+    if log_dir is None:
+        raw_dir = _log_dir_from_env(
+            Path(default_log_dir).expanduser() if default_log_dir else None
+        )
+    elif log_dir == "":
+        raw_dir = None
+    else:
+        raw_dir = Path(log_dir).expanduser()
+
+    if resolved_format not in _LOG_FORMATS:
+        resolved_format = "text"
+    if resolved_perf not in _PERF_LEVELS:
+        resolved_perf = "basic"
+
+    settings = LogSettings(
+        level=resolved_level,
+        format=resolved_format,
+        log_dir=raw_dir,
+        log_file_name=log_file_name or "openspeech.jsonl",
+        rotation=rotation or "50 MB",
+        retention=retention or "14 days",
+        perf=resolved_perf,
+        color=color,
+    )
+
+    # Remove any sinks we previously owned (do NOT touch host sinks).
+    _remove_os_sinks()
+
+    # If we're the only configurator, also strip loguru's default handler
+    # (id=0) so we don't double-log to stderr.  If a host is present, leave
+    # it alone.
+    if not _INTEGRATION["host_managed"]:
+        try:
+            _root_logger.remove(0)
+        except ValueError:
+            pass  # already removed
+
+    # Console sink — only when we own the output pipeline.
+    if not _INTEGRATION["host_managed"]:
+        sink_id = _root_logger.add(
+            _make_console_sink(settings.format),
+            level=settings.level,
+            enqueue=False,
+            backtrace=False,
+            diagnose=False,
+        )
+        _OS_SINK_IDS.append(sink_id)
+
+        # File sink (structured JSONL, rotated)
+        if settings.log_dir is not None:
+            try:
+                file_path = _make_file_sink_path(settings.log_dir, settings.log_file_name)
+                _attach_jsonl_file_sink(
+                    file_path=file_path,
+                    level=settings.level,
+                    rotation=settings.rotation,
+                    retention=settings.retention,
+                )
+            except Exception as e:
+                sys.stderr.write(f"[openspeech] failed to attach file log sink: {e}\n")
+
+    # Update module-level current settings.
+    global _CURRENT
+    _CURRENT = settings
+    return settings
+
+
+def _remove_os_sinks() -> None:
+    """Remove all sinks previously added by OpenSpeech (leave host sinks alone)."""
+    while _OS_SINK_IDS:
+        sink_id = _OS_SINK_IDS.pop()
+        try:
+            _root_logger.remove(sink_id)
+        except ValueError:
+            pass  # already removed
+
+
+def ensure_configured() -> LogSettings:
+    """Call ``configure_logging`` with defaults if it hasn't been called yet.
+
+    When a host application has already taken over via
+    :func:`integrate_with_host` (``host_managed=True``), this is a no-op —
+    we don't want to add sinks on top of the host's pipeline.
+    """
+    if _INTEGRATION["host_managed"]:
+        return _CURRENT
+    if not getattr(_CURRENT, "_applied", False):
+        s = configure_logging()
+        object.__setattr__(s, "_applied", True)
+        return s
+    return _CURRENT
+
+
+# ---------------------------------------------------------------------------
+# Host integration (let another loguru-based app own the sinks)
+# ---------------------------------------------------------------------------
+
+
+def integrate_with_host(
+    *,
+    tag: str = "openspeech",
+    level: str | None = None,
+    perf: str | None = None,
+    attach_sinks: bool = False,
+) -> LogSettings:
+    """Hand sink management over to a host application using loguru.
+
+    The host keeps its own sinks; OpenSpeech only guarantees that every
+    record it emits carries ``record.extra["component"] == tag`` so the
+    host can format, filter, or route those records.
+
+    Parameters
+    ----------
+    tag
+        Value written into ``record.extra["component"]`` for every
+        OpenSpeech log.  Defaults to ``"openspeech"``.
+    level
+        Minimum level applied *only to OpenSpeech records*.  This is
+        enforced at sink time via :func:`openspeech_level_filter`, so the
+        host's own log level is unaffected.  ``None`` keeps whatever the
+        host sink decides.
+    perf
+        Performance milestone verbosity (``off`` / ``basic`` / ``verbose``)
+        — independent of the host's log level.
+    attach_sinks
+        When ``False`` (default) OpenSpeech adds no sinks of its own; the
+        host is expected to have already registered at least one.  Set to
+        ``True`` to keep the built-in stderr + JSONL sinks *in addition*
+        to the host's sinks (rarely useful; provided as an escape hatch).
+
+    Returns
+    -------
+    LogSettings
+        The resolved settings; also stored on the module for
+        :func:`get_log_settings` to return.
+    """
+    _INTEGRATION["tag"] = tag
+    _INTEGRATION["level"] = level.upper() if level else None
+    _INTEGRATION["host_managed"] = not attach_sinks
+
+    global _CURRENT
+    _CURRENT = LogSettings(
+        level=(level.upper() if level else _CURRENT.level),
+        format=_CURRENT.format,
+        log_dir=_CURRENT.log_dir,
+        log_file_name=_CURRENT.log_file_name,
+        rotation=_CURRENT.rotation,
+        retention=_CURRENT.retention,
+        perf=(perf.lower() if perf else _CURRENT.perf),
+        color=_CURRENT.color,
+    )
+    object.__setattr__(_CURRENT, "_applied", True)
+
+    if attach_sinks:
+        # Keep our sinks *in addition to* host sinks.  Call the normal
+        # configure path, but the _INTEGRATION["host_managed"] gate is
+        # already off so sinks get added.
+        _INTEGRATION["host_managed"] = False
+        configure_logging(
+            level=_CURRENT.level,
+            format=_CURRENT.format,
+            perf=_CURRENT.perf,
+        )
+    else:
+        # Host is fully in control — drop any sinks we own.
+        _remove_os_sinks()
+
+    return _CURRENT
+
+
+def openspeech_filter(record: dict[str, Any]) -> bool:
+    """Loguru ``filter`` that matches only OpenSpeech records.
+
+    Usage (host side)::
+
+        logger.add("openspeech.log", filter=openspeech_filter)
+    """
+    return record.get("extra", {}).get("component") == _INTEGRATION["tag"]
+
+
+def openspeech_level_filter(min_level: str) -> Callable[[dict[str, Any]], bool]:
+    """Return a sink filter that enforces ``min_level`` *only* for OpenSpeech records.
+
+    Non-OpenSpeech records pass through unchanged — use this on a shared
+    host sink that receives both host and OpenSpeech logs but should apply
+    a different threshold to OpenSpeech.
+
+    Usage (host side)::
+
+        logger.add("wallex.log", filter=openspeech_level_filter("WARNING"))
+    """
+    target = min_level.upper()
+    # Resolve threshold once — loguru levels don't change at runtime.
+    try:
+        threshold_no = _root_logger.level(target).no
+    except Exception:
+        threshold_no = 20  # INFO fallback
+
+    def _filter(record: dict[str, Any]) -> bool:
+        if record.get("extra", {}).get("component") != _INTEGRATION["tag"]:
+            return True  # host records bypass
+        return record["level"].no >= threshold_no
+
+    return _filter
+
+
+def get_integration_tag() -> str:
+    """Return the current component tag used for OpenSpeech records."""
+    return _INTEGRATION["tag"]
+
+
+def is_host_managed() -> bool:
+    """Return True if a host application has taken over sink management."""
+    return bool(_INTEGRATION["host_managed"])
+
+
+__all__ = [
+    "LogSettings",
+    "bind_context",
+    "configure_logging",
+    "ensure_configured",
+    "get_integration_tag",
+    "get_log_settings",
+    "get_request_id",
+    "get_session_id",
+    "integrate_with_host",
+    "is_host_managed",
+    "logger",
+    "openspeech_filter",
+    "openspeech_level_filter",
+]