bioaccx 0.1.0__tar.gz

bioaccx-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# output results
+custom_models/
+.cache/
+test_config.yaml

bioaccx-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

bioaccx-0.1.0/LICENSE

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

bioaccx-0.1.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.5
+Name: bioaccx
+Version: 0.1.0
+Summary: Bioacoustic neural network custom classifier generator
+Project-URL: Homepage, https://github.com/biodiversica/bioaccx
+Project-URL: Documentation, https://github.com/biodiversica/bioaccx/tree/master/docs
+Project-URL: Issues, https://github.com/biodiversica/bioaccx/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: huggingface-hub>=0.20
+Requires-Dist: kagglehub>=1.0.1
+Requires-Dist: numpy>=1.26
+Requires-Dist: onnx>=1.15
+Requires-Dist: onnxconverter-common>=1.14
+Requires-Dist: paramiko>=5.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: scikit-learn>=1.4
+Requires-Dist: scipy>=1.11
+Requires-Dist: skl2onnx>=1.17
+Requires-Dist: soundfile>=0.12
+Requires-Dist: sympy>=1.12
+Requires-Dist: tensorflow-cpu>=2.16; sys_platform == 'win32' or (sys_platform == 'linux' and platform_machine == 'x86_64')
+Requires-Dist: tensorflow>=2.16; sys_platform == 'darwin' or (sys_platform == 'linux' and platform_machine == 'aarch64')
+Requires-Dist: tf2onnx>=1.16
+Requires-Dist: typer>=0.27
+Provides-Extra: arbimon
+Provides-Extra: cpu
+Requires-Dist: onnxruntime>=1.17; extra == 'cpu'
+Provides-Extra: dev
+Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: gpu
+Requires-Dist: onnxruntime-gpu>=1.19; extra == 'gpu'
+Provides-Extra: gui
+Requires-Dist: fastapi>=0.110; extra == 'gui'
+Requires-Dist: ruamel-yaml>=0.18; extra == 'gui'
+Requires-Dist: uvicorn>=0.27; extra == 'gui'
+Provides-Extra: ssh
+Requires-Dist: paramiko>=3.0; extra == 'ssh'
+Provides-Extra: umap
+Requires-Dist: matplotlib>=3.11.0; extra == 'umap'
+Requires-Dist: umap-learn>=0.5.12; extra == 'umap'
+Description-Content-Type: text/markdown
+
+# bioaccx
+
+**BIOAcoustic Custom Classifier eXchange** — a Python CLI tool for training and sharing custom bioacoustic classifiers on top of pre-trained foundation models such as [BirdNET](https://birdnet.cornell.edu/) and [Perch](https://www.kaggle.com/models/google/bird-vocalization-classifier).
+
+The core idea is a clean separation between the **backbone** and the **classifier head**:
+
+- The backbone (foundation model) is a large, general-purpose audio encoder shared by the community.
+- The head is a small, task-specific classifier trained on your labeled data — just a few kilobytes.
+
+This separation enables two complementary workflows:
+
+**Share lightweight heads.** Because the head is tiny compared to the backbone, you can publish and distribute your custom classifier without bundling the full model. Anyone who already has the same backbone can load your head and run inference immediately.
+
+**Deploy as a single file.** When you need a self-contained model — for edge devices, cloud APIs, or third-party tools — bioaccx can merge the backbone and head into one ONNX or TFLite file with a single audio input and class-score output.
+
+**Skip re-embedding when you already have embeddings.** If you or your team have already run the backbone and saved the resulting embedding vectors, you can point bioaccx at that cache and train or evaluate the head directly — no audio processing, no GPU time, no waiting.
+
+**Build datasets from multiple sources in one config.** bioaccx can assemble training data from local recordings, [iNaturalist](https://www.inaturalist.org/) observations, [Xeno-canto](https://xeno-canto.org/) recordings, and [Arbimon](https://arbimon.org/) projects — all mixed in a single table or combined with a local directory. Remote audio is downloaded and cached automatically, so subsequent runs skip the network entirely.
+
+bioaccx handles the full pipeline from raw audio to exported model, driven by a single config file.
+
+---
+
+> 🇧🇷 [Leia em português](README.pt-BR.md)
+
+---
+
+## How it works
+
+```
+Audio files  →  Foundation model (backbone)  →  Embeddings
+                                                      ↓
+                                       Keras or sklearn classifier head
+                                                      ↓
+                             ┌────────────────────────────────────────┐
+                             │  backbone + head merged  │  head only  │
+                             │   (single-file deploy)   │ (shareable) │
+                             └────────────────────────────────────────┘
+```
+
+1. **Foundation model** — a backbone version of a bioacoustic model extracts rich feature vectors from raw audio windows. Supported formats: ONNX, TFLite, TF SavedModel (protobuf).
+2. **Classifier head** — a small Keras MLP or sklearn LogisticRegression is trained on top of those embeddings using your labeled data.
+3. **Export** — choose between:
+   - **Full model** (`output_type: full`): merges backbone + head into a single ONNX or TFLite graph. Drop-in inference with no external dependencies.
+   - **Head only** (`output_type: head`): exports just the classifier. Tiny file, easy to share; requires the backbone at inference time.
+   - **Both** (`output_type: both`): produces both variants.
+
+---
+
+---
+
+## Installation
+
+**No Python needed.** The installer sets everything up and adds a **bioaccx**
+shortcut that opens the [browser GUI](#the-browser-gui). Run it again to upgrade.
+
+Windows — open PowerShell and paste:
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://github.com/biodiversica/bioaccx/releases/latest/download/install.ps1 | iex"
+```
+
+macOS (Apple Silicon) and Linux — open a terminal and paste:
+
+```sh
+curl -LsSf https://github.com/biodiversica/bioaccx/releases/latest/download/install.sh | sh
+```
+
+**With uv or pip.** bioaccx runs models through ONNX Runtime, and **there is no
+default one** — pick `cpu` or `gpu` when you install. A plain `bioaccx` resolves
+and installs happily, then fails the moment it tries to run a model, so the
+extra is not optional in practice.
+
+```bash
+uv tool install --python 3.12 "bioaccx[cpu]"            # CPU inference
+uv tool install --python 3.12 "bioaccx[gpu]"            # CUDA 12
+uv tool install --python 3.12 "bioaccx[cpu,gui,umap]"   # with the browser GUI and UMAP plots
+
+uv add "bioaccx[cpu]"                                   # or as a project dependency
+```
+
+Extras go **inside the brackets** — `uv tool install` has no `--extra` flag — and
+the whole argument needs quoting so the shell does not glob them. `--python`
+keeps uv off a Python newer than TensorFlow supports.
+
+See [Installation](docs/en/installation.md) for what the installer does, the
+extras table, supported systems, working on bioaccx itself, GPU acceleration
+with CUDA, and how much disk this needs.
+
+---
+
+## Quick start
+
+```bash
+# 0. Browse available foundation models and their registry IDs
+bioaccx registry
+
+# 1. Copy and edit the example config
+cp example_config.yaml my_config.yaml
+
+# 2. Validate config without running training
+bioaccx validate my_config.yaml
+
+# 3. Export the dataset as chunked WAV files (no model needed)
+bioaccx dataset my_config.yaml
+
+# 4. Compute the embedding database + UMAP (no training)
+bioaccx embeddings my_config.yaml
+
+# 5. Train and export
+bioaccx train my_config.yaml
+```
+
+`bioaccx merge` and `bioaccx extract-head` do the same jobs without training —
+see [Merging, extracting and converting heads](docs/en/model-surgery.md).
+
+---
+
+## The browser GUI
+
+`bioaccx gui` opens a config editor in a browser. It writes the same YAML files
+every other command reads — the terminal stays the way runs are started.
+
+```bash
+uv tool install "bioaccx[cpu,gui]"      # the GUI needs the [gui] extra
+
+bioaccx gui                             # start from a template
+bioaccx gui my_config.yaml              # open an existing config
+bioaccx gui --lang pt-BR                # open it in Portuguese
+```
+
+The form is generated from the config dataclasses, so it offers exactly the keys
+this version understands, with their real defaults and help text; the file it
+writes is shown beside it as you type, and your comments survive the round-trip.
+The **run** tab starts a command on that config and streams its log into the
+page; the **analysis** tab reads what past runs wrote — metrics, the UMAP map
+with the audio behind each point, and two runs side by side.
+
+See [The browser GUI](docs/en/gui.md) for all of it, including
+[interface languages](docs/en/gui.md#interface-languages) and serving the editor
+to another machine.
+
+---
+
+## Configuration
+
+Everything a run does is described by one YAML file:
+[`example_config.yaml`](example_config.yaml) is a working starting point,
+[Configuration](docs/en/configuration.md) explains it section by section, and
+[Config reference](docs/en/config-reference.md) lists every key with its default.
+
+---
+
+## Documentation
+
+The full documentation lives in [`docs/en/`](docs/en/). This page covers what
+bioaccx is, how to install it, and how to get a first run out of it.
+
+| Page | What is in it |
+|---|---|
+| [Installation](docs/en/installation.md) | Install paths, the extras table, GPU acceleration, disk space |
+| [Quick start](docs/en/quickstart.md) | The commands of a first run, in order |
+| [The browser GUI](docs/en/gui.md) | `bioaccx gui` — config editor, results explorer, interface languages |
+| [Configuration](docs/en/configuration.md) | The config file section by section, with worked examples |
+| [Config reference](docs/en/config-reference.md) | Every config key, its default and its help text |
+| [Datasets](docs/en/dataset-modes.md) | Label layouts, train/test split, appending, combining sources |
+| [Remote sound sources](docs/en/remote-sources.md) | iNaturalist, Xeno-canto and Arbimon rows in one table |
+| [Augmentation and windowing](docs/en/augmentation.md) | Noise augmentation, random shift, windows and overlap |
+| [Embeddings, cache and UMAP](docs/en/embeddings-umap.md) | The embedding store, `bioaccx embeddings`, UMAP and KMeans/NMI |
+| [Outputs](docs/en/outputs.md) | Directory structure, metadata, precision, excluding labels |
+| [Merging, extracting and converting heads](docs/en/model-surgery.md) | `merge`, `extract-head`, `convert-head` |
+| [Foundation model registry](docs/en/registry.md) | Registry IDs, supported models, adding a new one |
+| [Python API](docs/en/python-api.md) | Using bioaccx as a library |
+| [CLI reference](docs/en/cli.md) | Every command and option |
+
+The config and CLI references are generated from the code by
+`tools/gen_docs.py`, so they cannot drift behind it — see
+[`docs/README.md`](docs/README.md).
+
+---
+
+## License
+
+[MIT](LICENSE)

bioaccx-0.1.0/README.md

@@ -0,0 +1,184 @@
+# bioaccx
+
+**BIOAcoustic Custom Classifier eXchange** — a Python CLI tool for training and sharing custom bioacoustic classifiers on top of pre-trained foundation models such as [BirdNET](https://birdnet.cornell.edu/) and [Perch](https://www.kaggle.com/models/google/bird-vocalization-classifier).
+
+The core idea is a clean separation between the **backbone** and the **classifier head**:
+
+- The backbone (foundation model) is a large, general-purpose audio encoder shared by the community.
+- The head is a small, task-specific classifier trained on your labeled data — just a few kilobytes.
+
+This separation enables two complementary workflows:
+
+**Share lightweight heads.** Because the head is tiny compared to the backbone, you can publish and distribute your custom classifier without bundling the full model. Anyone who already has the same backbone can load your head and run inference immediately.
+
+**Deploy as a single file.** When you need a self-contained model — for edge devices, cloud APIs, or third-party tools — bioaccx can merge the backbone and head into one ONNX or TFLite file with a single audio input and class-score output.
+
+**Skip re-embedding when you already have embeddings.** If you or your team have already run the backbone and saved the resulting embedding vectors, you can point bioaccx at that cache and train or evaluate the head directly — no audio processing, no GPU time, no waiting.
+
+**Build datasets from multiple sources in one config.** bioaccx can assemble training data from local recordings, [iNaturalist](https://www.inaturalist.org/) observations, [Xeno-canto](https://xeno-canto.org/) recordings, and [Arbimon](https://arbimon.org/) projects — all mixed in a single table or combined with a local directory. Remote audio is downloaded and cached automatically, so subsequent runs skip the network entirely.
+
+bioaccx handles the full pipeline from raw audio to exported model, driven by a single config file.
+
+---
+
+> 🇧🇷 [Leia em português](README.pt-BR.md)
+
+---
+
+## How it works
+
+```
+Audio files  →  Foundation model (backbone)  →  Embeddings
+                                                      ↓
+                                       Keras or sklearn classifier head
+                                                      ↓
+                             ┌────────────────────────────────────────┐
+                             │  backbone + head merged  │  head only  │
+                             │   (single-file deploy)   │ (shareable) │
+                             └────────────────────────────────────────┘
+```
+
+1. **Foundation model** — a backbone version of a bioacoustic model extracts rich feature vectors from raw audio windows. Supported formats: ONNX, TFLite, TF SavedModel (protobuf).
+2. **Classifier head** — a small Keras MLP or sklearn LogisticRegression is trained on top of those embeddings using your labeled data.
+3. **Export** — choose between:
+   - **Full model** (`output_type: full`): merges backbone + head into a single ONNX or TFLite graph. Drop-in inference with no external dependencies.
+   - **Head only** (`output_type: head`): exports just the classifier. Tiny file, easy to share; requires the backbone at inference time.
+   - **Both** (`output_type: both`): produces both variants.
+
+---
+
+---
+
+## Installation
+
+**No Python needed.** The installer sets everything up and adds a **bioaccx**
+shortcut that opens the [browser GUI](#the-browser-gui). Run it again to upgrade.
+
+Windows — open PowerShell and paste:
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://github.com/biodiversica/bioaccx/releases/latest/download/install.ps1 | iex"
+```
+
+macOS (Apple Silicon) and Linux — open a terminal and paste:
+
+```sh
+curl -LsSf https://github.com/biodiversica/bioaccx/releases/latest/download/install.sh | sh
+```
+
+**With uv or pip.** bioaccx runs models through ONNX Runtime, and **there is no
+default one** — pick `cpu` or `gpu` when you install. A plain `bioaccx` resolves
+and installs happily, then fails the moment it tries to run a model, so the
+extra is not optional in practice.
+
+```bash
+uv tool install --python 3.12 "bioaccx[cpu]"            # CPU inference
+uv tool install --python 3.12 "bioaccx[gpu]"            # CUDA 12
+uv tool install --python 3.12 "bioaccx[cpu,gui,umap]"   # with the browser GUI and UMAP plots
+
+uv add "bioaccx[cpu]"                                   # or as a project dependency
+```
+
+Extras go **inside the brackets** — `uv tool install` has no `--extra` flag — and
+the whole argument needs quoting so the shell does not glob them. `--python`
+keeps uv off a Python newer than TensorFlow supports.
+
+See [Installation](docs/en/installation.md) for what the installer does, the
+extras table, supported systems, working on bioaccx itself, GPU acceleration
+with CUDA, and how much disk this needs.
+
+---
+
+## Quick start
+
+```bash
+# 0. Browse available foundation models and their registry IDs
+bioaccx registry
+
+# 1. Copy and edit the example config
+cp example_config.yaml my_config.yaml
+
+# 2. Validate config without running training
+bioaccx validate my_config.yaml
+
+# 3. Export the dataset as chunked WAV files (no model needed)
+bioaccx dataset my_config.yaml
+
+# 4. Compute the embedding database + UMAP (no training)
+bioaccx embeddings my_config.yaml
+
+# 5. Train and export
+bioaccx train my_config.yaml
+```
+
+`bioaccx merge` and `bioaccx extract-head` do the same jobs without training —
+see [Merging, extracting and converting heads](docs/en/model-surgery.md).
+
+---
+
+## The browser GUI
+
+`bioaccx gui` opens a config editor in a browser. It writes the same YAML files
+every other command reads — the terminal stays the way runs are started.
+
+```bash
+uv tool install "bioaccx[cpu,gui]"      # the GUI needs the [gui] extra
+
+bioaccx gui                             # start from a template
+bioaccx gui my_config.yaml              # open an existing config
+bioaccx gui --lang pt-BR                # open it in Portuguese
+```
+
+The form is generated from the config dataclasses, so it offers exactly the keys
+this version understands, with their real defaults and help text; the file it
+writes is shown beside it as you type, and your comments survive the round-trip.
+The **run** tab starts a command on that config and streams its log into the
+page; the **analysis** tab reads what past runs wrote — metrics, the UMAP map
+with the audio behind each point, and two runs side by side.
+
+See [The browser GUI](docs/en/gui.md) for all of it, including
+[interface languages](docs/en/gui.md#interface-languages) and serving the editor
+to another machine.
+
+---
+
+## Configuration
+
+Everything a run does is described by one YAML file:
+[`example_config.yaml`](example_config.yaml) is a working starting point,
+[Configuration](docs/en/configuration.md) explains it section by section, and
+[Config reference](docs/en/config-reference.md) lists every key with its default.
+
+---
+
+## Documentation
+
+The full documentation lives in [`docs/en/`](docs/en/). This page covers what
+bioaccx is, how to install it, and how to get a first run out of it.
+
+| Page | What is in it |
+|---|---|
+| [Installation](docs/en/installation.md) | Install paths, the extras table, GPU acceleration, disk space |
+| [Quick start](docs/en/quickstart.md) | The commands of a first run, in order |
+| [The browser GUI](docs/en/gui.md) | `bioaccx gui` — config editor, results explorer, interface languages |
+| [Configuration](docs/en/configuration.md) | The config file section by section, with worked examples |
+| [Config reference](docs/en/config-reference.md) | Every config key, its default and its help text |
+| [Datasets](docs/en/dataset-modes.md) | Label layouts, train/test split, appending, combining sources |
+| [Remote sound sources](docs/en/remote-sources.md) | iNaturalist, Xeno-canto and Arbimon rows in one table |
+| [Augmentation and windowing](docs/en/augmentation.md) | Noise augmentation, random shift, windows and overlap |
+| [Embeddings, cache and UMAP](docs/en/embeddings-umap.md) | The embedding store, `bioaccx embeddings`, UMAP and KMeans/NMI |
+| [Outputs](docs/en/outputs.md) | Directory structure, metadata, precision, excluding labels |
+| [Merging, extracting and converting heads](docs/en/model-surgery.md) | `merge`, `extract-head`, `convert-head` |
+| [Foundation model registry](docs/en/registry.md) | Registry IDs, supported models, adding a new one |
+| [Python API](docs/en/python-api.md) | Using bioaccx as a library |
+| [CLI reference](docs/en/cli.md) | Every command and option |
+
+The config and CLI references are generated from the code by
+`tools/gen_docs.py`, so they cannot drift behind it — see
+[`docs/README.md`](docs/README.md).
+
+---
+
+## License
+
+[MIT](LICENSE)

bioaccx-0.1.0/README.pt-BR.md

@@ -0,0 +1,189 @@
+<!-- translated-from: README.md@0ee356cafe56 -->
+# bioaccx
+
+**BIOAcoustic Custom Classifier eXchange** — uma ferramenta Python de linha de comando para treinar e compartilhar classificadores bioacústicos customizados sobre modelos base pré-treinados como o [BirdNET](https://birdnet.cornell.edu/) e o [Perch](https://www.kaggle.com/models/google/bird-vocalization-classifier).
+
+A ideia central é separar de forma limpa o **backbone** e o **classifier head**:
+
+- O backbone (modelo base) é um codificador de áudio grande e de uso geral, compartilhado pela comunidade.
+- O head é um classificador pequeno, específico da sua tarefa, treinado nos seus dados rotulados — alguns poucos kilobytes.
+
+Essa separação permite dois fluxos complementares:
+
+**Compartilhar heads leves.** Como classificadores customizados são geralmente pequenos perto do backbone, você pode publicar e distribuir seu classificador sem levar junto o modelo inteiro. Quem já tem o mesmo backbone carrega o seu classificador e roda a inferência na hora.
+
+**Publicar como um arquivo único.** Quando você precisa de um modelo autocontido — para dispositivos de borda, APIs na nuvem ou ferramentas de terceiros — o bioaccx funde backbone e head em um único arquivo ONNX ou TFLite, com uma entrada de áudio e uma saída de pontuações por classe.
+
+**Pular o reprocessamento quando você já tem os embeddings.** Se você ou sua equipe já rodaram o backbone e guardaram os vetores de embedding, dá para apontar o bioaccx para esse cache e treinar ou avaliar o head direto — sem processar áudio, sem tempo de GPU, sem espera.
+
+**Montar datasets de várias fontes em uma configuração só.** O bioaccx monta os dados de treino a partir de gravações locais, observações do [iNaturalist](https://www.inaturalist.org/), gravações do [Xeno-canto](https://xeno-canto.org/) e projetos do [Arbimon](https://arbimon.org/) — tudo misturado em uma tabela, ou combinado com um diretório local. O áudio remoto é baixado e cacheado automaticamente, então as execuções seguintes não tocam a rede.
+
+O bioaccx cuida do caminho inteiro, do áudio bruto ao modelo exportado, guiado por um único arquivo de configuração.
+
+> 🇬🇧 [Read in English](README.md)
+
+---
+
+## Como funciona
+
+```
+Arquivos de áudio  →  Modelo base (backbone)  →  Embeddings
+                                                      ↓
+                              Classifier head Keras ou sklearn
+                                                      ↓
+                             ┌────────────────────────────────────────┐
+                             │  backbone + head fundidos │ só o head  │
+                             │    (arquivo único)        │(compartilhável)│
+                             └────────────────────────────────────────┘
+```
+
+1. **Modelo base** — uma versão backbone de um modelo bioacústico extrai vetores de características ricos de janelas de áudio bruto. Formatos suportados: ONNX, TFLite, TF SavedModel (protobuf).
+2. **Classifier head** — uma pequena MLP em Keras ou uma LogisticRegression do sklearn é treinada sobre esses embeddings com os seus dados rotulados.
+3. **Exportação** — escolha entre:
+   - **Modelo completo** (`output_type: full`): funde backbone + head em um único grafo ONNX ou TFLite. Inferência direta, sem dependências externas.
+   - **Só o classificador (head)** (`output_type: head`): exporta apenas o classificador. Arquivo minúsculo, fácil de compartilhar; exige o backbone na hora da inferência.
+   - **Ambos** (`output_type: both`): produz as duas variantes.
+
+---
+
+## Instalação
+
+**Sem precisar de Python.** O instalador prepara tudo e adiciona um atalho
+**bioaccx** que abre a [GUI no navegador](#a-gui-no-navegador). Rode de novo
+para atualizar.
+
+No Windows — abra o PowerShell e cole:
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://github.com/biodiversica/bioaccx/releases/latest/download/install.ps1 | iex"
+```
+
+No macOS (Apple Silicon) e no Linux — abra um terminal e cole:
+
+```sh
+curl -LsSf https://github.com/biodiversica/bioaccx/releases/latest/download/install.sh | sh
+```
+
+**Com uv ou pip.** O bioaccx executa os modelos pelo ONNX Runtime, e **não há um
+padrão** — escolha `cpu` ou `gpu` na instalação. Um `bioaccx` sem extras instala
+sem reclamar e falha no momento em que tenta rodar um modelo, então na prática o
+extra não é opcional.
+
+```bash
+uv tool install --python 3.12 "bioaccx[cpu]"            # inferência na CPU
+uv tool install --python 3.12 "bioaccx[gpu]"            # CUDA 12
+uv tool install --python 3.12 "bioaccx[cpu,gui,umap]"   # com a GUI no navegador e os gráficos UMAP
+
+uv add "bioaccx[cpu]"                                   # ou como dependência de um projeto
+```
+
+Os extras vão **dentro dos colchetes** — o `uv tool install` não tem a opção
+`--extra` — e o argumento inteiro precisa de aspas para o shell não expandi-los.
+O `--python` impede o uv de escolher um Python mais novo do que o TensorFlow
+suporta.
+
+Veja [Instalação](docs/pt-BR/installation.md) para o que o instalador faz, a
+tabela de extras, os sistemas suportados, como trabalhar no próprio bioaccx,
+aceleração por GPU com CUDA e quanto disso ocupa em disco.
+
+---
+
+## Primeiros passos
+
+```bash
+# 0. Veja os modelos base disponíveis e seus IDs
+bioaccx registry
+
+# 1. Copie e edite a configuração de exemplo
+cp example_config.yaml my_config.yaml
+
+# 2. Valide a configuração sem rodar o treinamento
+bioaccx validate my_config.yaml
+
+# 3. Exporte o dataset como arquivos WAV em trechos (sem precisar do modelo)
+bioaccx dataset my_config.yaml
+
+# 4. Calcule o banco de embeddings + UMAP (sem treinar)
+bioaccx embeddings my_config.yaml
+
+# 5. Treine e exporte
+bioaccx train my_config.yaml
+```
+
+O `bioaccx merge` e o `bioaccx extract-head` fazem os mesmos trabalhos sem
+treinar — veja
+[Merging, extracting and converting heads](docs/en/model-surgery.md).
+
+---
+
+## A GUI no navegador
+
+O `bioaccx gui` abre um editor de configuração no navegador. Ele escreve os
+mesmos arquivos YAML que todos os outros comandos leem — o terminal continua
+sendo o lugar de onde as execuções partem.
+
+```bash
+uv tool install "bioaccx[cpu,gui]"      # a GUI precisa do extra [gui]
+
+bioaccx gui                             # começa de um modelo em branco
+bioaccx gui my_config.yaml              # abre uma configuração existente
+bioaccx gui --lang pt-BR                # abre em português
+```
+
+O formulário é gerado a partir das dataclasses de configuração, então oferece
+exatamente as keys que esta versão entende, com os valores padrão de verdade e
+os textos de ajuda; o arquivo que ele escreve aparece ao lado enquanto você
+digita, e seus comentários sobrevivem ao round-trip. A aba **executar** inicia
+um comando sobre essa configuração, com o log chegando na página ao vivo; a aba
+**análise** lê o que as execuções passadas escreveram — métricas, o mapa UMAP
+com o áudio por trás de cada ponto, e duas execuções lado a lado.
+
+Veja [A GUI no navegador](docs/pt-BR/gui.md) para tudo isso, incluindo os
+[idiomas da interface](docs/pt-BR/gui.md#idiomas-da-interface) e como servir o
+editor para outra máquina.
+
+---
+
+## Configuração
+
+Tudo o que uma execução faz é descrito por um único arquivo YAML: o
+[`example_config.yaml`](example_config.yaml) é um ponto de partida que funciona,
+[Configuration](docs/en/configuration.md) explica seção por seção (em inglês), e
+a [Referência de configuração](docs/pt-BR/config-reference.md) lista todas as
+keys com seus valores padrão.
+
+---
+
+## Documentação
+
+A documentação completa está em [`docs/pt-BR/`](docs/pt-BR/). Esta página cobre
+o que o bioaccx é, como instalá-lo e como tirar dele uma primeira execução.
+
+| Página | Conteúdo |
+|---|---|
+| [Instalação](docs/pt-BR/installation.md) | Formas de instalar, a tabela de extras, aceleração por GPU, espaço em disco |
+| [Primeiros passos](docs/pt-BR/quickstart.md) | Os comandos de uma primeira execução, em ordem |
+| [A GUI no navegador](docs/pt-BR/gui.md) | `bioaccx gui` — editor de configuração, explorador de resultados, idiomas |
+| [Referência de configuração](docs/pt-BR/config-reference.md) | Todas as keys, com valor padrão e descrição |
+| [Configuration](docs/en/configuration.md) 🇬🇧 | O arquivo de configuração seção por seção, com exemplos |
+| [Datasets](docs/en/dataset-modes.md) 🇬🇧 | Formatos de rótulo, divisão train/test, acréscimo, múltiplas fontes |
+| [Remote sound sources](docs/en/remote-sources.md) 🇬🇧 | iNaturalist, Xeno-canto e Arbimon em uma tabela só |
+| [Augmentation and windowing](docs/en/augmentation.md) 🇬🇧 | Ruído, deslocamento aleatório, janelas e sobreposição |
+| [Embeddings, cache and UMAP](docs/en/embeddings-umap.md) 🇬🇧 | O banco de embeddings, `bioaccx embeddings`, UMAP e KMeans/NMI |
+| [Outputs](docs/en/outputs.md) 🇬🇧 | Estrutura de diretórios, metadados, precisão, excluir rótulos |
+| [Merging, extracting and converting heads](docs/en/model-surgery.md) 🇬🇧 | `merge`, `extract-head`, `convert-head` |
+| [Foundation model registry](docs/en/registry.md) 🇬🇧 | IDs do registro, modelos suportados, adicionar um novo |
+| [Python API](docs/en/python-api.md) 🇬🇧 | Usar o bioaccx como biblioteca |
+| [CLI reference](docs/en/cli.md) 🇬🇧 | Todos os comandos e opções |
+
+As páginas marcadas com 🇬🇧 ainda não foram traduzidas e estão em inglês.
+
+As referências de configuração e da CLI são geradas a partir do código pelo
+`tools/gen_docs.py`, então não têm como ficar para trás dele — veja
+[`docs/README.md`](docs/README.md).
+
+---
+
+## Licença
+
+[MIT](LICENSE)

bioaccx-0.1.0/bioaccx/__init__.py

@@ -0,0 +1,6 @@
+"""bioaccx — bioacoustic custom classifier generator."""
+from bioaccx.config import BioaccxConfig, load_config
+from bioaccx.train import run
+
+__all__ = ["BioaccxConfig", "load_config", "run"]
+__version__ = "0.1.0"

bioaccx-0.1.0/bioaccx/__main__.py

@@ -0,0 +1,10 @@
+import signal
+
+from bioaccx.cli import main
+
+# The GUI cancels a run on Windows with Ctrl+Break (see gui/jobs.py), which
+# would otherwise end the process without the clean "Interrupted." exit.
+if hasattr(signal, "SIGBREAK"):
+    signal.signal(signal.SIGBREAK, signal.default_int_handler)
+
+main()