From bc0e7a36d5878e6a3e9f093cdf453caf2949ee81 Mon Sep 17 00:00:00 2001 From: "kapil.madan" <3740365+kmadan@users.noreply.github.com> Date: Thu, 14 May 2026 21:05:58 +0530 Subject: [PATCH] release(v0.7.3): hand-maintained README-pypi.md for proper PyPI rendering MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PyPI doesn't resolve relative image paths or cross-links against the source repo, so https://pypi.org/project/aicertify/ has been silently showing broken images (hero banner, diagram1, demo.gif) and broken links into examples/ and docs/. This release adds a hand-maintained README-pypi.md and points the `readme` field in pyproject.toml at it. The new file is a slightly- trimmed variant of README.md — same structure (banner → tagline → badges → diagram → quick start → demo gif → minimal Python → why → comparison table → OPA-users section → examples → see-the-output → GitHub pointers → license) — but with every image and cross-link rewritten to absolute `https://raw.githubusercontent.com/...` or `https://github.com/...` URLs. Trimmed sections vs the GitHub README: the language switcher (PyPI audience is en-only), the verbose How-It-Works/architecture diagram walkthrough (replaced with a single-paragraph OPA-users section), the long Regulatory Coverage list (replaced with the comparison table + a link to the full list), the CLI flag reference table (full help is one `aicertify --help` away), Status / Who-should-contribute (less PyPI-relevant). All trimmed content lives one click away on GitHub via the explicit "More on GitHub" pointer near the end. Verified locally with `readme_renderer[md]` (the actual library PyPI uses) — all image URLs resolve to https://raw.githubusercontent.com, all hrefs resolve to https://github.com or other absolute targets. The GitHub README.md is unchanged. Maintenance pattern: when updating Quick Start, the comparison table, or the examples list in README.md, update README-pypi.md in lockstep. CHANGELOG drift is the only thing to watch for. No code changes in this release. --- CHANGELOG.md | 6 ++ README-pypi.md | 184 ++++++++++++++++++++++++++++++++++++++++++ aicertify/__init__.py | 2 +- pyproject.toml | 10 ++- 4 files changed, 199 insertions(+), 3 deletions(-) create mode 100644 README-pypi.md diff --git a/CHANGELOG.md b/CHANGELOG.md index ab1d20d..8b4766d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.7.3] — 2026-05-14 + +### Fixed + +- **PyPI README rendering.** The PyPI project page previously showed broken images and broken `docs/` / `examples/` cross-links because PyPI doesn't resolve relative paths against the source repo. `pyproject.toml`'s `readme` field now points at a new **`README-pypi.md`** — a hand-maintained, slightly-trimmed variant of `README.md` with every image and cross-link rewritten to absolute `https://raw.githubusercontent.com/...` or `https://github.com/...` URLs. The hero banner, diagram1, `docs/demo.gif`, and every cross-link now render correctly on . The GitHub `README.md` is unchanged — keep both files in sync when updating Quick Start, comparison table, or examples list. + ## [0.7.2] — 2026-05-14 ### Changed diff --git a/README-pypi.md b/README-pypi.md new file mode 100644 index 0000000..61f0517 --- /dev/null +++ b/README-pypi.md @@ -0,0 +1,184 @@ +
+ + + AICertify — Compliance-as-code for AI systems + +
+ +

+ Audit your AI against the EU AI Act, NIST AI RMF, and 13 more frameworks — one contract, one command, one report. +

+ +

+ PyPI + CI + Stars + Python 3.12+ + Apache 2.0 + Built on OPA + 94 Rego Policies +

+ +

+ + + From AI app to audit-ready report: AI Application -> AICertify Contract -> OPA Policy Evaluation -> Compliance Report + +

