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}".

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;
• 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 da legislação" deixou de ser decorativo. Quando você o preenche e marca a caixa de corpus de regras, a plataforma dispara a carga 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.

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.

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).

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 — são copiados para os índices do nome novo, com o campo domain de cada documento reescrito, e os índices antigos são removidos só depois da cópia fechar sem falhas.
• 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 — nos dois casos 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.
• Falha ao mover os índices (OpenSearch fora do ar, por exemplo). A renomeação é abortada antes de qualquer gravação de configuração: os dados continuam intactos sob o nome antigo e a operação pode ser repetida.

Em contextos grandes a cópia dos índices leva alguns minutos e a janela precisa ficar aberta até o fim.

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.

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.

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.

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).