Skip to Content
DocumentationSDKs

SDKs & CLI

Official tooling for implementing the AI Provenance Protocol in your applications.

TypeScript / JavaScript SDK

Installation

npm install @ai-provenance-protocol/sdk

Requires Node.js 18+. Works with TypeScript and JavaScript, ESM and CommonJS.

Quick start

import { APP } from '@ai-provenance-protocol/sdk'
 
// Create metadata for a generation event
const metadata = APP.create({
  generator: {
    platform: 'my-platform',
    model: 'anthropic/claude-sonnet-4',
  },
  verification_uri: 'https://verify.my-platform.com/v1/verify',
})
 
// Embed in your JSON API response
const response = APP.embed(generatedContent, metadata)
// { ...generatedContent, _ai_provenance: { app_version: '1.0.0', ... } }

API reference

APP.create(options)

Creates a new APP metadata object. Automatically sets app_version, generated_at (current UTC time), and generation_id (UUID v4).

const metadata = APP.create({
  generator: {
    platform: 'my-platform',
    model: 'anthropic/claude-sonnet-4',
    platform_version: '2.1.0',       // optional
  },
  verification_uri: 'https://verify.my-platform.com/v1/verify',
  inputs: {
    type: 'structured',
    description: 'Product attributes',
  },
})

APP.embed(content, metadata)

Embeds APP metadata into a JSON object under the _ai_provenance key.

const output = APP.embed(
  { title: 'Premium Leather Wallet', description: 'Handcrafted...' },
  metadata
)
// { title: '...', description: '...', _ai_provenance: { ... } }

APP.extract(output)

Extracts APP metadata from an embedded JSON object, returning content and metadata separately.

const { content, app } = APP.extract(receivedJson)
// content: { title: '...', description: '...' }
// app: AppMetadata | null

APP.validate(metadata)

Validates APP metadata against the v1.0 JSON Schema. Returns { valid, errors }. Useful for validating metadata received from external systems.

const result = APP.validate(unknownData)
 
if (!result.valid) {
  result.errors.forEach(e => console.error(`${e.field}: ${e.message}`))
}

APP.review(metadata, options)

Records a human review on an existing metadata object. Returns a new object — does not mutate the original.

const reviewed = APP.review(metadata, {
  human_reviewed: true,
  reviewer_role: 'editor',
  review_type: 'approved_without_changes',
  review_notes: 'Adjusted tone for brand guidelines.',
})

review_type must be one of: approved_without_changes, edited, rejected, pending.

APP.hashContent(content, algorithm?)

Computes a content hash for the content_hash field. For JSON objects, uses canonical form (sorted keys, _ai_provenance excluded). Default algorithm is sha256.

const hash = APP.hashContent({ title: 'My Article', body: '...' })
// 'sha256:e3b0c44298fc...'
 
// Attach to metadata
const withHash = { ...metadata, content_hash: hash }

APP.verify(generationId, verificationUri)

Level 1 verification: confirms a generation ID exists at a platform’s verification endpoint.

const result = await APP.verify(
  metadata.generation_id,
  'https://verify.my-platform.com/v1/verify'
)
 
if (result.found) {
  console.log('Verified:', result.generator?.model)
}

APP.match(contentHash, verificationUri, contentType?)

Level 2 verification: finds generations matching a content hash.

const result = await APP.match(
  'sha256:e3b0c44298fc...',
  'https://verify.my-platform.com/v1/verify',
  'application/json'
)
console.log(`${result.matches.length} matching generation(s)`)

Named exports

All functions are also available as named exports for tree-shaking:

import { create, embed, extract, validate, review, hashContent, verify, match } from '@ai-provenance-protocol/sdk'

TypeScript types

import type { AppMetadata, Generator, Review, ValidationResult } from '@ai-provenance-protocol/sdk'

Python SDK

Installation

pip install ai-provenance-protocol

Requires Python 3.9+. Depends on jsonschema (Draft 2020-12 validation) and httpx (sync + async HTTP).

Quick start

from ai_provenance_protocol import APP
 
# Create metadata after your AI call
metadata = APP.create(
    generator={"platform": "my-platform", "model": "gpt-4o"},
    verification_uri="https://api.my-platform.com/verify",
)
 
# Embed in your API response
response = APP.embed({"reply": "Hello, world!"}, metadata)
# {"reply": "Hello, world!", "_ai_provenance": {"app_version": "1.0.0", ...}}

API reference

APP.create(**kwargs)

Creates a new APP metadata record. Automatically sets app_version, generated_at (UTC), and generation_id (UUID v4).

