simulate_reduction

Instructions

Implementation Reference

• server.py:234-273 (handler)

  Handler function for the simulate_reduction MCP tool. Performs what-if analysis by applying selected decarbonization initiatives to a portfolio company's latest emissions, computing total reduction, capex, and comparing the projected value against the 2030 SBTi target.

  @mcp.tool()
  def simulate_reduction(portco: str, initiative_ids: list[int]) -> dict[str, Any]:
      """
      What-if analysis: apply a subset of initiatives and return projected post-lever emissions.
  
      Args:
          portco:         Portco slug or name.
          initiative_ids: List of initiative IDs (from list_initiatives) to 'turn on'.
  
      Returns:
          Dict with baseline (current trajectory endpoint), applied initiatives,
          total reduction, total capex, and new endpoint vs target.
      """
      slug = _resolve_portco(portco)
      p = PORTCOS[slug]
      traj = TRAJECTORY[slug]
      totals = _year_totals(slug)
      latest_year = max(int(y) for y in totals)
      baseline = totals[str(latest_year)]["total"]
  
      selected = [i for i in INITIATIVES[slug] if i["id"] in initiative_ids]
      total_reduction = sum(i["estReduction"] for i in selected)
      total_capex = sum(i["capex"] for i in selected)
      new_total = max(0.0, baseline - total_reduction)
      target = traj["target2030"]
  
      return {
          "portco": p["name"],
          "baseline_tco2e": round(baseline, 1),
          "applied_initiatives": [
              {"id": i["id"], "name": i["name"], "reduction_tco2e": i["estReduction"], "capex_k": i["capex"]}
              for i in selected
          ],
          "total_reduction_tco2e": total_reduction,
          "total_capex_k_usd": total_capex,
          "projected_tco2e": round(new_total, 1),
          "target_2030_tco2e": target,
          "meets_target": new_total <= target,
          "gap_vs_target_tco2e": round(new_total - target, 1),
      }

• server.py:234-234 (registration)

  Registration of the simulate_reduction tool via the @mcp.tool() decorator from FastMCP. The decorator registers the function as an MCP tool available to the agent.

  @mcp.tool()

• server.py:42-52 (helper)

  Helper function used by simulate_reduction to resolve a portco slug or name to a normalized key.

  def _resolve_portco(portco: str) -> str:
      """Match portco by slug or name (case-insensitive). Raises on miss."""
      key = portco.strip().lower()
      if key in PORTCOS:
          return key
      for slug, p in PORTCOS.items():
          if p["name"].lower().startswith(key) or key in p["name"].lower():
              return slug
      raise ValueError(
          f"Unknown portco '{portco}'. Known slugs: {', '.join(PORTCOS.keys())}"
      )

• server.py:55-68 (helper)

  Helper function used by simulate_reduction to sum quarterly emissions data for a given portco to compute the latest-year baseline.

  def _year_totals(slug: str, year: int | None = None) -> dict[str, float]:
      """Sum quarterly emissions for a portco. If year is None, returns all years."""
      traj = TRAJECTORY[slug]["quarters"]
      result: dict[str, dict[str, float]] = {}
      for q in traj:
          y = int(q["q"].split("-")[1])
          if year is not None and y != year:
              continue
          key = str(y)
          result.setdefault(key, {"scope1": 0.0, "scope2": 0.0, "total": 0.0})
          result[key]["scope1"] += q["scope1"]
          result[key]["scope2"] += q["scope2"]
          result[key]["total"] += q["scope1"] + q["scope2"]
      return result