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 (recommended)
pip install aipr-py

# 2. Standalone from GitHub
pip install git+https://github.com/yunaremaia/aipr.git

Requires Python 3.10+. GH_TOKEN is recommended (anonymous API calls rate-limit fast):

export GH_TOKEN=ghp_xxx   # classic token with public repo read access

As a GitHub CLI extension

gh extension install yunaremaia/aipr does not work today: gh requires an extension manifest (gh-<name>.json) at the repository root, and this repo does not ship one. Install the package and link the gh-aipr entry point instead:

pip install aipr-py
ln -s "$(command -v aipr)" ~/.local/bin/gh-aipr

After that, gh aipr OWNER/REPO works identically to aipr OWNER/REPO.

One runtime dependency, regex (installed automatically); 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 linking gh-aipr as described in Install, 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

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

Exit codes (for CI and agents)

Batch mode: aipr owner/repo1 owner/repo2 ... prints one block per repo (JSON array with --json) and the exit code reflects the most restrictive result: 1 outranks 2, so a repo that forbids AI is never masked by a repo with no policy at all, and 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.

If this tool is useful to you, a star helps other people find it.

Related tools

• agent-guard — enforce guardrails on AI agent tool calls
• agentcost — track and attribute LLM spend per agent
• gfi — find well-scoped good first issues to start on
• oss-contribution-finder — find OSS projects ready to contribute to

Part of a family of focused, single-purpose developer tools — each one does one thing and does it well.

License

MIT