API Reference

pip install aigovhub-cli

from pathlib import Path
from aigovhub.scanner.engine import ScanEngine
from aigovhub.core.types import ScanConfig
 
# Create scan configuration
config = ScanConfig(
    confidence_threshold=0.7,
    use_llm_fallback=False,
)
 
# Create engine and scan
engine = ScanEngine(config)
result = engine.scan(Path("/path/to/repo"))
 
# Access results
for system in result.ai_systems:
    print(f"{system.name}: {system.ai_type.value} ({system.confidence.score:.0%})")

from aigovhub.core.types import ScanConfig
 
config = ScanConfig(
    confidence_threshold=0.7,      # Minimum confidence for detection
    use_llm_fallback=True,         # Enable LLM for ambiguous cases
    llm_provider="anthropic",      # LLM provider name
    include_patterns=[],           # Glob patterns to include
    exclude_patterns=[],           # Glob patterns to exclude
)

from aigovhub.core.types import ScanResult
 
result: ScanResult
 
# Properties
result.repository       # RepositoryInfo
result.ai_systems       # list[AISystem]
result.scan_config      # ScanConfig
result.scanned_at       # datetime
result.scanner_version  # str
result.signals          # list[DetectionSignal]
result.errors           # list[str]
result.warnings         # list[str]
 
# Computed properties
result.has_ai_systems   # bool
result.max_confidence   # float

from aigovhub.core.types import AISystem
 
system: AISystem
 
system.id              # str, e.g., "ai-001"
system.name            # str, human-readable name
system.ai_type         # AISystemType enum
system.confidence      # Confidence object
system.signals         # list[DetectionSignal]
system.source_files    # list[Path]
system.dependencies    # list[str]
system.model_files     # list[Path]
system.risk_category   # RiskCategory | None
system.intended_purpose # str | None
system.domain          # str | None

from aigovhub.core.types import AISystemType
 
AISystemType.ML_MODEL              # Traditional ML
AISystemType.DEEP_LEARNING         # Neural networks
AISystemType.LLM_INTEGRATION       # LLM usage
AISystemType.COMPUTER_VISION       # Image/video AI
AISystemType.NLP                   # Natural language processing
AISystemType.REINFORCEMENT_LEARNING
AISystemType.AUTONOMOUS_AGENT
AISystemType.RECOMMENDATION_SYSTEM
AISystemType.PREDICTIVE_ANALYTICS
AISystemType.UNKNOWN

from aigovhub.core.types import Confidence, ConfidenceLevel
 
# Create confidence
conf = Confidence(score=0.85, level=ConfidenceLevel.HIGH)
 
# Factory methods
Confidence.definitive()    # 1.0, DEFINITIVE
Confidence.high(0.9)       # HIGH level
Confidence.medium(0.65)    # MEDIUM level
Confidence.low(0.4)        # LOW level
 
# Properties
conf.score    # float 0.0-1.0
conf.level    # ConfidenceLevel enum

from aigovhub.core.types import ConfidenceLevel
 
ConfidenceLevel.DEFINITIVE   # 1.0
ConfidenceLevel.HIGH         # 0.8-0.99
ConfidenceLevel.MEDIUM       # 0.5-0.79
ConfidenceLevel.LOW          # 0.3-0.49
ConfidenceLevel.UNCERTAIN    # <0.3

from aigovhub.core.types import DetectionSignal, SignalSource
 
signal: DetectionSignal
 
signal.source       # SignalSource enum
signal.confidence   # Confidence
signal.ai_type      # AISystemType
signal.evidence     # list[str]
signal.files        # list[Path]
signal.dependencies # list[str]
signal.metadata     # dict[str, str]

from aigovhub.core.types import SignalSource
 
SignalSource.LIBRARY        # Dependency detection
SignalSource.MODEL_FILE     # Model file detection
SignalSource.API_USAGE      # API URL patterns
SignalSource.CODE_PATTERN   # Code patterns
SignalSource.LLM_ANALYSIS   # LLM fallback

from aigovhub.core.types import RiskCategory
 
RiskCategory.PROHIBITED      # Banned AI systems
RiskCategory.HIGH_RISK       # Strict requirements
RiskCategory.LIMITED_RISK    # Transparency requirements
RiskCategory.MINIMAL_RISK    # No specific requirements

