Tolky Features

TolkyFeatures é o catálogo de funcionalidades da plataforma Tolky. O assistente usa esse catálogo para identificar, a partir de uma pergunta em linguagem natural, qual funcionalidade é mais relevante para o contexto do usuário.

​

Esquema do banco

​

Tabela tolky_features

​

Relacionamentos com datasets e chunks

Ao criar uma feature, o sistema provisiona automaticamente:

• Um dataset dedicado (datasets) para isolar o conteúdo da feature do restante da base de conhecimento.
• Um chunk (chunks) com o texto combinado de title, description e long_description, que é vetorizado e indexado para busca semântica.

Ambos são identificados via dataset_id e chunk_id na tabela tolky_features. Esses registros são gerenciados internamente — não devem ser manipulados diretamente via API de datasets ou chunks.

​

Fluxo de dados

flowchart TD
  subgraph Criar
    A[POST /create] --> B[Inserir tolky_features]
    B --> C[Criar dataset dedicado]
    C --> D[Criar chunk com título + descrições]
    D --> E[Gerar embedding e indexar]
  end

  subgraph Atualizar
    F[PUT /update] --> G{Campos de texto\nalterados?}
    G -- sim --> H[Atualizar tolky_features]
    H --> I[Re-gerar embedding do chunk]
    G -- não --> J[Atualizar apenas metadados]
  end

  subgraph Deletar
    K[DELETE /delete] --> L[is_active = false]
    L --> M[Remover chunk do índice semântico]
  end

​

Endpoints disponíveis

• Criar feature — registra uma nova funcionalidade na plataforma
• Listar features — lista funcionalidades com filtros por módulo e status
• Atualizar feature — atualiza dados de uma funcionalidade existente
• Deletar feature — desativa uma funcionalidade e a remove da busca semântica

​

Busca semântica

A busca é feita em dois passos: geração do embedding da consulta e pesquisa por similaridade no índice de features.

async function searchFeatures(query, tolkyAdminToken) {
  const embeddingResponse = await fetch(`${BASE_URL}/api/v4/embeddings/generate`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${tolkyAdminToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ text: query }),
  });

  const { embedding } = await embeddingResponse.json();

  const searchResponse = await fetch(`${BASE_URL}/api/v4/tolkyFeatures/search`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${tolkyAdminToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ embedding, topK: 5 }),
  });

  return searchResponse.json();
}

​

Comportamento de re-embedding

Ao atualizar uma feature, o sistema re-gera o embedding apenas quando campos de texto são alterados:

O re-embedding ocorre de forma síncrona. A atualização só é confirmada após o novo vetor ser indexado com sucesso.

​

Falhas na criação

A criação de uma feature segue um modelo de duas fases:

1. Fase 1 — registro: o registro em tolky_features é inserido com dataset_id e chunk_id como null.
2. Fase 2 — indexação: o dataset e o chunk são criados e o embedding é gerado. Em caso de sucesso, dataset_id e chunk_id são preenchidos.

Se a Fase 2 falhar, o registro em tolky_features permanece com dataset_id e chunk_id como null e a feature não aparece na busca semântica. Nesses casos, exclua a feature e tente criar novamente. A feature sem índice não afeta o funcionamento das demais.

​

Re-ativação

Ao deletar uma feature, o dataset e o chunk associados são removidos do índice semântico, mas os registros em datasets e chunks não são apagados automaticamente.

UPDATE tolky_features
SET is_active = true
WHERE id = '<feature-id>';

-- Re-indexar o chunk associado
SELECT reindex_tolky_feature_chunk('<feature-id>');