---
title: 'SAT-Graph API: Temporal Legal Retrieval'
url: https://www.emergentmind.com/topics/sat-graph-api
type: topic
---

# SAT-Graph API: Temporal Legal Retrieval

SAT-Graph API is the formal query execution layer for the Structure-Aware Temporal Graph RAG (SAT-Graph RAG) in the legal domain. It is designed for settings in which retrieval must preserve hierarchical structure, temporal validity, and causal provenance of legal norms, rather than merely return semantically similar text. The system introduces a Canonical Action API composed of atomic, composable, auditable primitives that separate probabilistic discovery from deterministic retrieval, so that natural-language grounding occurs at the boundary of the system while all downstream access proceeds through formal identifiers and explicit temporal policies [2510.06002].

## 1. Problem setting and retrieval model

Standard Retrieval-Augmented Generation is treated as inadequate for many legal queries because it is probabilistic at its core: it ranks text chunks by similarity and often cannot guarantee that the retrieved passage is the legally valid version, the correct article, or the correct historical state. The motivating problem is therefore not only semantic relevance, but retrieval of the correct legal object, in the correct structural context, at the correct point in time, with traceable causal provenance. In this setting, validity is temporal, structure is semantically significant, and change histories must be auditable [2510.06002].

SAT-Graph RAG addresses the representation side of that problem by modeling legal norms as a verifiable, structure-aware, temporal knowledge graph. SAT-Graph API addresses the interaction side: if an external agent were to query the graph through ad hoc natural-language retrieval alone, ambiguity and nondeterminism would be reintroduced. The API is therefore not an answering endpoint in the ordinary sense. It is a controlled protocol for constructing retrieval plans whose individual steps remain inspectable.

A recurrent misconception is that a legal knowledge graph by itself guarantees reliable retrieval. The design of SAT-Graph API rejects that view. The graph is only one layer; the second layer is a formal action system that constrains how queries are decomposed and executed. A plausible implication is that the paper treats retrieval correctness as an interface problem as much as a storage problem.

## 2. Two-layer architecture and determinism

The architecture is explicitly divided into two layers. The lower layer is the SAT-Graph, which stores the legal ontology together with temporal and causal structure. The upper layer is the Canonical Action API, whose actions are atomic, composable, and auditable. A planner-guided agent, including a ReAct-style or graph-RAG-style agent, receives a user query and decomposes it into a directed acyclic graph (DAG) of action calls. Discovery actions may remain probabilistic, but once a formal identifier is resolved, the remainder of the plan is deterministic [2510.06002].

The central formal principle is determinism through formal IDs. Any action whose primary input is a formal ID is defined as fully deterministic. Discovery actions are the only probabilistic actions. This isolates probabilistic natural-language interpretation from exact graph retrieval. The design therefore makes explicit whether a step returns a ranked candidate list with confidence scores or a single grounded object.

This separation is operational as well as epistemic. The paper emphasizes that one should be able to inspect which reference was resolved to which ID, at what confidence, which version was considered valid at a given date, and which legislative action created or terminated that version. The output of a retrieval plan is thus intended to be human-readable and reviewable rather than opaque.

## 3. Ontology and formal data model

The API operates over an explicit ontology that separates normative structure, conceptual classification, temporal state, causality, and text carriers. That separation is presented as the condition that makes deterministic querying feasible [2510.06002].

| Entity | Core role | Notable fields |
|---|---|---|
| `Item` | Versioned structural entity | `id`, `category`, `type`, `label`, `parent`, `children`, `metadata` |
| `Theme` | Atemporal conceptual entity | `id`, `label`, multiple parents/children, `members` |
| `Version` | Point-in-time state of an `Item` | `id`, `item_id`, `validity_interval`, parent/children version links |
| `Action` | Atomic legislative event | `id`, `type`, `date`, `source_version_id`, `terminates_version`, `produces_version` |
| `TextUnit` | Decoupled text carrier | `source_node_type`, `source_node_id`, `language`, `aspect`, `content` |

