🚀 EntityMiner

Um projeto de exemplo para demonstração de extração de entidades nomeadas usando GLiNER2, implementado com Clean Architecture e Domain-Driven Design.

🌟 Visão Geral

Este projeto serve como exemplo prático de como integrar o GLiNER2 para reconhecimento de entidades nomeadas (NER). Ele demonstra princípios de Clean Architecture e DDD em um contexto simples, focando na extração de entidades de texto.

🏗️ Arquitetura

O projeto segue Clean Architecture com as seguintes camadas:

• 🏛️ Domínio: Lógica de negócio central e entidades
• ⚙️ Aplicação: Casos de uso e serviços de aplicação
• 🔌 Infraestrutura: Dependências externas e adaptadores
• 💻 Apresentação: Interfaces de usuário (CLI)

Funcionalidades

• Reconhecimento de entidades nomeadas (NER)
• Processamento em lote
• Thresholds de confiança configuráveis
• Estrutura de código limpa e testável
• Interface de linha de comando (CLI)
• Testes unitários
• Configuração via dataclasses
• Adaptador para GLiNER2

🔧 Serviços Implementados

EntityValidationService (Domain Service)

• Validação de entidades baseada em regras de negócio
• Estatísticas de validação
• Filtragem por confiança

LoggingService (Application Service)

• Logging estruturado de operações
• Métricas de performance
• Logs de configuração

CacheRepository (Infrastructure Repository)

• Cache em memória com TTL
• Melhoria de performance
• Interface abstrata para extensibilidade

📦 Instalação

Pré-requisitos

• Python 3.12+
• uv (gerenciador de pacotes recomendado)

Passos de Instalação

1. Clone o repositório:

git clone <url-do-repositorio>
cd EntityMiner

2. Instale as dependências:

uv sync

3. (Opcional) Configure variáveis de ambiente:

cp .env.example .env
# Edite .env conforme necessário

⚙️ Configuração

O projeto usa pydantic-settings para gerenciar configurações via variáveis de ambiente. Copie o arquivo .env.example para .env e ajuste os valores conforme necessário:

# Modelo GLiNER2 a usar
GLINER2_MODEL_PATH=fastino/gliner2-base-v1

# Threshold padrão de confiança (0.0 a 1.0)
GLINER2_DEFAULT_THRESHOLD=0.5

# Tamanho do lote para processamento
GLINER2_BATCH_SIZE=8

As configurações são automaticamente carregadas e usadas pela aplicação.

🎯 Uso

Linha de Comando

# Uso básico - Simples e direto!
uv run gliner2-adapter "Apple CEO Tim Cook anunciou o iPhone 17."

# Com tipos de entidades específicos - Personalize ao máximo!
uv run gliner2-adapter "Microsoft CEO Satya Nadella apresentou Copilot AI na Build 2025." --entities person organization product location

# Com threshold personalizado - Controle a precisão!
uv run gliner2-adapter "Texto aqui" --threshold 0.7

Makefile

# Instalar dependências
make install

# Executar aplicação interativamente (solicita texto via input)
make run

# Executar script de exemplo
make script

# Executar testes
make test

API Python

from src.application.use_cases.extract_entities import ExtractEntitiesUseCase
from src.infrastructure.adapters.gliner2_adapter import GLiNER2Adapter
from src.domain.entities.entities import Text
from src.domain.value_objects.value_objects import EntityTypes, Threshold

adapter = GLiNER2Adapter()
use_case = ExtractEntitiesUseCase(adapter)

text = Text("Apple CEO Tim Cook anunciou o iPhone 15 em Cupertino.")
entity_types = EntityTypes(["person", "organization", "product", "location"])
threshold = Threshold(0.5)

result = use_case.execute(text, entity_types, threshold)
print(result.entities)

# Processamento em lote - Eficiência para todos!
texts = [Text("Texto 1"), Text("Texto 2")]
batch_use_case = BatchExtractEntitiesUseCase(adapter)
results = batch_use_case.execute(texts, entity_types, threshold)

Estrutura do Projeto

📁 src/
├── 🏛️ domain/
│   ├── 📄 entities/          # Entidades de domínio (Text, Entity, ExtractionResult) - Os blocos de construção
│   ├── 🔢 value_objects/     # Objetos de valor (Threshold, EntityTypes) - Valores imutáveis
│   ├── 🔌 repositories/      # Interfaces de repositório - Abstração
│   └── ⚙️ services/          # Serviços de domínio - Lógica central
├── 🚀 application/
│   ├── 🎯 use_cases/         # Casos de uso (ExtractEntitiesUseCase) - Ações concretas
│   └── 🔧 services/          # Serviços de aplicação - Suporte essencial
├── 🌐 infrastructure/
│   ├── 🔌 adapters/          # Adaptadores externos (GLiNER2Adapter) - Conectores externos
│   └── 💾 repositories/      # Implementações de repositório - Realidade prática
├── 💻 presentation/
│   └── 🖥️ cli/               # Interface de linha de comando - CLI
└── ⚙️ config/                # Configurações
🧪 tests/
├── ✅ unit/                  # Testes unitários

🛠️ Desenvolvimento

Configuração do Ambiente

uv sync

Testes

uv run pytest

Linting

uv run ruff check .
uv run ruff format .

⚡ Exemplo Rápido

Execute o arquivo example.py para ver um exemplo básico:

uv run python scripts/example.py

� Referências

Explore mais sobre o GLiNER2! 📚

• 📄 Paper do GLiNER2: GLiNER-2.0: Multilingual Document-Level Relation Extraction with Large Language Models - Descubra a pesquisa por trás da tecnologia!
• 🐙 Repositório Oficial: GLiNER2 no GitHub - Código fonte e documentação completa!