human-movement-research 0.1.1__tar.gz

human_movement_research-0.1.1/CITATION.cff

@@ -0,0 +1,11 @@
+cff-version: 1.2.0
+message: "If you use Human Movement, please cite this software."
+type: software
+title: Human Movement Research
+version: 0.1.1
+date-released: 2026-11-06
+authors:
+  - family-names: Galal
+    given-names: Karim
+license: MIT
+abstract: "Windows-first personalized cursor trajectories and input timing for computer-use applications."

human_movement_research-0.1.1/CONTRIBUTORS.md

@@ -0,0 +1,5 @@
+# Contributor
+
+Karim Galal is the sole contributor and maintainer of Human Movement.
+
+External libraries, datasets, research papers and engineering baselines retain their original ownership and attribution. They are references or dependencies, rather than contributors to this package.

human_movement_research-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Karim Galal
+
+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.

human_movement_research-0.1.1/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: human-movement-research
+Version: 0.1.1
+Summary: Optional conditional diffusion research for timed cursor trajectories
+Author: Karim Galal
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Dist: numpy>=2.1
+Requires-Dist: torch>=2.6
+Requires-Dist: onnx>=1.17 ; extra == 'onnx'
+Requires-Dist: onnxruntime>=1.20 ; extra == 'onnx'
+Maintainer: Karim Galal
+Requires-Python: >=3.12
+Provides-Extra: onnx
+Description-Content-Type: text/markdown
+
+# Human Movement Research
+
+Optional conditional trajectory diffusion training, CPU export and inference tools. Developed and maintained solely by Karim Galal.
+
+```sh
+pip install human-movement-research
+human-movement-research --help
+```
+
+Requires NumPy and PyTorch. No trained, independently validated checkpoint is bundled. Training examples and tests validate the pipeline; they do not establish human behavioral fidelity. The core SDK works without this package and falls back to analytical generation when a neural model is unavailable or invalid.
+
+Licensed under MIT. See the included LICENSE file.

human_movement_research-0.1.1/README.md

@@ -0,0 +1,12 @@
+# Human Movement Research
+
+Optional conditional trajectory diffusion training, CPU export and inference tools. Developed and maintained solely by Karim Galal.
+
+```sh
+pip install human-movement-research
+human-movement-research --help
+```
+
+Requires NumPy and PyTorch. No trained, independently validated checkpoint is bundled. Training examples and tests validate the pipeline; they do not establish human behavioral fidelity. The core SDK works without this package and falls back to analytical generation when a neural model is unavailable or invalid.
+
+Licensed under MIT. See the included LICENSE file.

human_movement_research-0.1.1/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "human-movement-research"
+version = "0.1.1"
+readme = "README.md"
+description = "Optional conditional diffusion research for timed cursor trajectories"
+requires-python = ">=3.12"
+dependencies = [
+    "numpy>=2.1",
+    "torch>=2.6",
+]
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+
+[[project.authors]]
+name = "Karim Galal"
+
+[[project.maintainers]]
+name = "Karim Galal"
+
+[project.scripts]
+human-movement-research = "human_movement_research.cli:main"
+
+[project.optional-dependencies]
+onnx = [
+    "onnx>=1.17",
+    "onnxruntime>=1.20",
+]
+
+[build-system]
+requires = ["uv_build>=0.13.7,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+source-include = [
+    "CITATION.cff",
+    "CONTRIBUTORS.md",
+]

human_movement_research-0.1.1/pyproject.toml.orig

