Gerenciar Contextos

Cada domínio de dados da sua operação — processos judiciais, cadastro de empresas, um código legal — vive em um contexto próprio, com seu grafo, seus índices de busca, seus prompts e suas regras. Em vez de abrir chamado para o time de infraestrutura criar bases, você cria, edita, atualiza, limpa, exclui e governa todos os contextos em uma única tela: Sistema›Contextos (screens/settings-contextos.html). São os bancos de contexto da plataforma (processos, cnpj, cpc…) — sempre criados pela interface, nunca pelo setup automatizado.

O que aparece na tela

De cima para baixo:

1. Cabeçalho — o título "Contextos" à esquerda e, no canto superior direito, o botão + Novo Contexto, que abre o formulário "Adicionar Novo Contexto Legal". O cabeçalho se reorganiza sozinho em telas estreitas.
2. Matriz de Visibilidade dos Contextos — a governança de onde cada contexto pode ser usado (resumo abaixo).
3. Configurações por Contexto — um card com a mesma largura da Matriz de Visibilidade, contendo um seletor em lista vertical com uma linha por contexto (o ativo fica destacado), no mesmo desenho das linhas da matriz; a lista mostra até 8 contextos e, acima disso, ganha barra de rolagem vertical. Abaixo dela fica a barra de ações, que opera sempre sobre o contexto ativo do seletor:

1. Seções do contexto ativo — "Schema do Grafo — {contexto}" (estrutura do banco de grafos), "Embeddings — {contexto}" (vetores de busca semântica e modelo ativo) e "Prompts e Regras — {contexto}". A geração de embeddings roda no servidor: a barra geral e os cartões por contexto voltam ao reabrir a tela, em andamento ou já no desfecho — o detalhe fica no cache da plataforma, não na tela que o disparou (veja Embeddings — um campo de vetor por modelo).

O formulário de criação e de edição inclui o bloco "Fontes de dados deste contexto", que permite combinar mais de uma fonte no mesmo contexto — detalhado no guia de contexto multi-fonte —, o bloco "Identificação dos dados" (seção abaixo), o bloco "Função deste contexto" e o bloco "Contextos de regra aplicados na triagem", os dois descritos nas seções seguintes.

O que a criação provisiona

Um contexto só funciona quando existe em três lugares: o banco do grafo (entidades e relações), o índice de busca (texto e vetores) e o Knowledge Catalog (para alguém conseguir encontrá-lo). Salvar o formulário provisiona os três — cada um com uma regra de falha diferente, e todas visíveis:

Por que o banco vem antes do cadastro. Ele era criado depois de o contexto ser gravado, e a falha só ia para o registro técnico: o contexto ficava salvo apontando para um banco que podia não existir, e a tela respondia sucesso. Foi assim que um contexto medido em produção nasceu com banco no ar, índice inexistente, ponteiro de índice vazio e nenhum dataset no catálogo — sem uma única crítica na interface. Agora o banco é pré-condição: se ele não sobe, nada é gravado.

O índice é a exceção deliberada: um contexto recém-criado ainda não tem texto para perder, e o índice se recria depois sem efeito colateral. Por isso a falha dele não derruba o cadastro — mas vira aviso na tela, nunca só registro técnico.

Antes de salvar: a tela diz o que vai criar

No bloco "Fontes de dados deste contexto", quando você não escolhe nenhuma fonte, a plataforma deriva os destinos do nome interno — e agora diz isso antes de você salvar, em âmbar:

"Nenhuma fonte selecionada: a plataforma vai criar o banco Neo4j maira-ctx e o índice de busca datta_mairactx para este contexto."

O aviso informa, não bloqueia: derivar automaticamente é o comportamento desejado — o defeito era ele ser mudo. Se o nome interno ainda estiver em branco, o aviso avisa disso em vez de citar um nome vazio.

Depois de salvar: o relatório de criação

O salvamento abre um cartão "Contexto criado — {rótulo}" que mostra:

• o banco Neo4j e o índice de busca efetivamente provisionados (os valores que o servidor devolveu, não o palpite da tela);
• a lista "Ficou pendente:", com o que foi criado com ressalva — por exemplo, o índice de busca que não subiu, com a frase que diz onde conferir o OpenSearch e como recriá-lo, ou o contexto de processo judicial criado sem a Base do código processual (o "Gerar recurso" dele vai consultar o CPC — veja contexto multi-fonte, seção "Base do código processual"), ou com uma base que ainda não existe no Neo4j (o recurso sai sem artigos e jurisprudência até o banco ser carregado);
• o andamento da carga inicial da legislação, quando você informou uma URL (seção abaixo).

