factblock 1.0.0a1__tar.gz

factblock-1.0.0a1/.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,18 @@
+---
+name: Bug
+about: Something reads, writes or validates differently from what SPEC.md says
+title: ""
+labels: bug
+---
+
+**What you ran**
+
+```
+factblock ... 
+```
+
+**What came out, and what you expected**
+
+**A bundle that shows it** (a few JSONL lines are enough; `factblock sample` plus one edit is ideal)
+
+**Version**: `pip show factblock` or the commit, and Python version.

factblock-1.0.0a1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Question
+    url: https://github.com/factagora/factblock/discussions
+    about: How to use it, what a field means, whether something fits the format

factblock-1.0.0a1/.github/ISSUE_TEMPLATE/writer.md

@@ -0,0 +1,15 @@
+---
+name: New writer, reader or projection
+about: Propose an adapter for a store or feed, or a projection to another standard
+title: ""
+labels: proposal
+---
+
+**What it reads or writes** (the store, feed or standard, with a link to its format)
+
+**How its clocks map**: where `asserted_at`, `valid_from`/`valid_to` and `known_at` come from, and what is
+self-reported (self-reported knowledge time becomes a declared backfill batch, SPEC.md section 6).
+
+**What the projection loses**, if it is a projection.
+
+**Will you maintain it?** A writer or reader maintained outside this repository is what takes the format to 1.0.0.

factblock-1.0.0a1/.github/social-preview.html

