Hyperbase

Hyperbase is a Python library designed for working with Semantic Hypergraphs (SH). Semantic Hypergraphs allow for the structured representation of natural language sentences.

For example, the sentence "Einstein first published the theory of relativity in 1905" can be represented in SH notation as a nested structure of semantic roles (e.g., M for modifiers, P.sox for predicates, C for concepts, B.ma for binding markers, and T for temporal markers):

((first/M published/P.sox)
    einstein/C
    (the/M
        (of/B.ma theory/C relativity/C))
    (in/T 1905))

Hyperbase uses two main object classes:

• Atom: The most basic unit, representing a single token with a root, role, and optional namespace.
• Hyperedge: A collection of hyperedges. A non-atomic hyperedge is an ordered, recursive structure where the first element is the connector and the remaining elements are arguments.

Hyperedge is derived from Python's tuple, allowing index-based access to arguments. Atom is a subclass of Hyperedge.

Note: Do not instantiate these classes directly; always use hedge() to create them.

Hyperbase uses a plugin architecture for parsers. The core hyperbase package does not include any parsers; it only defines the abstract parser interface. Parsers are separate Python packages that register themselves via entry points.

Available parser packages include:

• hyperbase-parser-ab: The alphabeta plugin (AlphaBeta parser using spaCy).
• hyperbase-parser-gen: The generative plugin (Multilingual generative parser based on a transformer model).

SH uses inference rules to determine the type of a non-atomic hyperedge based on its components.

| Element types | Resulting type |
|---------------|----------------|
| (M x) | x |
| (B C C+) | C |
| (T [CR]) | S |
| (P [CRS]+) | P |
| (J x y+) | x |

Semantic Hypergraph (SH) notation is a structured way to represent natural language using atoms and hyperedges.

Core Principles:

• Atoms: The simplest structure, typically a single word with a type (e.g., sky/C).
• Hyperedges: Combinations of atoms or other hyperedges (e.g., (blue/M sky/C)).
• Connectors: The first element of a non-atomic hyperedge. Valid connectors include Predicates (P), Modifiers (M), Builders (B), Triggers (T), and Conjunctions (J).
• Subtypes: Additional information appended to a type (e.g., maria/Cp where p is a subtype of concept C).
• Namespaces: Used to distinguish identical atoms (e.g., paris/Cp/1 vs paris/Cp/2) or languages (e.g., sky/Cc/en).

(is/P.so (the/M sky/C) blue/C)

The Semantic Hypergraph serves as a knowledge model that allows for the representation of claims. Because hyperedges can be nested, you can represent facts about facts, which enables attributing assertions to specific sources.

Instead of relying on a single notion of "ground truth," hyperbase models assertions as claims. A claim is structured as a hyperedge (the source) containing a hyperedge (the fact).

Example: Representing that Mary claims Berlin is nice:

(claims mary (is berlin nice))

This structure is particularly useful for modeling controversial topics where multiple actors may have contradictory views on the same issue.

Hyperbase uses an accepts(source) mechanism to automatically select a reader for a given input.

1. Acceptance: All registered readers are checked. If reader.accepts(source) returns True, that reader is a candidate.
2. Priority (more_general): If multiple readers accept a source, Hyperbase uses the more_general attribute to pick the most specific one.
   • For example, a Wikipedia URL is accepted by both the url and wikipedia readers.
   • Because WikipediaReader declares more_general = ['url'], it takes priority over the generic url reader.

Every hyperedge has a type (t).

• Atoms: The type is explicitly defined in the string.
• Non-atomic hyperedges: The type is inferred from the connector. For example, a predicate (P) applied to arguments produces a relation (R).

Use .ct to inspect the type of the connector specifically.

edge = hedge("(likes/P.so mary/Cp chess/Cc)")
print(edge.t)   # 'R' (inferred Relation)
print(edge.ct) # 'P' (connector type Predicate)

The Semantic Hypergraph (SH) is the core data model of hyperbase. Unlike traditional graphs that use vertices and dyadic (two-way) edges, a hypergraph uses hyperedges to represent n-ary connections (relationships between any number of entities).

Key properties of SH hyperedges include:

• Ordering: The position of a vertex within a hyperedge matters (e.g., (a b c) is distinct from (c b a)).
• Recursivity: Hyperedges can contain other hyperedges as vertices. This allows for representing relationships between relationships (higher-order relationships).

Example of a recursive hyperedge:

(a b c (d e f))

In this example, the hyperedge connects atoms a, b, and c with another hyperedge (d e f).

Detailed installation instructions, the full manual, and additional documentation are hosted externally. For setup and usage guides, visit the official Hyperbase documentation site.

https://hyperquest.ai/hyperbase