@nikeandocean/carbon-factor-matcher 0.2.0

package/src/carbon_factor_matcher/models.py

@@ -0,0 +1,71 @@
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Factor:
+    """An emission factor from an LCA database."""
+
+    id: str
+    name: str
+    category: str
+    value: float
+    unit: str
+    geography: dict[str, str]
+    applicability: str
+    source: str
+    source_year: int
+    scope: int | None = None
+    uncertainty: str | None = None
+    notes: str | None = None
+    quality_technical: float | None = None
+    quality_source: float | None = None
+    quality_geographical: float | None = None
+    quality_time: float | None = None
+    quality_fairness: float | None = None
+    raw_data: dict | None = field(default=None, repr=False)
+
+
+@dataclass
+class Activity:
+    """User activity data for emission factor matching.
+
+    Example:
+        Activity(
+            name="工业用电",
+            location="上海市",
+            time="2024",
+            unit="kWh",
+            amount=1000,
+            technology="火力发电",
+        )
+    """
+
+    name: str                           # 活动名称 (e.g., "工业用电")
+    unit: str                           # 单位 (e.g., "kWh")
+    location: str = ""                  # 地点 (e.g., "上海市")
+    time: str = ""                      # 时间 (e.g., "2024")
+    amount: float = 0.0                 # 数量
+    technology: str = ""                # 工艺/技术 (e.g., "火力发电")
+    category: str = ""                  # 行业分类 (e.g., "制造业")
+
+    def to_query(self) -> str:
+        """Build search query string from activity fields."""
+        parts = []
+        if self.location:
+            parts.append(self.location)
+        if self.technology:
+            parts.append(self.technology)
+        parts.append(self.name)
+        if self.category:
+            parts.append(self.category)
+        return " ".join(parts)
+
+
+@dataclass
+class MatchResult:
+    """Result of a factor matching operation."""
+
+    factor: Factor
+    reason: str
+    confidence: float
+    candidates: list[Factor]

package/src/carbon_factor_matcher/server.py

