Metadata-Version: 2.4
Name: tgms
Version: 0.6.1
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: numpy>=1.26
Requires-Dist: jsonschema>=4.23
Requires-Dist: pyyaml>=6.0
Requires-Dist: litellm>=1.48 ; extra == 'agent'
Requires-Dist: fastmcp>=2.0 ; extra == 'agent'
Requires-Dist: duckdb>=1.1 ; extra == 'duckdb'
Requires-Dist: pyarrow>=17 ; extra == 'duckdb'
Requires-Dist: psycopg[binary]>=3.2 ; extra == 'eval'
Requires-Dist: clickhouse-connect>=0.8 ; extra == 'eval'
Requires-Dist: neo4j>=5.20 ; extra == 'eval'
Requires-Dist: pandas>=2.2 ; extra == 'eval'
Requires-Dist: kuzu>=0.7 ; extra == 'kuzu'
Requires-Dist: faiss-cpu>=1.8 ; extra == 'memory'
Requires-Dist: sentence-transformers>=3.0 ; extra == 'memory'
Provides-Extra: agent
Provides-Extra: duckdb
Provides-Extra: eval
Provides-Extra: kuzu
Provides-Extra: memory
License-File: LICENSE
Summary: Agent-Native Temporal Graph Management System (bi-temporal property graph + validated temporal operator algebra + PEV agent layer)
Keywords: temporal-graph,bi-temporal,llm-agents,database,verification
Author-email: Xiaofei Zhang <zxfhkust@gmail.com>
License-Expression: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/zxf-work/tgms/blob/main/docs/TECHNICAL_REPORT.md
Project-URL: Homepage, https://zxf-work.github.io/tgms/
Project-URL: Repository, https://github.com/zxf-work/tgms

# TGMS — Agent-Native Bi-Temporal Graph Management System

