Metadata-Version: 2.4
Name: ai-govern
Version: 0.1.0
Summary: CLI-first AI Governance platform that audits AI-enabled repositories for AI engineering best practices
Author: AI Govern Contributors
License: MIT
Keywords: agents,ai,audit,best-practices,cli,governance,llm
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.12
Requires-Dist: aiofiles>=23.2.0
Requires-Dist: anyio>=4.4.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: gitpython>=3.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: pathspec>=0.12.0
Requires-Dist: pydantic-settings>=2.3.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Requires-Dist: uvicorn[standard]>=0.30.0
Provides-Extra: dev
Requires-Dist: black>=24.4.0; extra == 'dev'
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.2.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Description-Content-Type: text/markdown

# AI Govern

> **"AI Govern verifies that your AI system is engineered correctly — not that your application code is written correctly."**

[![PyPI version](https://badge.fury.io/py/ai-govern.svg)](https://badge.fury.io/py/ai-govern)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**AI Govern** is a CLI-first AI Governance platform that audits AI-enabled repositories for AI engineering best practices. Think of it as **ESLint + Lighthouse + SonarQube — but exclusively for AI systems**.

---

## What It Does

AI Govern scans **only** the AI layer of your repository:

✅ **Analyzes** — CLAUDE.md, AGENTS.md, GEMINI.md, Cursor rules, Copilot instructions, prompt templates, skill definitions, agent workflows, MCP servers, tool definitions, LLM configurations, RAG configs, memory strategies

❌ **Ignores** — CRUD endpoints, React components, CSS, database schemas, authentication, general business logic

---

## Installation

```bash
pip install ai-govern
```

---

## Quick Start

```bash
# Scan current directory and open dashboard
ai-govern run

# Scan a specific repository
ai-govern run /path/to/your/ai-repo

# Generate standalone HTML report
ai-govern report

# Auto-fix issues interactively
ai-govern fix

# CI mode (returns exit code 1 if score below threshold)
ai-govern run --ci --output json

# Initialize configuration
ai-govern init

# List all governance rules
ai-govern plugins
```

---

## Dashboard

Running `ai-govern run` launches a local dashboard at `http://localhost:5172`:

- **Overview** — Governance score, issue summary, category breakdown
- **Issue Explorer** — Searchable, filterable issue list with full details
- **Context Analysis** — Quality analysis of CLAUDE.md, AGENTS.md, etc.
- **Automation Opportunities** — Where AI is over-engineered (use deterministic code instead)
- **Security** — Hardcoded secrets, prompt injection risks
- **Cost Optimization** — Caching gaps, token limit issues, model selection
- **Observability** — Missing telemetry, token logging, latency tracking
- **Agents** — Agent definition quality, circular workflows
- **Auto-Fix Panel** — Preview diffs, approve/reject, rollback

---

## Governance Categories

| Category | Weight | Example Rules |
|----------|--------|---------------|
| Security | 20% | Hardcoded API keys, prompt injection |
| Context | 15% | Missing CLAUDE.md, poor context quality |
| Prompt Engineering | 15% | Missing system prompt, duplicate prompts |
| Cost Optimization | 10% | No caching, no token limits |
| Agents | 10% | Missing descriptions, circular workflows |
| Observability | 8% | No telemetry, no token tracking |
| Documentation | 7% | Missing skill docs, no README AI section |
| RAG | 5% | No chunking strategy, no embedding model spec |
| Memory | 4% | No memory strategy, unbounded history |
| Tools/MCP | 3% | Missing tool descriptions, insecure transport |
| Model Governance | 3% | Unpinned model versions |
| Automation | 1% | LLM used for UUID/JSON/date formatting |

---

## Configuration

Create `ai-govern.yaml` in your repository root:

```yaml
# Governance Policy
min_governance_score: 70.0
fail_on_critical: true

# Disable specific rules
disabled_rules:
  - PE001  # Hardcoded prompts (if you prefer inline prompts)

# LLM Analysis (optional)
llm:
  enabled: false
  provider: openai
  model: gpt-4o-mini
  api_key_env: OPENAI_API_KEY

# Dashboard
dashboard_port: 5172
auto_open_browser: true
```

Run `ai-govern init` to generate this file automatically.

---

## CI/CD Integration

```yaml
# .github/workflows/ai-governance.yml
- name: AI Governance Check
  run: |
    pip install ai-govern
    ai-govern run --ci --output sarif
  
- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: ai-govern-report.sarif
```

---

## Plugin SDK

Write custom governance rules:

```python
from ai_govern.plugins.sdk import GovernanceRule, RuleCategory, Severity, ScanContext, GovernanceIssue

class MyCustomRule(GovernanceRule):
    rule_id = "CUSTOM001"
    name = "My Custom Rule"
    category = RuleCategory.AGENTS
    severity = Severity.MEDIUM
    
    def evaluate(self, context: ScanContext) -> list[GovernanceIssue]:
        # Your rule logic here
        return []
```

Register in `pyproject.toml`:

```toml
[project.entry-points."ai_govern.rules"]
my_rule = "my_plugin.rules:MyCustomRule"
```

---

## Architecture

```
ai-govern run
     │
     ├── FileScanner (AI-only file discovery)
     │       └── AI relevance filtering (50+ patterns)
     │
     ├── RuleEngine
     │       ├── RuleRegistry (built-in + plugins via entry_points)
     │       ├── RuleExecutor (concurrent, thread-pool)
     │       └── Scorer (weighted category scoring)
     │
     ├── AutoFixEngine (propose → preview → approve → apply → rollback)
     │
     └── FastAPI Server
             ├── API v1 (scan, issues, fixes, plugins, config)
             └── React Dashboard (pre-built, served as static files)
```

---

## License

MIT License — see [LICENSE](LICENSE) for details.
