Skip to main content
Version: 0.0.5 (stable)

agrag.common.data_models.graph_schema.GraphSchema

Bases: BaseModel

A versioned contract of entity and relation types.

Every extraction call is validated against a GraphSchema. There is no schema-free extraction path. Round-trip with model_dump(mode="json") and model_validate(). A schema declaring an entity property name that the vector payload reserves fails that validation. See EntityType.properties.

Construct a new schema to change its types. Ancestor access revalidates the hierarchy so direct parent edits cannot cause an invalid traversal.

Attributes:

  • name (str) – A short, unique name for this schema.
  • version (str) – The schema version. Bump when types or patterns change.
  • entities (list[EntityType]) – The entity types this schema recognizes.
  • relations (list[RelationType]) – The relation types this schema recognizes.

Functions:

  • allows – Return whether a pair of entity types is allowed for a relation.
  • ancestors – Return an entity type's ancestors in nearest-first breadth-first order.
  • node_labels – Return a node's leaf label followed by its ancestors.
  • resolve – Render entity details and relation patterns expanded over child types.
  • to_compact_summary – Serialize entity labels, parents and relation patterns for a prompt.
  • to_prompt_description – Serialize this schema in full for an LLM prompt.

allows​

allows(relation:str, source_label:str, target_label:str) -> bool

Return whether a pair of entity types is allowed for a relation.

Patterns cover descendants, and symmetric relations accept reversal. Unknown entity or relation labels return False. Invalid parent edits raise ValueError rather than traversing bad data.

Parameters:

  • relation (str) – The relation label.
  • source_label (str) – The source entity's leaf label.
  • target_label (str) – The target entity's leaf label.

ancestors​

ancestors(label:str) -> list[str]

Return an entity type's ancestors in nearest-first breadth-first order.

Parents retain their listed order. Shared ancestors appear only once.

Parameters:

  • label (str) – A declared entity label.

Raises:

  • ValueError – If the label is not declared or the hierarchy is invalid.

entities​

entities: list[EntityType]

model_config​

model_config = ConfigDict(extra='forbid')

name​

name: str

node_labels​

node_labels(label:str) -> list[str]

Return a node's leaf label followed by its ancestors.

Parameters:

  • label (str) – A declared entity label.

Raises:

  • ValueError – If the label is not declared or the hierarchy is invalid.

relations​

relations: list[RelationType]

resolve​

resolve() -> str

Render entity details and relation patterns expanded over child types.

The final line counts entity and relation labels.

to_compact_summary​

to_compact_summary() -> str

Serialize entity labels, parents and relation patterns for a prompt.

Descriptions, properties and cardinality limits are omitted, so this is the shape to inject where prompt space is tight. to_prompt_description carries the same labels with their full detail.

Returns:

  • str – A plain-text summary of entity labels and valid relation
  • str – patterns.

to_prompt_description​

to_prompt_description() -> str

Serialize this schema in full for an LLM prompt.

Entity labels, parents and declared properties are followed by each relation's valid patterns, symmetry and cardinality. Use to_compact_summary instead when prompt space is tight.

Returns:

  • str – A plain-text schema description, one fact per line.

version​

version: str