Sem pendência, o cartão é neutro; com pendência ou falha de carga, ele fica em destaque de erro. Esse cartão existe porque "criado com sucesso" e "criado pela metade" eram, até aqui, indistinguíveis na tela.

Recusas na criação

Todas devolvem mensagem em português dizendo o que corrigir, e nada é gravado:

Tipo de contexto e identificação dos dados

O campo Tipo de contexto é obrigatório e diz de que natureza são os dados. As categorias vêm de um catálogo da plataforma — declarar uma categoria nova é cadastro, não mudança de código —, e hoje são:

Quando o tipo escolhido guarda os dados em uma entidade própria, o formulário mostra o bloco "Identificação dos dados" com dois campos obrigatórios:

• Entidade âncora — o nome do nó do grafo que agrega os dados do contexto (maiúscula inicial, no singular: Processo, Empresa, Emprestimo).
• Propriedade identificadora — a propriedade única desse nó. É por ela que a plataforma liga documentos, análises e o fluxo de trabalho ao registro certo (processoNumero, cnpj, numeroPedido).

Os tipos que têm sugestão preenchem os dois campos sozinhos ao serem selecionados; Análise de Crédito não tem sugestão de propósito — pedido de crédito não é número CNJ nem CNPJ, e herdar qualquer um dos dois faria a plataforma procurar a chave onde ela nunca esteve.

Salvar sem esses campos é recusado, com mensagem dizendo o que preencher. A recusa existe porque a falha silenciosa é pior que o erro: contexto sem identificação não quebra — ele passa a procurar tudo como se fossem processos judiciais (:Processo por processoNumero), não encontra nada e não avisa. Foi assim que um contexto de dossiê acabou cadastrado com identificação nula.

Contextos já cadastrados sem identificação continuam funcionando e continuam editáveis: a exigência vale para contexto novo e para quem troca o tipo do contexto. Se você tem um contexto assim, abra-o, preencha os dois campos e salve.

Função deste contexto: quando ele é um corpus de regras

No cadastro, o bloco "Função deste contexto" traz uma única caixa:

☐ Este contexto guarda legislação/normas e serve de corpus de regras para a triagem

Marcá-la faz o contexto novo entrar na lista de corpora de regra visíveis — a mesma lista que alimenta o editor de Regras de Triagem e o bloco "Contextos de regra aplicados na triagem" dos outros contextos. É o que CPC, CPP, CDC e FEBRABAN já são.

Não existe — e não deve existir — um "tipo de contexto" chamado regra. O que faz um contexto ser corpus de regra são duas coisas, e nenhuma delas é a categoria: (a) o nome dele aparecer nas regras escritas para aquele corpus e (b) ele estar na lista de corpora visíveis. A medição sustenta a decisão: FEBRABAN é do tipo Custom e funciona como corpus de regras, com regras próprias em produção; CPC, CPP e CDC são do tipo Código Processual. Criar uma categoria nova para o mesmo conceito daria dois mecanismos divergentes para a mesma pergunta — e o dia em que os dois discordassem, ninguém saberia qual vale.

Duas garantias na gravação, porque as duas falhas seriam silenciosas:

• a lista existente é lida e somada, nunca substituída. Gravar só o nome novo apagaria CPC, CPP, CDC e FEBRABAN de uma vez, com a tela dizendo "sucesso";
• lista vazia não significa "nenhum corpus" — sem itens não há filtro, e todos os contextos já valem como corpus. Gravar [novo] sobre a lista vazia esconderia todos os outros. Nesse caso, nada é gravado.

Se a gravação falhar, o contexto continua criado e o relatório traz a pendência, dizendo onde incluí-lo à mão.

A caixa aparece apenas no cadastro. Na edição ela não existe de propósito: o campo é do cadastro, e exibi-lo na edição coletaria uma escolha que o salvamento descarta — exatamente o tipo de campo mudo que esta revisão eliminou. Para ajustar depois, use a lista de contextos visíveis em Sistema›Regras.

Carga inicial da legislação

