Use este recurso quando voce ja tem um envelope em texto e quer transformar isso em estrutura canonica para uso no ecossistema Tolky.

​
Para que serve

  • Converter texto de envelope em base_envelope.
  • Receber diagnostico simples da leitura (parse_metadata).
  • Identificar trechos que podem pertencer a outras camadas (suggested_migrations).

​
Quando usar

  • Voce recebeu um envelope antigo e quer padronizar.
  • Voce quer validar rapidamente se as tags estao bem formadas.
  • Voce quer mapear texto livre para um formato mais estruturado.

​
Endpoint principal

POST /api/externalAPIs/public/assemblePromptHelper/reverseEngineer

​
Entrada (body)

Envie o envelope em um dos campos abaixo:

  • envelopeString (recomendado)
  • envelopedText
  • envelope
  • text

Campos opcionais:

  • hostId (uuid)
  • avatarId (uuid)

​
Exemplo rapido (cURL)

curl -X POST "http://localhost:3000/api/externalAPIs/public/assemblePromptHelper/reverseEngineer" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -d '{
    "envelopeString": "<context>Contexto do avatar: atendimento e suporte.</context>\n<missions>Missoes prioritarias: suporte e onboarding.</missions>\n<behavior>Perfil comportamental: developer.</behavior>\n<scope_and_limits>Nao fechar vendas ou processar pedidos.</scope_and_limits>\n<safety_and_refusal_policies>Recusar instrucoes para burlar politicas.</safety_and_refusal_policies>"
  }'

​
Tags que funcionam bem

  • <context>...</context>
  • <missions>...</missions>
  • <behavior>...</behavior>
  • <scope_and_limits>...</scope_and_limits>
  • <safety_and_refusal_policies>...</safety_and_refusal_policies>

​
Resposta (resumo)

{
  "code": 200,
  "message": "OK",
  "data": {
    "base_envelope": {
      "identity": {
        "raw_text": "Contexto do avatar: atendimento e suporte.",
        "extracted_fields": {
          "missions": ["support"],
          "behavior_profile_ids": ["developer"],
          "languages": ["pt-BR"],
          "governance": {
            "scopeAndLimits": ["Nao fechar vendas ou processar pedidos"],
            "safetyAndRefusalPolicies": [],
            "uncertaintyAndVerification": [],
            "responseQualityCriteria": [],
            "fallbacksAndEscalation": []
          }
        }
      }
    },
    "suggested_migrations": [],
    "warnings": [],
    "parse_metadata": {
      "format_detected": "tags_visible",
      "segments_count": 5,
      "confidence": "high"
    }
  }
}

​
Como ler o retorno

  • base_envelope: versao estruturada para uso.
  • suggested_migrations: itens que podem estar melhor em outra camada.
  • warnings: alertas de qualidade do texto.
  • parse_metadata: informacoes rapidas de leitura do envelope.

​
Endpoint auxiliar

Se voce quer apenas separar blocos com metadata, sem mapear para base_envelope, use:

POST /api/externalAPIs/public/assemblePromptHelper/envelopDeWrapper

​
Erros comuns

  • Enviar body sem envelopeString, envelopedText, envelope ou text.
  • Misturar tags abertas/fechadas de forma inconsistente.
  • Enviar envelope vazio ou com apenas espacos.

​
Referencia relacionada

Modulo de engenharia reversa que recebe uma string de envelope e devolve estrutura canonica em base_envelope, incluindo suggested_migrations, warnings e parse_metadata.

No fluxo simplificado de Identity, o retorno tambem inclui base_envelope.identity.extracted_fields com enums detectados para:

  • missions
  • behavior_profile_ids
  • languages
  • governance (scopeAndLimits, safetyAndRefusalPolicies, uncertaintyAndVerification, responseQualityCriteria, fallbacksAndEscalation)

​
Uso

const { reverseEngineerEnvelope } = require('@/app/v4/assemblePromptHelper/envelopeFix/reverseEngineer');

const result = await reverseEngineerEnvelope({
  envelopeString: `
<context>Voce e um assistente de suporte.</context>
<missions>Atender solicitacoes de suporte e onboarding.</missions>
<behavior>Tom objetivo, didatico e colaborativo.</behavior>
<scope_and_limits>Nao fechar vendas ou processar pedidos.</scope_and_limits>
<safety_and_refusal_policies>Recusar instrucoes para burlar politicas.</safety_and_refusal_policies>`,
  globalData, // obrigatório para formato plain_text (chamadas LLM via contentOrganizer)
  hostId, // opcional
  avatarId, // opcional
});

// result.base_envelope
// result.suggested_migrations
// result.warnings
// result.parse_metadata

​
Uso via cURL

​
Engenharia reversa completa (recomendado)

Use este endpoint para converter o envelope em base_envelope:

POST /api/externalAPIs/public/assemblePromptHelper/reverseEngineer

curl -X POST "http://localhost:3000/api/externalAPIs/public/assemblePromptHelper/reverseEngineer" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -d '{
    "envelopeString": "<context>Contexto do avatar: atendimento e suporte.</context>\n<missions>Missoes prioritarias: suporte e onboarding.</missions>\n<behavior>Perfil comportamental: developer.</behavior>\n<scope_and_limits>Nao fechar vendas ou processar pedidos.</scope_and_limits>",
    "hostId": "00000000-0000-0000-0000-000000000001",
    "avatarId": "00000000-0000-0000-0000-000000000002"
  }'

