parcae 0.1.0

Infer daily rhythm and sleep schedule from message timestamps

parcae

Infer daily rhythm and sleep schedule from message timestamps

parcae is a command-line tool and Python library that analyzes nothing but timestamps and infers a user's likely timezone offset and their typical sleep window.

How It Works

parcae models human behavior as a very small Hidden Markov Model with two hidden states:

• Awake (A)
• Sleep (S)

The only observation is "was there at least one message in this time bin?". The model is trained globally across many users to learn:

• how likely people are to send messages while "awake"
• how unlikely they are to send messages while "asleep"
• how often they switch between the two states

At inference time, Parcae:

1. Tries many possible timezone offsets
2. Picks the offset that makes the timeline most explainable by a "human with one long sleep per day"
3. Decodes the most likely sleep/awake sequence
4. Extracts daily sleep blocks
5. Computes a typical schedule and regularity statistics

Installation

You can install parcae using pipx:

pipx install parcae

Usage

API

from parcae import Parcae

p = Parcae()

timestamps = [
    "2025-09-01T05:43:12+00:00",
    "2025-09-01T18:22:10+00:00",
    ...
]

print(p.analyze(timestamps))

CLI

Parcae expects a CSV file with one user's timestamps:

timestamp
2025-09-01T05:43:12+00:00
2025-09-01T07:58:33+00:00
2025-09-01T18:22:10+00:00

parcae user_timestamps.csv

Examples

+ Parcae analysis

~ inferred timezone: UTC+3

+ typical schedule:
        - sleep: 02:46 -> 11:38  (≈ 8h 45m)
        - awake: 11:38 -> 02:46

~ based on 30 days of data
~ bin size: 15 minutes