O campo "URL de origem dos dados" (antiga "URL da legislação") faz duas coisas. Ele fica salvo no contexto — na edição, volta preenchido, e é o endereço que o botão Atualizar dados usa (seção seguinte). E, quando você o preenche e marca a caixa de corpus de regras, a plataforma dispara a carga inicial contra o contexto que acabou de nascer — nunca contra o contexto ativo da sessão — e acompanha o andamento dentro do próprio cartão de criação, com barra de progresso e a atividade corrente.

A URL precisa começar por http:// ou https://, sem espaços; fora disso o cadastro é recusado com a mensagem do formato esperado. Deixar o campo em branco na edição limpa a origem salva.

O que impede a carga vira aviso no cartão, em vez de silêncio:

Fechar o cartão interrompe apenas o acompanhamento; a carga continua e pode ser acompanhada em Histórico de Execuções.

Contexto de legislação em uma chamada

Um contexto de lei (Lei 9.784, CLT, IN 2110, Decreto 70.235) sempre nasce do mesmo jeito: tipo Código Processual com a opção Legislação Federal, marcado como corpus de regras, com a URL oficial salva como origem, os prompts próprios do contexto e a carga inicial da página. Até 13/09/2026 esses passos eram uma receita que só existia em scripts e na memória de quem opera — e o Captain só conseguia executá-la se você ditasse cada passo.

Agora a receita é uma operação da plataforma, disponível na seção API do portal (referência de endpoints, grupo Usuários, Permissões & Contextos) e, por ela, no Captain: peça "crie o contexto LEI-9784 a partir da URL do Planalto com estes prompts" e ele faz a chamada inteira. O pedido leva:

A ordem é fixa e importa: a opção Legislação Federal é garantida no catálogo de tipos; o contexto é criado pelo mesmo caminho da tela (banco, índice, registro, corpus de regras, catálogo); os prompts são gravados antes da carga, porque a extração de entidades da carga lê o prompt NER do contexto; por fim a carga é disparada e roda em segundo plano — o retorno traz o identificador da tarefa e ela aparece em Atualizar dados e no painel de execuções como "Atualizar dados do contexto".

O que impede uma etapa não some no caminho:

Os scripts criar-contexto-lei-9784.sh e criar-contexto-clt.sh continuam existindo, mas viraram invólucros dessa única chamada: definem a lei, leem os arquivos de prompt e acompanham a carga; a receita mora na plataforma.

O criar-contextos-leis-trabalhistas.sh segue o mesmo molde para três leis trabalhistas avulsas, um contexto por lei, criados em sequência:

Ele aceita as mesmas opções dos demais (--conferir, --sem-carga, --sem-acompanhar) e para na primeira lei que falhar. Antes do primeiro cadastro, confere que os 11 prompts de cada lei existem e não estão vazios; se faltar algum, não cria nada — contexto criado com os prompts embutidos não se corrige rodando de novo, só regravando cada prompt em Sistema → IA. Rodado de novo, ele pula o contexto que já existe e só cria o que ainda não existe; não refaz carga que falhou. Se o contexto foi criado e a carga falhou ou não terminou (código de saída 3), refaça-a em Atualizar dados. Os prompts de cada lei vêm da pasta de prompts do repositório, uma subpasta por contexto; PROMPTS_BASE troca a pasta-mãe quando o script roda fora do repositório. Como nos demais contextos de lei, os dispositivos têm o prefixo LEI e o artigo com letra depois do ordinal vira identificador próprio (Art. 2º-C → LEI_ART_2_C).

Para fazer o release e criar as três leis num só comando, disparado da máquina de operação, use o release-com-contextos-leis-trabalhistas.sh. Ele confere o token de admin antes de começar (vencido ou sem o papel ADMIN, para na hora), roda o release completo, espera a subida dos serviços de configuração, prompts e documentos, confere que o serviço de documentos já traz o estruturador que separa os artigos com letra, copia os scripts e os prompts para um diretório temporário no servidor, cria e carrega as três leis e mostra o resultado com --conferir. O token fica num arquivo local com permissão 600, indicado em DATTA_JWT_FILE; ele não é gravado no servidor.

DATTA_JWT_FILE=~/datta.jwt ./scripts/release-com-contextos-leis-trabalhistas.sh

Use --sem-release quando a plataforma já estiver na versão certa, --conferir para só ver o que existe e --sem-carga para criar sem carregar o texto. O que vier depois de -- vai para o script de release.

Atualizar dados a partir da URL de origem

