# Formato JSON para Ferramentas LLM

## Introdução

Compartilhar uma ferramenta de uma maneira que possa ser rapidamente adicionada a um programa ou editor de ferramentas seria muito melhorada com uma maneira padrão de representar uma ferramenta e como usá-la. Queremos habilitar recursos como os seguintes:

* Um ícone para representar visualmente a ferramenta
* Metadados para o prompt:
  * Um nome para a ferramenta
  * Uma descrição para a ferramenta
  * Notas de uso para a ferramenta
* Parâmetros de placeholder incluídos na string de ferramenta
* Saída esperada
* Versionamento e carimbos de data/hora.

## Especificação do Formato JSON

```json
{
  "version": "string ou inteiro",
  "model_prompt": "string com espaços reservados {{variable_name}}",
  "metadata": {
    "prompt_name": "string",
    "description": "string",
    "usage_notes": "string",
    "model_version": ["string", "string", …],
    "creator": {
      "name": "string",
      "email": "string",
      "organization": "string"
    },
    "parameters": {
      "temperature": "float",
      "max_tokens": "inteiro",
      "top_p": "float",
      "frequency_penalty": "float",
      "presence_penalty": "float"
    },
    "variables": [
      {
        "name": "nome da variável 1",
        "type": "texto",
        "description": "string",
        "default": "string",
      },
      {
        "name": "nome da variável 2",
        "type": "seleção única",
        "description": "string",
        "default": "valor1",
        "allowed_values": ["valor1", "valor2", "valor3"]
      },
      {
        "name": "nome da variável 3",
        "type": "seleção múltipla",
        "description": "string",
        "default": ["valor1", "valor2"]
        "allowed_values": ["valor1", "valor2", "valor3"]
      },
      ...
    ],
    "expected_output": {
      "type": "string (p.ex., texto, código, limitado)",
      "format": "string (opcional, p.ex., JSON, XML, CSV)",
      "language": "string (opcional, p.ex., Python, JavaScript)",
      "allowed_values": ["string1", "string2", ...] (opcional)
    },
    "avatar_type": "string (p.ex., url, base64)",
    "avatar": "string (URL ou imagem codificada em base64), recomendado 256x256 pixels",
    "timestamp": "string (formato ISO 8601)"
  }
}
```

Você pode baixar nosso exemplo de JSON [aqui](https://skydeck-public-assets.s3.amazonaws.com/sample_tool.json).

## Descrição dos Campos

* **model\_prompt**: Uma string que contém o prompt do modelo GPT.
* **metadata**: Um objeto que contém informações adicionais sobre o prompt do modelo GPT, incluindo os seguintes sub-campos:
  * **model\_version**: Uma string que indica a versão do modelo GPT utilizado.
  * **creator**: Um objeto que contém informações sobre o criador do prompt do modelo GPT, com os seguintes sub-campos:
    * **name**: Uma string que representa o nome do criador.
    * **email**: Uma string que representa o email do criador.
    * **organization**: Uma string que representa a organização à qual o criador é afiliado.
  * **parameters**: Um objeto que contém informações sobre os parâmetros do modelo GPT, com os seguintes sub-campos:
    * **temperature**: Um float que indica a temperatura utilizada para controlar a aleatoriedade da saída.
    * **max\_tokens**: Um inteiro que indica o número máximo de tokens na resposta gerada.
    * **top\_p**: Um float que representa o limiar de probabilidade de amostragem do núcleo.
    * **frequency\_penalty**: Um float que representa a penalidade aplicada aos tokens com base em sua frequência no conjunto de dados.
    * **presence\_penalty**: Um float que representa a penalidade aplicada a novos tokens com base em sua presença no prompt.
  * **timestamp**: Uma string no formato ISO 8601 que representa a data e hora em que o prompt do modelo GPT foi criado ou modificado pela última vez.
  * **expected\_output (Opcional)**: Um objeto que contém campos relacionados à saída esperada do model\_prompt, incluindo os seguintes sub-campos:
    * **type**: Uma string que indica o tipo de saída esperado do model\_prompt.
    * **format (Opcional)**: Uma string que representa o formato da saída esperada, se aplicável.
    * **language (Opcional)**: Uma string que representa a linguagem de programação da saída esperada se o tipo for `code`.
    * **allowed\_values (Opcional)**: Um array de strings que contém uma lista de valores de saída permitidos se o tipo for `limited`.
  * **variables (Opcional)**: Uma lista contendo variáveis que podem ser inseridas na string `model_prompt` em um estilo de f-string. Cada variável contém os seguintes sub-campos:
    * **name**: Uma string representando o nome da variável.
    * **type**: Uma string mostrando o tipo de variável. Atualmente, os possíveis valores de `type` são `text` para a variável padrão, e `single-select` ou `multi-select` para variáveis de seleção.
    * **description**: Uma string mostrando a descrição da variável, incluindo usos e exemplos.
    * **default**: Um valor mostrando o valor padrão da variável. Este valor é uma string se `type` for `text` ou `single-select`, e um array de strings para `multi-select`.
    * **allowed\_values**: Um array de strings que contém uma lista de valores permitidos se o tipo de variável for `single-select` ou `multi-select`
  * **avatar (Opcional)**: Um objeto que contém campos relacionados à imagem gráfica que atua como um avatar ou ícone para o prompt, incluindo os seguintes sub-campos:
    * **avatar\_type**: Uma string especificando o tipo de dados do avatar incluído.
    * **avatar**: Uma string contendo o URL que aponta para a imagem se o avatar\_type for `url`, ou uma string codificada em base64 que representa a imagem se o avatar\_type for `base64`.
  * **prompt\_name (Opcional)**: Uma string representando o nome do prompt.
  * **description (Opcional)**: Uma string fornecendo uma breve descrição da ferramenta e sua finalidade.
  * **usage\_notes (Opcional)**: Uma string contendo notas de uso livre do criador sobre o uso ou quaisquer considerações específicas relacionadas à ferramenta.

Para especificar o formato da saída esperada do model\_prompt, você pode adicionar um objeto `expected_output` dentro do objeto `metadata`. Dependendo do tipo de saída esperada, você pode incluir os sub-campos relevantes no objeto `expected_output`.

Para incluir campos para variáveis que podem ser inseridas na string `model_prompt` em um estilo de f-string, você pode adicionar uma lista `variables` separada dentro do objeto `metadata`.

Para incluir uma imagem gráfica atuando como um avatar ou ícone para o prompt, você pode adicionar um campo `avatar` dentro do objeto `metadata`.

A inclusão dos campos `expected_output`, `variables`, `avatar`, `prompt_name`, `description`, e `usage_notes` dentro do objeto `metadata` ajuda a manter todas as informações contextuais sobre o prompt em um só lugar, facilitando o gerenciamento e o entendimento.

Você pode usar o campo `version` no nível superior do objeto JSON para rastrear explicitamente a versão de todo o arquivo JSON