hyperbase 0.8.0__py3-none-any.whl

hyperbase/patterns/merge.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from typing import Any
+
+from hyperbase import hedge
+from hyperbase.hyperedge import Hyperedge
+from hyperbase.patterns.utils import is_valid
+
+
+def _extract_any_edges(edge: Hyperedge) -> list[Hyperedge]:
+    if edge.not_atom and str(edge[0]) == 'any':
+        return list(edge[1:])
+    else:
+        return [edge]
+
+
+def _merge_patterns(edge1: Hyperedge, edge2: Hyperedge) -> Hyperedge | None:
+    # edges with different sizes cannot be merged
+    if len(edge1) != len(edge2):
+        return None
+
+    # atoms are not to be merged
+    if edge1.atom or edge2.atom:
+        return None
+
+    # edges with no subedge in common are not to be merged
+    if all(subedge1 != subedge2 for subedge1, subedge2 in zip(edge1, edge2)):
+        return None
+
+    merged_edge: list[Hyperedge | list[Any]] = []
+    for subedge1, subedge2 in zip(edge1, edge2):
+        if subedge1 == subedge2:
+            merged_edge.append(subedge1)
+        else:
+            submerged = merge_patterns(subedge1, subedge2)
+            if submerged:
+                merged_edge.append(submerged)
+            else:
+                alternatives = _extract_any_edges(subedge1) + _extract_any_edges(subedge2)
+                # heuristic: more complex edges first, likely to be more specific
+                alternatives = sorted(alternatives, key=lambda x: x.size(), reverse=True)
+                merged_edge.append(['any'] + alternatives)
+
+    return hedge(merged_edge)
+
+
+def merge_patterns(edge1: Hyperedge, edge2: Hyperedge) -> Hyperedge | None:
+    edge = _merge_patterns(edge1, edge2)
+    if is_valid(edge):
+        return edge
+    else:
+        return None

hyperbase/patterns/properties.py

@@ -0,0 +1,59 @@
+from hyperbase.hyperedge import Hyperedge
+
+
+FUNS: set[str] = {'var', 'atoms', 'lemma', 'any'} # | SEMSIM_FUNS.keys()
+
+def is_wildcard(atom: Hyperedge) -> bool:
+    """Check if this atom defines a wildcard, i.e. if its root is a pattern matcher.
+    (\\*, ., ..., if it is surrounded by parenthesis or variable label starting with an uppercase letter)
+    """
+    if atom.atom:
+        return atom.parens or atom[0][0] in {'*', '.'} or atom[0][0].isupper()  # type: ignore[attr-defined]
+    else:
+        return False
+
+
+def is_fun_pattern(edge: Hyperedge) -> bool:
+    if edge.atom:
+        return False
+    return str(edge[0]) in FUNS
+
+
+def is_pattern(edge: Hyperedge) -> bool:
+    """Check if this edge defines a pattern, i.e. if it includes at least
+    one pattern matcher.
+
+    Pattern matcher are:
+    - '\\*', '.', '(\\*)', '...'
+    - variables (atom label starting with an uppercase letter)
+    - argument role matcher (unordered argument roles surrounded by curly brackets)
+    - functional patterns (var, atoms, lemma, ...)
+    """
+    if edge.atom:
+        return is_wildcard(edge) or '{' in edge.argroles()
+    elif is_fun_pattern(edge):
+        return True
+    else:
+        return any(is_pattern(item) for item in edge)
+
+
+def is_unordered_pattern(edge: Hyperedge) -> bool:
+    """Check if this edge defines an unordered pattern, i.e. if it includes at least
+    one instance of unordered argument roles surrounded by curly brackets.
+    """
+    if edge.atom:
+        return '{' in edge.argroles()
+    else:
+        return any(is_unordered_pattern(item) for item in edge)
+
+def is_full_pattern(edge: Hyperedge) -> bool:
+    """Check if every atom is a pattern matcher.
+
+    Pattern matcher are:
+    '\\*', '.', '(\\*)', '...', variables (atom label starting with an
+    uppercase letter) and functional patterns.
+    """
+    if edge.atom:
+        return is_pattern(edge)
+    else:
+        return all(is_pattern(item) for item in edge)

