audio-classifier-tool 1.2.0__py3-none-any.whl

audio_classifier_tool-1.2.0.dist-info/METADATA

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: audio-classifier-tool
+Version: 1.2.0
+Summary: Detect and cut target segments (ads by default) from audio, config-driven and LLM-verified
+Project-URL: Homepage, https://github.com/jon-fox/audio-classifier-tool
+Project-URL: Repository, https://github.com/jon-fox/audio-classifier-tool
+Author: Jon Fox
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ad-removal,ads,audio,classifier,podcast,whisper
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.13
+Requires-Dist: backoff>=2.2.1
+Requires-Dist: boto3>=1.40.21
+Requires-Dist: ctranslate2==4.8.2
+Requires-Dist: faster-whisper==1.2.1
+Requires-Dist: numpy>=2
+Requires-Dist: nvidia-cublas-cu12; sys_platform == 'linux'
+Requires-Dist: nvidia-cudnn-cu12==9.*; sys_platform == 'linux'
+Requires-Dist: openai>=2
+Requires-Dist: pydantic-ai-slim[openai]>=2
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: python-toon>=0.1.3
+Requires-Dist: requests>=2.32.5
+Requires-Dist: scikit-learn>=1.9.1
+Requires-Dist: soundfile>=0.14.0
+Description-Content-Type: text/markdown
+
+# AudioClassifier - Dynamic Classifier used for Audio Segment Identification and Removal
+
+Runs locally by default: one audio file in, filtered audio out. Needs an OpenAI API key and `ffmpeg`.
+
+## Quick Start
+
+```bash
+uv sync
+export OPENAI_API_KEY=<your-key>
+
+PAYLOAD='{"source": "My Show", "name": "Episode 1", "audio_url": "<mp3-url>"}' \
+  uv run audioclassifier --detection examples/configs/ads.toon
+```
+
+Results land in `output/<source>/<name>/`: the original mp3, the cleaned `*_filtered.mp3`, and a `transcripts/` dir with what was transcribed and each LLM cut/keep decision (with reasoning). Or with Docker:
+
+```bash
+docker build -t audioclassifier-app .
+docker run --gpus all \
+  -e OPENAI_API_KEY=<your-key> \
+  -e DETECTION_CONFIG=ads \
+  -e PAYLOAD='{"source": "My Show", "name": "Episode 1", "audio_url": "<mp3-url>"}' \
+  -v "$(pwd)/output:/app/output" \
+  audioclassifier-app
+```
+
+Drop `--gpus all` to run on CPU (slower). The same container runs on any GPU box — RunPod, Modal, a gaming PC.
+
+## As a Library
+
+```bash
+uv add audio-classifier-tool      # pip install audio-classifier-tool
+```
+
+```python
+import audioclassifier
+
+result = audioclassifier.process_audio(
+    source="My Show",
+    name="Episode 1",
+    audio_url="<mp3-url>",
+    detection="examples/configs/ads.toon",  # a .toon path or a name in ./configs
+    detection_instructions="...",           # or pass the prompt directly
+    detection_keywords=["use code", ...],   # and the keyword gate
+)
+print(result["output_path"], result["seconds_removed"])
+```
+
+Importing has no side effects; configure the `"audioclassifier"` logger to see progress.
+
+For a real end-to-end run with live console output and a decision summary:
+
+```bash
+uv run python examples/process_audio.py "<mp3-url>"
+```
+
+## How It Works
+
+- Downloads the audio from the `PAYLOAD` JSON (`source`, `name`, `audio_url`, optional `description`)
+- Transcribes with faster-whisper (GPU-accelerated, CPU works too)
+- Detects target segments with OpenAI — ads by default
+- Cuts them and re-assembles the audio
+
+## Detection
+
+The classifier is fully yours to define — nothing is bundled. A [TOON](https://github.com/toon-format/spec) config supplies the keywords and prompts: select one with `--detection <name|path>` or `DETECTION_CONFIG` (names resolve from `./configs/`), or pass the prompt and keywords directly (`detection_instructions`/`detection_keywords` in the API, `DETECTION_INSTRUCTIONS`/`DETECTION_KEYWORDS` env vars). Complete examples live in `examples/configs/` (ads, politics).
+
+## Text Classifier (optional, opt-in)
+
+A self-distilled local classifier can add a third detection signal alongside keywords and audio analysis. Every processed audio file writes LLM-labeled decisions under `output/**/transcripts/` — that corpus is the classifier's training data, and it grows with each run.
+
+Enable with `USE_TEXT_CLASSIFIER=true`: the classifier's flagged ranges join the LLM prompt (advisory only — the LLM still decides), and it retrains automatically after each run from the **full accumulated history** (retraining is from scratch, in seconds, so nothing is ever forgotten). Refresh manually anytime:
+
+```bash
+uv run python examples/train_classifier.py          # or audioclassifier.train_text_classifier()
+```
+
+How it propagates: the durable memory is the decision files in `output/` — the model file (`local_models/text_classifier.joblib`) is a disposable cache rebuilt from them. Editing a decision file's `cut_ranges_seconds` after listening feeds your correction into the next training pass. In Docker, mount `local_models/` alongside `output/` to carry the model between containers (the data already survives via the `output/` mount).
+
+## Parallelism
+
+One audio file per `process_audio` call. Multiple processes are safe, even in the same directory — downloads and segment audio live in per-run temp dirs, and the classifier model is written atomically. Within one process, run audio files sequentially (Whisper models load once and are reused); concurrent runs in threads are supported only with one shared detection config. Don't feed the same audio to two processes at once — they'd write the same output files.
+
+## Options
+
+- `LLM_MODEL` — any [pydantic-ai model string](https://ai.pydantic.dev/models/) (default `openai:gpt-5.6`; e.g. `openai:gpt-5-nano` for cheapest, `anthropic:claude-sonnet-4-6`, `ollama:qwen3` — non-OpenAI providers may need their extra installed)
+- `DISCORD_ALERTS=true DISCORD_WEBHOOK_URL=<url>` — processing alerts in Discord
+- `storage="s3://bucket/prefix"` (API) or `"storage"` in `PAYLOAD` — upload the run's outputs (audio + transcripts + decisions) to S3 under `<prefix>/<source>/<name>/`, using ambient AWS credentials
+
+## License
+
+[MIT](LICENSE)

audio_classifier_tool-1.2.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+audioclassifier/__init__.py,sha256=AyO7Ro0619IofMvR4qF-kmGBV1lnWDxhhGHuxr8I78Q,2096
+audioclassifier/__main__.py,sha256=D2TLiTegR9xmSHp8vdjc_I9IBy2H-TbqEZ57YdHaGSw,76
+audioclassifier/cli.py,sha256=f1oYzovV5xKqBcuRMUJYxhf3RrT7EwRcc_kRTJW8PVQ,4168
+audioclassifier/util.py,sha256=Nj4SjhPSwFRLtVIBBZ98GNDWbXmFtNw6vhSYlJdVPGU,227
+audioclassifier/alerts/__init__.py,sha256=-kPUIrzcbg4jY6f405jL5idMv9hhnABcwpIha1hF65M,44
+audioclassifier/alerts/discord_alerts.py,sha256=kHvtMf23-CHnmTrJrvbdby1RFZSkCj_uT3bP3Sa0sqw,6929
+audioclassifier/cloud/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+audioclassifier/cloud/storage.py,sha256=46QAuB6ZGlZ1W-gdkF9Qz8YgH4cA-RWkaKHjCwUfNmE,1267
+audioclassifier/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+audioclassifier/config/constants.py,sha256=KY5WSZgkpetZaG9k7cVWpMWfvatTcFx8gXcaogwy0sc,1788
+audioclassifier/config/detection_config.py,sha256=pugr_IozCjTeJgtWgIYahFWhp-3fEepYh4An4EA6Dg4,4692
+audioclassifier/detection/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+audioclassifier/detection/llm_detector.py,sha256=NDJiBa86TnxnO8iWIPq39inUlaUA1HYMEVzBndleMYs,7292
+audioclassifier/detection/text_classifier.py,sha256=T2Z-LJb26FUpF_D0MNcDIuB1Tlsh9WKtTceVgMx4nXc,4906
+audioclassifier/logger/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+audioclassifier/logger/logger_setup.py,sha256=Lh31aHSRJd2J_YSLFLjVZ5HRjfmS1aFcpE8Ra2DVm_4,546
+audioclassifier/processing/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+audioclassifier/processing/audio_processor.py,sha256=KXjELSZuo-B6wU_IuL-EhXfnPPJ93ziu42NCIzcx6N0,13520
+audioclassifier/processing/download_mp3.py,sha256=K0NYZPBzhmCK5lIpOPqqJ5p2kzABLr1D66KKuoSFdUc,2333
+audioclassifier/processing/mp3_handler.py,sha256=MdHyOCKk3FPrsI0YY1_oTd6JgLfILQQe0Etc0VQzWWI,2864
+audio_classifier_tool-1.2.0.dist-info/METADATA,sha256=2puSsHfpU7Aic1gN2o5uC6Bpbr_CarosHVWDvMRpcQU,5962
+audio_classifier_tool-1.2.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+audio_classifier_tool-1.2.0.dist-info/entry_points.txt,sha256=vSN6GeXl6Eq7TOab5nXDLcpDqMGt5hJuukhP_aqn-8M,61
+audio_classifier_tool-1.2.0.dist-info/licenses/LICENSE,sha256=masymspiVA2InuFLMBG--KV1VliTPJqIIm-q-O_Tj-M,1069
+audio_classifier_tool-1.2.0.dist-info/RECORD,,

audio_classifier_tool-1.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.3
+Root-Is-Purelib: true
+Tag: py3-none-any

audio_classifier_tool-1.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+audioclassifier = audioclassifier.cli:main

audio_classifier_tool-1.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Jon Fox
+
+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.

audioclassifier/__init__.py

@@ -0,0 +1,59 @@
+"""AudioClassifier: detect and cut target segments from audio (ads by default)."""
+
+
+def process_audio(
+    source,
+    name,
+    audio_url,
+    detection=None,
+    detection_instructions=None,
+    detection_keywords=None,
+    description=None,
+    storage=None,
+):
+    """Process one audio file: download, transcribe, detect, and cut.
+
+    source groups outputs (output/<source>/<name>/); name is used for the
+    output filenames. detection: a config name (in ./configs) or a .toon path;
+    detection_instructions / detection_keywords override the selected config
+    directly. description is optional context about the audio for the
+    detection config's context-extraction prompt. storage: optional
+    s3://bucket/prefix — outputs are uploaded under <prefix>/<source>/<name>/.
+    Returns a dict with output_path, filtered_duration, original_duration,
+    seconds_removed, and (with storage) the uploaded S3 URIs.
+
+    Configure the "audioclassifier" logger to see progress; set OPENAI_API_KEY
+    (or the provider key matching LLM_MODEL) before calling.
+    """
+    if detection or detection_instructions or detection_keywords:
+        from audioclassifier.config.detection_config import set_detection_config
+
+        set_detection_config(
+            detection,
+            instructions=detection_instructions,
+            keywords=detection_keywords,
+        )
+
+    from audioclassifier.cli import process_payload
+
+    return process_payload(
+        {
+            "source": source,
+            "name": name,
+            "audio_url": audio_url,
+            "description": description,
+            "storage": storage,
+        }
+    )
+
+
+def train_text_classifier(output_dir=None):
+    """Train the self-distilled ad classifier from past runs' decision files.
+
+    Returns training metrics. The trained model is picked up automatically by
+    subsequent runs as an extra detection signal.
+    """
+    from audioclassifier.config.constants import FINISHED_MP3_DIR
+    from audioclassifier.detection import text_classifier
+
+    return text_classifier.train(output_dir or FINISHED_MP3_DIR)

audioclassifier/__main__.py

@@ -0,0 +1,4 @@
+from audioclassifier.cli import main
+
+if __name__ == "__main__":
+    main()

audioclassifier/alerts/__init__.py

@@ -0,0 +1 @@
+# Empty __init__.py file for alerts package

audioclassifier/alerts/discord_alerts.py

@@ -0,0 +1,206 @@
+import os
+
+import requests
+import traceback
+from datetime import datetime
+from audioclassifier.config.constants import DISCORD_ALERTS_ENABLED
+from audioclassifier.logger.logger_setup import logger
+
+
+class DiscordAlerter:
+    def __init__(self):
+        self.webhook_url = None
+
+        if not DISCORD_ALERTS_ENABLED:
+            logger.info("Discord alerts disabled (set DISCORD_ALERTS=true to enable)")
+            return
+
+        self.webhook_url = os.getenv("DISCORD_WEBHOOK_URL")
+        if not self.webhook_url:
+            logger.warning(
+                "DISCORD_ALERTS is enabled but DISCORD_WEBHOOK_URL is not set, alerts disabled"
+            )
+
+    def send_error_alert(
+        self, error, context="", name="", source="", additional_info=None
+    ):
+        """
+        Send a detailed error alert to Discord
+
+        Args:
+            error: The exception object or error message
+            context: Additional context about where the error occurred
+            name: Name of the audio being processed when error occurred
+            source: Source the audio belongs to
+            additional_info: Dictionary of additional information to include
+        """
+        if not self.webhook_url:
+            logger.debug("Discord alerts disabled, skipping alert")
+            return False
+
+        try:
+            # Build the error message
+            timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S UTC")
+
+            # Extract error details
+            if isinstance(error, Exception):
+                error_type = type(error).__name__
+                error_message = str(error)
+                # Get traceback if available
+                tb_str = (
+                    traceback.format_exc()
+                    if hasattr(error, "__traceback__")
+                    else "No traceback available"
+                )
+            else:
+                error_type = "Error"
+                error_message = str(error)
+                tb_str = "No traceback available"
+
+            # Build the alert message
+            message_parts = [
+                "🚨 **AUDIOCLASSIFIER APP ERROR ALERT** 🚨",
+                f"**Timestamp:** {timestamp}",
+            ]
+
+            if source:
+                message_parts.append(f"**Source:** {source}")
+
+            if name:
+                message_parts.append(f"**Audio:** {name}")
+
+            if context:
+                message_parts.append(f"**Context:** {context}")
+
+            message_parts.extend(
+                [
+                    f"**Error Type:** {error_type}",
+                    f"**Error Message:** {error_message}",
+                ]
+            )
+
+            if additional_info:
+                message_parts.append("**Additional Info:**")
+                for key, value in additional_info.items():
+                    message_parts.append(f"  • {key}: {value}")
+
+            # Add truncated traceback (Discord has message limits)
+            if tb_str and tb_str != "No traceback available":
+                # Truncate traceback to avoid Discord message limits (2000 chars)
+                tb_lines = tb_str.split("\n")
+                if len(tb_str) > 1000:
+                    tb_str = "\n".join(tb_lines[:10]) + "\n... (traceback truncated)"
+
+                message_parts.append(f"**Traceback:**\n```\n{tb_str}\n```")
+
+            final_message = "\n".join(message_parts)
+
+            # Ensure message doesn't exceed Discord's 2000 character limit
+            if len(final_message) > 1900:
+                final_message = final_message[:1900] + "\n... (message truncated)"
+
+            # Send to Discord
+            payload = {"content": final_message}
+            response = requests.post(self.webhook_url, json=payload, timeout=10)
+
+            if response.status_code == 204:
+                logger.info("Discord error alert sent successfully")
+                return True
+            else:
+                logger.error(
+                    f"Failed to send Discord alert. Status: {response.status_code}, Response: {response.text}"
+                )
+                return False
+
+        except Exception as e:
+            logger.error(f"Error sending Discord alert: {e}")
+            return False
+
+    def send_processing_alert(
+        self,
+        message_type,
+        source="",
+        name="",
+        additional_info=None,
+        alert_title="PROCESSING",
+    ):
+        """
+        Send processing status alerts (success, start, etc.)
+
+        Args:
+            message_type: Type of message (success, started, warning, etc.)
+            source: Source the audio belongs to
+            name: Name of the audio
+            additional_info: Dictionary of additional information
+        """
+        if not self.webhook_url:
+            logger.debug("Discord alerts disabled, skipping alert")
+            return False
+
+        try:
+            timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S UTC")
+
+            emoji_map = {
+                "success": "✅",
+                "started": "🚀",
+                "warning": "⚠️",
+                "info": "ℹ️",
+            }
+
+            emoji = emoji_map.get(message_type, "📢")
+
+            message_parts = [
+                f"{emoji} **AUDIOCLASSIFIER {alert_title} UPDATE**",
+                f"**Type:** {message_type.upper()}",
+                f"**Timestamp:** {timestamp}",
+            ]
+
+            if source:
+                message_parts.append(f"**Source:** {source}")
+
+            if name:
+                message_parts.append(f"**Audio:** {name}")
+
+            if additional_info:
+                for key, value in additional_info.items():
+                    message_parts.append(f"**{key}:** {value}")
+
+            final_message = "\n".join(message_parts)
+
+            payload = {"content": final_message}
+            response = requests.post(self.webhook_url, json=payload, timeout=10)
+
+            if response.status_code == 204:
+                logger.info(f"Discord {message_type} alert sent successfully")
+                return True
+            else:
+                logger.error(
+                    f"Failed to send Discord {message_type} alert. Status: {response.status_code}"
+                )
+                return False
+
+        except Exception as e:
+            logger.error(f"Error sending Discord processing alert: {e}")
+            return False
+
+
+# Global instance for easy access
+discord_alerter = DiscordAlerter()
+
+
+def send_error_alert(error, context="", name="", source="", additional_info=None):
+    """
+    Convenience function to send error alerts
+    """
+    return discord_alerter.send_error_alert(
+        error, context, name, source, additional_info
+    )
+
+
+def send_processing_alert(message_type, source="", name="", additional_info=None):
+    """
+    Convenience function to send processing alerts
+    """
+    return discord_alerter.send_processing_alert(
+        message_type, source, name, additional_info
+    )

audioclassifier/cli.py

@@ -0,0 +1,147 @@
+import argparse
+import os
+import sys
+
+from audioclassifier.logger.logger_setup import configure_logging, logger
+from audioclassifier.processing.mp3_handler import mp3_handler
+from audioclassifier.config.detection_config import (
+    get_detection_config,
+    set_detection_config,
+)
+import json
+from audioclassifier.config.constants import USE_TEXT_CLASSIFIER
+from audioclassifier.detection.llm_detector import _ensure_api_key
+from audioclassifier.util import generate_hash, sanitize_name
+from audioclassifier.alerts.discord_alerts import (
+    send_error_alert,
+    send_processing_alert,
+)
+
+
+def prepare_mp3_file(source, description, audio_hash, audio_url, name):
+    logger.info(f"Fetching MP3 file::{audio_url}")
+
+    try:
+        result = mp3_handler(
+            source,
+            description,
+            audio_hash,
+            audio_url,
+            name=name,
+        )
+        logger.info(f"MP3 file processed::{result}")
+        return result
+    except Exception as e:
+        logger.error(f"Error processing MP3 file::{e}")
+        send_error_alert(
+            error=e,
+            context="MP3 file processing failed in prepare_mp3_file",
+            name=name,
+            source=source,
+            additional_info={
+                "audio_url": audio_url,
+                "audio_hash": audio_hash,
+            },
+        )
+        raise e
+
+
+def process_payload(payload={}):
+    logger.info(f"Received payload::{payload}")
+
+    if not payload:
+        logger.info("No payload received")
+        return
+
+    source = sanitize_name(payload.get("source"))
+    name = payload.get("name")
+    audio_url = payload.get("audio_url")
+    logger.info(f"Processing source: {source}, name: {name}, audio_url: {audio_url}")
+    audio_hash = generate_hash(source, name)
+
+    description = payload.get("description") or ""
+    if description:
+        logger.info(f"Description provided for processing::{description}")
+
+    result = prepare_mp3_file(
+        source=source,
+        description=description,
+        audio_hash=audio_hash,
+        audio_url=audio_url,
+        name=name,
+    )
+    logger.info(f"Processing result::{result}")
+
+    storage = payload.get("storage")
+    if storage:
+        from audioclassifier.cloud.storage import upload_outputs
+
+        result["uploaded"] = upload_outputs(
+            os.path.dirname(result["output_path"]),
+            f"{storage.rstrip('/')}/{source}/{sanitize_name(name)}",
+        )
+
+    # Send success alert
+    send_processing_alert(
+        message_type="success",
+        source=source,
+        name=name,
+        additional_info={
+            "Audio Hash": audio_hash,
+            "Processed Length": f"{result['filtered_duration']} seconds",
+        },
+    )
+
+    # This run's decisions are new training data; refresh the classifier
+    if USE_TEXT_CLASSIFIER:
+        from audioclassifier.detection.text_classifier import retrain_after_run
+
+        retrain_after_run()
+
+    return result
+
+
+def main():
+    configure_logging()
+
+    parser = argparse.ArgumentParser(
+        description="AudioClassifier: detect and cut content from audio"
+    )
+    parser.add_argument(
+        "--detection",
+        help="detection config: a name in ./configs or a path to a .toon file",
+    )
+    args = parser.parse_args()
+    try:
+        config = (
+            set_detection_config(args.detection)
+            if args.detection
+            else get_detection_config()
+        )
+    except (RuntimeError, FileNotFoundError, ValueError) as e:
+        logger.error(str(e))
+        print(e, file=sys.stderr)
+        sys.exit(1)
+    logger.info(f"Using detection config: {config.name}")
+
+    try:
+        _ensure_api_key()
+    except RuntimeError as e:
+        logger.error(str(e))
+        print(e, file=sys.stderr)
+        sys.exit(1)
+
+    payload = os.getenv("PAYLOAD")
+    if not payload:
+        message = (
+            'Set PAYLOAD to a JSON object like {"source": ..., '
+            '"name": ..., "audio_url": ...} — see README.md'
+        )
+        logger.error(message)
+        print(message, file=sys.stderr)
+        sys.exit(1)
+    process_payload(json.loads(payload))
+
+
+if __name__ == "__main__":
+    main()

audioclassifier/cloud/storage.py

@@ -0,0 +1,36 @@
+"""Optional cloud storage: push a run's outputs to an s3:// location."""
+
+import os
+
+from audioclassifier.logger.logger_setup import logger
+
+
+def upload_outputs(output_dir, storage_uri):
+    """Upload everything under output_dir to storage_uri (s3://bucket/prefix).
+
+    Uses ambient AWS credentials (env/profile/role). Returns the uploaded
+    s3:// URIs.
+    """
+    import boto3
+
+    bucket, prefix = _parse_s3_uri(storage_uri)
+    client = boto3.client("s3")
+    uploaded = []
+    for root, _, files in os.walk(output_dir):
+        for filename in files:
+            local_path = os.path.join(root, filename)
+            relative = os.path.relpath(local_path, output_dir).replace(os.sep, "/")
+            key = f"{prefix}/{relative}" if prefix else relative
+            client.upload_file(local_path, bucket, key)
+            uploaded.append(f"s3://{bucket}/{key}")
+            logger.info(f"Uploaded {relative} to s3://{bucket}/{key}")
+    return uploaded
+
+
+def _parse_s3_uri(uri):
+    if not uri.startswith("s3://"):
+        raise ValueError(f"storage must be an s3:// URI, got {uri!r}")
+    bucket, _, prefix = uri[5:].partition("/")
+    if not bucket:
+        raise ValueError(f"storage URI is missing a bucket: {uri!r}")
+    return bucket, prefix.strip("/")