Code Scanning

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:

AST analysis

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

Feature detection

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

Prompt extraction

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

Workflow mapping

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

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
}

Config	Description	Default
`scan_dir`	Local output directory for scan results	`valiqor_output/scans`
`valiqor_intelligence`	Upload results to Valiqor backend	`true`

`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

Field	Type	Description
`status`	`str`	`"success"` or `"error"`
`project_name`	`str`	Project name used
`scan_id`	`str`	Unique identifier for this scan
`local_output_dir`	`str`	Path to generated files
`files_generated`	`list[str]`	Local files created
`files_uploaded`	`list[str]`	Files uploaded to backend
`upload_response`	`dict`	Backend response (if uploaded)
`error`	`str`	Error 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.

Start Here

Core Workflows

Concepts

Integrations

Resources

Quick start

Convenience function

What the scanner does

Scanner configuration

`scan()` method

ScanResult fields

Local-only scanning

Integration with Failure Analysis

CLI

Failure Analysis →

Tracing →

​Quick start

​Convenience function

​What the scanner does

​Scanner configuration

​scan() method

​ScanResult fields

​Local-only scanning

​Integration with Failure Analysis

​CLI

Failure Analysis →

Tracing →

Quick start

Convenience function

What the scanner does

Scanner configuration

`scan()` method

ScanResult fields

Local-only scanning

Integration with Failure Analysis

CLI