hyperbase/patterns/utils.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from typing import Any
+
+from hyperbase import hedge
+from hyperbase.hyperedge import Atom, Hyperedge
+from hyperbase.patterns.properties import is_fun_pattern
+from hyperbase.patterns.variables import is_variable
+
+
+# remove pattern functions from pattern, so that .argroles() works normally
+def _defun_pattern_argroles(edge: Hyperedge) -> Hyperedge:
+    if edge.atom:
+        return edge
+
+    if edge[0].argroles() != '':
+        return edge
+
+    if is_fun_pattern(edge):
+        fun: str = edge[0].root()
+        if fun == 'atoms':
+            for atom in edge.atoms():
+                argroles = atom.argroles()
+                if argroles != '':
+                    return atom
+            # if no atom with argroles is found, just return the first one
+            return edge[1]  # type: ignore[no-any-return]
+        else:
+            result = hedge([edge[0], _defun_pattern_argroles(edge[1])] + list(edge[2:]))
+            assert result is not None
+            return result
+    else:
+        result = hedge([_defun_pattern_argroles(subedge) for subedge in edge])
+        assert result is not None
+        return result
+
+
+def _atoms_and_tok_pos(
+        edge: Hyperedge,
+        tok_pos: Any
+) -> tuple[list[Atom], list[Any]]:
+    if edge.atom:
+        return [edge], [tok_pos]  # type: ignore[list-item]
+    atoms: list[Atom] = []
+    atoms_tok_pos: list[Any] = []
+    for edge_item, tok_pos_item in zip(edge, tok_pos):
+        _atoms, _atoms_tok_pos = _atoms_and_tok_pos(edge_item, tok_pos_item)
+        for _atom, _atom_tok_pos in zip(_atoms, _atoms_tok_pos):
+            if _atom not in atoms:
+                atoms.append(_atom)
+                atoms_tok_pos.append(_atom_tok_pos)
+    return atoms, atoms_tok_pos
+
+
+def _normalize_fun_patterns(pattern: Hyperedge) -> Hyperedge:
+    if pattern.atom:
+        return pattern
+
+    normalized = hedge([_normalize_fun_patterns(subpattern) for subpattern in pattern])
+    assert normalized is not None
+    pattern = normalized
+
+    if is_fun_pattern(pattern):
+        if str(pattern[0]) == 'lemma':
+            if is_fun_pattern(pattern[1]) and str(pattern[1][0]) == 'any':
+                new_pattern: list[str | Hyperedge | list[Any]] = ['any']
+                for alternative in pattern[1][1:]:
+                    new_pattern.append(['lemma', alternative])
+                result = hedge(new_pattern)
+                assert result is not None
+                return result
+
+    return pattern
+
+
+def is_valid(edge: Hyperedge | None, _vars: set[Hyperedge] | None = None) -> bool:
+    if _vars is None:
+        _vars = set()
+    if edge is None:
+        return False
+    if edge.atom:
+        return True
+    if is_variable(edge):
+        if edge[2].not_atom:
+            return False
+        # if edge[2] in _vars:
+        #     return False
+        _vars.add(edge[2])
+        return is_valid(edge[1], _vars=_vars)
+    return all(is_valid(subedge, _vars=_vars) for subedge in edge)
+
+
+def more_general(edge1: Hyperedge, edge2: Hyperedge) -> bool:
+    r1, s1, t1 = atom_pattern_counts(edge1)
+    r2, s2, t2 = atom_pattern_counts(edge2)
+    if r1 == r2:
+        if s1 == s2:
+            return t1 < t2
+        return s1 < s2
+    return r1 < r2
+
+
+def atom_pattern_counts(edge: Hyperedge) -> tuple[int, int, int]:
+    if edge.atom:
+        parts: list[str] = edge.parts()  # type: ignore[attr-defined]
+        roots = 1 if parts[0] != '*' else 0
+        subtyped = 1 if len(edge.type()) > 1 else 0
+        typed = 1 if len(parts) > 1 else 0
+    else:
+        roots = 0
+        subtyped = 0
+        typed = 0
+        for subedge in edge:
+            r, s, t = atom_pattern_counts(subedge)
+            roots += r
+            subtyped += s
+            typed += t
+    return roots, subtyped, typed

