Integration Guide

This is the complete implementer walkthrough. It starts with pip install and ends with your first AIEP-COMPLIANT v1.1.0 badge. No prior knowledge of the architecture is required.

Estimated time: under 30 minutes.

Step 0 — What you are building

You are building a system that produces verifiable decision records. Each record binds:

• the evidence that was used
• the reasoning steps taken
• a single pack_hash that proves nothing was altered

Any third party with aiep-genome-sdk can replay your records and confirm they are authentic. That is the entire value proposition.

Step 1 — Install the SDK

pip install aiep-genome-sdk

Verify the install:

aiep-verify --self-test

Expected output:

AIEP GENOME SDK v1.0.0 — R1-R8 SELF-TEST
  PASS R1 sorted keys
  PASS R2 compact separators
  PASS R3 NFC unicode normalisation
  PASS R4 NaN rejection
  PASS R5 negative-zero rejection
  ...
7/7 self-tests passed
AIEP-GENOME-SDK SELF-TEST PASS

If you see SELF-TEST PASS, the kernel is intact. If any test fails, do not proceed — the SDK installation is corrupted.

Step 2 — Understand the three fields

Every decision record has three inputs to pack_hash:

The pack_hash is a SHA-256 over these three fields in a canonical form defined in CANON_SPEC.md.

Step 3 — Create your first evidence record

from aiep_genome import pack_hash

evidence_ledger = [
    {
        "evidence_id": "e1",
        "evidence_type": "structured_data",
        "content": "Project Alpha cost estimate: £2,450,000. Basis: labour 47h @ £85/h, materials £1.2M.",
        "collected_ts": "2026-04-10T09:00:00Z",
        "source_uri": "https://example.com/project-alpha/cost-plan-rev3.pdf",
    }
]

reasoning_ledger = [
    {
        "entry_hash": "step_001",
        "kind": "ACTIVATION",
        "reasoning": "Cost plan references measured quantities. Accepting as primary evidence for cost commitment.",
        "branch_id": "main",
        "evidence_refs": ["e1"],
    }
]

schema_version = "aiep.canonical.v2.0.0"

result_hash = pack_hash(evidence_ledger, reasoning_ledger, schema_version)
print(f"pack_hash: {result_hash}")

The pack_hash you get is deterministic. Run this twice on any machine — same hash. Share the evidence_ledger, reasoning_ledger, and schema_version_id with anyone and they can reproduce the hash without trusting you.

Step 4 — Run the conformance suite

Download the AIEP-VECTORS test suite:

git clone https://github.com/Phatfella/AIEP-VECTORS.git

Run the full conformance verification:

aiep-verify --vectors AIEP-VECTORS/v1.1.0/

Expected output:

Running AIEP-VECTORS v1.1.0 (15 vectors)
  PASS det-001  deterministic-replay
  PASS det-002  deterministic-replay (NFC unicode)
  PASS det-003  deterministic-replay (uniqueness)
  PASS tamp-001 tamper-detection (evidence)
  PASS tamp-002 tamper-detection (reasoning)
  PASS neg-001  negative-proof
  PASS neg-002  negative-proof (empty)
  PASS adm-001  admissibility (gate closed)
  PASS adm-002  admissibility (gate open)
  PASS dis-001  dissent-preservation
  PASS dis-002  dissent-hash
  PASS rec-001  recall (order-a)
  PASS rec-002  recall (order-b)
  PASS swarm-001 swarm (order-independence)
  PASS swarm-002 swarm (inclusion-proof)
15/15 vectors passed — AIEP-COMPLIANT v1.1.0

Run the malformed-input rejection suite:

aiep-verify --vectors AIEP-VECTORS/v1.0.0-malformed/

Expected result: 6/6 vectors rejected — the SDK refuses to hash NaN, Infinity, or −0 inputs.

Step 5 — You are conformant

You can now add the conformance badge to your repository:

[![AIEP-COMPLIANT](https://img.shields.io/badge/AIEP-v1.1.0-green)](https://github.com/Phatfella/AIEP-VECTORS)

State in your CONFORMANCE.md:

# <Your System> — AIEP Conformance

[![AIEP-COMPLIANT](https://img.shields.io/badge/AIEP-v1.1.0-green)](CONFORMANCE.md)

Verified: aiep-verify --vectors AIEP-VECTORS/v1.1.0/ — 15/15 PASS  
Date: <date>  
SDK: aiep-genome-sdk v1.0.0

Step 6 — Automate conformance in CI

Add this to your CI pipeline so conformance is re-verified on every push:

# .github/workflows/aiep-verify.yml
name: AIEP Conformance
on: [push, pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install aiep-genome-sdk
        run: pip install aiep-genome-sdk
      - name: Clone test vectors
        run: git clone --depth 1 --branch v1.1.0 https://github.com/Phatfella/AIEP-VECTORS.git
      - name: Run conformance suite
        run: aiep-verify --vectors AIEP-VECTORS/v1.1.0/
      - name: Run malformed-input rejection suite
        run: aiep-verify --vectors AIEP-VECTORS/v1.0.0-malformed/

Step 7 — Add runtime enforcement (optional but recommended)

Once you are producing records in production, use aiep-validator to enforce the five constitutional constraints on every record before it is committed:

from aiep_validator.monitor import AiepMonitor

monitor = AiepMonitor()

# In your decision pipeline:
result = monitor.check(
    stored_pack_hash=pack_hash_of_record,
    evidence_ledger=evidence_ledger,
    reasoning_ledger=reasoning_ledger,
    plausibility_status="plausible",   # or "implausible", "speculative"
    gate_status="OPEN",                # or "CLOSED"
)

if not result.admissible:
    for v in result.violations:
        logging.error(f"AIEP constraint violated: [{v.rule}] {v.evidence}")
    raise RuntimeError("Record failed AIEP constitutional constraints — not committing")

The monitor commits a validator_record_hash to its audit log on every check. Suppression is detectable: changing a violation result to a pass changes the hash.

aiep-validator is available at: github.com/Phatfella/AIEP-VALIDATOR

Step 8 — Produce a replayable record document

A complete AIEP decision record for storage or sharing:

import json
from aiep_genome import pack_hash

evidence_ledger = [...]  # your evidence
reasoning_ledger = [...]  # your reasoning steps
schema_version = "aiep.canonical.v2.0.0"

record = {
    "schema_version_id": schema_version,
    "pack_hash": pack_hash(evidence_ledger, reasoning_ledger, schema_version),
    "evidence_ledger": evidence_ledger,
    "reasoning_ledger": reasoning_ledger,
    "plausibility_status": "plausible",
    "gate_status": "OPEN",
    "verdict": "admissible",
    "committed_ts": "2026-04-10T10:00:00Z",
}

with open("decision-record.json", "w") as f:
    json.dump(record, f, indent=2)

Any third party can verify this record with:

aiep-verify decision-record.json
# → record valid

What you have now

Common implementation questions

Do I need to store the full evidence content?

Yes, if you want third-party replay. The pack_hash is derived from the content, not a URL. If the content changes or the URL disappears, the hash no longer verifies. Either store the content verbatim in the evidence_ledger, or snapshot it at collection time and store the snapshot.

Can I use a language other than Python?

Yes. The TypeScript reference implementation is @aiep/verify in the genome-sdk repository at packages/verify/. It produces identical pack_hash values to the Python kernel on all 15 conformance vectors. The hashing rules are in CANON_SPEC.md — implement those rules and run the vectors to prove conformance.

What is a NegativeProofRecord?

When you have no evidence for a claim, produce a NegativeProofRecord rather than hallucinating. The negative_proof_hash primitive in the SDK (from aiep_genome.kernel import negative_proof_hash) creates a hash-committed record of absent evidence. Run the neg-001 and neg-002 vectors to see the expected values.

What is plausibility_status?

Only "plausible" passes CC-001. If your evidence is weak, record that honestly. The dissent mechanism exists to record the disagreement formally rather than suppress it.

How does the three-band execution model work?

AIEP defines three execution bands based on plausibility_status and gate_status:

Next steps

• Builders Programme — join the programme and list your integration
• GENOME SDK Reference — complete SDK documentation
• Canon & Primitives — the full list of hash primitives
• Certification & Registry — get listed as a certified AIEP publisher
• CONFORMANCE.md template — downstream conformance statement