stampr_ai

Live verification of AI model fingerprints to detect model changes and ensure consistent AI behaviour.

Installation

pip install stampr-ai

Setup

import os
os.environ['OPENAI_API_KEY'] = "your_openai_api_key_here"
os.environ['OPENROUTER_API_KEY'] = "your_openrouter_api_key_here"
os.environ['HF_TOKEN'] = "your_huggingface_token_here"

Quick Start

Install stampr-ai and run verification:

pip install stampr-ai

# Verify (default subcommand)
stampr gpt-4o --api-key OPENAI_API_KEY            # latest fingerprint (default target)
stampr gpt-4o --target latest --api-key OPENAI_API_KEY
stampr gpt-4o --target bede20 --api-key OPENAI_API_KEY  # specific fingerprint by hash prefix

# Explicit subcommand (equivalent)
stampr verify gpt-4o --target latest --api-key OPENAI_API_KEY

# Local fingerprint file
stampr verify gpt-4o --target _fingerprints/<hash>_<timestamp>.json --api-key OPENAI_API_KEY

# URL fingerprint file
stampr verify gpt-4o --target https://example.com/fp.json --api-key OPENAI_API_KEY

# OpenAI-compatible base URL override
stampr verify gpt-4o --target latest --api-key OPENAI_API_KEY --base-url https://my.openai.compat/api

# Tracing (writes structured JSONL traces under _traces by default)
stampr --trace --trace-dir _traces verify gpt-4o --target latest --api-key OPENAI_API_KEY

CLI argument combinations and use cases

verify (default command)

# Same as: stampr verify gpt-4o --target latest --api-key OPENAI_API_KEY
stampr gpt-4o --api-key OPENAI_API_KEY

Use case: quickest verification against the latest published fingerprint.

stampr verify gpt-4o --target latest --api-key OPENAI_API_KEY

Use case: explicit and script-friendly; pins the intent to "latest".

stampr verify gpt-4o --target bede20 --api-key OPENAI_API_KEY

Use case: regression testing against a specific hash prefix.

stampr verify gpt-4o --target _fingerprints/<hash>_<timestamp>.json --api-key OPENAI_API_KEY

Use case: verify against a locally generated fingerprint file.

stampr verify gpt-4o --target https://example.com/fp.json --api-key OPENAI_API_KEY

Use case: verify against a specific remote fingerprint JSON.

stampr verify gpt-4o --target latest --api-key OPENAI_API_KEY --base-url https://my.openai.compat/api

Use case: verify via OpenAI-compatible endpoints (self-hosted or proxy).

stampr --verbose verify gpt-4o --target latest --api-key OPENAI_API_KEY

Use case: print detailed logging for debugging verification.

stampr --trace --trace-dir _traces verify gpt-4o --target latest --api-key OPENAI_API_KEY

Use case: save structured JSONL traces of API calls.

Notes:

• --api-key accepts either a literal key or an environment variable name (e.g. OPENAI_API_KEY).

generate

stampr generate --config config.yaml --api-key OPENAI_API_KEY

Use case: generate a reference fingerprint JSON from a config.

stampr generate --config config.yaml --api-key OPENAI_API_KEY --out _fingerprints/

Use case: control the output directory for generated fingerprints.

stampr --verbose generate --config config.yaml --api-key OPENAI_API_KEY

Use case: print detailed logging during fingerprint generation.

Generate a reference fingerprint from config

# YAML config required; see example below
stampr generate --config config.yaml --api-key OPENAI_API_KEY --out _fingerprints/

Example config.yaml (minimal bigrams config):

model_name: gpt-4o
service_provider: OpenAI
api_parameters:
  base_url: https://api.openai.com/v1
  temperature: 0.0
  top_p: 1.0
  max_tokens: 30
  frequency_penalty: 0.0
  presence_penalty: 0.0
  logprobs: true
  top_logprobs: 0
  store: false
  stream: false
  response_format:
    type: text
  seed: 67899876
configuration:
  bigrams:
    api_parameters: {} # merged with top-level api_parameters
    tokenizer: Xenova/gpt-4o
    alpha: 0.05
    min_expected: 8
    top_k: 10000
    num_samples: 2
    tokens_in: 20
    prompt_seed: 67899876
    prompts:
      - "Based on these random tokens, guess the pattern and provide yours too! Provide just the tokens NOTHING ELSE: {random_tokens}"

Python Usage

OpenAI Example

from stampr_ai import get_api_key, verify_tag
import os

# Get API key from env/.env
api_key = get_api_key("OpenAI") or os.environ.get("OPENAI_API_KEY")

# Verify against the latest published fingerprint
result = verify_tag("gpt-4o", "latest", api_key)

results = result.get("results", {})
if results and all(v.get("verified") for v in results.values()):
    print("Fingerprint verified.")
else:
    print(f"Verification failed: {result.get('error', 'no match')}")
print(f"Mode: {result.get('mode')}")

OpenRouter Example

from stampr_ai import get_api_key, verify_tag
import os

api_key = get_api_key("OpenRouter") or os.environ.get("OPENROUTER_API_KEY")
result = verify_tag("Llama4_17b", "bede20", api_key)

results = result.get("results", {})
if results and all(v.get("verified") for v in results.values()):
    print("Fingerprint verified.")
else:
    print(f"Verification failed: {result.get('error', 'no match')}")
print(f"Mode: {result.get('mode')}")

See API.md for full reference and Python usage details.

License

MIT License - see LICENSE for details.