Ontology

Full Project Haystack def model with taxonomy, normalization, and reflection.

Haystack ontology model.

Data model for defs, libs, and namespace resolution over the Haystack taxonomy.

Usage:

from hs_py.ontology import Def, Lib, Namespace, load_lib_from_trio

lib = load_lib_from_trio(lib_trio_text, [defs_trio_text])
ns = Namespace([lib])
site_def = ns.get("site")

Defs

Def and Lib frozen dataclasses for ontology definitions.

Ontology definition and library data model.

A Def is a named term in the Haystack ontology, carrying metadata tags parsed from Trio records. A Lib groups related defs into a versioned, distributable package.

See: https://project-haystack.org/doc/docHaystack/Defs

class hs_py.ontology.defs.Def(symbol, tags=<factory>)

Bases: object

A single definition in the Haystack ontology.

Parameters:

• symbol (Symbol) – Qualified or unqualified symbol (e.g. ^ph::site or ^site).

• tags (dict[str, Any] (default: <factory>)) – Full tag dict from the Trio record.

symbol: Symbol

Qualified or unqualified symbol (e.g. ^ph::site or ^site).

tags: dict[str, Any]

Full tag dict from the Trio record.

property name: str

Unqualified def name (e.g. site from ph::site).

property lib_prefix: str | None

Library prefix if qualified (e.g. ph from ph::site).

property doc: str

Documentation string from doc tag.

property is_list: list[Symbol]

Supertype symbols from the is tag.

classmethod from_tags(tags)

Create a Def from a parsed Trio tag dict.

Parameters:

tags (dict[str, Any]) – Must contain a def tag with a Symbol value.

Raises:

ValueError – If def tag is missing or not a Symbol.

Return type:

Def

class hs_py.ontology.defs.Lib(symbol, version='', depends=(), base_uri=None, defs=())

Bases: object

A library of ontology definitions.

Parameters:

• symbol (Symbol) – Lib symbol (e.g. ^lib:ph).

• version (str (default: '')) – Semantic version string.

• depends (tuple[Symbol, ...] (default: ())) – Required library symbols.

• base_uri (Uri | None (default: None)) – Base URI for RDF export.

• defs (tuple[Def, ...] (default: ())) – All defs defined by this lib.

symbol: Symbol

Lib symbol (e.g. ^lib:ph).

version: str

Semantic version string.

depends: tuple[Symbol, ...]

Required library symbols.

base_uri: Uri | None

Base URI for RDF export.

defs: tuple[Def, ...]

All Def instances defined by this lib.

classmethod from_meta(meta, defs)

Create a Lib from lib.trio metadata and a list of defs.

Parameters:

• meta (dict[str, Any]) – Parsed lib.trio record (must have def tag).

• defs (list[Def]) – All defs belonging to this lib.

Return type:

Lib

Namespace

Namespace container with symbol resolution and lookup.

Ontology namespace for resolved defs.

The Namespace indexes defs from one or more libs, providing symbol resolution and taxonomy queries (subtype, supertype, transitive subtype checking).

See: https://project-haystack.org/doc/docHaystack/Namespaces

class hs_py.ontology.namespace.Namespace(libs=None)

Bases: object

Container for resolved ontology definitions.

Indexes defs by both qualified (ph::site) and unqualified (site) symbol names. Provides taxonomy queries over the is tag hierarchy.

Parameters:

libs (list[Lib] | None (default: None)) – List of Lib instances to include.

add_lib(lib)

Add a lib and its defs to the namespace.

Parameters:

lib (Lib) – Library to add.

Return type:

None

find_conjuncts(marker_names)

Return conjunct defs whose parts are all present in marker_names.

Uses a pre-built index for efficient lookup.

Parameters:

marker_names (set[str]) – Set of marker tag names present on an entity.

Return type:

list[Def]

Returns:

List of matching conjunct defs.

get(symbol)

Look up a def by symbol name.

Accepts both qualified (ph::site) and unqualified (site) names.

Parameters:

symbol (str | Symbol) – Qualified or unqualified symbol name.

Return type:

Def | None

Returns:

The matching Def, or None.

has(symbol)

Check whether a def with symbol exists in the namespace.

Parameters:

symbol (str | Symbol) – Qualified or unqualified symbol name.

Return type:

bool

Returns:

True if the def exists.

all_defs()

Iterate all unique defs (deduplicated by qualified name).

Return type:

Iterator[Def]

all_libs()

Iterate all libs.

Return type:

Iterator[Lib]

property def_count: int

Number of unique defs.

subtypes(symbol)

Return direct subtypes of a def.

Parameters:

symbol (str | Symbol) – Def symbol to look up.

Return type:

list[Def]

Returns:

List of Def instances.

supertypes(symbol)

Return direct supertypes of a def (from its is tag).

Parameters:

symbol (str | Symbol) – Def symbol to look up.

Return type:

list[Def]

Returns:

List of parent Def instances.

is_subtype(sub, sup)

Check whether sub is a transitive subtype of sup.

Also returns True if sub equals sup.

Parameters:

• sub (str | Symbol) – Candidate subtype symbol.

