plan.md

Plano Validado (Context7): HF Spaces + HF CLI + Jobs

Este plano foi corrigido com base nas boas praticas documentadas no Hugging Face Hub/CLI via Context7.

1) Arquitetura recomendada

• Space (Docker): roda o bot Discord e serve consultas RAG.
• HF Job: reconstrói o indice FAISS sob demanda ou por agendamento.
• Dataset repo (Hub): armazena os artefatos versionados do indice (faiss.index, meta.json, manifest.json).

Motivo: o acoplamento direto de volume entre Space e Job nao deve ser assumido. Para integracao confiavel entre componentes, use artefato no Hub.

2) Persistencia correta no Space

No Space, habilite Persistent Storage em Settings > Hardware.

Use os caminhos abaixo:

• HF_HOME=/data/.huggingface
• LOCAL_STORAGE_DIR=/data/storage

Observacao:

• /data e o caminho de volume persistente em Spaces.
• qualquer dado fora de /data pode ser efemero.

3) Fluxo operacional (producao)

3.1 Build de indice (Job)

1. Job baixa os documentos (repo/dataset/origem definida).
2. Job gera faiss.index + meta.json.
3. Job publica artefatos no dataset de indices (com commit e tag/revisao).
4. Job atualiza manifest.json com revision, created_at, embed_model, num_chunks.

3.2 Consumo no Space

1. Bot inicia.
2. Bot baixa o ultimo artefato aprovado do dataset.
3. Bot salva localmente em /data/storage para cache quente.
4. Bot consulta manifest.json periodicamente e faz hot-reload quando revision muda.

Resultado:

• sem depender de restart para atualizar base;
• rollback simples por revisao/tag do dataset.

3.3 Envio de @docs_rag para estrutura HF

Padrao recomendado: separar fonte documental e artefato de indice.

• Dataset 1 (fonte): <org-ou-user>/rag-docs
• Dataset 2 (indice): <org-ou-user>/rag-index

Estrutura no Hub:

• rag-docs/docs_rag/... (originais .pdf/.doc/.docx/.rtf)
• rag-index/artifacts/faiss.index
• rag-index/artifacts/meta.json
• rag-index/artifacts/manifest.json

Comandos para publicar ./docs_rag:

# criar dataset de documentos (uma vez)
hf repo create <org-ou-user>/rag-docs --repo-type dataset --private

# upload completo da pasta local docs_rag para /docs_rag no dataset
hf upload <org-ou-user>/rag-docs ./docs_rag docs_rag --repo-type dataset --commit-message "docs: carga inicial"

Incremental (atualizacoes futuras):

hf upload <org-ou-user>/rag-docs ./docs_rag docs_rag --repo-type dataset --commit-message "docs: update <timestamp>"

Upload otimizado (filtro e higiene):

hf upload <org-ou-user>/rag-docs ./docs_rag docs_rag \
  --repo-type dataset \
  --commit-message "docs: update <timestamp>" \
  --exclude "**/.DS_Store" \
  --exclude "**/Thumbs.db" \
  --exclude "**/~$*" \
  --exclude "**/*.tmp" \
  --exclude "**/*.log" \
  --exclude "**/__pycache__/**"

Upload otimizado com whitelist de extensoes (recomendado):

hf upload <org-ou-user>/rag-docs ./docs_rag docs_rag \
  --repo-type dataset \
  --commit-message "docs: update <timestamp>" \
  --include "**/*.pdf" \
  --include "**/*.doc" \
  --include "**/*.docx" \
  --include "**/*.rtf" \
  --exclude "**/.DS_Store" \
  --exclude "**/Thumbs.db" \
  --exclude "**/~$*"

Opcional para acervo muito grande (lote por pasta):

hf upload <org-ou-user>/rag-docs ./docs_rag/legislacao_grifada_e_anotada_atualiz_em_01_01_2026 docs_rag/legislacao_grifada_e_anotada_atualiz_em_01_01_2026 --repo-type dataset --commit-message "docs: lote legislacao"
hf upload <org-ou-user>/rag-docs ./docs_rag/sumulas_tse_stj_stf_e_tnu_atualiz_01_01_2026_2 docs_rag/sumulas_tse_stj_stf_e_tnu_atualiz_01_01_2026_2 --repo-type dataset --commit-message "docs: lote sumulas"

Observacoes operacionais:

• o Job deve ler da pasta docs_rag/ no dataset de documentos.
• o Job publica o resultado no dataset de indice (rag-index).
• o Space nunca depende diretamente do filesystem do Job.

4) Comandos HF CLI (baseline)

4.1 Autenticacao e diagnostico

hf auth whoami
hf env

4.2 Criar repo de artefatos (dataset)

hf repo create <org-ou-user>/rag-index --repo-type dataset --private

4.3 Upload de artefatos do indice

hf upload <org-ou-user>/rag-index ./artifacts . --repo-type dataset --commit-message "reindex: <timestamp>"

4.4 Rodar Job manual

hf jobs run python:3.12 python ingest_job.py

4.5 Agendar Job

Use os comandos de agendamento de jobs (hf jobs scheduled ...) para periodicidade (ex.: diario).

5) Variaveis e segredos

5.1 Space (Variables)

• HF_HOME=/data/.huggingface
• LOCAL_STORAGE_DIR=/data/storage
• INDEX_REPO_ID=<org-ou-user>/rag-index
• INDEX_REPO_TYPE=dataset
• INDEX_POLL_SECONDS=60

5.2 Space/Job (Secrets)

• HF_TOKEN (escopo minimo necessario)
• OPENROUTER_API_KEY
• DISCORD_TOKEN

Regra:

• nunca commitar token no repo;
• sempre usar Secrets do Space/Job.

6) Checklist de robustez

• validar autenticacao antes de operacoes: hf auth whoami.
• validar ambiente com hf env.
• publicar indice com metadados (manifest.json).
• fazer pinagem por revisao para reproducibilidade.
• manter estrategia de rollback (tag da ultima versao estavel).
• registrar logs de reindex e troca de revisao no bot.

7) Custo e desempenho

• Space CPU pequeno atende bem para consulta RAG leve.
• Reindex em Job CPU normalmente e suficiente.
• /data reduz redownload ao manter cache com HF_HOME.
• separar inferencia (OpenRouter) da indexacao reduz custo total.

8) Criticos corrigidos neste plano

• removida suposicao de persistencia em storage/ fora de /data.
• removida suposicao de compartilhamento direto de volume entre Space e Job.
• adicionada camada de artefato versionado no Hub para sincronizacao segura.
• adicionadas operacoes minimas de CLI para auditoria e rollback.