[PRE-TASK] Completing the Restoration of PCB-AoI: Addressing API Drift and Dependency Regressions

[phantom-712]

Pre-test for LFX Mentorship 2026 Term 1

CNCF - KubeEdge: Ianvs: Comprehensive Example Restoration (2026 Term 1)

[Proposal] Completing the Restoration of PCB-AoI: Addressing API Drift and Dependency Regressions

---

1. Background

1.1 Example Selection and Context

I have selected the PCB-AoI (Printed Circuit Board - Automated Optical Inspection) benchmark located in examples/pcb-aoi/ for this proposal. This example demonstrates edge-native incremental learning for industrial quality control, a critical use case for KubeEdge Ianvs in manufacturing environments.

1.2 Acknowledging Previous Efforts

I recognize that Issue #170 and subsequent pull requests (#174, #182) made valuable contributions to improving the PCB-AoI example, particularly in addressing file path compatibility issues. These efforts represent important steps toward restoring the benchmark functionality. However, my investigation reveals that despite these improvements, the example remains non-functional on modern Python environments due to unresolved dependency incompatibilities and data provisioning gaps.

1.3 The Critical Problem: API Drift and Missing Dependencies

After attempting to execute the benchmark on a fresh Python 3.9 environment following the current documentation, I encountered multiple cascading failures that prevent successful execution. These failures fall into three categories: API incompatibility, missing runtime dependencies, and data provisioning gaps.

First Layer: API Contract Violation

The benchmark immediately crashes during module import with the following error:

File "F:\KubeEdge\ianvs\core\testenvmanager\dataset\dataset.py", line 21
  from sedna.datasources import BaseDataSource
ModuleNotFoundError: No module named 'sedna.datasources'

This error occurs because the Ianvs codebase imports sedna.datasources.BaseDataSource, which existed in Sedna v0.1.0 but was restructured to sedna.core.base.BaseDataSource in Sedna v0.1.2 and later releases. When users install Sedna via pip install sedna today, they receive version 0.1.2 or later by default, creating an immediate incompatibility with the hardcoded legacy imports in Ianvs.

I verified this by examining the Sedna library source code across multiple versions. The module restructuring occurred between v0.1.1 and v0.1.2 as part of a broader refactoring of the Sedna architecture. The Ianvs import statements were never updated to reflect this change, creating a brittle dependency on a specific legacy version that is no longer the default installation.

Second Layer: Missing Runtime Dependencies

Even after attempting to resolve the Sedna import issue, the benchmark fails due to missing libraries that are imported but not declared in requirements.txt:

ModuleNotFoundError: No module named 'prettytable'
ModuleNotFoundError: No module named 'colorlog'

These libraries are used for formatting output and logging within the benchmark code but are absent from the dependency manifest. Additionally, while pandas is imported for data processing operations, it is not consistently declared across all requirement files, leading to inconsistent installation experiences.

Third Layer: Data Provisioning Failure

The configuration file examples/pcb-aoi/testenv.yaml references local dataset paths that do not exist in the repository:

FileNotFoundError: [Errno 2] No such file or directory: './dataset/train_data/index.txt'

The configuration contains only relative paths but completely omits the dataset_url field that would enable automated dataset download. While Issue #170 addressed some path compatibility concerns, it did not resolve the fundamental issue that new users have no mechanism to acquire the required dataset files. The benchmark documentation provides no instructions for dataset acquisition, and no automated download functionality exists in the codebase.

I created a verification script to simulate the data loading process, confirming that the current implementation provides no fallback mechanism when local files are missing and no guidance to users on how to obtain the data.

Fourth Layer: Runtime Type Mismatch

During the training phase, assuming previous errors could be bypassed, the benchmark encounters type incompatibility:

AttributeError: 'numpy.ndarray' object has no attribute 'groupby'

The legacy data processing logic assumes Pandas DataFrames with methods like groupby, but modern data loaders return NumPy arrays, causing the code to attempt Pandas-specific operations on incompatible types.

1.4 Why Previous Fixes Were Insufficient

