Particionar texto

Recebe um texto bruto e devolve blocos temáticos rotulados pela IA — cada bloco é autocontido e pode ser processado separadamente sem perder contexto. Quando options.persistChunks é true, cada bloco é gravado em public.chunks com embedding no dataset escolhido, pronto para RAG.

​

Endpoint

POST /api/externalAPIs/public/smartSplit/partition

​

Parâmetros

​

Exemplos

O único campo obrigatório no body é text. Todos os outros são opcionais.

curl -X POST {{BASE_URL}}/api/externalAPIs/public/smartSplit/partition \
  -H "Authorization: Bearer {{TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Chapter 1. The Beginning.\n\nOnce upon a time in a land far away, a young hero set out on a journey.\n\nChapter 2. The Challenge.\n\nThe road ahead was long. Mountains blocked the path.\n\nChapter 3. The Resolution.\n\nAfter many trials, the hero returned home, forever changed."
  }'

​

Resposta

{
  "success": true,
  "blocks": [
    { "text": "Capítulo 1. O início.\n\nEra uma vez em uma terra distante...", "label": "Capítulo 1 – O início" },
    { "text": "Capítulo 2. O desafio.\n\nO caminho era longo...", "label": "Capítulo 2 – O desafio" },
    { "text": "Capítulo 3. A resolução.\n\nApós muitas provações...", "label": "Capítulo 3 – A resolução" }
  ],
  "coverage": 1.0,
  "totalLines": 9,
  "sessionsUsed": 1,
  "fallbackUsed": false,
  "failedSessions": 0,
  "reasoning": "Agrupado pelos cabeçalhos de capítulo.",
  "auditLog": [
    "[SmartSplit] Iniciando particionamento de texto...",
    "[SmartSplit] Texto dividido em 9 linha(s)",
    "[SmartSplit] 1 sessão(ões) de IA necessária(s)",
    "[SmartSplit] 3 bloco(s) montado(s)",
    "[SmartSplit] Cobertura: 100.0% (9/9)",
    "[SmartSplit] Particionamento concluído com sucesso"
  ],
  "persisted": null,
  "uncoveredLines": { "count": 0, "indices": [], "ranges": [], "lines": [] },
  "costControl": {
    "usage": {
      "inputTokens": 480,
      "outputTokens": 95,
      "totalTokens": 575,
      "isEstimated": false,
      "source": "smart_split_aggregate"
    },
    "cost": {
      "inputCost": 0.000048,
      "outputCost": 0.000038,
      "totalCost": 0.000086,
      "currency": "USD",
      "pricingMissing": false,
      "matchedPricingKey": "openai:gpt-4.1-nano"
    },
    "control": { "decision": "allow", "reasons": [] },
    "references": { "caller": "smartSplit", "provider": "openai", "model": "gpt-4.1-nano" },
    "reconciliation": null
  }
}

​

Campos da Resposta

​

Erros

​

Como funciona

flowchart TD
    client[Cliente] -->|POST /partition| ctrl[PartitionController]
    ctrl --> auth["Autenticação e resolução de hostId/avatarId/datasetId"]
    auth --> media["Resolução de mídias (se mediaUrls fornecido)"]
    media --> preChunk["Pré-chunking se texto > 80k chars"]
    preChunk --> lines["Divisão em linhas (sentence-parse + cap 50 palavras)"]
    lines --> windows["Janelas deslizantes (400 linhas, 30 overlap)"]
    windows --> ia["Sessão de IA por janela"]
    ia -->|0 blocos| fallback["Fallback mecânico (fallbackMaxCharsPerBlock chars/bloco)"]
    ia -->|blocos| assemble
    fallback --> assemble[Montar blocos e validar cobertura]
    assemble -->|persistChunks true| persist["Gerar nome, criar dataset se necessário, gravar chunks"]
    assemble -->|persistChunks false| shape[Shape da resposta]
    persist --> shape
    shape --> client

1. Autenticação e resolução de contexto — o token é decodificado para extrair hostId e userId. Se persistChunks: true, o avatarId e o datasetId são resolvidos (ou derivados do avatar principal) e validados para garantir que pertencem ao host autenticado, bloqueando acesso cross-tenant.
2. Resolução de mídias — quando mediaUrls é fornecido, cada URL (imagem, PDF, áudio, vídeo) é processada via mediaAnalysisV3 e convertida em texto. O resultado é concatenado ao text antes das etapas seguintes.
3. Pré-chunking acima de 80 000 caracteres — textos maiores que options.maxCharsPerChunk (padrão 80 000) são quebrados em sub-textos independentes via cortes em fronteiras naturais (parágrafo → quebra de linha → sentença). Cada sub-texto é processado separadamente e os resultados são mesclados com offset global de linhas.
4. Divisão em linhas — o texto é segmentado via sentence-parse (com observeMultipleLineBreaks: true). Linhas com mais de 50 palavras são subdivididas. Fallback para quebras de linha simples quando a biblioteca não retorna sentenças.
5. Janelas deslizantes — acima de options.maxLinesPerSession linhas (padrão 400), o texto é cortado em janelas sobrepostas com options.overlapLines linhas de overlap (padrão 30) para manter contexto entre bordas.
6. Sessão de IA por janela — cada janela vira uma chamada ao LLM com saída estruturada { blocks: [{ ranges, label }], reasoning }. O modelo retorna ranges inclusivos [start, end] (0-based); a expansão para índices individuais ocorre internamente.
7. Fallback mecânico — se a IA devolver 0 blocos (recusa, parse inválido), a janela é dividida por caracteres até options.fallbackMaxCharsPerBlock (padrão 3 000) com label: null. A resposta sinaliza isso em fallbackUsed e failedSessions.
8. Validação de cobertura — ao final, SmartSplit checa se pelo menos options.minCoverage (padrão 0.90) das linhas foi coberta. Se não, volta success: false com reason: "coverage_below_threshold", missingCount e os blocos parciais. Falhas de cobertura são registradas automaticamente no TypeSense para monitoramento.
9. Persistência opcional — quando persistChunks: true, cada bloco é embeddado com text-embedding-3-large e inserido em public.chunks vinculado ao datasetId. Se o datasetId não foi passado e createDatasetIfMissing: true (padrão), as labels dos blocos alimentam um LLM que gera o nome do novo dataset antes da gravação. O objeto persisted na resposta traz datasetId, avatarId, datasetCreated, datasetName (quando criado), chunkIds e count.