gap_to_target

Instructions

Implementation Reference

• server.py:138-192 (handler)

  Handler function for the gap_to_target tool. Computes gap between current trajectory and SBTi-aligned reduction target for a portfolio company.

  @mcp.tool()
  def gap_to_target(portco: str, target_year: int = 2030) -> dict[str, Any]:
      """
      Compute gap between current trajectory and SBTi-aligned reduction target.
  
      Uses latest forecasted annual total and compares against the pro-rated linear
      pathway from base year to target year.
  
      Args:
          portco:      Portco slug or name.
          target_year: Year to evaluate against (default 2030).
  
      Returns:
          Dict with: current_tco2e, target_tco2e, gap_tco2e, gap_pct, on_track (bool),
          verdict (short string).
      """
      slug = _resolve_portco(portco)
      traj = TRAJECTORY[slug]
      p = PORTCOS[slug]
  
      # Latest full year of data (actual + forecast)
      totals = _year_totals(slug)
      latest_year = max(int(y) for y in totals)
      current = totals[str(latest_year)]["total"]
  
      base_total = traj["baseYearTotal"]
      target = traj["target2030"]
      gap = current - target
      gap_pct = (gap / target) * 100 if target else 0
  
      on_track = current <= base_total * (
          1 - (p["targetReduction"] / 100)
          * (latest_year - p["baseYear"]) / (p["targetYear"] - p["baseYear"])
      )
  
      if on_track:
          verdict = f"On pace. Latest-year emissions ({current:,.0f} tCO2e) are within the linear pathway."
      elif gap_pct < 15:
          verdict = f"Close — {gap_pct:.1f}% above target. Achievable with planned initiatives."
      else:
          verdict = f"Materially off-track — {gap_pct:.1f}% above {target_year} target. Needs additional levers."
  
      return {
          "portco": p["name"],
          "base_year": p["baseYear"],
          "base_year_total_tco2e": base_total,
          "latest_year": latest_year,
          "current_tco2e": round(current, 1),
          "target_year": target_year,
          "target_tco2e": target,
          "gap_tco2e": round(gap, 1),
          "gap_pct": round(gap_pct, 1),
          "on_track": bool(on_track),
          "verdict": verdict,
      }

• server.py:138-138 (registration)

  The tool is registered via the @mcp.tool() decorator on line 138, which makes it available as an MCP tool named 'gap_to_target'.

  @mcp.tool()

• server.py:139-153 (schema)

  Input schema: portco (str) and target_year (int, default 2030). Return type dict[str, Any] with documented fields.

  def gap_to_target(portco: str, target_year: int = 2030) -> dict[str, Any]:
      """
      Compute gap between current trajectory and SBTi-aligned reduction target.
  
      Uses latest forecasted annual total and compares against the pro-rated linear
      pathway from base year to target year.
  
      Args:
          portco:      Portco slug or name.
          target_year: Year to evaluate against (default 2030).
  
      Returns:
          Dict with: current_tco2e, target_tco2e, gap_tco2e, gap_pct, on_track (bool),
          verdict (short string).
      """

• server.py:55-68 (helper)

  Helper function _year_totals used by gap_to_target to sum quarterly emissions by year.

  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