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.

Attributes (read-only properties):

__repr__ returns SDKStore(entities=<count>, schema=<digest>).

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#

Creates a FactGraph from Python Entity classes. This is the normal SDK constructor. Pass path= when the graph should own a durable workspace that can later be saved with fg.save_workspace() and restored with FactGraph.load_workspace(...).

Parameters:

Returns: SDKStore bound to the compiled schema.

Raises:

• SDKStoreError if registry_root= or registry= is provided.
• SDKStoreError if ledger_path conflicts with the ledger path implied by path.
• SDKStoreError if both ledger and ledger_path are provided.
• SDKStoreError if the workspace schema object cannot be written, or if the schema classes are invalid.

Example:

from factgraph.sdk import FactGraph

fg = FactGraph.create(schema_classes=[User])

With a durable workspace:

fg = FactGraph.create(schema_classes=[User], path="/tmp/my-workspace")
fg.save_workspace()

FactGraph.from_schema_classes(classes, *, ledger=None, ledger_path=None, artifact_store_root=None, registry_root=None, registry=None, default_row_format=None) -> SDKStore#

Creates a FactGraph from Entity classes without binding a workspace path. Equivalent to create minus the path= workspace handling.

Parameters: as for create, except the first positional parameter is named classes and there is no path parameter.

Returns: SDKStore bound to the compiled schema.

Raises: SDKStoreError if registry_root= or registry= is provided, or on invalid ledger combinations or schema classes.

fg = FactGraph.from_schema_classes([User])

FactGraph.load_workspace(path, *, schema_classes=None, default_row_format=None) -> SDKStore#

Loads a saved FactGraph workspace from disk. The load restores the ledger and validates the workspace schema digest against the supplied schema_classes. Class-less dynamic load is not supported.

Parameters:

Returns: SDKStore bound to the restored ledger.

Raises:

• SDKStoreError if schema_classes is None.
• SDKStoreError if the workspace contains a legacy registry/ marker (run python -m factgraph migrate-workspace <path> first).
• SDKStoreError if the workspace schema digest does not match the compiled schema_classes.

fg = FactGraph.load_workspace("/tmp/my-workspace", schema_classes=[User])

See persist-and-reload-a-workspace.md and persistence.md.

FactGraph.attach(db, *, schema_classes, view=None, default_row_format=None, **kwargs) -> SDKStore#

Database-owned lifecycle. Attaches a FactGraph to an existing Database. The compiled schema_classes digest must match db.schema_digest. Attached runtimes route writes only through fg.commit_assertions(...); the namespace write methods (fg.fields.set, fg.fields.add, fg.entities.create, etc.) are not available on attached runtimes.

Parameters:

Returns: SDKStore attached to the Database (writable when view is None, read-only when view is given).

Raises:

• SDKStoreError if db is not a Database instance.
• SDKStoreError if any keyword argument is passed via **kwargs.
• SDKStoreError if the compiled schema digest does not match db.schema_digest.
• SDKStoreError if view is supplied but is not a Database-anchored DatabaseFrozenAssertionSet, or its db_id, schema_digest, or base_tx_id does not match the Database.

fg.commit_assertions(assertions) -> CommitResult#

Routes a sequence of writes through the attached Database. Available only on FactGraph.attach(db) runtimes.

Parameters:

• assertions (Sequence[AssertionInput]): the assertions to commit.

Returns: CommitResult.

Raises:

• SDKStoreError if the runtime is not attached (use fg.fields.set / fg.fields.add instead).
• SDKStoreError if the runtime is attached with a view (view-attached runtimes are read-only).

fg.save_workspace(path=None) -> dict[str, Any]#

Persists the graph as a FactGraph workspace. A workspace contains the ledger, schema metadata, the authoring registry, and a workspace manifest.

Parameters:

• path (str | Path | None, default None): the workspace directory. If omitted, the graph must already be bound to a workspace path through FactGraph.create(path=...) or an earlier fg.save_workspace(path).

Returns: dict[str, Any] with keys path (workspace root) and manifest (manifest path), both as strings.

Raises:

• SDKStoreError if no workspace path is bound and none is passed.
• SDKStoreError if called on an attached runtime.

See persistence.md.

fg.batch(*, meta=None)#

Returns a batch transaction context manager (SDKBatchTx) that groups multiple writes.

Parameters:

• meta (dict[str, Any] | None, default None): metadata applied to the batch.

Raises: SDKStoreError if called on an attached runtime.

with fg.batch() as tx:
    ...

fg.add_schema_classes(*schema_class_args, schema_classes=None) -> SchemaAddResult#

Registers new entity types or extends existing ones additively. Accepts either positional Entity subclasses or the schema_classes= keyword list, but not both.

Parameters:

• *schema_class_args (type[Entity]): one or more Entity subclasses passed positionally.
• schema_classes (list[type[Entity]] | None, default None): the additions as a list.

Returns: SchemaAddResult.

Raises:

• SDKStoreError if both positional classes and schema_classes= are given.
• SchemaConflictError / SchemaNonAdditiveError on non-additive schema changes.
• SDKStoreError if called on an attached runtime.

See schema.md.

Namespace map#

User-facing operations are grouped into fg.* namespaces, each a read-only manager exposed as a property on the graph. Assigning to a namespace attribute (for example fg.entities.foo = ...) raises FrozenSnapshotError.

Two namespace items named in earlier surfaces resolve here:

• ingest is reached as fg.schema.ingest(data, *, meta=None, allow_sensitive_meta=False), not a top-level fg.ingest namespace.
• batch is the method fg.batch(*, meta=None) documented above, not a property namespace.

fg.inferences exists for forward compatibility but exposes no public methods. The legacy accept / CandidateSet / Inference / EmitSpec / Pred / Query flow is not covered here.

For errors raised across these namespaces, see errors.md.