@@ -0,0 +1,232 @@
+"""Carbon Factor Matcher MCP server.
+
+Uses remote API for factor data, local LLM for Pro matching.
+"""
+
+import os
+import json
+from mcp.server.fastmcp import FastMCP
+
+from carbon_factor_matcher.api_client import FactorAPIClient
+from carbon_factor_matcher.matcher import EmissionFactorMatcher
+from carbon_factor_matcher.config import LLMConfig
+from carbon_factor_matcher.license import LicenseManager
+from carbon_factor_matcher.usage_tracker import UsageTracker
+
+
+def create_server(
+    api_url: str | None = None,
+    api_client: FactorAPIClient | None = None,
+    llm_api_key: str | None = None,
+    llm_base_url: str | None = None,
+    llm_model: str | None = None,
+    embedding_model: str | None = None,
+    license_key: str | None = None,
+    usage_db_path: str | None = None,
+) -> FastMCP:
+    """Create and configure the MCP server."""
+
+    # Resolve config from env vars or defaults
+    _default_db = os.path.join(os.path.expanduser("~"), ".carbon-factor-matcher", "usage.db")
+    config = LLMConfig(
+        api_key=llm_api_key or os.environ.get("LLM_API_KEY", ""),
+        base_url=llm_base_url or os.environ.get("LLM_BASE_URL", "https://api.deepseek.com"),
+        model=llm_model or os.environ.get("LLM_MODEL", "deepseek-chat"),
+        embedding_model=embedding_model or os.environ.get(
+            "EMBEDDING_MODEL", "shibing624/text2vec-base-chinese"
+        ),
+        license_key=license_key or os.environ.get("CARBON_FACTOR_LICENSE_KEY", ""),
+        usage_db_path=usage_db_path or os.environ.get(
+            "CARBON_FACTOR_USAGE_DB", _default_db
+        ),
+    )
+
+    # Initialize components
+    if api_client is None:
+        api_url = api_url or os.environ.get(
+            "CARBON_FACTOR_API_URL",
+            "https://paddle-webhook.nikeandocean.workers.dev/api",
+        )
+        api_client = FactorAPIClient(base_url=api_url)
+    license_mgr = LicenseManager(license_key=config.license_key)
+    usage_tracker = UsageTracker(db_path=config.usage_db_path)
+    user_id = _hash_key(config.license_key)
+
+    # Create MCP server
+    mcp = FastMCP("carbon-factor-matcher")
+
+    def _check_limit(tool_name: str) -> str | None:
+        """Check daily query limit. Returns error if exceeded, None if OK."""
+        limit = license_mgr.daily_limit
+        if limit is not None:
+            daily = usage_tracker.get_daily_usage(user_id)
+            if daily >= limit:
+                return json.dumps({
+                    "error": f"Daily free limit reached ({limit}/day). Upgrade to Pro for unlimited.",
+                    "purchase": "https://nikeandocean.github.io/carbon-factor-matcher",
+                }, ensure_ascii=False)
+        usage_tracker.track_call(user_id, tool_name)
+        return None
+
+    def _with_hint(data: dict) -> str:
+        """Serialize result and append upgrade hint for free tier."""
+        output = json.dumps(data, ensure_ascii=False, indent=2)
+        if license_mgr.daily_limit is not None:
+            daily = usage_tracker.get_daily_usage(user_id)
+            limit = license_mgr.daily_limit
+            remaining = max(0, limit - daily)
+            if remaining <= 20:
+                output += (
+                    f"\n\n---\n{remaining} free queries remaining today. "
+                    f"Upgrade to Pro ($5) for unlimited: "
+                    f"https://nikeandocean.github.io/carbon-factor-matcher"
+                )
+        return output
+
+    @mcp.tool()
+    def factor_match(activity_data: str, top_k: int = 10) -> str:
+        """Match activity data to the best emission factor using semantic search.
+
+        Uses two-stage matching:
+        1. Embedding-based rough filtering to find candidate factors
+        2. LLM-based fine-ranking to select the best match with reasoning
+
+        Args:
+            activity_data: Description of the activity (e.g., "Factory in Shenzhen,
+                          10kV industrial electricity, 2024, semiconductor fab")
+            top_k: Number of candidates to consider in rough filter (default: 10)
+
+        Returns:
+            JSON with best factor, match reason, confidence score, and alternatives
+        """
+        limit_err = _check_limit("factor_match")
+        if limit_err:
+            return limit_err
+
+        # Search via API
+        factors = api_client.search(activity_data, limit=20)
+
+        if not factors:
+            return json.dumps({"error": "No matching factors found"}, ensure_ascii=False)
+
+        if not license_mgr.can_use_advanced_matching():
+            # Free tier: return keyword search results
+            return _with_hint({
+                "factors": [
+                    {"id": f.id, "name": f.name, "value": f.value, "unit": f.unit}
+                    for f in factors[:10]
+                ],
+                "note": "Basic keyword search. Pro unlocks hybrid matching + quality rating.",
+            })
+
+        # Pro: use LLM matcher on API results
+        matcher = EmissionFactorMatcher(factors=factors, config=config, skip_embedding=False)
+        result = matcher.match(activity_data, top_k=top_k)
+
+        if result is None:
+            return json.dumps({"error": "No matching factors found"}, ensure_ascii=False)
+
+        return _with_hint({
+            "selected_factor": {
+                "id": result.factor.id,
+                "name": result.factor.name,
+                "value": result.factor.value,
+                "unit": result.factor.unit,
+                "category": result.factor.category,
+                "geography": result.factor.geography,
+                "applicability": result.factor.applicability,
+                "source": result.factor.source,
+                "source_year": result.factor.source_year,
+            },
+            "confidence": result.confidence,
+            "reason": result.reason,
+            "alternatives": [
+                {"id": f.id, "name": f.name, "value": f.value, "unit": f.unit}
+                for f in result.candidates[1:4]
+            ],
+        })
+
+    @mcp.tool()
+    def factor_search(query: str, category: str | None = None, limit: int = 10) -> str:
+        """Search emission factors by keyword.
+
+        Args:
+            query: Search keyword (e.g., "electricity", "diesel", "transport")
+            category: Optional category filter (e.g., "electricity", "fuel")
+            limit: Maximum number of results (default: 10)
+
+        Returns:
+            JSON list of matching factors
+        """
+        limit_err = _check_limit("factor_search")
+        if limit_err:
+            return limit_err
+
+        factors = api_client.search(query, limit=limit, category=category)
+
+        return _with_hint({
+            "count": len(factors),
+            "factors": [
+                {
+                    "id": f.id,
+                    "name": f.name,
+                    "value": f.value,
+                    "unit": f.unit,
+                    "category": f.category,
+                    "geography": f.geography,
+                    "source": f.source,
+                    "source_year": f.source_year,
+                }
+                for f in factors
+            ],
+        })
+
+    @mcp.tool()
+    def factor_detail(factor_id: str) -> str:
+        """Get full metadata for a specific emission factor.
+
+        Args:
+            factor_id: The unique identifier of the factor
+
+        Returns:
+            JSON with complete factor metadata
+        """
+        limit_err = _check_limit("factor_detail")
+        if limit_err:
+            return limit_err
+
+        factor = api_client.get_factor(factor_id)
+        if factor is None:
+            return json.dumps({"error": f"Factor not found: {factor_id}"}, ensure_ascii=False)
+
+        return _with_hint({
+            "id": factor.id,
+            "name": factor.name,
+            "category": factor.category,
+            "value": factor.value,
+            "unit": factor.unit,
+            "geography": factor.geography,
+            "applicability": factor.applicability,
+            "source": factor.source,
+            "source_year": factor.source_year,
+        })
+
+    return mcp
+
+
+def _hash_key(key: str) -> str:
+    """Create a short hash of license key for user tracking."""
+    import hashlib
+    if not key:
+        return "anonymous"
+    return hashlib.sha256(key.encode()).hexdigest()[:16]
+
+
+def main():
+    """Entry point for the MCP server."""
+    mcp = create_server()
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

