factgraph documentation#

factgraph (package factgraph, version 0.2.0, Apache-2.0, Python >= 3.10) is described in its pyproject.toml as a “FactGraph package for append-only facts, policy/view projection, and logic export.” Its public surface is the SDK exported from factgraph.sdk: you declare a schema as Python classes (Entity, Identity, Field), open a FactGraph workspace, and read and write facts through three layered namespaces (fg.entities, fg.fields, fg.assertions). Writes are recorded as assertions in an append-only ledger, so every active value carries the assertion that produced it. You author rules with the DSL (build_application_rule, the Entity(...) atom forms, vars), evaluate them with fg.eval.evaluate / fg.eval.explain against a chosen reasoning engine (native, souffle, problog, pyreason), and inspect provenance through fg.audit and fg.meta. Workspaces persist to disk and reload with a schema-digest guard via FactGraph.create, save_workspace, load_workspace, and attach.

Explanation#

Understanding-oriented discussion of why factgraph works the way it does.

• Append-only ledger and provenance: why writes are assertions on an append-only ledger and how that grounds provenance.
• Reasoning, evaluation, and evidence: how rule evaluation produces rows and evidence across the reasoning engines.
• Auditability: how the ledger, evaluation, and digests combine into an auditable record.

Tutorials#

Learning-oriented lessons that take you through a first end-to-end session.

• Getting started: install factgraph, declare a schema, write and read facts, and evaluate a first rule.

How-to guides#

Goal-oriented recipes for specific tasks once you know the basics.

• Define a schema: declare entities, identities, and fields as Python classes.
• Write and read facts: create entities and set, add, retract, and read field values.
• Find and match entities: look up entities by identity, filter with where, and match on field values.
• Evaluate a rule and read the proof: run a rule, iterate the result rows, and explain a closed head.
• Choose a reasoning engine: select native, souffle, problog, or pyreason and pass the matching config.
• Persist and reload a workspace: save a workspace to disk, reload it, and attach an existing database.
• Trace and audit a fact: explain which assertion is active for a field and find conflicts.

Reference#

Information-oriented description of the public API, copied from the code.

• factgraph (entry point): the FactGraph class, its constructors (create, from_schema_classes, load_workspace, attach), instance methods, and the fg.* namespace map.
• Schema: the Entity, Identity, and Field declaration surface, cardinality and type-domain rules, repr templates, the compile helpers, and the fg.schema namespace.
• Three-layer API: entities, fields, assertions: fg.entities, fg.fields, and fg.assertions, the records they return, and the editor and batch transaction surfaces.
• Rules: build_application_rule, the Entity(...) atom forms, vars, Not, the Rule and RuleExpr values, and fg.rules.inspect.
• Evaluation and explanation: fg.eval.evaluate and fg.eval.explain, the EvaluateResult / EvaluateRow / Explanation types, certainty, and the evidence graph.
• Engines and semantics: the engine= and config= options, ProbLogConfig, PyReasonConfig, SemanticsProfile, and certainty per engine.
• Audit and capabilities: the read-only fg.audit and fg.meta namespaces, including explain, conflicts, diff_proof_frames, and capabilities.
• Persistence: workspaces and attach: create, save_workspace, load_workspace, attach, the Database type, and the workspace manifest.
• Errors and error codes: the SDKError hierarchy, the .code / .path convention, and the exported error-code constants.