DOSSIE_TECNICO_2026-07-25.md

# Dossiê Técnico — THC LLM (backend)

**Data desta revisão:** 2026-07-25
**Repositório:** ~/thcllm — https://github.com/wilkertoigo/thcllm (mirror) + https://huggingface.co/spaces/HulkToigo/THCLLM (produção)
**HEAD:** 01dc751 — sincronizado em `origin` (HF Space) e `github` (mirror)

> Nota de proveniência: este arquivo existiu por engano no repositório
> `thc-cli` (commit `53bc8e0`, removido em `d1402e6`). O conteúdo é
> especificamente sobre o backend `app.py` do thcllm, não sobre a CLI —
> por isso foi movido para cá.

---

## 1. Estado do git (verificado em 2026-07-25)

- Branch: `main`, working tree clean.
- `origin` (HF Space) e `github` (mirror) **agora sincronizados** — antes
  desta revisão, `github` estava travado em `d07fc84` (bem atrás,
  faltavam ~24 commits incluindo toda a Fase 6/MCP e todo o trabalho de
  tool calling). Corrigido com `git push github main:main` (fast-forward
  confirmado seguro via `git merge-base --is-ancestor`).
- HEAD atual: `01dc751 fix(app): reordena schemas de tools/Anthropic e
  adiciona from __future__ import annotations`.

## 2. Tool calling — estado funcional

Implementado em dois formatos:
- **OpenAI-compatible** (`/v1/chat/completions`) — `tools` no formato
  `{"type":"function","function":{...}}`.
- **Anthropic-compatible** (`/v1/messages`, `/v1/messages/stream`) —
  `tools` no formato `{"name","description","input_schema"}`, usado pelo
  Claude Code SDK.

**Confirmado em produção**: curl real contra
`https://hulktoigo-thcllm.hf.space/v1/messages` com uma tool `get_weather`
retornou corretamente bloco `tool_use` com `stop_reason: "tool_use"`.
Testado com `llama33-70b-groq` (backend groq).

### Schemas (ordem confirmada em app.py, linhas 416-490)

416: class ToolFunctionParameters(BaseModel)
422: class ToolFunction(BaseModel)
428: class Tool(BaseModel)
433: class AnthropicMessage(BaseModel)
438: class AnthropicTool(BaseModel)
462: class ChatRequest(BaseModel) # usa Tool
490: class AnthropicRequest(BaseModel) # usa AnthropicTool

`from __future__ import annotations` está na linha 1 do arquivo — blindagem
permanente contra `NameError` de forward-reference em type hints.

## 3. PENDÊNCIA ATIVA — regressão encontrada nesta revisão

`grep -n "não suporta tool calling" app.py` retorna **vazio**.

Os warnings de log que avisam quando `req.tools` é enviado para um backend
que não suporta tool calling (`transformers`, `gguf`, `kilo`) existiam no
commit `ce54b53` original, mas se perderam na sequência de
revert/fix (`5ccd423` → `dbb524c`) e nunca foram restaurados. O `dbb524c`
("restaura suporte a tool calling sem SyntaxError") só recuperou a lógica
de `openrouter`/`groq`/`mistral`/`gemini`, não esses três warnings.

**Impacto**: baixo (comportamental, não funcional — hoje `req.tools`
simplesmente é ignorado nesses backends sem log, o que dificulta debug se
alguém tentar usar tools num modelo local/kilo sem perceber que não tem
efeito).

**Ação recomendada**: reintroduzir os 3 `logger.warning(...)` nos blocos
`if backend == "transformers"`, `elif backend == "gguf"`, `elif backend ==
"kilo"` de `chat_completions` e `chat_completions_async` — ver diff de
`ce54b53` para o texto exato original.

## 4. Pendências herdadas do relatório anterior (ainda não verificadas)

1. Testar `/v1/chat/completions` (formato OpenAI) pós-fix `01dc751`.
2. Testar `/v1/messages/stream` (SSE) com cliente real — só o
   não-streaming foi validado.
3. Testar tool calling com mistral, openrouter e gemini (só groq foi
   confirmado, e antes dos 3 incidentes de produção desta sessão).
4. Reintroduzir os warnings de backend sem suporte (ver seção 3 acima).

## 5. Inconsistência de schema em config.py (observação, não corrigida)

`TEXT_MODELS` mistura dois esquemas de chave:
- Backends remotos (`kilo`, `openrouter`, `groq`, `mistral`, `gemini`):
  usam `model_id`.
- Backends locais (`transformers`, `gguf`): usam `id` / `repo`+`file`.

Código que acesse `TEXT_MODELS[k]["model_id"]` genericamente pode gerar
`KeyError` para entradas locais. Não corrigido nesta revisão — só
documentado.

## 6. Estrutura do repositório

~/thcllm/
├── app.py (1838 linhas)
├── auth.py (103 linhas)
├── config.py (316 linhas)
├── models.py (141 linhas)
├── exceptions.py (46 linhas)
├── logger.py (14 linhas)
├── Dockerfile
├── requirements.txt
├── teste.py (stub: soma(a,b))
├── knowledge/, skills/
├── RELATORIO_TECNICO.md
├── SECURITY_INCIDENT_2026-07.md
└── DOSSIE_TECNICO_2026-07-25.md (este arquivo)


Sem pasta `tests/` — toda validação é manual (`py_compile`, `ast.parse`,
curl sequencial contra produção). O Space não tem CI.

## 7. Endpoints registrados

| método | path | 
|---|---|
| GET | `/` |
| GET | `/login`, `/auth/google`, `/auth/callback`, `/logout`, `/me` |
| GET | `/v1/models`, `/v1/quota` |
| POST | `/v1/knowledge/reload` |
| POST | `/v1/chat/completions` |
| POST | `/v1/images/generations` |
| POST | `/v1/audio/generations` |
| POST | `/v1/audio/transcriptions` |
| GET | `/v1/transcription-models` |
| POST | `/v1/messages`, `/v1/messages/stream` |

`/docs`, `/redoc`, `/openapi.json` ficam desativados por padrão
(`THC_DEBUG=true` para habilitar).

## 8. Lições de processo desta revisão (2026-07-25)

- Documentação e código divergem com facilidade quando há dois repos git
  separados (thc-cli / thcllm) apontando pra propósitos diferentes — um
  dossiê técnico do thcllm foi commitado por engano no repo do thc-cli.
  Antes de aceitar qualquer doc como verdade, confirmar com `git log`,
  `grep`, `find` no código real.
- Remote secundário (`github` mirror do thcllm) pode ficar
  silenciosamente desatualizado por múltiplos ciclos de trabalho — vale
  checar `git log <remote>/main --oneline` periodicamente, não só o
  remote principal de deploy.
- "Pendência antiga" registrada em relatório anterior (script de
  desativação do huggingface_provider) já tinha sido resolvida por outro
  caminho (comentário + import comentado em `providers/__init__.py` do
  thc-cli, datado de 2026-07-25) — relatórios precisam ser revalidados
  contra o código antes de serem tratados como lista de tarefas viva.