`Item` is a versioned structural entity, either a `Work` or `Work Component`, with optional parent and child relations. `Theme` is atemporal and can have multiple parents and children, so the thematic taxonomy is a DAG rather than a tree. `Version` captures temporal state through `Version.validity_interval = [start_date, end_date?]`. `Action` links `source_version_id` to `produces_version` and optionally `terminates_version`, thereby encoding causal provenance. `TextUnit` is decoupled from the core entities and can attach text to any node via `source_node_type` and `source_node_id`.

Several operational semantics are defined in near-formal terms. `Item` has a strict parent/children hierarchy, whereas `Theme` supports multiple inheritance. `searchTextUnits` has mutually exclusive scoping modes: either explicit `version_ids`, or `item_ids`/`theme_ids` with an optional `timestamp`. `getValidVersion` requires an explicit `TemporalPolicy`, including `TemporalPolicy.SnapshotLast`, which returns the last valid version at or before the timestamp, and `PointInTime` semantics. `TextUnit.aspects` supports retrieval across canonical text, descriptions, summaries, and metadata text.

## 4. Canonical action families

The action system is organized so that discovery is broad and flexible, while post-resolution access is exact. Discovery actions include `resolveItemReference`, `resolveThemeReference`, `searchItems`, `searchThemes`, and `searchTextUnits`. Deterministic actions include direct fetches, temporal resolution, structural navigation, causal tracing, aggregate analysis, introspection, and batch retrieval [2510.06002].

| Action family | Representative actions | Primary role |
|---|---|---|
| Discovery | `resolveItemReference`, `resolveThemeReference`, `searchItems`, `searchThemes`, `searchTextUnits` | Natural-language grounding and hybrid search |
| Deterministic fetch | `getItem`, `getTheme`, `getAction`, `getValidVersion`, `getTextForVersion` | Exact lookup and temporal resolution |
| Structure and causality | `enumerateItems`, `getAncestors`, `getThemesForItem`, `getItemContext`, `getItemHistory`, `traceCausality`, `compareVersions` | Context, lineage, and historical analysis |
| Aggregation and introspection | `summarizeImpact`, `getTemporalCoverage`, `getAvailableLanguages`, `getSupportedActionTypes`, `getRootThemes` | Server-side analysis and query validation |

`resolveItemReference(reference_text, context_id?, top_k?)` maps ambiguous expressions such as “Article 5 of the Constitution” or “the previous section” to ranked candidate item IDs and returns confidence scores rather than asserting certainty. The optional `context_id` supports relative reference resolution. `resolveThemeReference` performs an analogous function for conceptual categories. `searchItems` is structural discovery across the entire version history of each item and is therefore time-agnostic by design. `searchThemes` searches only curated textual descriptions of themes, not the texts of member items, in order to avoid semantic noise.

`searchTextUnits` is the principal hybrid retrieval primitive. It can scope by explicit `version_ids`, or by `item_ids` or `theme_ids` together with an optional `timestamp`. It supports `semantic_query`, `lexical_query`, `metadata_filter`, `language`, `aspects`, and `top_k`. When `timestamp` is omitted, it defaults to the current valid texts and thereby reproduces baseline RAG behavior. When `timestamp` is present, it becomes point-in-time retrieval over the historical snapshot valid at that date.

Once an identifier is known, exact retrieval actions take over. `getItem`, `getTheme`, and `getAction` are direct lookups. `getValidVersion(item_id, timestamp, policy)` is the core temporal-resolution primitive, and `getTextForVersion(version_id, language)` is a deterministic text fetch keyed by version. The paper stresses the distinction between `getTextForVersion`, which is a primary-key lookup, and `searchTextUnits`, which remains a search operation.

Structural navigation is handled through `enumerateItems`, `getAncestors`, `getThemesForItem`, and `getItemContext`. `enumerateItems` is polymorphic: within an item scope it returns children or descendants depending on `depth`, whereas within a theme scope it returns member items. `getAncestors` returns the breadcrumb path in the document hierarchy. `getItemContext` packages parent, siblings, and children in one atomic call.