• sup (str | Symbol) – Candidate supertype symbol.

Return type:

bool

all_supertypes(symbol)

Return all transitive supertypes of a def (cached).

Parameters:

symbol (str | Symbol) – Def symbol to look up.

Return type:

list[Def]

Returns:

All ancestor Def instances.

hs_py.ontology.namespace.load_defs_from_trio(text)

Parse Trio text and return Def objects for each record with a def tag.

Parameters:

text (str) – Trio-formatted text.

Return type:

list[Def]

Returns:

List of parsed defs.

hs_py.ontology.namespace.load_lib_from_trio(lib_trio, def_trios=None)

Load a Lib from lib.trio metadata and optional def trio strings.

Parameters:

• lib_trio (str) – Trio text for the lib metadata (must have one record with def).

• def_trios (list[str] | None (default: None)) – Optional list of Trio text strings for def records.

Return type:

Lib

Returns:

Fully constructed Lib.

Taxonomy

Subtype tree, tag inheritance, and conjunct resolution.

Taxonomy tree operations over the def hierarchy.

Provides utilities for working with the is tag inheritance tree, conjunct detection, and tag inheritance through the taxonomy.

See: https://project-haystack.org/doc/docHaystack/Subtyping

hs_py.ontology.taxonomy.effective_tags(ns, symbol)

Compute the effective tag set for a def, inheriting from supertypes.

Walks up the taxonomy tree and merges tags from all supertypes. Tags defined on the def itself take precedence over inherited tags.

Parameters:

• ns (Namespace) – Namespace to resolve symbols in.

• symbol (str | Symbol) – Def symbol to compute tags for.

Return type:

dict[str, Any]

Returns:

Merged tag dict.

hs_py.ontology.taxonomy.is_conjunct(symbol)

Check if a symbol is a conjunct (compound term with -).

Conjuncts like hot-water are composed from their dash-separated parts.

Return type:

bool

Parameters:

symbol (str | Symbol)

hs_py.ontology.taxonomy.marker_tags(ns, symbol)

Return the set of marker tag names for a def and all its supertypes.

This is useful for reflection: determining which marker defs an entity implements based on its tag set.

Parameters:

• ns (Namespace) – Namespace to resolve symbols in.

• symbol (str | Symbol) – Def symbol.

Return type:

set[str]

Returns:

Set of marker tag names.

hs_py.ontology.taxonomy.resolve_conjunct_parts(symbol)

Split a conjunct symbol into its component part names.

Parameters:

symbol (str | Symbol) – e.g. hot-water-plant

Return type:

list[str]

Returns:

e.g. ["hot", "water", "plant"]

hs_py.ontology.taxonomy.tag_on_defs(ns, tag)

Return the entity def names that a tag applies to via tagOn.

Parameters:

• ns (Namespace) – Namespace to resolve symbols in.

• tag (str | Symbol) – Tag name to look up.

Return type:

list[str]

Returns:

List of entity def names.

Normalize

Normalization pipeline to compile raw defs into a resolved namespace.

Normalization pipeline for compiling raw defs into a resolved namespace.

Implements a simplified version of the Haystack normalization pipeline:

1. Parse: convert Trio text to raw tag dicts

2. Resolve: create Def objects from parsed records

3. Taxonify: compute conjunct supertypes

4. Inherit: propagate tags down the taxonomy tree

5. Validate: check for missing references and cycles

See: https://project-haystack.org/doc/docHaystack/Normalization

exception hs_py.ontology.normalize.NormalizeError

Bases: ValueError

Raised when normalization encounters an error.

hs_py.ontology.normalize.compile_namespace(libs)

Run the normalization pipeline on a set of libs.

Parameters:

libs (list[Lib]) – Libraries to compile.

Return type:

Namespace

Returns:

Fully resolved Namespace.

Raises:

NormalizeError – If validation fails.

Reflect

Dict-to-def reflection engine for runtime type inference.

Reflection engine for mapping entity dicts to ontology defs.

Reflection determines which defs apply to an entity based on its tag set. This includes detecting simple marker matches, conjunct matches, and computing the full effective def set.

See: https://project-haystack.org/doc/docHaystack/Reflection

hs_py.ontology.reflect.fits(ns, tags, def_symbol)

Check if an entity’s tags fit a given def.

An entity fits a def if the def (or one of its subtypes) appears in the entity’s reflected def set.

Parameters:

• ns (Namespace) – Namespace to resolve defs in.

• tags (dict[str, Any]) – Entity tag dict.

• def_symbol (str | Symbol) – Def symbol to check against.

Return type:

bool

Returns:

True if the entity fits the def.

hs_py.ontology.reflect.reflect(ns, tags)

Return all defs that apply to an entity with the given tags.

The algorithm: 1. Scan the entity’s tags for marker tags (tags whose value is Marker). 2. For each marker, look up the matching def in the namespace. 3. Check for conjuncts (compound terms matching tag combinations). 4. Include all transitive supertypes.

Parameters:

• ns (Namespace) – Namespace to resolve defs in.

• tags (dict[str, Any]) – Entity tag dict.

Return type:

list[Def]

Returns:

List of applicable defs (most-specific first).