# WordAtlas
WordAtlas builds interactive semantic maps from [**WordNet**](https://wordnet.princeton.edu/).
- CLI: list relations or export a Graphviz image (PNG/SVG/PDF)
- Web: FastAPI + Cytoscape.js interactive graph, with relation toggles, label and font controls, and layout presets
## Install
- From PyPI (recommended):
```bash
pip install wordatlas
```
- From source (this repo):
```bash
pip install -e .
```
Optional dev extras:
```bash
pip install -e .[dev]
```
> Note: For PNG/SVG/PDF rendering you need the system Graphviz tool (`dot`). See Quickstart below.
## Quickstart
```bash
# 1) Install system graphviz (for PNG/SVG/PDF rendering)
# - Debian/Ubuntu: sudo apt-get update && sudo apt-get install -y graphviz
# - macOS (brew): brew install graphviz
# - Windows (choco): choco install graphviz -y
# 2) Create venv and install
python -m venv .venv
# Activate:
# - Linux/macOS: source .venv/bin/activate
# - Windows PowerShell: .venv\Scripts\Activate.ps1
pip install -e .
# 3) First run downloads WordNet corpora automatically
# CLI — quick checks
wordatlas list happiness --depth 1 --json-out g.json # write graph JSON
wordatlas show happiness --depth 1 # compact summary
# CLI — query and export image
wordatlas graph happiness --depth 2 --out graph.png
# Web — start API/UI
wordatlas web --host 0.0.0.0 --port 8000
# open http://localhost:8000/
```
## CLI commands and flags
### Commands:
- `wordatlas list WORD` — build the graph and print a relation summary table (or `--json-out`)
- `wordatlas show WORD` — print a compact JSON-like summary (center, counts, samples)
- `wordatlas graph WORD` — render a Graphviz image and optional CSV/JSON exports
### Common flags:
- `--depth INT` — overall expansion depth (default from env; see Configuration)
- `--max-nodes INT` — cap total nodes in the graph
- `--relation ...` or `-r ...` (repeatable) — keep only selected edge types
- `--rel-depth relation:INT` (repeatable) — per-relation hop caps
- Only relations you specify are constrained; others follow the overall `--depth`.
- `--pos-cap POS:INT` (repeatable) — cap nodes per POS (e.g., `n:80 a:30`)
- `--exclude WORD` (repeatable) — exclude words; `--stopwords file.txt` for a newline list
- `--min-degree INT` — drop nodes with degree less than N (center is kept)
- Rendering and exports:
- `--out PATH` — output file (suffix .png/.svg/.pdf)
- `--format {png,svg,pdf}` — override format regardless of `--out` suffix
- `--csv-out edges.csv` — write `source,target,relation`
- `--json-out graph.json` — dump graph JSON
- `--open` — open the rendered image
### Examples:
```bash
# Synonyms only, prune low-degree nodes, export CSV
wordatlas graph happy -r synonym --min-degree 1 --csv-out edges.csv --out g.svg
# Cap adjective nodes and limit hypernym depth
wordatlas graph bright --pos-cap a:5 --pos-cap n:50 --rel-depth hypernym:1 --out g.png
# Remove custom stopwords
wordatlas graph happy --stopwords stop.txt --exclude joyful
# Override format regardless of --out suffix
wordatlas graph run --out output.png --format pdf # writes output.pdf
```
## Web UI
- Sliders: label width and font size
- Layout presets: CoSE, Breadthfirst, Concentric, Grid
Tips:
- Click a node to recenter and rebuild the graph
- Use relation toggles to declutter specific edge types
## REST API
The web UI uses these endpoints; you can call them directly.
- GET `/api/health`
- Returns status, version, uptime, NLTK corpora status, and cache metrics.
- Example:
```bash
curl http://localhost:8000/api/health
```
- GET `/api/graph`
- Params: `word` (required), `depth` (int), `max_nodes` (int), `relation` (repeatable)
- Server-side relation filtering applies if one or more `relation` params are supplied.
- Example:
```bash
curl "http://localhost:8000/api/graph?word=happiness&depth=1&relation=synonym&relation=hypernym"
```
- POST `/api/cache/clear`
- Clears internal LRU caches to free memory.
- Example:
```bash
curl -X POST http://localhost:8000/api/cache/clear
```
## Relations supported
- synonyms, hypernyms, hyponyms, antonyms, similar_to
## Configuration
Environment variables:
- `WORDATLAS_DEFAULT_DEPTH` (int, default 1)
- `WORDATLAS_MAX_NODES` (int, default 300)
- `LOG_LEVEL` (str, default "INFO")
## Caching and performance
- NLTK corpora (`wordnet`, `omw-1.4`) are downloaded automatically on first use.
- WordNet synset lookups are cached with an internal LRU cache.
- Inspect via `GET /api/health` (cache metrics) and clear via `POST /api/cache/clear`.
- Use `--relation` filters, `--rel-depth`, `--pos-cap`, and `--min-degree` to keep graphs manageable.
## Tests
```bash
pip install -e .[dev]
pytest -q
```
## Development
```bash
# install dev deps
pip install -e .[dev]
# run the web app (live reload)
wordatlas web --reload
# or use Make targets
make install-dev
make test
make lint
make format
make typecheck
```
## License
See [LICENSE](LICENSE) for full license text.
## Acknowledgements
- [WordNet by Princeton University](https://wordnet.princeton.edu/)
- NLTK WordNet interface
- FastAPI, Uvicorn
- Cytoscape.js
- Graphviz
Raw data
{
"_id": null,
"home_page": null,
"name": "wordatlas",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "wordnet, nlp, graph, fastapi, cli, cytoscape",
"author": "Soumyadip Sarkar",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a6/0f/ffe38139c8054925fceb358499078c3496c6d7875944260b06e32081f659/wordatlas-0.1.1.tar.gz",
"platform": null,
"description": "# WordAtlas\n\nWordAtlas builds interactive semantic maps from [**WordNet**](https://wordnet.princeton.edu/).\n\n- CLI: list relations or export a Graphviz image (PNG/SVG/PDF)\n- Web: FastAPI + Cytoscape.js interactive graph, with relation toggles, label and font controls, and layout presets\n\n## Install\n\n- From PyPI (recommended):\n\n```bash\npip install wordatlas\n```\n\n- From source (this repo):\n\n```bash\npip install -e .\n```\n\nOptional dev extras:\n\n```bash\npip install -e .[dev]\n```\n\n> Note: For PNG/SVG/PDF rendering you need the system Graphviz tool (`dot`). See Quickstart below.\n\n## Quickstart\n\n```bash\n# 1) Install system graphviz (for PNG/SVG/PDF rendering)\n# - Debian/Ubuntu: sudo apt-get update && sudo apt-get install -y graphviz\n# - macOS (brew): brew install graphviz\n# - Windows (choco): choco install graphviz -y\n\n# 2) Create venv and install\npython -m venv .venv\n# Activate:\n# - Linux/macOS: source .venv/bin/activate\n# - Windows PowerShell: .venv\\Scripts\\Activate.ps1\npip install -e .\n\n# 3) First run downloads WordNet corpora automatically\n\n# CLI \u2014 quick checks\nwordatlas list happiness --depth 1 --json-out g.json # write graph JSON\nwordatlas show happiness --depth 1 # compact summary\n\n# CLI \u2014 query and export image\nwordatlas graph happiness --depth 2 --out graph.png\n\n# Web \u2014 start API/UI\nwordatlas web --host 0.0.0.0 --port 8000\n# open http://localhost:8000/\n```\n\n## CLI commands and flags\n\n### Commands:\n\n- `wordatlas list WORD` \u2014 build the graph and print a relation summary table (or `--json-out`)\n- `wordatlas show WORD` \u2014 print a compact JSON-like summary (center, counts, samples)\n- `wordatlas graph WORD` \u2014 render a Graphviz image and optional CSV/JSON exports\n\n### Common flags:\n\n- `--depth INT` \u2014 overall expansion depth (default from env; see Configuration)\n- `--max-nodes INT` \u2014 cap total nodes in the graph\n- `--relation ...` or `-r ...` (repeatable) \u2014 keep only selected edge types\n- `--rel-depth relation:INT` (repeatable) \u2014 per-relation hop caps\n - Only relations you specify are constrained; others follow the overall `--depth`.\n- `--pos-cap POS:INT` (repeatable) \u2014 cap nodes per POS (e.g., `n:80 a:30`)\n- `--exclude WORD` (repeatable) \u2014 exclude words; `--stopwords file.txt` for a newline list\n- `--min-degree INT` \u2014 drop nodes with degree less than N (center is kept)\n- Rendering and exports:\n - `--out PATH` \u2014 output file (suffix .png/.svg/.pdf)\n - `--format {png,svg,pdf}` \u2014 override format regardless of `--out` suffix\n - `--csv-out edges.csv` \u2014 write `source,target,relation`\n - `--json-out graph.json` \u2014 dump graph JSON\n - `--open` \u2014 open the rendered image\n\n### Examples:\n\n```bash\n# Synonyms only, prune low-degree nodes, export CSV\nwordatlas graph happy -r synonym --min-degree 1 --csv-out edges.csv --out g.svg\n\n# Cap adjective nodes and limit hypernym depth\nwordatlas graph bright --pos-cap a:5 --pos-cap n:50 --rel-depth hypernym:1 --out g.png\n\n# Remove custom stopwords\nwordatlas graph happy --stopwords stop.txt --exclude joyful\n\n# Override format regardless of --out suffix\nwordatlas graph run --out output.png --format pdf # writes output.pdf\n```\n\n## Web UI\n\n- Sliders: label width and font size\n- Layout presets: CoSE, Breadthfirst, Concentric, Grid\n\nTips:\n\n- Click a node to recenter and rebuild the graph\n- Use relation toggles to declutter specific edge types\n\n## REST API\n\nThe web UI uses these endpoints; you can call them directly.\n\n- GET `/api/health`\n\n - Returns status, version, uptime, NLTK corpora status, and cache metrics.\n - Example:\n\n ```bash\n curl http://localhost:8000/api/health\n ```\n\n- GET `/api/graph`\n\n - Params: `word` (required), `depth` (int), `max_nodes` (int), `relation` (repeatable)\n - Server-side relation filtering applies if one or more `relation` params are supplied.\n - Example:\n\n ```bash\n curl \"http://localhost:8000/api/graph?word=happiness&depth=1&relation=synonym&relation=hypernym\"\n ```\n\n- POST `/api/cache/clear`\n\n - Clears internal LRU caches to free memory.\n - Example:\n\n ```bash\n curl -X POST http://localhost:8000/api/cache/clear\n ```\n\n## Relations supported\n\n- synonyms, hypernyms, hyponyms, antonyms, similar_to\n\n## Configuration\n\nEnvironment variables:\n\n- `WORDATLAS_DEFAULT_DEPTH` (int, default 1)\n- `WORDATLAS_MAX_NODES` (int, default 300)\n- `LOG_LEVEL` (str, default \"INFO\")\n\n## Caching and performance\n\n- NLTK corpora (`wordnet`, `omw-1.4`) are downloaded automatically on first use.\n- WordNet synset lookups are cached with an internal LRU cache.\n - Inspect via `GET /api/health` (cache metrics) and clear via `POST /api/cache/clear`.\n- Use `--relation` filters, `--rel-depth`, `--pos-cap`, and `--min-degree` to keep graphs manageable.\n\n## Tests\n\n```bash\npip install -e .[dev]\npytest -q\n```\n\n## Development\n\n```bash\n# install dev deps\npip install -e .[dev]\n\n# run the web app (live reload)\nwordatlas web --reload\n\n# or use Make targets\nmake install-dev\nmake test\nmake lint\nmake format\nmake typecheck\n```\n\n## License\n\nSee [LICENSE](LICENSE) for full license text.\n\n## Acknowledgements\n\n- [WordNet by Princeton University](https://wordnet.princeton.edu/)\n- NLTK WordNet interface\n- FastAPI, Uvicorn\n- Cytoscape.js\n- Graphviz\n",
"bugtrack_url": null,
"license": "# License\n \n Copyright 2025 Soumyadip Sarkar\n \n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n \n http://www.apache.org/licenses/LICENSE-2.0\n \n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License.\n ",
"summary": "Interactive semantic maps (WordNet) via CLI and web",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/neuralsorcerer/WordAtlas",
"Issues": "https://github.com/neuralsorcerer/WordAtlas/issues"
},
"split_keywords": [
"wordnet",
" nlp",
" graph",
" fastapi",
" cli",
" cytoscape"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "65fd6a64fdcf2eca294f50256a61cb744272b6d3f1f0a0ad8658f68790111cec",
"md5": "6796d782e297ae0981e47a8c44ea5a0c",
"sha256": "62042526370edaef3146cdd360aa83c787d279b65ed6956d63404dce94c4cbe6"
},
"downloads": -1,
"filename": "wordatlas-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6796d782e297ae0981e47a8c44ea5a0c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 21158,
"upload_time": "2025-08-20T16:13:14",
"upload_time_iso_8601": "2025-08-20T16:13:14.559838Z",
"url": "https://files.pythonhosted.org/packages/65/fd/6a64fdcf2eca294f50256a61cb744272b6d3f1f0a0ad8658f68790111cec/wordatlas-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a60fffe38139c8054925fceb358499078c3496c6d7875944260b06e32081f659",
"md5": "820120ca047d2502d6b02ee6835ca4a5",
"sha256": "f136aae16188286f7d6d20371f405fe27b5ffccf53f2cb94dc076c78ba0607c7"
},
"downloads": -1,
"filename": "wordatlas-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "820120ca047d2502d6b02ee6835ca4a5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 21330,
"upload_time": "2025-08-20T16:13:15",
"upload_time_iso_8601": "2025-08-20T16:13:15.699004Z",
"url": "https://files.pythonhosted.org/packages/a6/0f/ffe38139c8054925fceb358499078c3496c6d7875944260b06e32081f659/wordatlas-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-20 16:13:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "neuralsorcerer",
"github_project": "WordAtlas",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "wordatlas"
}
JSON
