Metadata-Version: 2.4
Name: hermes-textstats
Version: 0.1.1
Summary: DIVE-ready text statistics helpers for Python, notebooks, and the terminal
Author-email: Marcello Raphael Christiano Pardede <marcelloraphael17@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/cilmar748/hermes-textstats
Project-URL: Source, https://github.com/cilmar748/hermes-textstats
Project-URL: Issues, https://github.com/cilmar748/hermes-textstats/issues
Keywords: text,statistics,reading-time,cli,cs1302,hermes
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Provides-Extra: build
Requires-Dist: build; extra == "build"
Requires-Dist: twine; extra == "build"
Dynamic: license-file

# hermes-textstats

`hermes-textstats` is a DIVE-ready Python package that turns short text, files,
and notebook drafts into clear writing statistics.

The name connects the package to the Hermes Agent workflow used in the course.
The package itself is intentionally small: it gives students a concrete package
that can be built, tested, documented, and published from DIVE/JupyterHub.

## Motivation

When I write short text for assignments, quiz explanations, README files, or
project reflections, I sometimes want quick feedback about length without
opening another tool. This package gives a simple example: a student can paste a
paragraph into Python, a notebook, or the terminal and immediately see word
count, sentence count, paragraph count, lexical diversity, longest sentence
length, character count, and estimated reading time.

Example use cases:

- checking the length of a reflection paragraph before submitting it;
- measuring a short quiz explanation inside DIVE/JupyterHub;
- using a small package project to practice the Hermes Agent + git + PyPI
  workflow.

## Installation

```bash
python -m pip install hermes-textstats
```

Published package: https://pypi.org/project/hermes-textstats/

## Quick Start

```python
from hermes_textstats import analyze_text, count_words

text = "Hermes helps me build, test, and publish Python packages."
print(count_words(text))
summary = analyze_text(text)
print(summary)
```

```bash
hermes-textstats "Hermes helps me build, test, and publish Python packages."
hermes-textstats --json "Hermes helps me build, test, and publish Python packages."
hermes-textstats --report "Hermes helps me build, test, and publish Python packages."
hermes-textstats --file reflection.txt
```

## API

- `count_words(text)`
- `count_sentences(text)`
- `count_paragraphs(text)`
- `count_characters(text, include_spaces=True)`
- `average_word_length(text)`
- `estimate_reading_time(text, words_per_minute=200)`
- `longest_sentence_length(text)`
- `lexical_diversity(text)`
- `analyze_text(text)`
- `format_markdown_report(text)`

## Development

```bash
python -m pip install -e ".[test]"
python -m pytest tests/ -v
python -m build
python -m twine check dist/*
```

## Project Notes

- [Paper package summary](docs/PAPER_PACKAGE_SUMMARY.md) contains the one-line
  summary, short motivation paragraph, and visual evidence for TALE 2026 notes.
- [Paper notes](docs/PAPER_NOTES.md) records what I built, what Hermes helped
  with, and what is already verified.
- [DIVE verification](docs/DIVE_VERIFICATION.md) lists the commands to run in
  DIVE before saying the package is verified there.
- [Notebook demo](notebooks/demo.ipynb) demonstrates the Python API in a
  notebook-style workflow.
- [Demo transcript](docs/assets/hermes-textstats-demo.txt) shows the package
  running from the command line.
- [Showcase screencap](docs/assets/hermes-textstats-showcase.png) is the
  compact visual for grant/paper updates.
- [Demo screencap](docs/assets/hermes-textstats-demo.png) is a screencap-style
  image made from the real CLI output.
- [Workflow diagram](docs/assets/hermes-textstats-workflow.svg) shows how DIVE,
  Hermes Agent, git, tests, docs, and TestPyPI/PyPI connect.

See `docs/ACCOUNT_SETUP.md` for the account/token steps used for TestPyPI,
PyPI, and Telegram setup.
