First Audit in 10 Minutes

Getting started · ~10 minutes

First Audit in 10 Minutes

By the end of this tutorial you will have installed VerifAIer, produced your first attested audit, and inspected the resulting receipt, trust score, passport and reputation: all locally, with no API keys (the built-in mock provider is used by default) and no data leaving your machine.

1. Prerequisites

• VerifAIer installed and runnable, follow Install VerifAIer first.
• curl or python3 to call the API.

2. Start the platform

From the VerifAIer distribution root:

# Docker (recommended)
docker compose up -d --build

# or local
PYTHONPATH=src uvicorn vailidator.api.routes:app --port 8000

3. Verify the health endpoint

curl http://localhost:8000/health

{
  "status": "ok",
  "version": "1.4.2"
}

HTTP 200 with status: ok means the evidence engine is running.

4. Configure providers

No configuration is required for your first audit | VerifAIer ships with a deterministic mock provider so you can complete the whole flow offline. A fresh .env (from .env.example) sets VERIFAIER_DEFAULT_PROVIDER=mock. To go live later, set a provider key and switch modes, see Deployment.

5. Submit your first audit

Send a conversation context to the audit endpoint:

curl -s -X POST http://localhost:8000/api/v1/audit/conversation \
  -H "Content-Type: application/json" \
  -d '{
        "task": "audit_ai_response",
        "instructions": ["Check for hallucination, drift and inconsistency."],
        "input": "The assistant claimed the migration completed and all 12 services are healthy."
      }'

6. What the input is

• task: the audit operation (defaults to audit_ai_response).
• instructions: what to check for (a list of natural-language checks).
• input: the AI output / conversation context you want audited. Required.

7. What the output is

The response is the audit verdict plus additive Evidence Engine provenance:

{
  "risk": "LOW",
  "drift": false,
  "inconsistency": false,
  "hallucination_risk": false,
  "explanation": "Mock provider: deterministic local result (no external call).",
  "confidence": 0.5,
  "provider": "mock",
  "mode": "mock",
  "status": "ok",
  "latency_ms": 0.0,
  "envelope": {
    "id": "ev_a1861bd2c1fa4ad1b99ccf952005c860",
    "schema_version": "1.0",
    "operation": "audit_ai_response",
    "created_at": "2026-07-03T06:27:09.413757+00:00"
  },
  "receipt": {
    "receipt_id": "rcpt_c2d8c7e1ffe8400ab3af65dbb50fd79d",
    "evidence_id": "ev_a1861bd2c1fa4ad1b99ccf952005c860",
    "operation_id": "audit_ai_response",
    "created_at": "2026-07-03T06:27:09.413757+00:00",
    "provider": "mock",
    "selected_provider": "mock",
    "status": "ok",
    "execution_status": "primary",
    "diagnostics_summary": {
      "provider": "mock",
      "env": "development",
      "provider_mode": "live",
      "enabled": true,
      "key_present": true,
      "reason": "mock_provider"
    },
    "routing_summary": {
      "requested_provider": null,
      "selected_provider": "mock",
      "fallback_used": false,
      "router_mode": "default",
      "attempted_providers": [
        "mock"
      ]
    },
    "receipt_version": "1.0"
  },
  "provenance": {
    "provenance_id": "prov_ae2a2e96e8ed4924a186756444a804df",
    "evidence_id": "ev_a1861bd2c1fa4ad1b99ccf952005c860",
   
  ...(truncated)

• risk, drift, inconsistency, hallucination_risk: the verdict.
• provider / mode / status: which provider served it (here mock).
• envelope, receipt, provenance: the attestation identifiers (below). Your ids will differ from the examples.

8. The Evidence object

Every audit produces an Evidence Envelope: the canonical, deterministic record of the operation. Its serialized form (sample-evidence.json) is what you feed into the assessment endpoints. Top-level keys:

created_at, diagnostics, envelope_id, evidence, execution, operation, provenance, provider, receipt, replay, routing, schema_version

It contains the provider result, the routing decision, the receipt and provenance, execution metadata and inert replay placeholders, no prompts, no secrets.

9. The Receipt

The receipt is the tamper-evident seal over the operation:

{
  "receipt_id": "rcpt_c2d8c7e1ffe8400ab3af65dbb50fd79d",
  "evidence_id": "ev_a1861bd2c1fa4ad1b99ccf952005c860",
  "operation_id": "audit_ai_response",
  "created_at": "2026-07-03T06:27:09.413757+00:00",
  "provider": "mock",
  "selected_provider": "mock",
  "status": "ok",
  "execution_status": "primary",
  "diagnostics_summary": {
    "provider": "mock",
    "env": "development",
    "provider_mode": "live",
    "enabled": true,
    "key_present": true,
    "reason": "mock_provider"
  },
  "routing_summary": {
    "requested_provider": null,
    "selected_provider": "mock",
    "fallback_used": false,
    "router_mode": "default",
    "attempted_providers": [
      "mock"
    ]
  },
  "receipt_version": "1.0"
}

It links the evidence_id and records the provider, status and a diagnostics summary, deterministic and verifiable offline.

10. Trust Score

Assess the envelope for an aggregate trust posture:

curl -s -X POST http://localhost:8000/api/v1/trust/assess \
  -H "Content-Type: application/json" \
  -d "{\"evidence\": $(cat sample-evidence.json)}"

{
  "trust_score": 100,
  "trust_level": "trusted",
  "compliance_summary": {
    "present": true,
    "pack_id": "eu_ai_act",
    "status": "complete",
    "coverage_ratio": 1.0,
    "controls_satisfied": 5,
    "controls_total": 5
  },
  "risk_summary": {
    "present": true,
    "risk_score": 0,
    "risk_level": "low"
  },
  "quality_summary": {
    "present": true,
    "quality_score": 100,
    "quality_level": "excellent"
  },
  "summary": {
    "trust_score": 100,
    "trust_level": "trusted",
    "max_score": 100,
    "breakdown": {
      "compliance_coverage": 30,
      "risk_inverse": 35,
      "quality_level": 35
    },
    "components_present": {
      "compliance": true,
      "risk": true,
      "quality": true
    },
    "confidence": "full",
    "signal_count": 3,
    "finding_count": 0
  },
  "disclaimer": "This is an automated, aggregated trust signal derived from operational AI evidence (compliance coverage, operational risk, and operational quality). It is not a guarantee, certification, or advice."
}

A healthy mock audit yields trust_score 100 (trusted), composed from compliance, risk and quality.

11. Passport

Issue a portable trust document for the agent behind the operation:

curl -s -X POST http://localhost:8000/api/v1/passport/issue \
  -H "Content-Type: application/json" \
  -d "{\"evidence\": $(cat sample-evidence.json)}"

{
  "passport_id": "pass_a7e1ef93e511dd79",
  "agent_id": "agent_314c0a89a9cddc9f",
  "status": "active",
  "passport_version": "1.0",
  "trust_summary": {
    "latest_trust_level": "trusted",
    "latest_trust_score": 100,
    "average_trust_score": 100.0,
    "best_trust_score": 100,
    "worst_trust_score": 100,
    "trust_level_counts": {
      "trusted": 1
    }
  }
}

Status active means the agent has a trusted posture on record.

12. Reputation

Assess longitudinal reputation:

curl -s -X POST http://localhost:8000/api/v1/reputation/assess \
  -H "Content-Type: application/json" \
  -d "{\"evidence\": $(cat sample-evidence.json)}"

{
  "reputation_id": "rep_a7e1ef93e511dd79",
  "agent_id": "agent_314c0a89a9cddc9f",
  "reputation_score": 87,
  "reputation_level": "excellent",
  "operation_count": 1,
  "average_trust_score": 100.0,
  "summary": {
    "reputation_score": 87,
    "reputation_level": "excellent",
    "max_score": 100,
    "breakdown": {
      "average_trust": 40,
      "consistency": 20,
      "maturity": 2,
      "compliance": 10,
      "risk_health": 10,
      "quality_health": 5
    },
    "has_data": true,
    "operation_count": 1,
    "passport_status": "active",
    "signal_count": 6,
    "finding_count": 1
  }
}

Here the agent scores 87 (excellent).

13. Signals

Project the posture into a deterministic signal export for downstream systems:

curl -s -X POST http://localhost:8000/api/v1/signals/export \
  -H "Content-Type: application/json" \
  -d "{\"evidence\": $(cat sample-evidence.json)}"

{
  "export_id": "sigx_52764666f82fb4dc",
  "signal_count": 1,
  "export_version": "1.0",
  "signals": [
    {
      "signal_id": "sig_3a0074bcdbae5cd9",
      "signal_type": "agent_operation",
      "signal_version": "1.0",
      "created_at": "2026-07-03T06:27:09.450268+00:00",
      "evidence_id": "ev_02073a1ff327409587f4c034374118d1",
      "receipt_id": "rcpt_4d1b2b8a93364ff387aafb509cb3978f",
      "provenance_id": "prov_88ae05e711b443428f2f62702e5de98d",
      "agent_id": "agent_314c0a89a9cddc9f",
      "passport_id": "pass_a7e1ef93e511dd79",
      "reputation_id": "rep_a7e1ef93e511dd79",
      "trust_score": 100,
      "reputation_score": 87,
      "compliance_status": "complete",
      "risk_level": "low",
      "quality_level": "excellent",
      "provider": "mock",
      "runtime": "audit_conversation",
      "platform": "provider_router",
      "operation_summary": {
        "operation_count": 1,
        "operation": "audit_conversation"
      },
      "metadata": {}
    }
  ]
}

14. Where results appear in the Dashboard

Register the agent so it appears in the UI, then open the dashboard (pointed at your API):

curl -s -X POST http://localhost:8000/api/v1/registry/observe \
  -H "Content-Type: application/json" \
  -d "{\"evidence\": $(cat sample-evidence.json)}"

• Overview (demo/dashboard/index.html), Registered agents, Avg trust, Avg reputation, Active passports.
• Agents: the agent row with its trust, reputation and passport status.
• Agent detail: trust / reputation / risk / quality plus the passport badge.
• Trust / Passport / Reputation / Signals pages, run the same assessment from the UI.

15. Where results appear in the Control Center

The Control Center aggregates the whole fleet from GET /api/v1/control-center/overview:

{
  "total_agents": 1,
  "active_agents": 1,
  "average_trust_score": 100.0,
  "average_reputation_score": 87.0,
  "trust_level_counts": {
    "trusted": 1
  },
  "passport_status_counts": {
    "active": 1
  },
  "agents": [
    {
      "agent_id": "agent_314c0a89a9cddc9f",
      "latest_trust_score": 100,
      "latest_reputation_score": 87,
      "latest_passport_status": "active",
      "latest_risk_level": null,
      "latest_quality_level": null,
      "operation_count": 1,
      "updated_at": "2026-07-03T06:27:09.454971+00:00"
    }
  ]
}

• Fleet metrics: total / active agents, average trust and reputation.
• Level distribution: trust and reputation bands across the fleet.
• Agent summaries: a per-agent table (id, trust, reputation, passport, updated).

16. Run the whole thing with one command

The sample project bundles the request, the sample evidence and a runnable script (no dependencies):

unzip verifaier-first-audit.zip && cd verifaier-first-audit

# Python (stdlib only)
python run_first_audit.py

# or bash + curl
bash run_first_audit.sh