Metadata-Version: 2.4
Name: ovos-wordnet-plugin
Version: 0.1.0
Summary: OVOS WordNet plugin — dictionary definitions and lexical relations
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: ovos-utils<1.0.0,>=0.7.0
Requires-Dist: ovos-plugin-manager<3.0.0,>=2.3.0a1
Requires-Dist: wn>=0.9
Requires-Dist: pydantic

# ovos-wordnet-plugin

OVOS plugin that exposes [WordNet](https://wordnet.princeton.edu/) as a
`RetrievalEngine` and a `ToolBox` with two agent tools.

Supports 30+ languages via the [`wn`](https://pypi.org/project/wn/) package
with [Open English WordNet 2024](https://github.com/globalwordnet/english-wordnet),
[ODENet](https://github.com/hdaSprachtechnologie/odenet) for German, and
[OMW 1.4](https://omwn.org/) 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

```bash
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`](https://github.com/OpenVoiceOS/ovos-plugin-manager)
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.

```python
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:

```python
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.

| Argument | Type | Default | Description |
|---|---|---|---|
| `word` | str | — | Word to define |
| `lang` | str | `"en"` | BCP-47 language code |
| `pos` | str | `"any"` | `"noun"`, `"verb"`, `"adjective"`, `"adverb"`, or `"any"` |

```python
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.

| Argument | Type | Default | Description |
|---|---|---|---|
| `word` | str | — | Word to look up |
| `lang` | str | `"en"` | BCP-47 language code |
| `pos` | str | `"noun"` | `"noun"`, `"verb"`, `"adjective"`, or `"adverb"` |

```python
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:

```python
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.

| BCP-47 | Language | Source |
|--------|----------|--------|
| `en` | English | Open English WordNet 2024 |
| `de` | German | ODENet 1.4 (native definitions) |
| `ar` | Arabic | OMW 1.4 |
| `bg` | Bulgarian | OMW 1.4 |
| `ca` | Catalan | OMW 1.4 |
| `cmn` | Mandarin Chinese | OMW 1.4 |
| `da` | Danish | OMW 1.4 |
| `el` | Greek | OMW 1.4 |
| `es` | Spanish | OMW 1.4 |
| `eu` | Basque | OMW 1.4 |
| `fi` | Finnish | OMW 1.4 |
| `fr` | French | OMW 1.4 |
| `gl` | Galician | OMW 1.4 |
| `he` | Hebrew | OMW 1.4 |
| `hr` | Croatian | OMW 1.4 |
| `id` | Indonesian | OMW 1.4 |
| `is` | Icelandic | OMW 1.4 |
| `it` | Italian | OMW 1.4 |
| `ja` | Japanese | OMW 1.4 |
| `lt` | Lithuanian | OMW 1.4 |
| `nb` | Norwegian Bokmål | OMW 1.4 |
| `nl` | Dutch | OMW 1.4 |
| `nn` | Norwegian Nynorsk | OMW 1.4 |
| `pl` | Polish | OMW 1.4 |
| `pt` | Portuguese | OMW 1.4 |
| `ro` | Romanian | OMW 1.4 |
| `sk` | Slovak | OMW 1.4 |
| `sl` | Slovenian | OMW 1.4 |
| `sv` | Swedish | OMW 1.4 |
| `th` | Thai | OMW 1.4 |
| `zsm` | Standard Malay | OMW 1.4 |

---

## Running tests

```bash
pip install pytest
pytest tests/
```

---

## License

Apache 2.0 — see [LICENSE](LICENSE).