[![CI](https://github.com/zxf-work/tgms/actions/workflows/ci.yml/badge.svg)](../../actions)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Coverage: temporal/ 97%](https://img.shields.io/badge/coverage_(temporal)-97%25-brightgreen.svg)](#correctness)

**A temporal graph database whose query surface is built for LLM agents —
and whose answers can be audited claim by claim.**

**Project page & blog:** https://zxf-work.github.io/tgms/ · **Paper:** [paper/main.pdf](paper/main.pdf)

LLM agents are unreliable at exactly the things temporal graph analytics
requires: arithmetic, identifiers, and asserting only what the evidence
shows. TGMS's answer is architectural — give the model **no opportunity**
to do any of them:

- a **bi-temporal property graph** (valid time × transaction time) that
  distinguishes *evolution* ("the edge ended") from *correction* ("we were
  wrong"), so agents can answer *"what did we believe on March 1?"* — a
  question latest-state snapshots and the RAG configurations we evaluated
  cannot express. Bi-temporality itself is inherited, not invented here —
  it has a four-decade literature, a place in SQL:2011, and production
  databases built around it. We measure against the clearest of those,
  [XTDB](https://xtdb.com): fed the same operation stream, the two systems
  agree on believed state at 400 of 400 probe points, with TGMS 3.9–4.7×
  faster at correction-heavy ingest on 23–27× less disk
  ([the head-to-head](https://zxf-work.github.io/tgms/blog/the-competitor-agrees.html));
- **15 verified temporal operators** (reachability over time-respecting
  paths, δ-motifs, snapshot diffs, burst detection, interval joins, grouped
  aggregation over edge events, and the belief log itself) — typed,
  deterministic, bounded,
  cost-guarded, exposed as tools (MCP or in-process); identifiers must come
  from a resolver, arithmetic from a `compute` operator;
- a **Planner–Executor–Verifier** loop: the LLM only plans and reports;
  plans are statically validated (including a grounding rule that makes
  fabricated identifiers impossible and output-field contracts that reject
  invented result paths), executed deterministically with content-addressed
  traces, and every claim in the written answer is **machine-checked
  against the trace that produced it** — including truncation taint, so
  "correct arithmetic over incomplete evidence" is caught too;
- a **purpose-built native storage engine** (Rust, PyO3): bi-temporal
  columnar segments, a temporal-CSR traversal index, group commit, and a
  single-writer / many-reader concurrency mode — 24.6 bytes per edge
  version, versus 78.4 on ClickHouse and 549.7 on PostgreSQL for the same
  1M-event log.

## Quickstart

```bash
pip install tgms
tgms demo
```

No GPU, no API key, no dataset download. `tgms demo` builds a small store of
its own in a temp directory and runs the arc every TGMS answer follows: what
the graph currently believes, what it believed *before* a correction landed,
and the trace that backs both claims up. Clean environment to first temporal
result: under 5 minutes.

Once you want your own graph data, the native test suite, the MCP server, or
an agent wired to a real LLM, see [Full setup](#full-setup-from-source)
below — this quickstart is deliberately the smallest possible first step,
not a tour of the operator surface.

Next steps, in the order most people need them:
[bring your own temporal graph data](docs/tutorials/bring-your-own-data.md) ·
[give TGMS to an agent over MCP](docs/tutorials/agent-setup.md) ·
[audit an answer](docs/tutorials/audit-an-answer.md) ·
[what you can rely on across versions](docs/STABILITY.md) ·
[what's coming](docs/PUBLIC_ROADMAP.md)

## Does it work?

Three different questions, three different answers. All three are reported
because the third is the least flattering.

**1. Does the agent layer beat the alternatives?** Dev-split campaign
(CollegeMsg, open-source models served locally on one 24 GB GPU. "Answer
accuracy" is normalized typed-answer accuracy — counts and values scored
strictly, interval answers credited at IoU ≥ 0.5. Full receipts ship with
the paper and the eval records in `benchmarks/results-v1/`):

| pooled answer accuracy, Qwen2.5-14B | TGMS | vector-RAG | static-graph RAG | text-to-Cypher |
|---|---:|---:|---:|---:|
| all task families | **0.41** | 0.09 | 0.05 | 0.18 |
| correction probes ("as of tt…") | **0.67** | 0.00 | 0.00 | 0.00 |

- vs static-graph RAG: **+36 points**, paired-bootstrap 95% CI [0.18, 0.59]
- verifier fault injection: **500/500 injected false claims caught, 0 false
  positives**; on the frozen campaign, **0 of 199 emitted answers** contained
  an unsupported claim with gating (21 of 220 without it) — coverage is
  199/282, so some of that is bought by declining to answer
- accuracy tracks planner capability where baselines stay flat: **13.8% /
  34.0% / 62.8%** at Qwen2.5 7B / 14B / 32B fp16, correction probes
  saturating at 100% at 32B

**2. Is the engine competitive?** Six systems answer one 13-query registry
— TGMS native, TGMS-on-DuckDB, PostgreSQL, ClickHouse, Neo4j, Memgraph —
with **every cell hash-verified before it was timed**:

| query shape | TGMS native | best other |
|---|---:|---:|
| temporal reachability, 200k | **14.7 ms** | 3.9–7.3 s (Memgraph, Neo4j) |
| closed-triangle δ-motif, 200k | **28.7 ms** | 2.1–5.5 s (Memgraph, Neo4j) |
| grouped aggregation, 200k | **14.5 ms** | 32.6 ms (ClickHouse) |
| entity history by identity, 200k | **0.1 ms** | 0.3 ms (PostgreSQL) |
| whole-window bucketed count, 10M | 84.7 ms | **37.9 ms** (ClickHouse) |

The last row is the one we cannot close: ClickHouse keeps a factor of 2.2
on whole-window aggregation at both 1M and 10M, and it is a constant of the
shape rather than something that grows with scale. Three rounds of
profiling took that gap from 12× to 2.2× and each round found our own
implementation rather than the workload. Single latency cells reproduce to
about ±20% between days, which is stated everywhere they are quoted.

At 10M events the full query suite runs inside **1.76 GB** of peak RSS,
16 concurrent readers get **10.2×** the throughput of one, and a live
writer costs those readers **0–3%** of per-query latency.

**3. Can it answer the questions people actually ask?** This is the honest
one. 110 questions were written by people who saw a plain-language
description of two public datasets and **never saw the operator list**. Of
those, **83 are expressible today** — 10 were expressible when the study was
pre-registered. Of LDBC SNB's 41 read templates, **3**, and that number has
not moved in eight sessions because 35 of the 38 misses need labelled
multi-way pattern matching, which is a deliberately deferred design
decision rather than a missing operator.

The store is good and the surface is narrow. Both instruments live in the
repo (`scripts/independent_questions.py`, `scripts/ldbc_fit.py`), they
re-run in seconds, and each capability shipped since has been scored
against a forecast made *before* it was built — delivered/predicted has run
14/30, 4/7, 10/13, 14/16, 15/15, 4/8, 5/5 and 4/5. The last two were the
first forecasts made per question rather than in aggregate, and they were
right in every cell.

## What the operators can express

Fifteen operators — fourteen of them unchanged since D-044, because the
interesting growth since v0.4.0 happened *inside* them, driven question by question by the study above:

| capability | where it lives | what it answers |
|---|---|---|
| grouped aggregation | `aggregate_events` | counts and distinct counts by time bucket, rel_type, endpoint or endpoint label |
| arithmetic | `compute` | mean/median over rows; ratio/diff/percent over two scalars — never in the LLM |
| typed properties | `aggregate_events` | predicates and min/max/mean over an edge property, where a value participates only if its JSON type fits |
| set operations | `compute`, `aggregate_events` | intersect/difference/union over uid lists, a cohort pre-filter, undirected and reciprocal pair modes |
| row arithmetic and joins | `compute` | `derive` adds one computed column; `join` aligns two grouped results on a key unique on both sides |
| ordered sequences | `aggregate_events` | longest gap between consecutive events, busiest sliding window of a given span, longest run with no gap over a threshold |
| calendar units | `aggregate_events` | grouping by hour of day, day of week or month of year, at a fixed offset from UTC that is an argument rather than a default |
| the belief log | `version_history` | which beliefs were revised and when — the only operator that reads the correction record rather than a state derived from it |

Every one of these is verified against the same brute-force oracle as the
operators themselves, and every one is measured in the session that shipped
it. What is *not* there is written down too, question by question, in the
re-audit tables of `scripts/independent_questions.py` and
`scripts/ldbc_fit.py` — both of which print the current blocked-capability
board on `report`.

## Full setup (from source)

Everything below builds TGMS from a checkout instead of the PyPI wheel:
real dataset loaders, the native-engine test suite, the MCP server, and an
agent loop wired to an actual LLM.

```bash
# macOS note: if this repo sits in an iCloud-synced folder, keep the venv
# outside it (iCloud sets the hidden flag on .pth files and Python 3.12+
# silently skips them):  export UV_PROJECT_ENVIRONMENT=$HOME/.venvs/tgms
uv sync --extra agent
make test                     # 271 tests: property, oracle, metamorphic, e2e
```

```bash
# build a real store + task suite (downloads CollegeMsg from SNAP)
make data-collegemsg suite-collegemsg
```

```bash
# call one verified operator — no LLM needed
uv run tgms call temporal_reachability \
  '{"src": "n9", "window": {"t_a": 1082040961000000, "t_b": 1088000000000000}}' \
  --store stores/collegemsg
```

```bash
# verifier acceptance experiment (deterministic, no LLM)
uv run tgms eval c2 --store stores/collegemsg \
  --suite stores/suite-collegemsg/suite.json --mutants 500
```

With any OpenAI-compatible LLM endpoint (e.g. `vllm serve Qwen/Qwen2.5-7B-Instruct`):

```bash
uv run tgms ask "How many nodes can n9 reach between ... and ...?" \
  --store stores/collegemsg --model openai/Qwen/Qwen2.5-7B-Instruct \
  --api-base http://localhost:8000/v1 --html trace.html   # auditable trace page
```

```bash
bash scripts/run_webapp.sh    # interactive guided demo at localhost:8080
```

## Interfaces

| Surface | Entry point | What it's for |
|---|---|---|
| Python library | `tgms.open(...)`, `Agent(store, model=…).ask(…)` | research code, notebooks |
| MCP server | `tgms serve --store PATH` | hand the verified toolbox to any MCP-capable agent |
| CLI | `tgms demo/ingest/synth/tasks/call/ask/bench/memory/eval` | reproducibility |
| Trace viewer | `tgms ask … --html trace.html` | *ask → answer → audit the evidence* (static, self-contained HTML) |
| Demo GUI | `tgms webapp …` / `scripts/run_webapp.sh` | guided tour: operators → agent → tamper demo → time travel |

## Correctness

Every operator is verified against an independent brute-force oracle (500
randomized cases per operator; 97% line coverage in `tgms/temporal/`
across both backends), plus
metamorphic properties — diff composition and **bi-temporal immutability**:
any result pinned to a past belief state is byte-identical before and after
later corrections. The same suite runs unmodified against **both backends**,
which is the whole acceptance argument for the native engine: it has to
satisfy the same human-owned ground truth that DuckDB does.

```bash
TGMS_TEST_BACKEND=native make test    # same tests, native engine
```

The write path is property-tested over random assert/retract/correct
interleavings, and the append-only event log replays into either backend
with identical store digests. Process rules are enforced in CI and are not
advisory: tests and the oracle may never share a commit with the
implementation they judge, and every number quoted on the project site is
resolved from `docs/site_facts.json` at build time, so a stale figure fails
the build rather than the review. See [CONTRIBUTING.md](CONTRIBUTING.md).

## Layout

```
tgms/core       clock, bi-temporal data model, error taxonomy
tgms/storage    StorageAdapter ABC, native + DuckDB backends, event log, TCSR index
tgms/temporal   operator algebra O1–O15 + brute-force oracle
tgms/tools      tool schemas, MCP server / ToolRouter, trace viewer, demo GUI
tgms/agent      plan IR, planner, executor, verifier, reporter, memory
tgms/data       dataset loaders (SHA-256 pinned) + synthetic generator
tgms/eval       task suites, baselines, matrix harness, metrics, fault injection
crates/         the native engine: bi-temporal segments, TCSR, motif kernel
```

Datasets are never bundled: loaders download from source (SNAP) and pin
SHA-256 manifests. See [docs/eval/](docs/eval/)
for design, positioning, measurements, and roadmap.

## License

Apache-2.0 — see [LICENSE](LICENSE). Cite via [CITATION.cff](CITATION.cff).

