SotuHire é um assistente de carreira local-first, multiárea e orientado por evidências. Ele reúne currículo, trajetória acadêmica, portfólio, preferências, oportunidades, editais e histórico de candidaturas para ajudar a pessoa usuária a entender o próprio perfil e tomar decisões melhores sem entregar o controle a uma automação opaca.
O produto funciona como uma camada de continuidade entre o Perfil Profissional Universal, o Career Context, as análises de currículo e vaga, o Radar, o Tracker, o Lattes, os editais e a extensão do navegador. Dados confirmados mantêm origem e referência; itens incertos continuam como candidatos revisáveis. A IA é opcional: Gemini e OpenAI podem enriquecer análises, enquanto o caminho local permanece disponível como base e fallback explícito.
A abordagem é local-first: banco, stores legados, snapshots e backups ficam no computador da pessoa usuária. Nenhuma candidatura, inscrição, pagamento ou envio de documento é realizado automaticamente. O SotuHire também não é apenas um “analisador de currículo”: ele preserva o que foi analisado, conecta evidências ao histórico e permite acompanhar como perfil, oportunidades e resultados evoluem.
O SotuHire foi pensado para trajetórias profissionais diversas, inclusive quando GitHub não faz parte da área:
- estudantes, estagiários, técnicos, tecnólogos e pessoas sem experiência formal;
- engenharias, indústria, manutenção, laboratório, qualidade e operações;
- saúde, direito e outras profissões com registros ou conselhos profissionais;
- educação, pesquisa, iniciação científica, pós-graduação, docência e Currículo Lattes;
- artes, design, arquitetura, comunicação, portfólio e produção cultural;
- administração, finanças, atendimento, comercial, turismo e serviços;
- transição de carreira, retorno ao mercado e mudança de área;
- concursos, processos seletivos públicos, residências, bolsas e outros editais.
Centraliza objetivos, formação, experiências, projetos, competências, idiomas, registros, preferências e restrições. Evidências vindas de currículo, Lattes, GitHub, extensão ou IA entram como candidatos e só se tornam fatos confirmados após revisão humana.
Extrai e organiza currículos TXT, PDF e DOCX, mantém uma base reutilizável e prepara a fundação para variantes por vaga. A interoperabilidade com JSON Resume permite exportar fatos confirmados e importar dados como candidatos revisáveis.
- Vaga: estrutura cargo, organização, localidade, requisitos, palavras-chave e riscos.
- Match: compara requisitos e evidências sem converter ausência de informação em experiência inventada.
- ATS: separa termos presentes, sustentados por evidência e ausentes.
- Tailor: sugere uma variante de currículo usando somente conteúdo que pode ser comprovado.
Interpreta texto do Currículo Lattes e de trajetórias acadêmicas para identificar formação, pesquisa, publicações, docência, extensão, bolsas, eventos e produção técnica ou artística. O fluxo não faz login nem scraping autenticado do Lattes.
Organiza órgão, banca, cargos, requisitos, etapas, documentos, datas, taxa e conteúdo programático. O Exam Fit compara requisitos com evidências confirmadas e pode gerar checklist e plano inicial de estudo. O edital oficial sempre prevalece.
Permite descrever oportunidades desejadas, consultar fontes públicas configuradas, executar buscas revisáveis e agendar ciclos locais com quiet hours, cooldown e notificações. Não há inscrição nem candidatura automática.
Mantém candidaturas em modo rápido — cargo, organização, URL e status — ou completo, com snapshots, análises, contatos, entrevistas, follow-up e resultado. O histórico preserva a vaga e o currículo realmente usados quando esses conteúdos estão disponíveis.
Analisa perfis e repositórios públicos, incluindo README, linguagens, estrutura, commits, atividade, práticas de engenharia e apresentação do projeto. As conclusões viram sugestões de evidência, não fatos salvos automaticamente.
Recebe texto, links, CSV, JSON, feeds públicos e capturas assistidas. A identidade canônica reduz duplicatas entre URL manual, Radar, extensão e portais diferentes, preservando as referências de origem.
Captura vaga, edital, projeto GitHub e lotes visíveis; analisa repositórios dentro do GitHub; mantém fila offline com retry e export/import; e conversa com o Local Companion ou com a API local. Pode operar sem o frontend aberto e possui modo próprio de IA opcional.
Gemini, OpenAI e o caminho local usam contratos estruturados. Execuções importantes registram provider e modelo solicitado/usado, prompt, fallback, evidências, avisos e necessidade de revisão — nunca a chave. A memória/RAG local recupera somente o contexto relevante para cada finalidade.
Vagas, currículos, variantes, editais e análises podem gerar snapshots imutáveis. O painel de Privacidade executa data health, cria backup ou export portátil, valida arquivos por checksum e só restaura após confirmação explícita.
Perfil + evidências revisadas
↓
Career Context
↓
Match · ATS · Tailor · Radar · Editais · GitHub
↓
Tracker + snapshots + histórico
↓
feedback humano e atualização do Perfil
Cada fluxo recebe apenas o contexto necessário. Evidências sensíveis são omitidas de providers externos por padrão, e conteúdo não confirmado não deve ser apresentado como fato seguro.
| Perfil Profissional Universal | Match |
|---|---|
 |
 |
