factblock 1.0.0a1__py3-none-any.whl

factblock/__init__.py

@@ -0,0 +1,30 @@
+"""FactBlock table format: reference reader and validator (SPEC.md).
+
+    scan(bundle, as_of, valid_at=None) -> Scan   # .nodes/.edges/.resolutions Arrow tables, .certificate
+    validate(bundle) -> list[Check]              # one row per check id in SPEC section 2
+    resolve(bundle, fact_key, as_of, valid_at=None, rules_as_of=None) -> dict   # SPEC 4.4
+    write_parquet(bundle, out) -> Path          # JSONL bundle to the Parquet profile, SPEC 5.3
+    extract(text, observed_at, ...) -> dict      # the claims profile through a model you choose (extract.py)
+    write_bundle(result, out, append=False)      # dicts to a JSONL bundle, growing one batch at a time
+    recall(bundle, query, as_of, valid_at=None, limit=10) -> dict   # the blocks about something, as of an instant
+    context(bundle, query, as_of) -> str           # the same recall as prompt lines
+    why(bundle, node_id, as_of, valid_at=None, depth=3) -> dict   # the chain behind one block, SPEC 4.5
+    leak(bundle, questions) -> dict               # answers that rest on blocks learned after the question was asked
+    sync(bundle, store, as_of=None, push=True, pull=True) -> dict   # folder <-> a store (TckgStore, or yours) by identity
+    to_claimreview(bundle, as_of, base_url=None) -> dict   # verdicts as schema.org ClaimReview JSON-LD, SPEC 9.2
+    to_okf(bundle, as_of, out) -> Path             # one OKF concept document per visible node, SPEC 9.1
+"""
+from .bundle import Bundle, write_bundle
+from .claimreview import to_claimreview
+from .okf import to_okf
+from .extract import extract, load_profile
+from .leak import leak
+from .parquet import write_parquet
+from .recall import context, recall
+from .resolve import resolve
+from .scan import Scan, scan
+from .sync import Store, TckgStore, sync
+from .validate import Check, validate
+from .why import why
+
+__all__ = ["Bundle", "Scan", "scan", "Check", "validate", "resolve", "write_parquet", "extract", "load_profile", "write_bundle", "why", "leak", "sync", "Store", "TckgStore", "to_claimreview", "to_okf", "recall", "context"]

factblock/__main__.py

