keyrecon 0.1.0__tar.gz

keyrecon-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Byong-Rae Ryu and Sunghwa Lee
+
+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.

keyrecon-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: keyrecon
+Version: 0.1.0
+Summary: Author-keyword reconstruction with Adaptive Composite Keyword Scoring (Adaptive CKS)
+Author: Byong-Rae Ryu, Sunghwa Lee
+License-Expression: MIT
+Keywords: keyword reconstruction,author keywords,bibliometrics,keyphrase extraction,spaCy,Adaptive CKS
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: pandas<4,>=2.0
+Provides-Extra: nlp
+Requires-Dist: spacy<4,>=3.8; extra == "nlp"
+Provides-Extra: transformers
+Requires-Dist: spacy<4,>=3.8; extra == "transformers"
+Requires-Dist: spacy-transformers<2,>=1.3; extra == "transformers"
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: build<2,>=1.2; extra == "dev"
+Dynamic: license-file
+
+# KeyRecon
+
+**KeyRecon** is a Python toolkit for reconstructing missing author keywords using
+**Adaptive Composite Keyword Scoring (Adaptive CKS)**.
+
+KeyRecon treats missing author keywords as a metadata-reconstruction problem rather
+than as unrestricted keyword extraction. It separates candidate generation, canonicalization,
+feature fitting, composite scoring, decision-threshold calibration, ranking, and provenance.
+
+## Status
+
+- **English (`en_reference`)**: reference implementation of the frozen Adaptive CKS architecture.
+- **Chinese (`zh_experimental`)**: experimental language adapter.
+- **Japanese (`ja_experimental`)**: experimental language adapter.
+- **Korean (`ko_experimental`)**: experimental language adapter.
+
+The multilingual adapters are deliberately marked **experimental**. The Adaptive CKS paper
+evaluates the English reference architecture; it does not establish that the same candidate
+policy, weights, or thresholds are optimal in Chinese, Japanese, or Korean.
+
+## Why KeyRecon?
+
+Ordinary keyword extraction asks which expressions are salient in a document.
+KeyRecon instead assumes that author-keyword metadata are observed for some records and
+genuinely missing for others. Observed records can therefore supply development-only evidence,
+while missing records are reconstruction targets. Observed author keywords are never overwritten.
+
+## Install for development
+
+```bash
+python -m pip install -e ".[dev,nlp]"
+```
+
+For transformer profiles:
+
+```bash
+python -m pip install -e ".[dev,transformers]"
+```
+
+Then install the spaCy pipeline explicitly:
+
+```bash
+python -m spacy download en_core_web_trf
+```
+
+Available KeyRecon profiles can be inspected with:
+
+```bash
+keyrecon models
+keyrecon setup --lang en
+keyrecon profile --lang en
+```
+
+## Minimal CSV workflow
+
+Input:
+
+```csv
+record_id,title,abstract,author_keywords
+d1,Sign language phonology,This paper studies phonological structure in sign language,sign language;phonology
+d2,Syntactic movement,We investigate long-distance movement and locality,movement;locality
+d3,Visual language structure,The analysis examines phonological patterning in a visual language,
+```
+
+Run:
+
+```bash
+keyrecon run input.csv predictions.csv --lang en --mode adaptive
+```
+
+`--mode adaptive` searches the prespecified 61-weight × 13-threshold Adaptive CKS space
+using development-only out-of-fold evidence from records with observed author keywords.
+
+For an English reference-weight run with development-only threshold calibration:
+
+```bash
+keyrecon run input.csv predictions.csv --lang en --mode reference
+```
+
+The command writes a long-form prediction CSV and a JSON run manifest.
+
+## Python API
+
+```python
+import pandas as pd
+from keyrecon import KeyRecon
+
+records = pd.read_csv("input.csv", keep_default_na=False)
+
+model = KeyRecon(language="en", mode="adaptive")
+predictions = model.fit_reconstruct_missing(records)
+
+print(model.fit_summary_)
+print(predictions[["record_id", "canonical_key", "cks_score", "rank"]])
+```
+
+## Language profiles
+
+| code | profile | spaCy pipeline | status |
+|---|---|---|---|
+| `en` | `en_reference` | `en_core_web_trf` | reference |
+| `zh` | `zh_experimental` | `zh_core_web_trf` | experimental |
+| `ja` | `ja_experimental` | `ja_core_news_trf` | experimental |
+| `ko` | `ko_experimental` | `ko_core_news_lg` | experimental |
+
+Language selection is explicit for reproducibility. Automatic language detection is intentionally
+not enabled in v0.1.0.
+
+## Scientific boundary
+
+The English reference profile preserves the study's key invariants:
+
+- title and abstract are parsed independently before candidate union;
+- the reference candidate span is 1–4 lexical units;
+- source provenance is retained and no title score bonus is used;
+- the five score components are TF–IDF, document frequency, dispersion, domain focus,
+  and phrase quality;
+- the operational decision score is rounded to 12 decimals;
+- eligibility is inclusive (`rounded_score >= threshold`);
+- ranking is score-descending with canonical-key ascending as deterministic tie-break;
+- at most 10 predictions are returned;
+- no below-threshold fallback is used.
+
+The public package does **not** bundle licensed Web of Science records, abstracts, held-out gold
+labels, or the full corpus-derived canonical mapping. Therefore exact paper-level replay also
+requires the private/licensed frozen research assets. The package provides the algorithmic
+reference implementation and provenance hashes for those external frozen assets.
+
+See `docs/scientific_boundary.md` and `docs/reproducibility.md`.
+
+## Multilingual design
+
+The Adaptive CKS scoring core is separated from the language adapter. Replacing the NLP model
+alone is not treated as sufficient evidence of multilingual validity: tokenization, candidate
+boundaries, POS behavior, and PhraseQuality are language-sensitive.
+
+See `docs/multilingual.md`.
+
+## Citation
+
+See `CITATION.cff`.
+
+## License
+
+MIT.

