Initial ForgeLM import

docs/api/endpoints.md

@@ -0,0 +1,225 @@
+# Endpoints HTTP
+
+Esta pagina documenta a superficie HTTP publica atual do ForgeLM.
+
+## Base URL
+
+- default de bind: `0.0.0.0:8080`
+- endereco recomendado para consumo local: `http://127.0.0.1:8080`
+
+Quando esta documentacao usa `127.0.0.1`, ela esta descrevendo o endereco tipico de consumo local, nao necessariamente o bind literal do processo.
+
+## GET /health
+
+Retorna um snapshot simples do estado do processo.
+
+### Auth
+
+- nao exige auth
+
+### Exemplo
+
+```bash
+curl http://127.0.0.1:8080/health
+```
+
+### Resposta
+
+```json
+{
+  "status": "ok",
+  "model_loaded": true,
+  "model_id": "meu-modelo",
+  "uptime_secs": 42
+}
+```
+
+### Observacoes
+
+- hoje `model_loaded` funciona como um sinal operacional simples do processo em pe
+- o app desktop usa `GET /health` como parte do readiness check do runtime local
+
+## GET /v1/models
+
+Lista o modelo canonico e aliases conhecidos.
+
+### Auth
+
+- exige auth apenas se `LOCALLLM_API_KEY` estiver configurada
+
+### Cabecalhos aceitos
+
+- `Authorization: Bearer <token>`
+- `x-api-key: <token>`
+- ou o cabecalho custom configurado em `LOCALLLM_AUTH_HEADER`
+
+### Exemplo
+
+```bash
+curl http://127.0.0.1:8080/v1/models
+```
+
+### Resposta
+
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "id": "default",
+      "object": "model",
+      "created": 1710000000,
+      "owned_by": "local",
+      "root": "meu-modelo",
+      "parent": "meu-modelo",
+      "permission": []
+    }
+  ]
+}
+```
+
+### Observacoes
+
+- `root` aponta para o modelo canonico
+- `parent` e usado quando um ID e alias do modelo canonico
+- o app desktop usa esse endpoint para preencher o seletor de modelo
+
+## POST /v1/chat/completions
+
+Endpoint principal de inferencia.
+
+### Auth
+
+- exige auth apenas se `LOCALLLM_API_KEY` estiver configurada
+
+### Campos principais da request
+
+```json
+{
+  "model": "default",
+  "messages": [
+    { "role": "user", "content": "Explique este projeto" }
+  ],
+  "max_tokens": 1024,
+  "temperature": 0.15,
+  "top_p": 0.95,
+  "stream": false,
+  "stop": [],
+  "n": 1,
+  "seed": null,
+  "user": null,
+  "response_format": null,
+  "tools": [],
+  "tool_choice": null,
+  "parallel_tool_calls": null,
+  "stream_options": null
+}
+```
+
+### Defaults importantes
+
+- `max_tokens`: `1024`
+- `temperature`: `0.15`
+- `top_p`: `0.95`
+- `n`: `1`
+
+### Regras de validacao
+
+- `model` deve existir no catalogo de modelos
+- `messages` nao pode ser vazio
+- `n` precisa ser `1`
+- `tools` podem ser rejeitadas se tool calling estiver desabilitado
+
+### Exemplo sem streaming
+
+```bash
+curl http://127.0.0.1:8080/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "default",
+    "messages": [{"role": "user", "content": "Diga ola"}],
+    "stream": false
+  }'
+```
+
+### Resposta sem streaming
+
+```json
+{
+  "id": "chatcmpl-...",
+  "object": "chat.completion",
+  "created": 1710000000,
+  "model": "meu-modelo",
+  "choices": [
+    {
+      "index": 0,
+      "message": {
+        "role": "assistant",
+        "content": "Ola!"
+      },
+      "finish_reason": "stop"
+    }
+  ],
+  "usage": {
+    "prompt_tokens": 12,
+    "completion_tokens": 8,
+    "total_tokens": 20,
+    "tokens_per_second": 31.5
+  }
+}
+```
+
+### Exemplo com streaming
+
+```bash
+curl http://127.0.0.1:8080/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -N \
+  -d '{
+    "model": "default",
+    "messages": [{"role": "user", "content": "Escreva um resumo"}],
+    "stream": true,
+    "stream_options": {"include_usage": true}
+  }'
+```
+
+### Streaming SSE
+
+O backend envia eventos `data: ...` no formato `chat.completion.chunk` e termina com:
+
+```text
+data: [DONE]
+```
+
+O ultimo chunk pode incluir `usage` se `include_usage=true`.
+
+### Erros
+
+Exemplo de payload de erro:
+
+```json
+{
+  "error": {
+    "message": "Only n=1 is currently supported",
+    "type": "invalid_request_error",
+    "param": "n",
+    "code": "unsupported_value"
+  }
+}
+```
+
+### Limitacoes atuais
+
+- o servidor nao implementa toda a plataforma OpenAI
+- `parallel_tool_calls` nao deve ser tratado como recurso plenamente suportado
+- o campo `content` de mensagens pode aceitar arrays de partes textuais, mas o backend reduz isso a texto consolidado
+- reasoning nativo nao aparece como campo separado na API HTTP; o app desktop separa `<think>...</think>` no frontend
+
+## Codigos de status mais comuns
+
+- `200 OK` - sucesso
+- `400 Bad Request` - payload invalido ou modo nao suportado
+- `401 Unauthorized` - chave ausente/invalida quando auth esta habilitada
+- `404 Not Found` - modelo nao encontrado
+
+Para configuracao do servidor e variaveis de ambiente, veja `configuration.md`.