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 analyze user_timestamps.csv

Compare two fingerprints to estimate whether they belong to the same person:

parcae compare parcae:v1:<fp1> parcae:v1:<fp2>

Examples

+ Parcae analysis

~ inferred timezone: UTC+3

+ typical schedule:
        - sleep: 23:52 -> 06:34  (≈ 8h 30m)
        - awake: 06:34 -> 23:52
        - variability: ±175m

+ activity profile (24h):
        ▁▁▁▁▁▁▁▁▅▇▅█▆▁▅▄▅▆▁▇▇▆▆▇
        |     |     |     |     
        00    06    12    18    

+ fingerprint:
        parcae:v1:AAAAAAAAAAAAAAAAAAAAAD0AWQA6AGMAQQAAADoAMAA6AEcAAABWAFUATgBMAFsAd__-D9QPqP12BPEBqwU=

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