behavioral-entropy
AI agent behavioral fingerprinting via entropy analysis.
behavioral-entropy measures Shannon entropy across agent activity streams
(timing patterns, decision latencies, action distributions) and generates
deterministic behavioral fingerprints. It can detect when two agents
exhibit similar behavior, score how unique an agent's behavioral profile
is relative to a population, and flag anomalous deviations from an
established baseline.
Installation
pip install behavioral-entropy
For ML-based anomaly detection (IsolationForest, DBSCAN, PCA):
pip install behavioral-entropy[ml]
The core library requires only numpy. Scikit-learn and scipy are
optional; the profiler falls back to pure statistical methods when
they are not installed.
Quick start
Python API
from behavioral_entropy import (
AgentProfile,
shannon_entropy_numeric,
generate_fingerprint,
profile_similarity,
BehavioralProfiler,
)
# Measure entropy of a timing sequence
timings = [0.12, 0.11, 0.13, 0.12, 0.14, 0.11, 0.13, 0.12]
entropy = shannon_entropy_numeric(timings)
print(f"Timing entropy: {entropy:.3f} bits")
# Build a profile and generate a fingerprint
profiler = BehavioralProfiler()
profile = profiler.build_profile(
agent_id="agent-alpha",
timing_samples=[timings],
action_choices={"query": 15, "index": 8, "delete": 2},
)
print(f"Fingerprint: {profile.fingerprint_hash}")
print(f"Behavioral entropy: {profile.behavioral_entropy:.3f}")
# Compare two profiles
profile_b = profiler.build_profile(
agent_id="agent-beta",
timing_samples=[[0.50, 0.48, 0.52, 0.49, 0.51]],
action_choices={"index": 20, "query": 3},
)
cmp = profile_similarity(profile, profile_b)
print(f"Similarity: {cmp.similarity:.3f}")
CLI
Analyze JSONL agent activity logs:
behavioral-entropy analyze activity.jsonl
Expected JSONL format (one JSON object per line):
{"agent_id": "agent-1", "timestamp": 1700000000.0, "action": "query", "latency_ms": 120.5}
{"agent_id": "agent-1", "timestamp": 1700000001.2, "action": "query", "latency_ms": 115.3}
Measure text entropy:
behavioral-entropy text-entropy "The quick brown fox jumps over the lazy dog"
Concepts
Shannon entropy
Shannon entropy measures the unpredictability of a distribution. For a discrete random variable with probability mass function p(x):
H(X) = -sum(p(x) * log2(p(x)))
A uniform distribution maximizes entropy (high unpredictability). A constant sequence has zero entropy (fully predictable).
Behavioral fingerprinting
Each AI agent produces observable behavioral signals: inter-request timing intervals, decision latencies, action-type distributions, and resource consumption patterns. These signals form a statistical fingerprint that can distinguish one agent from another, even when the agents perform the same nominal task.
behavioral-entropy computes a SHA-256 digest over the agent's
behavioral features, producing a deterministic fingerprint. Two profiles
with identical behavioral patterns yield the same fingerprint.
Anomaly detection
When scikit-learn is installed, the BehavioralProfiler trains an
IsolationForest on an agent's historical feature vectors. New
observations are scored against this model. Deviations from the learned
distribution indicate potential identity changes, compromised agents,
or behavioral drift.
Modules
| Module | Purpose |
|---|---|
entropy |
Shannon entropy calculations, text entropy, behavioral entropy |
fingerprint |
Fingerprint generation, profile similarity, uniqueness scoring |
profiler |
Feature extraction, ML-based profiling, anomaly detection |
types |
Shared dataclasses (AgentProfile, EntropyMeasurement, etc.) |
cli |
Command-line interface for JSONL analysis |
Development
git clone https://github.com/ScrappinR/behavioral-entropy.git
cd behavioral-entropy
pip install -e ".[all]"
pytest
License
Apache 2.0. See LICENSE.
Metadata
Release files for behavioral-entropy 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| behavioral_entropy-0.1.0.tar.gz | 24.0 kB | Without provenance | Details for behavioral_entropy-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| behavioral_entropy-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for behavioral_entropy-0.1.0-py3-none-any.whl |
Total release size: 46.2 kB
Release files / behavioral_entropy-0.1.0.tar.gz
| Download URL | behavioral_entropy-0.1.0.tar.gz |
|---|---|
| Size | 24.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0805dd02a89a9131eb09ae7835703bc17efedb18a76acf1ab3344b5f2a7e0f5d
|
|
BLAKE2b-256 checksum How to use checksums |
a176d977429992ecaafb1280fc29f1896b6e6d5f11d893a4f7a96d5d30902f31
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.12
|
Release files / behavioral_entropy-0.1.0-py3-none-any.whl
| Download URL | behavioral_entropy-0.1.0-py3-none-any.whl |
|---|---|
| Size | 22.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ffbe3724b393b20c94f02afec7f6877f6b97d57f5eea72fe9bd00f489cfa50d5
|
|
BLAKE2b-256 checksum How to use checksums |
804e0e036719a5a414c065cc603a09a5b6f5021dbc349fddaea08a989636315e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.12
|
Security for behavioral-entropy 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.