Gateway

// npm install termo_core --save-exact
import * as ai from "termo_core/ai";
// ou: import { ai } from "termo_core";

chave_ia_buscar_catalogoCopiar link

Catálogo do gateway de IA

Exige qualquer permissão da área gateway (qualquer ação liberada na área já libera a leitura). Lista o que POST /gateway atende: cada categoria (texto_para_texto, imagem_para_texto, texto_para_imagem, audio_para_texto, texto_para_audio, video_para_texto, texto_para_video) com a descrição, o tipo de entrada e de saida (texto, imagem, audio ou video), quantas chaves estão livres agora e as IAs que a atendem com o modelo de cada uma; e cada IA com o nome, se exige conta, o fuso padrão da cota e as categorias que atende.

function chave_ia_buscar_catalogo(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.CatalogoDoGateway>

import { CredencialDeAcesso } from "termo_core";
import { chave_ia_buscar_catalogo } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await chave_ia_buscar_catalogo(credencial_de_acesso);

Argumentos

Retorno: Promise<tipos.CatalogoDoGateway> · Rust: Result<tipos::CatalogoDoGateway, ErroAoChamarServico> · veja CatalogoDoGateway.

chave_ia_executar_gatewayCopiar link

Executa um pedido no gateway de IA

Com token de usuário, exige a permissão criar da área gateway; com token de aplicativo (outro back-end, via termo_core::CredencialDeAcesso::token_do_aplicativo()), qualquer app válido do TermoAuth entra e a conversa nova grava o slug do app em aplicativo. Atende o pedido com as chaves de IA cadastradas, trocando de chave e de IA quando uma falha, até as regras da categoria (/config_system_gateway) mandarem parar. categoria é obrigatória. Nas categorias de entrada em texto, texto é obrigatório; nas de entrada em imagem, áudio ou vídeo, arquivo é obrigatório: { base64, tipo_mime } (até 20 MB, aceita data URL) ou { url } (baixada pelo TermoAI), e texto é a pergunta sobre o arquivo (sem ele vale uma pergunta padrão). provedor fixa uma IA que atenda a categoria (só ela, sem trocar de IA). provedor_preferido (um provedor de GET /gateway/modelos) tenta primeiro as chaves dessa IA e só troca para as outras, na ordem de sempre, quando ela falha ou não tem chave livre; sem ele, a escolha é a de sempre; com provedor junto, vale o provedor. instrucao é a instrução de sistema, idioma ajuda transcrição e fala, voz escolhe a voz da fala. historico (no máximo as 40 últimas mensagens com texto, papel usuario ou assistente) dá contexto; sem ele, com conversa_id (de uma conversa da mesma categoria), o contexto vem da própria conversa. A pergunta e a resposta são gravadas na conversa informada ou numa conversa nova de origem api, cujo id volta em conversa_id; os arquivos da pergunta e da resposta ficam no TermoBucket (privados, do app termo-ai). A resposta traz texto ou arquivo (base64 com o tipo), a IA, o modelo, o apelido da chave que atendeu, os tokens (quando a IA informa), as tentativas que falharam e a duração. Ferramentas (opcional, só em texto_para_texto): ferramentas lista até 128 funções (nome com até 64 letras, números, _ ou -; descricao; parametros em JSON Schema) que a IA pode pedir para chamar; só entram as IAs que aceitam ferramentas (Gemini, Groq, Mistral, Cerebras, NVIDIA, Cohere, Z.ai e Ollama). Quando a IA quer uma ferramenta, a resposta traz chamadas_de_ferramenta (id, nome, argumentos em objeto e assinatura, que deve voltar igual) e, às vezes, texto. Quem chamou executa as ferramentas e pede de novo com o historico estendido: a mensagem assistente com as chamadas_de_ferramenta (e texto, vazio se não houver) e uma mensagem ferramenta por resultado, com chamada_id e o resultado em texto; quando o histórico termina num resultado, texto do pedido é opcional. Mensagens de ferramenta no histórico exigem ferramentas no pedido. A conversa gravada guarda as chamadas na mensagem do assistente, mas não os resultados.

function chave_ia_executar_gateway(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.PedidoGateway,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.RespostaDoGateway>

import { CredencialDeAcesso } from "termo_core";
import { chave_ia_executar_gateway } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await chave_ia_executar_gateway(credencial_de_acesso, corpo_da_requisicao);

Argumentos

Retorno: Promise<tipos.RespostaDoGateway> · Rust: Result<tipos::RespostaDoGateway, ErroAoChamarServico> · veja RespostaDoGateway.

chave_ia_buscar_modelosCopiar link

Lista os modelos que o gateway pode usar agora

Com token de usuário, exige qualquer permissão da área gateway; com token de aplicativo (outro back-end, via termo_core::CredencialDeAcesso::token_do_aplicativo()), qualquer app válido do TermoAuth entra. Serve para o app mostrar e deixar escolher a IA que vai em provedor_preferido do POST /gateway. categoria é opcional (padrão texto_para_texto). Só entram as IAs da categoria com ao menos uma chave ativa cadastrada, na ordem do catálogo. Cada item traz o id da IA (provedor, o valor de provedor_preferido), o nome da empresa (empresa), o modelo que o gateway usa nela, a url_da_logo (SVG servido pelo frontend do TermoAI; logo_monocromatica indica a logo de uma cor só, que deve ser pintada com a cor do texto), gratuito (todas as chaves ativas da IA são gratuitas; com uma paga já vira false), aceita_ferramentas e quantas chaves ativas a IA tem.

function chave_ia_buscar_modelos(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeChaveIaBuscarModelos = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.ModeloDoGateway>>

import { CredencialDeAcesso } from "termo_core";
import { chave_ia_buscar_modelos } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await chave_ia_buscar_modelos(credencial_de_acesso, { categoria: "..." });

Argumentos

Retorno: Promise<Array<tipos.ModeloDoGateway>> · Rust: Result<Vec<tipos::ModeloDoGateway>, ErroAoChamarServico>

TiposCopiar link

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

ArquivoCopiar link

import type { Arquivo } from "termo_core/ai";

export interface Arquivo {
  base64: string;
  tipo_mime: string;
}

ArquivoDoPedidoCopiar link

import type { ArquivoDoPedido } from "termo_core/ai";

export interface ArquivoDoPedido {
  base64?: string | null;
  nome?: string | null;
  tipo_mime?: string | null;
  url?: string | null;
}

CatalogoDoGatewayCopiar link

import type { CatalogoDoGateway } from "termo_core/ai";

export interface CatalogoDoGateway {
  categorias: Array<CategoriaDoCatalogo>;
  provedores: Array<ProvedorDoCatalogo>;
  rota: string;
}

CategoriaDoCatalogoCopiar link

import type { CategoriaDoCatalogo } from "termo_core/ai";

export interface CategoriaDoCatalogo {
  categoria: string;
  chaves_disponiveis: number;
  descricao: string;
  entrada: string;
  provedores: Array<ProvedorDaCategoria>;
  saida: string;
}

ChamadaDeFerramentaCopiar link

import type { ChamadaDeFerramenta } from "termo_core/ai";

export interface ChamadaDeFerramenta {
  argumentos?: unknown;
  assinatura?: string | null;
  id: string;
  nome: string;
}

FerramentaCopiar link

import type { Ferramenta } from "termo_core/ai";

export interface Ferramenta {
  descricao?: string | null;
  nome: string;
  parametros?: unknown;
}

MensagemDoHistoricoCopiar link

import type { MensagemDoHistorico } from "termo_core/ai";

export interface MensagemDoHistorico {
  chamada_id?: string | null;
  chamadas_de_ferramenta?: Array<ChamadaDeFerramenta>;
  papel: Papel;
  texto: string;
}

ModeloDoGatewayCopiar link

import type { ModeloDoGateway } from "termo_core/ai";

export interface ModeloDoGateway {
  aceita_ferramentas: boolean;
  chaves_ativas: number;
  empresa: string;
  gratuito: boolean;
  logo_monocromatica: boolean;
  modelo: string;
  provedor: string;
  url_da_logo: string;
}

PapelCopiar link

import type { Papel } from "termo_core/ai";

export type Papel = "usuario" | "assistente" | "ferramenta";

PedidoGatewayCopiar link

import type { PedidoGateway } from "termo_core/ai";

export interface PedidoGateway {
  arquivo?: ArquivoDoPedido | null;
  categoria: string;
  conversa_id?: string | null;
  ferramentas?: Array<Ferramenta> | null;
  historico?: Array<MensagemDoHistorico> | null;
  idioma?: string | null;
  instrucao?: string | null;
  provedor?: string | null;
  provedor_preferido?: string | null;
  texto?: string | null;
  voz?: string | null;
}

ProvedorDaCategoriaCopiar link

import type { ProvedorDaCategoria } from "termo_core/ai";

export interface ProvedorDaCategoria {
  modelo?: string | null;
  nome: string;
  provedor: string;
}

ProvedorDoCatalogoCopiar link

import type { ProvedorDoCatalogo } from "termo_core/ai";

export interface ProvedorDoCatalogo {
  categorias: Array<string>;
  exige_conta: boolean;
  fuso_da_cota: string;
  nome: string;
  provedor: string;
}

RespostaDoGatewayCopiar link

import type { RespostaDoGateway } from "termo_core/ai";

export interface RespostaDoGateway {
  arquivo?: Arquivo | null;
  categoria: string;
  chamadas_de_ferramenta?: Array<ChamadaDeFerramenta> | null;
  chave: string;
  conversa_id?: string | null;
  duracao_ms: number;
  modelo: string;
  provedor: string;
  tentativas: Array<TentativaDaMensagem>;
  texto?: string | null;
  tokens?: number | null;
}

TentativaDaMensagemCopiar link

import type { TentativaDaMensagem } from "termo_core/ai";

export interface TentativaDaMensagem {
  chave: string;
  duracao_ms: number;
  erro: string;
  modelo: string;
  provedor: string;
}