prase 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. prase-1.0.0/.github/workflows/wheels.yml +136 -0
  2. prase-1.0.0/.gitignore +16 -0
  3. prase-1.0.0/CMakeLists.txt +24 -0
  4. prase-1.0.0/LICENSE +21 -0
  5. prase-1.0.0/PKG-INFO +465 -0
  6. prase-1.0.0/README.md +445 -0
  7. prase-1.0.0/benchmarks/experiments.toml +272 -0
  8. prase-1.0.0/benchmarks/reproduce.py +442 -0
  9. prase-1.0.0/cpp/bindings.cpp +136 -0
  10. prase-1.0.0/cpp/paris.cpp +298 -0
  11. prase-1.0.0/cpp/paris.hpp +93 -0
  12. prase-1.0.0/pyproject.toml +39 -0
  13. prase-1.0.0/src/prase/__init__.py +32 -0
  14. prase-1.0.0/src/prase/__main__.py +5 -0
  15. prase-1.0.0/src/prase/_benchmark_manifest.toml +134 -0
  16. prase-1.0.0/src/prase/alignment.py +132 -0
  17. prase-1.0.0/src/prase/baselines.py +220 -0
  18. prase-1.0.0/src/prase/cli.py +118 -0
  19. prase-1.0.0/src/prase/config.py +284 -0
  20. prase-1.0.0/src/prase/datasets.py +285 -0
  21. prase-1.0.0/src/prase/decisions.py +107 -0
  22. prase-1.0.0/src/prase/embedding/__init__.py +70 -0
  23. prase-1.0.0/src/prase/embedding/base.py +294 -0
  24. prase-1.0.0/src/prase/embedding/bootea.py +370 -0
  25. prase-1.0.0/src/prase/embedding/common.py +261 -0
  26. prase-1.0.0/src/prase/embedding/gcnalign.py +197 -0
  27. prase-1.0.0/src/prase/embedding/imuse.py +329 -0
  28. prase-1.0.0/src/prase/embedding/iptranse.py +373 -0
  29. prase-1.0.0/src/prase/embedding/mtranse.py +121 -0
  30. prase-1.0.0/src/prase/embedding/multike.py +574 -0
  31. prase-1.0.0/src/prase/errors.py +13 -0
  32. prase-1.0.0/src/prase/kg.py +267 -0
  33. prase-1.0.0/src/prase/methods.py +76 -0
  34. prase-1.0.0/src/prase/metrics.py +72 -0
  35. prase-1.0.0/src/prase/paris/__init__.py +283 -0
  36. prase-1.0.0/src/prase/paris/native.py +98 -0
  37. prase-1.0.0/src/prase/paris/python.py +236 -0
  38. prase-1.0.0/src/prase/paris/state.py +137 -0
  39. prase-1.0.0/src/prase/pipeline.py +371 -0
  40. prase-1.0.0/src/prase/records.py +148 -0
  41. prase-1.0.0/src/prase/session.py +151 -0
  42. prase-1.0.0/src/prase/tsv.py +47 -0
  43. prase-1.0.0/tests/fixed_model.py +34 -0
  44. prase-1.0.0/tests/fixtures.py +59 -0
  45. prase-1.0.0/tests/test_benchmarks.py +120 -0
  46. prase-1.0.0/tests/test_data.py +261 -0
  47. prase-1.0.0/tests/test_embedding.py +270 -0
  48. prase-1.0.0/tests/test_paris.py +130 -0
  49. prase-1.0.0/tests/test_pipeline.py +380 -0
  50. prase-1.0.0/tests/test_review.py +213 -0
  51. prase-1.0.0/tests/test_session.py +99 -0
  52. prase-1.0.0/tests/wheel_smoke.py +20 -0
