quietplace 0.2.2__tar.gz

quietplace-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aliaksei Kaliutau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quietplace-0.2.2/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: quietplace
+Version: 0.2.2
+Summary: Semantic noise suppression demo controlled by Gemma/Gemma-compatible models served through vLLM.
+Author: Aliaksei Kaliutau
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11
+Requires-Dist: soundfile>=0.12
+Requires-Dist: pandas>=2.1
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: openai>=1.40
+Requires-Dist: torch>=2.2
+Requires-Dist: transformers>=4.43
+Requires-Dist: tqdm>=4.66
+Provides-Extra: serve
+Requires-Dist: vllm>=0.6; extra == "serve"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Requires-Dist: pytest>=8.2; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Dynamic: license-file
+
+# QuietPlace vLLM 
+
+QuietPlace is a package for safety-aware semantic noise suppression. 
+The package keeps the AST event classifier, deterministic DSP executor, metrics, and plotting code as a reusable Python library, 
+then uses a Jupyter notebook as the public demo surface.
+
+Gemma/Gemma-compatible inference is called through a **vLLM OpenAI-compatible server**.
+
+## Chapter 0 — Install the package
+
+1. Clone the repository
+
+```bash
+git clone https://github.com/akaliutau/quietplace.git
+cd quietplace
+```
+
+2. Create and activate a Conda environment
+
+```bash
+conda create -n quietplace python=3.12 -y
+conda activate quietplace
+```
+
+3. Install dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+## Chapter 1 — Put the trained AST classifier in the hard-coded location
+
+The demo assumes the AST classifier is already trained and exported with `save_pretrained()`.
+
+Hard-coded pointer:
+
+```text
+/kaggle/input/quietplace-policy-ast/quietplace_policy_ast
+```
+
+This is defined in:
+
+```text
+quietplace/config.py
+```
+
+Expected contents:
+
+```text
+config.json
+model.safetensors or pytorch_model.bin
+preprocessor_config.json
+policy_map.json        # optional but recommended
+```
+
+## Chapter 2 — Start vLLM instead of Ollama
+
+Example local server:
+
+```bash
+vllm serve google/gemma-4-e2b-it \
+  --host 0.0.0.0 \
+  --port 8000 \
+  --dtype auto \
+  --api-key EMPTY
+```
+
+The package calls:
+
+```text
+http://localhost:8000/v1/chat/completions
+```
+
+via the official `openai` Python client. If your vLLM model/tool parser does not support native tool calls, 
+the controller falls back to JSON parsing and the deterministic DSP executor still only runs whitelisted actions.
+
+## Chapter 3 — Create a realistic demo input
+
+Best competition input: combine held-out dataset clips so the demo has known ground-truth segments.
+
+```bash
+quietplace make-demo-scene \
+  --traffic-path /datasets/fsd50k/traffic_heldout.wav \
+  --siren-path /datasets/urbansound8k/fold10/siren_heldout.wav \
+  --speech-path /data/recorded_help.wav \
+  --out data/demo_scene
+```
+
+No dataset files available? Use the deterministic synthetic fallback:
+
+```bash
+quietplace make-demo-scene --out data/demo_scene
+```
+
+Outputs:
+
+```text
+data/demo_scene/quietplace_realistic_demo_scene.wav
+data/demo_scene/events_demo.json
+data/demo_scene/scene_manifest.json
+```
+
+## Chapter 4 — Run the package pipeline
+
+With the generated event table:
+
+```bash
+quietplace run data/demo_scene/quietplace_realistic_demo_scene.wav \
+  --events-json data/demo_scene/events_demo.json \
+  --backend auto \
+  --vllm-base-url http://localhost:8000/v1 \
+  --vllm-api-key EMPTY \
+  --vllm-model google/gemma-4-e2b-it \
+  --out runs/quietplace_demo
+```
+
+To force vLLM and fail if the server is down:
+
+```bash
+quietplace run data/demo_scene/quietplace_realistic_demo_scene.wav \
+  --events-json data/demo_scene/events_demo.json \
+  --backend vllm \
+  --out runs/quietplace_demo
+```
+
+Outputs:
+
+```text
+runs/quietplace_demo/original.wav
+runs/quietplace_demo/suppressed.wav
+runs/quietplace_demo/events.json
+runs/quietplace_demo/controller_policy.json
+runs/quietplace_demo/features.json
+runs/quietplace_demo/segment_metrics.csv
+runs/quietplace_demo/bandpower_metrics.csv
+runs/quietplace_demo/metrics_summary.json
+```
+
+## Chapter 5 — Generate charts for the video/writeup
+
+```bash
+quietplace charts data/demo_scene/quietplace_realistic_demo_scene.wav \
+  --events-json data/demo_scene/events_demo.json \
+  --backend auto \
+  --out runs/quietplace_demo \
+  --charts-out runs/quietplace_demo/charts
+```
+
+Charts:
+
+```text
+01_before_after_spectrograms.png
+02_waveform_ab.png
+03_segment_metrics.png
+04_bandpower_metrics.png
+```
+
+## Chapter 6 — Create writeup chapters from the run
+
+```bash
+quietplace chapters \
+  --run-dir runs/quietplace_demo \
+  --out reports/chapters
+```
+
+This creates draft markdown chapters:
+
+```text
+reports/chapters/01_problem.md
+reports/chapters/02_architecture.md
+reports/chapters/03_results.md
+reports/chapters/04_demo_script.md
+```
+
+Use these as the structure for the Kaggle writeup and video narration.
+
+
+## Project structure
+
+```text
+quietplace/audio.py        # audio IO, event schema, spectral features
+quietplace/classifier.py   # hard-coded AST classifier wrapper
+quietplace/controller.py   # vLLM/OpenAI-compatible policy controller
+quietplace/dsp.py          # deterministic suppressor executor
+quietplace/metrics.py      # calm-zone and preservation metrics
+quietplace/viz.py          # notebook charts
+quietplace/demo_scene.py   # realistic scene builder / synthetic fallback
+quietplace/pipeline.py     # end-to-end orchestration
+quietplace/cli.py          # commands used above
+notebooks/00_quietplace_vllm_demo.ipynb
+```
+
+## Build and publish the package
+
+see the details in [publish.md](publish.md)
+

