Metadata-Version: 2.4
Name: netwlens
Version: 1.3.2
Summary: Network topology visualization and analysis tool with comprehensive data validation
License: MIT
License-File: LICENSE
Keywords: network,topology,visualization,ipfabric,graphviz,validation,analysis
Author: IP Fabric Solution Architecture Team
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Requires-Dist: graphviz (>=0.20.0)
Requires-Dist: ipfabric (>=7.0.0)
Requires-Dist: loguru (>=0.6.0)
Requires-Dist: python-dotenv (>=1.0.0)
Project-URL: Documentation, https://gitlab.com/ip-fabric/integrations/netwlens#readme
Project-URL: Homepage, https://www.ipfabric.io
Project-URL: Issues, https://support.ipfabric.io
Project-URL: Repository, https://gitlab.com/ip-fabric/integrations/netwlens
Description-Content-Type: text/markdown

# Netwlens - Network Topology Visualization

A Python package for network topology visualization and analysis with IP Fabric integration. Features comprehensive data validation, automatic root device selection, and intelligent topology discovery.

## Smart Network Visualization

<img src="docs/img/smart-visualization.png" alt="Site Topology Example">

## Installation

### For Users

```bash
# Install with Poetry (recommended)
pip install poetry  # if you don't have Poetry installed
poetry add netwlens

# Or using pip
pip install netwlens
```

### For Developers

```bash
# Clone the repository
git clone <repository-url>
cd netwlens

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install with Poetry (recommended)
pip install poetry  # if you don't have Poetry installed
poetry install

# Or using pip
pip install -e .
```

## Quick Start

```python
from netwlens import DataCollector, DataVisualizer

# Collect site-specific network data
collector = DataCollector()
data_dir = collector.collect_site_data(
    site="London-3X",
    protocol="cdp",
    output="mynetwork"
)

# Or collect all inventory data (NEW!)
data_dir = collector.collect_data(
    site_name=None,  # None = all inventory
    protocol="cdp",
    output="all-network"
)

# Create visualization with automatic root selection (NEW!)
visualizer = DataVisualizer()
viz_path = visualizer.create_topology(
    input_dir=data_dir,
    # Automatically selects device with most connections
    format_type="svg"
)
```

## CLI Usage

```bash
# Collect site-specific data
netwlens collect --site London-3X --protocol cdp --output mynetwork

# Collect all inventory data (NEW!)
netwlens collect --protocol cdp --output all-data

# Create visualization with auto root selection (NEW!)
netwlens visualize --input netwlens_data/mynetwork

# Create visualization with manual root selection
netwlens visualize --input netwlens_data/mynetwork --root core-switch
```

## Output Structure

```
netwlens_data/
├── mynetwork/                      # Data collection output
│   ├── inventory.json              # Device inventory
│   ├── connections_raw.json        # Raw connections from IP Fabric
│   ├── connections_normalized.json # Processed connections (enriched + deduplicated)
│   └── topology/                   # Visualization output
│       ├── topology_hierarchical.svg
│       ├── topology_hierarchical.png
│       └── view_svg_topology.html
```

## Key Features

### 🔄 Flexible Data Collection
- **Site-Specific Collection**: Extract data for specific network sites
- **All Inventory Collection**: Collect data from entire network infrastructure
- **Protocol Support**: CDP, LLDP, and CEF protocols
- **Comprehensive Data Validation**: Multi-layer validation ensures data quality (NEW!)
- **Backward Compatibility**: Existing APIs preserved while adding new capabilities

### 🎯 Smart Visualization
- **Automatic Root Selection**: Intelligently selects device with most connections as topology root
- **Data Quality Assurance**: Automatic validation before visualization with detailed error reporting (NEW!)
- **Connectivity Analysis**: Device relationship validation and protocol consistency checks (NEW!)
- **Manual Root Override**: Specify custom root device when needed
- **Clean Orthogonal Layouts**: Professional diagrams with 90-degree connections
- **Multiple Output Formats**: SVG, PNG, and interactive HTML viewers
- **Smart Logging**: Connection analysis, validation summary, and root selection rationale

### 🛡️ Data Validation (NEW!)
- **Multi-Layer Validation**: File existence → JSON structure → Data quality → Visualization readiness
- **Quality Metrics**: Connected vs isolated devices, missing device detection, protocol consistency
- **Early Error Detection**: Comprehensive validation before expensive graph operations
- **Actionable Feedback**: Clear error messages explaining exactly what needs to be fixed
- **Smart Warnings**: Non-blocking issues like isolated devices are flagged appropriately

### 🏗️ Developer-Friendly
- **Simple API**: Clean `DataCollector` and `DataVisualizer` classes
- **Robust Validation**: Dedicated `DataValidator` class with comprehensive checks
- **CLI Interface**: Modern subcommand-based command line tools with built-in validation
- **Package Installation**: Standard `pip install` workflow
- **Comprehensive Documentation**: Detailed API docs and examples

## Requirements

- Python 3.11+
- IP Fabric access (for data collection)
- Graphviz (for visualization)
- Poetry (recommended) or pip

## Configuration

Set your IP Fabric credentials in environment variables or `.env` file:

```bash
IPF_URL=https://your-ipfabric-instance.com
IPF_TOKEN=your-api-token
```

For detailed documentation, see the `docs/` directory or visit the project repository.

