@nikeandocean/carbon-factor-matcher 0.2.0

package/src/carbon_factor_matcher/api_client.py

@@ -0,0 +1,94 @@
+"""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

@@ -0,0 +1,14 @@
+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

@@ -0,0 +1,220 @@
+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)

package/src/carbon_factor_matcher/license.py

@@ -0,0 +1,80 @@
+"""License management for Carbon Factor Matcher MCP server."""
+
+from enum import Enum
+from typing import Optional
+
+
+class LicenseTier(Enum):
+    """License tier levels."""
+
+    FREE = "free"
+    PRO = "pro"
+
+
+# Daily query limits per tier (None = unlimited)
+TIER_DAILY_LIMIT: dict[LicenseTier, Optional[int]] = {
+    LicenseTier.FREE: 300,
+    LicenseTier.PRO: None,
+}
+
+UPGRADE_HINT = (
+    "\n\n---\n"
+    "Daily free query limit reached (300/day). "
+    "Upgrade to Pro ($5 one-time) for unlimited queries + ecoinvent + hybrid matching.\n"
+    "Purchase: https://nikeandocean.github.io/carbon-factor-matcher"
+)
+
+
+class LicenseManager:
+    """Manage user license and feature access.
+
+    One-time purchase model (no expiration):
+    - free: ELCD only, basic search, 300 queries/day
+    - pro: ELCD + ecoinvent, hybrid matching, unlimited queries
+
+    Args:
+        license_key: License key string. Empty = free tier (no key needed).
+
+    Raises:
+        ValueError: If key format is invalid (looks like a key but isn't PRO-*).
+    """
+
+    def __init__(self, license_key: str = ""):
+        self.key = license_key
+        self.tier = self._parse_tier(license_key)
+
+    def _parse_tier(self, key: str) -> LicenseTier:
+        """Parse tier from license key prefix.
+
+        Key format: {TIER}-{RANDOM}-{TIMESTAMP}
+        Examples:
+        - PRO-KEY-123 -> PRO
+        - "" -> FREE
+        - (no key) -> FREE
+
+        Raises ValueError for malformed keys (e.g., "XXX-abc", "garbage-123").
+        """
+        if not key:
+            return LicenseTier.FREE
+        if "-" not in key:
+            return LicenseTier.FREE
+        prefix = key.split("-")[0].upper()
+        if prefix == "PRO":
+            return LicenseTier.PRO
+        raise ValueError(
+            f"Invalid license key prefix '{prefix}'. "
+            f"Expected 'PRO-*'. Get a key at https://nikeandocean.github.io/carbon-factor-matcher"
+        )
+
+    @property
+    def daily_limit(self) -> Optional[int]:
+        """Return max daily queries. None = unlimited."""
+        return TIER_DAILY_LIMIT[self.tier]
+
+    def can_use_ecoinvent(self) -> bool:
+        """Check if current tier can use ecoinvent data."""
+        return self.tier == LicenseTier.PRO
+
+    def can_use_advanced_matching(self) -> bool:
+        """Check if current tier can use hybrid matching + quality rating."""
+        return self.tier == LicenseTier.PRO