quietplace-0.2.2/README.md

@@ -0,0 +1,196 @@
+# QuietPlace vLLM 
+
+QuietPlace is a package for safety-aware semantic noise suppression. 
+The package keeps the AST event classifier, deterministic DSP executor, metrics, and plotting code as a reusable Python library, 
+then uses a Jupyter notebook as the public demo surface.
+
+Gemma/Gemma-compatible inference is called through a **vLLM OpenAI-compatible server**.
+
+## Chapter 0 — Install the package
+
+1. Clone the repository
+
+```bash
+git clone https://github.com/akaliutau/quietplace.git
+cd quietplace
+```
+
+2. Create and activate a Conda environment
+
+```bash
+conda create -n quietplace python=3.12 -y
+conda activate quietplace
+```
+
+3. Install dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+## Chapter 1 — Put the trained AST classifier in the hard-coded location
+
+The demo assumes the AST classifier is already trained and exported with `save_pretrained()`.
+
+Hard-coded pointer:
+
+```text
+/kaggle/input/quietplace-policy-ast/quietplace_policy_ast
+```
+
+This is defined in:
+
+```text
+quietplace/config.py
+```
+
+Expected contents:
+
+```text
+config.json
+model.safetensors or pytorch_model.bin
+preprocessor_config.json
+policy_map.json        # optional but recommended
+```
+
+## Chapter 2 — Start vLLM instead of Ollama
+
+Example local server:
+
+```bash
+vllm serve google/gemma-4-e2b-it \
+  --host 0.0.0.0 \
+  --port 8000 \
+  --dtype auto \
+  --api-key EMPTY
+```
+
+The package calls:
+
+```text
+http://localhost:8000/v1/chat/completions
+```
+
+via the official `openai` Python client. If your vLLM model/tool parser does not support native tool calls, 
+the controller falls back to JSON parsing and the deterministic DSP executor still only runs whitelisted actions.
+
+## Chapter 3 — Create a realistic demo input
+
+Best competition input: combine held-out dataset clips so the demo has known ground-truth segments.
+
+```bash
+quietplace make-demo-scene \
+  --traffic-path /datasets/fsd50k/traffic_heldout.wav \
+  --siren-path /datasets/urbansound8k/fold10/siren_heldout.wav \
+  --speech-path /data/recorded_help.wav \
+  --out data/demo_scene
+```
+
+No dataset files available? Use the deterministic synthetic fallback:
+
+```bash
+quietplace make-demo-scene --out data/demo_scene
+```
+
+Outputs:
+
+```text
+data/demo_scene/quietplace_realistic_demo_scene.wav
+data/demo_scene/events_demo.json
+data/demo_scene/scene_manifest.json
+```
+
+## Chapter 4 — Run the package pipeline
+
+With the generated event table:
+
+```bash
+quietplace run data/demo_scene/quietplace_realistic_demo_scene.wav \
+  --events-json data/demo_scene/events_demo.json \
+  --backend auto \
+  --vllm-base-url http://localhost:8000/v1 \
+  --vllm-api-key EMPTY \
+  --vllm-model google/gemma-4-e2b-it \
+  --out runs/quietplace_demo
+```
+
+To force vLLM and fail if the server is down:
+
+```bash
+quietplace run data/demo_scene/quietplace_realistic_demo_scene.wav \
+  --events-json data/demo_scene/events_demo.json \
+  --backend vllm \
+  --out runs/quietplace_demo
+```
+
+Outputs:
+
+```text
+runs/quietplace_demo/original.wav
+runs/quietplace_demo/suppressed.wav
+runs/quietplace_demo/events.json
+runs/quietplace_demo/controller_policy.json
+runs/quietplace_demo/features.json
+runs/quietplace_demo/segment_metrics.csv
+runs/quietplace_demo/bandpower_metrics.csv
+runs/quietplace_demo/metrics_summary.json
+```
+
+## Chapter 5 — Generate charts for the video/writeup
+
+```bash
+quietplace charts data/demo_scene/quietplace_realistic_demo_scene.wav \
+  --events-json data/demo_scene/events_demo.json \
+  --backend auto \
+  --out runs/quietplace_demo \
+  --charts-out runs/quietplace_demo/charts
+```
+
+Charts:
+
+```text
+01_before_after_spectrograms.png
+02_waveform_ab.png
+03_segment_metrics.png
+04_bandpower_metrics.png
+```
+
+## Chapter 6 — Create writeup chapters from the run
+
+```bash
+quietplace chapters \
+  --run-dir runs/quietplace_demo \
+  --out reports/chapters
+```
+
+This creates draft markdown chapters:
+
+```text
+reports/chapters/01_problem.md
+reports/chapters/02_architecture.md
+reports/chapters/03_results.md
+reports/chapters/04_demo_script.md
+```
+
+Use these as the structure for the Kaggle writeup and video narration.
+
+
+## Project structure
+
+```text
+quietplace/audio.py        # audio IO, event schema, spectral features
+quietplace/classifier.py   # hard-coded AST classifier wrapper
+quietplace/controller.py   # vLLM/OpenAI-compatible policy controller
+quietplace/dsp.py          # deterministic suppressor executor
+quietplace/metrics.py      # calm-zone and preservation metrics
+quietplace/viz.py          # notebook charts
+quietplace/demo_scene.py   # realistic scene builder / synthetic fallback
+quietplace/pipeline.py     # end-to-end orchestration
+quietplace/cli.py          # commands used above
+notebooks/00_quietplace_vllm_demo.ipynb
+```
+
+## Build and publish the package
+
+see the details in [publish.md](publish.md)
+