@@ -0,0 +1,30 @@
+[project]
+name = "human-movement-research"
+version = "0.1.1"
+readme = "README.md"
+description = "Optional conditional diffusion research for timed cursor trajectories"
+requires-python = ">=3.12"
+dependencies = ["numpy>=2.1", "torch>=2.6"]
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Karim Galal"}]
+maintainers = [{name = "Karim Galal"}]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+
+[project.scripts]
+human-movement-research = "human_movement_research.cli:main"
+
+[project.optional-dependencies]
+onnx = ["onnx>=1.17", "onnxruntime>=1.20"]
+
+[build-system]
+requires = ["uv_build>=0.13.7,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+source-include = ["CITATION.cff", "CONTRIBUTORS.md"]

human_movement_research-0.1.1/src/human_movement_research/__init__.py

@@ -0,0 +1,3 @@
+"""Optional research tools. Import does not load torch or start training."""
+
+__version__ = "0.1.1"

human_movement_research-0.1.1/src/human_movement_research/cli.py

@@ -0,0 +1,25 @@
+import argparse
+import json
+from pathlib import Path
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="human-movement-research")
+    commands = parser.add_subparsers(dest="command", required=True)
+    train = commands.add_parser("train")
+    train.add_argument("input", type=Path)
+    train.add_argument("output", type=Path)
+    train.add_argument("--epochs", type=int, default=100)
+    train.add_argument("--seed", type=int, default=17842)
+    export = commands.add_parser("export")
+    export.add_argument("checkpoint", type=Path)
+    export.add_argument("output", type=Path)
+    args = parser.parse_args(argv)
+    from . import training
+
+    if args.command == "train":
+        rows = [json.loads(line) for line in args.input.read_text().splitlines() if line.strip()]
+        result = training.train(rows, args.output, epochs=args.epochs, seed=args.seed)
+    else:
+        result = training.export(args.checkpoint, args.output)
+    print(json.dumps(result, indent=2))

human_movement_research-0.1.1/src/human_movement_research/data.py

@@ -0,0 +1,48 @@
+"""Retain event time while resampling positions by event index."""
+
+import math
+
+import numpy as np
+
+from .model import LENGTH
+
+DEFAULT_PROFILE = [0.10, 0.13, 0.15, 0.045, 0.025, 0.18, 0.008, 0.1]
+
+
+def condition(displacement, width, duration, profile):
+    dx, dy = displacement
+    return np.asarray(
+        [dx / 2000, dy / 2000, math.log1p(width) / 6, math.log(max(duration, 0.01)), *profile],
+        dtype=np.float32,
+    )
+
+
+def preprocess(trace: dict) -> tuple[np.ndarray, np.ndarray]:
+    if trace.get("split") != "generator_train" or trace.get("label") != "human":
+        raise ValueError("Neural fitting accepts only human generator_train recordings")
+    events = [e for e in trace["events"] if e.get("kind") == "move"]
+    if len(events) < 5:
+        raise ValueError("A trajectory needs at least five timed positions")
+    values = np.asarray([[e["x"], e["y"], e["t"]] for e in events], dtype=float)
+    if not np.isfinite(values).all() or np.any(np.diff(values[:, 2]) <= 0):
+        raise ValueError("Trajectory times must be finite and strictly increasing")
+    start, goal = values[0, :2], values[-1, :2]
+    duration = values[-1, 2] - values[0, 2]
+    delta, distance = goal - start, np.linalg.norm(goal - start)
+    if distance < 1 or not 0.01 <= duration <= 60:
+        raise ValueError("Unsupported displacement/duration")
+    positions = np.linspace(0, len(events) - 1, LENGTH)
+    samples = np.stack(
+        [np.interp(positions, np.arange(len(events)), values[:, i]) for i in range(3)], axis=1
+    )
+    u = np.linspace(0, 1, LENGTH)
+    base = start[None, :] + u[:, None] * delta
+    residual = (samples[:, :2] - base) / distance
+    increments = np.diff(samples[:, 2]) / duration * (LENGTH - 1)
+    log_dt = np.r_[0, np.log(np.maximum(increments, 1e-6))]
+    data = np.vstack((residual.T, log_dt))
+    width = float(trace.get("target_width", 24))
+    profile = trace.get("profile_features", DEFAULT_PROFILE)
+    if len(profile) != 8:
+        raise ValueError("Expected eight personal conditioning features")
+    return data.astype(np.float32), condition(delta, width, duration, profile)

