ai-govern 0.1.0

CLI-first AI Governance platform that audits AI-enabled repositories for AI engineering best practices

AI Govern

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

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

pip install ai-govern

---

Quick Start

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

# 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

# .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:

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:

[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 for details.