Contextos de legislação e jurisprudência (CPC, CPP, CDC, Lei 9.784, IN 2110…) nascem de uma página oficial e mudam quando ela muda. Em vez de lembrar o endereço e refazer a carga em Processar›Upload, use o botão Atualizar da barra de ações, em Configurações por Contexto:

1. Selecione o contexto no seletor.
2. Confira, em Editar, o campo URL de origem dos dados — é ele que será usado. Sem URL salva, com mais de uma origem de dados ou sem a permissão de carga por URL, as ações pela URL ficam desabilitadas e o modal diz o motivo.
3. Clique em Atualizar. Abre o modal "Atualizar dados — {contexto}", que mostra a URL de origem e oferece duas ações:
   • Atualizar agora — dispara a mesma ingestão por URL da aba URL do Upload, contra este contexto e com a opção de atualizar toda a base ligada: dispositivos alterados ganham a redação nova, os que não mudaram são mantidos.
   • Agendar — abre o editor de agendamento da plataforma (o mesmo da aba URL e da triagem em lote): uma vez, a cada N horas, diária, semanal ou mensal, com as próximas execuções calculadas pelo servidor. Quem dispara é o Datta Scheduler, com a mesma carga do botão "Atualizar agora". Exige a permissão DOCUMENT_SCHEDULE.
4. A barra de andamento aparece dentro do próprio modal, com a atividade corrente, a URL de origem e o botão Cancelar. Ao terminar, mostra quantos documentos foram carregados; se falhar, a mensagem em português e Tentar novamente. Fechar o modal não interrompe a atualização: o botão da barra de ações fica em "Atualizando dados…" e reabri-lo volta ao acompanhamento.
5. Em Re-ingerir a partir do grafo, as opções Incremental e Completa refazem a legislação e a jurisprudência que já estão no grafo do contexto (pelo endereço gravado em cada lei), com relatório de diferenças e drift semântico — o antigo par "Atualizar"/"Completa" da barra. Elas não usam a URL de origem: um contexto ainda vazio termina com "Nenhuma legislação encontrada", e o caminho certo é Atualizar agora.
6. Abaixo, o modal lista as atualizações agendadas deste contexto, com a próxima execução e os botões Editar, Pausar / Retomar e Remover — o que já foi carregado é sempre preservado.

Contextos criados antes da URL de origem. Os contextos de lei cadastrados antes de 03/09/2026 nasceram sem URL salva. O script scripts/preencher-source-url-contextos.py preenche o campo a partir do manifesto da base legal do PAF e dos source_url.txt dos prompts, e o seed seed-contextos-base-legal-paf.sh passou a gravá-la no cadastro.

Planalto só responde a navegador. O portal do Planalto não entrega a página a cliente HTTP comum (a resposta simplesmente não vem). Por isso a carga de legislação busca a página com um navegador real (Chromium via Playwright, o mesmo da carga do CPC), e só cai no HTTP simples se o navegador falhar. O portal de normas da RFB é lido pela API dele, sem navegador.

A execução é assíncrona: sair da tela não a interrompe. Ela aparece no painel Execuções em segundo plano do console como "Atualizar dados do contexto — {contexto}", e clicar nela volta para esta tela, já no contexto certo e com a barra religada de onde a execução está.

Só para contexto com uma única origem de dados. Contextos que reúnem vários bancos Neo4j — um por origem, como o FEBRABAN (CVM, BCB, base negativa) — não têm uma URL que represente "os dados do contexto". Neles o botão aparece desabilitado, e passar o mouse explica: o contexto possui mais de uma origem de dados. Cada origem se atualiza pela carga correspondente no DATTA Extract.

As ações pela URL exigem a permissão DOCUMENT_UPLOAD (a mesma da aba URL do Upload); sem ela, ficam desabilitadas com o aviso da permissão. Os agendamentos criados aqui são os mesmos que aparecem em Cargas de URL agendadas na aba URL do Upload — veja carga de URL agendada para o detalhe das repetições.

Contextos de regra aplicados na triagem

Este bloco é o inverso do anterior: lá o contexto é o corpus; aqui ele consome corpora de outros. São eixos independentes — um contexto de acervo consome CPC e CDC sem ser corpus de nada; um contexto de legislação é corpus e normalmente não consome ninguém.

Logo abaixo das fontes de dados, o formulário traz o bloco "Contextos de regra aplicados na triagem": uma lista de caixas de seleção com os contextos de regra disponíveis (os mesmos que aparecem no editor de Regras de Triagem, com o mesmo rótulo). Ele responde a uma pergunta que o contexto de dados sozinho não responde:

