Detection Guide

This guide explains how AIGovHub detects AI systems in your codebase.

Detection Philosophy

AIGovHub follows these principles:

1. Deterministic First: Use reliable, deterministic signals before LLM analysis
2. High Recall: Prioritize finding all AI systems (false negatives are worse than false positives)
3. Explainable: Every detection includes evidence for human review
4. Conservative LLM Use: Only use LLM for genuinely ambiguous cases

Detection Pipeline

┌─────────────────┐
│  Repository     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Parse Dependencies │  ← requirements.txt, pyproject.toml, setup.py
└────────┬────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│                    Signal Detectors                          │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐   │
│  │ Library   │ │ Model     │ │ API       │ │ Code      │   │
│  │ Signal    │ │ File      │ │ Usage     │ │ Pattern   │   │
│  │           │ │ Signal    │ │ Signal    │ │ Signal    │   │
│  └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘   │
│        │             │             │             │          │
│        └──────────┬──┴─────────────┴──┬──────────┘          │
│                   │                   │                     │
│                   ▼                   ▼                     │
│           ┌─────────────┐    ┌─────────────┐                │
│           │  Aggregator │───▶│ Need LLM?   │                │
│           └─────────────┘    └──────┬──────┘                │
│                                     │                       │
│                           ┌─────────┼─────────┐             │
│                           │ Yes     │    No   │             │
│                           ▼         │         ▼             │
│                    ┌───────────┐    │  ┌───────────┐        │
│                    │ LLM       │    │  │ AI        │        │
│                    │ Analysis  │────┴─▶│ Systems   │        │
│                    └───────────┘       └───────────┘        │
└─────────────────────────────────────────────────────────────┘

Signal Types

1. Library Signal (Priority: 1, Confidence: DEFINITIVE)

Detects AI systems based on Python package dependencies.

What it checks:

• requirements.txt
• pyproject.toml dependencies
• setup.py install_requires

Detected Libraries (100+ packages):

Example Detection:

signal:
  source: library
  confidence: 1.0 (definitive)
  ai_type: nlp
  evidence:
    - "ML library: transformers"
    - "ML library: torch"
  dependencies:
    - transformers
    - torch

2. Model File Signal (Priority: 2, Confidence: HIGH)

Detects AI systems based on model file presence.

Detected File Extensions:

Model Directories: Files in directories named models/, weights/, checkpoints/, pretrained/ get higher confidence.

Example Detection:

signal:
  source: model_file
  confidence: 0.9 (high)
  ai_type: deep_learning
  evidence:
    - "Model file: models/classifier.pt"
  files:
    - models/classifier.pt
  metadata:
    model_formats: ["pytorch"]
    in_model_directory: "true"

3. API Usage Signal (Priority: 4, Confidence: MEDIUM-HIGH)

Detects AI API usage patterns in code.

Detected API Endpoints:

Example Detection:

signal:
  source: api_usage
  confidence: 0.85 (high)
  ai_type: llm_integration
  evidence:
    - "API pattern: api.openai.com"
  files:
    - src/chat.py

4. Code Pattern Signal (Priority: 5, Confidence: MEDIUM)

Detects ML patterns in Python code.

Detected Patterns:

Example Detection:

signal:
  source: code_pattern
  confidence: 0.7 (medium)
  ai_type: ml_model
  evidence:
    - "Code pattern: model.fit()"
    - "Code pattern: from_pretrained()"
  files:
    - src/train.py

5. LLM Analysis Signal (Priority: 6, Confidence: VARIABLE)

Uses LLM to analyze ambiguous code when deterministic signals are insufficient.

When LLM is triggered:

• Some signals exist but confidence < threshold
• Only code patterns found (no library/model signals)
• Confidence is in "maybe" zone (0.3 - threshold)

Not triggered when:

• Definitive signals found (library detection)
• Confidence already above threshold
• --no-llm flag used

Example Detection:

signal:
  source: llm_analysis
  confidence: 0.75 (medium)
  ai_type: ml_model
  evidence:
    - "Custom neural network implementation"
    - "Manual backpropagation code"
  metadata:
    reasoning: "Code implements gradient descent manually without ML libraries"
    llm_provider: "anthropic"

Signal Aggregation

Multiple signals are combined using weighted aggregation:

Weights

Aggregation Logic

1. Definitive signal present? → Confidence = 100%
2. Multiple signals? → Weighted average + bonus (up to +20% for multiple agreeing signals)
3. Below threshold? → Not reported as AI system

Example Aggregation

Signals:
  - Library (transformers): 1.0 × 1.0 = 1.0
  - Model File (.pt):       0.9 × 0.9 = 0.81
  - Code Pattern:           0.7 × 0.6 = 0.42

Weighted Average: (1.0 + 0.81 + 0.42) / (1.0 + 0.9 + 0.6) = 0.89
Bonus for 3 signals: +0.1
Final Confidence: 0.99 → HIGH

AI System Type Classification

When aggregating signals, the system infers the AI type:

Understanding Detection Results

Confidence Levels

Confidence levels are automatically computed from the numeric score:

The level is derived from the score using these thresholds. When signals are aggregated, the final confidence score determines the reported level.

Reading the Output

ai_systems:
  - id: "ai-001"
    name: "transformers-nlp"      # Auto-generated from evidence
    type: "nlp"                   # Inferred from signals
    detection_confidence: 0.95    # Aggregated score
    source:
      files:                      # Files where AI detected
        - "src/model.py"
      dependencies:               # AI-related dependencies
        - "transformers>=4.30.0"
      model_files:                # Model files found
        - "models/bert.safetensors"

Tuning Detection

Lower False Negatives (Find More)

aigovhub scan . --confidence 0.5 --llm

Lower False Positives (More Certain)

aigovhub scan . --confidence 0.9 --no-llm

Fast Scanning (CI/CD)

aigovhub scan . --no-llm

Thorough Analysis

aigovhub scan . --confidence 0.5 --llm --verbose

Limitations

1. Language Support: Currently Python-focused
2. Dynamic Analysis: No runtime analysis, only static code inspection
3. Proprietary Code: May miss AI systems in compiled dependencies
4. Novel Patterns: New AI frameworks may not be recognized immediately
5. False Positives: Libraries with ML-like names may be flagged

Extending Detection

See API Reference for creating custom signal detectors.