audient 0.1.0__py3-none-any.whl

audient/_cli.py

@@ -0,0 +1,58 @@
+"""Console-script entry point.
+
+Prints a "loading" line before importing anything heavy so users see
+feedback within the first tick, then imports the real ``server.main``.
+Module-top imports in ``server`` pull in librosa, torch (via
+transformers), fastapi, uvicorn, and fastmcp — collectively 1–3 seconds
+of import time on a warm cache, longer on cold. Without this bootstrap
+the user stares at a blank prompt for the full duration and can't tell
+if the process is doing anything.
+
+Also parses --log-level / --quiet / --verbose EARLY (before the heavy
+imports) so logging.getLogger(...) calls at module-import time already
+respect the user's chosen level. Otherwise their first N log lines
+would use whatever level the default logger picked up, then flip mid-
+boot when server.main() re-configures.
+"""
+from __future__ import annotations
+
+import argparse
+import logging
+
+from .logs import configure, resolve_level
+
+
+def _peek_log_flags() -> tuple[str | None, bool, bool]:
+    """Extract just the log-related flags from sys.argv without
+    committing to the full CLI parser (which lives in server.py and
+    can't be imported yet — that would defeat the deferred-import
+    point of this bootstrap)."""
+    p = argparse.ArgumentParser(add_help=False)
+    p.add_argument("--log-level", default=None)
+    p.add_argument("-q", "--quiet", action="store_true", default=False)
+    p.add_argument("-v", "--verbose", action="store_true", default=False)
+    args, _ = p.parse_known_args()
+    return args.log_level, args.quiet, args.verbose
+
+
+def main() -> None:
+    cli_level, quiet, verbose = _peek_log_flags()
+    configure(level=resolve_level(
+        cli_level=cli_level, quiet=quiet, verbose=verbose,
+    ))
+    logger = logging.getLogger("audient")
+    logger.info(
+        "audient: loading (Python deps take a moment; "
+        "first run also downloads ~600MB of model weights)…"
+    )
+    # Best-effort flush so the loading line reaches the terminal
+    # before ~2s of blocking `from .server import ...` begins.
+    for h in logging.getLogger().handlers:
+        try:
+            h.flush()
+        except Exception:
+            pass
+
+    from .server import main as _server_main
+
+    _server_main()

audient/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

audient/cleaning.py

