Python Implementation

The Python implementation lives in the aihint/ directory and provides a full API, CLI, and trust scoring engine.

Requirements: Python 3.8+

Setup

From the repository root, install the required third-party Python packages:

python -m pip install cryptography requests jsonschema click pydantic aiohttp dnspython python-whois

Then run the CLI directly from source:

python -m aihint.cli --help

Run from the repository root

The JSON Schema validator looks for schema/aihint-global.schema.json relative to your working directory. Running commands from the repo root ensures validation works correctly. If the file isn't found, a built-in fallback schema is used.

CLI Usage

Run CLI commands with python -m aihint.cli from the repository root:

Create a hint

python -m aihint.cli create \
  --target "https://example.com" \
  --issuer "https://trust.example.org" \
  --score 0.85 \
  --method "aihint-core-v1" \
  --public-key-url "https://example.com/.well-known/aihint-pubkey.pem" \
  --private-key private_key.pem \
  --output aihint.json

Options:

Option	Required	Description
--target	Yes	Target domain URL
--issuer	Yes	Issuing authority URL
--score	Yes	Trust score (0.0–1.0)
--method	Yes	Scoring method identifier
--public-key-url	Yes	URL of the public key
--private-key	No	Private key file to sign the hint
--output / -o	No	Output file path
--expires-in	No	Expiration in days (default: 365)
--comment	No	Optional comment
--version	No	AiHint version (default: 0.1)

Validate a hint

python -m aihint.cli validate aihint.json

Verify a signature

python -m aihint.cli verify aihint.json

This fetches the public key from the public_key_url in the hint and verifies the RSA-SHA256 signature.

View hint info

python -m aihint.cli info aihint.json

Sign an existing hint

python -m aihint.cli sign aihint.json --private-key private_key.pem

Create with auto-scoring

python -m aihint.cli create-with-score \
  --target "https://example.com" \
  --issuer "https://trust.example.org" \
  --public-key-url "https://example.com/.well-known/aihint-pubkey.pem" \
  --private-key private_key.pem \
  --output aihint.json

This runs the trust scoring engine against the target domain and uses the result as the score.

Trust scoring

# Score a single website
python -m aihint.cli scoring score https://example.com

# Score with JSON output
python -m aihint.cli scoring score https://example.com --format json

# Score multiple URLs
python -m aihint.cli scoring batch https://example.com https://another.com

# Score URLs from a file
python -m aihint.cli scoring batch --file urls.txt

# Generate a sample config file
python -m aihint.cli scoring config --output scoring-config.json

Scoring output formats: text (default), json, table

Python API

Basic usage

import sys
sys.path.insert(0, '/path/to/aihint-standard')

from datetime import datetime, timezone, timedelta
from aihint import AIHint

api = AIHint()

# Create a hint
hint = api.create_global_hint(
    target="https://example.com",
    issuer="https://trust.example.org",
    score=0.85,
    method="aihint-core-v1",
    public_key_url="https://example.com/.well-known/aihint-pubkey.pem",
    expires_at=datetime.now(timezone.utc) + timedelta(days=365),
    comment="Verified domain",
)

# Sign the hint
signed = api.sign_hint(hint, "private_key.pem")

# Save to file
api.save_hint(signed, "aihint.json")

# Load and verify
loaded = api.load_hint("aihint.json")
is_valid = api.validate_hint(loaded)    # True if schema-valid
is_verified = api.verify_hint(loaded)   # True if signature checks out

Lower-level classes

When running from the repo root, you can import directly:

from aihint import AIHintValidator, AIHintSigner, AIHintVerifier

# Validate a dict against the JSON Schema
validator = AIHintValidator()
validator.validate(hint_dict)          # raises AIHintValidationError on failure
validator.validate_file("aihint.json")

# Sign a dict
signer = AIHintSigner("private_key.pem")
signature = signer.sign(hint_dict)     # returns Base64 signature string

# Verify a dict (fetches public key from public_key_url)
verifier = AIHintVerifier()
result = verifier.verify(hint_dict)    # True/False
verifier.verify_file("aihint.json")

Trust scoring

import asyncio
from aihint.scoring import TrustScoringEngine

engine = TrustScoringEngine()
result = asyncio.run(engine.score_website("https://example.com"))

print(f"Score: {result.final_score}")
print(f"Trust level: {result.trust_level}")
print(f"Security: {result.security_score}")
print(f"Reputation: {result.reputation_score}")
print(f"Compliance: {result.compliance_score}")

The scoring engine evaluates:

Category	Weight	Scorers
Security	40%	SSL/TLS validation, security headers, malware checks
Reputation	35%	Domain reputation, domain age, incident history
Compliance	25%	Privacy policy, contact info, compliance checks

Exported Classes

Class	Module	Purpose
AIHint	aihint	High-level facade for all operations
AIHintValidator	aihint.core	JSON Schema validation
AIHintSigner	aihint.core	RSA-SHA256 signing
AIHintVerifier	aihint.core	Signature verification (fetches public key via HTTP)
AIHintGlobal	aihint.models	Pydantic model for a Global Hint document
AIHintData	aihint.models	Pydantic model for hint data
TrustScoringEngine	aihint.scoring	Async trust scoring engine

Required Python Packages

These third-party packages must be installed for the implementation to work:

Package	Purpose
cryptography	RSA signing and verification
requests	HTTP requests (public key fetching)
jsonschema	JSON Schema validation
click	CLI framework
pydantic	Data models and validation
aiohttp	Async HTTP for trust scoring
dnspython	DNS resolution for scoring
python-whois	WHOIS lookups for domain age scoring

Install all at once:

python -m pip install cryptography requests jsonschema click pydantic aiohttp dnspython python-whois