v0.12.0 — Match Engine 2.0¶

Status¶

Implementado em 2026-06-21.

A v0.12.0 adiciona uma engine determinística para comparar currículo, vaga e evidências profissionais sem depender apenas de keyword matching. A IA continua opcional e consultiva: ela pode classificar, interpretar e explicar, mas o score final é calculado pelo código.

Problema resolvido¶

O matching simples por palavras falha quando:

a vaga é de área não técnica;
o requisito é registro profissional;
a vaga mistura obrigatório, desejável e opcional;
a competência é transferível, mas não direta;
o currículo tem evidências em GitHub, portfolio, memória ou perfil;
a senioridade, domínio ou formação mudam o risco da candidatura;
o requisito é norma, software, equipamento, ambiente ou credencial.

Módulos implementados¶

modules/matching/
  __init__.py
  models.py
  exceptions.py
  requirement_matcher.py
  evidence_matcher.py
  transferable_skills.py
  score_calculator.py
  risk_adjustment.py
  confidence.py
  explanation_builder.py
  engine.py

Fluxo¶

ResumeExtractionOutput
+ JobExtractionOutput
+ GitHubAnalyzerReport opcional
+ ProjectAnalysisReport opcional
+ memory/profile opcional
-> requirements_from_job_extraction
-> collect_resume/github/portfolio/text_evidence
-> match_requirements
-> find_transferable_skills
-> build_critical_gaps
-> calculate_match_scores
-> build_match_explanation
-> MatchResultV2

O analyzer antigo permanece disponível. O novo caminho analyze_job_v2 usa Match Engine 2.0 e cai para analyze_job se a engine falhar.

Modelos principais¶

MatchRequirement;
CandidateEvidence;
RequirementMatch;
CriticalGap;
TransferableSkillMatch;
MatchScoreBreakdown;
MatchExplanation;
MatchResultV2;
ProfessionalRegistrationInput.

Categorias e status¶

Categorias aceitas pela engine:

education
hard_skill
soft_skill
tool
software
equipment
certification
professional_license
professional_registration
language
experience
methodology
regulation
responsibility
availability
location
portfolio
domain_knowledge
other

Status de requisito:

matched
partial
missing
unclear
not_applicable

Competências transferíveis são explicadas em lista própria e não viram match direto.

Score calculado por código¶

Pesos da v0.12.0:

Dimensão	Peso
Requisitos obrigatórios	30%
Requisitos desejáveis	15%
Aderência de domínio	10%
Senioridade	10%
Formação, certificações e registros	10%
Força das evidências	10%
Evidências GitHub/portfolio	5%
ATS keyword alignment	5%
Preferências/logística	5%

Depois do cálculo base, risk_adjustment aplica penalidade. Um gap knockout real limita o score, e registro profissional obrigatório ausente limita ainda mais.

Scores emitidos:

match_score;
ats_alignment_score;
opportunity_fit_score;
evidence_score;
risk_score;
confidence_score;
overall_score.

Registros profissionais¶

O catálogo inicial classifica:

CRM, CRO, CRF, COREN, CREFITO, CRN, CRMV, CRP, CREF e CRTR;
CREA, CAU, CFT, CRT e CRQ;
OAB, CRC, CRA, CORECON, CRB, CRESS, CONRERP e CRECI;
CRBio;
MTE/DRT como professional_registration.

Regras:

registro obrigatório vira criticality = knockout;
registro desejável vira criticality = medium;
registro obrigatório ausente vira gap knockout;
a engine não sugere inventar credencial;
a opção Outro conselho / Outro registro profissional é aceita para cadastro ou revisão manual.

Exemplo de safe action:

A vaga exige CREA. Como o currículo não mostra esse registro, isso deve ser tratado como gap
crítico. Se você possui CREA ativo, destaque no currículo; caso contrário, a vaga pode não ser
compatível.

Evidências¶

Fontes aceitas:

resume;
github;
portfolio;
memory;
profile;
manual;
none.

Força da evidência:

weak;
medium;
strong;
verified;
unclear.

GitHub Analyzer 2.0 contribui quando disponível, especialmente para stacks, frameworks, arquivos amostrados, skills demonstradas e evidence score.

Competências transferíveis¶

A v0.12.0 inclui regras iniciais para:

professor;
enfermagem;
psicologia;
engenharia civil;
arquitetura;
manutenção;
cybersecurity.

Transferível ajuda a explicar compatibilidade parcial, mas não compensa registro profissional, diploma obrigatório ou experiência direta quando a vaga exige explicitamente.

Explicação¶

MatchExplanation inclui:

resumo do match;
motivos do score;
requisitos atendidos;
requisitos parcialmente atendidos;
requisitos ausentes;
gaps críticos;
competências transferíveis;
evidências usadas;
safe actions;
melhorias de currículo;
melhorias de GitHub/portfolio.

Testes e fixtures¶

Criados:

tests/test_match_engine_v2.py;
tests/test_requirement_matcher.py;
tests/test_evidence_matcher.py;
tests/test_transferable_skills.py;
tests/test_match_score_calculator.py;
tests/test_match_explanation_builder.py;
tests/test_match_confidence.py;
tests/test_match_risk_adjustment.py;
tests/fixtures/matching/*.

As fixtures cobrem backend, enfermagem, pedagogia, psicologia, engenharia civil, arquitetura, cybersecurity e evidências GitHub/portfolio.

Limites conhecidos¶

A integração profunda com ATS e Resume Tailor ficou preparada por contratos e prompts, mas pode evoluir em versões posteriores.
Pesos por domínio foram adicionados na v1.0.0 como configuração simples em modules/matching/domain_weights.py.
A UI ainda pode exibir o resultado v2 de forma mais rica em versão futura.
A lista de registros profissionais é catálogo inicial, não validação jurídica definitiva.

Critério de pronto¶

A v0.12.0 foi considerada pronta porque:

o score não depende apenas de keywords;
requisitos são normalizados e classificados;
gaps críticos travam score quando necessário;
registros profissionais sensíveis são tratados com linguagem segura;
competências transferíveis aparecem separadas de match direto;
evidências de currículo, GitHub, portfolio, memória e perfil entram no cálculo;
confidence é separado de score;
exemplos multiárea têm cobertura automatizada;
o matching antigo permanece como fallback.