factgraph: facts that carry their own proof on factgraph

Append-only ledger and provenance

Mon, 01 Jan 0001 00:00:00 +0000

About the append-only ledger and provenance#

factgraph never overwrites a fact and never deletes one. Every write you make through the SDK lands as a new row in an append-only ledger, and “removing” a fact is itself a new row that points back at the one being removed. This page explains why the store is shaped that way, how retraction works as a revocation rather than a delete, and how provenance metadata rides along with each assertion. The mechanism lives in factgraph.core.store.ledger.Ledger and in the write protocol that drives it.

Define a schema

Mon, 01 Jan 0001 00:00:00 +0000

How to define a schema#

This guide shows you how to declare entity types with identity and fields in Python and build a FactGraph from them, which is the first step before you write or read any facts.

Prerequisites#

The factgraph package installed (v0.2.0).
The public symbols Entity, Identity, Field, and FactGraph, all importable from factgraph.sdk.

Steps#

Declare an entity type by subclassing Entity. Annotate each member with a Python type and assign either an Identity() or a Field() descriptor. Every entity must declare at least one Identity() member; the metaclass raises SDKSchemaError with the message Entity '<name>' must declare at least one Identity field otherwise.

factgraph (entry point)

Mon, 01 Jan 0001 00:00:00 +0000

FactGraph (entry point and namespace map)#

The FactGraph class is the SDK entry point: it owns the compiled schema and the append-only ledger, and exposes every user-facing operation through a set of fg.* namespaces. FactGraph is a literal alias of SDKStore (FactGraph = SDKStore); both names refer to the same class and are exported from factgraph.sdk.

`FactGraph`#

The main SDK graph object. It holds the compiled schema (schema_ir), an append-only Ledger, an optional workspace path, and the namespace managers reachable as properties. Instances are normally built with the classmethod constructors below rather than by calling the class directly.

Getting started

Mon, 01 Jan 0001 00:00:00 +0000

Getting started: flag a transaction and prove it (AML)#

In this tutorial we will build a tiny anti money laundering (AML) check from scratch. We will model Customer and Transaction entities, record a couple of customers and a few transfers, write one rule that flags any transfer at or above a reporting threshold of 10000, evaluate it, and then read the self explaining proof of the flag condition by condition.

Reasoning, evaluation, and evidence

Mon, 01 Jan 0001 00:00:00 +0000

Reasoning, evaluation, and evidence#

When you evaluate a rule against a factgraph, you do not just get back a set of answers. You get back answers that can each explain themselves, condition by condition, in a way that replays to the same result every time. This page discusses how a rule turns into result rows, why each row can carry its own proof, and what makes that proof deterministic. It is the conceptual companion to Evaluation and explanation, which lists the precise types and signatures.

Schema

Mon, 01 Jan 0001 00:00:00 +0000

Schema: Entity, Identity, Field#

Reference for declaring a factgraph schema with Python classes: the Entity base class, the Identity and Field descriptors, the compile helpers, and the fg.schema register/extend/apply namespace.

All symbols on this page are importable from factgraph.sdk:

from factgraph.sdk import Entity, Field, Identity
from factgraph.sdk import (
 compile_schema_from_classes,
 schema_preflight_from_classes,
 build_authoring_schema_from_classes,
)

A schema is declared by subclassing Entity and assigning annotated Identity and Field descriptors. The EntityMeta metaclass reads the annotations at class-definition time and compiles them into a per-class __sdk_entity_spec__. FactGraph.create(schema_classes=[...]) consumes those specs to build the graph schema.

Write and read facts

Mon, 01 Jan 0001 00:00:00 +0000

How to write and read facts#

This guide shows you how to create an entity, write single- and multi-valued field facts onto it, and read those values back, either through an entity snapshot or directly by field. Use it once you have a schema and a FactGraph instance and want to populate and inspect data.

Prerequisites#

