Compatibilidade com TypeSafe

O modelo Jev fechado da TypeSafe criou a categoria “System One” de modelos de decisão. A API /v1/* do Ollaya é idêntica em nível de protocolo à da TypeSafe, conforme definida pelo esquema de transmissão e pelo tratamento de erros do typesafe-sdk 0.7.1, então o código escrito para a TypeSafe roda contra modelos abertos na sua própria máquina.

Aponte o SDK para o Ollaya

O SDK oficial da TypeSafe para Python 0.7.1 funciona sem alterações. Defina estas variáveis de ambiente:

export TYPESAFE_BASE_URL=http://localhost:11435
export TYPESAFE_API_KEY=local           # the SDK needs a non-empty key; any value works
export TYPESAFE_DEFAULT_MODEL=winnow:e4b   # otherwise the SDK sends its default, "jev-latest"
export NO_PROXY=localhost,127.0.0.1    # keep local requests off any system proxy

• Modelo padrão. winnow:e4b é o mais próximo do Jev (0.722 em decisões tipadas, contra 0.738) e responde em cerca de 90 ms em uma RTX 4090. Sem GPU NVIDIA, use laya, que responde em uma fração de segundo em uma CPU.
• API key. O Ollaya aceita qualquer key, a menos que o servidor defina OLLAYA_API_KEY; nesse caso a key do SDK precisa corresponder a ela.
• IDs de requisição. Toda resposta carrega x-typesafe-request-id, então response.request_id funciona.
• Tentativas. O SDK expira após 10 s e tenta de novo. A primeira requisição a um modelo espera enquanto ele carrega, e um carregamento que sobrevive à requisição continua, então a nova tentativa encontra o modelo aquecido.
• Proxies do sistema. Em um Mac com um proxy HTTP do sistema, o SDK da TypeSafe (como o httpx) envia também as requisições para localhost pelo proxy, ignorando a lista de exceções do sistema. Seus estados então passam pelo proxy, e enquanto o Ollaya está fora do ar o SDK reporta 502 status code (no body) em vez de uma conexão recusada. Defina NO_PROXY=localhost,127.0.0.1 ao lado de TYPESAFE_BASE_URL.
• Aquecimento e tempos. Para carregar um modelo antes da primeira requisição, envie {"model": "winnow:e4b", "keep_alive": -1} para /api/decide (sem state). As respostas de /v1/* não carregam tempos, como as da TypeSafe; /api/decide reporta total_duration, load_duration e eval_duration.

Endpoints

Requisição e resposta

curl http://localhost:11435/v1/systemone \
  -H "Authorization: Bearer local" \
  -d '{
  "model": "laya",
  "state": "Can I get an invoice for last month?",
  "questions": {
    "intent": {
      "type": "choice",
      "instructions": "What does the customer want?",
      "criteria": {
        "invoice": "Needs an invoice or receipt",
        "refund": "Wants money back",
        "other": "Anything else"
      }
    }
  }
}'

{
  "model": "laya:en",
  "answers": {
    "intent": {
      "type": "choice",
      "choice": "invoice",
      "confidence": 0.9547,
      "probabilities": {"invoice": 0.9698, "refund": 0.0172, "other": 0.013}
    }
  },
  "usage": {"input_tokens": 43, "output_tokens": 0}
}

model na resposta é o checkpoint que respondeu: laya é um router, e esta requisição em inglês foi para laya:en. O esquema da TypeSafe permite isso (“may differ from the alias supplied in the request”). Os valores têm 4 casas decimais, e probabilities seguem a ordem de criteria.

curl http://localhost:11435/v1/models -H "Authorization: Bearer local"

{
  "models": [
    {
      "name": "laya:en",
      "description": "English decision model (ModernBERT-large): guardrails, email and ticket triage.",
      "release_date": "2026-09-23"
    },
    {
      "name": "laya:latest",
      "description": "Routes each request to laya:en or laya:multilingual by the text's script and language.",
      "release_date": "2026-09-23"
    },
    {
      "name": "laya:multilingual",
      "description": "Decision model for 100+ languages (mmBERT-base).",
      "release_date": "2026-09-23"
    }
  ]
}

/v1/models lista os modelos baixados para esta máquina, routers incluídos; não lista o registro.

Erros

Os erros carregam os códigos de status da TypeSafe e um corpo que o SDK lê corretamente: um error de string (que o SDK mostra), um code legível por máquina e, em 422, a lista detail de problemas de validação da TypeSafe. Veja erros para cada código.

{"error": "model \"jev-latest:latest\" not found, try pulling it first", "code": "MODEL_NOT_FOUND"}

O que é diferente

A compatibilidade cobre a API, não o modelo:

• Os nomes de modelo são do Ollaya (laya, laya:en), então defina TYPESAFE_DEFAULT_MODEL ou passe model.
• instructions ausente. Quando uma pergunta não tem nenhuma, o modelo lê o id da pergunta no lugar, então dê nomes descritivos às perguntas (is_urgent, tone).
• Limites. No máximo 256 perguntas por requisição, 2–255 opções e 2–10 níveis de score. Cada modelo também tem um orçamento de opções: cerca de 125 opções para laya:en, 250 para laya:multilingual.
• Estados longos. A TypeSafe lê até 65.536 tokens; o contexto de um modelo aberto é mais curto (512 tokens para laya:en, 1.024 para laya:multilingual, incluindo as perguntas). Quando um estado não cabe, /v1/* retorna 422 STATE_TRUNCATED em vez de responder com parte dele. Use um modelo com contexto mais longo, encurte o estado ou chame /api/decide, que trunca e reporta state_truncated.
• /v1/* permanece puro. Campos nativos como keep_alive e extras são ignorados ali; roteamento, tempos e truncamento são reportados em /api/decide.
• A qualidade vem de modelos abertos, então difere da do Jev por tarefa:
  • laya:typed-decisions obtém 0.766 em decisões tipadas, contra 0.727 publicado para o Jev 1.13.
  • Os checkpoints base do Laya ficam perto do acaso zero-shot em decisões tipadas (0.362).
  • Perguntas choice com muitas opções (mais de ~20) são mais fracas: 0.425 no Banking77, contra 0.870 do Jev.

Meça nos seus próprios dados antes de trocar o tráfego de produção. A página do Laya tem os detalhes.

Sem afiliação

O Ollaya é um projeto de código aberto independente. Não é afiliado à TypeSafe nem endossado por ela.