jrrribeiro commited on
Commit
9e885e1
·
1 Parent(s): c85843b

chore: remove leftover non-essential planning artifacts

Browse files
GITHUB_ISSUES_HF_VALIDATOR.md DELETED
@@ -1,312 +0,0 @@
1
- # GitHub Issues - BirdNET Validator HF
2
-
3
- Use este arquivo como roteiro para abrir as issues no novo repositorio do app.
4
- Sugestao: criar milestones por sprint e labels por tipo.
5
-
6
- ## Labels sugeridas
7
- - epic
8
- - p0
9
- - p1
10
- - backend
11
- - frontend
12
- - infra
13
- - data
14
- - auth
15
- - performance
16
- - testing
17
-
18
- ## Milestones sugeridas
19
- - Sprint 0 - Preparacao
20
- - Sprint 1 - Ingestao e indice
21
- - Sprint 2 - Core leitura e cache
22
- - Sprint 3 - Persistencia colaborativa
23
- - Sprint 4 - Seguranca multi-projeto
24
- - Sprint 5 - UX e performance
25
- - Sprint 6 - Operacao e qualidade
26
-
27
- ## Issue 01 - Bootstrap do repositorio e CI minima
28
- Title: [Sprint 0][P0] Bootstrap do repositorio BirdNET-validator-App
29
- Labels: epic, p0, infra
30
- Milestone: Sprint 0 - Preparacao
31
- Body:
32
- - Objetivo: inicializar o novo repositorio com estrutura base, lint, testes e pipeline minima.
33
- - Tarefas:
34
- - Criar estrutura src, tests, docs, cli.
35
- - Adicionar pyproject.toml e requirements.
36
- - Adicionar pre-commit (opcional) e GitHub Actions para teste.
37
- - Subir app Gradio minimo com tela placeholder.
38
- - Criterios de aceite:
39
- - Repo roda local sem erro.
40
- - CI executa em PR.
41
- - README inicial com setup local.
42
-
43
- ## Issue 02 - Modelos de dominio e validacao de schema
44
- Title: [Sprint 0][P0] Definir modelos de dominio e schema
45
- Labels: p0, backend, data
46
- Milestone: Sprint 0 - Preparacao
47
- Body:
48
- - Objetivo: criar modelos Project, Detection, Validation, User, Role, IndexManifest.
49
- - Tarefas:
50
- - Implementar modelos com dataclass/pydantic.
51
- - Incluir validacoes de campos obrigatorios.
52
- - Fixar versao do schema para evolucao futura.
53
- - Criterios de aceite:
54
- - Testes unitarios de validacao passam.
55
- - Modelos serializam/deserializam sem perda.
56
-
57
- ## Issue 03 - Contratos de repositorio e fake adapters
58
- Title: [Sprint 0][P0] Criar contratos de repositorio e adapters fake
59
- Labels: p0, backend
60
- Milestone: Sprint 0 - Preparacao
61
- Body:
62
- - Objetivo: desacoplar UI da persistencia desde o inicio.
63
- - Tarefas:
64
- - Definir interfaces: ProjectRepository, DetectionRepository, ValidationRepository, AuthRepository.
65
- - Implementar adapters fake para testes locais.
66
- - Criterios de aceite:
67
- - Casos basicos funcionam sem HF remoto.
68
- - Cobertura minima dos contratos.
69
-
70
- ## Issue 04 - CLI create-project para dataset HF
71
- Title: [Sprint 1][P0] Implementar comando create-project
72
- Labels: p0, backend, data
73
- Milestone: Sprint 1 - Ingestao e indice
74
- Body:
75
- - Objetivo: criar estrutura do dataset por projeto no Hugging Face.
76
- - Tarefas:
77
- - Criar comando create-project.
78
- - Estrutura inicial: audio, index, validations, audit, manifest.json.
79
- - Criterios de aceite:
80
- - Estrutura criada corretamente em dataset novo.
81
- - Comando idempotente quando projeto ja existe.
82
-
83
- ## Issue 05 - CLI sync-audio com resume e retry
84
- Title: [Sprint 1][P0] Upload de audio em lotes com resume idempotente
85
- Labels: p0, backend, data, performance
86
- Milestone: Sprint 1 - Ingestao e indice
87
- Body:
88
- - Objetivo: subir audios sem depender de fluxo Git LFS local.
89
- - Tarefas:
90
- - Implementar sync-audio em lotes.
91
- - Retry com backoff e resume por checkpoint.
92
- - Log transacional por lote.
93
- - Criterios de aceite:
94
- - Falha de rede nao duplica uploads.
95
- - Retomada completa apos interrupcao.
96
-
97
- ## Issue 06 - CLI build-index e checksums
98
- Title: [Sprint 1][P0] Gerar index_manifest e shards de deteccao
99
- Labels: p0, data, backend
100
- Milestone: Sprint 1 - Ingestao e indice
101
- Body:
102
- - Objetivo: permitir leitura paginada rapida no app.
103
- - Tarefas:
104
- - Gerar manifest.json com estatisticas.
105
- - Gerar shards de deteccoes e checksums.
106
- - Criterios de aceite:
107
- - Manifesto referencia apenas artefatos existentes.
108
- - Validacao de integridade passa.
109
-
110
- ## Issue 07 - CLI verify-project
111
- Title: [Sprint 1][P0] Verificador de consistencia do projeto
112
- Labels: p0, data, testing
113
- Milestone: Sprint 1 - Ingestao e indice
114
- Body:
115
- - Objetivo: validar consistencia audio x index x deteccoes.
116
- - Tarefas:
117
- - Implementar comando verify-project.
118
- - Emitir relatorio com erros e warnings.
119
- - Criterios de aceite:
120
- - Retorna codigo de erro em inconsistencias.
121
-
122
- ## Issue 08 - Fila paginada de deteccoes
123
- Title: [Sprint 2][P0] Implementar detection queue paginada
124
- Labels: p0, backend, performance
125
- Milestone: Sprint 2 - Core leitura e cache
126
- Body:
127
- - Objetivo: navegar grandes volumes sem travar UI.
128
- - Tarefas:
129
- - API interna de pagina com filtros.
130
- - Ordenacao estavel e cursor/offset.
131
- - Criterios de aceite:
132
- - Navega 50k deteccoes com fluidez.
133
-
134
- ## Issue 09 - Download sob demanda por audio_id
135
- Title: [Sprint 2][P0] AudioFetchService para arquivo individual
136
- Labels: p0, backend, performance
137
- Milestone: Sprint 2 - Core leitura e cache
138
- Body:
139
- - Objetivo: baixar somente audio da deteccao ativa.
140
- - Tarefas:
141
- - Implementar fetch por audio_id.
142
- - Tratamento de erro e retry curto.
143
- - Criterios de aceite:
144
- - Nenhum preload global do dataset.
145
-
146
- ## Issue 10 - Cache efemero e cleanup apos validacao
147
- Title: [Sprint 2][P0] Implementar cache LRU TTL e limpeza pos-validacao
148
- Labels: p0, backend, performance
149
- Milestone: Sprint 2 - Core leitura e cache
150
- Body:
151
- - Objetivo: reduzir custo e memoria mantendo comportamento seguro.
152
- - Tarefas:
153
- - Cache em RAM e /tmp com limite configuravel.
154
- - Cleanup apos salvar validacao.
155
- - Criterios de aceite:
156
- - Temporario removido apos validacao.
157
- - Arquivo remoto permanece intacto.
158
-
159
- ## Issue 11 - Persistencia append-only de validacoes
160
- Title: [Sprint 3][P0] Log append-only de eventos de validacao
161
- Labels: p0, backend, data
162
- Milestone: Sprint 3 - Persistencia colaborativa
163
- Body:
164
- - Objetivo: garantir trilha auditavel completa.
165
- - Tarefas:
166
- - Salvar eventos em shards por data.
167
- - Incluir usuario, status anterior/novo, timestamp, notas.
168
- - Criterios de aceite:
169
- - Toda alteracao gera evento auditavel.
170
-
171
- ## Issue 12 - Snapshot current por detection_key
172
- Title: [Sprint 3][P0] Materializar estado atual de validacoes
173
- Labels: p0, backend, data, performance
174
- Milestone: Sprint 3 - Persistencia colaborativa
175
- Body:
176
- - Objetivo: acelerar leitura do estado mais recente.
177
- - Tarefas:
178
- - Consolidar eventos em current.parquet.
179
- - Criterios de aceite:
180
- - Lookup por detection_key em baixa latencia.
181
-
182
- ## Issue 13 - Concorrencia otimista e merge de conflito
183
- Title: [Sprint 3][P0] Controle de concorrencia para validadores simultaneos
184
- Labels: p0, backend
185
- Milestone: Sprint 3 - Persistencia colaborativa
186
- Body:
187
- - Objetivo: evitar perda silenciosa de dados.
188
- - Tarefas:
189
- - Implementar revisao/etag.
190
- - Definir merge deterministico de conflitos.
191
- - Criterios de aceite:
192
- - Nao ha perda de validacao em concorrencia.
193
-
194
- ## Issue 14 - Login e sessao com papeis
195
- Title: [Sprint 4][P0] AuthService com usuarios e papeis
196
- Labels: p0, auth, backend
197
- Milestone: Sprint 4 - Seguranca multi-projeto
198
- Body:
199
- - Objetivo: controlar acesso ao app e por projeto.
200
- - Tarefas:
201
- - Login e sessao segura.
202
- - Papel admin e validator.
203
- - Criterios de aceite:
204
- - Usuario sem permissao nao acessa projeto indevido.
205
-
206
- ## Issue 15 - ACL por projeto
207
- Title: [Sprint 4][P0] Isolamento de acesso por projeto
208
- Labels: p0, auth, backend
209
- Milestone: Sprint 4 - Seguranca multi-projeto
210
- Body:
211
- - Objetivo: evitar vazamento entre projetos.
212
- - Tarefas:
213
- - Enforcar filtro por projeto em todas consultas.
214
- - Criterios de aceite:
215
- - Dados de um projeto nao aparecem em outro.
216
-
217
- ## Issue 16 - Painel Admin multi-projeto
218
- Title: [Sprint 4][P0] UI admin para projetos e membros
219
- Labels: p0, frontend, auth
220
- Milestone: Sprint 4 - Seguranca multi-projeto
221
- Body:
222
- - Objetivo: operar ambiente sem editar codigo.
223
- - Tarefas:
224
- - Criar/arquivar projeto.
225
- - Atribuir usuarios por projeto.
226
- - Mostrar progresso por projeto.
227
- - Criterios de aceite:
228
- - Alteracoes ficam disponiveis para novas sessoes.
229
-
230
- ## Issue 17 - Fluxo rapido de validacao
231
- Title: [Sprint 5][P1] Acoes rapidas com auto-avanco
232
- Labels: p1, frontend
233
- Milestone: Sprint 5 - UX e performance
234
- Body:
235
- - Objetivo: aumentar throughput humano.
236
- - Tarefas:
237
- - Positivo/Negativo/Indeterminado/Pular com 1 clique.
238
- - Criterios de aceite:
239
- - Apos salvar, app avanca automaticamente.
240
-
241
- ## Issue 18 - Filtros compostos
242
- Title: [Sprint 5][P1] Filtros por especie confianca status localidade data
243
- Labels: p1, frontend, backend
244
- Milestone: Sprint 5 - UX e performance
245
- Body:
246
- - Objetivo: melhorar foco de validacao.
247
- - Criterios de aceite:
248
- - Combinacao de filtros retorna resultados corretos.
249
-
250
- ## Issue 19 - Recuperacao de sessao
251
- Title: [Sprint 5][P1] Restaurar ultimo contexto do usuario
252
- Labels: p1, frontend
253
- Milestone: Sprint 5 - UX e performance
254
- Body:
255
- - Objetivo: evitar perda de contexto ao recarregar.
256
- - Criterios de aceite:
257
- - Ultimo item e filtros principais restaurados.
258
-
259
- ## Issue 20 - Prefetch curto de audio
260
- Title: [Sprint 5][P1] Prefetch de N proximos audios
261
- Labels: p1, performance, backend
262
- Milestone: Sprint 5 - UX e performance
263
- Body:
264
- - Objetivo: reduzir latencia do proximo item.
265
- - Criterios de aceite:
266
- - Melhora p95 sem extrapolar limite de cache.
267
-
268
- ## Issue 21 - Logs estruturados
269
- Title: [Sprint 6][P1] Logging estruturado com correlacao
270
- Labels: p1, infra
271
- Milestone: Sprint 6 - Operacao e qualidade
272
- Body:
273
- - Objetivo: facilitar observabilidade e suporte.
274
- - Criterios de aceite:
275
- - Erros rastreaveis por usuario/projeto/request.
276
-
277
- ## Issue 22 - Metricas e painel operacional
278
- Title: [Sprint 6][P1] Metricas de latencia erro throughput
279
- Labels: p1, performance, frontend
280
- Milestone: Sprint 6 - Operacao e qualidade
281
- Body:
282
- - Objetivo: monitorar saude do sistema em producao.
283
- - Criterios de aceite:
284
- - p50/p95 e taxa de erro visiveis no admin.
285
-
286
- ## Issue 23 - Testes de integracao e carga basica
287
- Title: [Sprint 6][P1] Suite minima de qualidade para release
288
- Labels: p1, testing
289
- Milestone: Sprint 6 - Operacao e qualidade
290
- Body:
291
- - Objetivo: reduzir regressao antes de producao.
292
- - Criterios de aceite:
293
- - CI verde com testes unitarios e integracao.
294
-
295
- ## Dependencias recomendadas entre issues
296
- - 01 -> 02 -> 03
297
- - 03 -> 08, 09, 10, 11, 14
298
- - 04, 05, 06 -> 07
299
- - 06, 08 -> 09
300
- - 09 -> 10 -> 20
301
- - 11 -> 12 -> 13
302
- - 14 -> 15 -> 16
303
- - 08, 12, 14, 15 -> 17, 18, 19
304
- - Todas P0 -> 21, 22, 23
305
-
306
- ## Checklist de fechamento da v1
307
- - [ ] Upload CLI funcional para projetos grandes
308
- - [ ] Index paginado publicado por projeto
309
- - [ ] Audio sob demanda com cleanup local
310
- - [ ] Validacao colaborativa com auditoria
311
- - [ ] ACL por projeto e painel admin
312
- - [ ] Metricas e testes minimos em CI
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
HUGGINGFACE_VALIDATOR_BACKLOG.md DELETED
@@ -1,244 +0,0 @@
1
- # BirdNET Validator HF - Backlog Executavel
2
-
3
- ## 1) Objetivo
4
- Construir um novo app de validacao de deteccoes BirdNET para Hugging Face Spaces (Gradio), reutilizavel para varios projetos, com:
5
- - Um dataset Hugging Face por projeto
6
- - Download de audio sob demanda (1 arquivo por vez)
7
- - Limpeza de memoria/temporario apos validacao
8
- - Sem remover arquivos no dataset remoto
9
- - Upload de dados via CLI usando API (`huggingface_hub`), sem fluxo Git LFS local
10
- - Gestao de usuarios/papeis e isolamento por projeto
11
-
12
- ## 2) Estrategia de repositorios
13
- ### Repositorio 1 (novo): app
14
- - Nome sugerido: `BirdNET-validator-App`
15
- - Conteudo: Gradio app, servicos, auth, cache, UI, testes, docs de deploy
16
-
17
- ### Repositorios 2..N: datasets por projeto
18
- - Nome sugerido: `birdnet-<project-slug>-dataset`
19
- - Conteudo: `audio/`, `index/`, `validations/`, `audit/`, `manifest.json`
20
-
21
- ### Estrutura de pastas do app
22
- ```text
23
- BirdNET-validator-App/
24
- app.py
25
- requirements.txt
26
- README.md
27
- src/
28
- domain/
29
- services/
30
- repositories/
31
- auth/
32
- ui/
33
- cache/
34
- telemetry/
35
- cli/
36
- hf_dataset_cli.py
37
- tests/
38
- unit/
39
- integration/
40
- docs/
41
- architecture.md
42
- operations.md
43
- ```
44
-
45
- ## 3) Definicoes tecnicas fechadas
46
- - UI: Gradio no Hugging Face Space
47
- - Armazenamento principal: Hugging Face Datasets
48
- - Granularidade: 1 dataset por projeto
49
- - Ingestao: CLI separada com `huggingface_hub`
50
- - Identidade de deteccao: `detection_key` estavel e imutavel
51
- - Leitura de audio: sob demanda por `audio_id`
52
- - Cache local: efemero (RAM + /tmp), com limite por tamanho e TTL
53
- - Pos-validacao: limpar buffer em memoria e arquivo temporario local
54
- - Nunca deletar audio original do dataset remoto durante validacao
55
-
56
- ## 4) Definicao de pronto (DoD)
57
- Uma tarefa so e considerada pronta quando:
58
- 1. Codigo implementado com testes minimos
59
- 2. Logs de erro e sucesso adicionados
60
- 3. Documentacao curta atualizada
61
- 4. Validada em ambiente local
62
- 5. Sem regressao em fluxo principal
63
-
64
- ## 5) Epics e backlog por prioridade
65
-
66
- ## Epic A - Bootstrap do novo app e arquitetura base (P0)
67
- ### A1. Criar novo repositorio do app
68
- - Descricao: inicializar `BirdNET-validator-App` com estrutura base
69
- - Entregavel: repo criado + branch strategy + CI minima
70
- - Criterio de aceite: app sobe local com tela inicial vazia
71
-
72
- ### A2. Definir modelos de dominio
73
- - Descricao: `Project`, `Detection`, `Validation`, `User`, `Role`, `IndexManifest`
74
- - Entregavel: dataclasses/pydantic + validacoes de schema
75
- - Criterio de aceite: validacao de payload passa em testes unitarios
76
-
77
- ### A3. Definir contratos de repositorio
78
- - Descricao: interfaces para ProjectRepo, DetectionRepo, ValidationRepo, AuthRepo
79
- - Entregavel: interfaces + implementacao fake para teste
80
- - Criterio de aceite: casos basicos executam sem dependencia externa
81
-
82
- ## Epic B - CLI de ingestao para Hugging Face (P0)
83
- ### B1. Comando create-project
84
- - Descricao: criar estrutura do dataset remoto por projeto
85
- - Entregavel: comando `create-project`
86
- - Criterio de aceite: estrutura minima criada no repo dataset
87
-
88
- ### B2. Comando sync-audio em lotes
89
- - Descricao: upload de audios em batch com retry e resume idempotente
90
- - Entregavel: comando `sync-audio --resume`
91
- - Criterio de aceite: interrupcao de rede nao duplica arquivos
92
-
93
- ### B3. Comando build-index
94
- - Descricao: gerar `manifest.json` + shards de deteccoes
95
- - Entregavel: pasta `index/` com particoes e checksums
96
- - Criterio de aceite: manifesto referencia somente arquivos existentes
97
-
98
- ### B4. Comando verify-project
99
- - Descricao: checar consistencia audio x index x deteccoes
100
- - Entregavel: relatorio de saude do projeto
101
- - Criterio de aceite: retorna codigo de erro quando houver inconsistencias
102
-
103
- ## Epic C - Leitura paginada e audio sob demanda (P0)
104
- ### C1. Detection queue paginada
105
- - Descricao: listar deteccoes por pagina + filtros
106
- - Entregavel: API interna de pagina com cursor/offset
107
- - Criterio de aceite: navegar 50k deteccoes sem travar UI
108
-
109
- ### C2. Download individual de audio
110
- - Descricao: baixar so o audio da deteccao ativa
111
- - Entregavel: `AudioFetchService.fetch(audio_id)`
112
- - Criterio de aceite: sem pre-download global de dataset
113
-
114
- ### C3. Cache efemero com limpeza
115
- - Descricao: LRU/TTL em RAM e /tmp
116
- - Entregavel: `CacheManager` com `cleanup_after_validation()`
117
- - Criterio de aceite: arquivo temporario removido apos salvar validacao
118
-
119
- ### C4. Prefetch curto
120
- - Descricao: prefetch dos proximos N audios
121
- - Entregavel: worker simples de prefetch
122
- - Criterio de aceite: melhora p95 de carregamento sem extrapolar limite de cache
123
-
124
- ## Epic D - Persistencia de validacoes no HF Dataset (P0)
125
- ### D1. Modelo append-only de eventos
126
- - Descricao: salvar validacoes em log de eventos por projeto
127
- - Entregavel: `validations/events-YYYYMMDD.parquet` (ou csv shard)
128
- - Criterio de aceite: toda alteracao gera evento auditavel
129
-
130
- ### D2. Snapshot consolidado
131
- - Descricao: materializar estado atual por `detection_key`
132
- - Entregavel: `validations/current.parquet`
133
- - Criterio de aceite: lookup por detection_key em tempo baixo
134
-
135
- ### D3. Controle de concorrencia
136
- - Descricao: controle otimista por revisao/etag
137
- - Entregavel: rejeicao de escrita concorrente conflitante + merge rule
138
- - Criterio de aceite: dois validadores simultaneos nao perdem dados silenciosamente
139
-
140
- ## Epic E - Auth, papeis e isolamento por projeto (P0)
141
- ### E1. Login e sessao
142
- - Descricao: autenticar usuarios e carregar perfil/papeis
143
- - Entregavel: AuthService + sessao segura
144
- - Criterio de aceite: usuario sem permissao nao entra em projeto nao autorizado
145
-
146
- ### E2. ACL por projeto
147
- - Descricao: vincular usuario a um ou mais projetos
148
- - Entregavel: autorizacao por projeto em todas rotas de dados
149
- - Criterio de aceite: consultas sempre filtradas por projeto autorizado
150
-
151
- ### E3. Painel admin
152
- - Descricao: criar/arquivar projeto, atribuir usuarios, ver progresso
153
- - Entregavel: UI admin funcional
154
- - Criterio de aceite: alteracoes refletidas imediatamente nas sessoes novas
155
-
156
- ## Epic F - UX de validacao e produtividade (P1)
157
- ### F1. Fluxo rapido de validacao
158
- - Descricao: botoes de acao + avancar automaticamente
159
- - Entregavel: fluxo Positivo/Negativo/Indeterminado/Pular
160
- - Criterio de aceite: 1 clique para validar e ir para proximo
161
-
162
- ### F2. Filtros completos
163
- - Descricao: especie, confianca, status, localidade, data
164
- - Entregavel: filtros combinaveis
165
- - Criterio de aceite: filtro composto retorna lista correta
166
-
167
- ### F3. Recuperacao de sessao
168
- - Descricao: restaurar ultimo item e filtros
169
- - Entregavel: SessionState persistido por usuario/projeto
170
- - Criterio de aceite: recarregar pagina nao perde contexto principal
171
-
172
- ## Epic G - Observabilidade, qualidade e operacao (P1)
173
- ### G1. Logs estruturados
174
- - Descricao: correlacao por usuario/projeto/request
175
- - Entregavel: logger padrao JSON
176
- - Criterio de aceite: erro rastreavel de ponta a ponta
177
-
178
- ### G2. Metricas de performance
179
- - Descricao: p50/p95 fetch audio, taxa erro, throughput validacoes
180
- - Entregavel: painel simples em admin
181
- - Criterio de aceite: metrica atualiza em tempo quase real
182
-
183
- ### G3. Testes e hardening
184
- - Descricao: unit + integracao + testes de carga basica
185
- - Entregavel: suite minima automatizada
186
- - Criterio de aceite: pipeline CI verde em PR
187
-
188
- ## 6) Roadmap por sprint (2 semanas cada)
189
-
190
- ## Sprint 0 - Preparacao
191
- - A1, A2, A3
192
- - Saida: arquitetura base pronta + app inicia local
193
-
194
- ## Sprint 1 - Ingestao e indice
195
- - B1, B2, B3, B4
196
- - Saida: projeto pode ser publicado em dataset com indice valido
197
-
198
- ## Sprint 2 - Core de leitura e cache
199
- - C1, C2, C3
200
- - Saida: app navega deteccoes e toca audio sob demanda com limpeza local
201
-
202
- ## Sprint 3 - Persistencia colaborativa
203
- - D1, D2, D3
204
- - Saida: validacoes salvas com auditoria e sem perda por concorrencia
205
-
206
- ## Sprint 4 - Seguranca e multi-projeto
207
- - E1, E2, E3
208
- - Saida: login + ACL por projeto + admin operacional
209
-
210
- ## Sprint 5 - UX e performance
211
- - F1, F2, F3, C4
212
- - Saida: fluxo de validacao rapido e estavel para volume alto
213
-
214
- ## Sprint 6 - Operacao e qualidade
215
- - G1, G2, G3
216
- - Saida: observabilidade, testes e readiness de producao
217
-
218
- ## 7) Criticos de arquitetura (nao negociaveis)
219
- 1. Nao carregar dataset inteiro em memoria
220
- 2. Audio sempre sob demanda por item
221
- 3. Cleanup local obrigatorio apos validacao
222
- 4. detection_key imutavel
223
- 5. Isolamento forte por projeto e por usuario
224
-
225
- ## 8) Riscos e mitigacoes
226
- - Risco: contenção ao gravar validacoes no mesmo dataset
227
- - Mitigacao: append-only + snapshots + micro-batches
228
- - Risco: latencia de rede no fetch de audio
229
- - Mitigacao: cache efemero + prefetch curto + retries
230
- - Risco: crescimento de custo por requests
231
- - Mitigacao: politicas de cache e compressao de artefatos de indice
232
- - Risco: conflito entre validadores
233
- - Mitigacao: versao otimista + log de conflitos + merge deterministico
234
-
235
- ## 9) Entregaveis finais da v1
236
- 1. Repositorio do app no ar em HF Space
237
- 2. CLI funcional para publicar projetos no HF Dataset
238
- 3. Validacao multi-projeto com usuarios/papeis
239
- 4. Download individual de audio com limpeza local
240
- 5. Persistencia de validacoes com auditoria
241
- 6. Guia de operacao para onboarding de novos projetos
242
-
243
- ## 10) Proxima acao recomendada imediata
244
- Executar Sprint 0 e Sprint 1 antes de qualquer migracao de dados historicos.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
docs/BOOTSTRAP_COMMANDS_GITHUB_HF.md DELETED
@@ -1,77 +0,0 @@
1
- # Comandos Exatos - GitHub Repo + Hugging Face Space
2
-
3
- Este roteiro cria:
4
- 1) Repositorio do app no GitHub
5
- 2) Space Gradio no Hugging Face
6
- 3) Primeiro deploy do app
7
-
8
- ## Pre-requisitos
9
- - Git instalado
10
- - Conta GitHub autenticada no terminal (gh auth login)
11
- - Conta Hugging Face com token (write)
12
- - Python 3.11+
13
-
14
- ## A) Criar repositorio no GitHub e publicar codigo
15
- PowerShell (Windows):
16
-
17
- 1. Ir para a pasta do novo app
18
- cd "c:\Users\jonat\Documents\Python\BirdNET-validator-App"
19
-
20
- 2. Inicializar git local
21
- git init
22
- git add .
23
- git commit -m "chore: bootstrap sprint 0 for HF validator app"
24
-
25
- 3. Criar repo remoto e enviar
26
- gh repo create BirdNET-validator-App --public --source . --remote origin --push
27
-
28
- Observacao:
29
- - Se quiser privado, troque --public por --private.
30
-
31
- ## B) Criar Space Gradio no Hugging Face
32
- 1. Login no HF CLI
33
- huggingface-cli login
34
-
35
- 2. Criar Space
36
- huggingface-cli repo create BirdNET-validator-App --type space --space_sdk gradio --public
37
-
38
- Observacao:
39
- - Para privado, troque --public por --private.
40
-
41
- ## C) Conectar app ao Space e fazer deploy inicial
42
- 1. Adicionar remoto do Space
43
- git remote add hf https://huggingface.co/spaces/SEU_USUARIO/BirdNET-validator-App
44
-
45
- 2. Enviar codigo para o Space
46
- git push hf main
47
-
48
- Se sua branch principal local for master, use:
49
- git push hf master:main
50
-
51
- ## D) Configurar secrets no Space
52
- No painel do Space (Settings > Variables and secrets), adicionar:
53
- - HF_TOKEN (token com permissao write para datasets)
54
- - APP_AUTH_SECRET (segredo do app)
55
- - APP_ENV=prod
56
-
57
- ## E) Validar deploy
58
- 1. Abrir URL do Space:
59
- https://huggingface.co/spaces/SEU_USUARIO/BirdNET-validator-App
60
- 2. Verificar se a tela "BirdNET Validator HF" carregou.
61
-
62
- ## F) Primeiros comandos da CLI do projeto (quando implementar Sprint 1)
63
- A partir da raiz do app:
64
-
65
- 1. Criar projeto dataset
66
- python -m cli.hf_dataset_cli create-project --project-slug ppbio-rabeca --dataset-repo SEU_USUARIO/birdnet-ppbio-rabeca-dataset
67
-
68
- 2. Verificar projeto
69
- python -m cli.hf_dataset_cli verify-project
70
-
71
- ## G) Criar issue backlog no repo novo
72
- Use o arquivo da raiz do repo atual:
73
- - GITHUB_ISSUES_HF_VALIDATOR.md
74
-
75
- Sugestao:
76
- - Criar milestones Sprint 0..6
77
- - Abrir issues na ordem de dependencias do documento