GHP MVP

compass/__init__.py

@@ -6,9 +6,10 @@
 # Temporarily import to register plugins
 # Can drop once plugins register themselves
 from .extraction import (
-    COMPASSWindExtractor,
-    COMPASSSolarExtractor,
+    COMPASSGeoHeatPumpExtractor,
     COMPASSSmallWindExtractor,
+    COMPASSSolarExtractor,
+    COMPASSWindExtractor,
     TexasWaterRightsExtractor,
 )
 

compass/common/base.py

@@ -737,9 +737,9 @@ def _add_value_and_units_clarification_nodes(G):  # noqa: N803
             "1) Extract only the explicit numerical value provided for "
             "the restriction. Do not infer values from related "
             "restrictions.\n"
-            "2) If multiple values are given, select the most restrictive "
-            "one (i.e., the smallest allowable limit, the lowest maximum, "
-            "etc.).\n"
+            "2) If multiple **applicable** values are given, select the most "
+            "restrictive one (i.e., the smallest allowable limit, the lowest "
+            "maximum, etc.).\n"
             "3) Please focus only on {restriction} that would apply for "
             "{system_size_reminder}\n"
             "4) Pay close attention to clarifying details in parentheses, "
@@ -775,9 +775,9 @@ def _add_value_and_units_clarification_nodes(G):  # noqa: N803
             "2) The unit is expressed using standard, conventional unit "
             "names (e.g., 'feet', 'meters', 'acres', 'dBA', etc.). "
             "{unit_clarification}\n"
-            "3) If multiple values are mentioned, return only the units "
-            "for the most restrictive value that directly pertains to the "
-            "restriction.\n"
+            "3) If multiple **applicable** values are mentioned, return only "
+            "the units for the most restrictive value that directly pertains "
+            "to the restriction.\n"
             "\nExample Inputs and Outputs:\n"
             "Text: 'For all WES there is a limitation of overall height "
             "of 200 feet (including blades).'\n"

compass/extraction/__init__.py

@@ -10,7 +10,8 @@
 
 # Temporarily import to register plugins
 # Can drop once plugins register themselves
-from .wind import COMPASSWindExtractor
-from .solar import COMPASSSolarExtractor
+from .ghp import COMPASSGeoHeatPumpExtractor
 from .small_wind import COMPASSSmallWindExtractor
+from .solar import COMPASSSolarExtractor
 from .water import TexasWaterRightsExtractor
+from .wind import COMPASSWindExtractor

compass/extraction/ghp/__init__.py

@@ -0,0 +1,11 @@
+"""COMPASS Geothermal ground source heat pump plugin"""
+
+import importlib.resources
+
+from compass.plugin import create_schema_based_one_shot_extraction_plugin
+
+
+COMPASSGeoHeatPumpExtractor = create_schema_based_one_shot_extraction_plugin(
+    importlib.resources.files("compass.extraction.ghp") / "plugin_config.yaml",
+    tech="ghp",
+)

compass/extraction/ghp/plugin_config.yaml

@@ -0,0 +1,103 @@
+schema: ./geothermal_heat_pump_schema.json5
+
+data_type_short_desc: geothermal ground source heat pump ordinance
+
+query_templates:
+    - "{jurisdiction} geothermal ground source heat pump code"
+    - "filetype:pdf {jurisdiction} geothermal heat pump ordinance"
+    - "{jurisdiction} geothermal energy system ordinance"
+    - "Where can I find the legal text for geothermal heat pump zoning ordinances in {jurisdiction}?"
+    - "What is the specific legal information regarding zoning ordinances for geothermal heat pumps in {jurisdiction}?"
+
+website_keywords:
+    # These still need massaging
+    #   - e.g. include something about open loop or closed loop?
+    pdf: 92160
+    pump: 46080
+    geothermal: 23040
+    ordinance: 11520
+    zoning: 5760
+    regulation: 2880
+    code: 1440
+    heating: 1440
+    planning: 720
+    government: 180
+
+heuristic_keywords:
+  good_tech_acronyms:
+    - "ghp"
+    - "gshp"
+  good_tech_keywords:
+    - "geoexchange"
+    - "geo-exchange"
+    - "wellfield"
+    - "direct-use"
+    - "closed-loop"
+  good_tech_phrases:
+    - "well field"
+    - "geothermal resource"
+    - "geothermal drilling"
+    - "geothermal well"
+    - "geothermal reservoir"
+    - "geothermal permit"
+    - "geothermal ordinance"
+    - "geothermal zoning"
+    - "closed loop"
+    - "open loop"
+    - "vertical loop"
+    - "horizontal loop"
+    - "heating and cooling"
+    - "space heating"
+    - "direct use"
+    - "district heating"
+    - "greenhouse heating"
+    - "residential geothermal"
+    - "heat pump"
+    - "geothermal heat pump"
+    - "ground source heat pump"
+    - "ground-source heat pump"
+    - "ground heat pump"
+    - "ground-coupled heat pump"
+    - "ground coupled heat pump"
+    - "earth-coupled heat pump"
+    - "earth-source heat pump"
+    - "closed loop ground source"
+    - "open loop ground source"
+  not_tech_words:
+    - "production well"
+    - "geothermal exploration"
+    - "geothermal generating"
+    - "geothermal generation"
+    - "geothermal power"
+    - "geothermal production"
+    - "geothermal project"
+    - "geothermal overlay zone"
+    - "geothermal power plant"
+    - "geothermal facility"
+    - "geothermal electric"
+    - "geothermal energy facility"
+    - "geothermal lease"
+    - "geothermal development"
+    - "steam turbine"
+    - "binary cycle"
+    - "flash steam"
+    - "dry steam"
+    - "enhanced geothermal"
+    - "reservoir temperature"
+    - "reinjection well"
+    - "production zone"
+    - "geothermal production project"
+    - "exploratory well"
+    - "injection well"
+
+collection_prompts: True
+
+extraction_system_prompt: |-
+  You are a legal scholar extracting structured data from geothermal ground source heat pump ordinances.
+  Be focused and literal: extract only enacted, explicit, in-scope requirements.
+  Be thorough and complete: review all relevant sections, including tables and
+  lists, so no explicitly stated feature is missed.
+  Before finalizing, perform a feature-coverage check against the schema enum and
+  ensure each explicitly supported feature is captured exactly once.
+  Pay extra attention to any descriptions, instructions, examples, and definitions in the schema,
+  and be sure to follow all schema instructions carefully.

