ScoutEngine

Agente baseado em regras para avaliar características de jogadores de futebol, para assim sugerir posições e funções em campo.

Projeto realizado no período 2026.1 para a cadeira de "Sistemas Baseados em Conhecimento" da Universidade Federal da Paraíba.

Visao geral

O ScoutEngine recebe um conjunto de atributos numéricos (0 a 10) de um jogador, discretiza esses valores em níveis qualitativos (baixo, médio, alto) e aplica regras IF-THEN para gerar possíveis posições. O motor de inferência é feito a partir da biblioteca experta, utilizando de princípios do paradigma de Programação Orientada à Objetos para desenvolver o sistema de forma modularizada e visualizável.

Tecnologias utilizadas

Linguagem: Python 3.11
Biblioteca Principal: `experta`
Dependência Crítica Corrigida: `frozendict==2.4.4`

Estrutura do repositório

ScoutEngine/
├── data/
│   └── jogadores_exemplo.json   # dados de teste
├── requirements.txt             # dependências para instalação
├── src/
│   ├── main.ipynb
│   └── objs/
│       ├── __init__.py
│       ├── Jogador.py           # modelo do jogador e discretização
│       └── ScoutEngine.py       # regras e motor de inferência
├── LICENSE
└── README.md

Como executar (main.ipynb)

1. Crie e ative uma venv:

python -m venv .venv
source .venv/bin/activate

2. Instale as dependencias:

pip install -r requirements.txt

3. Abra o notebook src/main.ipynb no VS Code, selecione o kernel da venv e execute as células em ordem. O notebook lê o arquivo ../data/jogadores_exemplo.json a partir da pasta src.

Arquitetura do Agente

A construção do sistema foi baseado na obtenção e discretização dos atributos do jogador de futebol, para aplicar esses fatos obtidos no motor de inferência, afim de coletar relações entre as características e designar as melhores posições de um jogador.

Atributos de entrada

• Velocidade, Chute, Cabeceio, Passe, Cruzamento
• Robustez Física, Posicionamento, Fôlego
• Preferência (defesa, meio, ataque)

Niveis qualitativos

• Alto: valor $\geq 7$
• Medio: valor $\geq 4$ e $< 7$
• Baixo: valor $< 4$

Estratégia de Resolução de Conflitos (Salience)

As regras são organizadas por camadas de prioridade, com salience maior executando primeiro:

1. Discretização das características (salience = 10)

2. Criação de skills a partir das características (salience = 5)

3. Designação das posições (salience = 0)

4. Regra de exclusão (salience = -10)

Regras Principais do Agente

1. Se a preferencia for defesa, tiver otimo fisico e cabeceio medio/alto, entao Zagueiro - Fixo.

2. Se a preferencia for defesa, posicionamento medio/alto e velocidade medio/alto, entao Zagueiro - Cacador.

3. Se a preferencia for defesa ou meio, for bom passador e posicionamento medio/alto, entao Volante - Armador.

4. Se a preferencia for defesa ou meio, tiver otimo fisico e posicionamento medio/alto, entao Volante - Marcador.

5. Se a preferencia for meio, chute medio/alto e posicionamento medio/alto, entao Meia - Atacante.

6. Se a preferencia for meio, for bom passador e folego medio/alto, entao Meia - Armador.

7. Se a preferencia for meio, for velocista e cruzamento medio/alto, entao Meia - Pelas laterais.

8. Se a preferencia for ataque, robustez medio/alto e for bom finalizador, entao Atacante - Centro de area.

9. Se a preferencia for ataque, for velocista e cruzamento medio/alto, entao Atacante - Ponta.

10. Se a preferencia for ataque, chute medio/alto e posicionamento medio/alto, entao Atacante - Segundo Atacante.

Casos de teste (3 exemplos)

Os dados abaixo estao no arquivo data/jogadores_exemplo.json.

Caso 1: Neymar (preferencia meio)

• Entradas:

  • Velocidade: 9
  • Chute: 8
  • Cabeceio: 3
  • Passe: 6
  • Cruzamento: 5
  • Robustez: 3
  • Posicionamento: 6
  • Fôlego: 8

• Saida esperada:

  • Meia - Atacante
  • Meia - Pelas laterais

Caso 2: Rony (preferencia ataque)

• Entradas:

  • Velocidade: 10
  • Chute: 6
  • Cabeceio: 4
  • Passe: 5
  • Cruzamento: 5
  • Robustez: 5
  • Posicionamento: 4
  • Fôlego: 10

• Saida esperada:

  • Atacante - Ponta
  • Atacante - Segundo Atacante

Caso 3: Gustavo Gomez (preferencia defesa)

• Entradas:

  • Velocidade: 5
  • Chute: 4
  • Cabeceio: 8
  • Passe: 3
  • Cruzamento: 3
  • Robustez: 8
  • Posicionamento: 6
  • Fôlego: 5

• Saida esperada:

  • Zagueiro - Fixo
  • Zagueiro - Cacador
  • Volante - Marcador