keyrecon-0.1.0/README.md

@@ -0,0 +1,145 @@
+# KeyRecon
+
+**KeyRecon** is a Python toolkit for reconstructing missing author keywords using
+**Adaptive Composite Keyword Scoring (Adaptive CKS)**.
+
+KeyRecon treats missing author keywords as a metadata-reconstruction problem rather
+than as unrestricted keyword extraction. It separates candidate generation, canonicalization,
+feature fitting, composite scoring, decision-threshold calibration, ranking, and provenance.
+
+## Status
+
+- **English (`en_reference`)**: reference implementation of the frozen Adaptive CKS architecture.
+- **Chinese (`zh_experimental`)**: experimental language adapter.
+- **Japanese (`ja_experimental`)**: experimental language adapter.
+- **Korean (`ko_experimental`)**: experimental language adapter.
+
+The multilingual adapters are deliberately marked **experimental**. The Adaptive CKS paper
+evaluates the English reference architecture; it does not establish that the same candidate
+policy, weights, or thresholds are optimal in Chinese, Japanese, or Korean.
+
+## Why KeyRecon?
+
+Ordinary keyword extraction asks which expressions are salient in a document.
+KeyRecon instead assumes that author-keyword metadata are observed for some records and
+genuinely missing for others. Observed records can therefore supply development-only evidence,
+while missing records are reconstruction targets. Observed author keywords are never overwritten.
+
+## Install for development
+
+```bash
+python -m pip install -e ".[dev,nlp]"
+```
+
+For transformer profiles:
+
+```bash
+python -m pip install -e ".[dev,transformers]"
+```
+
+Then install the spaCy pipeline explicitly:
+
+```bash
+python -m spacy download en_core_web_trf
+```
+
+Available KeyRecon profiles can be inspected with:
+
+```bash
+keyrecon models
+keyrecon setup --lang en
+keyrecon profile --lang en
+```
+
+## Minimal CSV workflow
+
+Input:
+
+```csv
+record_id,title,abstract,author_keywords
+d1,Sign language phonology,This paper studies phonological structure in sign language,sign language;phonology
+d2,Syntactic movement,We investigate long-distance movement and locality,movement;locality
+d3,Visual language structure,The analysis examines phonological patterning in a visual language,
+```
+
+Run:
+
+```bash
+keyrecon run input.csv predictions.csv --lang en --mode adaptive
+```
+
+`--mode adaptive` searches the prespecified 61-weight × 13-threshold Adaptive CKS space
+using development-only out-of-fold evidence from records with observed author keywords.
+
+For an English reference-weight run with development-only threshold calibration:
+
+```bash
+keyrecon run input.csv predictions.csv --lang en --mode reference
+```
+
+The command writes a long-form prediction CSV and a JSON run manifest.
+
+## Python API
+
+```python
+import pandas as pd
+from keyrecon import KeyRecon
+
+records = pd.read_csv("input.csv", keep_default_na=False)
+
+model = KeyRecon(language="en", mode="adaptive")
+predictions = model.fit_reconstruct_missing(records)
+
+print(model.fit_summary_)
+print(predictions[["record_id", "canonical_key", "cks_score", "rank"]])
+```
+
+## Language profiles
+
+| code | profile | spaCy pipeline | status |
+|---|---|---|---|
+| `en` | `en_reference` | `en_core_web_trf` | reference |
+| `zh` | `zh_experimental` | `zh_core_web_trf` | experimental |
+| `ja` | `ja_experimental` | `ja_core_news_trf` | experimental |
+| `ko` | `ko_experimental` | `ko_core_news_lg` | experimental |
+
+Language selection is explicit for reproducibility. Automatic language detection is intentionally
+not enabled in v0.1.0.
+
+## Scientific boundary
+
+The English reference profile preserves the study's key invariants:
+
+- title and abstract are parsed independently before candidate union;
+- the reference candidate span is 1–4 lexical units;
+- source provenance is retained and no title score bonus is used;
+- the five score components are TF–IDF, document frequency, dispersion, domain focus,
+  and phrase quality;
+- the operational decision score is rounded to 12 decimals;
+- eligibility is inclusive (`rounded_score >= threshold`);
+- ranking is score-descending with canonical-key ascending as deterministic tie-break;
+- at most 10 predictions are returned;
+- no below-threshold fallback is used.
+
+The public package does **not** bundle licensed Web of Science records, abstracts, held-out gold
+labels, or the full corpus-derived canonical mapping. Therefore exact paper-level replay also
+requires the private/licensed frozen research assets. The package provides the algorithmic
+reference implementation and provenance hashes for those external frozen assets.
+
+See `docs/scientific_boundary.md` and `docs/reproducibility.md`.
+
+## Multilingual design
+
+The Adaptive CKS scoring core is separated from the language adapter. Replacing the NLP model
+alone is not treated as sufficient evidence of multilingual validity: tokenization, candidate
+boundaries, POS behavior, and PhraseQuality are language-sensitive.
+
+See `docs/multilingual.md`.
+
+## Citation
+
+See `CITATION.cff`.
+
+## License
+
+MIT.

