Reference on factgraph

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.

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.

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.

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.

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:

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:

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.

Reference on factgraph

factgraph (entry point)

FactGraph (entry point and namespace map)#

FactGraph#

Schema

Schema: Entity, Identity, Field#

Three-layer API

Three-layer API: entities, fields, assertions#

Rules

Rules#

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#

Audit and capabilities

Audit and capabilities#

fg.audit#

fg.audit.explain(target)#

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`#