@@ -0,0 +1,136 @@
1
+ name: Build and test wheels
2
+
3
+ # Every push and pull request builds and tests the wheels and the sdist.
4
+ # A manual run (workflow_dispatch) also uploads them to TestPyPI.
5
+ # A v* tag also uploads them to PyPI and creates a GitHub Release.
6
+
7
+ on:
8
+ push:
9
+ pull_request:
10
+ workflow_dispatch:
11
+
12
+ permissions:
13
+ contents: read
14
+
15
+ jobs:
16
+ wheels:
17
+ name: Wheels (${{ matrix.os }}, ${{ matrix.arch }})
18
+ strategy:
19
+ fail-fast: false
20
+ matrix:
21
+ include:
22
+ - os: ubuntu-latest
23
+ arch: x86_64
24
+ - os: ubuntu-24.04-arm
25
+ arch: aarch64
26
+ - os: windows-latest
27
+ arch: AMD64
28
+ - os: macos-latest
29
+ arch: arm64
30
+ runs-on: ${{ matrix.os }}
31
+ steps:
32
+ - uses: actions/checkout@v4
33
+ - uses: actions/setup-python@v5
34
+ with:
35
+ python-version: "3.12"
36
+ - run: python -m pip install "cibuildwheel==4.3.5"
37
+ - run: python -m cibuildwheel --output-dir wheelhouse
38
+ env:
39
+ CIBW_ARCHS: ${{ matrix.arch }}
40
+ - uses: actions/upload-artifact@v4
41
+ with:
42
+ name: wheels-${{ matrix.os }}-${{ matrix.arch }}
43
+ path: wheelhouse/*.whl
44
+
45
+ sdist:
46
+ name: Source distribution
47
+ runs-on: ubuntu-latest
48
+ steps:
49
+ - uses: actions/checkout@v4
50
+ - uses: actions/setup-python@v5
51
+ with:
52
+ python-version: "3.12"
53
+ - run: python -m pip install build
54
+ - run: python -m build --sdist
55
+ # Install from the sdist alone, compiling the native engine, then run the tests.
56
+ - run: python -m pip install "$(ls dist/*.tar.gz)[rdf]"
57
+ - run: python tests/wheel_smoke.py
58
+ - run: python -m unittest discover -s tests -v
59
+ - uses: actions/upload-artifact@v4
60
+ with:
61
+ name: sdist
62
+ path: dist/*.tar.gz
63
+
64
+ check-version:
65
+ name: Check the release version
66
+ if: startsWith(github.ref, 'refs/tags/v')
67
+ runs-on: ubuntu-latest
68
+ steps:
69
+ - uses: actions/checkout@v4
70
+ - uses: actions/setup-python@v5
71
+ with:
72
+ python-version: "3.12"
73
+ - name: Compare the tag with the version in pyproject.toml
74
+ run: |
75
+ version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
76
+ if [ "v$version" != "$GITHUB_REF_NAME" ]; then
77
+ echo "::error::Tag $GITHUB_REF_NAME does not match version $version in pyproject.toml"
78
+ exit 1
79
+ fi
80
+
81
+ publish-testpypi:
82
+ name: Publish to TestPyPI
83
+ if: github.event_name == 'workflow_dispatch'
84
+ needs: [wheels, sdist]
85
+ runs-on: ubuntu-latest
86
+ environment:
87
+ name: testpypi
88
+ url: https://test.pypi.org/project/prase/
89
+ permissions:
90
+ id-token: write
91
+ steps:
92
+ - uses: actions/download-artifact@v4
93
+ with:
94
+ path: dist
95
+ merge-multiple: true
96
+ - uses: pypa/gh-action-pypi-publish@release/v1
97
+ with:
98
+ repository-url: https://test.pypi.org/legacy/
99
+ skip-existing: true
100
+
101
+ publish-pypi:
102
+ name: Publish to PyPI
103
+ if: startsWith(github.ref, 'refs/tags/v')
104
+ needs: [wheels, sdist, check-version]
105
+ runs-on: ubuntu-latest
106
+ environment:
107
+ name: pypi
108
+ url: https://pypi.org/project/prase/
109
+ permissions:
110
+ id-token: write
111
+ steps:
112
+ - uses: actions/download-artifact@v4
113
+ with:
114
+ path: dist
115
+ merge-multiple: true
116
+ - uses: pypa/gh-action-pypi-publish@release/v1
117
+
118
+ github-release:
119
+ name: Create the GitHub Release
120
+ needs: publish-pypi
121
+ runs-on: ubuntu-latest
122
+ permissions:
123
+ contents: write
124
+ steps:
125
+ - uses: actions/download-artifact@v4
126
+ with:
127
+ path: dist
128
+ merge-multiple: true
129
+ - name: Attach the wheels and the sdist to a release for this tag
130
+ env:
131
+ GH_TOKEN: ${{ github.token }}
132
+ run: >-
133
+ gh release create "$GITHUB_REF_NAME" dist/*
134
+ --repo "$GITHUB_REPOSITORY"
135
+ --title "PRASE ${GITHUB_REF_NAME#v}"
136
+ --generate-notes
prase-1.0.0/.gitignore ADDED
@@ -0,0 +1,16 @@
1
+ /.venv/
2
+ /.toolchain/
3
+ /.benchmarks/
4
+ /data/
5
+ /docs/
6
+ /build/
7
+ /dist/
8
+ /runs/
9
+ __pycache__/
10
+ *.py[cod]
11
+ *.egg-info/
12
+ .pytest_cache/
13
+ .ruff_cache/
14
+ .coverage
15
+ .coverage.*
16
+ /wheelhouse/
@@ -0,0 +1,24 @@
1
+ cmake_minimum_required(VERSION 3.18)
2
+ project(prase LANGUAGES NONE)
3
+
4
+ option(PRASE_BUILD_NATIVE "Build the PARIS native engine" ON)
5
+ if(NOT PRASE_BUILD_NATIVE)
6
+ return()
7
+ endif()
8
+ enable_language(CXX)
9
+
10
+ set(PYBIND11_FINDPYTHON ON)
11
+ find_package(Python REQUIRED COMPONENTS Interpreter Development.Module)
12
+ find_package(pybind11 CONFIG REQUIRED)
13
+ find_package(Threads REQUIRED)
14
+
15
+ pybind11_add_module(_paris NO_EXTRAS cpp/bindings.cpp cpp/paris.cpp)
16
+ target_compile_features(_paris PRIVATE cxx_std_17)
17
+ target_link_libraries(_paris PRIVATE Threads::Threads)
18
+ if(MSVC)
19
+ target_compile_options(_paris PRIVATE /fp:precise)
20
+ elseif(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
21
+ target_compile_options(_paris PRIVATE -fno-fast-math -ffp-contract=off)
22
+ endif()
23
+
24
+ install(TARGETS _paris LIBRARY DESTINATION prase RUNTIME DESTINATION prase)
prase-1.0.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Zhiyuan Qi
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
prase-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,465 @@
1
+ Metadata-Version: 2.4
2
+ Name: prase
3
+ Version: 1.0.0
4
+ Summary: Probabilistic reasoning and semantic embedding for knowledge graph alignment
5
+ Author: Zhiyuan Qi
6
+ License-Expression: MIT
7
+ License-File: LICENSE
8
+ Project-URL: Homepage, https://github.com/qizhyuan/PRASE
9
+ Project-URL: Repository, https://github.com/qizhyuan/PRASE
10
+ Requires-Python: >=3.11
11
+ Requires-Dist: numpy>=1.26
12
+ Requires-Dist: scipy>=1.11
13
+ Requires-Dist: huggingface_hub>=0.34
14
+ Provides-Extra: train
15
+ Requires-Dist: torch>=2.2; extra == "train"
16
+ Requires-Dist: rapidfuzz>=3.8; extra == "train"
17
+ Provides-Extra: rdf
18
+ Requires-Dist: rdflib>=7.1; extra == "rdf"
19
+ Description-Content-Type: text/markdown
20
+
21
+ # PRASE
22
+
23
+ PRASE aligns the entities of two knowledge graphs without labeled pairs. It combines probabilistic reasoning with semantic embeddings ([Qi et al., IJCAI 2021](https://www.ijcai.org/proceedings/2021/278)):
24
+
25
+ 1. [PARIS](https://doi.org/10.14778/2078331.2078332) (Suchanek et al., VLDB 2011) matches entities, relations, and attributes by probabilistic reasoning over the graphs' facts and equal literals.
26
+ 2. An embedding model trains on the confident matches, proposes counterparts for the remaining entities, and scores entity similarity.
27
+ 3. A second PARIS pass starts from the proposed pairs and adds the embedding similarity to its evidence.
28
+
29
+ The package provides:
30
+
31
+ - PARIS reasoning with a C++ engine and a NumPy engine that give identical alignments. The PARIS authors publish their Java implementation at [dig-team/PARIS](https://github.com/dig-team/PARIS).
32
+ - Six embedding models in PyTorch: BootEA, GCNAlign, IMUSE, IPTransE, MTransE, and MultiKE.
33
+ - Pipelines built from interchangeable steps, with records of every intermediate alignment and score.
34
+ - Optional manual review: approved pairs stay fixed and rejected pairs are never matched.
35
+ - Benchmark recipes that reproduce the paper's experiments on six datasets.
36
+
37
+ The original implementation released with the IJCAI 2021 paper is on the [`legacy`](https://github.com/qizhyuan/PRASE/tree/legacy) branch.
38
+
39
+ ## PRASEMap Web Application
40
+
41
+ [PRASEMap](https://prasemap.qizhy.com/) is a web application built on PRASE, first presented as a demo at
42
+ CIKM 2021 ([Qi et al., CIKM 2021](https://doi.org/10.1145/3459637.3481972)). In the browser you can upload
43
+ two graphs or choose a built-in pair, run PARIS or PRASE, and review the matches. Approved and rejected
44
+ pairs carry over to the next run.
45
+
46
+ ## Installation
47
+
48
+ PRASE requires Python 3.11 or newer and installs from [PyPI](https://pypi.org/project/prase/):
49
+
50
+ ```console
51
+ # PARIS, the pipelines, and the benchmark downloader.
52
+ python -m pip install prase
53
+ # PyTorch and RapidFuzz for the embedding models.
54
+ python -m pip install "prase[train]"
55
+ # RDFLib for RDF input.
56
+ python -m pip install "prase[rdf]"
57
+ ```
58
+
59
+ The wheels for Linux (x86_64 and aarch64), Windows (x64), and macOS (Apple silicon) on Python 3.11 to 3.15 include the compiled PARIS engine. On other platforms pip builds the engine from source, which requires CMake 3.18+ and a C++17 compiler.
60
+
61
+ To install from a clone of the repository:
62
+
63
+ ```console
64
+ git clone https://github.com/qizhyuan/PRASE.git
65
+ cd PRASE
66
+ # PARIS with the C++ engine, built from source.
67
+ python -m pip install .
68
+ # The NumPy engine alone, without building the C++ engine.
69
+ python -m pip install . --config-settings wheel.cmake=false
70
+ ```
71
+
72
+ Embedding models train on the CPU by default. For GPU training, install the CUDA build of PyTorch that the [PyTorch installer](https://pytorch.org/get-started/locally/) selects for your system, for example:
73
+
74
+ ```console
75
+ python -m pip install torch --index-url https://download.pytorch.org/whl/cu132
76
+ ```
77
+
78
+ The examples below select the GPU with `options={"device": "cuda"}`. Run files take `device = "cuda"` in the model options, and the benchmark runner takes `--device cuda`.
79
+
80
+ ## Quick Start
81
+
82
+ PARIS on two small graphs:
83
+
84
+ ```python
85
+ from prase import KG, methods
86
+
87
+ left = KG.from_triples(
88
+ [("l:paris", "capital_of", "l:france")],
89
+ [("l:paris", "name", "Paris"), ("l:france", "name", "France")],
90
+ )
91
+ right = KG.from_triples(
92
+ [("r:paris", "capitalOf", "r:france")],
93
+ [("r:paris", "label", "Paris"), ("r:france", "label", "France")],
94
+ )
95
+ result = methods.paris().run(left, right)
96
+ print(result.alignment.to_ids(left, right))
97
+ ```
98
+
99
+ PRASE and SE on a benchmark dataset, after [signing in to Hugging Face](#benchmarks):
100
+
101
+ ```python
102
+ from prase import Alignment, load_benchmark, methods
103
+
104
+ # Download and verify D-W-15K-V2 on first use.
105
+ data = load_benchmark("D-W-15K-V2")
106
+
107
+ # PRASE: PARIS, BootEA, and PARIS again with BootEA's proposals and embeddings.
108
+ prase = methods.prase("bootea", options={"device": "cuda"})
109
+ result = prase.run(data.left, data.right, reference=data.reference())
110
+ print(result.scores)
111
+
112
+ # SE: GCNAlign trains on the first fold's training links and predicts the other entities.
113
+ fold = data.splits[0]
114
+ train = data.reference(fold.train)
115
+ se = methods.embedding_only("gcnalign", options={"device": "cuda"})
116
+ result = se.run(data.left, data.right, seeds=Alignment(train[:, 0], train[:, 1]),
117
+ reference=data.reference(fold.valid + fold.test))
118
+ print(result.scores)
119
+ ```
120
+
121
+ ## Align Your Own Graphs
122
+
123
+ Each graph consists of relation triples `head<TAB>predicate<TAB>tail` and optional attribute triples `entity<TAB>predicate<TAB>value`. A TOML run file names the inputs, the method, and the output directory:
124
+
125
+ ```toml
126
+ # run.toml
127
+ [input]
128
+ reference = "reference.tsv" # optional pairs for evaluation
129
+ seeds = "seeds.tsv" # optional known pairs
130
+
131
+ [input.left]
132
+ relations = "left-relations.tsv"
133
+ attributes = "left-attributes.tsv"
134
+
135
+ [input.right]
136
+ relations = "right-relations.tsv"
137
+ attributes = "right-attributes.tsv"
138
+
139
+ [method]
140
+ name = "prase"
141
+ model = "gcnalign"
142
+ options = { device = "cpu" }
143
+
144
+ [output]
145
+ directory = "runs/my-alignment"
146
+ ```
147
+
148
+ ```console
149
+ # Align the graphs and write the results to runs/my-alignment.
150
+ prase run run.toml
151
+ # Score an alignment against the ent_links file of an OpenEA folder.
152
+ prase evaluate runs/my-alignment/alignment.tsv --dataset path/to/openea-folder
153
+ # List the embedding models.
154
+ prase models
155
+ ```
156
+
157
+ Paths are relative to the run file. Seed and reference files have one `left<TAB>right` pair per line. Every input and method is also available in Python:
158
+
159
+ | Input | Run File | Python |
160
+ | --- | --- | --- |
161
+ | TSV triples | `relations` and `attributes` in `[input.left]` and `[input.right]` | `KG.from_tsv("left-relations.tsv", "left-attributes.tsv")` |
162
+ | RDF | `rdf = "left.ttl"` in `[input.left]` and `[input.right]` | `KG.from_rdf("left.ttl")` |
163
+ | OpenEA folder | `dataset = "path/to/folder"` in `[input]` | `load_dataset("path/to/folder")` |
164
+ | Benchmark dataset | `benchmark = "D-W-15K-V2"` in `[input]` | `load_benchmark("D-W-15K-V2")` |
165
+
166
+ | Method | `[method]` in a Run File | Python |
167
+ | --- | --- | --- |
168
+ | PARIS | `name = "paris"` | `methods.paris()` |
169
+ | PRASE | `name = "prase"`, `model = "bootea"`, `rounds = 1` | `methods.prase("bootea", rounds=1)` |
170
+ | SE | `name = "embedding-only"`, `model = "gcnalign"`, with `[input].seeds` | `methods.embedding_only("gcnalign")`, run with `seeds=` |
171
+ | STR-Match: edit similarity of names | `name = "str-match"` | `methods.name_match()` |
172
+ | EMB-Match: cosine of averaged name word vectors | `name = "emb-match"`, `word_vectors = "data/wiki-news-300d-1M.vec"` | `methods.name_embedding_match("data/wiki-news-300d-1M.vec")` |
173
+
174
+ The output directory holds the final alignment, the run settings, and one folder per step:
175
+
176
+ ```text
177
+ runs/my-alignment/
178
+ ├── alignment.tsv left ID, right ID, score
179
+ ├── run.json settings and per-step scores
180
+ ├── 01-paris/ alignment.tsv, predicates.tsv, step.json
181
+ ├── 02-embed-gcnalign/ proposals.tsv, step.json with the training summary
182
+ └── 03-paris/ alignment.tsv, predicates.tsv, step.json
183
+ ```
184
+
185
+ ### Manual Review
186
+
187
+ Every method runs without review. To correct an alignment, list approved and rejected pairs in a TSV file and rerun with it into a new output directory:
188
+
189
+ ```text
190
+ left right decision
191
+ http://dbpedia.org/resource/Illinois http://www.wikidata.org/entity/Q1204 approve
192
+ http://dbpedia.org/resource/Illinois http://www.wikidata.org/entity/Q1297 reject
193
+ ```
194
+
195
+ ```console
196
+ prase run run.toml --decisions review.tsv --output runs/my-alignment-reviewed
197
+ ```
198
+
199
+ `Session` keeps the graphs indexed between PARIS runs for interactive review:
200
+
201
+ ```python
202
+ from prase import Session, load_benchmark
203
+
204
+ data = load_benchmark("D-W-15K-V2")
205
+ session = Session(data.left, data.right)
206
+ session.run()
207
+
208
+ # PARIS matches DBpedia's Illinois to Chicago (Q1297). Illinois (Q1204) is the runner-up.
209
+ illinois = "http://dbpedia.org/resource/Illinois"
210
+ for right_id, candidate in session.candidates(illinois, limit=3):
211
+ print(right_id, round(candidate.score, 3))
212
+
213
+ session.approve(illinois, "http://www.wikidata.org/entity/Q1204")
214
+ session.fix_predicate("http://dbpedia.org/ontology/birthPlace", "http://www.wikidata.org/entity/P19")
215
+ session.run()
216
+ print(session.matches()[:5])
217
+ ```
218
+
219
+ ## Custom Pipelines and Models
220
+
221
+ A pipeline is a list of steps. Each step receives the current state (graphs, alignment, proposals, embeddings) and returns an updated copy. One PRASE round is `[ParisStep(), Embed(...), ParisStep()]`:
222
+
223
+ ```python
224
+ from dataclasses import dataclass, replace
225
+
226
+ from prase import Embed, ParisConfig, ParisStep, Pipeline
227
+
228
+
229
+ @dataclass
230
+ class KeepConfident:
231
+ minimum: float = 0.2
232
+ name = "keep-confident"
233
+
234
+ def run(self, state, context):
235
+ alignment = state.alignment.above(self.minimum)
236
+ context.report(kept=len(alignment))
237
+ return replace(state, alignment=alignment)
238
+
239
+
240
+ paris = ParisConfig(iterations=10, embedding_weight=0.3)
241
+ pipeline = Pipeline([
242
+ ParisStep(paris),
243
+ Embed("gcnalign", options={"device": "cuda"}, seed_threshold=0.1),
244
+ ParisStep(paris),
245
+ KeepConfident(),
246
+ ])
247
+ result = pipeline.run(data.left, data.right, reference=data.reference())
248
+ ```
249
+
250
+ ### Embedding Feedback
251
+
252
+ `Embed` trains on PARIS matches scoring at least `seed_threshold` and passes two kinds of feedback to the next `ParisStep`:
253
+
254
+ - **Proposed pairs** become starting matches. Their scores, multiplied by `proposal_weight` (default 1.0), are the starting probabilities, and PARIS replaces a pair when it finds a better counterpart.
255
+ - **Embeddings** enter every candidate score after the first `warmup` iterations: `(1 - embedding_weight) * structural + embedding_weight * cosine`, with `embedding_weight` defaulting to 0.2.
256
+
257
+ ```python
258
+ ParisStep(paris, proposal_weight=0.5) # proposed pairs start at half their scores
259
+ ParisStep(paris, use_embeddings=False) # proposed pairs only
260
+ ParisStep(paris, use_proposals=False) # embedding similarity only
261
+ ```
262
+
263
+ ```toml
264
+ # The same settings in a run file.
265
+ [method]
266
+ name = "prase"
267
+ model = "bootea"
268
+ proposal_weight = 0.5
269
+ # share_embeddings = false # proposed pairs only
270
+ # propose = false # embedding similarity only
271
+
272
+ [method.paris]
273
+ embedding_weight = 0.3
274
+ ```
275
+
276
+ ### Literal Matching
277
+
278
+ PARIS starts from pairs of equal literals. A `literal_matcher` returns other scored pairs of literal indices:
279
+
280
+ ```python
281
+ from prase import Alignment, methods
282
+
283
+
284
+ def casefold_literals(left, right):
285
+ """Pair literals that are equal after case folding."""
286
+ index = {value.casefold(): j for j, value in enumerate(right.literals)}
287
+ return Alignment.from_pairs(
288
+ (i, index[value.casefold()], 1.0) for i, value in enumerate(left.literals) if value.casefold() in index
289
+ )
290
+
291
+
292
+ result = methods.paris(literal_matcher=casefold_literals).run(left, right)
293
+ ```
294
+
295
+ ### Embedding Models
296
+
297
+ An embedding model has a `name` and a method `fit(data, *, seed) -> Embeddings`. `data` holds both graphs (`data.left`, `data.right`), the seed pairs as an `(n, 2)` index array (`data.seeds`), the candidate entities of each graph (`data.candidates`), and the rejected pairs, which must not become training pairs (`data.rejected`). The optional `propose(embeddings, data) -> Alignment` chooses the proposals and should skip the rejected pairs. Without it, each candidate proposes its nearest eligible neighbor.
298
+
299
+ ```python
300
+ # my_models.py
301
+ import zlib
302
+
303
+ import numpy as np
304
+
305
+ from prase import Embeddings
306
+ from prase.kg import entity_names
307
+
308
+
309
+ class NameTrigrams:
310
+ """Embed each entity by the hashed character trigrams of its name."""
311
+
312
+ name = "name-trigrams"
313
+
314
+ def __init__(self, width: int = 256):
315
+ self.width = width
316
+
317
+ def fit(self, data, *, seed):
318
+ return Embeddings(self.vectors(data.left), self.vectors(data.right), "cosine")
319
+
320
+ def propose(self, embeddings, data):
321
+ # Propose mutual nearest neighbors instead of each entity's nearest neighbor.
322
+ return embeddings.reciprocal_nearest(*data.candidates, excluded=data.rejected)
323
+
324
+ def vectors(self, kg):
325
+ vectors = np.zeros((kg.num_entities, self.width))
326
+ for row, name in enumerate(entity_names(kg)):
327
+ text = f" {(name or '').casefold()} "
328
+ for start in range(len(text) - 2):
329
+ vectors[row, zlib.crc32(text[start:start + 3].encode()) % self.width] += 1
330
+ return vectors
331
+ ```
332
+
333
+ ```python
334
+ from my_models import NameTrigrams
335
+
336
+ result = methods.prase(NameTrigrams()).run(data.left, data.right, reference=data.reference())
337
+ ```
338
+
339
+ ### Custom Steps in Run Files
340
+
341
+ Run files list `[[steps]]` instead of `[method]` and load models and steps by import path:
342
+
343
+ ```toml
344
+ [[steps]]
345
+ type = "paris"
346
+
347
+ [[steps]]
348
+ type = "embed"
349
+ model = "my_models:NameTrigrams"
350
+ options = { width = 512 }
351
+
352
+ [[steps]]
353
+ type = "paris"
354
+ embedding_weight = 0.3
355
+
356
+ # KeepConfident from the pipeline example, saved in my_steps.py.
357
+ [[steps]]
358
+ type = "my_steps:KeepConfident"
359
+ minimum = 0.2
360
+ ```
361
+
362
+ ```console
363
+ # Run from the folder that holds my_models.py and my_steps.py, so that Python can import them.
364
+ python -m prase run run.toml
365
+ ```
366
+
367
+ [`config.py`](https://github.com/qizhyuan/PRASE/blob/main/src/prase/config.py) documents every run-file setting.
368
+
369
+ ## Benchmarks
370
+
371
+ The benchmark collection [qizhy777/prase-benchmarks](https://huggingface.co/datasets/qizhy777/prase-benchmarks) contains the six datasets of the paper: EN-FR-100K-V2, EN-DE-100K-V2, D-W-100K-V2, D-Y-100K-V2, and D-W-15K-V2 from [OpenEA](https://github.com/nju-websoft/OpenEA), and MED-BBK-9K from [industry-eval-EA](https://github.com/ZihengZZH/industry-eval-EA). PRASE pins a revision of the collection and checks the SHA-256 of every file it downloads. Downloads require a Hugging Face account with read access to the collection. The `hf` command comes with PRASE:
372
+
373
+ ```console
374
+ # Sign in with an access token from https://huggingface.co/settings/tokens.
375
+ hf auth login
376
+ # Download and verify all six datasets into the Hugging Face cache.
377
+ prase download
378
+ # Or download some of them.
379
+ prase download D-W-15K-V2 MED-BBK-9K
380
+ ```
381
+
382
+ MultiKE and EMB-Match read the English FastText vectors [wiki-news-300d-1M.vec](https://fasttext.cc/docs/en/english-vectors.html):
383
+
384
+ ```console
385
+ # Download the 682 MB archive, extract the vectors into data/, and check their SHA-256.
386
+ prase download --word-vectors
387
+ # Or extract them into another folder.
388
+ prase download --word-vectors --vectors-dir path/to/vectors
389
+ ```
390
+
391
+ To fetch the vectors by hand:
392
+
393
+ ```console
394
+ curl -O https://dl.fbaipublicfiles.com/fasttext/vectors-english/wiki-news-300d-1M.vec.zip
395
+ python -m zipfile -e wiki-news-300d-1M.vec.zip data
396
+ ```
397
+
398
+ `benchmarks/reproduce.py` runs the recipes in [`benchmarks/experiments.toml`](https://github.com/qizhyuan/PRASE/blob/main/benchmarks/experiments.toml) and writes each run to `<output>/<experiment>/<dataset>/`. A run stops when its folder already holds a run, so give each reproduction a new `--output` directory and pass the same directory to `list` and `report`. The script and the recipes are in the repository:
399
+
400
+ ```console
401
+ # Get the benchmark scripts and install PRASE with the embedding models.
402
+ git clone https://github.com/qizhyuan/PRASE.git
403
+ cd PRASE
404
+ python -m pip install "prase[train]"
405
+ # PARIS on every dataset.
406
+ python benchmarks/reproduce.py run --method paris --all-datasets --output runs/reproduction
407
+ # PRASE with BootEA and with MultiKE on every dataset.
408
+ python benchmarks/reproduce.py run --method prase --model bootea --all-datasets --device cuda --output runs/reproduction
409
+ python benchmarks/reproduce.py run --method prase --model multike --all-datasets --device cuda --word-vectors data/wiki-news-300d-1M.vec --output runs/reproduction
410
+ # SE: train on the benchmark folds and rank the test links.
411
+ python benchmarks/reproduce.py run --method se --model gcnalign --dataset D-W-15K-V2 --output runs/reproduction
412
+ # One recipe by name, such as PRASE-BootEA with proposed pairs only.
413
+ python benchmarks/reproduce.py run --experiment prase-bootea-m --all-datasets --device cuda --output runs/reproduction
414
+ # Every recipe and its status, including the feedback ablations, round sweeps, and name-matching baselines.
415
+ python benchmarks/reproduce.py list --output runs/reproduction
416
+ # Tabulate the completed runs.
417
+ python benchmarks/reproduce.py report runs/reproduction
418
+ # The entire suite in its own directory.
419
+ python benchmarks/reproduce.py run --all --device cuda --word-vectors data/wiki-news-300d-1M.vec --output runs/full-suite
420
+ ```
421
+
422
+ ### Results
423
+
424
+ F1 of the final alignment with one PRASE round, seed 0, and embedding training on an NVIDIA RTX 5090. Embedding training is not bit-for-bit reproducible, so scores vary slightly from run to run. The values in parentheses are from the paper.
425
+
426
+ | Dataset | PARIS | PRASE-BootEA | PRASE-MultiKE |
427
+ | --- | --- | --- | --- |
428
+ | EN-FR-100K-V2 | 0.933 (0.926) | 0.954 (0.954) | 0.962 (0.954) |
429
+ | EN-DE-100K-V2 | 0.952 (0.948) | 0.966 (0.965) | 0.977 (0.972) |
430
+ | D-W-100K-V2 | 0.864 (0.854) | 0.891 (0.890) | 0.868 (0.859) |
431
+ | D-Y-100K-V2 | 0.986 (0.983) | 0.994 (0.993) | 0.998 (0.996) |
432
+ | D-W-15K-V2 | 0.905 (0.897) | 0.917 (0.923) | 0.911 (0.907) |
433
+ | MED-BBK-9K | 0.498 (0.499) | 0.578 (0.557) | 0.728 (0.711) |
434
+
435
+ ## Citation
436
+
437
+ If you use PRASE, please cite:
438
+
439
+ ```bibtex
440
+ @inproceedings{qi2021prase,
441
+ title = {Unsupervised Knowledge Graph Alignment by Probabilistic Reasoning and Semantic Embedding},
442
+ author = {Qi, Zhiyuan and Zhang, Ziheng and Chen, Jiaoyan and Chen, Xi and Xiang, Yuejia and Zhang, Ningyu and Zheng, Yefeng},
443
+ booktitle = {Proceedings of the Thirtieth International Joint Conference on Artificial Intelligence},
444
+ publisher = {International Joint Conferences on Artificial Intelligence Organization},
445
+ pages = {2019--2025},
446
+ year = {2021},
447
+ doi = {10.24963/ijcai.2021/278},
448
+ url = {https://doi.org/10.24963/ijcai.2021/278}
449
+ }
450
+
451
+ @inproceedings{qi2021prasemap,
452
+ title = {{PRASEMap}: A Probabilistic Reasoning and Semantic Embedding based Knowledge Graph Alignment System},
453
+ author = {Qi, Zhiyuan and Zhang, Ziheng and Chen, Jiaoyan and Chen, Xi and Zheng, Yefeng},
454
+ booktitle = {Proceedings of the 30th ACM International Conference on Information \& Knowledge Management},
455
+ publisher = {Association for Computing Machinery},
456
+ pages = {4779--4783},
457
+ year = {2021},
458
+ doi = {10.1145/3459637.3481972},
459
+ url = {https://doi.org/10.1145/3459637.3481972}
460
+ }
461
+ ```
462
+
463
+ ## License
464
+
465
+ PRASE is released under the [MIT License](LICENSE).