@nikeandocean/carbon-factor-matcher 0.2.0 → 0.2.1

package/src/carbon_factor_matcher/adapters/ecoinvent.py

@@ -1,292 +0,0 @@
-"""Adapter for ecoinvent Database Overview Excel files.
-
-Loads activity metadata from the ecoinvent Excel export and converts
-them into Factor objects for matching. CO2 values are placeholders (0.0)
-until Phase 2 fills them from the actual database.
-"""
-
-import logging
-from dataclasses import dataclass, field
-from pathlib import Path
-
-from carbon_factor_matcher.adapters.base import FactorAdapter
-from carbon_factor_matcher.models import Factor
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass
-class ImportResult:
-    """Result of an ecoinvent import operation."""
-    total_rows: int = 0
-    imported: int = 0
-    skipped: int = 0
-    errors: list[str] = field(default_factory=list)
-
-    @property
-    def success_rate(self) -> float:
-        """Calculate import success rate."""
-        if self.total_rows == 0:
-            return 0.0
-        return self.imported / self.total_rows
-
-# Sheet names for different system models
-SYSTEM_MODEL_SHEETS = {
-    "cut-off": "Cut-Off AO",
-    "cutoff": "Cut-Off AO",
-    "undefined": "Undefined AO",
-    "apos": "APOS AO",
-    "consequential": "Consequential AO",
-    "en15804": "EN15804 AO",
-}
-
-# Sectors to skip (not useful for emission factor matching)
-SKIP_SECTORS = {
-    "Waste Treatment & Recycling",
-}
-
-
-class EcoinventExcelAdapter(FactorAdapter):
-    """Load ecoinvent factors from the Database Overview Excel file.
-
-    Args:
-        excel_path: Path to the ecoinvent Excel file.
-        system_model: System model to load. One of: "cut-off", "undefined",
-            "apos", "consequential", "en15804". Default: "cut-off".
-        sectors: Optional list of sectors to include. If None, includes all.
-        geographies: Optional list of geography codes to include. If None, includes all.
-    """
-
-    def __init__(
-        self,
-        excel_path: str,
-        system_model: str = "cut-off",
-        sectors: list[str] | None = None,
-        geographies: list[str] | None = None,
-    ):
-        self._path = Path(excel_path)
-        if not self._path.exists():
-            raise FileNotFoundError(f"Excel file not found: {excel_path}")
-
-        sheet_name = SYSTEM_MODEL_SHEETS.get(system_model.lower())
-        if sheet_name is None:
-            raise ValueError(
-                f"Unknown system model '{system_model}'. "
-                f"Choose from: {list(SYSTEM_MODEL_SHEETS.keys())}"
-            )
-        self._sheet_name = sheet_name
-        self._sectors = set(sectors) if sectors else None
-        self._geographies = set(geographies) if geographies else None
-
-    def load(self) -> list[Factor]:
-        """Load factors from the Excel file."""
-        try:
-            import openpyxl
-        except ImportError:
-            raise ImportError(
-                "openpyxl is required for ecoinvent Excel adapter. "
-                "Install it with: pip install openpyxl"
-            )
-
-        logger.info(f"Loading ecoinvent from {self._path.name}, sheet={self._sheet_name}")
-        wb = openpyxl.load_workbook(self._path, read_only=True, data_only=True)
-
-        if self._sheet_name not in wb.sheetnames:
-            wb.close()
-            raise ValueError(
-                f"Sheet '{self._sheet_name}' not found. "
-                f"Available: {wb.sheetnames}"
-            )
-
-        ws = wb[self._sheet_name]
-        headers = [cell.value for cell in next(ws.iter_rows(min_row=1, max_row=1))]
-        col_map = {h: i for i, h in enumerate(headers) if h}
-
-        factors = []
-        skipped = 0
-
-        for row in ws.iter_rows(min_row=2, values_only=True):
-            row_list = list(row)
-
-            # Extract fields by header name
-            activity_uuid = self._get_col(row_list, col_map, "Activity UUID")
-            activity_name = self._get_col(row_list, col_map, "Activity Name")
-            geography = self._get_col(row_list, col_map, "Geography")
-            time_period = self._get_col(row_list, col_map, "Time Period")
-            sector = self._get_col(row_list, col_map, "Sector")
-            product_name = self._get_col(row_list, col_map, "Reference Product Name")
-            unit = self._get_col(row_list, col_map, "Unit")
-            isic = self._get_col(row_list, col_map, "ISIC Classification")
-
-            # Skip if missing essential fields
-            if not activity_uuid or not activity_name:
-                skipped += 1
-                continue
-
-            # Skip waste/infrastructure sectors
-            if sector in SKIP_SECTORS:
-                skipped += 1
-                continue
-
-            # Apply filters
-            if self._sectors and sector not in self._sectors:
-                skipped += 1
-                continue
-            if self._geographies and geography not in self._geographies:
-                skipped += 1
-                continue
-
-            # Parse year from time period (e.g., "2019 - 2023" → 2019)
-            source_year = self._parse_year(time_period)
-
-            # Build applicability from product info
-            applicability = product_name or activity_name
-
-            # Build category from sector + ISIC
-            category = sector or ""
-            if isic:
-                category = f"{sector}/{isic}" if sector else isic
-
-            factor = Factor(
-                id=activity_uuid,
-                name=activity_name,
-                category=category,
-                value=0.0,  # Placeholder — Phase 2 fills CO2 values
-                unit=unit or "",
-                geography={"location": geography or ""},
-                applicability=applicability,
-                source="ecoinvent 3.10",
-                source_year=source_year,
-                raw_data={
-                    "product_name": product_name,
-                    "isic": isic,
-                    "time_period": time_period,
-                    "system_model": self._sheet_name,
-                },
-            )
-            factors.append(factor)
-
-        wb.close()
-        logger.info(f"Loaded {len(factors)} ecoinvent factors (skipped {skipped})")
-        return factors
-
-    def load_with_result(self) -> tuple[list[Factor], ImportResult]:
-        """Load factors and return detailed import result.
-
-        Returns:
-            Tuple of (factors_list, import_result).
-        """
-        try:
-            import openpyxl
-        except ImportError:
-            raise ImportError(
-                "openpyxl is required for ecoinvent Excel adapter. "
-                "Install it with: pip install openpyxl"
-            )
-
-        logger.info(f"Loading ecoinvent from {self._path.name}, sheet={self._sheet_name}")
-        wb = openpyxl.load_workbook(self._path, read_only=True, data_only=True)
-
-        if self._sheet_name not in wb.sheetnames:
-            wb.close()
-            raise ValueError(
-                f"Sheet '{self._sheet_name}' not found. "
-                f"Available: {wb.sheetnames}"
-            )
-
-        ws = wb[self._sheet_name]
-        headers = [cell.value for cell in next(ws.iter_rows(min_row=1, max_row=1))]
-        col_map = {h: i for i, h in enumerate(headers) if h}
-
-        factors = []
-        errors = []
-        total = 0
-        skipped = 0
-
-        for row in ws.iter_rows(min_row=2, values_only=True):
-            total += 1
-            row_list = list(row)
-
-            try:
-                activity_uuid = self._get_col(row_list, col_map, "Activity UUID")
-                activity_name = self._get_col(row_list, col_map, "Activity Name")
-                geography = self._get_col(row_list, col_map, "Geography")
-                time_period = self._get_col(row_list, col_map, "Time Period")
-                sector = self._get_col(row_list, col_map, "Sector")
-                product_name = self._get_col(row_list, col_map, "Reference Product Name")
-                unit = self._get_col(row_list, col_map, "Unit")
-                isic = self._get_col(row_list, col_map, "ISIC Classification")
-
-                if not activity_uuid or not activity_name:
-                    skipped += 1
-                    continue
-
-                if sector in SKIP_SECTORS:
-                    skipped += 1
-                    continue
-
-                if self._sectors and sector not in self._sectors:
-                    skipped += 1
-                    continue
-                if self._geographies and geography not in self._geographies:
-                    skipped += 1
-                    continue
-
-                source_year = self._parse_year(time_period)
-                applicability = product_name or activity_name
-                category = sector or ""
-                if isic:
-                    category = f"{sector}/{isic}" if sector else isic
-
-                factor = Factor(
-                    id=activity_uuid,
-                    name=activity_name,
-                    category=category,
-                    value=0.0,
-                    unit=unit or "",
-                    geography={"location": geography or ""},
-                    applicability=applicability,
-                    source="ecoinvent 3.10",
-                    source_year=source_year,
-                    raw_data={
-                        "product_name": product_name,
-                        "isic": isic,
-                        "time_period": time_period,
-                        "system_model": self._sheet_name,
-                    },
-                )
-                factors.append(factor)
-
-            except Exception as e:
-                errors.append(f"Row {total}: {str(e)}")
-
-        wb.close()
-
-        result = ImportResult(
-            total_rows=total,
-            imported=len(factors),
-            skipped=skipped,
-            errors=errors,
-        )
-        logger.info(f"Loaded {len(factors)} ecoinvent factors (skipped {skipped})")
-
-        return factors, result
-
-    @staticmethod
-    def _get_col(row: list, col_map: dict, header: str) -> str | None:
-        """Get a column value by header name."""
-        idx = col_map.get(header)
-        if idx is None or idx >= len(row):
-            return None
-        val = row[idx]
-        return str(val).strip() if val else None
-
-    @staticmethod
-    def _parse_year(time_period: str) -> int:
-        """Extract start year from time period string like '2019 - 2023'."""
-        if not time_period:
-            return 0
-        try:
-            return int(time_period[:4])
-        except (ValueError, IndexError):
-            return 0