@@ -0,0 +1,237 @@
+"""The factblock command. `factblock --help` lists the subcommands in the order you meet them:
+sample, extract, scan, recall, why, resolve, leak, validate, sync, then the projections and adapters.
+Reads print for people; `--json` prints the same answer as JSON."""
+import argparse
+import json
+import os
+import pathlib
+import shutil
+import sys
+
+from . import Bundle, TckgStore, extract, leak, recall, resolve, scan, sync, to_claimreview, to_okf, validate, why, write_bundle, write_parquet
+from .adapters.factcheck import bundle_from_factcheck, search as factcheck_search
+
+# the wheel carries samples/rates at factblock/samples/rates (pyproject force-include); a checkout has it at the repo root
+SAMPLES = next((d for d in (pathlib.Path(__file__).parent / "samples", pathlib.Path(__file__).resolve().parents[1] / "samples") if (d / "rates").exists()), None)
+
+
+def _day(v):
+    return v.date().isoformat() if hasattr(v, "date") else str(v)[:10]
+
+
+def _cert(c):
+    m = c.get("masked", {}); b = c.get("backfill")
+    parts = [f"as of {c['as_of'][:10]}"]
+    if c.get("valid_at", "")[:10] != c["as_of"][:10]:
+        parts.append(f"valid at {c['valid_at'][:10]}")
+    parts.append("hidden: " + (", ".join(f"{n} {k}{'s' if n != 1 else ''}" for k, n in m.items()) if m else "nothing"))
+    if b:
+        parts.append(f"backfilled: {b['rows']} rows in {b['batches']} batch{'es' if b['batches'] != 1 else ''}")
+    return "  ".join(parts)
+
+
+def _print_scan(r):
+    print(_cert(r.certificate))
+    nodes = r.nodes.to_pylist()
+    for n in sorted(nodes, key=lambda n: (n["asserted_at"], n["id"])):
+        tail = f"   [superseded by {n['superseded_by']}]" if n.get("superseded_by") else ""
+        print(f"{n['id']:<12} {n['kind']:<11} {_day(n['asserted_at'])}  {n.get('statement') or ''}{tail}")
+    if r.edges.num_rows:
+        print("edges:")
+        for e in sorted(r.edges.to_pylist(), key=lambda e: (e["asserted_at"], e["source_id"])):
+            print(f"  {e['source_id']} --{e['edge_type']}--> {e['target_id']}   {_day(e['asserted_at'])}")
+    if r.resolutions.num_rows:
+        print("verdicts:")
+        for v in sorted(r.resolutions.to_pylist(), key=lambda v: v["decided_at"]):
+            print(f"  {v['target_id']:<12} {v.get('outcome') or v.get('value')}   decided {_day(v['decided_at'])}" + (f"   by {v['resolver']}" if v.get("resolver") else ""))
+
+
+def _print_why(r):
+    if not r["chain"]:
+        print(f"{r['root']}: {r.get('reason', 'no chain')}   {_cert(r['certificate'])}")
+        return
+    for row in sorted(r["chain"], key=lambda x: (len(x["path"]), x["path"])):
+        via = f" ({row['via']['edge_type']})" if row["via"] else ""
+        print("    " * row["depth"] + f"{row['role']}{via}: {row['id']}  {_day(row['asserted_at'])}  {row['statement'] or ''}")
+    print(_cert(r["certificate"]))
+
+
+def _print_resolve(k, r):
+    if r["status"] == "answered":
+        print(f"{k}: {json.dumps(r['value'])}   policy {r.get('policy')}, {len(r['candidates'])} candidate{'s' if len(r['candidates']) != 1 else ''}")
+    else:
+        print(f"{k}: no answer, {r['reason']}" + (f" since {r['unresolved_since'][:10]}" if r.get("unresolved_since") else ""))
+        for c in r.get("candidates", []):
+            print(f"  {c['id']:<12} {json.dumps(c['value'])}   valid from {c['valid_from'][:10]}   known {c['known_at'][:10]}")
+    print(_cert(r["certificate"]))
+
+
+def main():
+    p = argparse.ArgumentParser(prog="factblock", description="Agent memory for decisions: dated claims and their causal links, in a folder, read as of any instant.")
+    sub = p.add_subparsers(dest="cmd", metavar="command")
+
+    def cmd(name, help_, as_of=True, valid_at=True, json_=True):
+        s = sub.add_parser(name, help=help_, description=help_)
+        s.add_argument("bundle", help="the bundle directory")
+        if as_of:
+            s.add_argument("--as-of", required=True, help="the instant to read as of (date or ISO 8601); nothing learned later is shown")
+        if valid_at:
+            s.add_argument("--valid-at", help="the instant the content must hold at; default: as-of")
+        if json_:
+            s.add_argument("--json", action="store_true", help="print the answer as JSON")
+        return s
+
+    s = sub.add_parser("sample", help="copy the sample bundle (six dated claims, a reversal, three verdicts) into a folder", description="copy the sample bundle into a folder")
+    s.add_argument("out", help="folder to create, e.g. brain/")
+    e = sub.add_parser("extract", help="text in, dated blocks and their links appended to a bundle", description="text in, dated blocks and their links appended to a bundle")
+    e.add_argument("source", help="a text file, or - for stdin")
+    e.add_argument("--observed-at", required=True, help="when it was said or written (ISO 8601)")
+    e.add_argument("-o", "--out", required=True, help="bundle directory; created or appended to")
+    e.add_argument("--speaker", help="who said it, as written")
+    e.add_argument("--source-name", dest="source_name", help="where it came from (a channel, a document)")
+    e.add_argument("--provider", default="gemini", choices=["gemini", "openai", "fake"], help="gemini (GEMINI_API_KEY or Vertex), openai (OPENAI_API_KEY), or fake: no model, sentence split, for trying the format")
+    e.add_argument("--model", help="model name for the provider")
+    e.add_argument("--known-at", help="when you learned it; default now")
+    e.add_argument("--backfill", action="store_true", help="known_at = observed_at: material from the past, known when it was said")
+    e.add_argument("--namespace", default="local")
+    cmd("scan", "what the folder knew as of an instant: blocks, edges, verdicts, and what was hidden")
+    rc = cmd("recall", "the blocks about something as of an instant, ranked; the read an agent makes before it answers")
+    rc.add_argument("query", help="words to look for in statements, quotes and speakers")
+    rc.add_argument("--limit", type=int, default=10)
+    rc.add_argument("--all-kinds", action="store_true", help="include entities and episodes, not only claims and predictions")
+    w = cmd("why", "the chain behind one block as of an instant: causes, effects, successors, contradictions")
+    w.add_argument("node_id", help="the block id (see scan)")
+    w.add_argument("--depth", type=int, default=3, help="hops to walk; default 3")
+    r = cmd("resolve", "one value for a declared fact, by its declared policy, or the reason there is none")
+    r.add_argument("fact_key", help="the declared fact, e.g. belief:fed:direction")
+    r.add_argument("--rules-as-of", help="apply the declaration in force at this instant instead of as-of")
+    k = cmd("leak", "which answers in a dated question set rest on blocks learned after the question was asked", as_of=False, valid_at=False, json_=False)
+    k.add_argument("questions", help="JSONL: {id?, asked_at, evidence: [block id, ...]} per line")
+    cmd("validate", "the conformance checks of SPEC.md section 2; exit 1 if any fails", as_of=False, valid_at=False, json_=False)
+    y = sub.add_parser("sync", help="folder <-> a hosted ledger, both ways, by identity; known_at travels as batches", description="folder <-> a hosted ledger (tckg), both ways")
+    y.add_argument("bundle")
+    y.add_argument("url", help="the ledger, e.g. https://tckg.factagora.com")
+    y.add_argument("--space", help="whose memory this is on the ledger; rows that carry their own space keep it")
+    y.add_argument("--token", help="API key of the tenant; default $TCKG_TOKEN")
+    y.add_argument("--as-of", help="pull rows the ledger knew by this instant; default now")
+    y.add_argument("--push-only", action="store_true")
+    y.add_argument("--pull-only", action="store_true")
+    cr = cmd("to-claimreview", "verdicts visible as of an instant, as schema.org ClaimReview JSON-LD", json_=False)
+    cr.add_argument("--base-url", help="each review's url becomes <base-url>/<block id>")
+    ok = cmd("to-okf", "the blocks visible as of an instant, as an OKF bundle (markdown + frontmatter)", json_=False)
+    ok.add_argument("out", help="directory to write")
+    c = sub.add_parser("to-parquet", help="the same bundle in the Parquet profile, for DuckDB, Spark, Databricks", description="JSONL bundle to the Parquet profile")
+    c.add_argument("bundle"); c.add_argument("out")
+    fc = sub.add_parser("from-factcheck", help="published fact-checks in (Google Fact Check Tools API shape), dated claims with dated verdicts out", description="fact-checks in, dated claims with dated verdicts out")
+    fc.add_argument("-o", "--out", required=True, help="bundle directory; created or appended to")
+    fc.add_argument("--query", help="search the live API; needs --api-key or $FACTCHECK_API_KEY")
+    fc.add_argument("--language", help="BCP-47 filter for --query, e.g. en or ko")
+    fc.add_argument("--pages", type=int, default=1, help="pages of 100 to fetch for --query")
+    fc.add_argument("--api-key")
+    fc.add_argument("--from-json", help="a saved claims:search response, or a JSON array of claims")
+    fc.add_argument("--namespace", default="factcheck")
+    a = p.parse_args()
+    if not a.cmd:                       # bare `factblock`: show what it can do, not an error
+        p.print_help()
+        print("\nStart here: factblock sample brain/ && factblock scan brain/ --as-of 2024-05-01")
+        return
+    out_json = lambda d: print(json.dumps(d, indent=1, default=str))  # noqa: E731
+
+    if a.cmd == "sample":
+        if pathlib.Path(a.out).exists():
+            p.error(f"{a.out} exists; pick a new folder")
+        shutil.copytree(SAMPLES / "rates", a.out)
+        print(f"{a.out}: the sample bundle. Try: factblock scan {a.out} --as-of 2024-05-01")
+    elif a.cmd == "extract":
+        text = sys.stdin.read() if a.source == "-" else open(a.source).read()
+        existing = Bundle(a.out) if (pathlib.Path(a.out) / "factblock.json").exists() else None
+        r = extract(text, a.observed_at, speaker=a.speaker, source=a.source_name, provider=a.provider, model=a.model,
+                    known_at=a.known_at, backfill=a.backfill, namespace=a.namespace, existing=existing)
+        write_bundle(r, a.out, append=True)
+        s_ = r["summary"]
+        print(f"{a.out}: +{s_['blocks']} blocks, +{s_['entities']} entities, +{s_['links']} links"
+              + (f" ({s_['links_dropped']} dropped)" if s_['links_dropped'] else "") + f", batch {s_['batch']}")
+    elif a.cmd == "scan":
+        r = scan(a.bundle, a.as_of, a.valid_at)
+        if a.json:
+            out_json({"certificate": r.certificate,
+                      "nodes": r.nodes.select([c for c in ("id", "kind", "statement", "asserted_at", "superseded_by") if c in r.nodes.column_names]).to_pylist(),
+                      "edges": r.edges.select(["source_id", "target_id", "edge_type", "asserted_at"]).to_pylist() if r.edges.num_rows else [],
+                      "resolutions": r.resolutions.to_pylist()})
+        else:
+            _print_scan(r)
+    elif a.cmd == "recall":
+        r = recall(a.bundle, a.query, a.as_of, a.valid_at, a.limit, kinds=() if a.all_kinds else ("claim", "prediction"))
+        if a.json:
+            out_json(r)
+        else:
+            for i in r["items"]:
+                print(f"{i['id']:<12} {i['kind']:<11} {_day(i['asserted_at'])}  {i['statement']}" + (f"   ({i['speaker']})" if i.get("speaker") else ""))
+            print(f"{len(r['items'])} of {r['matched']} matching   {_cert(r['certificate'])}")
+    elif a.cmd == "why":
+        r = why(a.bundle, a.node_id, a.as_of, a.valid_at, a.depth)
+        out_json(r) if a.json else _print_why(r)
+    elif a.cmd == "resolve":
+        r = resolve(a.bundle, a.fact_key, a.as_of, a.valid_at, a.rules_as_of)
+        out_json(r) if a.json else _print_resolve(a.fact_key, r)
+    elif a.cmd == "leak":
+        r = leak(a.bundle, a.questions)
+        for q in r["per_question"]:
+            if q["leaked"] or q["missing"]:
+                print(f"{q['id']}: asked {q['asked_at'][:10]}, " + ", ".join(f"{l['id']} known {l['known_at'][:10]} ({l['reason']})" for l in q["leaked"])
+                      + (f", missing {q['missing']}" if q["missing"] else ""))
+        print(f"{r['leaked_questions']}/{r['questions']} questions leak ({r['leak_rate']:.0%}), {r['leaked_blocks']} blocks learned after the question"
+              + (f", {r['missing_blocks']} evidence ids not in the bundle" if r["missing_blocks"] else ""))
+        sys.exit(1 if r["leaked_questions"] else 0)
+    elif a.cmd == "validate":
+        checks = validate(a.bundle)
+        for c in checks:
+            print(f"{'ok  ' if c.ok else 'FAIL'} {c.check_id:<20} {c.detail}")
+        sys.exit(0 if all(c.ok for c in checks) else 1)
+    elif a.cmd == "sync":
+        token = a.token or os.environ.get("TCKG_TOKEN") or p.error("--token or $TCKG_TOKEN is required")
+        r = sync(a.bundle, TckgStore(a.url, token, a.space), a.as_of, push=not a.pull_only, pull=not a.push_only)
+        pu, pl = r["pushed"], r["pulled"]
+        parts = []
+        if pu is not None:
+            parts.append(f"pushed {pu['accepted']} rows in {pu['batches']} batches" + (f", {len(pu['skipped'])} already there" if pu["skipped"] else "")
+                         + (f", {len(pu['refused'])} refused" if pu["refused"] else "") + (f", {pu['resolutions_not_pushed']} resolutions kept local" if pu["resolutions_not_pushed"] else ""))
+        if pl is not None:
+            parts.append(f"pulled {pl['nodes']} nodes, {pl['edges']} edges, {pl['resolutions']} resolutions")
+        print(f"{a.bundle} <-> {a.url}: " + "; ".join(parts) + f" (as of {r['as_of'][:19]})")
+        for x in (pu or {}).get("refused", []):
+            print(f"  refused {x}")
+        sys.exit(1 if pu and pu["refused"] else 0)
+    elif a.cmd == "to-claimreview":
+        out_json(to_claimreview(a.bundle, a.as_of, a.base_url, a.valid_at))
+    elif a.cmd == "to-okf":
+        out = to_okf(a.bundle, a.as_of, a.out, a.valid_at)
+        print(f"wrote {out}: {len(list(out.glob('*.md')))} documents")
+    elif a.cmd == "to-parquet":
+        out = write_parquet(a.bundle, a.out)
+        print(f"wrote {out}: {sorted(x.name for x in out.iterdir())}")
+    elif a.cmd == "from-factcheck":
+        if a.from_json:
+            d = json.load(open(a.from_json))
+            claims = d.get("claims", []) if isinstance(d, dict) else d
+        elif a.query:
+            key = a.api_key or os.environ.get("FACTCHECK_API_KEY") or p.error("--api-key or $FACTCHECK_API_KEY is required with --query")
+            claims = factcheck_search(a.query, key, a.language, a.pages)
+        else:
+            p.error("one of --query or --from-json is required")
+        existing = Bundle(a.out) if (pathlib.Path(a.out) / "factblock.json").exists() else None
+        r = bundle_from_factcheck(claims, existing, a.namespace)
+        write_bundle(r, a.out, append=True)
+        s_ = r["summary"]
+        print(f"{a.out}: +{s_['claims']} claims, +{s_['verdicts']} verdicts, {s_['batches']} batches")
+
+
+def run():
+    try:
+        main()
+    except BrokenPipeError:        # `factblock scan ... | head`
+        sys.stderr.close()
+
+
+if __name__ == "__main__":
+    run()