Issue #170 and its associated pull requests focused primarily on file path corrections and structural improvements. While these changes were necessary, they did not address the fundamental architectural incompatibilities that prevent execution on modern dependency environments. Specifically:

• The import statements remain hardcoded to the legacy Sedna API, making the code incompatible with current Sedna releases.
• Missing libraries in the dependency manifest create unpredictable installation failures.
• The data provisioning mechanism still relies entirely on pre-existing local files without providing acquisition pathways.
• Type assumptions in the data processing pipeline have not been updated to handle modern library behaviors.

This proposal builds upon the foundation established by Issue #170 while addressing the remaining critical gaps that prevent the benchmark from functioning in production environments.

1.5 Debug Process and Verification

My debugging followed a systematic approach. First, I set up a clean Python 3.9 environment and attempted to execute the benchmark following current documentation exactly. Second, I traced the Sedna API evolution by examining source code across versions v0.1.0 through v0.1.3 on GitHub and PyPI. Third, I created minimal reproduction cases isolating each import failure. Fourth, I compared the PCB-AoI configuration structure against other functional examples in the repository to identify missing fields. Fifth, I tested dependency installation across multiple environments to confirm which libraries were missing from the manifest.

1.6 Impact Assessment

User Experience Impact: Developers attempting to evaluate Ianvs for industrial edge AI applications encounter immediate, blocking failures with unclear error messages. This creates a negative first impression and may lead potential contributors to abandon the project.

Core Architecture Impact: The dependency mismatch reveals broader concerns about version management and API stability throughout the Ianvs ecosystem. Tight coupling to specific library versions without compatibility layers creates ongoing maintenance burden.

Example Ecosystem Impact: PCB-AoI serves as the reference implementation for industrial computer vision at the edge. Its non-functional state means that entire categories of high-value use cases (defect detection, quality control, visual inspection) lack working demonstrations.

Platform Compatibility Impact: Hardcoded POSIX paths in some areas fail on Windows systems, violating the cross-platform promise essential for heterogeneous edge environments where development happens on various operating systems.

This issue represents a critical blocker for new contributors and industrial adopters. The urgency is high because the PCB-AoI use case demonstrates core KubeEdge value propositions, and its current state undermines the credibility of the Ianvs benchmarking platform.

---

2. Goals

Goal 1: Modernize Import Statements and API Compatibility
Implement version-aware import compatibility layers that support both legacy Sedna v0.1.0 and modern v0.1.2+ releases. This will involve refactoring sedna.datasources imports to use sedna.core.base while maintaining backward compatibility for environments still using older versions.

Goal 2: Complete Dependency Manifest
Add all missing runtime dependencies to requirements.txt, including prettytable, colorlog, and explicit pandas declarations. Establish version constraints that ensure consistent installation experiences across different environments.

Goal 3: Restore Data Pipeline with Automated Provisioning
Implement complete data acquisition infrastructure including dataset_url fields in configuration, automated download mechanisms with integrity verification, and clear error messaging when data is unavailable.

Goal 4: Fix Runtime Type Mismatches
Implement type-safe data processing that gracefully handles both Pandas DataFrames and NumPy arrays, ensuring the benchmark executes successfully regardless of which data structure the loaders return.

Goal 5: Establish Preventive Infrastructure
Contribute CI workflows validating all examples on multiple platforms and Python versions, preventing future dependency drift and ensuring sustained functionality.

---

3. Scope

3.1 Target Users

Primary users are industrial IoT practitioners and edge AI engineers evaluating Ianvs for manufacturing, quality control, and automated inspection scenarios. These users operate in heterogeneous environments mixing Windows development workstations with Linux edge devices, requiring benchmarks that work reliably across platforms.

Secondary users are academic researchers studying distributed machine learning and incremental learning algorithms. These researchers need stable, reproducible benchmarks to evaluate proposed methods against established baselines.

3.2 Differentiation from Existing Issues

While Issue #170 addressed file path compatibility, this proposal focuses on the unresolved dependency and API compatibility problems that continue to block execution. The key differentiators are:

API Modernization: Issue #170 did not address the sedna.datasources to sedna.core.base migration. This proposal implements compatibility adapters supporting multiple Sedna versions.

Complete Dependency Declaration: Previous work did not identify missing libraries like prettytable and colorlog. This proposal ensures the manifest is comprehensive.

Data Acquisition Infrastructure: Issue #170 corrected paths but did not solve the fundamental problem that users cannot obtain the dataset. This proposal implements automated download mechanisms.

Preventive Measures: This proposal extends beyond immediate fixes to establish CI infrastructure preventing future regressions across the entire example ecosystem.

---

4. Detailed Design

4.1 Architecture Overview

This project focuses on three layers of the Ianvs architecture. At the core module layer, modifications target core/testenvmanager/dataset/dataset.py and core/testenvmanager/testenv.py for compatibility shims and download handlers. At the configuration layer, updates focus on examples/pcb-aoi/testenv.yaml for provisioning metadata. At the testing layer, new CI workflows in .github/workflows/ provide automated validation.

4.2 Module-Specific Design Details

Dependency Compatibility Adapter

The current import pattern in dataset.py line 21 is:

from sedna.datasources import BaseDataSource

I will implement a version-aware compatibility adapter using cascading try-except blocks:

# Compatibility adapter for Sedna API evolution
try:
    # Attempt modern Sedna v0.1.2+ import path
    from sedna.core.base import BaseDataSource
except ModuleNotFoundError:
    try:
        # Fallback to legacy Sedna v0.1.0 import path
        from sedna.datasources import BaseDataSource
    except ModuleNotFoundError:
        raise ImportError(
            "Failed to import BaseDataSource from Sedna. "
            "Please ensure Sedna is installed: pip install sedna"
        )

This pattern prioritizes the modern API while providing graceful degradation for legacy installations. The approach maintains forward compatibility without forcing users to install outdated library versions. This adapter will be applied consistently across all modules importing from Sedna, including module.py and algorithm implementation files.

Complete Dependency Manifest

The current requirements.txt will be updated to include all runtime dependencies with appropriate version constraints:

sedna>=0.1.0
prettytable>=3.0.0
colorlog>=6.0.0
pandas>=1.3.0
numpy>=1.21.0

Version constraints use lower bounds to ensure minimum feature availability while allowing users to benefit from bug fixes in newer releases. I will test these constraints across Python 3.8, 3.9, 3.10, and 3.11 to verify compatibility.

Automated Data Provisioning System

The TestEnvManager class will be extended with an ensure_dataset() method that executes before benchmark initialization:

import urllib.request
import tarfile
import hashlib
from pathlib import Path

def ensure_dataset(config):
    dataset_dir = Path("./dataset")
    
    # Check if dataset already exists
    if dataset_dir.exists() and list(dataset_dir.glob("**/index.txt")):
        return
    
    # Download and extract dataset
    for split in ["train", "test"]:
        url = config.get(f"{split}_url")
        expected_sha256 = config.get(f"{split}_sha256")
        
        if not url:
            raise ValueError(f"Missing {split}_url in configuration")
        
        print(f"Downloading {split} dataset from {url}...")
        archive_path = dataset_dir / f"{split}_data.tar.gz"
        
        # Download with progress reporting
        urllib.request.urlretrieve(url, archive_path)
        
        # Verify integrity
        if expected_sha256:
            actual_sha256 = hashlib.sha256(archive_path.read_bytes()).hexdigest()
            if actual_sha256 != expected_sha256:
                raise ValueError(f"Checksum mismatch for {split} dataset")
        
        # Extract archive
        with tarfile.open(archive_path, 'r:gz') as tar:
            tar.extractall(dataset_dir)

The corresponding configuration update for examples/pcb-aoi/testenv.yaml:

dataset:
  train_url: "https://kubeedge-ianvs-dataset.obs.cn-north-1.myhuaweicloud.com/pcb-aoi/train_data.tar.gz"
  train_sha256: "abc123..."
  test_url: "https://kubeedge-ianvs-dataset.obs.cn-north-1.myhuaweicloud.com/pcb-aoi/test_data.tar.gz"
  test_sha256: "def456..."
  train_data:
    - "./dataset/train_data/index.txt"
  test_data:
    - "./dataset/test_data/index.txt"