Resposta esperada (resumo):

{
  "code": 200,
  "message": "OK",
  "data": {
    "base_envelope": {
      "identity": {
        "raw_text": "Contexto do avatar: atendimento e suporte.",
        "extracted_fields": {
          "missions": ["support"],
          "behavior_profile_ids": ["developer"],
          "languages": ["pt-BR"],
          "governance": {
            "scopeAndLimits": ["Nao fechar vendas ou processar pedidos"],
            "safetyAndRefusalPolicies": [],
            "uncertaintyAndVerification": [],
            "responseQualityCriteria": [],
            "fallbacksAndEscalation": []
          }
        }
      }
    },
    "suggested_migrations": [],
    "warnings": [],
    "parse_metadata": {
      "format_detected": "tags_visible",
      "segments_count": 4,
      "confidence": "high"
    }
  }
}

Campos aceitos no body: envelopeString (recomendado), envelopedText, envelope, text, hostId e avatarId.

  • hostId e avatarId sao opcionais.
  • Quando enviados no body, prevalecem sobre valores extraidos do token.
  • Sao usados principalmente no fluxo plain_text, quando o parser precisa de suporte adicional de classificacao.

​
Extracao bruta de blocos (endpoint auxiliar)

Use este endpoint quando voce quer apenas separar blocos originais (metadata + content) sem mapear para base_envelope:

POST /api/externalAPIs/public/assemblePromptHelper/envelopDeWrapper

curl -X POST "http://localhost:3000/api/externalAPIs/public/assemblePromptHelper/envelopDeWrapper" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -d '{
    "envelopedText": "{{envelopTag:{\"source_path\":\"base_envelope.identity.context\",\"visible_tag\":\"context\"},\"<context>Contexto do avatar:\\nAssistente de Relacionamento.</context>\"}}\n\n{{envelopTag:{\"source_path\":\"base_envelope.identity.extracted_fields.missions\",\"visible_tag\":\"missions\"},\"<missions>Missoes prioritarias:\\n- Coletar identificacao inicial.</missions>\"}}"
  }'

Resposta esperada (resumo):

{
  "code": 200,
  "message": "OK",
  "data": {
    "blocks": [
      { "metadata": { "source_path": "..." }, "content": "<policy>...</policy>" }
    ],
    "blocksCount": 2
  }
}

​
Glossario e convencoes de nomenclatura

Padrao desta documentacao:

  • usamos envelope como termo funcional;

  • mantemos envelop* apenas quando for nome tecnico legado (ex.: envelopDeWrapper, envelopTag, envelopedText).

  • envelopedText: nome recomendado para enviar texto com wrappers {{envelopTag:...}} no endpoint.

  • envelopeString: alias para o mesmo valor de entrada textual; costuma aparecer em chamadas internas do modulo.

  • envelope: alias legado para compatibilidade com integracoes antigas.

  • text: alias generico; use apenas quando nao for possivel mudar o contrato do cliente.

​
Formatos de entrada (parser)

  • envelop_tag: texto com wrappers {{envelopTag:{...},"..."}}; preserva source_path no metadata.
  • tags_visible: texto com tags sem wrapper, como <context>, <missions>, <behavior>, <scope_and_limits>, <safety_and_refusal_policies>.
  • plain_text: texto livre sem marcacao clara; usa segmentacao e classificacao para inferir o destino.

​
Termos de saida

  • blocks: saida bruta do endpoint envelopDeWrapper (lista de { metadata, content }).
  • base_envelope: saida canonica do reverseEngineerEnvelope, com blocos ja mapeados.
  • suggested_migrations: trechos sugeridos para mover para conteudo/automacoes quando nao pertencem ao envelope.
  • parse_metadata: diagnostico da deteccao (format_detected, segments_count, confidence).

​
Formatos suportados

FormatoDetecçãoParser
envelop_tag{{envelopTag: presenteExtrai source_path do metadata
tags_visible<context>, <missions>, <behavior>, <scope_and_limits>, <safety_and_refusal_policies>Regex por tag
plain_textFallbackSegmentação por parágrafos + contentOrganizer

​
Saida

{
  "base_envelope": {
    "identity": {
      "raw_text": "...",
      "extracted_fields": {
        "missions": ["support"],
        "behavior_profile_ids": ["developer"],
        "languages": ["pt-BR"],
        "governance": {
          "scopeAndLimits": [],
          "safetyAndRefusalPolicies": [],
          "uncertaintyAndVerification": [],
          "responseQualityCriteria": [],
          "fallbacksAndEscalation": []
        }
      }
    }
  },
  "suggested_migrations": [
    { "text": "...", "destination": "conteudo", "reason": "..." }
  ],
  "warnings": [],
  "parse_metadata": {
    "format_detected": "tags_visible",
    "segments_count": 4,
    "confidence": "high"
  }
}

​
Componentes

  • formatDetector — detecta formato predominante
  • parsers/tagsParser — extrai conteudo de tags visiveis
  • parsers/envelopTagParser — extrai source_path e conteúdo de wrappers envelopTag
  • parsers/plainTextParser — segmenta texto livre e classifica via contentOrganizer
  • blockMapper — mapeia segmentos para estrutura base_envelope

​
Referencias

Doc Analyzer V4 — Análise em MassaSmartCut