Regras comuns | LMSP 1.0 Rascunho

9.1 Versões e extensões

Cada requisição LMSP PODE carregar estes cabeçalhos:

LMSP-Version: 1.0
LMSP-Client: example-client/1.2.0

LMSP-Version é a versão do protocolo que o cliente tem como alvo. LMSP-Client identifica o software cliente para fins de diagnóstico, como name/version. Um serviço NÃO DEVE alterar o comportamento do protocolo com base nele.

Regras:

O v1 no caminho denota a versão principal.
Uma requisição que nomeia uma versão principal desconhecida é respondida com 426 Upgrade Required e o código de erro unsupported_protocol_version.
Novos campos opcionais NÃO DEVEM quebrar a compatibilidade da 1.x.
Serviços e clientes DEVEM ignorar os campos que não conhecem.
As extensões privadas ficam em um objeto extensions e são nomeadas em notação de domínio reverso:

{
  "extensions": {
    "com.example.cache": {
      "enabled": true
    }
  }
}

9.2 Idempotência

As requisições que criam algo, como criar uma resposta, criar uma tarefa ou carregar um modelo, aceitam uma chave de idempotência:

Idempotency-Key: <client-generated-unique-value>

O serviço armazena a chave junto com um digest do corpo da requisição e o resultado:

A mesma chave com o mesmo corpo retorna o resultado original.
A mesma chave com um corpo diferente é respondida com 409 Conflict e idempotency_conflict.

Uma chave tem como escopo o cliente e o endpoint. Ela DEVERIA ser um valor único de no máximo 255 caracteres, como um ULID ou um UUID. Um serviço DEVERIA guardar as chaves por pelo menos 24 horas.

Um serviço PODE ignorar a chave em requisições em streaming. Um cliente que precisa de novas tentativas seguras usa uma tarefa.

9.3 Erros

Todo erro na interface LMSP usa application/problem+json (RFC 9457):

{
  "type": "urn:lmsp:error:model-not-found",
  "title": "Model not found",
  "status": 404,
  "code": "model_not_found",
  "detail": "No local model with id 'qwen3:14b-q4_k_m'",
  "request_id": "req_01J8M9S6Y4W8C3P5R1V7Z2A0DH",
  "retryable": false
}

Campo	Obrigatório	Significado
`type`	Sim	URI que identifica o tipo de erro. O LMSP usa `urn:lmsp:error:` seguido do código com hifens no lugar de sublinhados.
`title`	Sim	Resumo curto e legível por pessoas.
`status`	Sim	O código de status HTTP.
`code`	Sim	Código de erro legível por máquina, da lista abaixo.
`detail`	Não	Explicação legível por pessoas desta ocorrência. Ela NÃO DEVE conter segredos, prompts nem conteúdo gerado.
`request_id`	Não	Identificador da requisição, para correlação com os logs do serviço.
`retryable`	Sim	Se repetir a requisição mais tarde pode dar certo.

Códigos de erro comuns:

Código	Status HTTP	Repetível	Significado
`invalid_request`	400	Não	A requisição está malformada ou tem parâmetros inválidos.
`unauthorized`	401	Não	O token está ausente, é inválido, expirou ou foi revogado, ou um código de pareamento está errado.
`forbidden`	403	Não	O token não tem o escopo exigido, ou a verificação de `Origin` ou `Host` falhou.
`model_not_found`	404	Não	Nenhum modelo local tem este ID.
`model_not_ready`	409	Sim	O modelo não está carregado e não é carregado sob demanda.
`model_load_failed`	500	Sim	O carregamento do modelo falhou.
`context_length_exceeded`	400	Não	A entrada não cabe na janela de contexto do modelo.
`unsupported_capability`	400 ou 501	Não	O modelo ou o serviço não suporta o que a requisição exige. Um endpoint opcional não implementado responde 501.
`unsupported_protocol_version`	426	Não	O serviço não suporta a versão principal solicitada.
`response_not_found`	404	Não	Nenhuma resposta armazenada tem este ID.
`task_not_found`	404	Não	Nenhuma tarefa tem este ID.
`task_not_cancelable`	409	Não	A tarefa já foi concluída com sucesso ou falhou.
`idempotency_conflict`	409	Não	A chave de idempotência já foi usada com outro corpo de requisição.
`event_history_expired`	410	Não	Os eventos solicitados são mais antigos que o período de retenção.
`rate_limited`	429	Sim	Requisições demais.
`resource_exhausted`	503	Sim	O dispositivo ficou sem memória ou sem outro recurso.
`backend_unavailable`	503	Sim	Não é possível alcançar o ambiente de execução do modelo.
`server_restarted`	503	Sim	O serviço foi reiniciado enquanto a tarefa estava inacabada.
`internal_error`	500	Varia	Uma falha inesperada dentro do serviço.

O campo retryable é a referência definitiva. A coluna acima mostra o valor usual. Um serviço PODE definir outros códigos. Um cliente DEVE tratar um código que não conhece pelo seu status HTTP e pelo seu campo retryable.

9.4 Verificação de integridade

GET /lmsp/v1/health

{
  "status": "ready",
  "service_id": "svc_01J8M4Y8K6M5E6K6Z7Z0Y8W3M2",
  "uptime_seconds": 86420,
  "loaded_models": 1,
  "active_tasks": 2,
  "storage": "ok"
}

Campo	Significado
`status`	`starting`, `ready`, `degraded` ou `stopping`.
`service_id`	O ID do serviço da descrição do serviço.
`uptime_seconds`	Segundos desde que o serviço foi iniciado.
`loaded_models`	Número de modelos no estado `ready`.
`active_tasks`	Número de tarefas que estão `queued`, `loading`, `running` ou `cancelling`.
`storage`	`ok` ou `error`.

O status HTTP é 200 OK quando status é ready ou degraded, e 503 Service Unavailable nos demais casos.

O endpoint de integridade retorna apenas o status operacional. Ele NÃO DEVE retornar caminhos de modelos, prompts, tokens de acesso nem outras informações sensíveis.