human_movement_research-0.1.1/src/human_movement_research/inference.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from functools import lru_cache
+from pathlib import Path
+
+import numpy as np
+import torch
+
+from .data import condition
+from .model import LENGTH, STEPS, schedule
+
+
+@lru_cache(maxsize=2)
+def _load(path: str, modified_ns: int, size: int):
+    p = Path(path)
+    manifest = json.loads(p.with_suffix(".manifest.json").read_text())
+    if manifest.get("architecture") != "hm-diffusion-tcn-1" or not manifest.get(
+        "validated", {}
+    ).get("cpu_parity"):
+        raise ValueError("Unsupported or unvalidated checkpoint")
+    if manifest["sha256"] != hashlib.sha256(p.read_bytes()).hexdigest():
+        raise ValueError("Model checksum mismatch")
+    return torch.jit.load(str(p), map_location="cpu").eval()
+
+
+def generate(
+    path: str,
+    *,
+    start,
+    goal,
+    duration: float,
+    target_width: float,
+    profile_features: list[float],
+    seed: int = 0,
+) -> list[tuple[float, float, float]]:
+    p = Path(path)
+    model = _load(str(p.resolve()), p.stat().st_mtime_ns, p.stat().st_size)
+    rng = torch.Generator().manual_seed(seed)
+    delta = np.asarray(goal, dtype=float) - start
+    cond = torch.tensor(condition(delta, target_width, duration, profile_features)[None])
+    beta, alpha, cumulative = schedule()
+    x = torch.randn((1, 3, LENGTH), generator=rng)
+    with torch.inference_mode():
+        for i in range(STEPS - 1, -1, -1):
+            epsilon = model(x, torch.tensor([i / (STEPS - 1)]), cond)
+            x = (x - beta[i] / torch.sqrt(1 - cumulative[i]) * epsilon) / torch.sqrt(alpha[i])
+            if i:
+                variance = beta[i] * (1 - cumulative[i - 1]) / (1 - cumulative[i])
+                x += variance.sqrt() * torch.randn(x.shape, generator=rng)
+    values = x[0].numpy()
+    if not np.isfinite(values).all():
+        raise ValueError("Nonfinite neural generation")
+    u = np.linspace(0, 1, LENGTH)
+    residual = values[:2].T
+    residual -= (1 - u[:, None]) * residual[0] + u[:, None] * residual[-1]
+    # Reject implausible untrained outputs instead of silently clipping them into a path.
+    if np.max(np.abs(residual)) > 0.5:
+        raise ValueError("Neural path failed spatial residual validation")
+    xy = np.asarray(start) + u[:, None] * delta + residual * np.linalg.norm(delta)
+    increments = np.exp(np.clip(values[2, 1:], -5, 5))
+    times = np.r_[0, np.cumsum(increments) / increments.sum() * duration]
+    xy[0], xy[-1] = start, goal
+    times[-1] = duration
+    return [(float(p[0]), float(p[1]), float(t)) for p, t in zip(xy, times, strict=True)]

human_movement_research-0.1.1/src/human_movement_research/model.py

@@ -0,0 +1,41 @@
+"""Compact conditional temporal diffusion; independent of the desktop runtime."""
+
+import torch
+from torch import nn
+
+LENGTH, CHANNELS, CONDITION_SIZE, STEPS = 64, 32, 12, 32
+
+
+class Denoiser(nn.Module):
+    def __init__(self):
+        super().__init__()
+        self.input = nn.Conv1d(3, CHANNELS, 3, padding=1)
+        self.condition = nn.Sequential(
+            nn.Linear(CONDITION_SIZE + 3, CHANNELS), nn.SiLU(), nn.Linear(CHANNELS, CHANNELS)
+        )
+        self.blocks = nn.ModuleList(
+            [
+                nn.Sequential(
+                    nn.Conv1d(CHANNELS, CHANNELS, 3, padding=d, dilation=d),
+                    nn.SiLU(),
+                    nn.Conv1d(CHANNELS, CHANNELS, 1),
+                )
+                for d in (1, 2, 4, 8)
+            ]
+        )
+        self.output = nn.Conv1d(CHANNELS, 3, 3, padding=1)
+
+    def forward(self, x: torch.Tensor, step: torch.Tensor, condition: torch.Tensor) -> torch.Tensor:
+        time = torch.stack(
+            (step, torch.sin(step * 3.14159265), torch.cos(step * 3.14159265)), dim=1
+        )
+        h = self.input(x) + self.condition(torch.cat((condition, time), dim=1)).unsqueeze(-1)
+        for block in self.blocks:
+            h = h + block(h) * 0.25
+        return self.output(h)
+
+
+def schedule():
+    beta = torch.linspace(0.0001, 0.05, STEPS)
+    alpha = 1 - beta
+    return beta, alpha, torch.cumprod(alpha, dim=0)