Causal lineage is exposed through `getItemHistory(item_id)`, `traceCausality(version_id)`, `getVersionsInInterval(item_id, start_date, end_date)`, `compareVersions(version_id_A, version_id_B)`, and `getActionsBySource(source_work_id, action_types?)`. `compareVersions` is described as producing a structure-aware diff report rather than merely a textual diff. Higher-level server-side analysis is provided by `summarizeImpact(item_ids?, theme_ids?, time_interval, action_types?)`, which returns an `ImpactReport` containing aggregate statistics and affected actions or items.

## 5. Planner-guided DAG execution

The planner-guided DAG is the main execution model. A query such as “What was the text of Article 6 of the Constitution in 1999?” decomposes into three stages: resolve the article reference, identify the valid version at the timestamp, and fetch the exact text for that version. A query such as “Summarize the evolution of all constitutional provisions related to Digital Security since 2000” decomposes into `searchThemes`, then `summarizeImpact` over the relevant theme and interval, followed by batch hydration if richer detail is needed [2510.06002].

More complex historical and provenance questions illustrate the difference between API-level determinism and agent-level reasoning. “What were the exact textual differences in Article 6 before and after the amendment that introduced housing?” is decomposed into `resolveItemReference`, `getItemHistory`, agent-side inspection of version texts to identify the pivotal action, and then `compareVersions` on the terminated and produced versions. “Which specific law introduced Article 227, paragraph 4, and is its text still the same today?” splits into parallel branches: one uses `getValidVersion` and `traceCausality` to identify the creating action, and the other compares the historical and current versions via `compareVersions`.

The paper also uses the deliberately ambiguous question “What was the previous rule that governed this matter?” to distinguish two different interpretations. A structural predecessor is found deterministically through `getValidVersion` together with `traceCausality`. A normative predecessor is found heuristically by searching prior temporal snapshots for semantically similar content. This distinction is important because it demonstrates that the API does not eliminate ambiguity by fiat; rather, it localizes ambiguity to the planning and discovery phase and makes the chosen interpretation inspectable.

## 6. Explainability, implementation, and scope

Explainability and auditability are primary design goals rather than secondary conveniences. By turning retrieval into a transparent DAG of actions, the system is presented as an XAI-oriented response for high-stakes legal settings. The action log can be reviewed by a human, exposing grounding confidence scores, timestamps used for validity checks, and causal links between versions and legislative acts. The intended properties are traceability, reproducibility, and accountability [2510.06002].

The action layer is intended to abstract over the underlying graph database, including Cypher over Neo4j. The paper states that the repository provides a complete machine-readable OpenAPI 3.0 YAML specification with request and response schemas, examples, error specifications, authentication, and rate limiting. It also proposes batch variants—`getBatchItems`, `getBatchValidVersions`, `getBatchTexts`, and `getBatchActions`—to avoid N+1 request patterns, especially when reconstructing historical state across many articles or hydrating lightweight reports.

The scope of the API is deliberately limited. It does not claim to solve conflict detection, transitive dependency analysis, or deeper legal inference; those tasks remain responsibilities of the higher-level agent. The design also depends on the correctness and completeness of the underlying ontology, so missing or incorrect modeling propagates into retrieval. It assumes competent planning agents capable of transforming natural-language queries into effective action DAGs.

The paper is explicit that the work is primarily a specification and architecture proposal rather than a full empirical evaluation. Production-grade deployment is said to require substantial engineering for temporal indexing, server-side aggregation, and batch support. A final source of confusion is terminological: “SAT-Graph API” in this usage denotes the legal retrieval layer of SAT-Graph RAG, not unrelated SAT-based graph systems or SAT-solving graph representations found elsewhere in the literature [2003.09642] [2307.09141].

Source: https://www.emergentmind.com/topics/sat-graph-api