parcae 0.1.0__py3-none-any.whl

parcae/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "0.1.0"
+
+from .api import Parcae
+
+__all__ = ["Parcae"]

parcae/api.py

@@ -0,0 +1,173 @@
+import sysconfig
+from datetime import datetime, timedelta
+from pathlib import Path
+
+import numpy as np
+
+
+def _logsumexp(a):
+    m = np.max(a)
+    return m + np.log(np.sum(np.exp(a - m)))
+
+
+def _forward_log(obs, log_trans, log_emit, log_init):
+    T = len(obs)
+    alpha = np.zeros((T, 2))
+
+    alpha[0] = log_init + log_emit[:, obs[0]]
+
+    for t in range(1, T):
+        for j in range(2):
+            alpha[t, j] = log_emit[j, obs[t]] + _logsumexp(
+                alpha[t - 1] + log_trans[:, j]
+            )
+
+    return _logsumexp(alpha[T - 1])
+
+
+def _viterbi(obs, log_trans, log_emit, log_init):
+    T = len(obs)
+    dp = np.zeros((T, 2))
+    back = np.zeros((T, 2), dtype=np.uint8)
+
+    dp[0] = log_init + log_emit[:, obs[0]]
+
+    for t in range(1, T):
+        for j in range(2):
+            scores = dp[t - 1] + log_trans[:, j]
+            k = np.argmax(scores)
+            dp[t, j] = scores[k] + log_emit[j, obs[t]]
+            back[t, j] = k
+
+    last = np.argmax(dp[T - 1])
+    best = dp[T - 1, last]
+
+    path = np.zeros(T, dtype=np.int8)
+    path[T - 1] = last
+
+    for t in range(T - 2, -1, -1):
+        path[t] = back[t + 1, path[t + 1]]
+
+    return path, best
+
+
+class Parcae:
+    def __init__(self, model_path=None, bin_minutes=15):
+        if model_path is None:
+            data_path = Path(sysconfig.get_paths()["data"]) / "models"
+            model_path = data_path / "hmm.npz"
+
+        data = np.load(model_path)
+
+        self.startprob = data["startprob"]
+        self.transmat = data["transmat"]
+        self.emissionprob = data["emissionprob"]
+
+        self.log_startprob = np.log(self.startprob)
+        self.log_transmat = np.log(self.transmat)
+        self.log_emissionprob = np.log(self.emissionprob)
+
+        self.bin_minutes = int(data.get("bin_minutes", bin_minutes))
+
+        self.sleep_state = int(np.argmin(self.emissionprob[:, 1]))
+        self.awake_state = 1 - self.sleep_state
+
+    def _parse_timestamps(self, timestamps):
+        out = []
+        for t in timestamps:
+            if isinstance(t, datetime):
+                out.append(t)
+            else:
+                out.append(datetime.fromisoformat(str(t)))
+        return sorted(out)
+
+    def _bin(self, timestamps):
+        start = timestamps[0].replace(hour=0, minute=0, second=0, microsecond=0)
+        end = timestamps[-1].replace(
+            hour=0, minute=0, second=0, microsecond=0
+        ) + timedelta(days=1)
+
+        bin_delta = timedelta(minutes=self.bin_minutes)
+        n_bins = int((end - start) / bin_delta)
+
+        bins = np.zeros(n_bins, dtype=np.uint8)
+
+        for t in timestamps:
+            idx = int((t - start) / bin_delta)
+            if 0 <= idx < n_bins:
+                bins[idx] = 1
+
+        return start, bins
+
+    def analyze(self, timestamps, tz_range=range(-12, 13)):
+        ts = self._parse_timestamps(timestamps)
+
+        span = ts[-1] - ts[0]
+        if span < timedelta(days=2):  # arbitrary number that seems fine
+            raise ValueError("not enough time span to analyze (need at least ~2 days)")
+
+        start_time, bins = self._bin(ts)
+
+        bins_per_day = (24 * 60) // self.bin_minutes
+
+        if len(bins) < 2 * bins_per_day:  # arbitrary number that seems fine
+            raise ValueError("not enough data after binning (need at least ~2 days)")
+
+        best_phi = 0
+        best_score = -np.inf
+
+        for phi in tz_range:
+            shift_bins = int(phi * bins_per_day / 24)
+            bins_phi = np.roll(bins, shift_bins)
+
+            score = _forward_log(
+                bins_phi,
+                self.log_transmat,
+                self.log_emissionprob,
+                self.log_startprob,
+            )
+
+            if score > best_score:
+                best_score = score
+                best_phi = phi
+
+        shift_bins = int(best_phi * bins_per_day / 24)
+        best_bins = np.roll(bins, shift_bins)
+
+        states, _ = _viterbi(
+            best_bins, self.log_transmat, self.log_emissionprob, self.log_startprob
+        )
+
+        sleep_blocks = []
+        awake_blocks = []
+
+        current_state = states[0]
+        block_start = 0
+
+        for i in range(1, len(states)):
+            if states[i] != current_state:
+                (
+                    sleep_blocks if current_state == self.sleep_state else awake_blocks
+                ).append((block_start, i))
+
+                block_start = i
+                current_state = states[i]
+
+        if current_state == self.sleep_state:
+            sleep_blocks.append((block_start, len(states)))
+        else:
+            awake_blocks.append((block_start, len(states)))
+
+        def blocks_to_time(blocks):
+            out = []
+            for a, b in blocks:
+                t0 = start_time + timedelta(minutes=self.bin_minutes * a)
+                t1 = start_time + timedelta(minutes=self.bin_minutes * b)
+                out.append({"start": t0.isoformat(), "end": t1.isoformat()})
+            return out
+
+        return {
+            "timezone_offset_hours": int(best_phi),
+            "sleep_blocks": blocks_to_time(sleep_blocks),
+            "awake_blocks": blocks_to_time(awake_blocks),
+        }

