ovos-wordnet-plugin

OVOS plugin that exposes WordNet as a RetrievalEngine and a ToolBox with two agent tools.

Supports 30+ languages via the wn package with Open English WordNet 2024, ODENet for German, and OMW 1.4 packs for other languages. Lexicons are downloaded automatically on first use and cached locally.

For languages whose OMW pack has no native definitions (most non-EN/DE languages), the engine fetches the English OEWN definition and translates it into the target language using the OVOS translation plugin configured on the system (default: ovos-translate-plugin-server).

Installation

pip install ovos-wordnet-plugin

The first query downloads the required WordNet lexicon (~30–60 MB for English). Subsequent calls are served from the local cache with no network access.

Components

WordnetRetrievalEngine

An OVOS RetrievalEngine that returns natural-language passages for a word lookup. Each passage covers one WordNet sense and is formatted as:

dog (noun): a member of the genus Canis. Also known as: domestic dog, Canis familiaris. Example: the dog barked all night

When the query matches a locale intent pattern (e.g. "what are the antonyms of happy?") the engine resolves that specific relation and returns a single rendered dialog response instead.

Passages are drawn from all four parts of speech (noun → verb → adjective → adverb) up to the requested k limit.

from ovos_wordnet_plugin import WordnetRetrievalEngine

engine = WordnetRetrievalEngine()
for passage, score in engine.query("bank", lang="en", k=3):
    print(f"[{score:.2f}] {passage}")

[0.70] bank (noun): sloping land (especially the slope beside a body of water). Example: he sat on the bank of the river
[0.70] bank (noun): a financial institution that accepts deposits. Also known as: depository financial institution.
[0.70] bank (verb): tip laterally. Example: the pilot had to bank the aircraft

Intent-style queries return a single spoken-language response:

for passage, score in engine.query("what are the hyponyms of dog", lang="en"):
    print(f"[{score:.2f}] {passage}")
# [0.90] The hyponyms of dog are: poodle, corgi, dalmatian, ...

WordnetToolbox

An OVOS ToolBox that registers two agent tools.

define_word

Returns definitions grouped by part of speech, plus usage examples.

from ovos_wordnet_plugin import WordnetToolbox, DefineWordArgs

tb = WordnetToolbox()
out = tb.define_word(DefineWordArgs(word="run", lang="en", pos="verb"))
for pos_label, definition in out.definitions:
    print(f"{pos_label}: {definition}")
# verb: move fast by using one's feet, with one foot off the ground at any given time
print(out.examples[:2])
# ['she ran her first marathon', ...]

word_relations

Returns synonyms, antonyms, hypernyms, hyponyms, and holonyms.

from ovos_wordnet_plugin import WordnetToolbox, WordRelationsArgs

tb = WordnetToolbox()
out = tb.word_relations(WordRelationsArgs(word="dog", lang="en", pos="noun"))
print("synonyms:", out.synonyms)     # ['dog', 'domestic dog', 'Canis familiaris']
print("hypernyms:", out.hypernyms)   # ['canine', 'canid', ...]
print("hyponyms:", out.hyponyms[:3]) # ['corgi', 'dalmatian', 'poodle']
print("holonyms:", out.holonyms)     # ['pack', ...]

Low-level Wordnet helper

The Wordnet class provides direct access to all WordNet relations:

from ovos_wordnet_plugin import Wordnet, NOUN, ADJ

# First sense only
data = Wordnet.get("bank", pos=NOUN, lang="en")

# All senses (generator)
for sense in Wordnet.search("bank", pos=NOUN, lang="en"):
    print(sense["definition"])

# Individual lookups
Wordnet.get_definition("bank", lang="en")
Wordnet.get_lemmas("bank", lang="en")
Wordnet.get_hypernyms("dog", lang="en")
Wordnet.get_hyponyms("dog", lang="en")
Wordnet.get_holonyms("dog", lang="en")
Wordnet.get_antonyms("good", pos=ADJ, lang="en")
Wordnet.get_root_hypernyms("dog", lang="en")
Wordnet.common_hypernyms("dog", "cat", lang="en")

Supported Languages

English uses OEWN 2024 (native definitions throughout). German uses ODENet (native definitions for ~85% of synsets). All other languages use their OMW 1.4 pack, which provides lemmas but typically no glosses — definitions are translated from English via the configured OVOS translation plugin.

Running tests

pip install pytest
pytest tests/

License

Apache 2.0 — see LICENSE.