São eixos independentes, e por isso são campos diferentes. Um mesmo acervo pode ser julgado por mais de um código (um contexto cível com relações de consumo declara CPC e CDC), e o mesmo código serve vários acervos. Marque um ou mais: a triagem avalia a união das regras de todos os marcados, sem repetir a regra que pertence a mais de um código.

O que a tela mostra conforme a seleção:

O último caso importa: se um contexto de regra é removido ou renomeado depois de já ter sido declarado, ele continua visível para você poder desmarcá-lo. Sem isso, o valor ficaria invisível na tela e a gravação passaria a falhar com "contexto inexistente" sem causa aparente.

Salvar manda a lista completa. Desmarcar tudo e salvar limpa a configuração — e a triagem desse contexto passa a recusar. Não é um efeito colateral: é a única forma explícita de voltar ao estado "não declarado".

Contexto de regra inexistente é recusado na gravação, com mensagem em português listando os disponíveis. A ordem importa: o primeiro contexto marcado é o primário e governa os prompts, a jurisprudência consultada e o rótulo que aparece no laudo; as regras vêm de todos.

A configuração é lida a cada execução da triagem — alterar aqui e disparar a triagem em seguida já usa o valor novo, sem reiniciar nada e sem esperar.

O que acontece quando um contexto não declara nada

A triagem recusa e diz o que fazer, em vez de adivinhar: cada processo aparece no acompanhamento em vermelho com o motivo "O contexto '{nome}' não declara quais contextos de regra se aplicam a ele. Abra Sistema > Contextos > Gerenciar, edite o contexto e preencha 'Contextos de regra aplicados na triagem'; depois repita a triagem." Nenhuma análise de IA é consumida.

Por que recusar. Até 08/08/2026 a plataforma inferia o código aplicável por palavras soltas no texto dos autos. Medido em produção: um processo cível de cumprimento de sentença contra a Fazenda Pública foi mandado para um código que não existe nesta plataforma — herança de um projeto anterior que sobreviveu no código — porque a palavra "administrativo" aparecia em ementas citadas nos autos. O laudo saía "concluído" com zero regras avaliadas, indistinguível de um processo realmente auditado. Os três códigos que a plataforma realmente tem, medidos na mesma data: CPC com 1.076 regras, CPP com 748 e CDC com 106.

Trocar a inferência por configuração fecha os dois lados: o valor errado é recusado na hora de salvar, e o valor ausente é anunciado na hora de triar.

Se você editou contextos antes de 08/08/2026

Até essa data havia um defeito no salvamento: toda edição de contexto apagava em silêncio três configurações que não estavam no formulário — o modelo de raciocínio do contexto, o rótulo do identificador e o contexto de regra fixo. A mesma perda acontecia ao aplicar um modelo de raciocínio a todos os contextos de uma vez.

Ninguém percebia porque a leitura devolvia o valor já resolvido, com o padrão derivado do tipo do contexto: o campo zerado continuava parecendo preenchido. Se você editou contextos antes dessa data, vale abrir cada um e conferir o modelo de raciocínio e o rótulo do identificador — e, agora, marcar os contextos de regra.

Matriz de Visibilidade dos Contextos

A matriz mapeia em quais funcionalidades os dados de cada contexto podem ser utilizados: uma linha por contexto cadastrado e seis colunas de caixa de seleção — Painel de Regras, Upload PDF, Upload URL, DATTABI, DATTA Extract e Ontologia. A tabela é montada a partir de um catálogo de funcionalidades no próprio frontend, então uma coluna nova aparece sem mudança de layout.

• Lista vazia = todos os contextos visíveis: desmarcar tudo numa coluna volta ao comportamento de todos visíveis — não há como o administrador se "trancar" para fora.
• Persistência imediata: cada clique grava na hora e sobrevive a recarregar a página. A coluna Painel de Regras ainda avisa as telas de regras já abertas, que recarregam a lista de contextos em tempo real.
• Funcionalidades reconhecidas: a gravação genérica aceita apenas dattabi, extract e ontology; uma funcionalidade desconhecida é recusada com mensagem de erro em português.
• Carregamento em paralelo: as seis colunas são buscadas ao mesmo tempo na montagem da página, e não uma após a outra.

Onde cada preferência é guardada:

A leitura e a gravação de cada coluna também estão disponíveis para integrações — veja a referência de API.