factblock/adapters/__init__.py

@@ -0,0 +1,2 @@
+"""Writers that turn another store's data into a FactBlock bundle (SPEC 6: a writer that
+is not a ledger declares backfill batches; it never invents known_at)."""

factblock/adapters/factcheck.py

@@ -0,0 +1,106 @@
+"""Fact-check feeds -> FactBlock bundle (SPEC 9.2, reverse direction). Reads the shape of Google's
+Fact Check Tools API (claims:search): a claim with `text`, `claimant`, `claimDate` and its
+`claimReview[]` with `publisher`, `url`, `title`, `reviewDate`, `textualRating`. Each claim becomes a
+node, each review a resolution row. The feed's dates are self-reported, so every row is written
+under a backfill batch declared at its review date (section 6): the claim became known to the
+fact-checking world when it was first reviewed, and each verdict when it was published.
+
+    bundle_from_factcheck(claims, existing=None) -> {"manifest", "nodes", "edges", "resolutions"}
+    search(query, api_key, language=None, pages=1)  -> claims   # the live API; needs a Google API key
+"""
+import hashlib
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from datetime import datetime, timezone
+
+from ..bundle import parse_instant
+
+LEDGER = "factblock-factcheck-adapter/0.1"
+API = "https://factchecktools.googleapis.com/v1alpha1/claims:search"
+#  textualRating, lowercased and stripped of punctuation -> recommended outcome (SPEC 3.6). Unknown ratings keep value only.
+OUTCOMES = {"true": "true", "correct": "true", "accurate": "true", "mostly true": "mostly_true", "mostly correct": "mostly_true",
+            "partly true": "mostly_true", "partially true": "mostly_true", "half true": "misleading", "misleading": "misleading",
+            "missing context": "misleading", "mostly false": "mostly_false", "partly false": "mostly_false", "false": "false",
+            "incorrect": "false", "pants on fire": "false", "fake": "false", "unproven": "unverifiable", "unverifiable": "unverifiable",
+            "unsupported": "unverifiable", "no evidence": "unverifiable"}
+
+
+def _iso(v):
+    d = parse_instant(v)
+    return d.astimezone(timezone.utc).isoformat()
+
+
+def _outcome(rating):
+    key = "".join(c if c.isalnum() or c == " " else " " for c in (rating or "").lower()).split()
+    return OUTCOMES.get(" ".join(key))
+
+
+def search(query, api_key, language=None, pages=1, page_size=100):
+    """claims:search, following nextPageToken up to `pages` times. Returns the raw claim dicts."""
+    out, token = [], None
+    for _ in range(pages):
+        q = {"query": query, "key": api_key, "pageSize": page_size, **({"languageCode": language} if language else {}), **({"pageToken": token} if token else {})}
+        try:
+            with urllib.request.urlopen(API + "?" + urllib.parse.urlencode(q), timeout=60) as resp:
+                d = json.load(resp)
+        except urllib.error.HTTPError as e:      # Google puts the reason in the body; show it instead of a bare status
+            body = e.read().decode(errors="replace")
+            try:
+                body = json.loads(body)["error"]["message"]
+            except (ValueError, KeyError, TypeError):
+                pass
+            raise RuntimeError(f"Fact Check Tools API: HTTP {e.code}: {body}") from None
+        out += d.get("claims", [])
+        token = d.get("nextPageToken")
+        if not token:
+            break
+    return out
+
+
+def bundle_from_factcheck(claims, existing=None, namespace="factcheck", captured_at=None) -> dict:
+    captured_at = _iso(captured_at or datetime.now(timezone.utc))
+    have_nodes = {n["id"] for n in (existing.nodes if existing else [])}
+    have_res = {(r["target_id"], r["decided_at"].isoformat()) for r in (existing.resolutions if existing else [])}
+    batches, nodes, resolutions = {}, [], []
+
+    def stamp(at):
+        batches.setdefault(at, f"factcheck-{at[:10]}-{hashlib.sha1(at.encode()).hexdigest()[:6]}")
+        return {"known_at": at, "attestation": {"ledger": LEDGER, "batch": batches[at]}}
+
+    for c in claims:
+        reviews = [r for r in c.get("claimReview", []) if r.get("reviewDate")]
+        if not c.get("text") or not reviews:
+            continue
+        reviews.sort(key=lambda r: r["reviewDate"])
+        first = _iso(reviews[0]["reviewDate"])
+        asserted = _iso(c["claimDate"]) if c.get("claimDate") else first
+        nid = hashlib.sha1(f"{c['text']}|{c.get('claimant', '')}|{asserted}".encode()).hexdigest()[:16]
+        if nid not in have_nodes:
+            have_nodes.add(nid)
+            payload = {"language": reviews[0].get("languageCode")}
+            if c.get("claimant"):
+                payload["speaker"] = c["claimant"]
+            nodes.append({"id": nid, "kind": "claim", "statement": c["text"], "payload": {k: v for k, v in payload.items() if v},
+                          "asserted_at": asserted, "valid_from": asserted, "valid_to": None, **stamp(first)})
+        for r in reviews:
+            decided = _iso(r["reviewDate"])
+            if (nid, decided) in have_res:
+                continue
+            have_res.add((nid, decided))
+            pub = r.get("publisher") or {}
+            row = {"target_id": nid, "value": r.get("textualRating"), "method": "claimreview", "decided_at": decided, **stamp(decided),
+                   "evidence": [{"type": "FACT_CHECK", "url": r.get("url"), "title": r.get("title"), "publisher": pub.get("name"), "published_at": decided}]}
+            if pub.get("site"):
+                row["resolver"] = f"org:{pub['site']}"
+            if _outcome(r.get("textualRating")):
+                row["outcome"] = _outcome(r["textualRating"])
+            resolutions.append(row)
+    manifest = {"factblock_version": "1.0-draft.1", "namespace": namespace, "source": LEDGER, "exported_as_of": captured_at,
+                "tables": {"nodes": "nodes.jsonl", "edges": "edges.jsonl", "resolutions": "resolutions.jsonl"},
+                "declarations": {"facts": [], "edge_types": [], "embedding": None,
+                                 "backfills": [{"batch": name, "declared_known_at": at, "reason": "fact-check feed: the publisher's review date is self-reported",
+                                                "declared_by": "process:" + LEDGER, "captured_at": captured_at} for at, name in sorted(batches.items())]}}
+    return {"manifest": manifest, "nodes": nodes, "edges": [], "resolutions": resolutions,
+            "summary": {"claims": len(nodes), "verdicts": len(resolutions), "batches": len(batches)}}

