aipr

AI Policy Read - read an open-source repository's AI contribution policy before you (or your agent) contribute.

aipr fetches the governance files that usually carry AI rules (CONTRIBUTING.md, AI_POLICY.md, AGENTS.md, CLAUDE.md, ...), classifies the repository's stance with weighted phrase matching, and answers one question: can an AI-assisted or autonomous contribution land here?

$ aipr asciimoo/hister
aipr: asciimoo/hister
[BLOCKED] human-only policy
sources: CONTRIBUTING.md, README.md
confidence: 1.0  score: 19.0
autonomous contribution: NOT SAFE - require human co-authorship
  [+5.0] ...Issues and PR descriptions must be fully human-written...
  [+5.0] ...AI should never be the main author of the PR...

$ aipr apache/maka
aipr: apache/maka
[UNKNOWN] no explicit AI policy found
exit=2

Why

More repositories are publishing explicit AI policies - from "we welcome AI-assisted work" to "agents are strictly forbidden". Violating one burns the contributor (and, for autonomous agents, the operator): rejected PRs at best, blocks at worst. aipr makes the check mechanical and cheap, for humans deciding where to spend review effort and for agents deciding where to spend their quota.

Install

# 1. From PyPI
pip install aipr

# 2. Standalone from GitHub
pip install git+https://github.com/yunaremaia/aipr.git
# requires Python 3.10+; GH_TOKEN recommended (anonymous API calls rate-limit fast)
export GH_TOKEN=ghp_xxx   # classic token with public repo read access

# 3. As a GitHub CLI extension (recommended)
gh extension install yunaremaia/aipr

The gh extension install method is the easiest — after install, gh aipr OWNER/REPO works immediately.

No dependencies beyond the standard library. pytest only to develop.

Usage

Standalone

aipr OWNER/REPO            # classify a GitHub repository
aipr --text FILE           # classify a local governance file
aipr --json OWNER/REPO     # machine-readable output
aipr --sarif OWNER/REPO    # SARIF 2.1.0 output for GitHub Code Scanning

As a GitHub CLI extension

After gh extension install yunaremaia/aipr, use gh aipr identically:

gh aipr OWNER/REPO
gh aipr --json OWNER/REPO
gh aipr --sarif OWNER/REPO
gh aipr --text FILE

Exit codes are preserved (0/1/2) for CI conditionals.

init — scaffold AI policy files

Generate AI_POLICY.md and AI_TOOL_POLICY.md in your repo:

aipr init [--dir .] [--type disclose|permissive|human_only] [--org ORG]

Presets:

• permissive — explicitly welcomes AI-assisted contributions (aipr-safe)
• disclose_ok (default) — allowed with Assisted-by: AI disclosure trailer
• human_only — AI must not be the main author (NOT autonomous-safe)

Verdicts

Verdict	Meaning	Autonomous-safe?
human_only	AI must not be the main author / human-written only / bans agents	no
restrictive	heavy process: mandatory disclosure + human-in-the-loop requirements	no
disclose_ok	allowed with a disclosure trailer (Assisted-by: AI)	yes*
permissive	explicitly welcomes AI-assisted contributions	yes
unknown	no explicit policy found	ask first

* still follow the disclosure rules - "safe" means no human co-authorship required by policy, not no obligations.

Exit codes (for CI and agents)

Code	Meaning
0	all inspected repos are autonomous-safe
1	at least one repo is restricted or human-only
2	at least one repo is unknown / no policy found (ranks worse than 1)
64	usage error

Batch mode: aipr owner/repo1 owner/repo2 ... prints one block per repo (JSON array with --json) and the exit code reflects the worst result — so an unverified repo can never pass a gate silently.

Policy fetches are cached on disk for 24h (~/.cache/aipr, configurable via AIPR_CACHE_DIR / AIPR_CACHE_TTL), so repeated scans cost zero API calls. Use --no-cache to force a fresh fetch.

How classification works

Weighted regex matching over concatenated governance text. Restrictive phrases score positive ("must be fully human-written" +5), permissive ones negative ("we warmly welcome AI-assisted" -3.5). The strongest signals force the verdict; weak mixed signals lean restrictive on purpose - when in doubt, do not send a bot.

Known limits: English-only patterns; phrase matching cannot understand nuance; a repo can carry policy in unusual files we don't probe. Treat UNKNOWN as "read it yourself".

CI/CD Integration

Block PRs Violating AI Policy

Drop .github/workflows/aipr.yml into your repository to automatically block pull requests targeting repos with human-only or restrictive AI policies:

# .github/workflows/aipr.yml – block PRs against repos with human-only AI policies
name: AI Policy Check
on:
  pull_request:
    branches: [main, master]

jobs:
  aipr:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-python@v5
        with:
          python-version: "3.10"
      - run: pip install git+https://github.com/yunaremaia/aipr.git
      - name: Check AI policy
        run: |
          aipr "$GITHUB_REPOSITORY" --json || true
          # Exit 1 = human_only/restrictive (block)
          # Exit 2 = unknown (warn, not block)
          aipr "$GITHUB_REPOSITORY" --json | jq -e '.verdict == "human_only" or .verdict == "restrictive"' && exit 1 || exit 0

GitHub Code Scanning (SARIF)

Use --sarif to output SARIF 2.1.0 (Static Analysis Results Interchange Format) and upload to GitHub Code Scanning. This surfaces AI policy compliance as alerts in the GitHub Security tab.

# Generate SARIF output
aipr --sarif OWNER/REPO > aipr-results.sarif
# Upload to GitHub Code Scanning via GitHub Actions:
#   github/codeql-action/upload-sarif with sarif_file: aipr-results.sarif

Verdict mapping to SARIF levels:

• human_only / restrictive → error (blocks contribution)
• unknown → warning (needs manual review)
• permissive / disclose_ok → note (safe to proceed)

Example GitHub Actions workflow snippet:

name: AI Policy Check (SARIF)
on:
  pull_request:
    branches: [main]

jobs:
  aipr-check:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install git+https://github.com/yunaremaia/aipr.git
      - run: aipr --sarif ${{ github.event.pull_request.head.repo.full_name }} > aipr-results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: aipr-results.sarif

Status

Early beta - battle-tested against a handful of real policies (hister, modular, polars, MDAnalysis, maka). Rule additions welcome: open an issue with the policy text and the verdict you expected.

License

MIT