Architecture

Architecture

System Overview

BGP Explorer is built as an AI-powered CLI that orchestrates multiple BGP data sources through Claude AI.

User → CLI (cli.py) → Agent (agent.py) → AI Backend (claude)
                                              ↓
                                        Tools (ai/tools.py)
                                              ↓
                    ┌─────────────┬───────────┴───────────┬─────────────┐
                    ↓             ↓                       ↓             ↓
              bgp-radar      RIPE Stat              Globalping    PeeringDB
            [real-time]    [state/history]          [probing]     [contacts]
                                                                      ↓
                                                                  Monocle
                                                              [relationships]

Component Layers

CLI Layer (cli.py)

The Click-based command-line interface handles:

• Argument parsing and validation
• Environment variable loading
• Session initialization
• Interactive chat loop
• Command processing (/monitor, /thinking, etc.)

Agent Layer (agent.py)

The orchestration layer that:

• Manages conversation state
• Routes messages to the AI backend
• Executes tool calls from AI responses
• Formats output for display
• Handles streaming responses

AI Backend (ai/claude.py)

The Claude integration that:

• Registers available tools
• Sends messages with extended thinking enabled
• Parses tool calls from responses
• Manages thinking budget and token limits

Tools (ai/tools.py)

The MCP server (mcp_server.py) exposes 8 composite tools, the standalone BGPTools class provides individual tools:

• Each tool is a method with docstrings that Claude reads
• Tools call the appropriate data source client
• Results are formatted for Claude to interpret

Data Sources (sources/)

Individual clients for each data source:

File	Client	Purpose
ripe_stat.py	RipeStatClient	RIPE Stat REST API
bgp_radar.py	BgpRadarClient	bgp-radar subprocess
globalping.py	GlobalpingClient	Globalping REST API
peeringdb.py	PeeringDBClient	PeeringDB data (CAIDA dump)
monocle.py	MonocleClient	Monocle CLI wrapper

Data Flow

Query Flow

1. User enters a question
2. CLI passes message to Agent
3. Agent sends to Claude with available tools
4. Claude decides which tools to call
5. Agent executes tool calls
6. Results returned to Claude
7. Claude synthesizes response
8. Agent displays response to user

Tool Execution Flow

Agent receives tool_use from Claude
    ↓
Agent looks up tool in BGPTools
    ↓
Tool calls data source client
    ↓
Client makes API/subprocess call
    ↓
Response parsed and formatted
    ↓
Result returned to Claude

Data Models

BGPRoute

Represents a single BGP route observation:

@dataclass
class BGPRoute:
    prefix: str           # e.g., "8.8.8.0/24"
    origin_asn: int       # e.g., 15169
    as_path: list[int]    # e.g., [6939, 15169]
    next_hop: str | None
    collector: str        # e.g., "rrc00"
    peer_ip: str | None
    peer_asn: int | None
    timestamp: datetime
    source: str           # "ris_live", "ripe_stat", "bgpstream"
    rpki_status: str | None

BGPEvent

Represents a BGP anomaly event:

@dataclass
class BGPEvent:
    type: EventType        # hijack, leak, blackhole
    severity: Severity     # low, medium, high
    affected_prefix: str
    affected_asn: int | None
    detected_at: datetime
    details: dict

Project Structure

src/bgp_explorer/
├── cli.py           # Click CLI entrypoint
├── agent.py         # AI agent orchestration
├── config.py        # Pydantic settings
├── output.py        # Output formatting
├── models/          # Data models
│   ├── route.py       # BGPRoute dataclass
│   └── event.py       # BGPEvent dataclass
├── cache/           # TTL cache implementation
│   └── cache.py       # Async-safe caching
├── sources/         # Data source clients
│   ├── base.py        # Abstract base class
│   ├── ripe_stat.py   # RIPE Stat REST API
│   ├── bgp_radar.py   # bgp-radar subprocess
│   ├── globalping.py  # Globalping REST API
│   ├── peeringdb.py   # PeeringDB data
│   └── monocle.py     # Monocle CLI wrapper
├── analysis/        # Analysis utilities
│   ├── path_analysis.py  # AS path analysis
│   └── as_analysis.py    # ASN relationship analysis
└── ai/              # AI backends
    ├── base.py      # Abstract base class
    ├── claude.py    # Claude implementation
    └── tools.py     # Tool definitions

Caching

The cache/ module provides an async-safe TTL cache:

• Default TTL: 5 minutes
• Caches RIPE Stat API responses
• Reduces API calls for repeated queries
• Thread-safe for concurrent access

Extended Thinking

Claude's extended thinking feature is used for deeper analysis:

• Thinking budget configurable (1024-16000 tokens)
• Summaries shown to user before responses
• Allows Claude to reason through complex investigations
• Historical thinking blocks excluded from context to save tokens

Error Handling

The system degrades gracefully:

• If a tool fails, investigation continues with available data
• Missing optional dependencies are handled at runtime
• API errors are caught and reported clearly
• Timeouts prevent hanging on unresponsive services

Next Steps

• Data Sources - Details on each data source
• Tools Reference - Complete tool documentation
• Contributing - Development setup