Metadata-Version: 2.4
Name: aipr-py
Version: 0.2.5
Summary: Read a repository's AI contribution policy before you (or your agent) contribute.
Author-email: Yunare Maia <yunare@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/yunaremaia/aipr
Keywords: ai-policy,open-source,contributing,cli,agents
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: regex>=2024.1.0
Dynamic: license-file

# aipr

[![CI](https://github.com/yunaremaia/aipr/actions/workflows/ci.yml/badge.svg)](https://github.com/yunaremaia/aipr/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/yunaremaia/aipr/blob/main/LICENSE)
![Stars](https://img.shields.io/github/stars/yunaremaia/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

```bash
# 1. From PyPI
pip install aipr-py

# 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

```bash
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:

```bash
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:

```bash
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:

```yaml
# .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.

```bash
# 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:

```yaml
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](https://github.com/yunaremaia/agent-guard)** — enforce guardrails on AI agent tool calls
- **[agentcost](https://github.com/yunaremaia/agentcost)** — track and attribute LLM spend per agent
- **[gfi](https://github.com/yunaremaia/gfi)** — find well-scoped good first issues to start on
- **[oss-contribution-finder](https://github.com/yunaremaia/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
