@nikeandocean/carbon-factor-matcher 0.2.0 → 0.2.1

package/src/carbon_factor_matcher/models.py

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

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

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