Type-Safe Data Processing

The runtime type mismatch will be resolved by implementing defensive type checking in the data processing pipeline:

import numpy as np
import pandas as pd

def safe_groupby(data, column):
    """
    Type-safe groupby operation supporting both NumPy arrays and Pandas DataFrames.
    
    Args:
        data: Input data as NumPy array or Pandas DataFrame
        column: Column name or index for grouping
    
    Returns:
        Pandas GroupBy object
    """
    if isinstance(data, np.ndarray):
        # Convert NumPy array to DataFrame for compatibility
        if data.ndim == 1:
            data = pd.DataFrame({column: data})
        else:
            data = pd.DataFrame(data)
    
    return data.groupby(column)

This pattern will be applied wherever DataFrame-specific methods are invoked on potentially incompatible types, maintaining backward compatibility while supporting modern data loader implementations.

Cross-Platform Path Handling

All hardcoded POSIX paths will be replaced with platform-agnostic alternatives using pathlib.Path:

from pathlib import Path

# Before: data_dir = "/root/data"
# After:
data_dir = Path.home() / "ianvs_data"
data_dir.mkdir(parents=True, exist_ok=True)

4.3 Core versus Example Modifications

The dependency compatibility adapter belongs in the core because all Sedna-using examples will face identical API drift as the library evolves. Implementing this once in the core prevents code duplication and ensures consistent behavior.

The automated data provisioning system also belongs in core infrastructure because dataset hosting and download is a common requirement across all examples. Future examples can adopt this pattern without reimplementing download logic.

The specific dataset URLs and checksums for PCB-AoI remain in example-specific configuration, but the format and schema are standardized in the core to promote consistency.

The type-safe data processing wrappers belong in the core because the type mismatches stem from the core data loading pipeline returning structures that downstream code does not expect.

---

5. Road Map

Phase 1: Stabilization and Dependency Resolution (Weeks 1-4)

Week 1: Comprehensive Dependency Audit

Conduct systematic audit of all Sedna API usage across the Ianvs codebase, documenting every import statement and the expected API surface. Create a dependency matrix showing which Ianvs modules depend on which Sedna interfaces. Set up Dockerized reference environment (Ubuntu 22.04, Python 3.9) for reproducible testing.

Deliverable: Dependency audit report and Dockerfile for reference environment.

Week 2: Implement Compatibility Adapter

Implement version-aware import system in dataset.py and extend to all Sedna-importing modules. Test compatibility layer against Sedna versions v0.1.0, v0.1.1, v0.1.2, v0.1.3, and latest release in isolated environments.

Deliverable: Pull request containing compatibility layer with unit tests verifying correct behavior across Sedna versions.

Week 3: Complete Dependency Manifest

Update requirements.txt with all missing libraries (prettytable, colorlog, explicit pandas). Establish version constraints through testing against multiple library versions. Document compatibility matrix in docs/dependency-compatibility.md.

Deliverable: Updated requirements file with version constraints and comprehensive dependency documentation.

Week 4: Unit Testing Infrastructure

Create comprehensive test suite for import resolution and dependency handling using pytest with parameterized fixtures. Achieve minimum 90 percent coverage of compatibility layer code. Verify tests pass on all supported Sedna versions.

Deliverable: Test suite passing on all supported Sedna versions with documented coverage metrics.

Phase 2: Data Engineering and Pipeline Restoration (Weeks 5-8)

Week 5: Dataset Identification and Hosting

Locate canonical PCB-AoI dataset, verify licensing terms and data quality. Coordinate with KubeEdge maintainers to arrange hosting on project infrastructure (Huawei Cloud OBS or alternative stable platform). Calculate storage requirements and establish access controls.

Deliverable: Hosted, publicly accessible dataset with documented licensing and stable URL.

Week 6: Download Handler Implementation

