HumanProof

PyPI version CI codecov Python 3.10+ License: MIT PyPI Downloads Typed

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/[email protected]

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/[email protected]
  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

Star History Chart

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

Real-World Scenario

Esports: Detecting AI Aimbot in Tournament Play

A tournament operator reviews replay data for a suspected aimbot. The player's mouse trajectory is unnaturally smooth — no micro-corrections, no velocity variance. humanproof flags it in under 100ms with no ML model required:

from humanproof import InputSample, InputTrajectory, MotorScorer

# Human player trajectory — realistic noise, varied timing (dt 8–12ms)
human_deltas = [
    (3.1, 2.4, 9.0), (-1.2, 3.8, 11.0), (4.7, -0.9, 8.0), (2.3, 5.1, 10.0),
    (-0.8, 2.7, 12.0), (5.2, -1.4, 9.0), (1.9, 4.3, 10.0), (-2.6, 0.8, 8.0),
    (3.8, -3.1, 11.0), (0.4, 6.2, 9.0), (-1.7, 2.9, 10.0), (4.1, 0.3, 12.0),
    (2.8, -2.2, 8.0), (-0.5, 4.8, 10.0), (3.4, 1.7, 9.0), (1.1, -3.6, 11.0),
    (5.0, 2.1, 10.0), (-2.9, 3.5, 8.0), (0.7, -1.8, 12.0), (4.4, 2.6, 9.0),
]
human_samples = [InputSample(dx=dx, dy=dy, dt=dt) for dx, dy, dt in human_deltas]

# AI bot trajectory — unnaturally smooth, perfectly consistent timing (dt=16ms exactly)
bot_deltas = [
    (2.0, 2.0, 16.0), (2.0, 2.0, 16.0), (2.0, 2.0, 16.0), (2.0, 2.0, 16.0),
    (2.0, 2.0, 16.0), (2.0, 2.0, 16.0), (2.0, 2.0, 16.0), (2.0, 2.0, 16.0),
    (2.0, 2.0, 16.0), (2.0, 2.0, 16.0), (2.0, 2.0, 16.0), (2.0, 2.0, 16.0),
    (2.0, 2.0, 16.0), (2.0, 2.0, 16.0), (2.0, 2.0, 16.0), (2.0, 2.0, 16.0),
    (2.0, 2.0, 16.0), (2.0, 2.0, 16.0), (2.0, 2.0, 16.0), (2.0, 2.0, 16.0),
]
bot_samples = [InputSample(dx=dx, dy=dy, dt=dt) for dx, dy, dt in bot_deltas]

scorer = MotorScorer()

human_result = scorer.score(InputTrajectory(samples=human_samples))
bot_result   = scorer.score(InputTrajectory(samples=bot_samples))

print(f"[Player]  verdict={human_result.verdict}  human_score={human_result.human_score:.2f}  ai_score={human_result.ai_score:.2f}")
print(f"[Bot]     verdict={bot_result.verdict}  human_score={bot_result.human_score:.2f}  ai_score={bot_result.ai_score:.2f}")

if bot_result.verdict == "AI":
    print("\nFLAGGED: Suspected aimbot detected — trajectory referred to tournament integrity committee.")

What this catches that traditional anti-cheat misses: Memory scanners require OS-level access and are bypassed by external AI controllers. humanproof works on replay data alone — usable post-match for dispute resolution, with no kernel driver required.

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

---

Stay Updated

Subscribe to The Silence Layer — weekly dispatches on production AI infrastructure, new releases, and the failure modes that production AI systems don't surface until it's too late.

License

MIT — see LICENSE.