from pathlib import Path
from aigovhub.scanner.engine import ScanEngine
from aigovhub.core.types import ScanConfig
 
# Initialize
engine = ScanEngine(
    config=ScanConfig(),
    llm_client=None,  # Optional LLMClient
)
 
# Scan a repository
result = engine.scan(Path("/path/to/repo"))
 
# Convert to artifact format
artifact_data = engine.to_artifact(result)

from pathlib import Path
from aigovhub.scanner.repository import Repository
 
# Initialize
repo = Repository(
    path=Path("/path/to/repo"),
    exclude_patterns=[".git", "node_modules"],
    include_patterns=None,
)
 
# Get repository info
info = repo.info  # RepositoryInfo
 
# Iterate files
python_files = repo.iter_files(extensions={".py"})
model_files = repo.iter_files(pattern="*.pt")
 
# Read file content
content = repo.read_file(Path("src/main.py"))
 
# Find specific files
found = repo.find_files({"requirements.txt", "pyproject.toml"})

from pathlib import Path
from aigovhub.scanner.dependency_parser import DependencyParser
 
parser = DependencyParser(Path("/path/to/repo"))
 
# Parse all dependency files
dependencies = parser.parse_all()
 
# Parse specific file
from_requirements = parser.parse_requirements(Path("requirements.txt"))
from_pyproject = parser.parse_pyproject(Path("pyproject.toml"))
 
# Get dependency names
names = parser.get_dependency_names()  # set[str]

from aigovhub.detection.detector import AIDetector
from aigovhub.core.types import ScanConfig
 
detector = AIDetector(
    config=ScanConfig(),
    llm_client=None,
)
 
# Run detection
ai_systems, signals = detector.detect(repository, dependencies)

from aigovhub.detection.aggregator import SignalAggregator
 
aggregator = SignalAggregator(confidence_threshold=0.7)
 
# Aggregate signals
ai_systems = aggregator.aggregate(signals)
 
# Check if LLM needed
needs_llm = aggregator.needs_llm_analysis(signals)

from aigovhub.detection.signals.base import SignalDetector
from aigovhub.core.types import DetectionSignal, Confidence, SignalSource, AISystemType
 
class CustomSignal(SignalDetector):
    @property
    def name(self) -> str:
        return "custom"
 
    @property
    def priority(self) -> int:
        return 5  # Lower = higher priority
 
    def detect(
        self,
        repository: Repository,
        dependencies: list[Dependency],
    ) -> list[DetectionSignal]:
        signals = []
 
        # Your detection logic here
        if self._found_something(repository):
            signals.append(DetectionSignal(
                source=SignalSource.CODE_PATTERN,
                confidence=Confidence.medium(0.7),
                ai_type=AISystemType.ML_MODEL,
                evidence=["Found custom AI pattern"],
                files=[Path("src/model.py")],
            ))
 
        return signals
 
    def _found_something(self, repository: Repository) -> bool:
        # Implementation
        return False

from aigovhub.llm.client import LLMClient, get_llm_client
 
# Create client
client = LLMClient(
    provider="anthropic",
    api_key="sk-...",  # Optional, uses env var
)
 
# Or use factory
client = get_llm_client(provider="openai")
 
# Check configuration
if client.is_configured:
    # Generate completion
    response = client.complete(
        prompt="Analyze this code...",
        system_prompt="You are an AI expert.",
        max_tokens=1024,
        temperature=0.0,
    )
    print(response)
 
    # Async version
    response = await client.complete_async(prompt)

from aigovhub.llm.providers.base import LLMProvider, LLMResponse
 
class CustomProvider(LLMProvider):
    @property
    def name(self) -> str:
        return "custom"
 
    @property
    def is_configured(self) -> bool:
        return True  # Check API key, etc.
 
    def complete(
        self,
        prompt: str,
        *,
        system_prompt: str | None = None,
        max_tokens: int = 1024,
        temperature: float = 0.0,
    ) -> LLMResponse:
        # Your implementation
        return LLMResponse(
            content="Response text",
            model="custom-model",
            usage={"input_tokens": 100, "output_tokens": 50},
            finish_reason="stop",
        )
 
    async def complete_async(self, prompt: str, **kwargs) -> LLMResponse:
        # Async implementation
        return self.complete(prompt, **kwargs)

