Skip to main content
The Scanner module performs AST-based static analysis of your AI codebase — detecting features, extracting prompts, and mapping workflows. Scan results can be uploaded to the Valiqor backend for deeper analysis and attached to Failure Analysis runs.

​
Quick start

from valiqor.scanner import ValiqorScanner

scanner = ValiqorScanner()  # Loads config from .valiqorrc
scanner.configure(
    api_key="vq_...",
    project_name="my-app",
)

result = scanner.scan(repo_path=".")

print(f"Status: {result.status}")
print(f"Scan ID: {result.scan_id}")
print(f"Files generated: {result.files_generated}")
print(f"Files uploaded: {result.files_uploaded}")

​
Convenience function

For one-liner scans: 
from valiqor.scanner import quick_scan

result = quick_scan(
    api_key="vq_...",
    project_name="my-app",
    repo_path=".",
)

​
What the scanner does

The scanner runs a local pipeline:
1

AST analysis

Parses your Python codebase using abstract syntax trees to understand code structure.
2

Feature detection

Identifies AI features: LLM calls, retrieval functions, tool definitions, agent patterns.
3

Prompt extraction

Extracts prompt templates, system messages, and few-shot examples from your code.
4

Workflow mapping

Maps execution flow: which functions call which, how data flows through your pipeline.
5

Upload (optional)

If valiqor_intelligence is enabled, uploads results to the backend for deeper Stage 2+ analysis.

​
Scanner configuration

The scanner uses the same .valiqorrc config file: 
{
  "project_name": "my-app",
  "api_key": "vq_...",
  "scan_dir": "valiqor_output/scans",
  "valiqor_intelligence": true
}
ConfigDescriptionDefault
scan_dirLocal output directory for scan resultsvaliqor_output/scans
valiqor_intelligenceUpload results to Valiqor backendtrue

​
scan() method

result = scanner.scan(
    repo_path=".",           # Path to the repository to scan
    skip_upload=False,       # If True, only run local scan (no cloud upload)
)

​
ScanResult fields

FieldTypeDescription
statusstr"success" or "error"
project_namestrProject name used
scan_idstrUnique identifier for this scan
local_output_dirstrPath to generated files
files_generatedlist[str]Local files created
files_uploadedlist[str]Files uploaded to backend
upload_responsedictBackend response (if uploaded)
errorstrError message (if failed)

​
Local-only scanning

For environments without backend access: 
result = scanner.scan(
    repo_path=".",
    skip_upload=True,  # Only run local analysis
)

# Results saved to valiqor_output/scans/latest/
print(f"Output: {result.local_output_dir}")
for f in result.files_generated:
    print(f"  {f}")

​
Integration with Failure Analysis

When run_scan=True (default) in FA, scan data is automatically attached: 
# FA automatically includes scan context
result = client.failure_analysis.run(
    dataset=my_data,
    run_scan=True,  # Default — attaches scan data if available
)
This gives FA additional context about your codebase structure for more accurate failure classification.

​
CLI

# Scan current directory
valiqor scan run --path .

# Scan with custom output
valiqor scan run --path /path/to/repo --output ./scan-output

Failure Analysis →

Use scan data for deeper failure analysis.

Tracing →

Combine scanning with runtime tracing.