A FactGraph instance built from your schema classes. See How to define a schema and the factgraph reference for constructor options.
Each schema class declares at least one Identity() field and zero or more Field() fields. See the schema reference.

The examples below use this schema:

Auditability

Mon, 01 Jan 0001 00:00:00 +0000

Auditability#

Auditability in factgraph is not a feature you switch on. It is a consequence of how the graph stores facts and how it explains conclusions. Because the ledger is append-only, every assertion carries its own provenance, and every evaluated conclusion comes back with an evidence structure that names the rule and the supporting facts, you can always trace a conclusion to its inputs. This page discusses why that is structural rather than a logging mode, and how the three pieces fit together.

Find and match entities

Mon, 01 Jan 0001 00:00:00 +0000

How to find and match entities#

This guide shows you how to read entities back out of a FactGraph: filter them by exact field values with fg.entities.where, and select them by a rule or rule-expression pattern (with port constraints) using fg.entities.match. Both return a tuple/list of read-only EntitySnapshot objects.

Prerequisites#

A FactGraph with a registered schema and some entities written to it. See How to define a schema and How to write and read facts.
The Entity subclasses you query with must be the same classes you registered.

Both verbs require an Entity subclass as the first positional argument. Passing a string, a Field descriptor, or any other type raises SDKStoreError (the Layer 1 navigation key check, ADR-API §4.1.1).

Three-layer API

Mon, 01 Jan 0001 00:00:00 +0000

Three-layer API: entities, fields, assertions#

The write and read surface of a FactGraph (alias of SDKStore) is divided into three navigation layers, each exposed as a read-only namespace on the graph instance fg.

Each namespace is selected by a fixed navigation key. Passing the wrong kind of key raises SDKStoreError with a message that names the correct layer (citing ADR-API §4.1.1). The layers are:

Namespace	Layer	Navigation key	Property
`fg.entities`	1	`EntityClass` + identity kwargs, or a managed `e_ref`	`entities`
`fg.fields`	2	`Field` descriptor + `e_ref` (+ optional value)	`fields`
`fg.assertions`	3	`asrt_id` string	`assertions`

All three namespaces reject attribute assignment: fg.entities.x = ..., fg.fields.x = ..., and fg.assertions.x = ... each raise FrozenSnapshotError.

Evaluate a rule and read the proof

Mon, 01 Jan 0001 00:00:00 +0000

How to evaluate a rule and read its proof#

This guide shows you how to build a rule with build_application_rule, run it against a graph, and read the proof behind each result row, for when you need both the answer and a human-readable account of why it holds.

Prerequisites#

A FactGraph with the facts your rule body needs. Field atoms such as User(u).status == "active" match field claims written by fg.fields.set. See How to write and read facts.
Be aware of how existence atoms compile. An existence atom such as User(u) lowers to the User:exists predicate, and a field atom like User(u).status == "active" lowers to both the User:exists predicate and the field predicate. So any rule body that mentions an entity variable carries an implicit User:exists requirement. fg.entities.create(...) emits only the entity’s identity claims; it does not emit a :exists claim (the :exists co-emission is transitional and not performed by the current write path, see the guard note in factgraph.sdk.store). A rule body that relies on existence therefore will not match entities created through the SDK write path until a :exists claim is present for them.
The rule-authoring imports come from factgraph.sdk.dsl. The schema base classes (Entity, Identity, Field) come from factgraph.sdk.

Steps#

Define a schema and create the entities the rule will match. create emits the identity claims for the entity; fg.fields.set adds field claims.

Rules

Mon, 01 Jan 0001 00:00:00 +0000

Rules#

Reference for the rule-authoring surface: build_application_rule, the Entity-DSL atom forms, vars, Not, the application Rule value, RuleExpr composition, and fg.rules.inspect with its RuleExprInspect result. Most of these symbols are importable from factgraph.sdk. The supporting types RuleValidationError, RuleOccurrence, and RulePortRef are not exported from factgraph.sdk; import them from factgraph.application.protocol (their defining module is factgraph.application.protocol.rule). PortType is importable only from factgraph.application.protocol.rule.

