KNOWLEDGE · vocabulary · v0.0.5

AbstractSemantics

AbstractSemantics is the central, editable semantics registry of AbstractFramework: the predicates and entity types allowed in knowledge-graph (KG) assertions, and the memory relations that link AbstractMemory records. It also builds a compact, bounded JSON Schema that makes a model return KG assertions as structured output. It holds definitions only: no network calls and no storage.

GitHub PyPI llms.txt llms-full.txt 
pip install abstractsemantics     # only dependency: PyYAML
Overview

One registry, three vocabularies

The default registry ships as package data (abstractsemantics/semantics.yaml, registry version 2). The loader returns immutable dataclasses, and runtimes, authoring tools and ingestion pipelines share the same allowed ids.

44 predicates

CURIE ids (compact prefixed names) from standard vocabularies for structure, metadata, context, actions, concepts and evidence (for example dcterms:hasPart, schema:about, cito:supports). Predicates may declare an inverse as a navigation hint.

rdfdctermsschemaskoscito

18 entity types

Allowed types for KG entities, such as schema:Person, schema:Thing, dcterms:Text or cito:Claim, with optional parent pointers.

EntityTypeDefparent

11 memory relations

Plain-word edges for AbstractMemory records: summarizes, mentions, written_amid, from_session, reflected_in, continues, derived_from, refines, answers, supports, part_of. Each names its subject_role and object_role and may list equivalent standard CURIEs.

MemoryRelationDefprov

Prefixes in the registry: dcterms, schema, skos, cito, rdf, prov, ex. Memory relations are kept apart from predicates: the predicate list feeds the KG-extraction enum, and memory-record words never appear there.

AbstractSemantics comes with the one-line AbstractFramework installer: AbstractRuntime depends on it to resolve structured-output schema references such as abstractsemantics:kg_assertion_schema_v0.
Capabilities

Registry and schema

Schema

Bounded output schema

build_kg_assertion_schema_v0() returns a deterministic JSON Schema dict with predicate and entity-type enums, a cap on assertions and bounded evidence fields. It raises ValueError for negative bounds.

Aliases

Predicate normalization

normalize_kg_predicate() maps an extractor's predicate to its canonical id at your ingestion boundary: canonical ids pass through, known aliases map (KG_PREDICATE_ALIAS_MAP_V0), anything else returns None. Nothing is coerced to a guessed meaning.

Memory

Memory-record validation

memory_relation_ids() lists the declared relations; memory_record_predicate_ids() adds the digest predicate MEMORY_DIGEST_PREDICATE (dcterms:abstract) to give the validation set for memory-record writes.

Reference

Stable $ref

Store {"$ref": KG_ASSERTION_SCHEMA_REF_V0} in a workflow and resolve it with resolve_schema_ref instead of embedding the full schema.

Loader

A loader that reports problems

Duplicate YAML keys fail the load. Malformed predicates or entity types are skipped with a warning naming the file; duplicate ids keep the first. memory_relations is strict: a CURIE-prefixed id, a collision with a predicate, a missing role or a repeat fails the load.

Custom

Your own registry

Point ABSTRACTSEMANTICS_REGISTRY_PATH at a YAML file, or pass load_semantics_registry(path). Aliases are offered only when their target exists in the registry you pass. The package is fully typed (py.typed).

Quickstart

Code examples

from abstractsemantics import load_semantics_registry, build_kg_assertion_schema_v0

reg = load_semantics_registry()
print(len(reg.predicates), len(reg.entity_types))   # 44 18

schema = build_kg_assertion_schema_v0(registry=reg, include_predicate_aliases=True)

# or resolve the stable reference
from abstractsemantics import KG_ASSERTION_SCHEMA_REF_V0, resolve_schema_ref
schema = resolve_schema_ref({"$ref": KG_ASSERTION_SCHEMA_REF_V0})
from abstractsemantics import load_semantics_registry

reg = load_semantics_registry()
print(sorted(reg.memory_relation_ids()))
print(sorted(reg.memory_record_predicate_ids()))

supports = next(r for r in reg.memory_relations if r.id == "supports")
print(supports.subject_role, "->", supports.object_role)  # evidence -> claim
from abstractsemantics import load_semantics_registry, normalize_kg_predicate

reg = load_semantics_registry()
print(normalize_kg_predicate("schema:hasPart", registry=reg))      # 'dcterms:hasPart'
print(normalize_kg_predicate("something:invented", registry=reg))  # None
# semantics.yaml (excerpt of the shipped registry)
version: 2
prefixes:
  dcterms: "http://purl.org/dc/terms/"
  schema: "https://schema.org/"
  prov: "http://www.w3.org/ns/prov#"
predicates:
  - id: "dcterms:hasPart"
    label: "has part"
    inverse: "dcterms:isPartOf"
entity_types:
  - id: "schema:Person"
    label: "Person"
memory_relations:
  - id: "summarizes"
    label: "summarizes"
    equivalent: ["prov:wasDerivedFrom"]
    subject_role: "summary"
    object_role: "source"
APIWhat it does
load_semantics_registry(path=None)Load the shipped registry, or ABSTRACTSEMANTICS_REGISTRY_PATH, or path; returns a SemanticsRegistry
SemanticsRegistryversion, prefixes, predicates, entity_types, memory_relations; predicate_ids(), entity_type_ids(), memory_relation_ids(), memory_record_predicate_ids()
build_kg_assertion_schema_v0(...)registry=None, include_predicate_aliases=False, max_assertions=12, min_assertions_when_nonempty=3, max_evidence_quote_len=160, max_original_context_len=280
normalize_kg_predicate(...)Canonical id or None
resolve_schema_ref(schema)Resolve {"$ref": "abstractsemantics:kg_assertion_schema_v0"} to the schema dict
Where to next

Keep going

AbstractMemoryThe memory engine whose records use these relations. AbstractRuntimeResolves the KG-assertion schema from this registry. Researcher journeyKnowledge graphs, memory and provenance. Install the frameworkOne line on macOS, Linux and Windows.