OPENNLP-547: Add a transition-based dependency parser component

[krickert]

Adds a transition-based dependency parser: API, arc-standard maxent parser, CoNLL-U reading, evaluation, cross validation, command line tools, eval and manual chapter. The feedforward parser is #1323, stacked on this branch.

API (opennlp-api): DependencyParser, DependencySample, DependencyArc and the immutable DependencyGraph. Input validation is DependencySample.checkTokensAndTags, shared by samples and parsers, and throws IllegalArgumentException.

Parser (opennlp-runtime): DependencyParserME runs an arc-standard transition system over a classifier trained with TrainingParameters. ArcStandardOracle derives transitions from projective trees; non-projective training sentences are skipped and counted. DependencyModel persists the classifier and manifest. DependencyEvaluator and DependencyCrossValidator report UAS and LAS with and without punctuation and accept DependencyEvaluationMonitor listeners.

Formats (opennlp-formats): ConlluDependencySampleStream reads CoNLL-U. ID and HEAD are integer columns, multiword ranges and empty nodes are skipped, -tagset u or x selects UPOS or XPOS, and the data must be UTF-8.

Tools (opennlp-cli): DependencyParserTrainer, DependencyParser, DependencyParserEvaluator and DependencyParserCrossValidator, with -misclassified output.

Eval: UniversalDependencyParserEval pins scores on the English, German, Spanish and French UD treebanks from opennlp-data.zip. Eval build: https://ci-builds.apache.org/job/OpenNLP/job/eval-tests-configurable/88/

Manual: a dependency parser chapter; its examples run as ConlluDependencyParserUsageTest.

Tests: 51 in opennlp-api, 102 in opennlp-runtime, 136 in opennlp-formats, 56 in opennlp-cli for the parser and CoNLL-U classes, with checkstyle and forbiddenapis clean.

OPENNLP-547

[mawiesne]

@krickert Can you rebase this one onto main? Currently changes show up here that are now already included in main.

[krickert]

Rebased on main .. good to go

#1182 merged the diff is the parser alone, 34 new files and no change to existing code.

Also a run of the review conventions.

[jzonthemtn]

Thanks @krickert. A long open JIRA ticket for sure!

The API and graph validation look solid. I found two issues worth checking into:

• The CoNLL-U reader accepts DEPREL=_ as a label instead of skipping the incomplete annotation.
• Training with a tag such as UNK overwrites a reserved vocabulary entry, producing a model that serializes successfully but fails to reload.

What do you think about held-out accuracy tests for the neural parser, similar to the treebank evaluation for the classical parser?

[krickert]

Thanks Jeff. Both are fixed, each with a failing test committed ahead of the fix. The CoNLL-U reader now skips a sentence whose relation column is the underscore placeholder, the same way it already skipped an underscore head. The feedforward trainer no longer lets a tag or label spelled like a reserved symbol take over that symbol's embedding row; it shares the row, as words already did, so the model reloads.

On held-out accuracy: I added UniversalDependencyParserEval in opennlp-eval-tests, following the AbstractEvalTest and OPENNLP_DATA_DIR pattern. It trains both parsers on the UD 2.0 English train split and pins the dev-split scores: the transition parser at UAS 0.8182 and LAS 0.7861, the feedforward parser at UAS 0.8413 and LAS 0.8174, on 25,148 words. The numbers reproduce exactly across runs. It replaces the property-gated evaluation test that lived in opennlp-formats.

[krickert]

Eval build for this head (afd68fb) is running on Jenkins: https://ci-builds.apache.org/job/OpenNLP/job/eval-tests-configurable/74/ (eval-tests-configurable, branch OPENNLP-547-dependency-parser). It uses the opennlp-data.zip published on nightlies today and includes the new UniversalDependencyParserEval, so expect it to take longer than a regular eval run.

[krickert]

Evals passed for this, going to re-run it as I added double precision scoring.

[rzo1]

Evals passed for this, going to re-run it as I added double precision scoring.

Moved to draft for now. Please re-open as ready for review once all your additional checks and stuff are done.

[krickert]

https://ci-builds.apache.org/job/OpenNLP/job/eval-tests-configurable/76/console

Eval build is running

[krickert]

Eval ran successfully

[rzo1]

Thanks. jzonthemtn's two issues are fixed with tests, and the eval pattern is right.

My main concern is the model. FeedforwardDependencyModel is not a BaseModel: it has its own binary format (ONLP-FFDP-1) with no manifest, language, version check or artifact serializer. Once released we have to support that format. The same goes for the rest of the component shape: training takes a Settings record instead of TrainingParameters, and there's no DependencyParserFactory extends BaseToolFactory, no CLI tools, and no stream factory registration. Every other component in OpenNLP works this way, and I don't want a second model format with 3.0.0.

I'd suggest splitting it:

1. This PR: API (DependencyParser, DependencySample, DependencyGraph), the CoNLL-U reader, evaluator and arc-standard parts, aligned with the other components (Sample, serialVersionUID, TrainingParameters, factory, CLI).
2. Follow-up: the feedforward model as a BaseModel, with a new eval run.

If you'd rather keep it in one PR, the model format has to be settled before we look at the details.

Other points:

• OPENNLP-547 has no fix version. Please set 3.0.0.
• There are 147 commits, some without a JIRA key. We will squash-merge.
• Duplication, see inline comments.
• dev/download-ud-treebank.sh, its README and UdTreebankDownloadScriptTest: the build doesn't use the script, since the eval reads from opennlp-data, and the unit test starts bash. Please remove all three and the reference in dependency.xml.

[rzo1]

@krickert Can you fixed up this branch plz? It has 147 commits and I don't think they belong here.

[krickert]

R4R @rzo1

[krickert]

I'm really excited about this one. It's going to be a fun feature to have. The front end is going to look really cool. I'll rebase and mark r4r after it merges. No rush and thank you - I know this one is a larger one.

[rzo1]

Can we rebase and make use of ArgumentChecker?

[krickert]

Can we rebase and make use of ArgumentChecker?

Rebased onto main and switched the null checks to ArgumentChecks. The three combined checks now name the argument that was null.

[rzo1]

Please find my (human) review comments attached.

[krickert]

@rzo1 followed all the suggestions and agree with all of them. Please check again

[rzo1]

Can you trigger an eval run?

[krickert]

Eval build on it's way.

https://ci-builds.apache.org/job/OpenNLP/job/eval-tests-configurable/95/

[krickert]

Eval build on it's way.

https://ci-builds.apache.org/job/OpenNLP/job/eval-tests-configurable/95/

Eval green

[mawiesne]

@krickert Thx for the PR and the patience with the reviewers. The set of code and test additions is now in great shape (💠 ) and I don't see more reasons to wait. Let's bring this to main (🚀 ). We can apply fixes and (potential) simplifications with more compact, future PRs, that is, it can be done prior to OpenNLP 3.0.0 release, if needed.

[krickert]

@mawiesne - thank you for taking the time to review which has taught me so much in a short period of time. I'll say with humility: the PR-pocolapse you dealt with required so much patience, and I can't tell ya enough of how much I appreciate your work and patience to lead through and keep the quality so high. It's taught me a lot quickly - both technically and how to do things the apache way - and looking forward to further collaborations and contributions with the team.

I don't think I've had more fun with coding since I first compiled w/gcc via slackware linux for the first time in a dorm room :)