Metadata-Version: 2.4
Name: quietplace
Version: 0.2.5
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<3,>=1.26
Requires-Dist: scipy<2,>=1.11
Requires-Dist: soundfile<1,>=0.12
Requires-Dist: pandas<4,>=2.1
Requires-Dist: matplotlib<4,>=3.8
Requires-Dist: requests<3,>=2.31
Requires-Dist: openai<3,>=1.40
Requires-Dist: tqdm<5,>=4.66
Provides-Extra: ast
Requires-Dist: torch<3,>=2.8; extra == "ast"
Requires-Dist: torchvision<1,>=0.23; extra == "ast"
Requires-Dist: torchaudio<3,>=2.8; extra == "ast"
Requires-Dist: transformers<6,>=5.8.1; extra == "ast"
Requires-Dist: accelerate<2,>=1.11; extra == "ast"
Requires-Dist: safetensors<1,>=0.6; extra == "ast"
Provides-Extra: gemma
Requires-Dist: torch<3,>=2.8; extra == "gemma"
Requires-Dist: transformers<6,>=5.8.1; extra == "gemma"
Requires-Dist: accelerate<2,>=1.11; extra == "gemma"
Requires-Dist: huggingface_hub<1,>=0.36; extra == "gemma"
Requires-Dist: safetensors<1,>=0.6; extra == "gemma"
Provides-Extra: notebook
Requires-Dist: ipython<10,>=9; extra == "notebook"
Requires-Dist: scikit-learn<2,>=1.6; extra == "notebook"
Provides-Extra: test
Requires-Dist: pytest<9,>=8; 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)

