Metadata-Version: 2.4
Name: stampr_ai
Version: 0.9.0a1
Summary: Live verification of AI model fingerprints to detect model changes
Author-email: Vasilios Mavroudis <mavroudisv@gmail.com>, Dan Ristea <dan.ristea.19@ucl.ac.uk>
License-Expression: MIT
Project-URL: Homepage, https://stampr-ai.com
Project-URL: Documentation, https://stampr-ai.com/docs
Project-URL: Repository, https://github.com/stampr-ai/stampr_ai
Project-URL: Bug Tracker, https://github.com/stampr-ai/stampr_ai/issues
Project-URL: Changelog, https://github.com/stampr-ai/stampr_ai/blob/main/CHANGELOG.md
Keywords: ai,model,verification,fingerprint,security,llm,monitoring,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.32.4
Requires-Dist: python-dotenv>=1.1.0
Requires-Dist: scipy>=1.17.0
Requires-Dist: zstandard
Requires-Dist: brotli
Requires-Dist: PyYAML>=6.0.2
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-extra-types[pycountry]>=2.11.0
Requires-Dist: annotated-types>=0.7.0
Requires-Dist: typer>=0.24.1
Requires-Dist: click>=8.3.1
Requires-Dist: tokenizers>=0.22.2
Requires-Dist: openai>=2.26.0
Provides-Extra: tqdm
Requires-Dist: tqdm>=4.67.3; extra == "tqdm"
Provides-Extra: all
Requires-Dist: stampr_ai[tqdm]; extra == "all"
Dynamic: license-file

# stampr_ai

<div style="text-align: center;">
  <img src="https://www.stampr-ai.com/images/stampr.png" alt="Stampr AI Logo" width="200"/>
</div>

[![PyPI version](https://badge.fury.io/py/stampr-ai.svg)](https://badge.fury.io/py/stampr-ai)
[![Python versions](https://img.shields.io/pypi/pyversions/stampr-ai.svg)](https://pypi.org/project/stampr-ai/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

## Installation

```bash
pip install stampr-ai
```

## Setup

```python
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:

```bash
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)

```bash
# 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.

```bash
stampr verify gpt-4o --target latest --api-key OPENAI_API_KEY
```
Use case: explicit and script-friendly; pins the intent to "latest".

```bash
stampr verify gpt-4o --target bede20 --api-key OPENAI_API_KEY
```
Use case: regression testing against a specific hash prefix.

```bash
stampr verify gpt-4o --target _fingerprints/<hash>_<timestamp>.json --api-key OPENAI_API_KEY
```
Use case: verify against a locally generated fingerprint file.

```bash
stampr verify gpt-4o --target https://example.com/fp.json --api-key OPENAI_API_KEY
```
Use case: verify against a specific remote fingerprint JSON.

```bash
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).

```bash
stampr --verbose verify gpt-4o --target latest --api-key OPENAI_API_KEY
```
Use case: print detailed logging for debugging verification.

```bash
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`

```bash
stampr generate --config config.yaml --api-key OPENAI_API_KEY
```
Use case: generate a reference fingerprint JSON from a config.

```bash
stampr generate --config config.yaml --api-key OPENAI_API_KEY --out _fingerprints/
```
Use case: control the output directory for generated fingerprints.

```bash
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

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

Example `config.yaml` (minimal bigrams config):

```yaml
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

```python
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

```python
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](LICENSE) for details. 