quietplace-0.2.2/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "quietplace"
+version = "0.2.2"
+description = "Semantic noise suppression demo controlled by Gemma/Gemma-compatible models served through vLLM."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Aliaksei Kaliutau" }]
+dependencies = [
+  "numpy>=1.26",
+  "scipy>=1.11",
+  "soundfile>=0.12",
+  "pandas>=2.1",
+  "matplotlib>=3.8",
+  "openai>=1.40",
+  "torch>=2.2",
+  "transformers>=4.43",
+  "tqdm>=4.66",
+]
+
+[project.optional-dependencies]
+serve = [
+  "vllm>=0.6",
+]
+dev = [
+  "build>=1.2",
+  "twine>=5.1",
+  "pytest>=8.2",
+]
+test = [
+    "pytest>=8.0",
+]
+
+[project.scripts]
+quietplace = "quietplace.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["quietplace*"]
+
+[tool.pytest.ini_options]
+pythonpath = [".", "quietplace"]
+testpaths = ["tests"]

quietplace-0.2.2/quietplace/__init__.py

@@ -0,0 +1,7 @@
+"""quiteplace: notebook-first semantic noise suppression."""
+
+from .audio import Event
+from .pipeline import run_pipeline
+
+__all__ = ["Event", "run_pipeline"]
+__version__ = "0.2.0"

