How-to guides on factgraph

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.

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:

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).

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.

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.

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.

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: