Managing Contexts

Each data domain in your operation — court cases, company registries, a legal code — lives in its own context, with its graph, its search indices, its prompts and its rules. Instead of filing a request for the infrastructure team to create databases, you create, edit, update, clear, delete and govern every context from a single screen: Sistema›Contextos (screens/settings-contextos.html). These are the platform's context databases (processos, cnpj, cpc…) — always created through the interface, never by the automated setup.

What you see on the screen

Top to bottom:

1. Header — the "Contextos" title on the left and, in the top-right corner, the + Novo Contexto button, which opens the "Adicionar Novo Contexto Legal" form. The header reflows on its own for narrow screens.
2. Context Visibility Matrix — the governance of where each context may be used (summary below).
3. Per-context settings — a card with the same width as the Visibility Matrix, holding a vertical-list selector with one row per context (the active one is highlighted), matching the matrix row design; the list shows up to 8 contexts and grows a vertical scrollbar past that. Below it sits the action bar, which always operates on the active context of the selector:

1. Active-context sections — "Schema do Grafo — {context}" (structure of the graph database), "Embeddings — {context}" (semantic search vectors and active model) and "Prompts e Regras — {context}".

The create and edit form includes the "Fontes de dados deste contexto" block, which lets you combine more than one source in the same context — detailed in the multi-source context guide —, the "Identificação dos dados" block (section below), the "Função deste contexto" block and the "Contextos de regra aplicados na triagem" block, both covered in the next sections.

What creating a context provisions

A context only works once it exists in three places: the graph database (entities and relationships), the search index (text and vectors) and the Knowledge Catalog (so anyone can find it). Saving the form provisions all three — each with a different failure rule, and all of them visible:

Why the database comes before the registration. It used to be created after the context was stored, and the failure only reached the technical record: the context was saved pointing at a database that might not exist, and the screen answered success. That is how a context measured in production was born with its database up, no index, an empty index pointer and no dataset in the catalogue — without a single warning in the interface. The database is now a precondition: if it does not come up, nothing is stored.

The index is the deliberate exception: a brand-new context has no text to lose, and the index can be recreated later with no side effect. So its failure does not abort the registration — but it becomes a warning on screen, never just a technical record.

Before saving: the screen states what it will create

In the "Fontes de dados deste contexto" block, when you pick no source the platform derives the destinations from the internal name — and now says so before you save, in amber:

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

The notice informs, it does not block: deriving automatically is the intended behaviour — the defect was that it was silent. If the internal name is still blank, the notice says so instead of quoting an empty name.

After saving: the creation report

Saving opens a "Contexto criado — {label}" card showing:

• the Neo4j database and the search index actually provisioned (the values the server returned, not the screen's guess);
• the "Ficou pendente:" list, with whatever was created with a caveat — for example, the search index that did not come up, with the sentence telling you where to check OpenSearch and how to recreate it;
• the progress of the initial load of legislation, when you supplied a URL (section below).

With no pending items the card is neutral; with a pending item or a failed load it turns into an error card. The card exists because "created successfully" and "created halfway" were, until now, indistinguishable on screen.

Refusals on creation

All of them return a Portuguese message stating what to fix, and nothing is stored:

Context type and data identification

The Tipo de contexto field is mandatory and states what kind of data the context holds. The categories come from a platform catalogue — declaring a new category is registration, not a code change — and today they are:

When the chosen type keeps its data in an entity of its own, the form shows the "Identificação dos dados" block with two mandatory fields:

• Entidade âncora — the name of the graph node that aggregates the context's data (initial capital, singular: Processo, Empresa, Emprestimo).
• Propriedade identificadora — that node's unique property. It is what ties documents, analyses and the workflow to the right record (processoNumero, cnpj, numeroPedido).

Types that carry a suggestion fill both fields in as soon as they are selected; Análise de Crédito deliberately has none — a credit application is neither a CNJ number nor a CNPJ, and inheriting either would make the platform look for the key where it never was.

Saving without those fields is rejected, with a message stating what to fill in. The rejection exists because the silent failure is worse than the error: a context without identification does not break — it starts looking for everything as if it were court cases (:Processo by processoNumero), finds nothing and says nothing. That is how one dossier context ended up registered with a null identification.

Contexts already registered without identification keep working and stay editable: the requirement applies to a new context and to anyone changing the context's type. If you have one of those, open it, fill both fields in and save.

This context's role: when it is a rule corpus

In the creation form, the "Função deste contexto" block carries a single checkbox:

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

Ticking it puts the new context into the list of visible rule corpora — the same list that feeds the Screening Rules editor and the "Contextos de regra aplicados na triagem" block of every other context. It is what CPC, CPP, CDC and FEBRABAN already are.

*There is no — and must be no — context type called "rule". What makes a context a rule corpus are two things, and neither is the category: (a) its name appearing in the rules written for that corpus and (b) its presence in the list of visible corpora. The measurement backs the decision: FEBRABAN is of type Custom and works as a rule corpus, with its own rules in production; CPC, CPP and CDC are of type Código Processual*. Creating a new category for the same concept would give two diverging mechanisms for one question — and the day they disagreed, nobody would know which one holds.

Two guarantees on write, because both failures would be silent:

• the existing list is read and appended to, never replaced. Writing only the new name would wipe CPC, CPP, CDC and FEBRABAN in one go, with the screen saying "success";
• an empty list does not mean "no corpus" — with no items there is no filter, and every context already counts as a corpus. Writing [new] over the empty list would hide all the others. In that case nothing is written.

If the write fails, the context is still created and the report carries the pending item, telling you where to add it by hand.

The checkbox appears only when creating. It is deliberately absent from the edit form: the field belongs to creation, and showing it on edit would collect a choice the save discards — exactly the kind of mute field this revision removed. To adjust it later, use the visible-contexts list under Sistema›Regras.

Initial legislation load

The "URL da legislação" field stopped being decorative. When you fill it in and tick the rule-corpus checkbox, the platform starts the load against the context that has just been born — never against the session's active context — and tracks it inside the creation card itself, with a progress bar and the current activity.

Whatever prevents the load becomes a notice on the card, instead of silence:

Closing the card only stops the tracking; the load carries on and can be followed in Execution History.

Rule contexts applied by screening

This block is the inverse of the previous one: there the context is the corpus; here it consumes corpora from others. They are independent axes — a collection context consumes CPC and CDC without being a corpus of anything; a legislation context is a corpus and usually consumes none.

Right below the data sources, the form brings the "Contextos de regra aplicados na triagem" block: a checkbox list with the available rule contexts (the same ones the Screening Rules editor shows, with the same label). It answers a question the data context alone cannot answer:

They are independent axes, which is why they are different fields. The same collection may be judged by more than one code (a civil context with consumer relations declares CPC and CDC), and the same code serves several collections. Tick one or many: screening evaluates the union of the rules of everything ticked, without repeating a rule that belongs to more than one code.

What the screen shows as you select:

That last case matters: if a rule context is removed or renamed after being declared, it stays visible so you can untick it. Otherwise the value would be invisible on screen and saving would start failing with "nonexistent context" for no apparent reason.

Saving sends the complete list. Unticking everything and saving clears the configuration — and screening for that context starts refusing. That is not a side effect: it is the only explicit way back to the "not declared" state.

A nonexistent rule context is refused when saving, with a message in Portuguese listing the available ones. Order matters: the first ticked context is the primary one and governs the prompts, the case law consulted and the label shown in the report; the rules come from all of them.

The setting is read on every screening run — change it here, launch screening right after, and the new value is already in effect, with no restart and no wait.

What happens when a context declares nothing

Screening refuses and says what to do, instead of guessing: each case appears in the live view in red with the reason "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." No AI analysis is spent.

Why refusing. Until 2026-08-08 the platform inferred the applicable code from loose words in the case text. Measured in production: a civil enforcement case against the public treasury was sent to a code that does not exist on this platform — inheritance from an earlier project that survived in the code — because the word "administrativo" appeared in summaries quoted in the file. The report came out "completed" with zero rules evaluated, indistinguishable from a genuinely audited case. The three codes the platform actually has, measured on the same date: CPC with 1,076 rules, CPP with 748 and CDC with 106.

Replacing inference with configuration closes both ends: the wrong value is refused when saving, and the missing value is announced when screening.

If you edited contexts before 2026-08-08

Until that date there was a defect in saving: every context edit silently erased three settings that are not in the form — the context's reasoning model, the identifier label and the fixed rule context. The same loss happened when applying a reasoning model to all contexts at once.

Nobody noticed because reads returned the already resolved value, with the default derived from the context type: the zeroed field kept looking filled. If you edited contexts before that date, it is worth opening each one and checking the reasoning model and the identifier label — and, now, ticking the rule contexts.

Context Visibility Matrix

The matrix maps which features may use each context's data: one row per registered context and six checkbox columns — Painel de Regras, Upload PDF, Upload URL, DATTABI, DATTA Extract and Ontologia. The table is built from a feature catalog in the frontend itself, so a new column shows up without a layout change.

• Empty list = all contexts visible: unticking everything in a column falls back to every context being visible — there is no way for the administrator to "lock themselves out".
• Immediate persistence: every click saves right away and survives a page reload. The Painel de Regras column also notifies the rules screens that are already open, which reload the context list in real time.
• Recognized features: the generic write accepts only dattabi, extract and ontology; an unknown feature is refused with an error message in Portuguese.
• Parallel loading: all six columns are fetched at the same time when the page mounts, not one after the other.

Where each preference is stored:

Reading and writing each column is also available to integrations — see the API reference.

How far the visibility is enforced today

The matrix is interface and governance visibility, not a server-side per-context data access control list. To restrict who accesses what, use roles and permissions.

Hands-on example — creating a context from scratch

Your team is about to screen consumer-law cases and needs its own context, separate from the civil one:

1. In Sistema›Contextos, click + Novo Contexto.
2. In the "Adicionar Novo Contexto Legal" form, fill in both names (see Internal name vs. label just below) and the description: the Nome interno (e.g. Consumidor) and the Rótulo de exibição (e.g. "Código de Defesa do Consumidor").
3. In the "Fontes de dados deste contexto" block, tick the sources it uses.
4. In the "Contextos de regra aplicados na triagem" block, tick CDC — and CPC as well, if the collection also holds ordinary civil cases. The screen confirms below: "A triagem vai avaliar a união das regras de 2 contextos: CPC, CDC." Under "Função deste contexto", leave the checkbox unticked: this context holds cases, it is not itself a corpus of norms.
5. If you picked no sources, check the amber notice with the database and the index that will be created. Save.
6. Read the "Contexto criado" card: it shows the database and the index provisioned and, if any, the "Ficou pendente:" list. With no pending items the context already appears in the selector — ready for ingestion.
7. In the Visibility Matrix, tick where it should appear (e.g. only Painel de Regras and Upload PDF while it is in pilot).

Internal name vs. label

Every context carries two names, and the distinction matters the day you drive the platform through its API.

Where to find it: open Editar on the context. The "Nome interno" block, in monospace with a copy button, is the key the API expects.

Renaming the internal name

The internal name is editable in the same Editar form. It is not a label: it is stored in the domain field of every indexed passage, in the names of the context's search indices and in every external integration that already references it. Saving a new name therefore triggers a migration — the screen asks for confirmation and describes what will happen before writing anything.

What the platform moves on its own, within the save itself:

• The context's OpenSearch indices — text, vectors and chat history — are copied to the indices of the new name, with each document's domain field rewritten, and the old indices are removed only after the copy completes without failures.
• The context's prompts (index datta_prompts).
• The :Contexto node in the system databases datta and datta-audit-db.
• The active context, the three global Visibility Matrix lists (Painel de Regras, Upload PDF, Upload URL) and those of the remaining features.
• The workspaces that include the context.
• The rule contexts of other contexts that point at this one.
• The Knowledge Catalog datasets, which start listing the new name. Without that repoint the same dataset would appear twice in catalogue search — once per name — because the fresh scan publishes the new entry without removing the old.
• The context's BPM process models and instances. Without this, every model of the context would become an orphan at once (the very state the context validation on model creation exists to prevent) and instances would stop resolving owner, title and enrichment.

What does not change: the context's Neo4j database. It is a stored value, not derived from the name, so the graph stays exactly where it was — the "Careful" note below still applies after a rename.

What is left to you:

• Every external integration calling the API with ?domain=<old name> must switch to the new name. The platform has no way of discovering those callers; the report shown at the end of the rename says so.

Known refusals — in both cases nothing is changed and the context stays intact under its current name:

• A name already used by another context.
• A name that would collide on the index of another context. Index names drop hyphens, underscores and accents (datta_{letters and digits only}), so base-negativa and base_negativa would fight over the same datta_basenegativa and both contexts would start writing to the same place. Pick a name that differs by letters or digits.
• A failure while moving the indices (OpenSearch down, for instance). The rename is aborted before any configuration is written: the data stays intact under the old name and the operation can be retried.

On large contexts copying the indices takes a few minutes and the window must stay open until it finishes.

Careful. The internal name is not the database name. In the Processos context, for instance, the database is called processotributario and the label is "Processo Tributario" — three distinct strings, and only the first works in ?domain=. Passing the database name makes the endpoint answer that the context was not found.

Who can use it

• Viewing the screen, the matrix and the lists: CONFIG_VIEW.
• Changing the matrix and the per-context settings: CONFIG_EDIT.
• Clearing data: CONTEXT_PURGE (sensitive permission) — see clearing a context's data.
• Starting the initial legislation load along with creation: DOCUMENT_UPLOAD. Without it the context is created as usual and the card warns that the load was not started.

How to grant each one is covered in the roles and permissions guide.

UX history

• 2026-06-11 — the "+ Novo Contexto" button moved up into the page header (it used to sit in the middle, next to the selector); the edit button started showing only "Editar" (it used to repeat the name of the active context, e.g. "Editar PROCESSOS"); the Visibility Matrix was removed under the assumption that workspaces would cover visibility.
• 2026-06 — the Visibility Matrix came back at the user's request, now built from the feature catalog and expanded with DATTABI, DATTA Extract and Ontologia. The header with "+ Novo Contexto" and the "Editar" label from the earlier change remain.

Related documents

• Multi-source context — heterogeneous data sources per context.
• Clearing a context's data — emptying the content while keeping the context.
• Context Visibility Matrix — visibility governance per feature, in detail.
• Batch Screening — where the rule contexts configured here are applied.
• Graph database naming — system databases versus context databases.
• Context provisioning — the order, the contracts and the known limitations of what creation provisions (restricted reading).