Docs + marketing overhaul (security fixes already merged into main via #33/#35/#37/#39)#38
Merged
Merged
Conversation
…lities - Update transformers to >=4.50.0 (fixes CVE-2025-1194, CVE-2025-2099) - Update setuptools to >=78.1.1 (fixes CVE-2025-47273) - Regenerate poetry.lock with updated dependencies
…ty vulnerabilities
Prinevo
previously approved these changes
Jun 17, 2025
Restructure the README to read like a product page:
- Centered HTML hero with logo, tagline ("Compliance-as-code for AI
systems"), and a value-prop subtitle.
- Ordered 9-badge wall (CI, Stars, Version, Python, Apache 2.0, Built on
OPA, Policies-from-gopal, Beta, PRs Welcome).
- Language-switcher row anchoring four upcoming translations.
- Five embedded marketing diagrams (PNG, each <140 KB), generated by a
reproducible matplotlib script under diagrams/generate_diagrams.py:
1. End-to-end flow (AI app -> contract -> OPA eval -> report)
2. Architecture pipeline (evaluators -> OPA -> report generator)
3. Regulatory coverage grid (94 policies across 15+ frameworks)
4. Comparison vs Fairlearn / AIF360 / MS RAI / Credo AI
5. Audit-ready report anatomy
- Comparison table differentiating AICertify against the four named
alternatives on open-source, on-prem, policy-as-code, named regs,
industry verticals, audit-ready reports, and custom policies.
- Regulatory coverage section enumerating every framework with its
policy count and the gopal source of truth.
- Honest status section: production-ready frameworks vs work-in-progress.
The README now leads with the user's pain (regulators move faster than
governance docs), shows the deliverable (an audit-ready PDF), then
explains the mechanism. Quickstart fits in four shell lines.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Full README translations for four large developer markets: - README.zh-CN.md — Simplified Chinese (mainland) - README.ja-JP.md — Japanese (technical です/ます register) - README.ko-KR.md — Korean (-습니다/-입니다 formal) - README.hi-IN.md — Hindi (Devanagari with selective Latin retention for technical terms that read awkwardly when transliterated) Each translation: - Mirrors the English README structure exactly (headings, tables, code blocks, image refs, badges all preserved). - Includes the language switcher with the current language rendered as plain <strong> text and the others as anchor links. - Keeps regulation names (EU AI Act, NIST AI RMF, FERPA, COPPA, FAA Part 107, EASA SORA, RTCA DO-365/366) and product names (Fairlearn, AIF360, MS RAI Toolbox, Credo AI) verbatim — they are recognized internationally. - Uses consistent translated terminology for compliance, policy, audit, framework, evaluation, and human oversight. Together with the English README, AICertify is now discoverable in five languages covering ~15M+ developers outside of native-English markets. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two operational instruction files for AI coding assistants working in this repository (Claude Code, Cursor, Codex, Windsurf, Gemini CLI, Copilot, and any future agent that respects these conventions). AGENTS.md is the canonical guide: - What the project is (Python framework around OPA + gopal). - Repository layout with the role of each subdirectory. - Useful commands (install, quickstart, CLI, tests, lint). - Conventions (Python 3.12 only, line length 88, Pydantic v2, OPA policies are vendored from gopal upstream and should be edited there). - What NOT to do (don't pin deps aggressively, don't break the public API surface, don't introduce 3.13-only syntax, don't replace OPA). - A note on the author's preference for surgical changes. CLAUDE.md inherits from AGENTS.md and adds Claude Code-specific notes: fast-orientation paths into the codebase, TodoWrite usage, a pointer to the skills/ directory (added in a follow-up commit), and what NOT to claim about the project (no MCP server shipped yet). Together these reduce time-to-first-useful-edit for any AI agent opening the repo cold. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Ships four installable Claude Code skills under skills/. Each subfolder
contains a SKILL.md with YAML frontmatter; users register them with:
mkdir -p ~/.claude/skills && cp -r skills/* ~/.claude/skills/
Skills:
- /run-compliance-check
Runs the canonical end-to-end quickstart (sample contract through
the EU AI Act policy set), locates the generated report, summarizes
pass/fail, and surfaces failure stack traces with the most likely
fix when the run errors.
- /evaluate-contract <contract.json> <framework> [report-format]
Validates the user-supplied contract, resolves the framework path
under aicertify/opa_policies/, runs the CLI, summarizes the headline
result, and surfaces the top failing rules with their deny[msg]
strings.
- /explain-regulation <framework>
Walks every .rego in the framework directory, extracts METADATA,
translates the allow conditions into plain English, and produces an
auditor-readable coverage summary — including explicit "placeholder"
flags for stub policies.
- /draft-policy <domain> <framework> <policy_name> [--upstream]
Scaffolds a new Rego policy + test sibling matching the project's
conventions (package path mirrors directory, METADATA block, default
deny, helper_functions.reporting integration). Defaults to writing
upstream into gopal where it should live.
Lowers first-use friction: a Claude Code user clones the repo, registers
the skills, and gets compliance-aware slash commands immediately.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Begin tracking notable changes in the standard Keep-a-Changelog 1.1.0 format, with an explicit Semver commitment. The initial file covers: - An [Unreleased] section capturing this docs/marketing overhaul: the hero rewrite, 5 generated diagrams, AGENTS.md + CLAUDE.md, the Claude Code skills directory, the comparison table, and the diagram generator script. - A [0.7.0] section reconstructing the visible v0.7 milestones from the recent git history: ReportLab-based reporting, the quickstart, the pluggable evaluator classes, the gopal submodule migration, security fixes (protobuf 5.29.5, pycares 4.9.0, transformers, setuptools), and the auto-labeling workflow fix. Future releases should append [X.Y.Z] - YYYY-MM-DD sections. The changelog also serves as crawler-visible signal of project velocity for anyone evaluating maintenance health. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Make pyproject.toml ready for "pip install aicertify" once we cut a
release to PyPI. Specifically:
- Fix the malformed license expression. The previous value was
license = {text = "\"Apache-2.0\""}
which embeds escaped quotes inside the license string. Replaced with
the SPDX form: license = "Apache-2.0".
- Add 16 PyPI keywords — these power package search ranking:
ai-governance, ai-compliance, ai-act, eu-ai-act, nist-ai-rmf,
responsible-ai, open-policy-agent, opa, rego, regulatory-compliance,
ai-audit, ai-safety, fairness, policy-as-code, ai-evaluation,
ai-certification.
- Add 13 PyPI classifiers including the audience hints (Developers,
Information Technology, Legal Industry, Science/Research) and topic
classifications (Artificial Intelligence, Security, Quality Assurance,
Testing). These show up as the package's PyPI taxonomy.
- Add a [project.urls] block (Homepage, Repository, Documentation,
Issues, Changelog, and a cross-link to the gopal policy library).
- Install a real console-script entry point under [project.scripts]:
aicertify = "aicertify.cli:main"
Previously users had to invoke "python -m aicertify.cli" — this gives
them the standard "aicertify ..." command after install.
- Remove the duplicate, out-of-sync [tool.poetry] block that still had
version 0.1.0 and a minimal subset of dependencies; Poetry 2.x reads
the canonical [project] section directly. The remaining [tool.poetry]
block only carries Poetry-specific config (packages, group.dev).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
docs/INDEX.md provides a single navigation hub for the documentation surface, organized along the Diátaxis quadrants: - Tutorials — quickstart, sample contract, examples README - How-to guides — the four Claude Code skills, report-format howto - Reference — Python API, CLI flags, regulatory coverage table, pyproject.toml, CHANGELOG - Explanation — PROJECT_OVERVIEW.md, AGENTS.md, "why policy-as-code?" Plus a community section linking CONTRIBUTING, CODE_OF_CONDUCT, issues, and the sister gopal repo. Nothing is moved or renamed — this is purely an additive index pointing into existing files. The README remains the primary entry point; INDEX serves users who land here after following a "docs/" link. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
kmadan
changed the title
github-actions
Bot
added
📝 documentation
The PyPI-prep commit removed the duplicate, out-of-sync [tool.poetry] dependencies block in favor of the canonical [project] section. Poetry sees that as a "significant change" relative to the on-disk lockfile and refuses to install until the lockfile is regenerated. Regenerating with poetry 2.0.1 (poetry 2.1.x crashes on Python 3.12.3 due to a tarfile.ALLOW_MISSING gap unrelated to this PR). All security-relevant pins are preserved: - protobuf 5.29.5 - pycares 4.9.0 - urllib3 2.5.0 - transformers 4.50.3 - setuptools >= 78.1.1 Diff is ~70 lines of metadata churn (hash field, etc.) with no version changes to any dependency. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
kmadan
added a commit
that referenced
this pull request
May 14, 2026
…#33/#35/#37/#39) (#38) * fixes for security alerts * fix: update transformers and setuptools to resolve security vulnerabilities - Update transformers to >=4.50.0 (fixes CVE-2025-1194, CVE-2025-2099) - Update setuptools to >=78.1.1 (fixes CVE-2025-47273) - Regenerate poetry.lock with updated dependencies * fix: update protobuf to 5.29.5 and pycares to 4.9.0 to resolve security vulnerabilities * docs(readme): rewrite hero, add 5 marketing diagrams, comparison table Restructure the README to read like a product page: - Centered HTML hero with logo, tagline ("Compliance-as-code for AI systems"), and a value-prop subtitle. - Ordered 9-badge wall (CI, Stars, Version, Python, Apache 2.0, Built on OPA, Policies-from-gopal, Beta, PRs Welcome). - Language-switcher row anchoring four upcoming translations. - Five embedded marketing diagrams (PNG, each <140 KB), generated by a reproducible matplotlib script under diagrams/generate_diagrams.py: 1. End-to-end flow (AI app -> contract -> OPA eval -> report) 2. Architecture pipeline (evaluators -> OPA -> report generator) 3. Regulatory coverage grid (94 policies across 15+ frameworks) 4. Comparison vs Fairlearn / AIF360 / MS RAI / Credo AI 5. Audit-ready report anatomy - Comparison table differentiating AICertify against the four named alternatives on open-source, on-prem, policy-as-code, named regs, industry verticals, audit-ready reports, and custom policies. - Regulatory coverage section enumerating every framework with its policy count and the gopal source of truth. - Honest status section: production-ready frameworks vs work-in-progress. The README now leads with the user's pain (regulators move faster than governance docs), shows the deliverable (an audit-ready PDF), then explains the mechanism. Quickstart fits in four shell lines. * docs(i18n): add Simplified Chinese, Japanese, Korean, and Hindi READMEs Full README translations for four large developer markets: - README.zh-CN.md — Simplified Chinese (mainland) - README.ja-JP.md — Japanese (technical です/ます register) - README.ko-KR.md — Korean (-습니다/-입니다 formal) - README.hi-IN.md — Hindi (Devanagari with selective Latin retention for technical terms that read awkwardly when transliterated) Each translation: - Mirrors the English README structure exactly (headings, tables, code blocks, image refs, badges all preserved). - Includes the language switcher with the current language rendered as plain <strong> text and the others as anchor links. - Keeps regulation names (EU AI Act, NIST AI RMF, FERPA, COPPA, FAA Part 107, EASA SORA, RTCA DO-365/366) and product names (Fairlearn, AIF360, MS RAI Toolbox, Credo AI) verbatim — they are recognized internationally. - Uses consistent translated terminology for compliance, policy, audit, framework, evaluation, and human oversight. Together with the English README, AICertify is now discoverable in five languages covering ~15M+ developers outside of native-English markets. * docs(agents): add AGENTS.md and CLAUDE.md for AI coding agent context Two operational instruction files for AI coding assistants working in this repository (Claude Code, Cursor, Codex, Windsurf, Gemini CLI, Copilot, and any future agent that respects these conventions). AGENTS.md is the canonical guide: - What the project is (Python framework around OPA + gopal). - Repository layout with the role of each subdirectory. - Useful commands (install, quickstart, CLI, tests, lint). - Conventions (Python 3.12 only, line length 88, Pydantic v2, OPA policies are vendored from gopal upstream and should be edited there). - What NOT to do (don't pin deps aggressively, don't break the public API surface, don't introduce 3.13-only syntax, don't replace OPA). - A note on the author's preference for surgical changes. CLAUDE.md inherits from AGENTS.md and adds Claude Code-specific notes: fast-orientation paths into the codebase, TodoWrite usage, a pointer to the skills/ directory (added in a follow-up commit), and what NOT to claim about the project (no MCP server shipped yet). Together these reduce time-to-first-useful-edit for any AI agent opening the repo cold. * feat(skills): add 4 Claude Code skills for compliance workflows Ships four installable Claude Code skills under skills/. Each subfolder contains a SKILL.md with YAML frontmatter; users register them with: mkdir -p ~/.claude/skills && cp -r skills/* ~/.claude/skills/ Skills: - /run-compliance-check Runs the canonical end-to-end quickstart (sample contract through the EU AI Act policy set), locates the generated report, summarizes pass/fail, and surfaces failure stack traces with the most likely fix when the run errors. - /evaluate-contract <contract.json> <framework> [report-format] Validates the user-supplied contract, resolves the framework path under aicertify/opa_policies/, runs the CLI, summarizes the headline result, and surfaces the top failing rules with their deny[msg] strings. - /explain-regulation <framework> Walks every .rego in the framework directory, extracts METADATA, translates the allow conditions into plain English, and produces an auditor-readable coverage summary — including explicit "placeholder" flags for stub policies. - /draft-policy <domain> <framework> <policy_name> [--upstream] Scaffolds a new Rego policy + test sibling matching the project's conventions (package path mirrors directory, METADATA block, default deny, helper_functions.reporting integration). Defaults to writing upstream into gopal where it should live. Lowers first-use friction: a Claude Code user clones the repo, registers the skills, and gets compliance-aware slash commands immediately. * docs: start CHANGELOG.md in Keep-a-Changelog format Begin tracking notable changes in the standard Keep-a-Changelog 1.1.0 format, with an explicit Semver commitment. The initial file covers: - An [Unreleased] section capturing this docs/marketing overhaul: the hero rewrite, 5 generated diagrams, AGENTS.md + CLAUDE.md, the Claude Code skills directory, the comparison table, and the diagram generator script. - A [0.7.0] section reconstructing the visible v0.7 milestones from the recent git history: ReportLab-based reporting, the quickstart, the pluggable evaluator classes, the gopal submodule migration, security fixes (protobuf 5.29.5, pycares 4.9.0, transformers, setuptools), and the auto-labeling workflow fix. Future releases should append [X.Y.Z] - YYYY-MM-DD sections. The changelog also serves as crawler-visible signal of project velocity for anyone evaluating maintenance health. * build(pypi): prep AICertify for PyPI publication Make pyproject.toml ready for "pip install aicertify" once we cut a release to PyPI. Specifically: - Fix the malformed license expression. The previous value was license = {text = "\"Apache-2.0\""} which embeds escaped quotes inside the license string. Replaced with the SPDX form: license = "Apache-2.0". - Add 16 PyPI keywords — these power package search ranking: ai-governance, ai-compliance, ai-act, eu-ai-act, nist-ai-rmf, responsible-ai, open-policy-agent, opa, rego, regulatory-compliance, ai-audit, ai-safety, fairness, policy-as-code, ai-evaluation, ai-certification. - Add 13 PyPI classifiers including the audience hints (Developers, Information Technology, Legal Industry, Science/Research) and topic classifications (Artificial Intelligence, Security, Quality Assurance, Testing). These show up as the package's PyPI taxonomy. - Add a [project.urls] block (Homepage, Repository, Documentation, Issues, Changelog, and a cross-link to the gopal policy library). - Install a real console-script entry point under [project.scripts]: aicertify = "aicertify.cli:main" Previously users had to invoke "python -m aicertify.cli" — this gives them the standard "aicertify ..." command after install. - Remove the duplicate, out-of-sync [tool.poetry] block that still had version 0.1.0 and a minimal subset of dependencies; Poetry 2.x reads the canonical [project] section directly. The remaining [tool.poetry] block only carries Poetry-specific config (packages, group.dev). * docs: add Diátaxis-organized documentation index docs/INDEX.md provides a single navigation hub for the documentation surface, organized along the Diátaxis quadrants: - Tutorials — quickstart, sample contract, examples README - How-to guides — the four Claude Code skills, report-format howto - Reference — Python API, CLI flags, regulatory coverage table, pyproject.toml, CHANGELOG - Explanation — PROJECT_OVERVIEW.md, AGENTS.md, "why policy-as-code?" Plus a community section linking CONTRIBUTING, CODE_OF_CONDUCT, issues, and the sister gopal repo. Nothing is moved or renamed — this is purely an additive index pointing into existing files. The README remains the primary entry point; INDEX serves users who land here after following a "docs/" link. * chore: regenerate poetry.lock for cleaned-up pyproject.toml The PyPI-prep commit removed the duplicate, out-of-sync [tool.poetry] dependencies block in favor of the canonical [project] section. Poetry sees that as a "significant change" relative to the on-disk lockfile and refuses to install until the lockfile is regenerated. Regenerating with poetry 2.0.1 (poetry 2.1.x crashes on Python 3.12.3 due to a tarfile.ALLOW_MISSING gap unrelated to this PR). All security-relevant pins are preserved: - protobuf 5.29.5 - pycares 4.9.0 - urllib3 2.5.0 - transformers 4.50.3 - setuptools >= 78.1.1 Diff is ~70 lines of metadata churn (hash field, etc.) with no version changes to any dependency.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this PR is now
This PR started as a security-fixes branch and was the home of several iterative security patches (protobuf 5.29.5, pycares 4.9.0, transformers 4.50+, setuptools 78.1.1+). All of those security fixes have already been merged into main via separate PRs (#33, #35, #37, #39) since this branch was opened. This PR has therefore been repurposed as the docs + marketing overhaul that's been layered on top.
What's in here (8 commits past
main)docs(readme): rewrite hero, add 5 marketing diagrams, comparison tabledocs(i18n): add Simplified Chinese, Japanese, Korean, and Hindi READMEsdocs(agents): add AGENTS.md and CLAUDE.md for AI coding agent contextfeat(skills): add 4 Claude Code skills for compliance workflows/run-compliance-check,/evaluate-contract,/explain-regulation,/draft-policydocs: start CHANGELOG.md in Keep-a-Changelog formatbuild(pypi): prep AICertify for PyPI publicationdocs: add Diátaxis-organized documentation indexMerge main into fix-security-vulnerabilitiesWhat's NOT in here
.regopolicy changesRisk
Low. CI passes. CodeQL is green. The only Python change is a new
diagrams/generate_diagrams.py(matplotlib-only, used for regenerating marketing images).Companion PR
The sister policy library, gopal#14, ships a parallel docs+marketing overhaul.
🤖 Generated with Claude Code