aipr-py 0.2.4__tar.gz

aipr_py-0.2.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yunare Maia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aipr_py-0.2.4/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: aipr-py
+Version: 0.2.4
+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)
+
+**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.
+
+## License
+
+MIT

aipr_py-0.2.4/README.md

@@ -0,0 +1,219 @@
+# 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)
+
+**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.
+
+## License
+
+MIT

aipr_py-0.2.4/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aipr-py"
+version = "0.2.4"
+description = "Read a repository's AI contribution policy before you (or your agent) contribute."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Yunare Maia", email = "yunare@gmail.com" }]
+keywords = ["ai-policy", "open-source", "contributing", "cli", "agents"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Version Control :: Git",
+]
+dependencies = [
+    "regex>=2024.1.0",
+]
+
+[project.scripts]
+aipr = "aipr.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/yunaremaia/aipr"
+
+[tool.setuptools.packages.find]
+where = ["src"]

aipr_py-0.2.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aipr_py-0.2.4/src/aipr/__init__.py

@@ -0,0 +1,3 @@
+"""aipr: read an open-source repository's AI contribution policy."""
+
+__version__ = "0.2.3"

aipr_py-0.2.4/src/aipr/cache.py

@@ -0,0 +1,84 @@
+"""Thread-safe TTL cache for policy detection results."""
+
+from __future__ import annotations
+
+import copy
+import os
+import threading
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from aipr.detector import Policy
+
+
+# Default TTL: 24 hours (in seconds)
+DEFAULT_CACHE_TTL = int(os.environ.get("AIPR_CACHE_TTL", "86400"))
+MAX_CACHE_SIZE = int(os.environ.get("AIPR_CACHE_SIZE", "1024"))
+
+
+@dataclass
+class CacheEntry:
+    ts: float
+    policy: object  # Policy dataclass
+
+
+class TTLCache:
+    """Thread-safe TTL cache with LRU eviction and deep copy on read.
+    
+    Replaces lru_cache for Policy objects to ensure:
+    1. Thread safety via threading.Lock
+    2. TTL-based expiration (configurable via AIPR_CACHE_TTL env var)
+    3. Deep copy on read to prevent mutation of cached state
+    """
+
+    def __init__(self, ttl: int = DEFAULT_CACHE_TTL, maxsize: int = MAX_CACHE_SIZE):
+        self._ttl = ttl
+        self._maxsize = maxsize
+        self._cache: dict[str, CacheEntry] = {}
+        self._lock = threading.Lock()
+
+    def get(self, key: str) -> Optional[object]:
+        """Get a cached Policy, returning a deep copy.
+        
+        Returns None if key not found or entry expired.
+        """
+        with self._lock:
+            entry = self._cache.get(key)
+            if entry is None:
+                return None
+            if time.time() - entry.ts > self._ttl:
+                del self._cache[key]
+                return None
+            return copy.deepcopy(entry.policy)
+
+    def put(self, key: str, policy: object) -> None:
+        """Store a Policy with current timestamp.
+        
+        Evicts oldest entries if cache exceeds maxsize.
+        """
+        with self._lock:
+            while len(self._cache) >= self._maxsize:
+                oldest_key = min(self._cache, key=lambda k: self._cache[k].ts)
+                del self._cache[oldest_key]
+            self._cache[key] = CacheEntry(ts=time.time(), policy=copy.deepcopy(policy))
+
+    def clear(self) -> None:
+        """Clear all cached entries."""
+        with self._lock:
+            self._cache.clear()
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._cache)
+
+    def __contains__(self, key: str) -> bool:
+        with self._lock:
+            entry = self._cache.get(key)
+            if entry is None:
+                return False
+            if time.time() - entry.ts > self._ttl:
+                del self._cache[key]
+                return False
+            return True