hyperbase/patterns/variables.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+from collections import Counter
+from typing import Any
+
+from hyperbase import hedge
+from hyperbase.hyperedge import Hyperedge
+from hyperbase.patterns.properties import is_pattern
+import hyperbase.constants as const
+
+
+def apply_vars(edge: Hyperedge, variables: dict[str, Hyperedge]) -> Hyperedge:
+    if edge.atom:
+        if is_pattern(edge):
+            varname = _varname(edge)
+            if len(varname) > 0 and varname in variables:
+                return variables[varname]
+        return edge
+    else:
+        result = hedge([apply_vars(subedge, variables) for subedge in edge])
+        assert result is not None
+        return result
+
+
+def _varname(atom: Hyperedge) -> str:
+    if not atom.atom:
+        return ''
+    label: str = atom.parts()[0]  # type: ignore[attr-defined]
+    if len(label) == 0:
+        return label
+    elif label[0] in {'*', '.'}:
+        return label[1:]
+    elif label[:3] == '...':
+        return label[3:]
+    elif label[0].isupper():
+        return label
+    else:
+        return ''
+
+
+def _assign_edge_to_var(
+        curvars: dict[str, Hyperedge],
+        var_name: str,
+        edge: Hyperedge
+) -> dict[str, Hyperedge]:
+    new_edge: Hyperedge = edge
+    if var_name in curvars:
+        cur_edge = curvars[var_name]
+        if cur_edge.not_atom and str(cur_edge[0]) == const.list_or_matches_builder:
+            new_edge = cur_edge + (edge,)
+        else:
+            result = hedge((hedge(const.list_or_matches_builder), cur_edge, edge))
+            assert result is not None
+            new_edge = result
+    return {var_name: new_edge}
+
+
+def is_variable(edge: Hyperedge) -> bool:
+    if edge.not_atom:
+        return edge[0].atom and edge[0].root() == 'var'  # type: ignore[no-any-return]
+    return False
+
+
+def contains_variable(edge: Hyperedge) -> bool:
+    if edge.atom:
+        return False
+    else:
+        if is_variable(edge):
+            return True
+        return any(contains_variable(subedge) for subedge in edge)
+
+
+def all_variables(edge: Hyperedge | None, _vars: Counter[Any] | None = None) -> Counter[Any]:
+    if _vars is None:
+        _vars = Counter()
+    if edge is None:
+        return _vars
+    if edge.atom:
+        return _vars
+    else:
+        if is_variable(edge):
+            _vars[edge[2]] += 1
+        for subedge in edge:
+            all_variables(subedge, _vars=_vars)
+    return _vars
+
+
+def extract_vars_map(
+        edge: Hyperedge | None,
+        _vars: dict[str, Hyperedge] | None = None
+) -> dict[str, Hyperedge]:
+    if _vars is None:
+        _vars = {}
+
+    if edge is None:
+        return _vars
+    if edge.not_atom:
+        if is_variable(edge):
+            new_edge: Hyperedge = edge[1]
+            var_name = str(edge[2])
+            if var_name in _vars:
+                cur_edge = _vars[var_name]
+                if cur_edge.not_atom and str(cur_edge[0]) == const.list_or_matches_builder:
+                    new_edge = cur_edge + (new_edge,)
+                else:
+                    result = hedge((hedge(const.list_or_matches_builder), cur_edge, new_edge))
+                    assert result is not None
+                    new_edge = result
+            _vars[var_name] = new_edge
+        for subedge in edge:
+            extract_vars_map(subedge, _vars=_vars)
+    return _vars
+
+
+def remove_variables(edge: Hyperedge) -> Hyperedge:
+    if is_variable(edge):
+        return remove_variables(edge[1])
+    if edge.atom:
+        return edge
+    else:
+        result = hedge([remove_variables(subedge) for subedge in edge])
+        assert result is not None
+        return result
+
+
+def apply_variable(
+        edge: Hyperedge,
+        var_name: str,
+        var_edge: Hyperedge | list[Hyperedge]
+) -> tuple[Hyperedge, bool]:
+    clean_edge = remove_variables(edge)
+    if clean_edge == var_edge or (type(var_edge) == list and clean_edge in var_edge):
+        result = hedge(('var', clean_edge, var_name))
+        assert result is not None
+        return result, True
+
+    subedges: list[Hyperedge] = []
+    found = False
+    if edge.not_atom:
+        for subedge in edge:
+            vedge, vresult = apply_variable(subedge, var_name, var_edge)
+            subedges.append(vedge)
+            if vresult:
+                found = True
+        hedge_result = hedge(subedges)
+        assert hedge_result is not None
+        return hedge_result, found
+
+    return edge, False
+
+
+def apply_variables(
+        edge: Hyperedge,
+        variables: dict[str, Hyperedge | list[Hyperedge]]
+) -> Hyperedge | None:
+    new_edge = edge
+    for var_name, var_edge in variables.items():
+        new_edge, found = apply_variable(new_edge, var_name, var_edge)
+        if not found:
+            return None
+    return new_edge