@@ -0,0 +1,104 @@
+"""Cleaning ops. Every op takes (samples, sample_rate) and returns new
+samples — the store layer (or `invoke_specialist`) wraps results."""
+
+from __future__ import annotations
+
+import librosa
+import numpy as np
+from scipy.signal import butter, sosfiltfilt
+
+
+def bandpass(y: np.ndarray, sr: int, lo_hz: float, hi_hz: float, order: int = 4) -> np.ndarray:
+    nyq = sr / 2
+    lo = max(lo_hz, 1.0) / nyq
+    hi = min(hi_hz, nyq - 1.0) / nyq
+    if not 0 < lo < hi < 1:
+        raise ValueError(f"invalid band: lo={lo_hz} hi={hi_hz} sr={sr}")
+    sos = butter(order, [lo, hi], btype="band", output="sos")
+    return sosfiltfilt(sos, y).astype(y.dtype, copy=False)
+
+
+def normalize(y: np.ndarray, method: str = "peak", target_dbfs: float = -3.0) -> np.ndarray:
+    """Normalize amplitude. `peak` scales the absolute maximum to `target_dbfs`
+    (default -3 dB to leave headroom); `rms` scales RMS to `target_dbfs`."""
+    target = 10 ** (target_dbfs / 20.0)
+    if method == "peak":
+        peak = float(np.max(np.abs(y)))
+        if peak < 1e-12:
+            return y
+        return (y * (target / peak)).astype(y.dtype, copy=False)
+    if method == "rms":
+        rms = float(np.sqrt(np.mean(y**2)))
+        if rms < 1e-12:
+            return y
+        return (y * (target / rms)).astype(y.dtype, copy=False)
+    raise ValueError(f"unknown normalize method: {method!r} (use 'peak' or 'rms')")
+
+
+def hpss(y: np.ndarray, sr: int, component: str = "both") -> tuple[np.ndarray, np.ndarray] | np.ndarray:
+    """Harmonic-Percussive Source Separation (librosa). Splits audio into:
+      - harmonic: tonal/sustained content (speech, music, sustained tones)
+      - percussive: transient/click-like content (knocks, footsteps, drums)
+
+    Useful when two overlapping sources fall into different timbral
+    categories — e.g., a doorbell ringing while someone is talking
+    (speech → harmonic; doorbell ring transients → percussive).
+
+    `component`:
+      - `"harmonic"`: return only the harmonic component.
+      - `"percussive"`: return only the percussive component.
+      - `"both"` (default): return (harmonic, percussive) as a tuple.
+    """
+    h, p = librosa.effects.hpss(y)
+    if component == "harmonic":
+        return h.astype(y.dtype, copy=False)
+    if component == "percussive":
+        return p.astype(y.dtype, copy=False)
+    if component == "both":
+        return h.astype(y.dtype, copy=False), p.astype(y.dtype, copy=False)
+    raise ValueError(f"hpss component must be 'harmonic', 'percussive', or 'both'; got {component!r}")
+
+
+def spectral_subtract(
+    signal: np.ndarray,
+    noise_profile: np.ndarray,
+    sr: int,
+    *,
+    over_subtraction: float = 1.0,
+    spectral_floor: float = 0.05,
+    n_fft: int = 2048,
+    hop_length: int = 512,
+) -> np.ndarray:
+    """Classic spectral subtraction. Given a noise-only window (`noise_profile`)
+    and a mixed signal window (`signal`), estimate the noise spectrum and
+    subtract it from the signal's magnitude spectrum bin-by-bin. Phase is
+    preserved from the signal.
+
+    Effective when:
+      - The noise is approximately stationary (rain, HVAC hum, traffic).
+      - You can find a noise-only stretch in the recording to use as the
+        profile.
+
+    Less effective when:
+      - The "noise" is non-stationary (music, speech).
+      - The signal and noise share spectral bands tightly (two voices,
+        two broadband mechanical sources).
+
+    Params:
+      `over_subtraction`: multiplier on the noise estimate. 1.0 = plain
+        subtraction. Higher values suppress noise more aggressively but
+        introduce musical-noise artifacts.
+      `spectral_floor`: minimum residual ratio (0..1) — bins are floored at
+        `spectral_floor * |signal_bin|` to avoid sharp zeros that cause
+        artifacts. 0.05 is a conservative default.
+    """
+    S_sig = librosa.stft(signal.astype(np.float32), n_fft=n_fft, hop_length=hop_length)
+    S_noise = librosa.stft(noise_profile.astype(np.float32), n_fft=n_fft, hop_length=hop_length)
+    mag_sig = np.abs(S_sig)
+    phase_sig = np.angle(S_sig)
+    mag_noise = np.abs(S_noise).mean(axis=1, keepdims=True)
+    subtracted = mag_sig - over_subtraction * mag_noise
+    mag_clean = np.maximum(subtracted, spectral_floor * mag_sig)
+    S_clean = mag_clean * np.exp(1j * phase_sig)
+    y_clean = librosa.istft(S_clean, n_fft=n_fft, hop_length=hop_length, length=len(signal))
+    return y_clean.astype(signal.dtype, copy=False)

audient/features.py

