recotem

Recotem é um framework de sistema de recomendação orientado a receitas que simplifica o treinamento e a disponibilização de modelos de recomendação. Ele é construído sobre o irspack e usa um único arquivo de receita YAML para definir todo o pipeline: fonte de dados, algoritmo de treinamento, busca de hiperparâmetros e local de saída. O comando `recotem train` produz um artefato binário assinado, enquanto o `recotem serve` executa um servidor FastAPI que expõe endpoints como `/v1/recipes/{name}:recommend` e `:recommend-related`, com troca a quente automática quando novos artefatos aparecem. Ele não requer banco de dados ou broker de mensagens, tornando-o leve e fácil de implantar. Os principais recursos incluem: - **Configuração orientada a receitas**: Um arquivo YAML define um modelo completo, desde a ingestão de dados até a disponibilização. - **Otimização de hiperparâmetros**: Usa Optuna para pesquisar algoritmos do irspack. - **iALS ciente de recursos**: Suporta recursos laterais de item/usuário (categóricos, numéricos, multi-rótulo) para recomendações aprimoradas. - **Suporte a cold-start**: Pode recomendar para usuários ou itens desconhecidos usando recursos de atributos. - **Fontes de dados plugáveis**: Suporte integrado para CSV, Parquet, BigQuery e SQL (PostgreSQL, MySQL, SQLite), com extensibilidade via pontos de entrada Python. - **Artefatos seguros**: Assinados com HMAC, com rotação de múltiplas chaves e uma lista de permissões de classes determinística para desserialização segura. - **Autenticação por chave de API**: Cabeçalho opcional `X-API-Key`, com chaves hash em repouso. - **Armazenamento flexível**: Usa fsspec para caminhos locais, S3, GCS, Azure e HTTPS. - **Observabilidade**: Métricas Prometheus opcionais e logs JSON estruturados com redação de segredos. A ferramenta é projetada para reprodutibilidade e simplicidade operacional. O treinamento é executado como um job em lote (ex.: cron, Airflow, Kubernetes CronJob), e a disponibilização é um processo de longa duração que observa novos artefatos e os troca atomicamente. Essa separação permite que treinamento e disponibilização rodem em máquinas diferentes, comunicando-se apenas por arquivos de artefato. A instalação é via pip com extras para fontes de dados específicas (ex.: `recotem[bigquery]`, `recotem[s3]`). Uma imagem Docker multi-arquitetura está disponível no ghcr.io. O projeto requer Python 3.12+ e suporta Linux glibc (x86-64/arm64), macOS (Apple Silicon) e Windows (x86-64). Alguns extras como `bprfm` têm suporte de plataforma mais restrito e podem exigir compilação a partir do código-fonte. O exemplo de início rápido demonstra o treinamento de um recomendador TopPop a partir de um pequeno CSV e a disponibilização de recomendações via HTTP. O site de documentação (recotem.org) fornece guias abrangentes, referências de API e detalhes operacionais.