Adds docs
This commit is contained in:
115
docs/visao-geral.md
Normal file
115
docs/visao-geral.md
Normal file
@@ -0,0 +1,115 @@
|
||||
# Doc-Processor — Visão Geral do Sistema
|
||||
|
||||
## O que é
|
||||
|
||||
O **Doc-Processor** é um serviço de análise automatizada de guias de autorização médica. Ele recebe solicitações de procedimentos médicos (guias), extrai o texto dos documentos anexados via OCR, e utiliza um agente de inteligência artificial (LLM) para decidir se cada serviço solicitado deve ser **Aprovado** ou **Reprovado**, com base em regras de negócio configuradas para cada código de procedimento.
|
||||
|
||||
O sistema foi desenvolvido para operar no contexto de operadoras de saúde (ex: Unimed), reduzindo o trabalho manual dos auditores médicos.
|
||||
|
||||
---
|
||||
|
||||
## Fluxo de Processamento
|
||||
|
||||
```
|
||||
POST /process
|
||||
│
|
||||
├─► Para cada guia (em paralelo):
|
||||
│ │
|
||||
│ ├─► Para cada anexo (em paralelo):
|
||||
│ │ ├─► Baixa o arquivo do S3
|
||||
│ │ ├─► OCR via AWS Textract
|
||||
│ │ └─► Armazena texto extraído na guia
|
||||
│ │
|
||||
│ └─► Para cada serviço (em paralelo):
|
||||
│ ├─► Verifica se o código existe nas regras
|
||||
│ ├─► Monta o payload JSON (atendimento + guia + serviço + histórico)
|
||||
│ ├─► Chama o agente LangGraph com o texto dos documentos
|
||||
│ └─► Retorna Aprovado / Reprovado / SKIPPED
|
||||
│
|
||||
├─► Salva todos os resultados no S3 (bucket de saída)
|
||||
└─► Retorna resposta HTTP com as avaliações
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Decisão do Agente
|
||||
|
||||
O agente segue a seguinte lógica de decisão para cada serviço:
|
||||
|
||||
1. **Critérios de auto-aprovação** (`rules.yaml › rules`): Se qualquer um desses critérios estiver presente na guia ou nos documentos, o procedimento é aprovado imediatamente.
|
||||
2. **Documentação mínima** (`rules.yaml › min_doc`): Se nenhum critério de auto-aprovação for atendido, o agente verifica se a documentação mínima exigida está presente. Se estiver (mesmo que em tipo diferente de documento), o procedimento é aprovado.
|
||||
3. **Reprovação**: Se nem os critérios de auto-aprovação nem a documentação mínima estiverem presentes, o procedimento é reprovado.
|
||||
|
||||
O agente também verifica, em cada documento, se o nome do beneficiário da guia está presente.
|
||||
|
||||
---
|
||||
|
||||
## Tecnologias Utilizadas
|
||||
|
||||
| Tecnologia | Função |
|
||||
|-------------------|-----------------------------------------------------|
|
||||
| FastAPI | Framework web / API REST |
|
||||
| LangGraph | Orquestração do agente de IA (fluxo ReAct) |
|
||||
| LangChain AWS | Integração com AWS Bedrock (LLM Claude/Anthropic) |
|
||||
| AWS Bedrock | Modelo de linguagem (LLM) para decisão |
|
||||
| AWS Textract | OCR de PDFs e imagens |
|
||||
| AWS S3 | Armazenamento de documentos de entrada e resultados |
|
||||
| AWS Secrets Manager | Gerenciamento seguro de credenciais |
|
||||
| Langfuse | Observabilidade e rastreamento de chamadas ao LLM |
|
||||
| PyPDF2 | Separação de páginas de PDFs para OCR por página |
|
||||
| Pydantic | Validação do corpo da requisição |
|
||||
| Docker | Containerização do serviço |
|
||||
|
||||
---
|
||||
|
||||
## Estrutura de Diretórios
|
||||
|
||||
```
|
||||
code/
|
||||
├── app.py # Ponto de entrada da API FastAPI
|
||||
├── dockerfile # Imagem Docker da aplicação
|
||||
├── Makefile # Automação de build e deploy
|
||||
├── requirements.txt # Dependências Python
|
||||
│
|
||||
├── services/
|
||||
│ ├── authorization.py # Avalia cada serviço via agente de IA
|
||||
│ ├── document_extractor.py # Extrai texto de documentos no S3 via Textract
|
||||
│ └── result_store.py # Persiste resultados no S3
|
||||
│
|
||||
├── utils/
|
||||
│ ├── config.py # Variáveis de ambiente / configurações
|
||||
│ ├── langgraph_agent.py # Definição e execução do agente LangGraph
|
||||
│ ├── rules.yaml # Regras de autorização por código de procedimento
|
||||
│ └── secrets_manager.py # Carrega segredos do AWS Secrets Manager
|
||||
│
|
||||
└── document/ # Documentação do sistema (esta pasta)
|
||||
├── visao-geral.md
|
||||
├── modulos.md
|
||||
└── api.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuração
|
||||
|
||||
### Variáveis de Ambiente
|
||||
|
||||
| Variável | Obrigatória | Padrão | Descrição |
|
||||
|----------------------|-------------|-------------------------------|----------------------------------------------|
|
||||
| `AWS_REGION` | Não | `us-east-2` | Região AWS usada para todos os serviços |
|
||||
| `BEDROCK_MODEL_ARN` | **Sim** | — | ARN do modelo Claude no AWS Bedrock |
|
||||
| `OUTPUT_BUCKET` | Não | `upflux-doc-analyzer` | Bucket S3 onde os resultados são salvos |
|
||||
| `API_VERSION` | Não | `v1` | Prefixo de versão usado na chave do S3 |
|
||||
| `LANGFUSE_HOST` | Não | `https://cloud.langfuse.com` | Host do servidor Langfuse (observabilidade) |
|
||||
|
||||
### Segredos (AWS Secrets Manager — Secret ID: `doc-analyzer`)
|
||||
|
||||
| Chave | Descrição |
|
||||
|------------------------|----------------------------------------------------|
|
||||
| `API-KEY` | Chave de autenticação da API (`X-API-Key`) |
|
||||
| `AWS_ACCESS_KEY` | Access Key para acesso ao S3 de entrada |
|
||||
| `AWS_SECRET_KEY` | Secret Key para acesso ao S3 de entrada |
|
||||
| `LANGFUSE-SECRET-KEY` | Chave secreta do Langfuse |
|
||||
| `LANGFUSE-PUBLIC-KEY` | Chave pública do Langfuse |
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user