@@ -0,0 +1,190 @@
+"""Symbolic feature extraction for audio clips.
+
+Functions accept a (samples, sample_rate) pair, never an audio_id — keeps
+this module testable without the store.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import librosa
+import numpy as np
+from scipy.signal import find_peaks
+
+
+def _round(x: float, n: int = 3) -> float:
+    return float(np.round(float(x), n))
+
+
+def spectral_peaks(y: np.ndarray, sr: int, top_n: int = 5) -> list[dict[str, float]]:
+    if len(y) < 1024:
+        return []
+    spec = np.abs(np.fft.rfft(y * np.hanning(len(y))))
+    freqs = np.fft.rfftfreq(len(y), 1 / sr)
+    spec_db = 20 * np.log10(spec + 1e-12)
+    min_dist = max(5, int(50 / (sr / len(y))))
+    peaks, props = find_peaks(spec_db, prominence=6.0, distance=min_dist)
+    if len(peaks) == 0:
+        return []
+    order = np.argsort(props["prominences"])[::-1][:top_n]
+    return [
+        {
+            "freq_hz": _round(freqs[peaks[i]], 1),
+            "magnitude_db": _round(spec_db[peaks[i]] - spec_db.max(), 1),
+            "prominence_db": _round(props["prominences"][i], 1),
+        }
+        for i in order
+    ]
+
+
+def mains_hum(peaks: list[dict[str, float]]) -> dict[str, float] | None:
+    """Detect 50/60 Hz mains leakage including 2nd/3rd harmonics.
+
+    A harmonic peak alone is not sufficient evidence — male vocal F0
+    (~120–200 Hz) overlaps the 120/150/180 Hz harmonic bands. Only claim
+    a mains family when the fundamental (50 or 60 Hz) is also present
+    with non-trivial prominence."""
+    def near(freq: float, target: float, tol: float = 3.0) -> bool:
+        return abs(freq - target) <= tol
+
+    fund_50 = next((p for p in peaks if near(p["freq_hz"], 50) and p["prominence_db"] >= 6), None)
+    fund_60 = next((p for p in peaks if near(p["freq_hz"], 60) and p["prominence_db"] >= 6), None)
+    if not fund_50 and not fund_60:
+        return None
+
+    fundamental = fund_50 or fund_60
+    f0 = 50.0 if fund_50 else 60.0
+    harmonics = []
+    for mult in (2, 3, 4):
+        match = next((p for p in peaks if near(p["freq_hz"], f0 * mult)), None)
+        if match:
+            harmonics.append({"freq_hz": match["freq_hz"], "prominence_db": match["prominence_db"]})
+
+    return {
+        "fundamental_hz": fundamental["freq_hz"],
+        "prominence_db": fundamental["prominence_db"],
+        "family_hz": f0,
+        "harmonics": harmonics,
+    }
+
+
+def voicing(y: np.ndarray, sr: int) -> dict[str, float]:
+    """Two stable, interpretable voicing features:
+      - `harmonic_ratio`: fraction of signal energy in the harmonic (vs
+        percussive) component. Speech, sustained instruments, and bird songs
+        all read high here.
+      - `zero_crossing_rate`: time-domain rate of sign changes. Voiced speech
+        sits in ~0.02-0.15; fricatives and noise push it higher.
+
+    Computed on energetic frames only (silence trimmed) so pauses don't
+    suppress the harmonic ratio. For an actual speech-vs-not decision call
+    `vad` instead — it does frame-level analysis with proper segments.
+    """
+    y_trim, _ = librosa.effects.trim(y, top_db=30)
+    if len(y_trim) < sr // 10:
+        y_trim = y
+    harm, _ = librosa.effects.hpss(y_trim)
+    harm_ratio = float(np.sum(harm**2) / (np.sum(y_trim**2) + 1e-12))
+    zcr = float(librosa.feature.zero_crossing_rate(y_trim).mean())
+    return {
+        "harmonic_ratio": _round(harm_ratio),
+        "zero_crossing_rate": _round(zcr),
+    }
+
+
+def temporal_stability(y: np.ndarray, sr: int) -> dict[str, float]:
+    centroid_t = librosa.feature.spectral_centroid(y=y, sr=sr)[0]
+    rms_t = librosa.feature.rms(y=y, frame_length=2048, hop_length=512)[0]
+    rms_t_db = 20 * np.log10(rms_t + 1e-12)
+    half = len(y) // 2
+    peaks_a = spectral_peaks(y[:half], sr, top_n=1) if half > 1024 else []
+    peaks_b = spectral_peaks(y[half:], sr, top_n=1) if half > 1024 else []
+    peak_drift = (
+        abs(peaks_a[0]["freq_hz"] - peaks_b[0]["freq_hz"])
+        if peaks_a and peaks_b else 0.0
+    )
+    centroid_cv = float(centroid_t.std() / (centroid_t.mean() + 1e-12))
+    return {
+        "centroid_std_hz": _round(float(centroid_t.std()), 1),
+        "centroid_cv": _round(centroid_cv),
+        "rms_std_db": _round(float(rms_t_db.std()), 1),
+        "peak_drift_hz": _round(peak_drift, 1),
+    }
+
+
+def clipping_analysis(y: np.ndarray) -> dict[str, Any]:
+    """Plateau-based clipping detection. Single full-scale samples (a typical
+    normalized peak) don't count — real clipping holds the cap for multiple
+    consecutive samples because the original signal was above the cap and got
+    truncated to a flat line. 3-sample minimum follows pro-audio convention
+    (foobar2000; Adobe Audition uses 4). Returns the supporting data so the
+    agent can reason about borderline cases itself."""
+    at_full = np.abs(y) >= 0.999
+    n_clipped = int(at_full.sum())
+    fraction = float(n_clipped / len(y)) if len(y) else 0.0
+
+    longest_run = 0
+    cur = 0
+    for v in at_full:
+        if v:
+            cur += 1
+            if cur > longest_run:
+                longest_run = cur
+        else:
+            cur = 0
+
+    return {
+        "n_clipped_samples": n_clipped,
+        "fraction": _round(fraction, 6),
+        "longest_run_samples": int(longest_run),
+        "clipping_likely": bool(longest_run >= 3),
+    }
+
+
+def summarize(y: np.ndarray, sr: int) -> dict[str, Any]:
+    """High-level overview — what `summarize(audio_id)` returns."""
+    duration = len(y) / sr
+    peaks = spectral_peaks(y, sr, top_n=5)
+    rms = float(np.sqrt(np.mean(y**2)))
+    peak_amp = float(np.max(np.abs(y)))
+    frame_rms = librosa.feature.rms(y=y, frame_length=2048, hop_length=512)[0]
+    noise_floor_db = float(20 * np.log10(np.percentile(frame_rms, 10) + 1e-12))
+    signal_db = float(20 * np.log10(np.percentile(frame_rms, 95) + 1e-12))
+    return {
+        "duration_s": _round(duration, 2),
+        "sample_rate": int(sr),
+        "rms": _round(rms, 4),
+        "peak_amplitude": _round(peak_amp, 4),
+        "noise_floor_dbfs": _round(noise_floor_db, 1),
+        "snr_db": _round(signal_db - noise_floor_db, 1),
+        "dominant_peaks": peaks[:3],
+        "mains_hum": mains_hum(peaks),
+        "clipping": clipping_analysis(y),
+    }
+
+
+def spectrum(y: np.ndarray, sr: int) -> dict[str, Any]:
+    """What `spectrum(audio_id, ...)` returns."""
+    centroid = float(librosa.feature.spectral_centroid(y=y, sr=sr).mean())
+    rolloff = float(librosa.feature.spectral_rolloff(y=y, sr=sr, roll_percent=0.85).mean())
+    bandwidth = float(librosa.feature.spectral_bandwidth(y=y, sr=sr).mean())
+    flatness = float(librosa.feature.spectral_flatness(y=y).mean())
+    return {
+        "centroid_hz": _round(centroid, 1),
+        "rolloff_85pct_hz": _round(rolloff, 1),
+        "bandwidth_hz": _round(bandwidth, 1),
+        "flatness": _round(flatness),
+        "peaks": spectral_peaks(y, sr, top_n=5),
+        "temporal": temporal_stability(y, sr),
+    }
+
+
+def stats(y: np.ndarray, sr: int) -> dict[str, Any]:
+    """What `stats(audio_id, ...)` returns."""
+    kurt = float(((y - y.mean()) ** 4).mean() / (y.std() ** 4 + 1e-12) - 3)
+    return {
+        "rms": _round(float(np.sqrt(np.mean(y**2))), 4),
+        "kurtosis_excess": _round(kurt, 2),
+        "voicing": voicing(y, sr),
+    }

audient/logs.py

@@ -0,0 +1,128 @@
+"""Central logging setup.
+
+Every module that emits diagnostics does::
+
+    from audient.logs import get_logger
+    logger = get_logger(__name__)
+    logger.info("stream: CLAP loaded (17.4s)")
+
+Output shape (default INFO level)::
+
+    20:45:12.847 INFO     stream: CLAP loaded (17.4s)
+    20:45:13.201 WARNING  arbiter stop: RuntimeError: ...
+    20:45:13.202 ERROR    arbiter task died: cannot reuse coroutine
+
+`configure()` is called once from ``audient._cli`` (or by tests that
+need a specific level). Level resolution priority — first non-None
+wins:
+
+  1. explicit CLI arg (``--log-level``, ``--quiet``, ``--verbose``)
+  2. ``AUDIENT_LOG_LEVEL`` env var (case-insensitive)
+  3. default: ``INFO``
+
+Third-party loggers (fast-agent, uvicorn, httpx, transformers,
+huggingface_hub) get their own level set to WARNING unless the user
+opts into DEBUG — otherwise the transcript is dominated by their
+noise on every model load.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from typing import Literal
+
+_LEVELS = ("debug", "info", "warning", "error")
+LevelName = Literal["debug", "info", "warning", "error"]
+
+_configured = False
+
+
+def _level_from_name(name: str) -> int:
+    return getattr(logging, name.upper(), logging.INFO)
+
+
+def resolve_level(
+    *,
+    cli_level: str | None = None,
+    quiet: bool = False,
+    verbose: bool = False,
+) -> int:
+    """CLI > env > default. Returns a numeric logging level.
+
+    ``--quiet`` and ``--verbose`` are shortcuts. Explicit
+    ``--log-level`` overrides them if both are given.
+    """
+    if cli_level:
+        return _level_from_name(cli_level)
+    if quiet:
+        return logging.WARNING
+    if verbose:
+        return logging.DEBUG
+    env = os.environ.get("AUDIENT_LOG_LEVEL")
+    if env:
+        return _level_from_name(env)
+    return logging.INFO
+
+
+def configure(level: int = logging.INFO) -> None:
+    """Idempotent root-logger setup with a stderr handler.
+
+    Repeat calls change the level but do not attach duplicate handlers.
+    """
+    global _configured
+    root = logging.getLogger()
+    if not _configured:
+        handler = logging.StreamHandler(sys.stderr)
+        # `%(asctime)s` alone gives second-resolution; we want ms for
+        # perf diagnostics (model warm timings, ingestion cadence, arbiter
+        # decisions). Use `%(msecs)03.0f` on the same record for the
+        # sub-second slice.
+        handler.setFormatter(logging.Formatter(
+            fmt="%(asctime)s.%(msecs)03d %(levelname)-8s %(message)s",
+            datefmt="%H:%M:%S",
+        ))
+        root.addHandler(handler)
+        _configured = True
+    root.setLevel(level)
+
+    # Third-party noise: pin to WARNING unless we're in DEBUG. The
+    # user set the level on THEIR code — they don't want CLAP's
+    # tokenizer chatter or uvicorn's per-request access lines under
+    # a plain `--verbose`.
+    third_party_level = logging.DEBUG if level <= logging.DEBUG else logging.WARNING
+    for name in (
+        "uvicorn",
+        "uvicorn.error",
+        "uvicorn.access",
+        "httpx",
+        "httpcore",
+        "transformers",
+        "huggingface_hub",
+        "urllib3",
+        "asyncio",
+        # FastMCP / mcp SDK internal chatter. Per-request lines like
+        # "Processing request of type ListToolsRequest" and
+        # "Created new transport with session ID: <uuid>" and the
+        # classifier's periodic "Processing request of type
+        # PingRequest" all land here at INFO. Suppressed unless the
+        # user opts into DEBUG.
+        "mcp",
+        "mcp.server",
+        "mcp.server.lowlevel",
+        "mcp.server.streamable_http",
+        "fastmcp",
+        # fast-agent-mcp client side.
+        "fast_agent",
+    ):
+        logging.getLogger(name).setLevel(third_party_level)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Preferred accessor. Mirrors ``logging.getLogger`` — kept as a
+    thin re-export so we have a single import surface for future
+    migrations (e.g. structured logging)."""
+    return logging.getLogger(name)
+
+
+__all__ = ["configure", "get_logger", "resolve_level", "LevelName"]

audient/migrations/0001_session_id.sql

@@ -0,0 +1,31 @@
+-- Phase 02.4 Plan 03 — add session_id to the events table.
+--
+-- session_id is the wire-level discriminator that Phase 02.4 hard-codes
+-- to 'default' everywhere. Adding it as a NOT NULL column with a
+-- DEFAULT 'default' clause is the canonical SQLite ADD-COLUMN shape:
+-- atomic, backward-compatible (existing rows get the default), and
+-- preserves the events table's primary-key shape.
+--
+-- event_embeddings is a sqlite-vec `vec0` virtual table (see
+-- concept_memory._init_schema CREATE VIRTUAL TABLE ... USING vec0(...)).
+-- vec0 does NOT support ALTER. We track session_id via a sidecar
+-- table keyed by event_id, backfilled from the events table the
+-- first time this migration runs. event_embeddings_session is the
+-- canonical mapping; future queries that need the session id of an
+-- embedding row JOIN through this table.
+--
+-- Idempotence is guaranteed by the schema_migrations table in
+-- events_db.run_pending_migrations — each filename is recorded once
+-- on first apply, and a re-run is a no-op.
+
+ALTER TABLE events ADD COLUMN session_id TEXT NOT NULL DEFAULT 'default';
+
+CREATE INDEX IF NOT EXISTS events_session_id_idx ON events (session_id);
+
+CREATE TABLE IF NOT EXISTS event_embeddings_session (
+    event_id TEXT PRIMARY KEY,
+    session_id TEXT NOT NULL DEFAULT 'default'
+);
+
+INSERT OR IGNORE INTO event_embeddings_session (event_id, session_id)
+    SELECT event_id, 'default' FROM events;