From bdb373a1f2c91e605407e6e0a0113591f0dc7fe1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yann=20Le=C3=A3o?= Date: Thu, 23 Jul 2026 15:14:41 -0300 Subject: [PATCH] docs(governance): establish repository policies Refs #31 --- .github/CODEOWNERS | 1 + .github/pull_request_template.md | 22 ++++ CONTRIBUTING.md | 45 +++++++ LICENSE | 21 ++++ README.md | 200 +++++++++---------------------- SECURITY.md | 25 ++++ docs/GOVERNANCE.md | 48 ++++++++ pyproject.toml | 2 +- 8 files changed, 222 insertions(+), 142 deletions(-) create mode 100644 .github/CODEOWNERS create mode 100644 .github/pull_request_template.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 SECURITY.md create mode 100644 docs/GOVERNANCE.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..53156b6 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +* @YannLeao @MClaraFerreira5 @EllenRocha1 diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..7bce6fd --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,22 @@ +## Contexto + + + +Closes # + +## Alterações + +- + +## Validação + +- [ ] Testes relevantes executados localmente. +- [ ] Lint e checagem de tipos executados, quando aplicável. +- [ ] Documentação, configuração e variáveis de ambiente atualizadas, quando aplicável. +- [ ] Não foram incluídos segredos, dados de treinamento ou artefatos de modelo. + +## Impacto operacional + + + +Nenhum. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5c7975b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,45 @@ +# Contribuindo + +Este é um repositório acadêmico privado do projeto MedTrack. Somente integrantes +autorizados da organização podem criar branches e pull requests. + +## Fluxo de contribuição + +1. Crie uma branch a partir de `main` para uma issue ou card específico. +2. Faça mudanças pequenas, testáveis e com escopo explícito. +3. Use Conventional Commits e referencie a issue no corpo do commit, por exemplo + `Refs #123`. +4. Abra um pull request, descreva a motivação, os testes executados e impactos de + configuração ou deploy. +5. Aguarde os checks obrigatórios e a aprovação de outro integrante antes do merge. + +Não faça push direto em `main`, force push em branches protegidas, nem inclua +dados de treinamento, pesos de modelos, segredos ou arquivos `.env` no Git. + +## Revisão + +Os responsáveis técnicos atuais são: + +| Integrante | Papel | +| --- | --- | +| [@YannLeao](https://github.com/YannLeao) | Maintainer e responsável final por releases e merge. | +| [@MClaraFerreira5](https://github.com/MClaraFerreira5) | Integrante e revisora. | +| [@EllenRocha1](https://github.com/EllenRocha1) | Integrante e revisora. | + +Todo pull request requer pelo menos uma aprovação de um integrante diferente do +autor. Alterações em API, infraestrutura, segurança, modelo ou dados devem +explicar a compatibilidade e o plano de validação. + +## Convenções + +- Prefira `feat`, `fix`, `docs`, `test`, `build`, `ci` e `chore` como tipos de + commit. +- Mantenha documentação operacional em `docs/` e decisões relevantes como ADRs + em `docs/adr/`. +- Não altere o contrato HTTP sem atualizar `docs/contracts/api-v1.md` e alinhar + a mudança com os consumidores do ecossistema MedTrack. +- Execute os checks indicados em [docs/TESTING.md](docs/TESTING.md) antes de + solicitar revisão. + +Consulte [docs/GOVERNANCE.md](docs/GOVERNANCE.md) para as regras de integração e +responsabilidades do projeto. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..02449a8 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 MedTrack Project + +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. diff --git a/README.md b/README.md index 4cfcd15..c351a88 100644 --- a/README.md +++ b/README.md @@ -1,167 +1,85 @@ -# MedTrack AI 🧠💊 -### Motor de Visão Computacional e OCR +# MedTrack AI -O **MedTrack AI** é o motor de inteligência artificial do ecossistema MedTrack. O sistema utiliza um modelo híbrido que combina **YOLOv8** (detecção e localização dos campos na embalagem) e **EasyOCR** (extração textual inteligente), servindo dados estruturados em JSON para o aplicativo mobile em Kotlin via **FastAPI**. +Serviço de inferência de visão computacional do ecossistema acadêmico MedTrack. +Ele expõe uma API HTTP com FastAPI e organiza o ciclo de vida do modelo de +detecção e extração de texto, além das ferramentas de treinamento associadas. ---- +O projeto é um protótipo acadêmico. Suas previsões não substituem a conferência +humana ou a orientação de profissionais de saúde. -## 📦 Estrutura do Repositório +## Componentes -``` -MedTrack-IA/ -├── src/ -│ ├── api/ -│ │ ├── api.py # Servidor FastAPI com suporte a medicamentos genéricos -│ │ ├── ocr_extration.py # Módulo de processamento de crops e chamadas ao EasyOCR -│ │ ├── labeling.py # Ferramenta de anotação manual do dataset via OpenCV -│ │ └── augmentation.py # Pipeline de Data Augmentation -│ └── training/ -│ └── train.py # Script de fine-tuning do YOLOv8 -├── config/ -│ └── campos.yaml # Configuração das 6 classes do dataset -├── data/ # Imagens brutas (não versionadas no Git) -├── dataset/ # Dataset gerado pelo labeling (não versionado no Git) -├── requirements.txt -└── README.md -``` - ---- - -## 🎯 Classes Detectadas - -| ID | Classe | Descrição | -|----|--------|-----------| -| 0 | `nome` | Nome comercial do medicamento | -| 1 | `agente_ativo` | Princípio ativo | -| 2 | `dosagem` | Concentração/dosagem | -| 3 | `validade` | Data de validade | -| 4 | `quantidade` | Quantidade de unidades | -| 5 | `generico` | Tarja/logo de medicamento genérico | - ---- - -## 🛠️ Como Rodar Localmente - -### 1. Pré-requisitos - -- **Python 3.10 ou superior** -- Drivers NVIDIA + **CUDA Toolkit** (opcional, recomendado para GTX 1650+) - -### 2. Clonar e instalar dependências - -```bash -git clone https://github.com/MClaraFerreira5/MedTrack-IA.git -cd MedTrack-IA -pip install -r requirements.txt -``` +| Área | Responsabilidade | +| --- | --- | +| `src/medtrack_ai/api` | Aplicação FastAPI, contrato HTTP, health checks e observabilidade. | +| `src/medtrack_ai/inference` | Carregamento e execução do modelo de inferência. | +| `src/medtrack_ai/model_registry` | Leitura e validação do manifesto do artefato de modelo. | +| `src/training` | Ferramentas de treinamento e aumento de dados. | +| `config/training` | Configuração versionada do dataset e das classes de treinamento. | +| `tests` | Testes unitários, de integração e smoke tests opcionais do modelo. | -### 3. Baixar os pesos do modelo (`best.pt`) +Dados de treinamento, pesos e resultados de execução não são versionados. O +artefato de inferência é recuperado de um GitHub Release e validado por checksum. -Os pesos do modelo treinado **não são versionados no Git** por boas práticas. Para obtê-los: +## Início rápido -1. Acesse a aba **Releases** deste repositório -2. Baixe o arquivo `best.pt` da última versão estável -3. Coloque o arquivo no caminho: +O caminho recomendado para desenvolvimento da API é Docker Compose. São +necessários Docker Desktop, Python 3.11 e `uv` para recuperar o modelo local. -``` -src/training/runs/detect/medtrack_yolo_train/weights/best.pt +```powershell +Copy-Item .env.example .env +uv run --group dev python scripts/fetch_model.py +docker compose up --build ``` -### 4. Iniciar o servidor +Após a inicialização: -```bash -python src/api/api.py +```powershell +Invoke-WebRequest http://localhost:8000/healthz +Invoke-WebRequest http://localhost:8000/readyz ``` -A API estará disponível em: -- **Swagger UI:** [http://localhost:8000/docs](http://localhost:8000/docs) -- **Endpoint principal:** `POST http://localhost:8000/detect` - ---- - -## 📱 Integração com o App Mobile (Kotlin) +Para encerrar o ambiente: -O celular físico ou emulador não enxerga `localhost` diretamente. Use as configurações abaixo no seu cliente Retrofit: - -| Ambiente | URL Base | -|----------|----------| -| Emulador Android nativo | `http://10.0.2.2:8000` | -| Celular físico (Wi-Fi) | URL gerada pelo [Ngrok](https://ngrok.com) | - -**Para usar o Ngrok:** -```bash -ngrok http 8000 -# Use a URL gerada: https://xxxx.ngrok-free.app/detect +```powershell +docker compose down ``` ---- - -## 🔁 Pipeline de IA +Consulte o [guia de contêiner](docs/CONTAINER.md) para os pré-requisitos, +execução sem Compose e detalhes do modelo local. -``` -[Imagem do App Mobile] - │ - ▼ (resize para 640px) -[Imagem Otimizada] - │ - ▼ -┌─────────────────────────┐ -│ YOLOv8 Nano (GPU) │ ──► Detecta campos + tarja genérico -└─────────────────────────┘ - │ - ├──► [Tarja genérico detectada] ──► nome = "Medicamento Genérico" - │ - └──► [Crops dos outros campos] - │ - ▼ - ┌───────────────────────┐ - │ EasyOCR (GPU/CPU) │ ──► Extrai texto de cada campo - └───────────────────────┘ - │ - ▼ - JSON estruturado -``` +## Desenvolvimento e qualidade -**Exemplo de resposta:** -```json -{ - "status": "success", - "data": { - "nome": "Astro", - "agente_ativo": "Sinvastatina", - "dosagem": "500mg", - "validade": "10/2026", - "quantidade": "30 comprimidos", - "is_generico": false - } -} +```powershell +uv sync --group dev +uv run --group dev pytest +uv run --group dev ruff check src tests scripts +uv run --group dev pyright src/medtrack_ai tests scripts ``` -## 📊 Governança de Dados e Dataset (YOLOv8) - -Para cumprir os requisitos de reprodutibilidade científica e técnica do modelo, o dataset completo utilizado para o treinamento do `best.pt` foi estruturado e disponibilizado externamente (evitando inflar o tamanho do repositório Git). - -* 🔗 **Link de Acesso ao Dataset Estruturado (.zip):** [Link_do_Google_Drive](https://drive.google.com/file/d/1kFx1Vbpx1E5vtfPsAJBaApEtnxy1iSfs/view?usp=sharing) - -### 🧬 Estrutura do Arquivo Disponibilizado -O arquivo compactado segue rigorosamente a arquitetura de diretórios do ecossistema Ultralytics, emparelhando cada imagem ao seu respectivo arquivo de anotação bounding-box (`.txt`): -* `/train/images/` e `/train/labels/` (Conjunto de treino) -* `/val/images/` e `/val/labels/` (Conjunto de validação e métricas de acurácia) -* `campos.yaml` (Mapeamento de caminhos relativos e indexação das classes de fármacos) ---- - -## ⚠️ Aviso de Uso Responsável -O **MedTrack AI** é um protótipo assistivo desenvolvido para fins **acadêmicos**. O processamento visual e a extração de dados de embalagens são baseados em previsões probabilísticas. +A estratégia de testes e os comandos opcionais estão em +[docs/TESTING.md](docs/TESTING.md). Pull requests são validados pelos workflows +descritos em [docs/CI_CD.md](docs/CI_CD.md). -Este sistema **NÃO substitui**, em nenhuma hipótese: -- A conferência visual humana da receita médica e da embalagem física -- A orientação de profissionais de saúde qualificados (médicos, farmacêuticos, enfermeiros) +## Documentação -Qualquer utilização em cenários reais deve contar com **dupla checagem humana** para garantir a segurança na administração de medicamentos. +| Tema | Documento | +| --- | --- | +| Contrato HTTP | [docs/contracts/api-v1.md](docs/contracts/api-v1.md) | +| Artefato e versão do modelo | [docs/models/README.md](docs/models/README.md) | +| Contêiner local | [docs/CONTAINER.md](docs/CONTAINER.md) | +| CI/CD e versionamento | [docs/CI_CD.md](docs/CI_CD.md) | +| Deploy de staging | [docs/RAILWAY.md](docs/RAILWAY.md) | +| Decisões arquiteturais | [docs/adr/README.md](docs/adr/README.md) | +| Governança | [docs/GOVERNANCE.md](docs/GOVERNANCE.md) | ---- +## Contribuição e segurança +O repositório é restrito aos integrantes do projeto MedTrack. As regras de +contribuição, revisão e responsáveis estão em [CONTRIBUTING.md](CONTRIBUTING.md). +Relatos de vulnerabilidade devem seguir [SECURITY.md](SECURITY.md), e não ser +publicados em issues. -## 📄 Licença +## Licença -Projeto acadêmico — Engenharia da Computação · 2026 +O código está licenciado sob a [MIT License](LICENSE). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..5feac1d --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,25 @@ +# Política de segurança + +## Versões suportadas + +O projeto oferece correções de segurança apenas para a versão em desenvolvimento +na branch `main`. Por ser um protótipo acadêmico, não há garantia de suporte para +versões históricas ou disponibilidade clínica. + +## Relato responsável + +Não abra uma issue pública para relatar uma vulnerabilidade. Envie uma mensagem +para [yann.kjleao@ufrpe.br](mailto:yann.kjleao@ufrpe.br) com: + +- descrição e impacto potencial; +- passos mínimos para reproduzir; +- versão, commit ou ambiente afetado; +- sugestão de mitigação, se houver. + +O mantenedor confirmará o recebimento em até cinco dias úteis e combinará a +divulgação e a correção com o relator. Não envie imagens de prescrições, dados +pessoais, credenciais, tokens ou outros dados sensíveis no relato. + +Falhas de qualidade do modelo ou divergências de OCR não são, por si só, +vulnerabilidades de segurança. Elas devem ser registradas no canal interno do +projeto, sem anexar dados sensíveis. diff --git a/docs/GOVERNANCE.md b/docs/GOVERNANCE.md new file mode 100644 index 0000000..d9ef2ac --- /dev/null +++ b/docs/GOVERNANCE.md @@ -0,0 +1,48 @@ +# Governança do repositório + +## Escopo e acesso + +O MedTrack AI é um projeto acadêmico mantido pela organização MedTrack Project. +O repositório é fechado a contribuições externas; mudanças são realizadas pelos +integrantes autorizados e integradas por pull request. + +| Responsável | Atribuição | +| --- | --- | +| [@YannLeao](https://github.com/YannLeao) | Maintainer, aprovação final, releases e operação. | +| [@MClaraFerreira5](https://github.com/MClaraFerreira5) | Desenvolvimento e revisão. | +| [@EllenRocha1](https://github.com/EllenRocha1) | Desenvolvimento e revisão. | + +## Integração em `main` + +A branch `main` é protegida por rulesets. O fluxo obrigatório é branch de +trabalho, pull request, checks automatizados e revisão por outra pessoa. + +Configuração esperada no GitHub: + +- bloquear exclusão e force push; +- exigir pull request e resolução de conversas; +- exigir branches atualizadas e status checks aprovados; +- exigir ao menos uma aprovação; +- exigir revisão de CODEOWNERS, quando os três integrantes tiverem acesso de + escrita confirmado. + +`CODEOWNERS` define os três integrantes como responsáveis pelo repositório. O +arquivo apenas aponta responsáveis; a exigência efetiva de aprovação depende dos +dois últimos controles no ruleset do GitHub. + +## Decisões e mudanças + +Mudanças que afetem contratos, modelo, segurança, dados ou operação devem ter +issue/card associado, validação explícita e, quando envolverem uma decisão +duradoura, uma ADR em `docs/adr/`. + +Os commits seguem Conventional Commits e mencionam a issue relacionada no corpo, +por exemplo `Refs #123`. As instruções práticas estão em +[CONTRIBUTING.md](../CONTRIBUTING.md). + +## Segurança e dados + +Vulnerabilidades seguem [SECURITY.md](../SECURITY.md). Dados de treinamento, +pesos de modelos, segredos e arquivos de ambiente não pertencem ao Git; suas +regras de armazenamento e recuperação são documentadas nos guias de modelo e +de operação. diff --git a/pyproject.toml b/pyproject.toml index 7498410..9ed0aff 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -8,7 +8,7 @@ version = "0.1.0" description = "Serviço de inferência e ferramentas de treinamento do MedTrack." readme = "README.md" requires-python = ">=3.11,<3.12" -license = { text = "UNLICENSED" } +license = { text = "MIT" } authors = [{ name = "MedTrack" }] dependencies = [ "fastapi==0.110.0",