A Rule is an AND-only conjunction of conditions over existing facts, with named output ports. Rules are values: they compose with & and | into a RuleExpr, and are inspected with fg.rules.inspect.

Choose a reasoning engine

Mon, 01 Jan 0001 00:00:00 +0000

How to choose a reasoning engine#

This guide shows you how to pick and configure the engine that evaluates a rule, when the default boolean answer is not enough and you need a probabilistic or possibilistic verdict instead.

You select the engine on the call, not on the graph: every fg.eval.evaluate(...) and fg.eval.explain(...) call takes an engine= keyword, and the probabilistic and possibilistic engines additionally take a config= wrapper. The same rule and the same facts can be evaluated under any supported engine.

Evaluation and explanation

Mon, 01 Jan 0001 00:00:00 +0000

Evaluation and explanation#

The fg.eval namespace, its result envelope (EvaluateResult / EvaluateRow), and the explanation surface (Explanation and the EvidenceGraph it carries).

fg.eval is a read-only namespace on a FactGraph / SDKStore instance. Assigning to it raises FrozenSnapshotError. It never writes to the ledger.

`fg.eval.evaluate(rule_or_expr, *, head, engine=None, config=None) -> EvaluateResult`#

Evaluates an application Rule or a RuleExpr against the current visible view and returns an EvaluateResult envelope. (The same method also accepts an Inference object or a structured derivation dict; those legacy derivation inputs are not covered here.)

Engines and semantics

Mon, 01 Jan 0001 00:00:00 +0000

Engines and semantics#

The engine= and config= options of fg.eval.evaluate(...) and fg.eval.explain(...), the supported engine names, the public semantics wrappers ProbLogConfig and PyReasonConfig, the canonical SemanticsProfile, and how certainty is represented per engine.

`engine=` option#

Selects the runtime adapter that executes a rule, RuleExpr, or inference. Passed as a keyword to fg.eval.evaluate(...), fg.eval.evaluate_candidates(...), and fg.eval.explain(...).

Type: string or None
Default: None, which resolves to "native".
Accepted values: "native", "souffle", "problog", "pyreason".

The accepted set is fixed by SUPPORTED_ENGINES in factgraph.core.semantics:

Persist and reload a workspace

Mon, 01 Jan 0001 00:00:00 +0000

How to persist and reload a workspace#

This guide shows you how to save a FactGraph ledger to disk as a durable workspace and reload it later under the matching schema. Use it when a graph must outlive the process that built it, for example to hand a ledger to a separate read or evaluation step.

A workspace is a directory holding the ledger (ledger.db), a schema object under db/, and a manifest (factgraph_workspace.json). Reload validates the stored schema digest against the Entity classes you supply, so the same classes that created the workspace must be available at load time. For the full surface and manifest layout, see Persistence: workspaces and attach.

Audit and capabilities

Mon, 01 Jan 0001 00:00:00 +0000

Audit and capabilities#

Reference for the fg.audit namespace (explain, conflicts, diff_proof_frames) and the fg.meta namespace (capabilities). Both namespaces are read-only: assigning an attribute on either raises FrozenSnapshotError.

`fg.audit`#

The fg.audit namespace exposes post-hoc audit queries over the ledger and over recorded round events. The attribute fg.audit returns the audit namespace manager.

fg.audit # read-only namespace; fg.audit.x = ... raises FrozenSnapshotError

`fg.audit.explain(target)`#

Explain chosen-policy state for the predicate/entity cell of one assertion.

Parameters:

Trace and audit a fact

Mon, 01 Jan 0001 00:00:00 +0000

How to trace and audit a fact#

