krev 0.1.0

Keystroke Revision Extraction and Visualisation library

K-REV

Keystroke Revision Tracking and Extraction

---

Overview

K-Rev is a Python library for detecting and analyzing revision episodes in streams of keystroke data.
It helps researchers and developers understand how writers revise their text — identifying bursts of deletion, retyping, or restructuring that reveal cognitive and editing processes during writing.

Whether you are studying writing behavior, building educational tools, or visualizing editing timelines, K-Rev makes keystroke-based revision analysis simple, reproducible, and extensible.

---

Features

• Automatic detection of revision episodes from raw keystroke logs
• Flexible data model for representing typing, pauses, and edits
• Analytics and visualization utilities (coming soon)
• Extensible architecture — plug in your own revision classifiers
• Compatible with common keystroke formats (e.g., InputLog, ScriptLog, or custom JSON)

---

Installation

pip install kretrace

---

Quickstart

Once you extracted you keystroke data, create a list that represents the text after each keystroke and a list that keeps the cursor position after each keystroke. Example:

    text_list = [
        "The quick brown fox",
        "The quick brown fox ",
        "The quick brown fox j",
        "The quick brown fox ju",
        "The quick brown fox jum",
        "The quick brown fox jumps",
        "The quick brown fox jumps ",
        "The quick brown fox jumps o",
        "The quick brown fox jumps ov",
        "The quick brown fox jumps ove",
        "The quick brown fox jumps over",
        "The quick brown fo jumps over",
        "The quick brown f jumps over",
        "The quick brown  jumps over",
        "The quick brown c jumps over",
        "The quick brown ca jumps over",
        "The quick brown cat jumps over",
        "The quick brown cat jumps over ",
        "The quick brown cat jumps over t",
        "The quick brown cat jumps over th",
        "The quick brown cat jumps over the",
        "The quick brown cat jumps over the ",
        "The quick brown cat jumps over the d",
        "The quick brown cat jumps over the do",
        "The quick brown cat jumps over the dog",
    ]
    cursor_list = [19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 18, 17, 16, 17, 18, 19, 31, 32, 33, 34, 35, 36, 37, 38]

Then we can extract the revision events from the keystroke data.

>>> from krev.main import characterize_revisions
>>> revisions = characterize_revisions(text_list, cursor_list)

If you are working with french text, you can also already use our pipeline to classify the revision event through requesting an LLM. In order to do so, you must precise the model you want to use and an API key. You should be aware of the tokens that might be used by doing such a request. Prompts are available in the open-source code of the library.

>>> from krev.main import characterize_revisions
>>> revisions = characterize_revisions(text_list, cursor_list, "gpt-5", api_key=API-KEY)

Finally you can go through the list of revisions to observe the text before/after the revision, the revision type, where it appends in the text...

>>> for revision in revisions:
... print(revision.text_before, revision.text_end, revision.reason_start, revision.start_point, revision.type)

---

How it works

---

Next steps

Taking into account trailing text. For now, the presence of trailing text might cause problems to the revision extraction procedure. Multi-lingual pipeline for revision classification (only in French for now, but revision extraction works for any Indo-European language). Replace the API use of LLMs to classify the revision by smaller models.

---

License

K-Rev operates under an ASL License, and is a property of EvidenceB. It is open source for research purpose, but not open for commercial use. If you would like to use this library for a commercial purpose, please contact the owners of this repository. See the License file for further details.

---

Citation

---

Acknowledgements