package/src/carbon_factor_matcher/api_client.py

@@ -1,94 +0,0 @@
-"""HTTP client for the Carbon Factor Matcher remote API."""
-
-import json
-import urllib.request
-import urllib.parse
-from typing import Optional
-
-from .models import Factor
-
-
-DEFAULT_API_URL = "https://paddle-webhook.nikeandocean.workers.dev/api"
-
-
-class FactorAPIClient:
-    """Client for the remote factor data API.
-
-    Args:
-        base_url: API base URL (default: Cloudflare Worker).
-    """
-
-    def __init__(self, base_url: str = DEFAULT_API_URL):
-        self.base_url = base_url.rstrip("/")
-
-    def _get(self, path: str, params: dict | None = None) -> dict:
-        """Make a GET request to the API."""
-        url = f"{self.base_url}{path}"
-        if params:
-            url += "?" + urllib.parse.urlencode(params)
-
-        req = urllib.request.Request(url, headers={"Accept": "application/json"})
-        with urllib.request.urlopen(req, timeout=30) as resp:
-            return json.loads(resp.read().decode("utf-8"))
-
-    def search(self, query: str, limit: int = 10, category: str | None = None) -> list[Factor]:
-        """Search for emission factors by keyword.
-
-        Args:
-            query: Search query (e.g., "electricity", "diesel").
-            limit: Maximum number of results (default: 10).
-            category: Optional category filter.
-
-        Returns:
-            List of matching Factor objects.
-        """
-        params = {"q": query, "limit": str(limit)}
-        if category:
-            params["category"] = category
-
-        data = self._get("/search", params)
-        factors_data = data.get("factors", [])
-        if not isinstance(factors_data, list):
-            return []
-        return [_dict_to_factor(f) for f in factors_data]
-
-    def get_factor(self, factor_id: str) -> Optional[Factor]:
-        """Get a factor by its ID.
-
-        Args:
-            factor_id: The unique factor identifier.
-
-        Returns:
-            Factor object or None if not found.
-        """
-        try:
-            data = self._get(f"/factor/{factor_id}")
-            if "error" in data:
-                return None
-            return _dict_to_factor(data)
-        except Exception:
-            return None
-
-    def stats(self) -> dict:
-        """Get database statistics."""
-        return self._get("/stats")
-
-
-def _dict_to_factor(d: dict) -> Factor:
-    """Convert API response dict to Factor object."""
-    return Factor(
-        id=d.get("id", ""),
-        name=d.get("name", ""),
-        category=d.get("category", ""),
-        value=d.get("value", 0.0),
-        unit=d.get("unit", ""),
-        geography=d.get("geography", {}),
-        applicability=d.get("applicability", ""),
-        source=d.get("source", ""),
-        source_year=d.get("source_year", 0),
-        quality_technical=d.get("quality_technical"),
-        quality_source=d.get("quality_source"),
-        quality_geographical=d.get("quality_geographical"),
-        quality_time=d.get("quality_time"),
-        quality_fairness=d.get("quality_fairness"),
-    )