@@ -0,0 +1,22 @@
+<!doctype html><html><head><meta charset="utf-8"><style>
+*{margin:0;padding:0;box-sizing:border-box}
+body{width:1280px;height:640px;background:#1e1e2e;color:#cdd6f4;font-family:"DejaVu Sans Mono",Menlo,monospace;padding:64px 72px 56px;display:flex;flex-direction:column;justify-content:space-between}
+h1{font-size:76px;font-weight:700;letter-spacing:-1px;color:#cdd6f4}
+h1 span{color:#89b4fa}
+.tag{margin-top:14px;font-size:30px;color:#bac2de;line-height:1.35}
+.tag b{color:#f9e2af;font-weight:700}
+.term{border:1px solid #45475a;border-radius:8px;padding:22px 26px;font-size:19px;line-height:1.55;background:#181825}
+.p{color:#a6e3a1}.d{color:#6c7086}.r{color:#f5c2e7}.c{color:#89dceb}
+.foot{display:flex;justify-content:space-between;font-size:20px;color:#7f849c}
+</style></head><body>
+<div><h1>Fact<span>Block</span></h1>
+<div class="tag">Agent memory for decisions. A temporal causal knowledge graph<br>that remembers <b>when</b> and <b>why</b> for your AI.</div></div>
+<div class="term">
+<div><span class="p">$</span> factblock why samples/cramer 1b77a1a8 --as-of 2026-09-10</div>
+<div><span class="r">subject</span>: <span class="d">2025-07-17</span>  The data center buildout is the largest construction boom since WWII.</div>
+<div>&nbsp;&nbsp;&nbsp;&nbsp;<span class="r">effect (CAUSES)</span>: <span class="d">2025-07-17</span>  Lead contractors are receiving strong data center orders.</div>
+<div>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="r">effect (CAUSES)</span>: <span class="d">2025-07-17</span>  Eaton is a good stock to own.</div>
+<div><span class="c">as of 2025-01-01: not_yet</span>   <span class="d">hidden: 1790 blocks learned later</span></div>
+</div>
+<div class="foot"><span>github.com/factagora/factblock</span><span>pip install factblock · Apache-2.0</span></div>
+</body></html>

factblock-1.0.0a1/.github/workflows/release.yml

@@ -0,0 +1,18 @@
+name: release
+on:
+  push:
+    tags: ["v*"]
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync
+      - run: for t in tests/test_*.py; do uv run python $t; done
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

factblock-1.0.0a1/.github/workflows/test.yml

@@ -0,0 +1,20 @@
+name: test
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync
+      - run: uv run python tests/test_rates.py
+      - run: uv run python tests/test_graphiti_adapter.py
+      - run: uv run python tests/test_duckdb.py
+      - run: uv run python tests/test_extract.py
+      - run: uv run python tests/test_why.py
+      - run: uv run python tests/test_leak.py
+      - run: uv run python tests/test_recall.py
+      - run: uv run python tests/test_sync.py
+      - run: uv run python tests/test_claimreview.py
+      - run: uv run python tests/test_okf.py
+      - run: uv run python tests/test_factcheck.py

factblock-1.0.0a1/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+.DS_Store

factblock-1.0.0a1/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## 1.0-draft.1 (2026-10-04)
+
+First public draft of the format and the reference library.
+
+- Five invariants (three clocks, attested knowledge time, append-only, typed edges, declared facts) with one validator check id each.
+- Logical model: node, edge, resolution, declarations (facts, backfill batches, edge types, embedding model).
+- JSONL and Parquet profiles; Parquet files sorted by `known_at`, unknown fields kept in `extra`.
+- Read semantics: as-of with certificate, `valid_at` defaulting to `as_of`, supersession, `resolve` by declared policy, expansion.
+- Readers: the Python library (`scan`, `validate`, `resolve`, `write_parquet`) and the DuckDB macro pack.
+- Writers: the tckg ledger (`GET /v1/export`) and the Graphiti adapter.
+
+### Added (2026-10-05)
+- `factblock extract`: text in, a batch of blocks out, through a model you choose (`gemini`, `openai`, or `fake` for offline runs). The claims profile lives in `factblock/profiles/claims/` as three files (instructions, output schema, edge types) so other languages run the same extraction. Every extract declares one backfill batch (SPEC 6: a non-ledger writer never invents `known_at`).
+- `write_bundle(result, out, append=True)` in `factblock.bundle`: a folder grows one batch at a time and stays valid; entities are reused across batches.
+- README rewritten as the project's front door: agent memory for decisions.
+- `factblock why <bundle> <node_id> --as-of T [--valid-at T] [--depth N]` and `factblock.why()`: the chain behind one block on files, mirroring tckg's `why`. Both directions over causal, argumentative and temporal edges, a role at every hop, `not_yet` or `absent` when the root is not visible yet (SPEC 4.5).
+- `factblock leak <bundle> <questions.jsonl>` and `factblock.leak()`: for a question set with `asked_at` and the block ids each answer rests on, which answers depend on blocks learned after the question was asked (`known_later`) or not in force then (`not_in_force`), per question and as a rate. Exit code 1 on any leak. Sample set: `samples/rates-questions.jsonl`.
+- `factblock sync <bundle> <url> --space S [--token T] [--as-of T] [--push-only | --pull-only]` and `factblock.sync(bundle, store)`: a folder and a store, both ways, by identity. Rows only the folder has go up under the folder's batches; rows only the store has come down with the store's `known_at`; a second run is a no-op; `--pull-only` into a new folder clones a space. `Store` is a two-method protocol (`pull`, `push`); `TckgStore` speaks tckg's HTTP API with no dependency beyond the standard library. SPEC 6.1 states the import rule (declare the bundle's batches, never adopt a row as learned now).
+- `write_bundle` writes a `resolutions` table when given one and serialises datetimes.
+- `factblock to-claimreview <bundle> --as-of T [--base-url U]` and `factblock.to_claimreview()`: the verdicts visible as of an instant as schema.org ClaimReview JSON-LD (SPEC 9.2). Latest verdict per block, ratings from the new recommended `outcome` vocabulary (SPEC 3.6), the rest under `factblock:` keys.
+- SPEC 3.1 names the payload conventions `extract` already writes (`speaker`, `quote`, `source`); SPEC 3.6 adds the recommended verdict vocabulary and the evidence element shape; SPEC 9 becomes two projections (OKF, ClaimReview) with the reverse-direction rule for fact-check feeds.
+- `samples/rates` gains a `resolutions` table: two verdicts and one re-resolution, ledger-stamped, so as-of reads hide verdicts learned later.
+- `factblock to-okf <bundle> <out> --as-of T` and `factblock.to_okf()`: one OKF v0.2 concept document per visible node, relations as links with the relation in prose, `index.md` with the certificate, `log.md` in `known_at` order (SPEC 9.1). No YAML dependency: JSON is YAML.
+- `factblock from-factcheck -o <bundle> (--query Q | --from-json FILE)` and `factblock.adapters.factcheck`: fact-checks in the Fact Check Tools API shape become claim nodes and verdict rows, each under a batch declared at its review date; `textualRating` is normalised to the recommended vocabulary where it fits and kept verbatim as `value`; re-import adds nothing. Live search needs `$FACTCHECK_API_KEY`.
+- SPEC 3.5 adds the `org:<id>` actor shape for publishers and institutions.
+- CLI: `factblock sample <dir>` copies the sample bundle (shipped in the wheel); `scan`, `why` and `resolve` print for people by default and take `--json`; every subcommand has help text and they are listed in the order you meet them. `extract` writes 8-character ids you can type.
+- Repository: CONTRIBUTING (DCO), RELEASING, CODE_OF_CONDUCT, issue templates.
+- `factblock recall <bundle> "<query>" --as-of T [--limit N] [--all-kinds]` and `factblock.recall()` / `factblock.context()`: the blocks about something as of an instant, ranked by query hits then recency, with the certificate. Keyword matching only; no embeddings yet.
+- `samples/cramer`: a real bundle. Jim Cramer on CNBC, 2024-09 to 2026-09: 2,091 blocks under one backfill batch per recording, 1,169 typed links, 779 calls settled at their horizon as resolution rows. README's "What comes out" shows it. The reader test reads it at three instants.
+- CLI exits quietly when its output pipe closes (`| head`).
+- `bench/streamingqa`: the hindsight number. StreamingQA's 36,378 dated questions as dated blocks; a time-ignorant top-5 recall leaks on 79.7% of questions (41.8% of picks), the as-of recall on none. `factblock.scan` now wraps a table-free `visible()` and `recall` keeps per-node word sets; a recall over 36,378 blocks takes under a second

factblock-1.0.0a1/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Code of conduct
+
+This project is a place to work on a format and a library. Everyone is welcome to report, ask, propose and
+contribute, whoever they are and wherever they come from.
+
+**Expected**: be direct and be kind. Disagree with the idea, not the person. Assume the other side has a reason
+you have not heard yet. Say what you need; answer what was asked.
+
+**Not accepted**: harassment, personal attacks, discriminatory remarks, publishing someone's private information,
+and sustained disruption of a thread after being asked to stop.
+
+Maintainers may edit or remove comments, close threads and, for repeated or severe cases, block an account from
+the repository. Report a problem to randy@factagora.com; reports are read by a person and handled in private.

factblock-1.0.0a1/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing
+
+FactBlock is a format first and a library second. The spec ([SPEC.md](./SPEC.md)) is normative; the
+Python package is the reference implementation. A change to one usually means a change to the other.
+
+## Before you open a pull request
+
+```bash
+uv sync
+for t in tests/test_*.py; do uv run python $t; done     # the same checks CI runs
+uv run python -m factblock validate samples/rates
+```
+
+Every test file is one script that prints `PASS ...` or raises. Add a check to the file that covers
+what you changed, or a new `tests/test_<thing>.py` and a line in `.github/workflows/test.yml`.
+
+## What goes where
+
+- **A new field or rule**: SPEC.md first (section 3 or 4), with its validator check id in section 2 or 8,
+  then `factblock/validate.py` and a case in `tests/test_rates.py`. Minor versions add fields; they never
+  change the meaning of an existing one (section 7).
+- **A new writer or reader** (an adapter for another store or feed): `factblock/adapters/<name>.py`,
+  one test with a synthetic fixture under `tests/fixtures/`, a line in SPEC.md section 10. The one rule
+  every writer keeps is section 6: never invent `known_at`; declare a backfill batch instead.
+- **A new projection** (another standard a bundle should speak): `factblock/<name>.py`, a subsection
+  under SPEC.md section 9 with the mapping table and what the projection loses.
+- **Extraction rules** live in `factblock/profiles/claims/` as three files, not in code, so that other
+  languages run the same extraction. Change the files; keep `extract.py` thin.
+
+No new runtime dependencies without a reason in the pull request. The core depends on `pyarrow` only;
+model SDKs are optional extras.
+
+## Developer Certificate of Origin
+
+Contributions are accepted under the [Developer Certificate of Origin 1.1](https://developercertificate.org/):
+by signing off a commit you state that you wrote the change or have the right to submit it under the
+project's license (Apache-2.0). Sign off with `git commit -s`, which adds
+
+```
+Signed-off-by: Your Name <you@example.com>
+```
+
+There is no separate contributor agreement.
+
+## Style
+
+Short files, plain functions, no abstractions for one caller. Prose in English, sentence case, no em
+dashes. A module docstring says what the file does and which SPEC section it implements.

factblock-1.0.0a1/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

factblock-1.0.0a1/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.5
+Name: factblock
+Version: 1.0.0a1
+Summary: Agent memory for decisions: extract dated claims and their causal links into a temporal causal knowledge graph you can read as of any instant
+Project-URL: Homepage, https://github.com/factagora/factblock
+Project-URL: Specification, https://github.com/factagora/factblock/blob/main/SPEC.md
+Project-URL: Changelog, https://github.com/factagora/factblock/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/factagora/factblock/issues
+Project-URL: Hosted, https://docs.tckg.factagora.com
+Author-email: Factagora <randy@factagora.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agent-memory,arrow,as-of,bitemporal,knowledge-graph,parquet
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: pyarrow>=17
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.62; extra == 'gemini'
+Provides-Extra: openai
+Requires-Dist: openai>=1.50; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# FactBlock: agent memory for decisions
+
+[![test](https://github.com/factagora/factblock/actions/workflows/test.yml/badge.svg)](https://github.com/factagora/factblock/actions/workflows/test.yml) [![PyPI](https://img.shields.io/pypi/v/factblock)](https://pypi.org/project/factblock/) [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
+
+**A temporal causal knowledge graph that remembers *when* and *why* for your AI.**
+
+![factblock: scan, recall and why over two years of Jim Cramer's calls, read as of different days](./samples/demo.gif)
+
+Your data is full of claims: facts, opinions, predictions, promises. FactBlock extracts them, keeps when they were said and when you learned them, links what caused what, and never overwrites what changed. Your agent recalls them as of any moment, so it decides on what was knowable then, not on hindsight.
+
+```bash
+pip install factblock
+factblock sample brain/                               # six dated claims, a reversal, three verdicts
+factblock scan brain/ --as-of 2024-05-01              # what was known that day, and what was hidden
+factblock recall brain/ "interest rates" --as-of 2024-05-01   # the blocks about something, as of that day
+factblock why brain/ c3 --as-of 2024-10-01            # the causal chain behind a block
+factblock resolve brain/ belief:fed:direction --as-of 2024-10-01
+factblock extract transcript.txt --observed-at 2024-03-20 --speaker "Jim Cramer" --backfill -o brain/   # your model key, or --provider fake
+```
+
+```
+$ factblock why brain/ c3 --as-of 2024-10-01
+subject: c3  2024-06-20  Housing demand falls as mortgages track yields
+    cause (CAUSES): c2  2024-04-10  Bond yields rise after the rate hike
+        cause (CAUSES): c1  2024-03-20  The Fed raises interest rates
+            successor (SUPERSEDES): c4  2024-09-18  The Fed cuts interest rates
+as of 2024-10-01  hidden: 1 resolution  backfilled: 9 rows in 3 batches
+```
+
+Run the same command `--as-of 2024-05-01` and the chain stops at `c2`, because `c3` was not known yet. Add `--json` to any read for the machine form.
+
+```python
+import factblock
+print(factblock.context("brain/", "interest rates", as_of="2024-05-01"))
+# - 2024-03-20: The Fed raises interest rates
+# - 2024-04-10: Bond yields rise after the rate hike
+# (as of 2024-05-01; 9 later blocks hidden)
+```
+
+That string goes into your agent's prompt. `factblock.recall(...)` returns the same blocks as dicts with a certificate, and `factblock.scan(...)` returns everything visible as pyarrow tables.
+
+`brain/` is a folder of plain files. Commit it to git, query it with DuckDB, hand it to another agent, or [sync it with a hosted ledger](#same-files-hosted). Nothing here needs a server.
+
+## What comes out
+
+Two years of one public figure's statements, as files. [`samples/cramer`](./samples/cramer) is Jim Cramer on CNBC, 2024-09 to 2026-09: 2,091 blocks, 1,169 links he drew between them, 779 priced calls scored at their horizon. Every block links to the recording and the timestamp.
+
+```
+$ factblock scan samples/cramer --as-of 2025-01-01 | head -1
+as of 2025-01-01  hidden: 1790 nodes, 1025 edges, 753 resolutions  backfilled: 471 rows in 52 batches
+
+$ factblock why samples/cramer 1b77a1a885470207 --as-of 2026-09-10
+subject: 1b77a1a885470207  2025-07-17  The current data center buildout is the largest construction boom since World War II.
+    effect (CAUSES): c43aac6a842836bf  2025-07-17  Lead contractors such as ABB and Legrand are receiving strong data center orders.
+        effect (CAUSES): 041ef1dfd5dbb6df  2025-07-17  Companies involved in the data center buildout, such as Eaton and Parker-Hannifin, are receiving a large number of new orders.
+            effect (CAUSES): 2751ba237ecd5415  2025-07-17  Parker-Hannifin is a good stock to own.
+            effect (CAUSES): 7d3af08ba4f4f027  2025-07-17  Eaton is a good stock to own.
+```
+
+A call and its verdict carry separate clocks, so the same read gives different answers on different days:
+
+```
+66027d5985bf9605  prediction  2024-09-11  Nvidia's business is currently growing, not slowing down.   NVDA, up
+  verdict: came_true   decided 2024-12-10   NVDA +23.3% over 90 days   known 2024-12-10
+```
+
+As of 2024-11-01 the call is open. As of 2024-12-10 it came true. As of 2024-09-10 it does not exist yet. `to-claimreview samples/cramer --as-of 2025-06-01` writes the 197 verdicts known by then as schema.org JSON-LD.
+
+Every block carries two clocks: **asserted_at**, when it was said (`--observed-at` for `extract`), and **known_at**, when your system learned it. By default that is now, so a 2024 transcript extracted today is hidden from a 2024 read; `--backfill` declares it known when it was said, which is what you want for material from the past. `--provider fake` splits sentences without a model, enough to see the files; `gemini` and `openai` do the real extraction with your key. Every edge carries a type with a family (causal, argumentative, temporal) and the speaker's own confidence. Nothing is a chunk, nothing is a bare triple; the unit is a dated statement someone made.
+
+## When
+
+Memory that cannot answer "what did I know on that date" leaks the future into every evaluation and every backtest. FactBlock reads are always **as of** an instant:
+
+```python
+import factblock
+r = factblock.scan("brain/", as_of="2024-05-01")
+r.nodes                 # pyarrow.Table: only blocks known by 2024-05-01
+r.certificate           # {'as_of': ..., 'masked': {'node': 4, 'edge': 2}, 'backfill': {'batches': 1, 'rows': 3}}
+```
+
+The certificate says how many rows were hidden because they were learned later, and which rows were backfilled from the past under a declared batch. An answer with masking is a correct answer for that instant, and it says so.
+
+A statement that gets corrected or reversed is not overwritten. The new block points at the old one with `SUPERSEDES`, both keep their intervals, and a read as of a date in between still sees the old one. That is how "when did they change their mind" stays answerable.
+
+## Why
+
+Edges are the speaker's reasoning, not co-occurrence: `CAUSES`, `CONTRIBUTING_FACTOR`, `TRIGGERS`, `PREVENTS`, `SUPPORTS`, `CONTRADICTS`, `CONCURRENT_SIGNAL`, `SUPERSEDES`. `why` walks them from a block to the given depth, as of an instant, and names the role at every hop (`cause`, `effect`, `successor`, `contradiction`), so the chain never includes a reason that was not yet known.
+
+Declared facts make conflicts explicit. Declare `belief:fed:direction` with a policy (`latest_valid`, `latest_observed`, `source_priority`, `strict`) and `resolve` returns one value or the reason there is none: `no_data`, `not_yet`, `no_value_at`, `unresolved_conflict`. It never guesses.
+
+## Claims it is good at
+
+| Kind | Example | What you can ask that other memories cannot |
+|---|---|---|
+| **Prediction** | "Yields keep climbing this year" (podcast, 2024-03-20) | What did this person believe on 2024-03-20? Did it come true? When did they say the opposite? |
+| **Stance** | CEO: "No price increase this year" (Jan), "An increase is unavoidable" (Jul) | How did the company's position move? What did we know in May? |
+| **Fact that gets corrected** | "Q2 revenue was $4.1B", restated to $3.9B six weeks later | `resolve` as of August gives $4.1B, as of October $3.9B, as of July `no_data` |
+| **Commitment** | Sales: "We ship SSO by end of Q3" (to customer A) | Which promises to A are past due and unresolved? Recall them before the support agent answers |
+| **Your AI's own assertions** | Assistant: "Your plan includes 10 seats" (to user B) | Which of last month's assertions are now false? Where did each one come from? |
+
+The common thread: a claim has a speaker, a time, a reason, and a later verdict. RAG keeps chunks, entity graphs keep triples, chat memories keep summaries. None of them keep that.
+
+## Use it with your AI
+
+**Recall as context.** `recall` ranks the visible blocks about a query (keywords over statement, quote and speaker) and `context` turns them into prompt lines, with `as_of` set to the decision time (now, or a past instant for a backtest). `scan` returns everything visible as Arrow tables when you want to build your own.
+
+**Analytics.** `to-parquet` writes the Parquet profile. DuckDB reads it with no Python through [`duckdb/factblock.sql`](./duckdb/factblock.sql): `factblock_nodes(bundle, as_of)`, `factblock_edges`, `factblock_certificate`. Spark and Databricks read the same files.
+
+**From an existing graph.** [`factblock/adapters/graphiti.py`](./factblock/adapters/graphiti.py) turns a Graphiti graph into a bundle; the store's own timestamps become declared backfill batches, because a store that stamped time itself is a witness.
+
+**Speak the standards.** `to-claimreview` writes the verdicts visible as of an instant as schema.org ClaimReview JSON-LD; `to-okf` writes the blocks as an Open Knowledge Format bundle (markdown with frontmatter) that catalogs and agents read; `from-factcheck` brings published fact-checks in (Google's Fact Check Tools API shape) as dated claims with dated verdicts, every row under a batch declared at its review date. None of them is the storage format; they are doors.
+
+**Check your evals.** `leak` takes a question set with dates (`{asked_at, evidence: [block ids]}` per line) and reports how many answers depend on blocks learned after the question's date, naming each block and when it became known. It exits non-zero on a leak, so it fits in CI. On [StreamingQA](./bench/streamingqa) (36,378 dated questions about dated news), a recall that ignores time rests on a block learned after the question for **80% of questions**; the same recall as of the question date leaks nothing and says how much it hid. If your memory benchmark never reports this number, it is measuring hindsight.
+
+## Same files, hosted
+
+A folder is one writer's memory. [factagora.ai](https://factagora.ai) is where a `brain/` meets other people's. Upload it and it comes back with **more rows, never changed rows**: verdicts on predictions whose horizon has passed (mechanical ones from prices and published figures, judgment calls from the community, each with evidence), links to what other people claimed about the same thing (`SUPPORTS`, `CONTRADICTS`), entities resolved across worldviews. Every added row carries its own `known_at`, stamped by the server rather than by you, so a verdict is as replayable as the claim it judges: as of last June, the prediction was still open.
+
+It also gives what a folder cannot: one ledger shared by many agents and users, natural-language writes at scale, and an MCP address per worldview, so a user plugs one into Claude or Cursor and reaches nothing else. Browse public worldviews there, or ask one a question as of a date. `GET /v1/export` hands the folder back at any instant. The format is the contract; you can leave with your files.
+
+`factblock sync brain/ <url> --space <space>` moves rows both ways by identity: what only the folder has goes up, what only the ledger has comes down, nothing is changed in place. A row's `known_at` travels as the batch that attests it, so the ledger learns a 2024 transcript as known in 2024, not today, and the folder learns a verdict at the instant the ledger stamped it. Run it again and it is a no-op. `--pull-only` into a folder that does not exist yet clones a space. The token is `$TCKG_TOKEN` or `--token`.
+
+**Bring your own store.** `sync` talks to a store through two methods, `pull(as_of)` and `push(manifest, nodes, edges)` ([`factblock/sync.py`](./factblock/sync.py), the `Store` protocol). `TckgStore` is the one for tckg over HTTP; [`tests/test_sync.py`](./tests/test_sync.py) has a forty-line in-memory one that shows the single rule a store has to keep: declare the bundle's batches as your own backfill batches, never adopt an imported row as learned now. A SQLite, Neo4j, or warehouse store is the same two methods.
+
+The same ledger runs closed for companies at [app.factagora.com](https://app.factagora.com): your support logs, your sales promises, your own assistant's assertions, as claims with verdicts, inside your tenant.
+
+## The format
+
+[`SPEC.md`](./SPEC.md) is short. Five invariants (present, attested, unique, typed, declared), a JSONL profile and a Parquet profile, read semantics, and the conformance checks `validate` runs (eleven of them). Projections to OKF and ClaimReview are described, and `to-claimreview` writes the verdicts visible as of an instant as schema.org JSON-LD, so a bundle can feed systems that speak those.
+
+Format, not platform. Apache-2.0. tckg is one writer of this format; nothing here requires it. Contributions are welcome under the DCO: see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Status
+
+`1.0-draft.1`. Works today: `extract` (providers `gemini`, `openai`, and `fake` for offline runs; the claims profile is three files under [`factblock/profiles/claims`](./factblock/profiles/claims) that any language can run), `validate`, `scan`, `recall`, `why`, `leak`, `resolve`, `to-parquet`, `sync` with a tckg ledger or a store of your own, `to-claimreview`, `to-okf`, `from-factcheck`, the DuckDB macros, the Graphiti adapter, and the tckg export. Extraction quality on real transcripts is being measured separately; the rules are the ones a dated-claims pipeline has run on hundreds of videos. Next: a PyPI release. The format reaches 1.0.0 when a reader or writer maintained outside this repository exists; until then minor versions may change fields and the manifest's `factblock_version` says which one a bundle speaks.
+
+```bash
+uv sync --extra gemini                                 # or --extra openai; the fake provider needs nothing
+export GEMINI_API_KEY=...                              # or GOOGLE_GENAI_USE_VERTEXAI=1 GOOGLE_CLOUD_PROJECT=... for Vertex
+echo "The Fed will keep raising rates this year. That means bond yields keep climbing." \
+  | uv run python -m factblock extract - --observed-at 2024-03-20 --speaker "Jim Cramer" --backfill -o brain/
+uv run python -m factblock scan brain/ --as-of 2024-05-01
+```
+
+```bash
+uv sync
+uv run python -m factblock validate samples/rates
+uv run python -m factblock scan samples/rates --as-of 2024-08-01
+uv run python -m factblock why samples/rates c3 --as-of 2024-10-01 --json
+uv run python -m factblock leak samples/rates samples/rates-questions.jsonl
+uv run python -m factblock resolve samples/rates belief:fed:direction --as-of 2024-10-01
+uv run python tests/test_rates.py && uv run python tests/test_why.py && uv run python tests/test_recall.py && uv run python tests/test_leak.py && uv run python tests/test_sync.py && uv run python tests/test_claimreview.py && uv run python tests/test_okf.py && uv run python tests/test_factcheck.py && uv run python tests/test_graphiti_adapter.py && uv run python tests/test_duckdb.py
+```