Até onde a visibilidade é aplicada hoje

A matriz é visibilidade de interface e governança, não uma lista de controle de acesso a dados por contexto no servidor. Para restringir quem acessa o quê, use as roles e permissões.

Exemplo prático — criar um contexto do zero

Sua equipe vai passar a triar processos de consumo e precisa de um contexto próprio, separado do cível:

1. Em Sistema›Contextos, clique em + Novo Contexto.
2. No formulário "Adicionar Novo Contexto Legal", preencha os dois nomes (veja Nome interno vs. rótulo logo abaixo) e a descrição: o Nome interno (ex.: Consumidor) e o Rótulo de exibição (ex.: "Código de Defesa do Consumidor").
3. No bloco "Fontes de dados deste contexto", marque as bases que ele usa.
4. No bloco "Contextos de regra aplicados na triagem", marque CDC — e também CPC, se o acervo tiver processos cíveis comuns. A tela confirma embaixo: "A triagem vai avaliar a união das regras de 2 contextos: CPC, CDC." Em "Função deste contexto", deixe a caixa desmarcada: este contexto guarda processos, ele não é um corpus de normas.
5. Se você não escolheu fontes, confira o aviso em âmbar com o banco e o índice que serão criados. Salve.
6. Leia o cartão "Contexto criado": ele mostra o banco e o índice provisionados e, se houver, a lista "Ficou pendente:". Sem pendências, o contexto já aparece no seletor — pronto para receber ingestão.
7. Na Matriz de Visibilidade, marque em quais telas ele deve aparecer (ex.: apenas Painel de Regras e Upload PDF, enquanto estiver em piloto).

Descrição do contexto

O campo "Descrição do contexto" do formulário é opcional e fica gravado no contexto: a edição reabre com o texto salvo, e as integrações o leem no campo description da consulta do contexto. Até 27/09/2026 o texto era descartado em silêncio — a tela o enviava, o servidor não o guardava e a edição voltava com o campo vazio.

A descrição também vai para o grafo de sistema da plataforma — a propriedade descricao do nó do contexto no banco datta (e na réplica do banco de auditoria):

Na edição, deixar o campo como veio preserva a descrição; apagar o texto e salvar limpa. A descrição automática também é recalculada sempre que o serviço de configuração sobe, então um contexto que mudou de rótulo antes desta correção passa a mostrar o rótulo certo sem precisar ser editado.

A descrição digitada também pesa no chat. Numa pergunta que consulta vários contextos, o chat compara a pergunta com um texto que descreve cada contexto (rótulo, tipo, descrição e fontes) e dá até 40% a mais de pontuação aos resultados do contexto mais parecido. Uma descrição que fala de "empresas e sócios" puxa o contexto para cima em perguntas de CNPJ, mesmo que ele guarde processos — descreva o que o contexto contém. Esse texto fica guardado por até 24 horas: a troca da descrição (como a do rótulo, do tipo ou das fontes) leva até esse tempo para mudar a ordem das respostas.

Nome interno vs. rótulo

Todo contexto tem dois nomes, e a distinção importa no dia em que você for operar a plataforma por API.

Onde encontrá-lo: abra Editar no contexto. O bloco "Nome interno", em fonte monoespaçada e com botão de copiar, é a chave que a API espera.

Renomear o nome interno

O nome interno é editável no mesmo formulário de Editar. Ele não é um rótulo: fica gravado no campo domain de cada trecho indexado, no nome dos índices de busca do contexto e em toda integração externa que já o referencie. Por isso salvar um nome novo dispara uma migração — a tela pede confirmação e descreve o que vai acontecer antes de gravar.

O que a plataforma move sozinha, no próprio salvamento:

• Os índices OpenSearch do contexto — texto, vetores e histórico de chat — passam para o nome novo numa troca atômica, os dois juntos. Por alguns segundos eles ficam bloqueados para escrita; a plataforma cria uma cópia idêntica de cada um (os mesmos campos, os mesmos vetores, a mesma compressão), confere que a cópia tem os mesmos documentos — no total e em cada campo de vetor — e troca os nomes de uma vez. O que chega nesses segundos (uma resposta do chat guardada na memória, um trecho indexado) espera a troca terminar e entra no índice novo: nada se perde.
• O nome antigo continua funcionando como apelido (alias) do índice novo. O chat, que ainda usa o nome antigo por alguns minutos, uma aba aberta antes da renomeação e uma carga em andamento continuam lendo e gravando no lugar certo.
• O campo domain de cada documento passa para o nome novo logo depois, em segundo plano. Numa versão do OpenSearch que não regrava com segurança documento com vetor comprimido, o relatório avisa e o campo fica com o nome antigo — a busca não depende dele, só a origem exibida num resultado. O mesmo vale para o que for gravado depois pelo nome antigo.
• Os prompts do contexto (índice datta_prompts).
• O nó :Contexto nos bancos de sistema datta e datta-audit-db.
• O contexto ativo, as três listas globais da Matriz de Visibilidade (Painel de Regras, Upload PDF, Upload URL) e as das demais funcionalidades.
• Os workspaces que incluem o contexto.
• Os contextos de regra dos outros contextos que apontam para este.
• Os datasets no Knowledge Catalog, que passam a listar o nome novo. Sem esse reaponte, o mesmo dataset apareceria duas vezes na busca do catálogo — uma sob cada nome —, porque o novo scan publica a entrada nova sem apagar a antiga.
• Os modelos e as instâncias de processo BPM do contexto. Sem isso, todo modelo do contexto viraria órfão de uma vez (é o mesmo estado que a validação de contexto na criação do modelo existe para impedir) e as instâncias deixariam de resolver responsável, título e enriquecimento.

O que não muda: o banco Neo4j do contexto. Ele é um valor gravado, não derivado do nome, então o grafo continua exatamente onde estava — o exemplo do "Cuidado" abaixo segue valendo depois de renomear.

O que fica com você:

• Toda integração externa que chama a API com ?domain=<nome antigo> precisa passar a usar o nome novo. A plataforma não tem como descobrir quem são esses chamadores; o relatório exibido ao fim da renomeação lembra disso.

Recusas conhecidas — em todas elas nada é alterado e o contexto continua íntegro sob o nome atual:

• Nome já usado por outro contexto.
• Nome que colidiria no índice de outro contexto. O nome do índice descarta hífen, underscore e acento (datta_{apenas letras e números}), então base-negativa e base_negativa disputariam o mesmo datta_basenegativa, e os dois contextos passariam a gravar no mesmo lugar. Escolha um nome que difira por letras ou números.
• Nome cujo índice cairia num índice de sistema da plataforma (rum, prompts, glossaryTermos…) — a mesma recusa da criação, com a mensagem nomeando o índice de sistema em conflito.
• Já existe conteúdo no índice do nome novo (por exemplo, o histórico do chat de um contexto antigo que tinha esse nome). Renomear por cima misturaria os dois.
• Outra renomeação do mesmo contexto, a exclusão dele ou a manutenção do histórico do chat em andamento. Aguarde terminar e salve de novo.
• Falha ao mover os índices (OpenSearch fora do ar, por exemplo). A plataforma desfaz a renomeação antes de responder — apaga as cópias parciais e devolve a escrita aos índices — e nenhuma configuração é gravada: os dados continuam intactos sob o nome antigo e a operação pode ser repetida. Se a reversão não terminar, a mensagem diz exatamente o que sobrou.

Quando o índice do contexto mora num servidor de dados externo, ele é movido lá mesmo, e o histórico do chat continua no servidor da plataforma. As duas trocas acontecem em sequência; se a segunda falhar, a mensagem diz o que já mudou de nome e o que ficou — nada se perde, o nome interno não é alterado, e salvar de novo conclui o que faltou.

Se a resposta não chegar a tempo, a mensagem diz que o estado dos índices é incerto: o nome interno não foi alterado, o nome atual continua levando ao conteúdo, e a renomeação pode ser repetida — ela reconhece o que já foi movido e só conclui o que faltou.

A troca leva segundos mesmo em contextos grandes: a cópia não regrava documento por documento.

Renomear de volta para um nome que o contexto já teve funciona: o apelido antigo é reaproveitado. E criar um contexto novo com o nome antigo de outro também: o contexto novo retoma o nome, e o apelido deixa de levar ao conteúdo do contexto renomeado.

Cuidado. O nome interno não é o nome do banco de dados. No contexto Processos, por exemplo, o banco chama-se processotributario e o rótulo é "Processo Tributario" — três strings distintas, e só a primeira funciona em ?domain=. Passar o nome do banco faz o endpoint responder que o contexto não foi encontrado.

Substituições aprendidas

Cada contexto guarda o que o chat aprendeu com as pessoas que o usam:

• Entidade ausente confirmada — a pergunta citou uma entidade que o modelo de dados não tem ("contador") e a pessoa confirmou usar a mais próxima ("Pessoa"). O par é sugerido nas próximas perguntas, mas a confirmação continua obrigatória a cada vez: trocar a entidade muda a pergunta. A recusa também conta, como sinal contrário.
• Sinônimo de propriedade — um termo da pergunta que corresponde a uma propriedade do modelo de dados com outro nome ("razão social" → Empresa.empresaNome). Vale por padrão, sem pergunta: é interpretação, não troca.

A seção Substituições aprendidas no detalhe do contexto lista os pares com o tipo, quantas vezes foram confirmados, recusados ou usados, e a última decisão. Todo par é validado contra o esquema atual do grafo do contexto: se o label ou a propriedade deixou de existir, o par aparece como obsoleto e não é mais sugerido ao chat. Com permissão de edição de configuração é possível adicionar um par à mão (o alvo tem de existir no esquema; para propriedade, na forma Label.propriedade) e esquecer qualquer par. Adicionar e esquecer ficam na trilha de auditoria, e o chat passa a refletir a mudança em até 15 minutos (é o prazo do cache dos pares).

Os pares pertencem ao contexto: contexto novo, com outro modelo de dados, nasce sem nenhum e aprende com o uso. Eles não são compartilhados entre contextos e somem quando o contexto é excluído.

Quem pode usar

• Ver a tela, a matriz e as listas: CONFIG_VIEW.
• Alterar a matriz e as configurações por contexto: CONFIG_EDIT.
• Limpar dados: CONTEXT_PURGE (permissão sensível) — veja limpar dados de um contexto.
• Disparar a carga inicial da legislação junto com a criação: DOCUMENT_UPLOAD. Sem ela o contexto é criado normalmente e o cartão avisa que a carga não foi disparada.
• Criar um contexto de legislação em uma chamada: CONFIG_EDIT para o cadastro, e a chamada usa a sua identidade nas etapas seguintes — PROMPT_EDIT para os prompts e DOCUMENT_UPLOAD para a carga. O que a sua permissão não cobre volta como aviso, nunca em silêncio.

Como conceder cada uma está no guia de roles e permissões.

Histórico de UX

• 2026-06-11 — o botão "+ Novo Contexto" subiu para o cabeçalho da página (antes ficava no meio, junto ao seletor); o botão de edição passou a exibir apenas "Editar" (antes repetia o nome do contexto ativo, ex. "Editar PROCESSOS"); a Matriz de Visibilidade foi removida por se entender que os workspaces cobririam a visibilidade.
• 2026-06 — a Matriz de Visibilidade voltou a pedido do usuário, agora montada a partir do catálogo de funcionalidades e ampliada com DATTABI, DATTA Extract e Ontologia. O cabeçalho com "+ Novo Contexto" e o rótulo "Editar" da mudança anterior permanecem.
• 2026-09-27 — o formulário de edição abre vazio e com o Salvar desabilitado ("Carregando...") até os dados do contexto chegarem; se eles não chegam, a mensagem em vermelho diz o motivo e o Salvar continua desabilitado — feche e abra a edição de novo. Cancelar e o X limpam o formulário, e a resposta de um contexto que você já fechou é descartada. Antes, abrir outro contexto logo depois de fechar um mostrava os campos do anterior, e salvar ali gravava os dados de um contexto por cima de outro. Na mesma data a descrição passou a ser gravada, e a edição passou a mostrar os avisos do salvamento (ex.: processo judicial sem a Base do código processual, ou base que não existe no Neo4j) numa notificação. Uma edição que troca o nome interno e traz uma Base do código processual inválida passou a ser recusada antes da troca — antes o contexto era renomeado, as demais alterações se perdiam e o Salvar seguinte respondia "Contexto não encontrado".

Documentos relacionados

• Contexto multi-fonte — fontes de dados heterogêneas por contexto.
• Limpar dados de um contexto — esvaziar o conteúdo mantendo o contexto.
• Matriz de Visibilidade dos Contextos — governança de visibilidade por funcionalidade, em detalhe.
• Triagem em Lote — onde os contextos de regra configurados aqui são aplicados.
• Nomes de bancos no grafo — bancos de sistema versus bancos de contexto.
• Provisionamento de contexto — a ordem, os contratos e as limitações conhecidas do que a criação provisiona (leitura restrita).