SYEN Audit Integration Guide

1. OVERVIEW

SYEN Audit is a cryptographic audit ledger for AI decision systems. It records every AI action, human approval, and automated decision as a tamper-evident entry that is independently verifiable by auditors, regulators, and courts.

This guide covers installation, authentication, event ingestion, chain verification, and proof retrieval. A complete integration for a new event type takes under 30 minutes.

2. PREREQUISITES

• Python 3.10 or higher
• A running SYEN Audit deployment via AWS or Azure Marketplace
• Your tenant credentials provided at subscription activation
• Network access to your SYEN Audit endpoint

3. INSTALLATION

pip install syen-audit-client

4. AUTHENTICATION

Initialize the client with your deployment details. Token management is handled automatically.

from syen_audit import SYENAuditClient, EventClass

client = SYENAuditClient(
    base_url="https://your-syen-audit-endpoint.com",
    tenant_id="your-tenant-id",
    agent_id="your-agent-name",
    agent_code_hash="sha256-hash-of-your-agent-code"
)

# Establish session
await client.attest()

5. INGESTING EVENTS

Every AI action, decision, or system event is recorded with a single ingest() call. The event_class determines the category. event_type is a free-form string scoped within the class.

Basic Event

receipt = await client.ingest(
    event_class=EventClass.EXECUTION,
    event_type="credit.decision.made",
    payload={
        "applicant_id": "app-991",
        "decision": "APPROVED",
        "score": 740
    }
)

print(receipt.event_id)          # Unique event identifier
print(receipt.sequence_counter)  # Position in the chain

Event with Human Decision Surface

When a human reviewed and approved a decision, include the decision_surface to record what was shown, when, and what they decided.

receipt = await client.ingest(
    event_class=EventClass.EXECUTION,
    event_type="credit.decision.made",
    payload={"applicant_id": "app-991", "decision": "APPROVED"},
    decision_surface={
        "explainability_artifact_hash": "sha256-of-artifact-shown",
        "human_decision": "APPROVE",
        "presentation_timestamp": "2026-03-20T14:00:00Z",
        "signoff_timestamp": "2026-03-20T14:00:03Z",
        "decision_complexity_tier": 2
    }
)

# True if signoff was under the threshold for the complexity tier
print(receipt.velocity_flag_triggered)

Event with Extended Context

Pass optional context fields to capture AI model provenance, infrastructure details, and compliance gate results.

receipt = await client.ingest(
    event_class=EventClass.EXECUTION,
    event_type="model.inference",
    payload={"output": "APPROVED"},
    context={
        "trace_id": "abc-123",
        "model_version": "risk-engine-v2.1.0",
        "compliance_gate_result": "APPROVED",
        "pii_detected": False,
        "cloud_provider": "aws",
        "cloud_region": "us-east-1"
    }
)

6. EVENT CLASSES

SYEN Audit supports eleven event classes covering the full lifecycle of an AI-assisted workflow. EXECUTION and OUTCOME are required for initial integration.

7. VERIFYING THE CHAIN

The verify() call confirms the chain has not been tampered with. Run this after any bulk operation or on a schedule to confirm ongoing integrity.

result = await client.verify(
    stream_id="your-tenant:prod-us-east-1:credit-decisions"
)

if result.verified:
    print(f"Chain verified: {result.checked_count} events")
else:
    print(f"Integrity failure detected at sequence {result.first_failure_sequence}")

8. RETRIEVING PROOF

For any event, retrieve the full non-repudiable proof package. This includes cryptographic signatures, chain linkage, and the human decision surface if present. Payload data is never returned.

proof = await client.get_proof(receipt.event_id)

# Proof is available for independent verification
# Contact sales@syensystems.com for auditor verification documentation

9. EXTERNAL TIMESTAMP ANCHORING

Every day at 00:01 UTC, SYEN Audit anchors the chain to an external FIPS-compliant trusted timestamp authority. The anchor record is retrievable via the API and independently verifiable by any authorized auditor.

anchor = await client.get_anchor(date="2026-03-20")

print(anchor.anchor_status)      # complete
print(anchor.anchor_created_at)

# Independent verification documentation available to
# Enterprise and Federal customers on request

10. API REFERENCE

All endpoints require a Bearer token from POST /api/v1/attest except GET /api/v1/health.

11. DECISION COMPLEXITY TIERS

When a human review is recorded, the velocity flag fires if the signoff was faster than the threshold for the tier. The event is always recorded regardless of the flag.

12. PRODUCTION DEPLOYMENT

SYEN Audit deploys on Kubernetes via Helm chart. Production deployment documentation including infrastructure requirements, KMS configuration, and security hardening guidelines is provided to customers during technical onboarding.

Contact sales@syensystems.com to begin the onboarding process. Enterprise and Federal customers receive dedicated deployment assistance.