Getting Started

This guide will help you install AIGovHub CLI and run your first AI system scan.

Prerequisites

Python 3.12 or higher
pip or uv package manager
Git (optional, for repository metadata)

Installation

Using uv (Recommended)

uv is a fast Python package installer:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
 
# Install aigovhub-cli
uv pip install aigovhub-cli

Using pip

pip install aigovhub-cli

From Source

git clone https://github.com/aigovhub/aigovhub-cli
cd aigovhub-cli
uv sync --all-extras  # or: pip install -e ".[dev]"

Verify Installation

aigovhub --version
# Output: aigovhub version 0.1.0

Your First Scan

1. Navigate to Your Project

cd /path/to/your/project

2. Run a Dry-Run Scan

Start with a dry run to see what would be detected without creating files:

aigovhub scan . --dry-run

Example output:

ℹ Scanning repository: /path/to/your/project

╭─────────────────────────── AIGovHub Scan Results ────────────────────────────╮
│ Repository: your-project                                                     │
│ Path: /path/to/your/project                                                  │
│ Commit: abc1234                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

                              Detected AI Systems
┏━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
┃ ID     ┃ Name               ┃ Type            ┃   Confidence ┃ Risk          ┃
┡━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
│ ai-001 │ transformers-nlp   │ nlp             │  100% (def)  │ not evaluated │
└────────┴────────────────────┴─────────────────┴──────────────┴───────────────┘

Summary: 1 AI system(s) detected, max confidence: 100%

3. Generate the Compliance Artifact

Once satisfied with the detection results, run the full scan:

aigovhub scan .

This creates aigovhub.yaml in your project root.

4. Review the Output

Open aigovhub.yaml to review the detected AI systems:

schema_version: "1.0.0"
generated_at: "2025-01-15T10:30:00Z"
generated_by: "aigovhub v0.1.0"
 
repository:
  name: "your-project"
  git_commit: "abc1234"
 
ai_systems:
  - id: "ai-001"
    name: "transformers-nlp"
    type: "nlp"
    detection_confidence: 1.0
    source:
      files: ["src/model.py"]
      dependencies: ["transformers>=4.30.0"]
      model_files: []
    classification:
      risk_category: null
    intended_purpose:
      description: null
      domain: null
 
compliance:
  status: "not_evaluated"

5. Commit to Version Control

Add the artifact to your repository:

git add aigovhub.yaml
git commit -m "Add AI compliance artifact"

Understanding the Output

Confidence Levels

Level	Score	Meaning
DEFINITIVE	100%	Confirmed AI system (ML library detected)
HIGH	80-99%	Very likely AI system (model files, API clients)
MEDIUM	50-79%	Possible AI system (code patterns)
LOW	30-49%	Uncertain, may need review
UNCERTAIN	<30%	Unlikely to be AI system

AI System Types

Type	Description
`ml_model`	Traditional machine learning model
`deep_learning`	Neural network / deep learning system
`llm_integration`	Large Language Model integration
`computer_vision`	Image/video processing AI
`nlp`	Natural language processing
`reinforcement_learning`	RL agent or system
`autonomous_agent`	Autonomous AI agent

Common Workflows

Initialize an Empty Artifact

If you want to manually document AI systems:

aigovhub init

This creates a template aigovhub.yaml you can fill in.

Validate an Existing Artifact

Check if your aigovhub.yaml is valid:

aigovhub validate

With strict mode (fail on warnings):

aigovhub validate --strict

Scan Without LLM

For faster, deterministic-only scanning:

aigovhub scan . --no-llm

Custom Output Location

aigovhub scan . --output reports/ai-compliance.yaml

JSON Output

aigovhub scan . --format json --output ai-systems.json

Next Steps

CLI Reference - Learn all available commands and options
Configuration - Set up LLM providers and default settings
Detection Guide - Understand how detection works
CI/CD Integration - Automate compliance checks

Troubleshooting

"No AI systems detected"

This is normal for non-AI projects. The tool only reports what it finds.

If you expected AI systems to be detected:

Check that your requirements.txt or pyproject.toml lists AI dependencies
Lower the confidence threshold: --confidence 0.5
Enable LLM fallback: --llm

"Permission denied"

Ensure you have read access to all files in the repository.

"Rate limit exceeded" (LLM)

The LLM fallback hit API rate limits. Options:

Use --no-llm for deterministic-only detection
Wait and retry
Use a different LLM provider

Getting Help

aigovhub --help
aigovhub scan --help
aigovhub init --help
aigovhub validate --help