# hyperbase: a Python library for Semantic Hypergraphs

> Hyperbase represents a sentence as an ordered, recursive hyperlink rather than a triple. It is a research library from CNRS-funded work, and its README points elsewhere for installation and the manual.

**hyperquest-hq/hyperbase** — A foundational library for Semantic Hypergraphs

- Repository: https://github.com/hyperquest-hq/hyperbase
- Website: https://hyperquest.ai/hyperbase
- Stars: 650 · Forks: 77
- Language: Python
- License: MIT
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/hyperquest-hq-hyperbase

## The representation problem hyperbase was built around

A knowledge graph built on triples forces a sentence apart. "Einstein first published the theory of relativity in 1905" becomes a subject, a predicate and an object, and the word "first", the date, and the fact that publication is the relation all have to be pushed into separate nodes or dropped. Hyperbase starts from the opposite direction. Its README describes a Semantic Hypergraph as a way to represent that same sentence as "an ordered, recursive hyperlink", and the figure in the README shows the sentence decomposed into hyperedge blocks rather than a triple.

The two words doing the work are ordered and recursive. Ordered means the sequence of elements inside a hyperedge carries meaning, so "first published" is not the same structure as "published first". Recursive means a hyperedge can contain other hyperedges, so a clause can sit inside another clause without flattening into separate statements. That is the specific gap this library addresses, and it is a real one for anyone doing text analysis where word order and nesting change the meaning of a claim.

