Docs

Contributing

Local development

Concise path from clone to a working audit service, documentation gates, and tests. For product semantics, stay with the canonical guides linked at the end.

Prerequisites#

  • Git, Docker with Compose v2, Python 3.10+, Rust toolchain (cargo).
  • Ports 8088 (audit HTTP) and 5432 (Postgres) available locally.

1. Clone#

git clone https://github.com/MonikaDvorackova/aigov-compliance-engine.git
cd aigov-compliance-engine

2. Python tooling (venv + editable install)#

The CLI and tests live under python/. Create a venv inside python/ (matches Makefile targets that run cd python && . .venv/bin/activate):

cd python
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
python -m pip install -U pip
python -m pip install -e ".[dev]"
cd ..

If pytest fails at import time with ModuleNotFoundError (for example nacl), install the editable package in that venv as above; PyNaCl is declared in python/pyproject.toml.

3. Audit service via Docker Compose#

From the repository root:

docker compose up -d --build

Health (liveness; available only after the service has bound HTTP):

curl -fsS http://127.0.0.1:8088/health

Operational readiness (Postgres + migrations + writable ledger expectations used by the service):

curl -fsS http://127.0.0.1:8088/ready

Root docker-compose.yml sets GOVAI_API_KEYS for the container (see file for the dev value). Use the same bearer token when calling authenticated routes from your shell.

4. Optional root .env#

Makefile does -include .env. Copy .env.example to .env for local overrides only; never commit secrets.

5. Documentation report gate#

From the repository root (uses system python3 and scripts/gate_reports.py):

python3 scripts/gate_reports.py
make gate

These targets use stdlib-only Python under scripts/ (no network, no writes):

make oss-health                      # required contributor/OSS files exist (exits 1 if missing)
make oss-metrics                     # Markdown / examples / test counts (Markdown table to stdout)
make docs-links                      # README + docs/**/*.md relative links (warn-only; exits 0 if broken)
make docs-links-strict               # same as docs-links with --strict (exits 1 on broken local links)
make security-trust                  # structured security/trust diagnostics (deterministic JSON: add --json)
make trust-manifest                  # validate docs/trust/trust-manifest.json (deterministic JSON: add --json)
make trust-chain-check               # validate trust/*.json + examples/trust (stdlib; add --json)
make immutable-trust-check           # trust-chain-check + gate
make commercial-readiness            # commercial readiness diagnostics
make commercial-readiness-check      # commercial-readiness + gate
make oss-diagnostics                 # aggregated JSON: layout, health, strict links, docs/reports vs origin/staging when ref exists
make enterprise-readiness-check      # security-trust + trust-manifest + commercial-readiness + oss-diagnostics

Machine-readable JSON (automation / CI mirrors):

python3 scripts/repo_health_check.py --json
python3 scripts/security_trust_check.py --json
python3 scripts/validate_trust_manifest.py --json
python3 scripts/trust_chain_check.py --json
python3 scripts/pilot_execution_check.py --json
python3 scripts/validate_pilot_manifest.py --json
python3 scripts/customer_operations_check.py --json
python3 scripts/validate_customer_operations_manifest.py --json
python3 scripts/partner_ecosystem_check.py --json
python3 scripts/validate_partner_ecosystem_manifest.py --json
python3 scripts/generate_partner_certification_package.py --manifest docs/partners/partner-ecosystem-manifest.json
python3 scripts/regulatory_evidence_check.py --json

CI (.github/workflows/oss-developer-experience.yml) uploads structured diagnostics as the oss-check-json artifact after make enterprise-readiness-check. Browse the catalog interactively:

CI artifact explorer

70 files uploaded as oss-check-json after make enterprise-readiness-check. Search or expand a domain to inspect outputs.

oss-check-json

Repository health

Required OSS files, layout checks, and contributor onboarding paths.

1
  • repo-health.jsonOSS health gate outputjson

Trust and security

Security-trust diagnostics and machine-readable trust manifest validation.

4
  • security-trust.jsonStructured security/trust checksjson
  • trust-manifest.jsonPublished trust manifest snapshotjson
  • trust-manifest-validation.jsonManifest schema validationjson
  • trust-chain.jsonImmutable trust chain validationjson

Documentation quality

Strict link checks and aggregated OSS diagnostics.

2
  • docs-links.jsonBroken local link reportjson
  • oss-diagnostics.jsonAggregated OSS diagnostics JSONjson

Commercial readiness

Billing, pricing, deployment, and enterprise onboarding path checks.

1
  • commercial-readiness.jsonCommercial platform readinessjson

Pilot execution

Sales and pilot package validation for enterprise evaluations.

2
  • pilot-execution.jsonPilot execution diagnosticsjson
  • pilot-manifest-validation.jsonPilot manifest validationjson

Operations

Customer operations manifests and production readiness checklist.

3
  • customer-operations.jsonCustomer operations diagnosticsjson
  • customer-operations-manifest-validation.jsonOperations manifest validationjson
  • production-readiness-checklist.mdGenerated production readiness checklistmarkdown

Partner ecosystem

Partner program manifests and certification package smoke output.

3
  • partner-ecosystem.jsonPartner ecosystem diagnosticsjson
  • partner-ecosystem-manifest-validation.jsonPartner manifest validationjson
  • partner-certification-package.mdCertification package generator outputmarkdown

Regulatory evidence

EU AI Act obligations, regulatory manifests, and export reports.

4
  • regulatory-evidence.jsonRegulatory evidence diagnosticsjson
  • regulatory-manifest-validation.jsonRegulatory manifest validationjson
  • ai-act-obligations-validation.jsonAI Act obligations validationjson
  • regulatory-evidence-export.mdRegulatory evidence Markdown exportmarkdown

Observability

Operational snapshots, health scores, and intelligence reports.

5
  • observability.jsonObservability diagnosticsjson
  • observability-manifest-validation.jsonObservability manifest validationjson
  • operational-snapshot-validation.jsonOperational snapshot validationjson
  • operational-health-score.jsonOperational health scorejson
  • operational-intelligence-report.mdOperational intelligence reportmarkdown

Runtime safety

Runtime guardrails, snapshots, scores, and safety reports.

5
  • runtime-safety.jsonRuntime safety diagnosticsjson
  • runtime-safety-manifest-validation.jsonRuntime safety manifest validationjson
  • runtime-safety-snapshot-validation.jsonRuntime safety snapshot validationjson
  • runtime-safety-score.jsonRuntime safety scorejson
  • runtime-safety-report.mdRuntime safety reportmarkdown

Evidence quality

Dataset provenance, evidence quality scoring, and governance reports.

5
  • evidence-quality.jsonEvidence quality diagnosticsjson
  • evidence-quality-manifest-validation.jsonEvidence quality manifest validationjson
  • dataset-provenance-snapshot-validation.jsonDataset provenance snapshot validationjson
  • evidence-quality-score.jsonEvidence quality scorejson
  • dataset-governance-report.mdDataset governance reportmarkdown

Policy intelligence

Governance control snapshots, coverage scores, and control reports.

5
  • policy-intelligence.jsonPolicy intelligence diagnosticsjson
  • policy-intelligence-manifest-validation.jsonPolicy intelligence manifest validationjson
  • governance-control-snapshot-validation.jsonGovernance control snapshot validationjson
  • policy-coverage-score.jsonPolicy coverage scorejson
  • governance-control-report.mdGovernance control reportmarkdown

Model risk

Model evaluation snapshots, risk scores, and assurance reports.

5
  • model-risk.jsonModel risk diagnosticsjson
  • model-risk-manifest-validation.jsonModel risk manifest validationjson
  • model-evaluation-snapshot-validation.jsonModel evaluation snapshot validationjson
  • model-risk-score.jsonModel risk scorejson
  • model-assurance-report.mdModel assurance reportmarkdown

Agent governance

Agent delegation snapshots, governance scores, and agent reports.

5
  • agent-governance.jsonAgent governance diagnosticsjson
  • agent-governance-manifest-validation.jsonAgent governance manifest validationjson
  • agent-delegation-snapshot-validation.jsonAgent delegation snapshot validationjson
  • agent-governance-score.jsonAgent governance scorejson
  • agent-governance-report.mdAgent governance reportmarkdown

Marketplace

Extension packages, policy packs, and marketplace listings.

8
  • marketplace.jsonMarketplace diagnosticsjson
  • marketplace-manifest-validation.jsonMarketplace manifest validationjson
  • policy-pack-marketplace-manifest-validation.jsonPolicy pack marketplace manifestjson
  • policy-pack-eu-ai-act-basic-validation.jsonEU AI Act basic pack validationjson
  • policy-pack-internal-model-risk-validation.jsonInternal model risk pack validationjson
  • policy-pack-vendor-evaluation-validation.jsonVendor evaluation pack validationjson
  • extension-package-validation.jsonExtension package validationjson
  • marketplace-listing.mdMarketplace listing outputmarkdown

Customer analytics

Customer health scoring and executive business review exports.

4
  • customer-analytics.jsonCustomer analytics diagnosticsjson
  • customer-analytics-manifest-validation.jsonCustomer analytics manifest validationjson
  • customer-health-score.jsonCustomer health scorejson
  • executive-business-review.mdExecutive business review reportmarkdown

Developer integrations

Automation packs, integration manifests, and summary reports.

4
  • developer-integrations.jsonDeveloper integrations diagnosticsjson
  • developer-integrations-manifest-validation.jsonIntegrations manifest validationjson
  • automation-pack-validation.jsonAutomation pack validationjson
  • automation-pack-summary.mdAutomation pack summarymarkdown

Release readiness

Changelog validation, release manifests, and readiness reports.

4
  • release-manifest-validation.jsonRelease manifest validationjson
  • changelog-validation.jsonChangelog validationjson
  • release-readiness-report.jsonRelease readiness aggregate reportjson
  • release-notes-template.mdRelease notes templatemarkdown

Enterprise security review example (no audit service): bash examples/security-review/run-security-review-check.sh (from repo root).

Fail-closed demo (requires running audit stack + python/.venv with govai):

export GOVAI_AUDIT_BASE_URL=http://127.0.0.1:8088
export GOVAI_API_KEY=test-key   # must match root docker-compose.yml
make fail-closed-demo            # scripts/run_fail_closed_demo.py — BLOCKED contract, JSON on stdout

Read-only vs fail-closed semantics and exit codes: examples/local-demo/CONTRACT.md. Public docs preview: run the dashboard/ dev server (cd dashboard && npm ci && npm run dev) and open /docs / /help (content is read from ../docs/ at build/runtime).

Local audit read-only demo (optional)#

With the audit API already listening (for example after docker compose up -d --build):

make local-demo       # python3 scripts/run_local_demo.py — GET /health, /ready, /status only
make local-demo-curl  # bash examples/local-demo/curl-health-ready.sh

These targets do not submit evidence, do not require API keys, and do not mutate the ledger. They are not part of make oss-diagnostics because a running service is not guaranteed in CI sandboxes.

Public documentation (dashboard)#

Canonical long-form documentation stays in docs/. The production-shaped reader UI is the dashboard/ App Router (app/docs, app/help). Canonical prose is not duplicated in a second Mintlify tree in this repository.

6. Rust tests#

cargo test --manifest-path rust/Cargo.toml

7. Python tests#

With the python/.venv activated:

cd python
python -m pytest

If you run python3 -m pytest python/tests from the repo root without the venv, collection may fail on missing optional deps — use the venv from step 2.

8. Optional: audit binary in background (Makefile)#

make audit_bg      # builds and runs rust/src binary; waits for GET /ready
make audit_stop    # when finished

Canonical references#

← Back to home