hyperbase-0.8.0.dist-info/METADATA

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: hyperbase
+Version: 0.8.0
+Summary: A foundational library for Semantic Hypergraphs
+Project-URL: Homepage, https://hyperquest.ai/hyperbase
+Author-email: "Telmo Menezes et al." <telmo@telmomenezes.net>
+License-Expression: MIT
+License-File: AUTHORS
+License-File: LICENSE
+Keywords: AI,Cognition,Knowledge Representation,Knowledge Systems,NLP,Natural Language Understanding,Text Analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Requires-Dist: tqdm>=4.65.0
+Provides-Extra: dev
+Requires-Dist: coverage>=7.4.3; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'dev'
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.6.2; extra == 'dev'
+Requires-Dist: ruff>=0.2.2; extra == 'dev'
+Requires-Dist: types-passlib>=1.7.7.20240106; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Hyperbase
+
+## A foundational library for Semantic Hypergraphs
+
+Hyperbase is a foundational library for working with *Semantic Hypergraphs (SH)*, which make it possible to represent a natural language sentence such as "Einstein first published the theory of relativity in 1905" as an ordered, recursive hyperlink of the form:
+
+<figure markdown="span">
+  ![Einstein first published the Theory of Relativity in 1905.](assets/images/hyperedge-blocks.png){ width="75%" }
+</figure>
+
+Hyperbase is written in Python, to both take advantage and facilitate integration with the rich environment of scientific libraries available in this language. It is released under the highly permissive MIT open source license.
+
+## Installation and manual
+
+Installation instructions, the manual and more information can be found here: <https://hyperquest.ai/hyperbase>
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first
+to discuss what you would like to change.
+
+Please make sure to update tests as appropriate.
+
+## Funding
+
+The creation of this software library and the associated research that made it possible were funded by CNRS and the ERC Consolidator
+Grant [Socsemics](https://socsemics.huma-num.fr/) (grant #772743).
+
+<a href="https://socsemics.huma-num.fr/" style="margin:0px">
+  <img src="docs/source/_static/socsemics.png" width="200">
+</a>
+
+## License
+
+[MIT](https://choosealicense.com/licenses/mit/)

hyperbase-0.8.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+hyperbase/__init__.py,sha256=n-PM2j8J7dTXw6U0wzW0RvNGL1GDB4zPrEoLsvc4h2M,66
+hyperbase/constants.py,sha256=WsJN2e9W_y0l5duM14U3IFu9owNZwPfwQ5Ckd9IgSTw,132
+hyperbase/hyperedge.py,sha256=2_Ox3Gmr2oD3eIf5U-eyCgETyAnwzX-KuOMoKPrz380,38870
+hyperbase/parsers/__init__.py,sha256=PKS2pEcSg04GTasj-fUPXObepo7OA3XY-11amTQGS8s,1229
+hyperbase/parsers/correctness.py,sha256=DR1TtKstkYwpQ52269nLGfIhHb_kv8UkR02rrdeU0Zc,12494
+hyperbase/parsers/parser.py,sha256=DrsZ_f_EvRrJ2wdpdbcVOnlwenbOgrjkpgwc5tEnKGU,1602
+hyperbase/parsers/utils.py,sha256=aj0FwKZo-rr5u-T7wRzNKdS09Sm9eslLna3XXpsMaOE,671
+hyperbase/patterns/__init__.py,sha256=NO7tdoymCjeJyH9V56I82lNdt5VU1oo4LfE8A9eoGQs,990
+hyperbase/patterns/argroles.py,sha256=9vx76c8kHHMVN26-UqQUlRwSRt8xKctL8J765ls-WUc,4649
+hyperbase/patterns/atoms.py,sha256=SNKi77yoZkoN9sg8vspm-yNIfzHfEmFxpmWG-Gp3fJA,3459
+hyperbase/patterns/common.py,sha256=fUTbU9bv6uPOEDl41HtxiJJ7Ic2sny3HnUh0vyR7toQ,5644
+hyperbase/patterns/counter.py,sha256=fQwkQj7vX80myzoaPQPXdmgHcueCBIKTf_iUi91NjYw,5387
+hyperbase/patterns/entrypoints.py,sha256=QBbNSurfXbaS5IIomvYnumpmxYecRr044r5UnouXndI,3120
+hyperbase/patterns/matcher.py,sha256=FG1uJjH6uekChvkIzWDWG45Dm4nn2mbBqtKbEs4He-0,8951
+hyperbase/patterns/merge.py,sha256=nbyykuSy-yBUsQXfqkli-FXoVTRn87QYZEF8KWYtusI,1657
+hyperbase/patterns/properties.py,sha256=7vpz2wyxbajDCTpkdFrm9cPrbmL9urKwiUvBmd1gN0s,1947
+hyperbase/patterns/utils.py,sha256=BvnLzWKHWt389b2-CUvj9pBA4OQk5tfFpYOSJ8uRI24,3777
+hyperbase/patterns/variables.py,sha256=tNx3z-wsVextPMu6ZzTv_BmgFfgaKdrBnITCH0n0sjk,4727
+hyperbase-0.8.0.dist-info/METADATA,sha256=WuZCTNk_v3c52q4ytbRfreI0TnEEhOu6-9_dCHEUqnc,2669
+hyperbase-0.8.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+hyperbase-0.8.0.dist-info/licenses/AUTHORS,sha256=V_ronS38DRrVTALZyRiRk0-ox8OreFVqw1WOt9D7n4I,176
+hyperbase-0.8.0.dist-info/licenses/LICENSE,sha256=6p_7YBrzvSBO3phQeZm2sRg0JmEKiyBJwzZVwseDaGE,1118
+hyperbase-0.8.0.dist-info/RECORD,,

hyperbase-0.8.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hyperbase-0.8.0.dist-info/licenses/AUTHORS

@@ -0,0 +1,5 @@
+Telmo Menezes <telmo@telmomenezes.net>
+Chih-Chun Chen <c.chen@abmcet.net>
+Camille Roth <roth@cmb.hu-berlin.de>
+Kexin Ren <kren4@ualberta.ca>
+Max Reinhard <mail@max-reinhard.de>

hyperbase-0.8.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (C) 2026 CNRS - Centre national de la recherche scientifique
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.