The intended audience is stated in the package metadata rather than the README. The classifiers list Intended Audience :: Science/Research and the topics include cognitive science, computational social science and natural language understanding. The funding note names CNRS and the ERC Consolidator Grant Socsemics (grant #772743) as the source of support. This is a research artifact first, with an eye on production use second.

## What the repository layout tells you about the architecture

The package lives under src/hyperbase, with tests in a separate top-level tests directory and documentation under docs/ built with mkdocs.yml. The build backend is hatchling, and the version is read dynamically from a VERSION file at the repository root rather than hard-coded in pyproject.toml. That combination is a small signal about how the project is run: the version file is the single source of truth, and the changelog sits next to it.

The runtime dependency list is short: tqdm, prompt-toolkit and rich. All three are presentation or progress libraries. tqdm draws progress bars, rich formats terminal output, prompt-toolkit builds interactive prompts. Nothing in that list is a graph database, a parser or a numerical stack. The practical reading is that hyperbase is a representation and manipulation layer, not a storage or query system. It gives you the data structure and the operations on it, and leaves persistence and querying to whatever you build around it.

The presence of prompt-toolkit and rich alongside a [project.scripts] entry named hyperbase points to an interactive console as part of the package. The entry point is declared as hyperbase.cli:main, so installing the package puts a hyperbase command on the path that starts that console. The README itself does not describe the console, which is a gap: the manual at hyperquest.ai/hyperbase is where the README sends you for it.

Development tooling is unusually strict for a research library. mypy runs in strict mode, and ruff is configured with a long select list covering pycodestyle, Pyflakes, import sorting, pyupgrade, bugbear, flake8-simplify, Ruff-specific rules, flake8-quotes, flake8-comprehensions, flake8-pytest-style, pep8-naming and flake8-annotations. A pre-commit configuration is present at the root. The effect is that contributions are held to annotation and naming standards that many research codebases skip.

## Getting hyperbase and what the packaging metadata commits to

The README does not contain install commands. It states that "Installation instructions, the manual and more information can be found here" and links to https://hyperquest.ai/hyperbase. That page is the authoritative source, and nothing in the repository substitutes for it.

What the repository does commit to is the packaging contract in pyproject.toml. The project is named hyperbase, the version is read dynamically from the VERSION file, and the wheel target is declared as packages = ["src/hyperbase"]. The interpreter floor is stated as requires-python = ">=3.10":

```toml
[project]
name = "hyperbase"
dynamic = ["version"]
description = "A foundational library for Semantic Hypergraphs"
readme = "README.md"
license = "MIT"
requires-python = ">=3.10"
```

The runtime dependencies are three, and they are all terminal-facing rather than computational:

```toml
dependencies = [
    "tqdm>=4.65.0",
    "prompt-toolkit>=3.0.0",
    "rich>=13.0.0",
]
```

One console entry point is declared, so an installed package is expected to expose a hyperbase command that resolves to hyperbase.cli:main:

```toml
[project.scripts]
hyperbase = "hyperbase.cli:main"
```

There is also a dev extra for people working on the library itself. It pulls in mypy, ruff, pre-commit, types-passlib, coverage, mkdocs-material, mkdocstrings, click and pytest:

```toml
[project.optional-dependencies]
dev = [
    "mypy>=1.8.0",
    "ruff>=0.2.2",
    "pre-commit>=3.6.2",
    "types-passlib>=1.7.7.20240106",
    "coverage>=7.4.3",
    "mkdocs-material>=9.5",
    "mkdocstrings[python]>=0.24",
    "click==8.2.1",  # pinned to prevent bug with mkdocs reload on change
    "pytest>=9.0.0",
]
```

That click pin carries a comment explaining it exists "to prevent bug with mkdocs reload on change". It concerns the documentation toolchain, not the library, but it means a dev environment and a production environment can resolve click differently. What the console does once it starts is not in the README, so the manual is the only place to find the commands it accepts.

## Where hyperbase stops being the right tool

The dependency list is the clearest limitation. There is no database driver, no serialization format declared in pyproject.toml, and no query language mentioned anywhere in the README. If your requirement is "store a million hypergraphs and query them by pattern", hyperbase does not claim to do that, and nothing in the repository suggests it does. You would be building the persistence and query layer yourself.

The README is also thin in a way that matters for evaluation. It shows one example sentence and a figure, then moves straight to contributing and funding. There is no API walkthrough, no list of operations, no explanation of how a hyperedge is constructed in code. The manual is linked but not reproduced. For a library whose entire value is a data structure, the absence of a worked code example in the README means you cannot judge the ergonomics of the API without leaving the repository.

The maturity signal is honest but worth reading carefully. The classifier says Development Status :: 4 - Beta. The version history shows v0.8.0, v0.9.0 and v0.10.0 released within roughly two and a half weeks in March and April 2026, which is a fast iteration cadence on a pre-1.0 API. Expect the surface to move. The last push to the default branch was on 2026-09-09, so the repository is not dormant, but a beta classifier plus a 0.x version means you should pin the version you depend on and read CHANGELOG.md before upgrading.

Finally, the name collides. Searching for "hyperbase" surfaces retro game consoles, a console product, and unrelated hardware, none of which have anything to do with this library. That is a discovery problem rather than a technical one, but it will cost you time when you search for help.

## How this differs from a triple-based knowledge graph toolkit

The obvious comparison is with RDF and property-graph tooling, where the unit of meaning is a triple or an edge between two nodes. The difference in approach is structural, not cosmetic. In a triple store, a relation with more than two participants is reified: you create an intermediate node and attach the extra participants to it. Order is not part of the model, so if the sequence of words matters you encode it as additional properties.

Hyperbase inverts that. The hyperedge is the primitive, it holds an ordered sequence of elements, and it can contain other hyperedges directly. The README's example sentence is the illustration: "Einstein first published the theory of relativity in 1905" is presented as one ordered, recursive hyperlink rather than a set of statements that need reification to stay connected. If your data is naturally n-ary and order-sensitive, this model avoids a layer of translation that triple stores force on you.

The trade-off is ecosystem. Triple stores come with SPARQL, mature storage engines, and decades of tooling. Hyperbase comes with a Python data structure, an interactive console and a manual. Choosing it means accepting that you are working closer to the representation and further from the infrastructure. For a research pipeline where the representation is the contribution, that is a reasonable exchange. For a production system that needs federated queries across existing datasets, it is not.

## Licence, maintenance and the upgrade cost you should budget for

The licence is MIT, declared both in the README and in pyproject.toml as license = "MIT", with a LICENSE file at the repository root. MIT is permissive: it allows commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is the practical implication, not legal advice, and if your organisation has a policy review for dependencies you should route the LICENSE file through it rather than relying on the classifier.

The repository is not archived, and the last push to main was on 2026-09-09. The release cadence in the changelog is the number that matters for upgrade planning: three minor releases between 2026-03-26 and 2026-04-11. On a 0.x version, minor releases can carry breaking changes, and the README does not document a deprecation policy or a rollback path. The CHANGELOG.md file at the root is the only place to find out what actually changed, and the VERSION file is what the build reads, so a pinned dependency plus a changelog read before each bump is the realistic upgrade procedure.

The dependency footprint keeps maintenance cheap on the runtime side. Three pure-Python presentation libraries, no compiled extensions, no system services. Upgrading hyperbase will not drag a database migration behind it. The cost sits in the API surface instead, which is why pinning matters more here than the dependency list suggests.

## Conclusion

Hyperbase fits researchers and NLP engineers who need to encode a full sentence, with order and nesting, as one structure instead of decomposing it into subject-predicate-object triples. It does not fit anyone who needs a query language, a storage engine or an installation path documented inside this repository, since the README defers installation and the manual to hyperquest.ai/hyperbase. Before adopting it, read that manual and confirm the CLI entry point and the three runtime dependencies (tqdm, prompt-toolkit, rich) match your environment, and check the CHANGELOG for what changed between v0.8.0 and v0.10.0.

## FAQ

### What is hyperbase?

It is a Python library for working with Semantic Hypergraphs, representing a sentence such as "Einstein first published the theory of relativity in 1905" as an ordered, recursive hyperlink. It is released under the MIT licence and requires Python 3.10 or later.

### How do I install hyperbase?

The README does not give install commands; it states that installation instructions and the manual are at https://hyperquest.ai/hyperbase. The package metadata declares requires-python >= 3.10 and a hatchling build with the package under src/hyperbase.

### Does hyperbase include a console command?

Yes. The pyproject.toml [project.scripts] table defines a hyperbase entry point mapped to hyperbase.cli:main, and the runtime dependencies include prompt-toolkit and rich, which support an interactive terminal interface. The README does not document the console's commands.

## Sources

- [hyperquest-hq/hyperbase on GitHub](https://github.com/hyperquest-hq/hyperbase)
- [License: MIT](https://github.com/hyperquest-hq/hyperbase/blob/main/LICENSE)
- [Project website](https://hyperquest.ai/hyperbase)
- [README](https://github.com/hyperquest-hq/hyperbase/blob/main/README.md)
- [Releases](https://github.com/hyperquest-hq/hyperbase/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hyperquest-hq-hyperbase