package/src/carbon_factor_matcher/config.py

@@ -1,14 +0,0 @@
-from dataclasses import dataclass
-
-
-@dataclass
-class LLMConfig:
-    """Configuration for the LLM used in factor matching."""
-
-    api_key: str = ""
-    base_url: str = "https://api.deepseek.com"
-    model: str = "deepseek-chat"
-    max_tokens: int = 2048
-    embedding_model: str = "shibing624/text2vec-base-chinese"
-    license_key: str = ""
-    usage_db_path: str = "usage.db"

package/src/carbon_factor_matcher/factor_db.py

@@ -1,220 +0,0 @@
-import json
-import logging
-from pathlib import Path
-
-from carbon_factor_matcher.models import Factor
-
-logger = logging.getLogger(__name__)
-
-
-class FactorDatabase:
-    """Loads and queries emission factors from multiple data sources.
-
-    Supports loading from:
-    - JSON-LD ILCD files (ELCD format) via data_dir
-    - Custom adapters (ecoinvent Excel, etc.) via load_adapter()
-    """
-
-    def __init__(self, data_dir: str = "data/factors"):
-        self._data_dir = Path(data_dir)
-        self._factors: list[Factor] = []
-        self._by_id: dict[str, Factor] = {}
-        self._load()
-
-    def load_adapter(self, adapter) -> None:
-        """Load factors from a FactorAdapter.
-
-        Args:
-            adapter: A FactorAdapter instance (e.g., EcoinventExcelAdapter).
-        """
-        factors = adapter.load()
-        for f in factors:
-            if f.id in self._by_id:
-                logger.debug(f"Duplicate factor ID, skipping: {f.id}")
-                continue
-            self._factors.append(f)
-            self._by_id[f.id] = f
-        logger.info(f"Adapter loaded {len(factors)} factors, total now: {len(self._factors)}")
-
-    def _load(self) -> None:
-        """Load all JSON-LD ILCD files from the data directory."""
-        for json_file in self._data_dir.glob("**/*.json"):
-            try:
-                data = json.loads(json_file.read_text(encoding="utf-8"))
-                if isinstance(data, list):
-                    for item in data:
-                        self._try_add_process(item)
-                elif isinstance(data, dict):
-                    self._try_add_process(data)
-            except (json.JSONDecodeError, KeyError):
-                continue
-
-    def _try_add_process(self, data: dict) -> None:
-        """Try to parse a JSON-LD process into a Factor."""
-        if data.get("@type") != "Process":
-            return
-
-        factor = self._parse_process(data)
-        if factor:
-            self._factors.append(factor)
-            self._by_id[factor.id] = factor
-
-    def _parse_process(self, data: dict) -> Factor | None:
-        """Parse a JSON-LD ILCD Process into a Factor."""
-        process_id = data.get("@id", "")
-        name = data.get("name", "")
-        if not process_id or not name:
-            return None
-
-        # Extract geography - handle both formats
-        geography = {}
-        # Format 1: location at top level (ELCD 3.x)
-        if "location" in data and isinstance(data["location"], dict):
-            loc_name = data["location"].get("name", "")
-            if loc_name:
-                geography["location"] = loc_name
-        # Format 2: geography field
-        geo_data = data.get("geography", {})
-        if isinstance(geo_data, dict):
-            location = geo_data.get("location", "")
-            description = geo_data.get("description", "")
-            if location:
-                geography["location"] = location
-            if description:
-                geography["description"] = description
-
-        # Extract time - handle both formats
-        source_year = 0
-        # Format 1: processDocumentation.validFrom (ELCD 3.x)
-        doc = data.get("processDocumentation", {})
-        if isinstance(doc, dict):
-            valid_from = doc.get("validFrom", "")
-            if valid_from and len(valid_from) >= 4:
-                try:
-                    source_year = int(valid_from[:4])
-                except ValueError:
-                    pass
-            # Fallback to timeDescription
-            if source_year == 0:
-                time_desc = doc.get("timeDescription", "")
-                if time_desc and len(time_desc) >= 4:
-                    try:
-                        source_year = int(time_desc[:4])
-                    except ValueError:
-                        pass
-        # Format 2: time.startDate
-        time_data = data.get("time", {})
-        if isinstance(time_data, dict):
-            start = time_data.get("startDate", "")
-            if start and len(start) >= 4:
-                try:
-                    source_year = int(start[:4])
-                except ValueError:
-                    pass
-
-        # Extract category
-        category = data.get("category", "")
-
-        # Extract the reference exchange (main output/emission)
-        exchanges = data.get("exchanges", [])
-        value, unit = self._extract_reference_value(exchanges)
-
-        if value == 0:
-            return None
-
-        # Determine source from metadata
-        source = self._extract_source(data)
-
-        # Build applicability description
-        applicability = self._build_applicability(data)
-
-        return Factor(
-            id=process_id,
-            name=name,
-            category=category,
-            value=value,
-            unit=unit,
-            geography=geography,
-            applicability=applicability,
-            source=source,
-            source_year=source_year,
-            raw_data=data,
-        )
-
-    def _extract_reference_value(self, exchanges: list[dict]) -> tuple[float, str]:
-        """Extract the reference exchange value and unit."""
-        for ex in exchanges:
-            # Skip input exchanges
-            is_input = ex.get("isInput", ex.get("input", True))
-            if is_input:
-                continue
-            # Try different amount field names
-            result = ex.get("amount", ex.get("resultingAmount", 0))
-            if result > 0:
-                unit_ref = ex.get("unit", {})
-                unit = unit_ref.get("name", "") if isinstance(unit_ref, dict) else ""
-                return float(result), unit
-        return 0.0, ""
-
-    def _extract_source(self, data: dict) -> str:
-        """Extract data source information."""
-        # Check processDocumentation first (ELCD 3.x format)
-        doc = data.get("processDocumentation", {})
-        if isinstance(doc, dict):
-            for key in ("dataGenerator", "publication", "dataSetOwner"):
-                if key in doc:
-                    ref = doc[key]
-                    if isinstance(ref, dict) and "name" in ref:
-                        return ref["name"]
-                    if isinstance(ref, str):
-                        return ref
-        # Fallback to top-level fields
-        for key in ("dataGenerator", "publication", "commissioner"):
-            if key in data:
-                ref = data[key]
-                if isinstance(ref, dict) and "name" in ref:
-                    return ref["name"]
-                if isinstance(ref, str):
-                    return ref
-        return "Unknown"
-
-    def _build_applicability(self, data: dict) -> str:
-        """Build an applicability description from process metadata."""
-        parts = []
-        # Check processDocumentation first (ELCD 3.x format)
-        doc = data.get("processDocumentation", {})
-        if isinstance(doc, dict):
-            tech_desc = doc.get("technologyDescription", "")
-            if tech_desc:
-                parts.append(tech_desc)
-            geo_desc = doc.get("geographyDescription", "")
-            if geo_desc:
-                parts.append(geo_desc)
-        # Fallback to top-level fields
-        if "technology" in data:
-            tech = data["technology"]
-            if isinstance(tech, dict) and "description" in tech:
-                parts.append(tech["description"])
-        if "geography" in data:
-            geo = data["geography"]
-            if isinstance(geo, dict) and "description" in geo:
-                parts.append(geo["description"])
-        return "; ".join(parts) if parts else data.get("name", "")
-
-    @property
-    def factors(self) -> list[Factor]:
-        return list(self._factors)
-
-    def search(self, query: str) -> list[Factor]:
-        """Simple keyword search across factor name, category, applicability."""
-        query_lower = query.lower()
-        return [
-            f for f in self._factors
-            if query_lower in f.name.lower()
-            or query_lower in f.category.lower()
-            or query_lower in f.applicability.lower()
-        ]
-
-    def get_by_id(self, factor_id: str) -> Factor | None:
-        """Get a factor by its ID."""
-        return self._by_id.get(factor_id)