metadata = APP.create(
    generator={"platform": "my-platform", "model": "gpt-4o"},
    verification_uri="https://api.my-platform.com/verify",
    inputs={"type": "text", "description": "User prompt"},
    # optional
    generation_id="550e8400-...",
    parent_generation_id="...",
    extensions={"io.acme": {"tenant_id": "t_123"}},
)

APP.embed(content, metadata) / APP.extract(content)

output = APP.embed({"answer": "42"}, metadata)
 
content, meta = APP.extract(output)
# content == {"answer": "42"}
# meta    == {...}  or  None if not present

APP.validate(metadata)

Validates against the APP v1.0 JSON Schema (bundled — no network call).

result = APP.validate(metadata)
# {"valid": True, "errors": []}
 
if not result["valid"]:
    for err in result["errors"]:
        print(err)

APP.review(metadata, **kwargs)

Records a human review. Returns a new dict (immutable pattern).

approved = APP.review(
    metadata,
    human_reviewed=True,
    reviewer_role="editor",
    review_type="approved_without_changes",
)

APP.hash_content(content) / APP.attach_hash(metadata, content)

h = APP.hash_content({"answer": "42"})
# {"algorithm": "sha256", "value": "<hex>"}
 
metadata_with_hash = APP.attach_hash(metadata, content)

APP.verify_sync(generation_id, verification_uri) / APP.verify(...)

Level 1 verification — look up a generation ID.

# Sync
result = APP.verify_sync(
    metadata["generation_id"],
    metadata["verification_uri"],
)
# {"found": True, "metadata": {...}}
 
# Async
result = await APP.verify(
    metadata["generation_id"],
    metadata["verification_uri"],
)

APP.match_sync(content_hash, verification_uri) / APP.match(...)

Level 2 verification — match by content hash.

h = APP.hash_content(content)
result = APP.match_sync(h["value"], metadata["verification_uri"])
# {"match": True, "generation_id": "..."}

Direct imports and types

All functions and TypedDict types are importable directly:

from ai_provenance_protocol import create, embed, extract, validate, review
from ai_provenance_protocol import hash_content, attach_hash, verify_sync
from ai_provenance_protocol import AppMetadata, Generator, ValidationResult

Validator CLI

A command-line tool for validating APP metadata and verifying generations — no code required.

Usage

npx app-validator <command>

Or install globally:

npm install -g app-validator

Commands

validate <file>

Validate APP metadata in a JSON file.

# Validate a standalone APP metadata object
npx app-validator validate metadata.json
 
# Extract and validate _ai_provenance from a larger JSON document
npx app-validator validate api-response.json --extract
 
# Machine-readable JSON output (for CI pipelines)
npx app-validator validate metadata.json --json

Exit codes: 0 = valid, 1 = invalid, 2 = file/parse error

✓ Valid APP metadata

  generation_id       a1b2c3d4-e5f6-7890-abcd-ef1234567890
  generator           anthropic/claude-sonnet-4 (my-platform)
  generated_at        2026-04-18T10:00:00Z
  ai_generated        true
  reviewed            false
  verification_uri    https://verify.my-platform.com/v1/verify

verify <generation-id> <verification-uri>

Level 1 verification: confirm a generation ID exists at a platform’s endpoint.

npx app-validator verify a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  https://verify.my-platform.com/v1/verify

Exit codes: 0 = found, 1 = not found, 2 = request error

hash <file>

Compute a canonical content hash for a JSON file (for use with the content_hash field).

# Hash a JSON file
npx app-validator hash content.json
 
# Hash only the content, excluding _ai_provenance
npx app-validator hash output.json --extract
 
# Use SHA-512
npx app-validator hash content.json --algorithm sha512

Output: sha256:e3b0c44298fc1c149afbf4c8996fb924...

CI integration

# GitHub Actions — fail if APP metadata is missing or invalid
- name: Validate APP metadata
  run: npx app-validator validate ./output/response.json --extract --json

Available packages

PackageLanguageRegistryStatus
@ai-provenance-protocol/sdkTypeScript / JavaScriptnpmAvailable
app-validatorCLInpmAvailable
ai-provenance-protocolPythonPyPIAvailable

Implementing without an SDK

You don’t need an SDK to implement APP. The protocol is simple enough to implement directly:

  1. Generate a UUID v4 for generation_id
  2. Construct the metadata JSON object
  3. Embed using your chosen embedding mode
  4. Validate against the JSON Schema 

See the Getting Started guide for a full walkthrough.

Contributing

Interested in building an SDK for another language? See the Contributing Guide .

Last updated on
Regulatory MappingOverview