from pathlib import Path
from aigovhub.artifact.manager import ArtifactManager
 
manager = ArtifactManager()
 
# Initialize new artifact
manager.init(
    path=Path("aigovhub.yaml"),
    template="standard",  # minimal, standard, enterprise
    repo_name="my-project",
)
 
# Read existing artifact
artifact = manager.read(Path("aigovhub.yaml"))
 
# Write artifact
manager.write(Path("output.yaml"), data_dict)
 
# Update artifact
updated = manager.update(
    Path("aigovhub.yaml"),
    {"compliance": {"status": "compliant"}},
)

from pathlib import Path
from aigovhub.artifact.validator import ArtifactValidator
 
validator = ArtifactValidator()
 
# Validate file
result = validator.validate(
    path=Path("aigovhub.yaml"),
    schema_version="1.0.0",  # Optional
)
 
# Check results
if result.is_valid:
    print("Valid!")
else:
    for error in result.errors:
        print(f"Error: {error}")
 
for warning in result.warnings:
    print(f"Warning: {warning}")
 
# Access metadata
print(result.info)  # {"schema_version": "1.0.0", ...}

from aigovhub.artifact.schema import AIGovHubArtifact
 
# Parse from dict
artifact = AIGovHubArtifact.from_dict(data)
 
# Access fields
print(artifact.schema_version)
print(artifact.ai_systems)
 
# Convert to dict
data = artifact.to_dict()

from aigovhub.sbom.generator import SBOMGenerator
 
generator = SBOMGenerator()
 
# Generate SBOM dict
sbom = generator.generate(scan_result)
 
# Generate JSON string
json_str = generator.to_json(scan_result)

from aigovhub.core.config import Config, get_config, reset_config
 
# Get global config
config = get_config()
 
# Access settings
print(config.confidence_threshold)
print(config.llm_provider)
 
# Get API key for provider
key = config.get_api_key("anthropic")
 
# Reset (mainly for testing)
reset_config()

from aigovhub.core.exceptions import (
    AIGovHubError,           # Base exception
    ConfigurationError,       # Config issues
    RepositoryError,         # Repository access
    ScanError,               # Scanning errors
    DetectionError,          # Detection errors
    ValidationError,         # Validation errors
    LLMError,                # LLM errors
    LLMProviderNotConfiguredError,
    LLMRateLimitError,
    SBOMGenerationError,
)
 
try:
    result = engine.scan(path)
except RepositoryError as e:
    print(f"Repository error: {e.message}")
    print(f"Details: {e.details}")
except AIGovHubError as e:
    print(f"Error: {e}")

"""Complete example of using AIGovHub API."""
 
from pathlib import Path
import json
 
from aigovhub.core.types import ScanConfig
from aigovhub.core.config import get_config
from aigovhub.scanner.engine import ScanEngine
from aigovhub.artifact.manager import ArtifactManager
from aigovhub.artifact.validator import ArtifactValidator
from aigovhub.sbom.generator import SBOMGenerator
 
 
def scan_repository(repo_path: str) -> dict:
    """Scan a repository and return results."""
    path = Path(repo_path)
 
    # Configure scan
    config = ScanConfig(
        confidence_threshold=0.7,
        use_llm_fallback=False,
    )
 
    # Run scan
    engine = ScanEngine(config)
    result = engine.scan(path)
 
    # Generate artifact
    artifact_data = engine.to_artifact(result)
 
    # Write artifact
    output_path = path / "aigovhub.yaml"
    manager = ArtifactManager()
    manager.write(output_path, artifact_data)
 
    # Validate
    validator = ArtifactValidator()
    validation = validator.validate(output_path)
 
    if not validation.is_valid:
        raise ValueError(f"Validation failed: {validation.errors}")
 
    # Generate SBOM
    sbom_gen = SBOMGenerator()
    sbom = sbom_gen.generate(result)
 
    return {
        "ai_systems": len(result.ai_systems),
        "max_confidence": result.max_confidence,
        "artifact_path": str(output_path),
        "sbom": sbom,
    }
 
 
if __name__ == "__main__":
    results = scan_repository(".")
    print(json.dumps(results, indent=2, default=str))