package/src/carbon_factor_matcher/usage_tracker.py

@@ -0,0 +1,68 @@
+"""Usage tracking for API calls."""
+
+import os
+import sqlite3
+from datetime import date
+
+
+class UsageTracker:
+    """Track user API call counts.
+
+    Stores usage data in a local SQLite database.
+    Each call is recorded with user_id, tool name, and date.
+
+    Args:
+        db_path: Path to SQLite database file. Use ":memory:" for testing.
+    """
+
+    def __init__(self, db_path: str = "usage.db"):
+        self.db_path = db_path
+        if db_path != ":memory:":
+            os.makedirs(os.path.dirname(db_path) or ".", exist_ok=True)
+        self._conn = sqlite3.connect(db_path)
+        self._init_db()
+
+    def _init_db(self):
+        """Initialize database tables."""
+        self._conn.execute("""
+            CREATE TABLE IF NOT EXISTS usage (
+                user_id TEXT NOT NULL,
+                tool TEXT NOT NULL,
+                date TEXT NOT NULL,
+                count INTEGER DEFAULT 0,
+                PRIMARY KEY (user_id, tool, date)
+            )
+        """)
+        self._conn.commit()
+
+    def track_call(self, user_id: str, tool: str):
+        """Record one API call.
+
+        Args:
+            user_id: User identifier (e.g., license key hash).
+            tool: Tool name (e.g., "factor_match").
+        """
+        today = date.today().isoformat()
+        self._conn.execute("""
+            INSERT INTO usage (user_id, tool, date, count)
+            VALUES (?, ?, ?, 1)
+            ON CONFLICT(user_id, tool, date)
+            DO UPDATE SET count = count + 1
+        """, (user_id, tool, today))
+        self._conn.commit()
+
+    def get_daily_usage(self, user_id: str) -> int:
+        """Get total call count for user today.
+
+        Args:
+            user_id: User identifier.
+
+        Returns:
+            Total calls today across all tools.
+        """
+        today = date.today().isoformat()
+        result = self._conn.execute(
+            "SELECT COALESCE(SUM(count), 0) FROM usage WHERE user_id = ? AND date = ?",
+            (user_id, today),
+        ).fetchone()
+        return result[0]