{"id":16328721,"url":"https://github.com/trueagi-io/hyperon-experimental","last_synced_at":"2026-03-07T04:04:14.066Z","repository":{"id":36955571,"uuid":"408812681","full_name":"trueagi-io/hyperon-experimental","owner":"trueagi-io","description":"MeTTa programming language implementation","archived":false,"fork":false,"pushed_at":"2026-02-11T11:11:59.000Z","size":10310,"stargazers_count":228,"open_issues_count":90,"forks_count":82,"subscribers_count":14,"default_branch":"main","last_synced_at":"2026-02-11T19:35:34.402Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://metta-lang.dev","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trueagi-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-09-21T12:32:52.000Z","updated_at":"2026-02-11T11:04:22.000Z","dependencies_parsed_at":"2023-10-11T13:33:28.454Z","dependency_job_id":"792b0446-f692-497e-b275-b3db47346dc8","html_url":"https://github.com/trueagi-io/hyperon-experimental","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/trueagi-io/hyperon-experimental","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trueagi-io%2Fhyperon-experimental","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trueagi-io%2Fhyperon-experimental/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trueagi-io%2Fhyperon-experimental/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trueagi-io%2Fhyperon-experimental/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trueagi-io","download_url":"https://codeload.github.com/trueagi-io/hyperon-experimental/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trueagi-io%2Fhyperon-experimental/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30207394,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T03:24:23.086Z","status":"ssl_error","status_checked_at":"2026-03-07T03:23:11.444Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-10T23:14:29.058Z","updated_at":"2026-03-07T04:04:09.048Z","avatar_url":"https://github.com/trueagi-io.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"![CI](https://github.com/trueagi-io/hyperon-experimental/actions/workflows/ci-auto.yml/badge.svg)\n\n# Overview\n\nOpenCog Hyperon is a substantially revised, novel version of OpenCog - which is currently at an active\npre-alpha stage of development and experimentation. One of the focuses in the Hyperon design is a successor\nto the OpenCog Classic Atomese language with clear semantics supporting meta-language features,\ndifferent types of inference, etc. What we have landed on is an \"Atomese 2\" language called MeTTa (Meta Type Talk).\n\nIn order to get familiar with MeTTa one can visit [MeTTa website](https://metta-lang.dev)\nand watch video with different [MeTTa examples explained](https://singularitynet.zoom.us/rec/share/VqHmU37XtbS7VnKY474tkTvvTglsgOIfsI-21MXWxVm_in7U3tGPcfjjiE0P_15R.yUwPdCzEONSUx1EL?startTime=1650636238000).\nThe examples of MeTTa programs can be found in [./python/tests/scripts](./python/tests/scripts) directory.\nPlease look at the [Python unit tests](./python/tests) to understand how one can use MeTTa from Python.\nMore complex usage scenarios are located at [MeTTa examples repo](https://github.com/trueagi-io/metta-examples).\nA lot of different materials can be found on [OpenCog wiki server](https://wiki.opencog.org/w/Hyperon).\nAlso see [MeTTa specification](https://wiki.opencog.org/w/File:MeTTa_Specification.pdf).\n\nIf you want to contribute the project please see the [contributing guide](./docs/CONTRIBUTING.md) first.\nIf you find troubles with the installation, see the [Troubleshooting](#troubleshooting) section below.\nFor development related instructions see the [development guide](./docs/DEVELOPMENT.md).\n\n# Using the latest release version\n\nIt is the most simple way of getting MeTTa interpreter especially if you are a Python developer.\nThe following command installs the latest release version from PyPi package repository:\n```\npython3 -m pip install hyperon\n```\nIf you encountered `externally-managed-environment` error then create and activate a Python virtual environment. One can use `venv`, `virtualenv` or `conda` virtual environment (please see Python's [Creating Virtual Environments](https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments) or Anaconda's [Creating an environment from an environment.yml file](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-from-an-environment-yml-file) instructions, [environment.yaml](./environment.yaml) for conda). One more option is using `--break-system-packages` Pip flag: `python3 -m pip install hyperon --break-system-packages`.\n\nAnother way is using released Docker image:\n```\ndocker run -ti trueagi/hyperon:latest\n```\n\nAfter installing package or starting Docker container run MeTTa Python based\ninterpreter:\n```\nmetta-py\n```\n\nUsing Docker you can also run Rust REPL:\n```\nmetta-repl\n``` \n\n# Using latest development version\n\n## Docker\n\nA docker image can be used as a ready to run stable and predictable development\nenvironment. Docker 26.0.0 or greater version is required to build image\nmanually.\n\nBuild Docker image from a local copy of the repo running:\n```\ndocker build -t trueagi/hyperon .\n```\n\nOr build it without local copy of the repo running:\n```\ndocker build \\\n    --build-arg BUILDKIT_CONTEXT_KEEP_GIT_DIR=1 \\\n    -t trueagi/hyperon \\\n    http://github.com/trueagi-io/hyperon-experimental.git#main\n```\n\nUse `--target build` option to create an image which keeps the full build\nenvironment and can be used for developing interpreter:\n```\ndocker build --target build -t trueagi/hyperon .\n```\n\nIf the docker image doesn't work, please raise an\n[issue](https://github.com/trueagi-io/hyperon-experimental/issues).\n\n## Manual installation\n\n### Prerequisites\n\n* Install the latest stable Rust, see [Rust installation\npage](https://www.rust-lang.org/tools/install). Make sure your\n`PATH` variable includes `$HOME/.cargo/bin` directory after installing\nRust (see the Notes at the installation page).\n\n  Requirements for building C and Python API\n  * Python3 and Python3-dev (3.8 or later)\n  * Pip (23.1.2 or later)\n  * GCC (7.5 or later)\n  * CMake (3.24 or later)\n\n  To support Git based modules (enabled by default):\n  * OpenSSL library\n  * Zlib library\n\n  To support DAS integration (enabled by default):\n  * Protobuf compiler\n\n* Install cbindgen:\n```\ncargo install --force cbindgen\n```\n\n* Install Conan and make default Conan profile:\n```\npython3 -m pip install conan==2.19.1\nconan profile detect --force\n```\n\n* Upgrade Pip to the required version:\n```\npython3 -m pip install pip==23.1.2\n```\n\n# Build and run\n\n## Rust library and REPL\n\nBuild and test the Rust binaries:\n```\ncargo test\n```\n\nThe experimental features can be enabled by editing\n[Cargo.toml](./lib/Cargo.toml) file before compilation or by using `--features`\n[command line option](https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options).\nSee comments in the `[features]` section of the file for the features\ndescriptions.\n\nRun examples:\n```\ncargo run --example sorted_list\n```\n\nRun Rust REPL:\n```\ncargo run --bin metta-repl\n```\nYou can also find executable at `./target/debug/metta-repl`.\n\nTo enable logging during running tests or examples export `RUST_LOG`\nenvironment variable:\n```\nRUST_LOG=hyperon=debug cargo test\n```\n\nRunning benchmarks requires nightly toolchain so they can be run using:\n```\ncargo +nightly bench --features benchmark\n```\n\nGenerate docs:\n```\ncargo doc --no-deps\n```\nDocs can be found at `./target/doc/hyperon/index.html`.\n\n## C and Python API\n\nCreate build directory and initialize CMake project:\n```\nmkdir -p build\ncd build\ncmake ..\n```\n\nCommands for building and testing project depend on a type of a configuration\ngenerator which is used by CMake. `cmake --help` command lists supported\ngenerators at the end of its output. Default generator is marked by `*`. One\ncan select the configuration generator by specifying `-G \u003cgenerator\u003e` CMake\noption.\n\n### Single configuration generators like \"Unix Makefiles\"\n\nFor this kind of generators the build type is selected at the CMake project\ninitialization stage. To use debug build type add\n`-DCMAKE_BUILD_TYPE=Debug` CMake flag to the command above. To change the\nbuild type the whole project configuration should be regenerated.\n\nBuild and run tests commands:\n```\ncmake --build .\ncmake --build . --target check\n```\n\n### Multiple configuration generator like \"Visual Studio ...\"\n\nThis kind of generators allows generating configuration once and select it each\ntime when making build or running tests. One can add `--config` parameter to\nselect configuration. By default `Debug` configuration is built.\n\nKeep in mind that one cannot select the library used by `metta` command even in\ncase of multiple configuration generator. `metta` command uses the last\nconfiguration built.\n\nBuild and run tests commands:\n```\ncmake --build . [--config \u003cRelease|Debug\u003e]\ncmake --build . --target check [--config \u003cRelease|Debug\u003e]\n```\n\n## Running Python and MeTTa examples\n\nIn order to run examples you need to install the Python module. Please ensure\nyou built [C and Python API](#c-and-python-api) first. Then execute the\nfollowing command in the top directory of repository:\n```\npython3 -m pip install -e ./python[dev]\n```\n\nAfter this one can run unit tests within `python` directory using `pytest`:\n```\npytest ./tests\n```\n\nOne can run MeTTa script from command line:\n```\nmetta-py ./tests/scripts/\u003cname\u003e.metta\n```\n\nRun REPL:\n```\ncargo run --features python --bin metta-repl\n```\nYou can also find executable at `./target/debug/metta-repl`.\n\nRunning the REPL with Python support in a Python virtual environment like PyEnv or Conda requires additional configuration.  See [troubleshooting](#rust-repl-cannot-load-python-library)\n\n### Logger\n\nYou can enable logging by prefixing the MeTTa command line by\n\n```\nRUST_LOG=hyperon[::COMPONENT]*=LEVEL\n```\n\nwhere\n- `[::COMPONENT]*` is a, possibly empty, sequence of modules and\n  submodules of hyperon, such as `::metta`, `::metta::runner`,\n  `::common`, `::common::multitrie`, etc.\n- `LEVEL` is the log level.  Possible log levels are: `error`, `warn`,\n  `info`, `debug` and `trace`.\n\nFor example, to log all hyperon messages at the `debug` level and\nbelow, while running `script.metta`, you may type:\n\n```\nRUST_LOG=hyperon=debug metta-py script.metta\n```\n\nOr, to log all hyperon messages at the `trace` level and below,\nrestricted to module `metta` and submodule `types`, you may type:\n\n```\nRUST_LOG=hyperon::metta::types=trace metta-py script.metta\n```\n\nBy default all log messages are directed to stderr.\n\n## Troubleshooting\n\n### Conan unable to find library in remotes\n\nIf you see the following error from Conan:\n```\nERROR: Package 'libcheck/0.15.2' not resolved: Unable to find 'libcheck/0.15.2' in remotes\n```\n\nMake sure your Conan remote repository is updated to the latest URL:\n```\nconan remote update conancenter --url=\"https://center2.conan.io\"\n```\n\n### Conan claims it cannot find out the version of the C compiler\n\nIf you see the following `cmake` output:\n```\nERROR: Not able to automatically detect '/usr/bin/cc' version\nERROR: Unable to find a working compiler\n```\nTry to create the default Conan profile manually:\n```\nconan profile detect --force\n```\nIf it doesn't help, then try to manually add `compiler`, `compiler.version` and\n`compiler.libcxx` values in the default Conan profile\n(`~/.conan2/profiles/default`).\nFor example:\n```\ncompiler=gcc\ncompiler.version=7\ncompiler.libcxx=libstdc++\n```\n\n### Rust compiler shows errors\n\nPlease ensure you are using the latest stable version:\n```\nrustup update stable\n```\n\nIf you see  the following error:\n```\nfailed to select a version for `libc` \n    ... required by package `tokio v1.43.0`\n    ... which satisfies dependency `tokio = \"^1.43.0\"` of package `metta-bus-client v0.3.0 (https://github.com/singnet/das?tag=0.11.1#aeafbddf)`\n    ... which satisfies git dependency `metta-bus-client` of package `hyperon v0.2.6 (/media/sveta/hdisk4/singnet/hyperon-experimental-vit/lib)`\n    ... which satisfies path dependency `hyperon` of package `hyperonc v0.2.6 (/media/sveta/hdisk4/singnet/hyperon-experimental-vit/c)`\nversions that meet the requirements `^0.2.168` are: 0.2.175, 0.2.174, 0.2.173, 0.2.172, 0.2.171, 0.2.170, 0.2.169, 0.2.168\n\nall possible versions conflict with previously selected packages.\n```\nthen remove `Cargo.lock` file.\n\n### Importing hyperon Python module fails\n\nIf importing the hyperon module in Python\n```python\nimport hyperon\n```\n\nreturns the error:\n```\nModuleNotFoundError: No module named 'hyperonpy'\n```\n\nPlease ensure you have installed the Python module, see\n[Running Python and MeTTa examples](#running-python-and-metta-examples).\n\n### Rust REPL cannot load Python library\n\nThe REPL needs a path to the libpython library in the current environment.  This can be done one of two ways:\n\n#### On Linux\n\n##### Use `patchelf` on resulting REPL binary to link it with `libpython.so`\n```\nldd target/debug/metta-repl | grep libpython ; to find \u003clibpython-name\u003e\npatchelf --replace-needed \u003clibpython-name\u003e \u003cpath-to-libpython-in-virtual-env\u003e target/debug/metta-repl\n```\nThis must be redone each time the repl is rebuilt, e.g. with `cargo build`.\n\n##### Set the `LD_LIBRARY_PATH` environment variable prior to launching `metta-repl`\n```\nexport LD_LIBRARY_PATH=\u003cpath-to-libpython-directory-in-virtual-env\u003e\n```\n\n#### On Mac OS\n##### Use `install_name_tool` to change the REPL binary's link path for `libpython`\n```\notool -L target/debug/metta-repl | grep libpython ; to find \u003clibpython-name\u003e\ninstall_name_tool -change \u003clibpython-name\u003e \u003cpath-to-libpython-in-virtual-env\u003e target/debug/metta-repl\n```\nThis must be redone each time the repl is rebuilt, e.g. with `cargo build`.\n\n##### Set the `DYLD_FALLBACK_LIBRARY_PATH` environment variable prior to launching `metta-repl`\n```\nexport DYLD_FALLBACK_LIBRARY_PATH=\u003cpath-to-libpython-directory-in-virtual-env\u003e\n```\nThis can be done in your `~/.bashrc` file if you don't want to do it each time you launch the REPL.\n\nFor more information about linking `libpython`, see [#432](https://github.com/trueagi-io/hyperon-experimental/issues/432).\n\n# Development\n\n## Structure of the codebase\n\nMain library `libhyperon.rlib` is written in Rust language, it contains core\nAPI which can be used from other Rust projects. Source code of the library is\ndivided on three crates located under [./hyperon-common](./hyperon-common),\n[./hyperon-atom](./hyperon-atom) and [./lib](./lib) directories. It is a plain\nRust project which can be built and tested using Cargo tool.\n\n[./hyperon-common](./hyperon-common) crate contains different utility\nstructures which are not directly related to the MeTTa and Hyperon. For example\ndifferent collection and reference implementations.\n[./hyperon-atom](./hyperon-atom) crate contains core API which can be imported by\nthird-party built-in modules providers. [./lib](./lib) crate contains MeTTa\natomspace and interpreter implementations.\n\nIn order to provide API for platforms and languages other than Rust there is a\nC API export library `libhyperonc`. Source code of the library is located under\n[./c](./c) directory. The library contains Rust C API bindings and depends on\n`libhyperon.rlib` library. Native library is compiled using Cargo, C headers\nare generated using cbindgen tool.\n\nSource code of the Python integration library is located under\n[./python](./python) directory. It contains two main parts. First part is a\nnative Python library `libhyperonpy` which is written using\n[pybind11](https://github.com/pybind/pybind11), it converts Python API calls\ninto C API calls and vice versa. Second part is a Python library `hyperon`\nwhich uses `libhyperonpy` as a proxy for a C API calls.\n\nAll components which depend on `libhyperonc` are built using\n[CMake](https://cmake.org/) build tool in order to manage dependencies\nautomatically.\n\nThe diagram below demonstrates main components and dependencies between them:\n![Diagram of the structure](./docs/assets/structure.svg)\n[Source code of the diagram](./docs/assets/structure.plantuml)\n\n## Language support for IDEs\n\nDifferent IDEs may require different tweaks to support the languages\nused in the codebase. The language servers which we use\nfor development are:\n- [rust-analyzer](https://github.com/rust-lang/rust-analyzer);\n- [clangd](https://clangd.llvm.org/installation), generate compile\n  commands for the `clangd` using `cmake` variable:\n  ```\n  cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=Y ..\n  ```\n- [Python LSP server](https://github.com/python-lsp/python-lsp-server#installation).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrueagi-io%2Fhyperon-experimental","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrueagi-io%2Fhyperon-experimental","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrueagi-io%2Fhyperon-experimental/lists"}