parcae/cli.py

@@ -0,0 +1,114 @@
+import argparse
+import csv
+import math
+from collections import defaultdict
+from datetime import datetime, timedelta
+
+from parcae import Parcae
+
+
+def parse_csv(path):
+    timestamps = []
+    with open(path, "r", encoding="utf-8") as f:
+        reader = csv.DictReader(f)
+        fieldnames = reader.fieldnames
+        if fieldnames is None or "timestamp" not in fieldnames:
+            raise ValueError("! CSV must have a 'timestamp' column")
+
+        for row in reader:
+            timestamps.append(row["timestamp"])
+
+    return timestamps
+
+
+def minutes_since_midnight(dt):
+    return dt.hour * 60 + dt.minute
+
+
+def format_hm(minutes):
+    h = (minutes // 60) % 24
+    m = minutes % 60
+    return f"{h:02d}:{m:02d}"
+
+
+def circular_mean_minutes(values):
+    angles = [2 * math.pi * v / 1440.0 for v in values]
+
+    x = sum(math.cos(a) for a in angles)
+    y = sum(math.sin(a) for a in angles)
+
+    if x == 0 and y == 0:
+        return int(values[0])
+
+    mean_angle = math.atan2(y, x)
+    if mean_angle < 0:
+        mean_angle += 2 * math.pi
+
+    mean_minutes = int(round(mean_angle * 1440.0 / (2 * math.pi)))
+    return mean_minutes % 1440
+
+
+def main():
+    parser = argparse.ArgumentParser(prog="parcae")
+    parser.add_argument("csv", help="CSV file with a 'timestamp' column")
+    parser.add_argument("-v", "--version", action="version", version="%(prog)s 0.1.0")
+    args = parser.parse_args()
+
+    print("+ Parcae analysis\n")
+
+    timestamps = parse_csv(args.csv)
+
+    p = Parcae()
+    result = p.analyze(timestamps)
+
+    tz = result["timezone_offset_hours"]
+    sleep_blocks = result["sleep_blocks"]
+
+    print(f"~ inferred timezone: UTC{tz:+d}\n")
+
+    offset = timedelta(hours=tz)
+
+    local_blocks = []
+    for b in sleep_blocks:
+        start = datetime.fromisoformat(b["start"]) + offset
+        end = datetime.fromisoformat(b["end"]) + offset
+        local_blocks.append((start, end))
+
+    by_day = defaultdict(list)
+
+    for start, end in local_blocks:
+        day = start.date()
+        dur = (end - start).total_seconds()
+        by_day[day].append((dur, start, end))
+
+    main_sleeps = []
+    for day, blocks in by_day.items():
+        blocks.sort(reverse=True)
+        _, start, end = blocks[0]
+        main_sleeps.append((start, end))
+
+    if not main_sleeps:
+        print("! no sleep blocks detected")
+        return
+
+    sleep_starts = [minutes_since_midnight(s) for s, e in main_sleeps]
+    sleep_ends = [minutes_since_midnight(e) for s, e in main_sleeps]
+    durations = [int((e - s).total_seconds() / 60) for s, e in main_sleeps]
+
+    mean_start = circular_mean_minutes(sleep_starts)
+    mean_end = circular_mean_minutes(sleep_ends)
+    durations.sort()
+    med_dur = durations[len(durations) // 2]
+
+    print("+ typical schedule:")
+    print(
+        f"\t- sleep: {format_hm(mean_start)} -> {format_hm(mean_end)}  (≈ {med_dur // 60}h {med_dur % 60:02d}m)"
+    )
+    print(f"\t- awake: {format_hm(mean_end)} -> {format_hm(mean_start)}\n")
+
+    print(f"~ based on {len(main_sleeps)} days of data")
+    print(f"~ bin size: {p.bin_minutes} minutes")
+
+
+if __name__ == "__main__":
+    main()

parcae-0.1.0.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: parcae
+Version: 0.1.0
+Summary: Infer daily rhythm and sleep schedule from message timestamps
+Project-URL: Homepage, https://github.com/jeremyctrl/parcae
+Project-URL: Repository, https://github.com/jeremyctrl/parcae
+Project-URL: Issues, https://github.com/jeremyctrl/parcae/issues
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.4.1
+Provides-Extra: train
+Requires-Dist: hmmlearn>=0.3.3; extra == "train"
+Requires-Dist: matplotlib>=3.10.8; extra == "train"
+Requires-Dist: pandas>=3.0.0; extra == "train"
+Dynamic: license-file
+
+<div align="center">
+
+# parcae
+
+<div>
+   <a href="https://pypi.org/project/parcae/"><img src="https://img.shields.io/pypi/v/parcae.svg" alt="PyPI"></a>
+   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
+</div>
+
+<a href="https://heyjeremy.vercel.app/blog/when-do-you-sleep"><img src="https://img.shields.io/badge/blog-when%20do%20you%20sleep%3F%20learning%20a%20pattern%20of%20life%20from%20message%20timestamps-blue" alt="Blog"></a>
+
+Infer daily rhythm and sleep schedule from message timestamps
+
+</div>
+
+`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](https://pypa.github.io/pipx):
+
+```bash
+pipx install parcae
+```
+
+## Usage
+
+### API
+
+```python
+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:
+
+```csv
+timestamp
+2025-09-01T05:43:12+00:00
+2025-09-01T07:58:33+00:00
+2025-09-01T18:22:10+00:00
+```
+
+```bash
+parcae user_timestamps.csv
+```
+
+#### Examples
+
+```bash
++ 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
+```

parcae-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+parcae/__init__.py,sha256=xcLcFjuCpmp-5ImKBc6MPFEbbq_2bfG4-kE9YNOhgNM,69
+parcae/api.py,sha256=O-JZw_HvZzC2yXSZGDgLMntwqnxaJs8edxEuTpAWCIw,5132
+parcae/cli.py,sha256=9wkIU42fx2GVDYETyxv0hXkDs-Xn5j8OqKm5mbdThTg,3115
+parcae-0.1.0.data/data/models/hmm.npz,sha256=MMnWWesB0-VzqLDJEGllFIZeHb5GVtUF5DDsXLOl61U,1118
+parcae-0.1.0.dist-info/licenses/LICENSE,sha256=lkt0mQbom19fj92XgwyoYS3T2ES7S6F4aqV2-53AksA,1075
+parcae-0.1.0.dist-info/METADATA,sha256=S2s1arkvKmJfqobtCjUbYjNT4x9PFgU_Gd9MQOoaek0,2839
+parcae-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+parcae-0.1.0.dist-info/entry_points.txt,sha256=okhIV74Y1DqE8UGhVycpEU2NTwq3ReBkaoxfm7BBsrI,43
+parcae-0.1.0.dist-info/top_level.txt,sha256=S_O9fdoifLS3yrrHeidB6sQ61r8l6KBvSHZ0arhaGoE,7
+parcae-0.1.0.dist-info/RECORD,,

parcae-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

parcae-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+parcae = parcae.cli:main

parcae-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 jeremyctrl (Jeremy)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

parcae-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+parcae