AI Diagnostics

Netspecs can generate narrative diagnostic reports using AI, analyzing your test results and providing actionable recommendations.

Supported Providers

Netspecs uses LiteLLM to support multiple LLM providers:

Provider	Models	Environment Variable
OpenAI	gpt-5.2, gpt-4o, gpt-4-turbo	`OPENAI_API_KEY`
Anthropic	claude-3-opus, claude-3-sonnet	`ANTHROPIC_API_KEY`
Azure OpenAI	gpt-4, gpt-35-turbo	`AZURE_API_KEY`, `AZURE_API_BASE`
Ollama	llama2, mistral, etc.	(local, no key needed)

Setup

Option 1: Environment Variable

export OPENAI_API_KEY="sk-your-api-key-here"
netspecs run --ai-report

Option 2: .env.local File

Create a .env.local file in your working directory:

OPENAI_API_KEY=sk-your-api-key-here

Option 3: CLI Argument

netspecs run --ai-report --api-key sk-your-api-key-here

Using Different Models

OpenAI (Default)

# Default model (gpt-5.2)
netspecs run --ai-report

# Specific model
netspecs run --ai-report --model gpt-4o

Anthropic Claude

export ANTHROPIC_API_KEY="your-key"
netspecs run --ai-report --model claude-3-sonnet-20240229

Ollama (Local)

# Start Ollama with a model
ollama run llama2

# Use with netspecs
netspecs run --ai-report --model ollama/llama2

Report Format

The AI analyst provides:

Overall Health Assessment
Connection quality rating (Excellent/Good/Fair/Poor/Critical)
Key Issues Identified
High latency problems
Packet loss concerns
Jitter affecting real-time apps
Speed issues
Throttling patterns
Impact Analysis
How issues affect different use cases:
- Web browsing
- Video streaming
- Video conferencing
- Online gaming
- File transfers
Recommendations
Specific actions to resolve issues
When to contact ISP
Equipment suggestions
Technical Details
In-depth observations for advanced users

Example Output

## Overall Assessment: FAIR

Your internet connection shows moderate issues that may affect real-time 
applications like gaming and video calls.

### Key Issues

1. **Elevated Jitter (18ms)**: Your connection shows noticeable latency 
   variation, which can cause choppy audio in video calls and rubber-banding 
   in games.

2. **Speed Discrepancy**: There's a 65% difference between Ookla (250 Mbps) 
   and HTTP tests (150 Mbps), suggesting possible traffic prioritization.

### Impact

- **Gaming**: May experience occasional lag spikes
- **Video Calls**: Possible audio/video sync issues
- **Streaming**: Should be unaffected
- **Downloads**: Running below expected speeds

### Recommendations

1. Try connecting via Ethernet instead of WiFi
2. Restart your router during off-peak hours
3. If issues persist, contact your ISP with these results as evidence
4. Consider testing at different times of day

### Technical Notes

- Average latency to gaming servers: 45ms (acceptable)
- Packet loss: 0.5% (within normal range)
- Baseline vs heavy traffic latency increase: +25ms (moderate)

Generating Reports from Saved Results

Run tests and save results:

netspecs run --output json --output-dir ./results

Generate report later:

netspecs report ./results/diagnostic_20240101_120000.json --api-key your-key

Cost Considerations

AI reports use approximately: - 500-800 input tokens (test results) - 500-1000 output tokens (report)

At typical OpenAI pricing, each report costs approximately $0.01-0.02.

Privacy

Test results sent to the AI include: - Latency measurements - Speed test results - Endpoint hostnames (not IPs) - Statistical summaries

No personally identifiable information is included unless you've added custom endpoints containing such data.