| Radar | Tracker |
|---|---|
 |
 |
| Lattes e Acadêmico | Editais e Concursos |
|---|---|
 |
 |
| Configuração de IA | Dados e privacidade |
|---|---|
 |
 |
| Popup da extensão | Análise dentro do GitHub |
|---|---|
 |
 |
Mais telas: galeria e roteiro de demonstração.
| Modo | O que executa | Persistência |
|---|---|---|
| Demo | Frontend com personas e respostas coerentes, sem exigir backend | Estado da sessão do navegador |
| API Real | React conectado à FastAPI local | SQLite e stores locais |
| Site sem extensão | Todos os fluxos web, inclusive captura manual e fontes públicas | Local |
| Extensão independente | Captura e análise própria; Companion pode receber dados sem React aberto | Service worker, fila e stores locais |
| Extensão integrada | Handshake, contexto seguro, importação para Perfil, Vaga, Edital, GitHub e Tracker | Local Companion + API local |
Requisitos:
- Python 3.11 ou 3.12;
- Node.js 22 e npm para o frontend;
- Git;
- Chrome, Edge ou outro navegador Chromium para a extensão;
- chave Gemini ou OpenAI somente se desejar IA externa.
Clone e crie o ambiente:
git clone https://github.com/Soturine/SotuHire.git
cd SotuHire
python -m venv .venv.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -e .[dev]
cd apps/web
npm ci
cd ../..source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e ".[dev]"
cd apps/web
npm ci
cd ../..Use terminais separados para API e frontend.
API local:
python scripts/run_api.pyFrontend:
cd apps/web
npm run devAbra http://127.0.0.1:5173. O seletor no app alterna entre Demo e API Real; a API usa http://127.0.0.1:8787/api/v1 por padrão.
Local Companion para a extensão:
python -m modules.local_api.serverDocumentação local:
mkdocs serveValidação principal:
ruff check .
ruff format --check .
pytest
pyright
mkdocs build --strict
cd apps/web
npm run lint
npm run typecheck
npm run build
npm run test:e2eO SotuHire continua utilizável sem chave externa. Para habilitar IA:
- abra Configurações → IA;
- escolha Gemini, OpenAI ou Local;
- use o link do próprio app para abrir a página oficial do provider;
- cole a chave no backend local;
- atualize o catálogo, escolha o modelo e execute Testar conexão;
- selecione um preset ou habilite apenas os fluxos desejados.
Os catálogos de modelo são consultados de verdade, possuem cache e podem ser atualizados; o modelo escolhido é enviado ao provider. Se o provider falhar, a resposta informa provider/modelo efetivamente usados e o motivo do fallback.
No site, a chave é armazenada somente no backend local e não é devolvida ao React. Ela não deve ir para Git, documentação, screenshot, log, localStorage, sessionStorage, backup ou export. Testes externos são opt-in; a suíte padrão usa mocks.
O painel IA e Qualidade mede execuções por tarefa, provider, modelo e versão do prompt. Ele combina validação de schema, golden datasets multiárea, evidência, claims sem suporte, fallback, latência, tokens, custo disponível e feedback humano. Comparações sempre exibem o tamanho da amostra e não declaram um vencedor definitivo com poucos casos.
Os traces usam retenção configurável e, por padrão, não armazenam inputs nem outputs completos. Gemini/OpenAI são testados somente por opt-in com fixtures fictícias; mocks e fallback local mantêm os testes e o produto utilizáveis sem chamada paga. Outcome Learning associa sinais do Tracker a fonte, variante de currículo, Match e ATS, mas não afirma causalidade nem altera Perfil ou pesos automaticamente.
- execute
python scripts/package_extension.pypara validar e gerar o ZIP, ou use a pastabrowser-extension/diretamente; - abra
chrome://extensionsouedge://extensions; - habilite Modo do desenvolvedor;
- clique em Carregar sem compactação e selecione
browser-extension/.
- prioriza
schema.org/JobPosting, depois metadados estruturados, seletores semânticos e texto visível; - cria capturas e snapshots de vaga, edital e projeto;
- mantém fila com estado, número de tentativas, erro, próximo retry, limite e deduplicação;
- permite exportar/importar a fila sem incluir chaves;
- usa handshake para informar versões, capacidades e compatibilidade;
- consulta apenas um resumo seguro do Perfil/Career Context;
- funciona com Local Companion mesmo quando o frontend está fechado.
Para análise GitHub, é possível usar processamento local, a IA configurada no SotuHire, Gemini próprio ou OpenAI próprio. A chave própria fica em sessão por padrão; persistência no cofre IndexedDB do service worker exige consentimento. Ela nunca usa chrome.storage.sync, não entra no content script ou na página e pode ser removida a qualquer momento.
Detalhes de instalação, permissões e diagnóstico: guia da extensão.
Por padrão, os dados ficam em data/:
data/sotuhire.db: entidades relacionais, snapshots, candidaturas e rastros seguros de IA;data/**/*.jsonedata/**/*.jsonl: stores legados mantidos para compatibilidade e migração;data/backups/: arquivos ZIP checksummed;data/secrets/: configuração local de provider, sempre excluída de backup e Git.
Defina SOTUHIRE_DATA_DIR para usar outro diretório local. Antes de migrar dados antigos:
python scripts/migrate_local_data.py --dry-run
python scripts/migrate_local_data.py --apply
python scripts/migrate_local_data.py --verifyOs arquivos JSON/JSONL antigos não são apagados. O --apply cria backup antes da transação e registra a migração. Para saúde, backup, export e restauração:
python scripts/check_data_health.py
python scripts/backup_data.py
python scripts/backup_data.py --export
python scripts/restore_data.py data/backups/ARQUIVO.zip
python scripts/restore_data.py data/backups/ARQUIVO.zip --applyA primeira chamada de restore é dry-run. No frontend, a aplicação da restauração exige confirmação textual e cria um novo backup preventivo.
O SotuHire não realiza auto-apply, candidatura automática, inscrição automática, pagamento, boleto, envio de documentos, bypass de CAPTCHA ou decisão crítica final apenas por IA.
- Visão geral
- Mapa de integração dos módulos
- Matriz verificável de capacidades
- Career Context Engine
- Linhagem e deduplicação
- Repositories e persistência
- Schema SQLite e migrações
- Snapshots de candidatura
- Backup, restore e data health
- Orquestração de IA
- Extensão e Perfil
- Segurança e privacidade
- Comece aqui: índice documental e documentação publicada
- Produto: visão, estratégia multiárea e roadmap
- Dados: arquitetura de storage, schema e migrações e matriz de integração
- IA: catálogo de prompts, plano de avaliação e RAG local
- Fontes e extensão: fontes de dados e guia da extensão
- Frontend: guia do app React, modos Demo/API Real e testes
- Testes: QA, CI/CD e golden datasets
- Portfólio: roteiro de demonstração e case study
- Histórico: CHANGELOG e releases
As próximas frentes aprofundam calibração por domínio, edição avançada de documentos e conectores públicos oficiais, sempre mantendo workflows de carreira sob aprovação humana. Consulte o roadmap atual para critérios, riscos e itens fora de escopo.
- abra uma issue descrevendo problema, evidência e comportamento esperado;
- crie uma branch curta e focada;
- adicione ou atualize testes e documentação;
- rode as validações locais relevantes;
- abra um pull request sem dados pessoais, chaves ou artefatos locais.
Mudanças devem preservar o modo Demo, a API Real, o fallback local, a revisão humana e os limites de segurança do produto.
Distribuído sob a Apache License 2.0.
Release atual: v1.9.7 · Notas da release · Tag