+ +
+ +> 📦 **Full documentation, examples, contributing guide, translations (zh-CN / ja-JP / ko-KR / hi-IN), and 94 Rego policies** live in the [GitHub repository](https://github.com/Principled-Evolution/aicertify). + +Regulators are moving faster than your governance docs. The EU AI Act is in force. NIST AI RMF is the de-facto US standard. India, Brazil, and Singapore are next. `AICertify` lets you encode those obligations as executable [Open Policy Agent](https://www.openpolicyagent.org/) policies, run them against captured AI interactions, and produce audit-ready reports in PDF, Markdown, JSON, or HTML. + +It's the missing link between *"we have a responsible-AI policy"* and *"we can prove it."* + +**Use it when you need to:** + +- turn AI governance policies into executable checks +- produce audit-ready compliance evidence on every release +- evaluate AI interactions against named regulatory frameworks (EU AI Act, NIST AI RMF, FERPA, fair-lending, FAA/EASA aviation, …) +- generate Markdown, JSON, HTML, or PDF reports your auditor can read +- integrate AI compliance checks into CI/CD + +AICertify is part of the [Open Policy Agent ecosystem](https://www.openpolicyagent.org/ecosystem/entry/principled-evolution) — built on the same policy engine that powers Kubernetes admission, microservice authorisation, and infrastructure governance at scale. + +> ⭐ **If AICertify helps you, please star the [repo](https://github.com/Principled-Evolution/aicertify).** It helps AI governance and policy-as-code practitioners discover the project. + +--- + +## Quick Start + +```bash +# 1. Install AICertify (~3–5 min on first install; pulls langchain + transformers) +pip install aicertify + +# 2. Install the OPA binary, one-time (~80 MB) +curl -L https://openpolicyagent.org/downloads/latest/opa_linux_amd64 -o /usr/local/bin/opa && sudo chmod +x /usr/local/bin/opa + +# 3. Run the bundled demo — no contract file, no API keys, ~10 seconds +aicertify demo +``` + +`aicertify demo` loads a bundled sample contract, evaluates it against the EU AI Act policy set via OPA, and writes `aicertify_demo_report.md` to the current directory. Open the report — that's what your audit deliverable looks like. + +

+ aicertify demo recording — banner, spinners, evaluation progress, generated report path +

+ +For richer evaluations (LangFair fairness metrics, DeepEval content-safety scoring, PDF reports), see [`examples/quickstart.py`](https://github.com/Principled-Evolution/aicertify/blob/main/examples/quickstart.py) and the [forkable example bots](https://github.com/Principled-Evolution/aicertify/tree/main/examples) — each ships an `input_contract.json`, a `policy_config.yaml`, and a `run.py`. + +### Minimal Python usage + +```python +from aicertify import regulations, application + +# 1. Pick the regulations you want to certify against +regs = regulations.create("my_regulations") +regs.add("eu_ai_act") + +# 2. Wrap your AI app +app = application.create( + name="customer-support-bot", + model_name="gpt-4o", + model_version="2024-08-06", +) + +# 3. Feed it real interactions +app.add_interaction( + input_text="I want a refund for my order", + output_text="I can help with that. Could you share your order number?", +) + +# 4. Evaluate and get reports back +await app.evaluate(regulations=regs, report_format="pdf", output_dir="reports") +``` + +That's the whole loop. **Contract → interactions → evaluate → report.** + +--- + +## Why AICertify? + +Most AI governance programs live in PDFs, spreadsheets, and policy documents. They describe what *should* happen but do not prove what *did*. + +AICertify turns governance rules into executable policy checks. + +Instead of saying: + +> "Our chatbot follows our responsible AI policy." + +You can produce: + +> "Here is the captured interaction, the policy version, the OPA evaluation result, and the generated audit report." + +AICertify is for AI teams, governance teams, auditors, and platform engineers who need AI compliance evidence that can be **read, run, reviewed, and repeated**. + +See the full positioning in [docs/why-aicertify.md on GitHub](https://github.com/Principled-Evolution/aicertify/blob/main/docs/why-aicertify.md). + +--- + +## Compared with alternatives + +Most AI-governance tooling is either: + +- **A vendor SaaS** that locks your audit trail behind a login (Credo AI, Holistic AI), or +- **A research toolkit** focused on a single dimension — fairness metrics (Fairlearn, AI Fairness 360) or explainability (Microsoft RAI Toolbox). + +Neither produces the document a regulator actually asks for: *evidence that you tested this AI system against a named regulation, with reproducible policies and a dated report.* + +| | AICertify | Fairlearn / AIF360 | MS RAI Toolbox | Credo AI | +|---|---|---|---|---| +| Open source | ✅ Apache 2.0 | ✅ MIT | ✅ MIT | ❌ Closed | +| On-prem / air-gapped | ✅ | ✅ | ✅ | ❌ | +| Named regulatory frameworks | **EU AI Act, NIST RMF, Brazil AI Bill, India DPDP, +11 more** | ❌ (fairness only) | ❌ (toolkit) | ✅ | +| Policy-as-code (auditable, diff-able) | ✅ OPA / Rego | ❌ | ❌ | ❌ | +| Industry verticals out of the box | Aviation, Banking, Healthcare, Automotive, Education | ❌ | ❌ | Partial | +| Generates audit-ready reports | ✅ PDF / MD / JSON / HTML | ❌ | Partial | ✅ | +| Custom policies | ✅ Drop a `.rego` file | ❌ | N/A | ✅ (paid) | + +--- + +## For OPA / Rego users + +If you already use OPA, AICertify gives you the **AI-application context layer** OPA was missing. You bring your AI app; AICertify captures the interactions, feeds them through the OPA engine against AI-specific Rego policies sourced from [gopal](https://github.com/Principled-Evolution/gopal), and emits audit-ready evidence. + +The whole stack is policy-as-code — same workflow you already use for Kubernetes admission, microservice authorisation, and infrastructure governance. + +--- + +## Forkable examples + +Copy any of these and substitute your own contract: + +- **[customer-support-bot](https://github.com/Principled-Evolution/aicertify/tree/main/examples/customer-support-bot)** — limited-risk EU AI Act + global cross-cutting policies +- **[healthcare-triage-bot](https://github.com/Principled-Evolution/aicertify/tree/main/examples/healthcare-triage-bot)** — EU AI Act high-risk Annex III(5)(a) + gopal healthcare patient-safety policies +- **[hiring-screening-bot](https://github.com/Principled-Evolution/aicertify/tree/main/examples/hiring-screening-bot)** — EU AI Act high-risk Annex III(4) + fair-lending proxy + FRIA metadata pattern + +Each example ships an `input_contract.json`, `policy_config.yaml`, `sample_interactions.json`, an `expected_report.md`, and a `run.py` you can execute directly. + +--- + +## See the output + +You don't have to install anything to see what AICertify produces. A sample pre-generated PDF is in the repo: + +- **[demo-report-eu-ai-act.pdf](https://github.com/Principled-Evolution/aicertify/blob/main/docs/demo-report-eu-ai-act.pdf)** — a customer-support agent evaluated against the EU AI Act +- **[examples/outputs/](https://github.com/Principled-Evolution/aicertify/tree/main/examples/outputs)** — canonical full outputs for EU AI Act, loan evaluation, and medical diagnosis + +--- + +## More on GitHub + +- Full [README with diagrams](https://github.com/Principled-Evolution/aicertify) (English / [简体中文](https://github.com/Principled-Evolution/aicertify/blob/main/README.zh-CN.md) / [日本語](https://github.com/Principled-Evolution/aicertify/blob/main/README.ja-JP.md) / [한국어](https://github.com/Principled-Evolution/aicertify/blob/main/README.ko-KR.md) / [हिन्दी](https://github.com/Principled-Evolution/aicertify/blob/main/README.hi-IN.md)) +- [CONTRIBUTING.md](https://github.com/Principled-Evolution/aicertify/blob/main/CONTRIBUTING.md) — how to add policies, examples, or framework coverage +- [SECURITY.md](https://github.com/Principled-Evolution/aicertify/blob/main/SECURITY.md) — private vulnerability disclosure +- [CHANGELOG.md](https://github.com/Principled-Evolution/aicertify/blob/main/CHANGELOG.md) — what changed in each release +- [gopal](https://github.com/Principled-Evolution/gopal) — the upstream OPA/Rego policy library AICertify uses + +--- + +## License + +Apache 2.0 — see the [LICENSE file](https://github.com/Principled-Evolution/aicertify/blob/main/LICENSE). diff --git a/aicertify/__init__.py b/aicertify/__init__.py index b693986..073cc36 100644 --- a/aicertify/__init__.py +++ b/aicertify/__init__.py @@ -6,7 +6,7 @@ """ # Version information -__version__ = "0.7.2" +__version__ = "0.7.3" # Direct imports for developer convenience try: diff --git a/pyproject.toml b/pyproject.toml index 83c3035..0c308e2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,13 +1,19 @@ [project] name = "aicertify" -version = "0.7.2" +version = "0.7.3" description = "Compliance-as-code for AI systems. Audit your AI against the EU AI Act, NIST AI RMF, and 13+ regulatory frameworks using Open Policy Agent (OPA) — and produce audit-ready PDF, Markdown, JSON, or HTML reports." authors = [ {name = "Kapil Madan", email = "kapil.madan@gmail.com"}, {name = "Principled Evolution", email = "info@principledevolution.ai"}, ] license = "Apache-2.0" -readme = "README.md" +# README-pypi.md is the hand-maintained PyPI-facing variant: same shape as +# README.md but with all relative image / link paths rewritten to absolute +# https://raw.githubusercontent.com / https://github.com URLs so PyPI renders +# the banner, diagram, demo GIF, and cross-links correctly. See README-pypi.md +# top-matter — keep both files in sync when updating Quick Start, comparison +# table, or examples list. +readme = "README-pypi.md" requires-python = ">=3.12,<3.13" keywords = [ "ai-governance",