Skip to content

poc-pack-financial-quickstart.md

Latest commit

 

History

History
200 lines (132 loc) · 6.08 KB

poc-pack-financial-quickstart.md

File metadata and controls

200 lines (132 loc) · 6.08 KB
Raw

Financial PoC Pack (1-day quickstart, EN)

Purpose

This quickstart turns the AML/KYC beachhead from "docs" into a pilot-ready package with operator checkpoints, evaluator criteria, and evidence handoff.

What this package proves in implemented scope:

  1. Fail-closed governance behavior in /v1/decide.
  2. Expected semantics diffing against fixture baselines.
  3. Quantitative pass/fail/warning summary for pilot go/no-go.
  4. Evidence-readiness handoff path toward external review bundle generation.

Who this guide is for

  • Customer-side evaluator: confirm AML/KYC governance value quickly.
  • Operator: run and interpret results without hidden assumptions.
  • Internal sponsor: approve pilot readiness with explicit boundaries.

Scope (single beachhead)

This package is intentionally constrained to one beachhead:

  • Beachhead domain: aml_kyc
  • Anchor template: aml_kyc_high_risk_country_wire_manual_review

Representative AML/KYC contracts covered by this package:

  • sanctions partial match must not become proceed
  • source of funds missing must not become APPROVE
  • policy definition missing must route to POLICY_DEFINITION_REQUIRED family
  • sufficient evidence low-risk path may route to proceed/APPROVE family
  • secure/prod controls missing in secure posture must fail-closed to block

Reference semantics and taxonomy:

Pilot package artifacts

1) Pilot checklist

2) Operator runbook

3) Canned synthetic sample cases

  • veritas_os/sample_data/governance/aml_kyc_pilot_cases.json

4) Deterministic runnable scenario fixture (bind/compliance output)

  • Runner: scripts/run_aml_kyc_poc_fixture.py
  • Fixture: veritas_os/sample_data/governance/aml_kyc_poc_pack/scenario_high_risk_manual_review.json
  • Expected output: veritas_os/sample_data/governance/aml_kyc_poc_pack/expected_high_risk_manual_review_output.json

5) Expected evidence bundle examples

  • veritas_os/sample_data/governance/aml_kyc_expected_evidence_bundle_examples.json

6) Red-team / failure scenarios

  • veritas_os/sample_data/governance/aml_kyc_failure_scenarios.json

7) Acceptance criteria summary

8) Customer handoff path

9) Security / privacy boundaries

Inputs and runner

  • Pilot fixture: veritas_os/sample_data/governance/aml_kyc_pilot_cases.json
  • Runner: scripts/run_financial_poc.py
  • Runtime module: veritas_os/scripts/financial_poc_runner.py

1-day pilot quickstart (operator path)

Step 0 — Prepare environment (30-60 min)

  1. Start VERITAS OS (Docker Compose recommended from repository root).
  2. Confirm backend health:
curl -s http://localhost:8000/health
  1. Confirm pilot fixture exists:
test -f veritas_os/sample_data/governance/aml_kyc_pilot_cases.json && echo "fixture_ok"

Step 1 — Dry-run baseline (15 min)

python scripts/run_financial_poc.py \
  --input veritas_os/sample_data/governance/aml_kyc_pilot_cases.json \
  --dry-run \
  --output-json veritas_os/scripts/logs/aml_kyc_pilot_dry_run_report.json

Step 1b — Deterministic governance-output check (10 min)

Run one executable AML/KYC fixture and verify expected governance outcome, bind result, and compliance-oriented output:

python scripts/run_aml_kyc_poc_fixture.py \
  --input veritas_os/sample_data/governance/aml_kyc_poc_pack/scenario_high_risk_manual_review.json \
  --verify-expected veritas_os/sample_data/governance/aml_kyc_poc_pack/expected_high_risk_manual_review_output.json \
  --output-json veritas_os/scripts/logs/aml_kyc_poc_fixture_output.json

Expected fixture behavior:

  • governance_outcome.gate_decision = human_review_required
  • bind_result.admissible = false (bind-boundary hold path)
  • compliance_view.status = conformant for synthetic expected evidence coverage

Step 2 — Live governance run (30-60 min)

VERITAS_API_KEY=demo-key \
python scripts/run_financial_poc.py \
  --input veritas_os/sample_data/governance/aml_kyc_pilot_cases.json \
  --api-url http://localhost:8000/v1/decide \
  --required-evidence-mode strict \
  --output-json veritas_os/scripts/logs/aml_kyc_pilot_live_report.json

Step 3 — Acceptance checkpoint (30 min)

Validate minimum pilot sign-off:

  • summary.counts.warning = 0
  • summary.counts.fail = 0
  • summary.pass_rate >= 0.90
  • summary.evaluated >= 5
  • anchor case pilot_aml_kyc_anchor_high_risk_country = pass

Step 4 — Evidence handoff checkpoint (30 min)

  1. Review handoff flow: AML/KYC Customer Handoff Path
  2. Review external bundle contract: External Audit Readiness
  3. Share synthetic-only artifacts with acceptance summary.

Operator-facing output interpretation

  • summary.outcome:
    • pass: all evaluated cases matched expected semantics.
    • warning: runtime instability or bounded warning state exists.
    • fail: one or more required semantics diverged from baseline.
  • mismatch_overview: concise triage view for non-pass cases.
  • required_evidence_runtime_warnings: taxonomy/profile drift signals that may reduce audit confidence.

Operator rule of thumb:

  • Do not treat pass rate alone as sufficient when warnings remain.
  • Treat unexpected proceed/APPROVE in ambiguity cases as blocker-level.

Security warnings

  • Do not send production PII or account identifiers in pilot payloads.
  • Avoid exposing API keys in shell history or logs.
  • Keep HTTP endpoints limited to localhost rehearsal environments.
  • This package is governance routing + evidence posture only, not legal advice.