factblock/adapters/graphiti.py

@@ -0,0 +1,110 @@
+"""Graphiti (Zep) graph -> FactBlock bundle. The second implementation of the format:
+it reads Graphiti's own objects, not tckg, and depends on nothing but the duck-typed
+attributes below, so it runs against any Graphiti backend (Neo4j, FalkorDB, Kuzu).
+
+Mapping (SPEC.md 3; tckg's memory/tckg_driver is the reverse direction):
+  group_id                 -> space
+  EpisodicNode             -> node kind=episode   (statement=name, asserted_at=valid_at)
+  EntityNode               -> node kind=entity    (statement=name)
+  EntityEdge (a fact)      -> node kind=claim     (statement=fact, valid=[valid_at, invalid_at))
+                              + claim MENTIONS source entity, claim MENTIONS target entity
+                              + claim DERIVED_FROM each episode it came from
+  EpisodicEdge             -> edge episode MENTIONS entity
+  created_at               -> known_at, attested by one backfill batch per distinct created_at:
+                              Graphiti stamps created_at itself, so it is self-reported (SPEC 6, 9)
+Embeddings are not exported: the bundle cannot name the model (declarations.embedding is null).
+"""
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+LEDGER = "factblock-graphiti-adapter/0.1"
+
+
+def _iso(d):
+    if d is None:
+        return None
+    if d.tzinfo is None:
+        d = d.replace(tzinfo=timezone.utc)
+    return d.astimezone(timezone.utc).isoformat()
+
+
+def _enum(v):
+    return getattr(v, "value", v)
+
+
+def bundle_from_graphiti(entities, episodes, facts, episodic_edges, exported_at=None) -> dict:
+    """Returns {"manifest", "nodes", "edges"} as plain dicts; write_bundle() puts them on disk."""
+    exported_at = _iso(exported_at or datetime.now(timezone.utc))
+    # Batches are numbered in time order, whatever order the store returned rows in,
+    # so an importer that applies them by number applies them chronologically and
+    # never sees an edge before its endpoints.
+    instants = sorted({_iso(x.created_at) for group in (entities, episodes, facts, episodic_edges) for x in group})
+    batches = {k: f"graphiti-{i + 1}" for i, k in enumerate(instants)}
+
+    def batch_for(created_at):
+        return batches[_iso(created_at)]
+
+    def stamp(created_at):
+        return {"known_at": _iso(created_at), "attestation": {"ledger": LEDGER, "batch": batch_for(created_at)}}
+
+    nodes, edges, spaces = [], [], set()
+    ids = set()
+    for e in episodes:
+        spaces.add(e.group_id); ids.add(e.uuid)
+        nodes.append({"id": e.uuid, "kind": "episode", "space": e.group_id, "statement": e.name,
+                      "payload": {"source": _enum(e.source), "source_description": e.source_description,
+                                  "content": e.content, "labels": list(getattr(e, "labels", []) or [])},
+                      "asserted_at": _iso(e.valid_at), "valid_from": _iso(e.valid_at), "valid_to": None, **stamp(e.created_at)})
+    for n in entities:
+        spaces.add(n.group_id); ids.add(n.uuid)
+        nodes.append({"id": n.uuid, "kind": "entity", "space": n.group_id, "statement": n.name,
+                      "payload": {"labels": list(getattr(n, "labels", []) or []), "summary": getattr(n, "summary", "") or "",
+                                  "attributes": dict(getattr(n, "attributes", {}) or {})},
+                      "asserted_at": _iso(n.created_at), "valid_from": _iso(n.created_at), "valid_to": None, **stamp(n.created_at)})
+    seen_edges = set()
+
+    def edge(src, dst, typ, when, created_at):
+        key = (src, dst, typ)
+        if key in seen_edges or src not in ids or dst not in ids:
+            return
+        seen_edges.add(key)
+        edges.append({"source_id": src, "target_id": dst, "edge_type": typ,
+                      "asserted_at": _iso(when), "valid_from": _iso(when), "valid_to": None, **stamp(created_at)})
+
+    for f in facts:
+        spaces.add(f.group_id); ids.add(f.uuid)
+        start = f.valid_at or f.created_at
+        end = f.invalid_at if (f.invalid_at and start and f.invalid_at > start) else None
+        payload = {"name": f.name, "episodes": list(f.episodes or []), "attributes": dict(getattr(f, "attributes", {}) or {})}
+        if getattr(f, "expired_at", None):
+            payload["graphiti_expired_at"] = _iso(f.expired_at)
+        if f.invalid_at and end is None:
+            payload["graphiti_invalid_at"] = _iso(f.invalid_at)     # kept, not applied: it did not follow valid_at
+        nodes.append({"id": f.uuid, "kind": "claim", "space": f.group_id, "statement": f.fact, "payload": payload,
+                      "asserted_at": _iso(start), "valid_from": _iso(start), "valid_to": _iso(end), **stamp(f.created_at)})
+    for f in facts:
+        start = f.valid_at or f.created_at
+        edge(f.uuid, f.source_node_uuid, "MENTIONS", start, f.created_at)
+        edge(f.uuid, f.target_node_uuid, "MENTIONS", start, f.created_at)
+        for ep in f.episodes or []:
+            edge(f.uuid, ep, "DERIVED_FROM", start, f.created_at)
+    for x in episodic_edges:
+        edge(x.source_node_uuid, x.target_node_uuid, "MENTIONS", x.created_at, x.created_at)
+
+    manifest = {
+        "factblock_version": "1.0-draft.1",
+        "namespace": "graphiti/" + ",".join(sorted(spaces)),
+        "source": LEDGER,
+        "exported_as_of": exported_at,
+        "tables": {"nodes": "nodes.jsonl", "edges": "edges.jsonl"},
+        "declarations": {
+            "facts": [],
+            "backfills": [{"batch": b, "declared_known_at": k, "reason": "Graphiti created_at, self-reported by the source store",
+                           "declared_by": "process:" + LEDGER, "captured_at": exported_at} for k, b in batches.items()],
+            "edge_types": [], "embedding": None},
+    }
+    return {"manifest": manifest, "nodes": nodes, "edges": edges}
+
+
+from ..bundle import write_bundle  # noqa: E402,F401  (kept here for callers that imported it from the adapter)

