humanproof 0.1.0

Motor-noise fingerprinting for AI detection in competitive games

humanproof

77 tests · 95% coverage — motor-noise fingerprinting for AI detection in competitive games.

Navigation: Why · How it works · Features · Install · Quick Start · CLI · REST API · MCP / Claude · OpenAI · GitHub Action · vs Alternatives · Repo tree · Star history

---

Why

AI agents in competitive gaming (FPS, RTS, MOBAs) produce unnaturally smooth input — near-zero jitter, no micro-corrections, perfectly consistent velocity. humanproof quantifies this difference with a lightweight pure-Python library that requires no ML models.

How it works

graph LR
    A[Input samples dx/dy/dt] --> B[InputTrajectory]
    B --> C[MotorScorer.extract_features]
    C --> D[MotorFeatures<br/>noise_ratio, correction_rate, smoothness]
    D --> E[MotorScorer.score]
    E --> F[MotorScore<br/>human_score, ai_score, verdict]
    F --> G[CLI / API / MCP]

Features

Feature	Description
Minimal dependencies (click, rich only)	No numpy, no scikit-learn — just two lightweight CLI/display packages
No training data	Threshold-based heuristics, works out of the box
Multiple interfaces	CLI, FastAPI REST server, MCP for Claude
SQLite persistence	Stores trajectories and scores locally
77 pytest tests	95% coverage, fully typed
MCP tools	score_trajectory, batch_score, list_scores for Claude
OpenAI functions	JSON definitions in tools/openai-tools.json
GitHub Action	sandeep-alluru/humanproof@v0.1.0

Key discriminating features:

Signal	Human	AI
noise_ratio (std/mean speed)	0.4 – 0.8	0.05 – 0.2
correction_rate (reversals/sample)	0.15 – 0.35	< 0.05
smoothness (1/mean_jerk)	< 5.0	> 8.0

Install

Note: PyPI publication is pending. Install directly from GitHub:

pip install git+https://github.com/sandeep-alluru/humanproof.git

pip install humanproof
pip install "humanproof[api]"   # + FastAPI server
pip install "humanproof[mcp]"   # + MCP server for Claude

Quickstart

from humanproof import InputSample, InputTrajectory, MotorScorer

samples = [InputSample(dx=3.0, dy=2.0, dt=10.0) for _ in range(20)]
traj = InputTrajectory(samples=samples)
scorer = MotorScorer()
result = scorer.score(traj)
print(result.verdict, result.human_score)

CLI

Command	Description
humanproof score <file>	Score a single JSON trajectory file
humanproof batch <dir>	Score all JSON files in a directory
humanproof batch-csv <csv>	Score trajectories from a CSV file (columns: trajectory_id, t, x, y, button)
humanproof session <csv>	Analyze a session CSV for behavioral shifts across trajectories
humanproof log	List all stored scores
humanproof status	Show count of stored data

humanproof score trajectory.json
humanproof batch ./trajectories/
humanproof log
humanproof status

REST API

pip install "humanproof[api]"
uvicorn humanproof.api:app --reload

curl -X POST http://localhost:8000/score -H 'Content-Type: application/json' \
  -d '{"samples": [{"dx":1,"dy":1,"dt":10}]}'

Endpoints: GET /health · POST /score · POST /batch · GET /scores

MCP / Claude

Add to Claude Desktop config (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "humanproof": {
      "command": "humanproof-mcp"
    }
  }
}

Tools available: score_trajectory, batch_score, list_scores.

OpenAI Function Calling

Function definitions are in tools/openai-tools.json:

import json, openai
tools = json.load(open("tools/openai-tools.json"))
response = openai.chat.completions.create(
    model="gpt-4o",
    tools=tools,
    messages=[{"role": "user", "content": "Is this input human?"}]
)

GitHub Action

- uses: sandeep-alluru/humanproof@v0.1.0
  with:
    trajectory-file: replay.json

Alternatives

Tool	Approach	humanproof advantage
VAC / EasyAntiCheat	Memory scanning	No kernel driver needed
ML classifiers	Requires training data	Zero-shot, no model required
Replay analysis tools	Manual review	Automated, scriptable API
Kernel-level drivers	OS-level hooks	Pure Python, cross-platform

Repository tree

humanproof/
├── src/humanproof/       # library source
│   ├── trajectory.py     # InputSample, InputTrajectory
│   ├── scorer.py         # MotorFeatures, MotorScore, MotorScorer
│   ├── store.py          # SQLite persistence
│   ├── report.py         # Rich / JSON / Markdown output
│   ├── cli.py            # Click CLI
│   ├── api.py            # FastAPI server
│   └── mcp_server.py     # MCP server
├── tests/                # 77 pytest tests, 95% coverage
├── examples/
│   ├── demo.py                          # end-to-end demo
│   ├── game_anticheat.py                # game anti-cheat integration example
│   ├── esports_integrity_monitor.py     # esports session integrity monitor
│   └── claude_computer_use_detection.py # Claude computer-use AI detection
├── docs/                 # 11-page MkDocs site
└── tools/openai-tools.json

Star history

Add topics to this repo: gaming anti-cheat motor-fingerprinting ai-detection python

Case Studies

See how teams are using humanproof in production:

• Behavioral Anti-Cheat for Competitive Esports — IronLadder detects 847 cheaters in 30 days with 0.3% false positive rate
• Separating Real Users from AI Agents in Web Analytics — Veridian Analytics quarantines 94% of bot traffic across 500 e-commerce clients

License

MIT — see LICENSE.