SAT-Graph API: Temporal Legal Retrieval
- SAT-Graph API is the formal query execution layer for the legal domain that preserves hierarchical structure, temporal validity, and causal provenance.
- It employs a two-layer architecture where probabilistic discovery is separated from deterministic retrieval via formal identifiers and explicit temporal policies.
- The API guarantees explainability and auditability by providing a transparent DAG of composable actions that allow review of legal versioning and causal links.
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 (Martim, 7 Oct 2025).
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 (Martim, 7 Oct 2025).
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 (Martim, 7 Oct 2025).
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 (Martim, 7 Oct 2025).
| 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 (Martim, 7 Oct 2025).
| 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 (Martim, 7 Oct 2025).
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 (Martim, 7 Oct 2025).
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 (Bekos et al., 2020, Shirokikh et al., 2023).