factblock/bundle.py

@@ -0,0 +1,89 @@
+"""Load a bundle (SPEC 5.1): manifest plus node, edge, resolution tables as lists of dicts."""
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+INSTANT_KEYS = ("asserted_at", "valid_from", "valid_to", "known_at", "decided_at")
+
+
+def parse_instant(v):
+    """RFC 3339 string -> aware datetime. None stays None."""
+    if v is None or isinstance(v, datetime):
+        return v
+    d = datetime.fromisoformat(v.replace("Z", "+00:00"))
+    return d if d.tzinfo else d.replace(tzinfo=timezone.utc)
+
+
+def _read_table(path: Path) -> list[dict]:
+    if not path.exists():
+        return []
+    if path.suffix == ".parquet":
+        import pyarrow.parquet as pq
+        from .parquet import decode_parquet_row
+        rows = [decode_parquet_row(r) for r in pq.read_table(path).to_pylist()]
+    else:
+        with path.open() as f:
+            rows = [json.loads(line) for line in f if line.strip()]
+    for r in rows:
+        for k in INSTANT_KEYS:
+            if k in r:
+                r[k] = parse_instant(r[k])
+    return rows
+
+
+class Bundle:
+    def __init__(self, path):
+        self.path = Path(path)
+        self.manifest = json.loads((self.path / "factblock.json").read_text())
+        tables = self.manifest.get("tables", {})
+        self.nodes = _read_table(self.path / tables.get("nodes", "nodes.jsonl"))
+        self.edges = _read_table(self.path / tables.get("edges", "edges.jsonl"))
+        self.resolutions = _read_table(self.path / tables.get("resolutions", "resolutions.jsonl"))
+        d = self.manifest.get("declarations", {})
+        self.facts = {}
+        for f in d.get("facts", []):
+            f["declared_at"] = parse_instant(f.get("declared_at"))
+            self.facts.setdefault(f["fact_key"], []).append(f)
+        self.backfills = {b["batch"]: b for b in d.get("backfills", [])}
+        for b in self.backfills.values():
+            b["declared_known_at"] = parse_instant(b["declared_known_at"])
+        self.edge_types = {e["edge_type"]: e["family"] for e in d.get("edge_types", [])}
+
+    def blocks(self):
+        """Every block with a table label: nodes, edges, resolutions."""
+        for r in self.nodes:
+            yield "node", r
+        for r in self.edges:
+            yield "edge", r
+        for r in self.resolutions:
+            yield "resolution", r
+
+
+def write_bundle(result: dict, out, append: bool = False) -> Path:
+    """Put {"manifest", "nodes", "edges", "resolutions"?} on disk as a JSONL bundle. With append=True and a bundle
+    already at `out`, rows are added and the manifest's declarations are merged, so a folder grows
+    one batch at a time and stays valid."""
+    out = Path(out); out.mkdir(parents=True, exist_ok=True)
+    mpath = out / "factblock.json"
+    manifest = result["manifest"]
+    if append and mpath.exists():
+        old = json.loads(mpath.read_text())
+        for key in ("facts", "backfills", "edge_types"):
+            have = {json.dumps(x, sort_keys=True) for x in old["declarations"].get(key, [])}
+            old["declarations"][key] = old["declarations"].get(key, []) + [x for x in manifest["declarations"].get(key, []) if json.dumps(x, sort_keys=True) not in have]
+        old["exported_as_of"] = manifest.get("exported_as_of", old.get("exported_as_of"))
+        manifest = old
+        mode = "a"
+    else:
+        mode = "w"
+    tables = manifest.setdefault("tables", {})
+    tables.setdefault("nodes", "nodes.jsonl"); tables.setdefault("edges", "edges.jsonl")
+    if result.get("resolutions"):
+        tables.setdefault("resolutions", "resolutions.jsonl")
+    mpath.write_text(json.dumps(manifest, indent=1) + "\n")
+    for name in ("nodes", "edges", "resolutions"):
+        rows = result.get(name, [])
+        if name in tables and (rows or (mode == "w" and name != "resolutions")):
+            with (out / tables[name]).open(mode) as f:
+                f.write("".join(json.dumps({k: v for k, v in r.items() if not k.startswith("_")}, default=lambda d: d.isoformat()) + "\n" for r in rows))
+    return out