This guide shows you how to start from a fact you already hold (its assertion id or AssertionRecord), read the provenance recorded on it, and inspect which value the runtime chose for that entity field cell, including when several active assertions compete.

Prerequisites#

A FactGraph (alias SDKStore) with a registered schema and at least one written field assertion.
The assertion id of the fact, or an AssertionRecord for it. Field writes return the assertion id: fg.fields.set(...) and fg.fields.add(...) both return a str asrt_id. If you only have the entity and field, see step 1 for how to recover the id.

The examples use this schema and a single written cell:

Persistence

Mon, 01 Jan 0001 00:00:00 +0000

Persistence: workspaces and attach#

The public surface for persisting a FactGraph to disk and reloading it: the workspace create / save_workspace / load_workspace lifecycle, the FactGraph.attach(db, ...) Database lifecycle, and the Database, CommitResult, AssertionInput, and MetaEntry types exported from factgraph.sdk.

FactGraph is a literal alias of SDKStore (FactGraph = SDKStore). The names are interchangeable; this page uses FactGraph.

`FactGraph.create(schema_classes, *, ledger=None, ledger_path=None, path=None, artifact_store_root=None, registry_root=None, registry=None, default_row_format=None) -> SDKStore`#

Classmethod. Creates a FactGraph from Python Entity classes and optionally binds it to a durable workspace directory. This is the constructor that produces a workspace-capable graph.

Errors

Mon, 01 Jan 0001 00:00:00 +0000

Errors and error codes#

The public exception hierarchy raised by the factgraph SDK, the attributes carried on each error, and the exported error-code string constants.

Most public error classes and all code constants are re-exported from the top-level factgraph.sdk package (see reference/factgraph.md). The base class SDKError is not re-exported from factgraph.sdk; import it from factgraph.sdk.errors. RuleValidationError and DetachedRowError live outside the SDK package; DetachedRowError is re-exported from factgraph.sdk, while RuleValidationError is not.

factgraph: facts that carry their own proof on factgraph

Append-only ledger and provenance

About the append-only ledger and provenance#

Define a schema

How to define a schema#

Prerequisites#

Steps#

factgraph (entry point)

FactGraph (entry point and namespace map)#

FactGraph#

Getting started

Getting started: flag a transaction and prove it (AML)#

Reasoning, evaluation, and evidence

Reasoning, evaluation, and evidence#

Schema

Schema: Entity, Identity, Field#

Write and read facts

How to write and read facts#

Prerequisites#

Auditability

Auditability#

Find and match entities

How to find and match entities#

Prerequisites#

Three-layer API

Three-layer API: entities, fields, assertions#

Evaluate a rule and read the proof

How to evaluate a rule and read its proof#

Prerequisites#

Steps#

Rules

Rules#

Choose a reasoning engine

How to choose a reasoning engine#

Evaluation and explanation

Evaluation and explanation#

fg.eval.evaluate(rule_or_expr, *, head, engine=None, config=None) -> EvaluateResult#

Engines and semantics

Engines and semantics#

engine= option#

Persist and reload a workspace

How to persist and reload a workspace#

Audit and capabilities

Audit and capabilities#

fg.audit#

fg.audit.explain(target)#

Trace and audit a fact

How to trace and audit a fact#

Prerequisites#

Persistence

Persistence: workspaces and attach#

FactGraph.create(schema_classes, *, ledger=None, ledger_path=None, path=None, artifact_store_root=None, registry_root=None, registry=None, default_row_format=None) -> SDKStore#

Errors

Errors and error codes#

`FactGraph`#

`fg.eval.evaluate(rule_or_expr, *, head, engine=None, config=None) -> EvaluateResult`#

`engine=` option#

`fg.audit`#

`fg.audit.explain(target)`#

`FactGraph.create(schema_classes, *, ledger=None, ledger_path=None, path=None, artifact_store_root=None, registry_root=None, registry=None, default_row_format=None) -> SDKStore`#