compass/extraction/small_wind/parse.py

@@ -253,6 +253,9 @@ class StructuredSmallWindOrdinanceParser(StructuredSmallWindParser):
     OUT_LABEL = "ordinance_values"
     """Identifier for structured ordinance data output by this class"""
 
+    TASK_ID = LLMUsageCategory.ORDINANCE_VALUE_EXTRACTION
+    """Identifier for this parser's specific LLM task category"""
+
     async def parse(self, text):
         """Parse text and extract structure ordinance data
 
@@ -569,6 +572,9 @@ class StructuredSmallWindPermittedUseDistrictsParser(
     OUT_LABEL = "permitted_district_values"
     """Identifier for structured ordinance data output by this class"""
 
+    TASK_ID = LLMUsageCategory.PERMITTED_USE_VALUE_EXTRACTION
+    """Identifier for this parser's specific LLM task category"""
+
     _SMALL_WES_CLARIFICATION = (
         "Small wind energy systems (AWES) may also be referred to as "
         "non-commercial wind energy systems, on-site wind energy systems, "

compass/extraction/solar/parse.py

@@ -200,6 +200,9 @@ class StructuredSolarOrdinanceParser(StructuredSolarParser):
     OUT_LABEL = "ordinance_values"
     """Identifier for structured ordinance data output by this class"""
 
+    TASK_ID = LLMUsageCategory.ORDINANCE_VALUE_EXTRACTION
+    """Identifier for this parser's specific LLM task category"""
+
     async def parse(self, text):
         """Parse text and extract structure ordinance data
 
@@ -505,6 +508,9 @@ class StructuredSolarPermittedUseDistrictsParser(StructuredSolarParser):
     OUT_LABEL = "permitted_district_values"
     """Identifier for structured ordinance data output by this class"""
 
+    TASK_ID = LLMUsageCategory.PERMITTED_USE_VALUE_EXTRACTION
+    """Identifier for this parser's specific LLM task category"""
+
     _LARGE_SEF_CLARIFICATION = (
         "Large solar energy systems (SES) may also be referred to as solar "
         "panels, solar energy conversion systems (SECS), solar energy "

compass/extraction/wind/parse.py

@@ -190,6 +190,9 @@ class StructuredWindOrdinanceParser(StructuredWindParser):
     OUT_LABEL = "ordinance_values"
     """Identifier for structured ordinance data output by this class"""
 
+    TASK_ID = LLMUsageCategory.ORDINANCE_VALUE_EXTRACTION
+    """Identifier for this parser's specific LLM task category"""
+
     async def parse(self, text):
         """Parse text and extract structure ordinance data
 
@@ -508,6 +511,9 @@ class StructuredWindPermittedUseDistrictsParser(StructuredWindParser):
     OUT_LABEL = "permitted_district_values"
     """Identifier for structured ordinance data output by this class"""
 
+    TASK_ID = LLMUsageCategory.PERMITTED_USE_VALUE_EXTRACTION
+    """Identifier for this parser's specific LLM task category"""
+
     _LARGE_WES_CLARIFICATION = (
         "Large wind energy systems (WES) may also be referred to as wind "
         "turbines, wind energy conversion systems (WECS), wind energy "

compass/plugin/one_shot/base.py

@@ -133,6 +133,12 @@ def create_schema_based_one_shot_extraction_plugin(config, tech):  # noqa: C901
         Technology identifier to use for the plugin (e.g., "wind",
         "solar"). Must be unique from the identifiers of any existing
         plugins.
+
+    Returns
+    -------
+    callable
+        A `SchemaBasedExtractionPlugin` subclass configured according to
+        the input configuration.
     """
     if not isinstance(config, dict):
         config = load_config(config)
@@ -401,6 +407,7 @@ def _validate_website_keywords(self):
             """
 
     register_plugin(SchemaBasedExtractionPlugin)
+    return SchemaBasedExtractionPlugin
 
 
 def _collectors_from_config(config):

compass/plugin/one_shot/components.py

@@ -1,7 +1,9 @@
 """COMPASS extraction schema-based plugin component implementations"""
 
+import json
 import asyncio
 import logging
+from datetime import datetime
 from abc import ABC, abstractmethod
 
 import pandas as pd
@@ -91,7 +93,7 @@
 
 """
 _DATA_PARSER_MAIN_PROMPT = """\
-Extract all {desc}features from the following text:
+Extract all applicable {desc}features explicitly supported by following text:
 
 {text}
 
@@ -101,6 +103,12 @@
 You are a legal scholar extracting structured data from {desc}documents. \
 Follow all instructions in the schema descriptions carefully.\
 """
+_DATA_PARSER_ADDITIONAL_CONTEXT = """\
+# ADDITIONAL CONTEXT #
+- Today's date is {todays_date}. If you are extracting a moratorium or \
+temporary restriction that includes an explicit end date that has already \
+passed as of today, treat it as expired and omit that prohibition feature.\
+"""
 
 
 class SchemaBasedTextCollector(SchemaOutputLLMCaller, BaseTextCollector, ABC):
@@ -176,11 +184,17 @@ async def check_chunk(self, chunk_parser, ind):
 
     async def _check_chunk_with_prompt(self, key, text_chunk):
         """Call LLM on a chunk of text to check for ordinance"""
+        main_prompt = _TEXT_COLLECTION_MAIN_PROMPT.format(
+            schema=self.SCHEMA, text=text_chunk
+        )
+        logger.debug("Checking text chunk with LLM: %s", text_chunk)
+        logger.debug_to_file(
+            "\t- System Message:\n%s", _TEXT_COLLECTION_SYSTEM_PROMPT
+        )
+        logger.debug_to_file("\t- Main prompt:\n%s", main_prompt)
         content = await self.call(
             sys_msg=_TEXT_COLLECTION_SYSTEM_PROMPT,
-            content=_TEXT_COLLECTION_MAIN_PROMPT.format(
-                schema=self.SCHEMA, text=text_chunk
-            ),
+            content=main_prompt,
             response_format={
                 "type": "json_schema",
                 "json_schema": {
@@ -191,7 +205,7 @@ async def _check_chunk_with_prompt(self, key, text_chunk):
             },
             usage_sub_label=LLMUsageCategory.DOCUMENT_CONTENT_VALIDATION,
         )
-        logger.debug("LLM response: %s", content)
+        logger.debug("LLM response:\n%s", json.dumps(content, indent=4))
         return content.get(key, False)
 
     def _store_chunk(self, parser, chunk_ind):
@@ -239,8 +253,10 @@ async def _process(self, text_chunks):
         """Perform extraction processing"""
 
         logger.info(
-            "Extracting summary text from %d text chunks asynchronously...",
+            "Extracting summary text from %d text chunks asynchronously "
+            "using LLM: %r...",
             len(text_chunks),
+            self.llm_service.model_name,
         )
         outer_task_name = asyncio.current_task().get_name()
         summaries = [
@@ -330,9 +346,24 @@ async def parse(self, text):
             else ""
         )
 
+        todays_date = datetime.now().strftime("%B %d, %Y")
+        sys_prompt = (
+            f"{self.SYSTEM_PROMPT}\n\n{_DATA_PARSER_ADDITIONAL_CONTEXT}"
+        )
+        sys_prompt = sys_prompt.format(
+            desc=desc, schema=self.SCHEMA, todays_date=todays_date
+        )
+
+        main_prompt = _DATA_PARSER_MAIN_PROMPT.format(desc=desc, text=text)
+        logger.debug(
+            "Extracting ordinances with LLM: %r", self.llm_service.model_name
+        )
+        logger.debug_to_file("\t- System Message:\n%s", sys_prompt)
+        logger.debug_to_file("\t- Main prompt:\n%s", main_prompt)
+
         extraction = await self.call(
-            sys_msg=self.SYSTEM_PROMPT.format(desc=desc),
-            content=_DATA_PARSER_MAIN_PROMPT.format(desc=desc, text=text),
+            sys_msg=sys_prompt,
+            content=main_prompt,
             response_format={
                 "type": "json_schema",
                 "json_schema": {
@@ -343,6 +374,9 @@ async def parse(self, text):
             },
             usage_sub_label=LLMUsageCategory.ORDINANCE_VALUE_EXTRACTION,
         )
+        logger.debug_to_file(
+            "LLM response:\n%s", json.dumps(extraction, indent=4)
+        )
         data = extraction["outputs"]
         if not data:
             logger.debug(