factblock/claimreview.py

@@ -0,0 +1,64 @@
+"""SPEC 9: the ClaimReview projection. Every verdict visible as of an instant becomes one schema.org
+ClaimReview (JSON-LD), the shape Google's fact-check tools, Meta's programme and ClaimReview-aware
+CMSs consume. Lossy by design: one verdict per block (the latest), no chain, no interval. What
+ClaimReview cannot say travels under `factblock:` keys that a consumer may ignore."""
+from .bundle import Bundle, parse_instant
+from .scan import _as_of, _visible, scan
+
+#  outcome -> (alternateName, ratingValue on a 1..5 scale, or None when the scale does not apply)
+RATINGS = {
+    "true": ("True", 5), "mostly_true": ("Mostly true", 4), "mostly_false": ("Mostly false", 2), "false": ("False", 1),
+    "misleading": ("Misleading", 2), "unverifiable": ("Unverifiable", None),
+    "came_true": ("Came true", 5), "partial": ("Partially came true", 3), "did_not": ("Did not come true", 1), "undecidable": ("Undecidable", None),
+}
+
+
+def _actor(a):
+    if not a:
+        return None
+    name = a.split(":", 1)[1] if a.startswith(("human:", "process:", "org:")) else a.split("/", 1)[0]
+    return {"@type": "Person" if a.startswith("human:") else "Organization", "name": name}
+
+
+def _rating(r):
+    outcome = r.get("outcome") or (r["value"] if isinstance(r.get("value"), str) else None)
+    name, value = RATINGS.get(outcome, (str(outcome) if outcome is not None else str(r.get("value")), None))
+    out = {"@type": "Rating", "alternateName": name}
+    if value is not None:
+        out.update({"ratingValue": value, "bestRating": 5, "worstRating": 1})
+    return out
+
+
+def to_claimreview(bundle, as_of, base_url=None, valid_at=None) -> dict:
+    b = bundle if isinstance(bundle, Bundle) else Bundle(bundle)
+    s = scan(b, as_of, valid_at)
+    t = _as_of(as_of); v = parse_instant(valid_at) if valid_at else t
+    nodes = {n["id"]: n for n in b.nodes}
+    latest = {}
+    for r in sorted((r for r in b.resolutions if _visible(r, t, v)), key=lambda r: (r["decided_at"], r["known_at"])):
+        latest[r["target_id"]] = r          # ClaimReview has no history: the latest verdict stands for the block
+    reviews = []
+    for tid, r in latest.items():
+        n = nodes.get(tid)
+        if n is None:
+            continue
+        payload = n.get("payload") or {}
+        source = payload.get("source") if isinstance(payload.get("source"), dict) else {}
+        claim = {"@type": "Claim", "datePublished": n["asserted_at"].date().isoformat()}
+        if payload.get("speaker"):
+            claim["author"] = {"@type": "Person", "name": payload["speaker"]}
+        elif n.get("author"):
+            claim["author"] = _actor(n["author"])
+        if source.get("url"):
+            claim["appearance"] = {"@type": "CreativeWork", "url": source["url"], **({"name": source["title"]} if source.get("title") else {})}
+        cr = {"@type": "ClaimReview", "claimReviewed": n.get("statement"), "datePublished": r["decided_at"].date().isoformat(),
+              "itemReviewed": claim, "reviewRating": _rating(r), "factblock:id": tid, "factblock:kind": n["kind"],
+              "factblock:known_at": r["known_at"].isoformat()}
+        if _actor(r.get("resolver")):
+            cr["author"] = _actor(r["resolver"])
+        if base_url:
+            cr["url"] = f"{base_url.rstrip('/')}/{tid}"
+        if r.get("method"):
+            cr["factblock:method"] = r["method"]
+        reviews.append(cr)
+    return {"@context": "https://schema.org", "@graph": reviews, "factblock:certificate": s.certificate}