quietplace-0.2.2/quietplace/audio.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any, Iterable
+
+import numpy as np
+import soundfile as sf
+from scipy import signal
+
+from .config import PROTECTED_LABELS, SR, SUPPRESSIBLE_LABELS
+
+
+@dataclass(slots=True)
+class Event:
+    label: str
+    start: float
+    end: float
+    confidence: float
+    policy_hint: str = "uncertain"
+    source: str = "classifier"
+
+    def as_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, row: dict[str, Any]) -> "Event":
+        return cls(
+            label=str(row.get("label", "unknown")),
+            start=float(row.get("start", 0.0)),
+            end=float(row.get("end", 0.0)),
+            confidence=float(row.get("confidence", 0.0)),
+            policy_hint=infer_policy(str(row.get("label", "unknown")), str(row.get("policy_hint", row.get("policy", "uncertain")))),
+            source=str(row.get("source", "json")),
+        )
+
+
+def infer_policy(label: str, fallback: str = "uncertain") -> str:
+    normalized = normalize_label(label)
+    if normalized in PROTECTED_LABELS:
+        return "preserve"
+    if normalized in SUPPRESSIBLE_LABELS:
+        return "suppress"
+    return fallback if fallback in {"preserve", "suppress", "uncertain"} else "uncertain"
+
+
+def normalize_label(label: str) -> str:
+    return "_".join(str(label).strip().lower().replace("/", " ").replace("-", " ").split())
+
+
+def normalize(y: np.ndarray, peak: float = 0.98) -> np.ndarray:
+    y = np.asarray(y, dtype=np.float32).reshape(-1)
+    m = float(np.max(np.abs(y))) if y.size else 0.0
+    if m <= 1e-9:
+        return y.astype(np.float32)
+    return (y / m * float(peak)).astype(np.float32)
+
+
+def to_mono(y: np.ndarray) -> np.ndarray:
+    y = np.asarray(y, dtype=np.float32)
+    if y.ndim == 1:
+        return y
+    return y.mean(axis=1).astype(np.float32)
+
+
+def resample_audio(y: np.ndarray, sr: int, target_sr: int = SR) -> np.ndarray:
+    if int(sr) == int(target_sr):
+        return y.astype(np.float32)
+    g = math.gcd(int(sr), int(target_sr))
+    up = int(target_sr) // g
+    down = int(sr) // g
+    return signal.resample_poly(y, up, down).astype(np.float32)
+
+
+def load_audio(path: str | Path, sr: int = SR, peak: float | None = None) -> tuple[np.ndarray, int]:
+    y, source_sr = sf.read(str(path), always_2d=False)
+    y = to_mono(y)
+    y = resample_audio(y, int(source_sr), sr)
+    if peak is not None:
+        y = normalize(y, peak=peak)
+    return y.astype(np.float32), sr
+
+
+def write_audio(path: str | Path, y: np.ndarray, sr: int = SR) -> None:
+    Path(path).parent.mkdir(parents=True, exist_ok=True)
+    sf.write(str(path), np.asarray(y, dtype=np.float32), sr)
+
+
+def fit_audio(y: np.ndarray, n_samples: int) -> np.ndarray:
+    y = np.asarray(y, dtype=np.float32).reshape(-1)
+    if y.size >= n_samples:
+        return y[:n_samples]
+    return np.pad(y, (0, n_samples - y.size)).astype(np.float32)
+
+
+def paste_clip(base: np.ndarray, clip: np.ndarray, sr: int, start_sec: float, gain: float = 1.0) -> np.ndarray:
+    out = np.asarray(base, dtype=np.float32).copy()
+    start = max(0, int(round(float(start_sec) * sr)))
+    if start >= len(out):
+        return out
+    end = min(len(out), start + len(clip))
+    out[start:end] += float(gain) * clip[: end - start]
+    return out.astype(np.float32)
+
+
+def read_events_json(path: str | Path) -> list[Event]:
+    data = json.loads(Path(path).read_text())
+    if isinstance(data, dict) and "events" in data:
+        data = data["events"]
+    return [Event.from_dict(row) for row in data]
+
+
+def write_events_json(path: str | Path, events: Iterable[Event]) -> None:
+    Path(path).parent.mkdir(parents=True, exist_ok=True)
+    Path(path).write_text(json.dumps([e.as_dict() for e in events], indent=2))
+
+
+def dominant_freqs(y: np.ndarray, sr: int = SR, max_count: int = 6) -> list[float]:
+    y = np.asarray(y, dtype=np.float32)
+    if y.size < 64:
+        return []
+    nperseg = min(4096, max(256, len(y)))
+    freqs, psd = signal.welch(y, fs=sr, nperseg=nperseg)
+    band = (freqs >= 40) & (freqs <= 1000)
+    if not np.any(band):
+        return []
+    bf = freqs[band]
+    bp = psd[band]
+    distance = max(1, int(35 / (bf[1] - bf[0]))) if len(bf) > 1 else 1
+    peaks, props = signal.find_peaks(bp, distance=distance, prominence=np.max(bp) * 0.02 if len(bp) else 0.0)
+    if len(peaks) == 0:
+        idx = np.argsort(bp)[-max_count:]
+    else:
+        idx = peaks[np.argsort(bp[peaks])[-max_count:]]
+    vals = sorted(float(round(bf[i], 1)) for i in idx)
+    return vals
+
+
+def band_energy(y: np.ndarray, sr: int, low_hz: float, high_hz: float) -> float:
+    y = np.asarray(y, dtype=np.float32)
+    if y.size < 64:
+        return 0.0
+    freqs, psd = signal.welch(y, fs=sr, nperseg=min(4096, len(y)))
+    mask = (freqs >= float(low_hz)) & (freqs <= float(high_hz))
+    return float(psd[mask].sum() + 1e-12)
+
+
+def spectral_features(y: np.ndarray, sr: int = SR) -> dict[str, Any]:
+    y = np.asarray(y, dtype=np.float32)
+    if y.size == 0:
+        return {"duration_sec": 0.0, "rms": 0.0, "peak": 0.0, "dominant_freqs_hz": []}
+    freqs, psd = signal.welch(y, fs=sr, nperseg=min(4096, len(y)))
+    total = float(psd.sum() + 1e-12)
+    low = float(psd[(freqs >= 40) & (freqs <= 300)].sum() / total)
+    mid = float(psd[(freqs > 300) & (freqs <= 2000)].sum() / total)
+    high = float(psd[freqs > 2000].sum() / total)
+    rms = float(np.sqrt(np.mean(y * y) + 1e-12))
+    return {
+        "duration_sec": round(len(y) / sr, 3),
+        "rms": round(rms, 6),
+        "peak": round(float(np.max(np.abs(y))), 6),
+        "low_band_energy_share_40_300hz": round(low, 4),
+        "mid_band_energy_share_300_2000hz": round(mid, 4),
+        "high_band_energy_share_2000hz_plus": round(high, 4),
+        "dominant_freqs_hz": dominant_freqs(y, sr),
+    }
+
+
+def protected_mask(n_samples: int, sr: int, protected: Iterable[tuple[float, float] | list[float]]) -> np.ndarray:
+    mask = np.zeros(int(n_samples), dtype=bool)
+    for start, end in protected:
+        a = max(0, min(int(n_samples), int(round(float(start) * sr))))
+        b = max(0, min(int(n_samples), int(round(float(end) * sr))))
+        if b > a:
+            mask[a:b] = True
+    return mask
+
+
+def segment_mask(n_samples: int, sr: int, segments: Iterable[tuple[float, float] | list[float]]) -> np.ndarray:
+    mask = np.zeros(int(n_samples), dtype=bool)
+    for start, end in segments:
+        a = max(0, min(int(n_samples), int(round(float(start) * sr))))
+        b = max(0, min(int(n_samples), int(round(float(end) * sr))))
+        if b > a:
+            mask[a:b] = True
+    return mask