foley 0.0.2__tar.gz

foley-0.0.2/.claude/CLAUDE.md

@@ -0,0 +1,55 @@
+# foley — agent guide
+
+**foley** is a retrieval-first façade for sound effects: find (or generate) the right
+sound for a moment of narration and weave it in. Four stages —
+**SOURCE → INDEX → SELECT → WEAVE** — plus cross-cutting layers (licensing/provenance,
+evaluation/QC, observability, `dol` storage). It is the SFX sibling of
+[`arioso`](https://github.com/thorwhalen/arioso) (a unified façade over music-gen
+backends) and shares its discipline.
+
+**Status:** early implementation. The plan is **[Epic #13](https://github.com/thorwhalen/foley/issues/13)**
+with 12 sub-issues (#1–#12). **#1 Foundation** (data models, `dol` stores, audio + Tier-0 QC)
+and **#2 Index** (CLAP embedder, hybrid RRF search, `SoundLibrary` façade, UCS/AudioSet
+taxonomy resolver) are built; next is **#3 Ingestion** → **#4 Bootstrap** (the `ingest()`→`search()` keystone).
+
+## Read before doing foley work
+
+- **Authoritative architecture** → [`misc/docs/research/10-facade-architecture.md`](../misc/docs/research/10-facade-architecture.md)
+  (component diagram, data models, façade API, protocols, module tree, build order).
+- **Design map** → [`misc/docs/design.md`](../misc/docs/design.md) ·
+  **Roadmap** → [`misc/docs/roadmap.md`](../misc/docs/roadmap.md)
+- **Research** → 12 cited reports in [`misc/docs/research/`](../misc/docs/research/)
+  (index + the 12-prompt library there).
+
+## Dev skills (the agent toolkit for building foley)
+
+| Skill | Use when |
+|-------|----------|
+| **`foley-dev-implement`** | implementing any epic subtask — the build loop, module layout, canonical data models, invariants, façade discipline, git flow |
+| **`foley-dev-add-source`** | adding a sound source — a retrieve adapter (Freesound/BBC/…) or a generate adapter (Stable Audio Open/ElevenLabs/…) via the `SOURCE_CONFIG` pattern |
+
+These are **dev** skills (for the agent building foley), not skills shipped to end
+users. Real files live in `skills/foley-dev-*/`, symlinked into `.claude/skills/`.
+
+## Behavioral rules (the non-negotiables)
+
+- **Git flow:** work on a **feature branch → PR into `main`**. No direct-to-main commits.
+- **Follow the architecture; don't fork it.** Build against the module layout,
+  protocols, and canonical data models in report 10 / `base.py`. Don't invent parallel
+  structures. See `foley-dev-implement`.
+- **Licensing is load-bearing** (foley's output gets published): `LicenseRecord` is the
+  SSOT for *both* the candidate license-filter *and* each sound's storage mode;
+  `redistribute_standalone_ok` (copyright) ≠ `cache_bytes_ok` (TOS); the license gate is
+  **fail-closed**. See `foley-dev-add-source` and report 07.
+- **Façade discipline:** mirror `arioso` (config-driven plugin adapters, unified
+  vocabulary → native params, zero-dep core + lazy optional-extras, `dol` storage) and
+  `accompy` (progressive disclosure, protocol-based extensibility, `check_requirements`
+  onboarding).
+- **Every module needs a top-level docstring** (auto-extracted for docs). Prefer
+  functional style; keyword-only args past the 3rd position.
+
+## Where things go (placement test)
+
+Behavioral rules → this file / the skills. Content & context → the named files in
+`misc/docs/` referenced above. *If deleting a sentence wouldn't change behavior, it
+belongs in a file, not here.*

foley-0.0.2/.claude/skills/foley-dev-add-source/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: foley-dev-add-source
+description: Use when adding a new sound SOURCE to foley — either a retrieve adapter (a sound-library/API such as Freesound, BBC Sound Effects, Epidemic, Storyblocks, Pond5) or a generate adapter (a text-to-SFX model/API such as Stable Audio Open, ElevenLabs Sound Effects, AudioGen). Covers the SOURCE_CONFIG plugin pattern (mirroring arioso's per-platform config), the SourceAdapter protocol, unified query/generation vocabulary → native-param translation, lazy optional-deps, and the mandatory per-source license policy (commercial_ok / redistribute_standalone_ok / cache_bytes_ok / ai_training_ok). Triggers on adding a source, adding an adapter, wiring a new SFX API or generator into foley.
+metadata:
+  audience: developers
+---
+
+# Adding a source to foley
+
+A **source** is anywhere foley gets a sound. Two kinds, one contract:
+
+- **retrieve** — fetch existing sounds from a library/API. Anchor: **Freesound** (CC0
+  subset). Others (BBC, Epidemic, Storyblocks, Pond5, Pro Sound Effects) are mostly
+  partner-gated → ship as stubs. See `misc/docs/research/01-sfx-source-apis.md`.
+- **generate** — synthesize a sound (the arioso analog). Defaults: **Stable Audio Open**
+  (local) + **ElevenLabs Sound Effects** (hosted). See
+  `misc/docs/research/02-genai-sfx-generation.md`.
+
+The pattern mirrors [`arioso`](https://github.com/thorwhalen/arioso)'s
+`arioso/platforms/<name>/` (a `config.py` declaring `PLATFORM_CONFIG` + an optional
+`adapter.py`). Read an arioso platform before writing a foley source.
+
+## Layout
+
+```
+foley/sources/<name>/
+    __init__.py
+    config.py     # required: declares SOURCE_CONFIG
+    adapter.py    # optional: custom logic (needed for non-trivial REST / local models)
+```
+
+The source is auto-discovered by `registry.py`; third parties can also
+`register_source(name, config, adapter)` at runtime.
+
+## `SOURCE_CONFIG` (the declaration)
+
+```python
+SOURCE_CONFIG = {
+    "name": "<name>",
+    "kind": "retrieve",              # or "generate"
+    "display_name": "...",
+    "website": "https://...",
+
+    "auth": {"type": "bearer_token", "env_var": "<NAME>_API_KEY"},  # or None
+
+    # unified foley vocabulary -> this source's native names
+    "param_map": {
+        "query": {"native_name": "text", "required": True},   # retrieve
+        "duration": {"native_name": "length_s"},
+        # generate uses GENERATION_AFFORDANCES (prompt, duration, prompt_influence, ...)
+    },
+    "supported_affordances": ["query", "duration", "license"],
+    "on_unsupported_param": "warn",
+
+    # REST sources: endpoints; local models: omit and implement adapter.generate()
+    "api": {"base_url": "https://...", "search_endpoint": {...}, "download_endpoint": {...}},
+
+    "output": {"default_format": "wav", "returns": "bytes"},  # or "url" / "array"
+
+    # ⚠️ MANDATORY license policy — see invariants below
+    "license": {
+        "default_license_id": "CC0-1.0",     # per-item value can override
+        "commercial_ok": True,
+        "redistribute_standalone_ok": True,   # copyright: may the raw file be re-exposed?
+        "cache_bytes_ok": False,              # TOS: may we store the bytes? (Freesound: no)
+        "ai_training_ok": True,
+        "requires_attribution": False,
+    },
+    "commercial_ok": True,                    # generate guardrail (+ revenue_cap for Stable Audio Open)
+    "rate": {"per_min": 60, "per_day": 2000},
+    "cost": {...},
+    "data_egress": "external",                # for offline/sensitive-narration mode
+}
+```
+
+## The `SourceAdapter` protocol
+
+- **retrieve:** `search(query, **affordances) -> list[Candidate]` · `get(id) -> SoundRecord`
+  · `download(record) -> bytes` (honoring `cache_bytes_ok`).
+- **generate:** `generate(prompt, **affordances) -> SoundRecord` (bytes/array in the blob
+  store; a `LicenseRecord` marking `is_ai_generated=True`, model/seed/prompt captured).
+
+Translate unified affordances → native params via `param_map` (like arioso's translation
+layer); warn-and-drop unsupported ones per `on_unsupported_param`.
+
+## License invariants (do NOT skip — foley output gets published)
+
+1. **Every fetched or generated sound gets a `LicenseRecord`.** Seed it from
+   `SOURCE_CONFIG["license"]`; let per-item API metadata override (e.g. a Freesound sound's
+   actual CC license).
+2. **`redistribute_standalone_ok` (copyright) is distinct from `cache_bytes_ok` (TOS).**
+   Freesound CC0 → `redistribute_standalone_ok=True` but `cache_bytes_ok=False`: store
+   **by-reference** (keep the source URI/id, re-fetch on use), never a permanent local copy.
+   Own/generated/CC0-bulk audio → `cache_bytes_ok=True`: store **by-value** (content-hashed
+   bytes in the blob store).
+3. **Generate adapters carry a `commercial_ok` guardrail.** Most open SFX weights are
+   CC-BY-NC → their outputs are non-commercial; mark them. Stable Audio Open is commercial
+   under a **$1M revenue cap** — encode `revenue_cap_usd`.
+4. **Generated audio is watermarked/disclosed** (AudioSeal + optional C2PA) — handled by
+   `foley/provenance/`, but set `is_ai_generated` + generation fields on the record.
+5. The agent's fail-closed `keep(record, IntendedUse)` gate depends on these flags being
+   correct. Wrong flags = legal/TOS violation slips through.
+
+## Checklist for a new source
+
+- [ ] `foley/sources/<name>/config.py` with a complete `SOURCE_CONFIG` (incl. the full
+      `license` block + `kind`).
+- [ ] `adapter.py` if REST/local logic is non-trivial; else rely on the shared base adapter.
+- [ ] `param_map` covers every affordance the source supports; unsupported → `warn`.
+- [ ] License flags set correctly, especially `cache_bytes_ok` vs `redistribute_standalone_ok`.
+- [ ] Optional dep in a `foley[<name>]` extra, **lazy-imported** (core stays zero-dep).
+- [ ] Tests: adapter returns valid `Candidate`/`SoundRecord`s; license flags populate;
+      by-reference vs by-value storage honored.
+- [ ] Auto-discovered by `registry.py` (or documented `register_source` usage).
+
+See `foley-dev-implement` for the surrounding build loop, module layout, and git flow.

foley-0.0.2/.claude/skills/foley-dev-implement/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: foley-dev-implement
+description: Use when implementing (or planning to implement) any foley epic subtask — building the SOURCE / INDEX / SELECT / WEAVE stages or the cross-cutting layers of the foley SFX façade. Covers the build loop, the module layout, the canonical data models (SoundRecord, LicenseRecord, Candidate, SoundDesignTimeline), the non-negotiable invariants (license SSOT + fail-closed gate, cache_bytes_ok vs redistribute_standalone_ok, the eval PR gate, AI disclosure), the façade discipline (mirror arioso/accompy), and the branch→PR git flow. Triggers on foley implementation, foley subtask, foley adapter/index/agent/weave work, foley base.py / data models.
+metadata:
+  audience: developers
+---
+
+# Building a foley subtask
+
+foley is a retrieval-first SFX façade (SOURCE → INDEX → SELECT → WEAVE + cross-cutting
+layers). The whole plan is **[Epic #13](https://github.com/thorwhalen/foley/issues/13)**,
+subtasks **#1–#12**. Read this before implementing any of them.
+
+## First: orient (don't invent)
+
+1. Read **`misc/docs/research/10-facade-architecture.md`** — the authoritative synthesis
+   (component diagram, data models as code, façade API, protocols, module tree,
+   dependency graph). It reconciles all 12 research reports; treat it as the spec.
+2. Skim **`misc/docs/design.md`** (the readable map) and the specific research report(s)
+   backing your subtask (each subtask issue lists them).
+3. Look at how [`arioso`](https://github.com/thorwhalen/arioso) and
+   [`accompy`](https://github.com/thorwhalen/accompy) do the same shape — foley mirrors
+   their façade discipline.
+
+## The build loop
+
+1. **Pick a subtask** from Epic #13. Respect the dependency order — the keystone is
+   **#1 Foundation → #2 Index → #3 Ingestion → #4 Bootstrap** (gets `ingest()` → `search()`
+   working). Then a thin slice through Select (#7) → Weave (#8).
+2. **Branch:** `git checkout -b <topic>` off `main`. Never commit foley code directly to
+   `main` — open a **PR** that references the subtask (`Closes #N`).
+3. **Implement against the layout & protocols** below — extend the SSOT data models, don't
+   fork them. New optional dependency? Put it in an `optional-dependencies` extra
+   (`foley[<capability>]`) and **lazy-import** it; the core stays zero-dep.
+4. **Test** (economist / testing-trophy: cheap, stable API-level checks first — see
+   `misc/docs/research/08-evaluation-quality.md`). Pure functions get unit tests; the
+   retrieval path gets Tier-1 metrics.
+5. **Eval gate** (once the harness from #10 exists): a change to the index/embedder/
+   prompt must not drop **`nDCG@10` by > 0.02** on the frozen golden set.
+6. **PR** into `main`; keep the subtask's task-list checkboxes updated.
+
+## Module layout (from report 10 — build into this tree)
+
+```
+foley/
+    __init__.py        # façade: find(), search(), generate(), ingest(), weave()
+    base.py            # SoundRecord, LicenseRecord, Candidate, SoundEvent, Verdict,
+                       #   IntendedUse, affordance registries — the SSOT types
+    registry.py        # adapter auto-discovery + lazy loading
+    audio.py           # I/O + DSP primitives (soundfile/soxr/librosa/pyloudnorm)
+    sources/           # source adapters (config.py + adapter.py each) — see foley-dev-add-source
+    index/             # embedders, taggers, captioners, library (dol + LanceDB), search, taxonomy
+    agent/             # decompose, verify, policy(decide), tools, mcp
+    weave/             # align, anchor, mix, master, timeline, render
+    eval/              # qc (Tier-0), retrieval metrics (Tier-1), fit (Tier-2)
+    provenance/        # LicenseRecord wiring, credits, watermark/disclosure
+    obs/               # OpenTelemetry spans + run-manifest artifact
+```
+
+Optional-extras: `foley[freesound]`, `foley[stable-audio]`, `foley[elevenlabs]`,
+`foley[clap]`, `foley[tag]`, `foley[caption]`, `foley[index]`, `foley[weave]`,
+`foley[agent]`, `foley[all]`. `ffmpeg`/`rubberband` are **system** deps surfaced via a
+`check_requirements`/`verify_and_setup` helper (accompy-style), never inherited by `pip`.
+
+## Canonical data models (SSOT — live in `base.py`, never fork)
+
+- **`SoundRecord`** — the metadata SSOT for one sound (report 04 schema + report 09
+  storage fields + a nested `LicenseRecord` + a QC block + `named_cue` continuity). The
+  audio bytes live in the `dol` blob store; the record holds a content-hash `uri`, never
+  inline bytes.
+- **`LicenseRecord`** — per-sound rights/provenance (report 07). Carries the derived
+  flags used everywhere: `commercial_ok`, `embed_in_derivative_ok`,
+  `redistribute_standalone_ok`, `modification_ok`, `ai_training_ok`, **`cache_bytes_ok`**,
+  plus attribution/watermark/generation fields.
+- **`Candidate` / `SoundEvent` / `Verdict`** — the SELECT agent's working types (report 05).
+- **`SoundDesignTimeline` / `TimelineItem`** — the WEAVE render model (report 06); it is a
+  **strict superset** of the SELECT plan. The agent emits the sparse plan; WEAVE resolves
+  anchors and fills processing defaults. It is JSON-serializable, diffable, and
+  re-renderable — the "editable sound-design timeline" (foley's snapshots/stories analog).
+
+## Non-negotiable invariants
+
+1. **`LicenseRecord` is the SSOT for two things:** the candidate license-filter *and*
+   each `SoundRecord`'s storage mode. Wire both from it.
+2. **`redistribute_standalone_ok` (copyright) ≠ `cache_bytes_ok` (TOS/operational).** e.g.
+   Freesound CC0 is legally redistributable yet its API TOS forbids caching → store
+   **by-reference**. Get this wrong and you either break the law or break the TOS.
+3. **The license gate is fail-closed.** `keep(record, IntendedUse)` runs as a hard gate
+   *before* verification/ranking in the agent's `decide()`; unknown rights → reject.
+4. **AI-generated audio is disclosed & watermarked.** Watermark generations (AudioSeal),
+   optionally write C2PA, and honor the **EU AI Act Art. 50** disclosure deadline
+   (**2 Aug 2026**). Tracked in #9.
+5. **The eval gate guards regressions** (once #10 lands): no silent `nDCG@10` drop.
+
+## Reference
+
+Depth for any subtask is in the matching research report in `misc/docs/research/`
+(`01` sources · `02` generation · `03` recognition · `04` index · `05` agent · `06`
+weave · `07` licensing · `08` eval · `09` audio/storage · `11` corpora · `12`
+meta-scan · **`10` = authoritative architecture**). For adding a source, use the
+**`foley-dev-add-source`** skill.

foley-0.0.2/.gitattributes

@@ -0,0 +1 @@
+*.ipynb linguist-documentation

foley-0.0.2/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+# wads CI — calls the reusable workflow hosted in i2mint/wads.
+#
+# All configuration comes from this repo's pyproject.toml [tool.wads.ci.*].
+# To customize the workflow itself (rare), replace this file with the
+# full inline template `wads/data/github_ci_uv.yml` from i2mint/wads.
+#
+# Pinning: `@master` floats with wads. If you need version stability for
+# a release-sensitive repo, change `@master` to a wads tag (e.g. `@v0.1.81`).
+# CI failure does not block a published release — it blocks the publish
+# step itself — so floating master is generally safe.
+#
+# Permissions: GitHub validates that the caller grants AT LEAST the
+# permissions any job in the called workflow requests — at workflow-parse
+# time, not at run-time, even if the job would be skipped via `if:`.
+# The reusable workflow needs:
+#   contents: write   for the publish job's version-bump push-back
+#                     and for the github-pages job's gh-pages branch push
+#   pages: write      for the github-pages job's REST API Pages config
+# Both default to `write` on org-account GITHUB_TOKEN and need to be
+# granted explicitly on personal-account callers (where the default is
+# read-only). No `id-token: write` needed — the publish-github-pages
+# action uses peaceiris/actions-gh-pages (branch-based) + REST API,
+# not the OIDC `actions/deploy-pages` flow.
+name: Continuous Integration
+on: [push, pull_request]
+jobs:
+  ci:
+    uses: i2mint/wads/.github/workflows/uv-ci.yml@master
+    permissions:
+      contents: write
+      pages: write
+    # Explicit pass-through (not `secrets: inherit`) because `inherit` does
+    # not reliably propagate caller-repo secrets to a reusable workflow owned
+    # by a different account (verified empirically: personal-account caller +
+    # i2mint-org workflow → `${{ secrets.PYPI_PASSWORD }}` resolved to empty).
+    #
+    # This list is the per-repo *transport*: it should contain PYPI_PASSWORD
+    # (for publishing) plus every secret your tests/CI need. It is generated
+    # from [tool.wads.ci.env] in pyproject.toml. To add one, run
+    #   wads-secrets add VAR_NAME            # updates pyproject + this block
+    # or just append a line below. *Which* of these become job env vars (and
+    # which are required) is controlled by [tool.wads.ci.env] — passing a
+    # secret here does not by itself put it in the environment.
+    #
+    # A secret name must also be declared in the reusable workflow's superset
+    # (wads/ci_secrets.py). `wads-secrets add` warns if it is not.
+    secrets:
+      PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}

foley-0.0.2/.gitignore

@@ -0,0 +1,121 @@
+.claude/handoffs/
+.claude/scratch/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# TLS certificates
+## Ignore all PEM files anywhere
+*.pem
+## Also ignore any certs directory
+certs/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/*
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea
+.claude/skills/.system/

foley-0.0.2/LICENSE

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

foley-0.0.2/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: foley
+Version: 0.0.2
+Summary: Unified facade for sourcing, indexing, and searching sound effects to weave into narration
+Project-URL: Homepage, https://github.com/thorwhalen/foley
+Project-URL: Repository, https://github.com/thorwhalen/foley
+Project-URL: Documentation, https://thorwhalen.github.io/foley
+Author: Thor Whalen
+License: mit
+License-File: LICENSE
+Keywords: audio,audio-retrieval,clap,foley,narration,sfx,sound-design,sound-effects,text-to-audio
+Requires-Python: >=3.10
+Requires-Dist: config2py
+Requires-Dist: dol
+Provides-Extra: audio
+Requires-Dist: librosa; extra == 'audio'
+Requires-Dist: numpy; extra == 'audio'
+Requires-Dist: pyloudnorm; extra == 'audio'
+Requires-Dist: soundfile; extra == 'audio'
+Requires-Dist: soxr; extra == 'audio'
+Provides-Extra: clap
+Requires-Dist: torch; extra == 'clap'
+Requires-Dist: transformers>=4.40; extra == 'clap'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
+Requires-Dist: sphinx>=6.0; extra == 'docs'
+Provides-Extra: index
+Requires-Dist: lancedb>=0.13; extra == 'index'
+Provides-Extra: index-sqlite
+Requires-Dist: sqlite-vec>=0.1.0; extra == 'index-sqlite'
+Provides-Extra: test
+Requires-Dist: numpy; extra == 'test'
+Requires-Dist: pyloudnorm; extra == 'test'
+Requires-Dist: pytest-cov>=4.0; extra == 'test'
+Requires-Dist: pytest>=7.0; extra == 'test'
+Requires-Dist: soundfile; extra == 'test'
+Requires-Dist: soxr; extra == 'test'
+Description-Content-Type: text/markdown
+
+# foley
+
+Find (or generate) the **right sound effect for a moment of narration** — and weave it in.
+
+foley is a **retrieval-first façade for sound effects**: one simple surface over many
+sound *sources* (your own library, service APIs, and generative-AI models), a searchable
+*index* of every sound (by keyword **and** meaning), an *agent* that picks the right
+sound for a narrative context, and a *compositor* that places it under the voice.
+
+It's the SFX sibling of [`arioso`](https://github.com/thorwhalen/arioso) (a unified
+façade over AI music-generation backends): same discipline — one entry function,
+config-driven plugin adapters, a unified vocabulary translated per-backend, zero
+required core deps with lazy optional-deps — but centered on **search** rather than
+generation, with generation as just one of several sources.
+
+> **Status: design-stage.** The architecture is researched and specified; the code is
+> being built. The API below is the *intended* surface (see the roadmap for what's
+> live). Follow along in [`misc/docs/`](misc/docs/).
+
+## The idea
+
+```python
+import foley
+
+# The headline — right sounds for a narrative context:
+# decompose the passage into salient sound events → search → verify → decide
+candidates = foley.find("She pushed open the heavy oak door; rain hammered outside.")
+
+# Direct hybrid search of your library (text query or a reference clip)
+hits = foley.search("distant thunder rumble", k=10, commercial_ok=True)
+
+# Generate a sound when nothing fits (arioso-style; pluggable backends)
+clip = foley.generate("a single wooden door creak", backend="stable_audio_open", duration=3)
+
+# Grow the library — ingest auto-tags, captions, and embeds every file
+foley.ingest("~/my_sounds/")
+foley.add_from("freesound", query="ocean waves", license="cc0")
+
+# Compose (future): render the sound design onto a narration
+foley.weave(narration_audio, candidates)
+```
+
+## How it works — four stages
+
+| Stage | What it does | Built on |
+|-------|--------------|----------|
+| **Source** | your own files · Freesound (CC0) · generate (Stable Audio Open / ElevenLabs) | config-driven adapters, per-sound license tracking |
+| **Index** | probe → tag → caption → embed every sound; hybrid keyword+semantic search | PANNs · CLAP · EnCLAP · LanceDB (local→cloud via `dol`) |
+| **Select** | decompose a narrative context → search → verify → generate-or-retrieve | CLAP retrieval + LLM decomposition + a verification ladder |
+| **Weave** | align to the voice, duck, place, master *(future)* | forced-alignment · LUFS/EBU-R128 |
+
+The selection tools publish as an **MCP server** (via `py2mcp`) so the same capabilities
+drive the agent, a CLI, and external hosts.
+
+## Design & research
+
+foley's design is grounded in five research reports (unified, cited):
+
+- [Design](misc/docs/design.md) · [Roadmap](misc/docs/roadmap.md)
+- [Research reports](misc/docs/research/) — sound sources, SFX generation, recognition/
+  tagging, embeddings/indexing, and the context-retrieval agent
+- [Deep-research prompt library](misc/docs/research/deep-research-prompts.md) — 12
+  ready-to-run prompts covering every dimension of the project
+
+## Install
+
+```
+pip install foley
+```
+
+(Optional per-capability extras — `foley[freesound]`, `foley[clap]`, `foley[stable-audio]`,
+`foley[index]`, … — are added as each subsystem lands.)
+
+## License
+
+MIT

foley-0.0.2/README.md

@@ -0,0 +1,76 @@
+# foley
+
+Find (or generate) the **right sound effect for a moment of narration** — and weave it in.
+
+foley is a **retrieval-first façade for sound effects**: one simple surface over many
+sound *sources* (your own library, service APIs, and generative-AI models), a searchable
+*index* of every sound (by keyword **and** meaning), an *agent* that picks the right
+sound for a narrative context, and a *compositor* that places it under the voice.
+
+It's the SFX sibling of [`arioso`](https://github.com/thorwhalen/arioso) (a unified
+façade over AI music-generation backends): same discipline — one entry function,
+config-driven plugin adapters, a unified vocabulary translated per-backend, zero
+required core deps with lazy optional-deps — but centered on **search** rather than
+generation, with generation as just one of several sources.
+
+> **Status: design-stage.** The architecture is researched and specified; the code is
+> being built. The API below is the *intended* surface (see the roadmap for what's
+> live). Follow along in [`misc/docs/`](misc/docs/).
+
+## The idea
+
+```python
+import foley
+
+# The headline — right sounds for a narrative context:
+# decompose the passage into salient sound events → search → verify → decide
+candidates = foley.find("She pushed open the heavy oak door; rain hammered outside.")
+
+# Direct hybrid search of your library (text query or a reference clip)
+hits = foley.search("distant thunder rumble", k=10, commercial_ok=True)
+
+# Generate a sound when nothing fits (arioso-style; pluggable backends)
+clip = foley.generate("a single wooden door creak", backend="stable_audio_open", duration=3)
+
+# Grow the library — ingest auto-tags, captions, and embeds every file
+foley.ingest("~/my_sounds/")
+foley.add_from("freesound", query="ocean waves", license="cc0")
+
+# Compose (future): render the sound design onto a narration
+foley.weave(narration_audio, candidates)
+```
+
+## How it works — four stages
+
+| Stage | What it does | Built on |
+|-------|--------------|----------|
+| **Source** | your own files · Freesound (CC0) · generate (Stable Audio Open / ElevenLabs) | config-driven adapters, per-sound license tracking |
+| **Index** | probe → tag → caption → embed every sound; hybrid keyword+semantic search | PANNs · CLAP · EnCLAP · LanceDB (local→cloud via `dol`) |
+| **Select** | decompose a narrative context → search → verify → generate-or-retrieve | CLAP retrieval + LLM decomposition + a verification ladder |
+| **Weave** | align to the voice, duck, place, master *(future)* | forced-alignment · LUFS/EBU-R128 |
+
+The selection tools publish as an **MCP server** (via `py2mcp`) so the same capabilities
+drive the agent, a CLI, and external hosts.
+
+## Design & research
+
+foley's design is grounded in five research reports (unified, cited):
+
+- [Design](misc/docs/design.md) · [Roadmap](misc/docs/roadmap.md)
+- [Research reports](misc/docs/research/) — sound sources, SFX generation, recognition/
+  tagging, embeddings/indexing, and the context-retrieval agent
+- [Deep-research prompt library](misc/docs/research/deep-research-prompts.md) — 12
+  ready-to-run prompts covering every dimension of the project
+
+## Install
+
+```
+pip install foley
+```
+
+(Optional per-capability extras — `foley[freesound]`, `foley[clap]`, `foley[stable-audio]`,
+`foley[index]`, … — are added as each subsystem lands.)
+
+## License
+
+MIT