Implement automated download and extraction logic in core data management module. Include progress reporting, SHA256 checksum verification, and comprehensive error handling for network failures. Document process for example maintainers adding download functionality to their examples.

Deliverable: Functional data download system integrated into Ianvs core with user feedback mechanisms.

Week 7: Runtime Logic Fixes

Address NumPy versus Pandas type mismatches by implementing defensive type checking in data processing pipeline. Add type annotations to all data processing functions. Integrate mypy for static type checking during development.

Deliverable: Type-safe processing pipeline with comprehensive annotations passing mypy validation.

Week 8: Data Validation System

Implement automated validation verifying downloaded dataset integrity. Check expected sample counts in training and test splits, validate metadata file presence and formatting, detect data leakage between splits. Document expected data schema for future reference.

Deliverable: Automated dataset validation system running during benchmark initialization.

Phase 3: Validation and Continuous Integration (Weeks 9-12)

Week 9: Cross-Platform Testing

Execute comprehensive testing on Windows 11, Ubuntu 22.04, and macOS 13 across Python versions 3.8, 3.9, 3.10, and 3.11. Test both x86-64 and ARM64 architectures where applicable. Document all platform-specific issues and implement fixes.

Deliverable: Compatibility report documenting successful execution on all target platforms with platform-specific fixes if needed.

Week 10: Systematic Path Refactoring

Conduct comprehensive refactoring of all path manipulation code to use pathlib. Implement pre-commit linting rule preventing use of os.path.join in new code to prevent regression.

Deliverable: Fully refactored codebase with consistent platform-agnostic path handling.

Week 11: GitHub Actions CI Pipeline

Create comprehensive CI workflow using GitHub Actions with matrix strategy testing multiple Python versions and operating systems. Include steps for environment setup, dependency installation, example execution, and result validation. Configure detailed logging for failed runs.

Deliverable: Functioning CI pipeline providing automated validation and clear feedback on pull requests.

Week 12: Documentation and Knowledge Transfer

Update PCB-AoI README with detailed setup instructions. Create troubleshooting guide for common issues. Document architectural decisions made during restoration. Produce video tutorial demonstrating complete benchmark execution from setup through results.

Deliverable: Comprehensive documentation covering setup, execution, troubleshooting, and maintenance with recorded tutorial.

---

6. Success Criteria

• Zero Installation Errors: Fresh Python environments should execute the benchmark without import or dependency failures across Python 3.8 through 3.11.

• Automated Data Acquisition: Benchmark should download and verify datasets automatically on first execution without user intervention.

• Cross-Platform Execution: Successful execution on Windows, Linux, and macOS with identical results and no platform-specific errors.

• CI Pipeline Coverage: All Ianvs examples pass automated validation on every commit to main branch.

• Documentation Completeness: New contributors with basic Python knowledge should complete setup and execution in under 30 minutes.

---

7. Conclusion

I am genuinely excited about the opportunity to contribute to KubeEdge Ianvs through this mentorship program. The PCB-AoI benchmark represents a critical use case for industrial edge AI, and completing its restoration will significantly strengthen the Ianvs example ecosystem.

I deeply respect the work accomplished in Issue #170 and its associated pull requests. Those efforts established important foundations in path compatibility and structural improvements. This proposal builds directly upon that foundation by addressing the remaining dependency and API compatibility gaps that continue to prevent successful execution in modern environments.

My investigation has provided comprehensive insight into the Ianvs architecture and the challenges of maintaining a complex example ecosystem as dependencies evolve. I am confident that the systematic approach outlined in this proposal will not only restore the PCB-AoI benchmark to full functionality but also establish patterns and infrastructure that prevent similar issues across other examples.

I am committed to delivering high-quality, maintainable code that upholds the standards of the KubeEdge community. I look forward to working closely with mentors and maintainers throughout this 12-week program and contributing meaningfully to the long-term success of the Ianvs project.

Thank you for considering this proposal.

---

By -

Ansuman Patra
Sophomore, IIT BHU (Varanasi)
ansumanpatra10@gmail.com