human_movement_research-0.1.1/src/human_movement_research/training.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+import numpy as np
+import torch
+
+from .data import preprocess
+from .model import CONDITION_SIZE, LENGTH, STEPS, Denoiser, schedule
+
+
+def train(traces: list[dict], output: str | Path, *, epochs: int = 100, seed: int = 17842) -> dict:
+    if not traces or epochs < 1:
+        raise ValueError("Provide training traces and at least one epoch")
+    torch.manual_seed(seed)
+    torch.set_num_threads(2)
+    torch.use_deterministic_algorithms(True)
+    pairs = [preprocess(trace) for trace in traces]
+    x = torch.tensor(np.stack([p[0] for p in pairs]))
+    conditions = torch.tensor(np.stack([p[1] for p in pairs]))
+    model = Denoiser()
+    optimizer = torch.optim.AdamW(model.parameters(), lr=0.001)
+    _, _, cumulative = schedule()
+    losses = []
+    for _ in range(epochs):
+        total = 0.0
+        for indices in torch.randperm(len(x)).split(32):
+            batch = x[indices]
+            step = torch.randint(STEPS, (len(indices),))
+            noise = torch.randn_like(batch)
+            a = cumulative[step, None, None]
+            corrupted = a.sqrt() * batch + (1 - a).sqrt() * noise
+            loss = torch.nn.functional.mse_loss(
+                model(corrupted, step.float() / (STEPS - 1), conditions[indices]), noise
+            )
+            optimizer.zero_grad()
+            loss.backward()
+            torch.nn.utils.clip_grad_norm_(model.parameters(), 1)
+            optimizer.step()
+            total += loss.item() * len(indices)
+        losses.append(total / len(x))
+    output = Path(output)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    provenance = {
+        "architecture": "hm-diffusion-tcn-1",
+        "seed": seed,
+        "epochs": epochs,
+        "samples": len(traces),
+        "training_sha256": hashlib.sha256(json.dumps(traces, sort_keys=True).encode()).hexdigest(),
+        "participants": sorted({t["participant_id"] for t in traces}),
+        "sessions": sorted({t["session_id"] for t in traces}),
+        "loss": losses,
+        "quality": "research candidate; no behavioral fidelity certification",
+    }
+    torch.save({"weights": model.state_dict(), "provenance": provenance}, output)
+    output.with_suffix(".json").write_text(json.dumps(provenance, indent=2), encoding="utf-8")
+    return provenance
+
+
+def export(checkpoint: str | Path, output: str | Path) -> dict:
+    saved = torch.load(checkpoint, map_location="cpu", weights_only=True)
+    model = Denoiser().eval()
+    model.load_state_dict(saved["weights"])
+    scripted = torch.jit.script(model)
+    torch.manual_seed(100)
+    with torch.inference_mode():
+        for _ in range(4):
+            x, t, c = torch.randn(2, 3, LENGTH), torch.rand(2), torch.randn(2, CONDITION_SIZE)
+            reference, candidate = model(x, t, c), scripted(x, t, c)
+            if not torch.isfinite(candidate).all() or not torch.allclose(
+                reference, candidate, atol=1e-5
+            ):
+                raise ValueError("CPU export parity/finite-output validation failed")
+    output = Path(output)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    scripted.save(str(output))
+    manifest = {
+        "format": "torchscript",
+        "architecture": "hm-diffusion-tcn-1",
+        "steps": STEPS,
+        "length": LENGTH,
+        "sha256": hashlib.sha256(output.read_bytes()).hexdigest(),
+        "validated": {"cpu_parity": True, "finite_outputs": True},
+        "behavioral_validation": False,
+        "provenance": saved["provenance"],
+    }
+    output.with_suffix(".manifest.json").write_text(
+        json.dumps(manifest, indent=2), encoding="utf-8"
+    )
+    return manifest