keyrecon-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "keyrecon"
+version = "0.1.0"
+description = "Author-keyword reconstruction with Adaptive Composite Keyword Scoring (Adaptive CKS)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  {name = "Byong-Rae Ryu"},
+  {name = "Sunghwa Lee"},
+]
+keywords = [
+  "keyword reconstruction",
+  "author keywords",
+  "bibliometrics",
+  "keyphrase extraction",
+  "spaCy",
+  "Adaptive CKS",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Text Processing :: Linguistic",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+  "numpy>=1.26,<3",
+  "pandas>=2.0,<4",
+]
+
+[project.optional-dependencies]
+nlp = [
+  "spacy>=3.8,<4",
+]
+transformers = [
+  "spacy>=3.8,<4",
+  "spacy-transformers>=1.3,<2",
+]
+dev = [
+  "pytest>=8,<10",
+  "build>=1.2,<2",
+]
+
+[project.scripts]
+keyrecon = "keyrecon.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+keyrecon = ["profiles/*.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-q"

keyrecon-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

keyrecon-0.1.0/src/keyrecon/__init__.py

@@ -0,0 +1,12 @@
+"""KeyRecon: author-keyword reconstruction with Adaptive CKS."""
+
+from .version import __version__
+from .engine import KeyRecon
+from .config import AdaptiveCKSWeights, EN_REFERENCE_WEIGHTS
+
+__all__ = [
+    "__version__",
+    "KeyRecon",
+    "AdaptiveCKSWeights",
+    "EN_REFERENCE_WEIGHTS",
+]

keyrecon-0.1.0/src/keyrecon/candidate_table.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import pandas as pd
+
+from .canonical import Canonicalizer
+from .languages.base import LanguageAdapter
+
+def aggregate_candidates(
+    occurrences: pd.DataFrame,
+    canonicalizer: Canonicalizer,
+    adapter: LanguageAdapter,
+) -> pd.DataFrame:
+    if occurrences.empty:
+        return pd.DataFrame(columns=[
+            "record_id", "canonical_key", "candidate_length",
+            "total_occurrence_count", "title_occurrence_count",
+            "abstract_occurrence_count", "source_class", "representative_surface",
+        ])
+    work = occurrences.copy()
+    work["canonical_key"] = work["candidate_exact_key"].map(canonicalizer)
+    work = work.loc[work["canonical_key"].astype(str).str.strip().ne("")].copy()
+
+    rows = []
+    for (rid, canonical), group in work.groupby(["record_id", "canonical_key"], sort=True):
+        title_n = int(group["source_field"].eq("TITLE").sum())
+        abstract_n = int(group["source_field"].eq("ABSTRACT").sum())
+        if title_n and abstract_n:
+            source_class = "TITLE_AND_ABSTRACT"
+        elif title_n:
+            source_class = "TITLE_ONLY"
+        else:
+            source_class = "ABSTRACT_ONLY"
+        surface_counts = (
+            group.groupby("candidate_surface").size()
+            .sort_values(ascending=False, kind="stable")
+        )
+        max_count = int(surface_counts.max())
+        representative = sorted(surface_counts.loc[surface_counts.eq(max_count)].index.astype(str))[0]
+        fallback_length = int(group.loc[group["candidate_surface"].astype(str).eq(representative),
+                                        "lexical_unit_count"].iloc[0])
+        rows.append({
+            "record_id": str(rid),
+            "canonical_key": str(canonical),
+            "candidate_length": adapter.canonical_length(str(canonical), fallback=fallback_length),
+            "total_occurrence_count": int(len(group)),
+            "title_occurrence_count": title_n,
+            "abstract_occurrence_count": abstract_n,
+            "source_class": source_class,
+            "representative_surface": representative,
+        })
+    return pd.DataFrame(rows)

keyrecon-0.1.0/src/keyrecon/candidates/__init__.py

@@ -0,0 +1,4 @@
+from .english_reference import EnglishReferenceCandidateGenerator
+from .generic import GenericSpacyCandidateGenerator
+
+__all__ = ["EnglishReferenceCandidateGenerator", "GenericSpacyCandidateGenerator"]