Metadata-Version: 2.5
Name: thematos
Version: 1.0.2
Summary: LDA topic modeling on tomotopy, with HyFI 2.0 config groups and workflows
Project-URL: Homepage, https://thematos.entelecheia.ai
Project-URL: Repository, https://github.com/entelecheia/thematos
Project-URL: Documentation, https://thematos.entelecheia.ai
Project-URL: Changelog, https://github.com/entelecheia/thematos/blob/main/CHANGELOG.md
Author-email: Young Joon Lee <entelecheia@hotmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: hyfi,lda,nlp,tomotopy,topic-modeling
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: hyfi<3,>=2
Requires-Dist: lexikanon<2,>=1
Requires-Dist: matplotlib>=3.7
Requires-Dist: numpy>=1.23.5
Requires-Dist: pandas>=2
Requires-Dist: pillow>=9
Requires-Dist: pyarrow>=14
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: tomotopy>=0.14
Requires-Dist: wordcloud>=1.9.4
Description-Content-Type: text/markdown

# ThematOS

[![pypi-image]][pypi-url]
[![license-image]][license-url]

LDA topic modeling on [tomotopy](https://bab2min.github.io/tomotopy/). ThematOS is a plain Python library; it also ships [HyFI 2.0](https://hyfi.entelecheia.ai) config groups and workflows, so a training run, a parameter sweep, or an inference run can be started from the command line and recorded in a run manifest. The name comes from the Greek θέματος, "of the theme".

- [Documentation][docs-url]
- [Migrating from 0.x](https://thematos.entelecheia.ai/migration/)

ThematOS 1.0 drops the HyFI 1.x API. Pin `thematos<1` to keep it.

## Install

```bash
uv add thematos          # or: pip install thematos
pip install pyLDAvis     # optional: LDAvis HTML next to the other artifacts
```

Python 3.11 or newer. Stopwords come from [lexikanon](https://github.com/entelecheia/lexikanon), which pulls in MeCab through fugashi; on Python 3.15 fugashi builds from source and needs the MeCab library (`apt-get install libmecab-dev` or `brew install mecab`).

## Use it as a library

```python
from thematos.datasets import Corpus
from thematos.models import LdaModel

corpus = Corpus(data_file="news.parquet", text_col="tokens")  # or Corpus(data=dataframe)
model = LdaModel(output_dir="workspace/topic/model", seed=42, model_args={"k": 10})
model.train(corpus)  # trains and computes coherence; writes nothing
model.save()  # model file, log-likelihood trace, distributions, top words
model.summarize()  # tomotopy summary and one JSON line in model-summary.jsonl
model.plot()  # log-likelihood plot and topic word clouds
model.model.perplexity
```

Every file name starts with the model id, `LDA_model_k(10)` here. Importing thematos never imports HyFI.

## Use it from HyFI

Installing thematos registers its config groups through the `hyfi.plugins` entry point:

| group | options |
|---|---|
| `model` | `lda` |
| `dataset` | `topic_corpus` (stopwords from lexikanon's `stopwords` group) |
| `words` | `wordprior` |
| `plot` | `wordcloud` |
| `workflow` | `thematos_lda`, `thematos_lda_sweep`, `thematos_lda_infer` |

```bash
hyfi run workflow=thematos_lda dataset.data_file=news.parquet dataset.text_col=tokens \
  model.model_args.k=20 model.seed=42
```

Artifacts go under the project workspace (`workspace/topic/model/` by default) and the run manifest under `.hyfi/runs/<run id>/manifest.json`. See [Usage](https://thematos.entelecheia.ai/usage/) for the sweep and inference workflows.

## Citation

See [CITATION.cff](https://github.com/entelecheia/thematos/blob/main/CITATION.cff), or use GitHub's "Cite this repository" button.

## License

[MIT][license-url]

[pypi-image]: https://img.shields.io/pypi/v/thematos
[pypi-url]: https://pypi.org/project/thematos
[license-image]: https://img.shields.io/github/license/entelecheia/thematos
[license-url]: https://github.com/entelecheia/thematos/blob/main/LICENSE
[docs-url]: https://thematos.entelecheia.ai
