Official implementation of "Holographic CCG Parsing" (Yamaki, Taniguchi, and Mochihashi; ACL 2023). Hol-CCG formulates CCG parsing as recursive composition in a continuous vector space, using holographic embeddings (circular correlation) as an explicit compositional operator over word and phrase vectors.
Hol-CCG supports Python >= 3.12 and is tested in CI with CPython 3.12.3. The supported public setup path is pip. From a clone of this repository, create an isolated environment and install the exact tested dependency set with:
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip==26.1.2
python -m pip install -e . -c requirements/constraints-py312.txt
python -m pip checkOptional extras (python -m pip install -e ".[<extra>]" -c requirements/constraints-py312.txt):
hub— Hugging Face Hub download of pretrained models.prolog— spaCy, for POS/lemma tagging in Prolog output. After installing, runpython -m spacy download en_core_web_smonce.wandb— Weights & Biases experiment logging.dev— the test dependencies (pytest).
The parser reads a whitespace-tokenized .raw file (one sentence per line) and
writes CCGbank-style .auto derivations.
holccg-parse \
--model_dir <model_bundle> \
--input_raw_path in.raw \
--output_auto_path out.autoThe installed command uses a bundled default configuration and resolves its
relative paths against the current working directory. Pass --config <yaml>
to use a different configuration. In a source checkout, the maintained default
is configs/parse.yaml and paths are anchored to the repository root.
From a source checkout the same entry point is available as
python scripts/parse.py --model_dir <model_bundle> --input_raw_path in.raw --output_auto_path out.auto.
from holccg import Parser
parser = Parser.from_pretrained("<model_bundle>", device="cpu")
parsed = parser.parse_tokens(
["The", "dog", "barks", "."], index=1, sentence_id="sentence.1"
)
print(parsed.status.value) # "success"
print(parsed.auto) # CCGbank .auto derivation stringRunning the snippet above against the released
ryosuke-yamaki/hol-ccg-roberta-large checkpoint prints:
success
(<T S[dcl] 0 2> (<T S[dcl] 1 2> (<T NP 1 2> (<L NP[nb]/N POS POS The NP[nb]/N>) (<L N POS POS dog N>) ) (<L S[dcl]\NP POS POS barks S[dcl]\NP>) ) (<L . POS POS . .>) )
Use device="cuda" (the default) for GPU inference.
Four trained checkpoints accompany this release on the Hugging Face Hub, one per normalization type and encoder. All models are trained on CCGbank (LDC2005T13) WSJ sections 02-21; performance metrics are measured on Dev = WSJ section 00 and Test = WSJ section 23.
| Model | Normalization | Encoder | Dev LF1 | Test LF1 | Dev Supertagging Acc. | Test Supertagging Acc. |
|---|---|---|---|---|---|---|
ryosuke-yamaki/hol-ccg-roberta-large |
real | roberta-large | 92.73 | 92.69 | 96.49 | 96.57 |
ryosuke-yamaki/hol-ccg-roberta-large-complex |
complex | roberta-large | 92.03 | 92.10 | 96.54 | 96.48 |
ryosuke-yamaki/hol-ccg-roberta-base |
real | roberta-base | 92.47 | 91.98 | 96.47 | 96.33 |
ryosuke-yamaki/hol-ccg-roberta-base-complex |
complex | roberta-base | 91.83 | 91.56 | 96.36 | 96.32 |
Pass a Hub repository ID to Parser.from_pretrained (requires the [hub]
extra) or use a local bundle directory; checkpoints are not bundled with the
source distribution.
Training reads an extracted CCGbank v1.1 release. Point ccgbank_root in the
config at that directory (containing data/AUTO, data/PARG, etc.), then run:
python scripts/train.py --config configs/train.yamlKey configuration knobs (configs/train.yaml):
pretrained_encoder_name— the HF encoder/tokenizer (defaultroberta-large).model.normalization_type/model.normalization_norm—realvscomplexholographic normalization and its scale.training.epochs,training.batch_size, and learning rates.training.spec_cache_dir— regenerable parsed-tree cache, kept outsideoutput/by default at.cache/holccg/specs/.grammar.build/grammar.min_rule_freq— build and save the CKY grammar (rule counts + head info) from the training derivations.checkpoint.save_dir— where the model bundle is written.
Weights & Biases logging is opt-in: set use_wandb: true (and install the
[wandb] extra). Its local run data defaults to output/logs/wandb/.
Evaluation reads an extracted CCGbank v1.1 release as the gold data input and a trained HolCCG model bundle:
holccg-evaluate \
--ccgbank-dir <ccgbank_root> \
--gold-dir dataset/derived/ccgbank_gold \
--output-dir output/evaluations/internal_wsj23 \
--sections 23 \
--model-dir <model_bundle>--gold-dir is optional. By default, the shared directory is derived from the
CCGbank location: dataset/ccgbank_1_1 maps to
dataset/derived/ccgbank_gold. The evaluation pipeline builds the gold bundle
on first run.
python -m pip install -e ".[dev]" -c requirements/constraints-py312.txt
python -m pytestTests that require a model bundle or licensed data are asset-gated and skip cleanly when those assets are absent.
This code is released under the MIT License (see LICENSE), with two
exceptions. The C&C-derived components — src/holccg/evaluation/candc_generate,
candc_evaluate, and ccgbank, the bundled tr* category resources, and the
derived logic in src/holccg/parsing/ccg_rules.py — remain under the C&C
non-commercial-use licence. The src/holccg/parsing/candc_grammar Python port
is covered by the Java C&C BSD 2-Clause licence. See THIRD_PARTY_NOTICES.md
and the LICENCE files bundled inside those directories. CCGbank itself is
licensed data from the Linguistic Data Consortium and is not distributed here.
@inproceedings{yamaki-etal-2023-holographic,
title = "Holographic {CCG} Parsing",
author = "Yamaki, Ryosuke and
Taniguchi, Tadahiro and
Mochihashi, Daichi",
editor = "Rogers, Anna and
Boyd-Graber, Jordan and
Okazaki, Naoaki",
booktitle = "Proceedings of the 61st Annual Meeting of the Association for Computational Linguistics (Volume 1: Long Papers)",
month = jul,
year = "2023",
address = "Toronto, Canada",
publisher = "Association for Computational Linguistics",
url = "https://aclanthology.org/2023.acl-long.15/",
doi = "10.18653/v1/2023.acl-long.15",
pages = "262--276"
}