Metadata-Version: 2.4
Name: INFRA-COMPASS
Version: 0.19.0
Summary: INFRA-COMPASS is a tool that leverages Large Language Models (LLMs) to create and maintain an inventory of state and local codes and ordinances applicable to energy infrastructure.
Author-email: Paul Pinchuk <ppinchuk@nlr.gov>, Guilherme Castelão <gpimenta@nlr.gov>
Maintainer-email: Paul Pinchuk <ppinchuk@nlr.gov>, Guilherme Castelão <gpimenta@nlr.gov>
License-Expression: BSD-3-Clause
Project-URL: homepage, https://github.com/NatLabRockies/COMPASS
Project-URL: documentation, https://natlabrockies.github.io/COMPASS/
Project-URL: repository, https://github.com/NatLabRockies/COMPASS
Keywords: COMPASS,NLR,Ordinance,Database
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.12
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: beautifulsoup4<5,>=4.12.3
Requires-Dist: click<9,>=8.1.7
Requires-Dist: crawl4ai<0.9,>=0.8.6
Requires-Dist: docling<3,>=2.90.0
Requires-Dist: docling-core<3.0.0,>=2.73.0
Requires-Dist: docling-parse<6.0.0,>=5.3.2
Requires-Dist: html5lib<2,>=1.1
Requires-Dist: huggingface_hub<1
Requires-Dist: langchain-text-splitters<2,>=1.0.0
Requires-Dist: networkx<4,>=3.4.2
Requires-Dist: nltk<4,>=3.9.1
Requires-Dist: nlr-elm<1,>=0.0.41
Requires-Dist: numpy<3,>=2.4.3
Requires-Dist: openai>=2.34.0
Requires-Dist: pandas<3,>=2.2.3
Requires-Dist: pdftotext<3,>=2.2.2
Requires-Dist: platformdirs<5,>=4.5.1
Requires-Dist: playwright<1.52,>=1.49.0
Requires-Dist: pyjson5<3,>=2.0.0
Requires-Dist: rich<14,>=13.9.4
Requires-Dist: toml<0.11,>=0.10.2
Provides-Extra: ocr
Requires-Dist: pytesseract<0.4,>=0.3.13; extra == "ocr"
Provides-Extra: dev
Requires-Dist: jupyter<1.1,>=1.0.0; extra == "dev"
Requires-Dist: pipreqs<0.5,>=0.4.13; extra == "dev"
Requires-Dist: ruff<0.16,>=0.15.5; extra == "dev"
Requires-Dist: ruff-lsp<0.0.63,>=0.0.62; extra == "dev"
Provides-Extra: test
Requires-Dist: flaky<4,>=3.8.1; extra == "test"
Requires-Dist: pytest<10,>=9.0.3; extra == "test"
Requires-Dist: pytest-asyncio<2,>=1.3.0; extra == "test"
Requires-Dist: pytest-cases<4,>=3.10.1; extra == "test"
Requires-Dist: pytest-cov<8,>=7.1.0; extra == "test"
Requires-Dist: pytest-mock<4,>=3.15.1; extra == "test"
Requires-Dist: pytest-profiling<2,>=1.8.1; extra == "test"
Requires-Dist: pytest-xdist<4,>=3.8.0; extra == "test"
Requires-Dist: snakeviz<3,>=2.2.2; extra == "test"
Requires-Dist: statsmodels<0.15,>=0.14; extra == "test"
Requires-Dist: tox<5,>=4.52.1; extra == "test"
Provides-Extra: doc
Requires-Dist: ghp-import<3,>=2.1.0; extra == "doc"
Requires-Dist: myst-parser<6,>=5.0.0; extra == "doc"
Requires-Dist: pydata-sphinx-theme<0.18,>=0.17.1; extra == "doc"
Requires-Dist: sphinx-click<7,>=6.2.0; extra == "doc"
Requires-Dist: sphinx-copybutton<0.6,>=0.5.2; extra == "doc"
Requires-Dist: sphinx-tabs<4,>=3.5; extra == "doc"
Requires-Dist: sphinxcontrib-mermaid<3,>=2.0.1; extra == "doc"
Provides-Extra: anthropic
Requires-Dist: anthropic<0.41,>=0.40.0; extra == "anthropic"
Requires-Dist: botocore<2,>=1.35.72; extra == "anthropic"
Requires-Dist: boto3<2,>=1.35.71; extra == "anthropic"
Provides-Extra: build
Requires-Dist: build<2,>=1.2.2; extra == "build"
Requires-Dist: pkginfo<2,>=1.12.1.2; extra == "build"
Dynamic: license-file

|License| |Zenodo| |PythonV| |PyPI| |Ruff| |Pixi| |SWR|

.. |PythonV| image:: https://badge.fury.io/py/INFRA-COMPASS.svg
    :target: https://pypi.org/project/INFRA-COMPASS/

.. |PyPI| image:: https://img.shields.io/pypi/pyversions/INFRA-COMPASS.svg
    :target: https://pypi.org/project/INFRA-COMPASS/

.. |Ruff| image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
    :target: https://github.com/astral-sh/ruff

.. |License| image:: https://img.shields.io/badge/License-BSD_3--Clause-orange.svg
    :target: https://opensource.org/licenses/BSD-3-Clause

.. |Pixi| image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/prefix-dev/pixi/main/assets/badge/v0.json
    :target: https://pixi.sh

.. |SWR| image:: https://img.shields.io/badge/SWR--25--62_-blue?label=NLR
    :alt: Static Badge

.. |Zenodo| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.17173409.svg
    :target: https://doi.org/10.5281/zenodo.17173409

.. inclusion-intro

What is COMPASS?
================
COMPASS (formally the Infrastructure Continuous Ordinance Mapping for Planning and Siting Systems, or "INFRA-COMPASS")
is an innovative software tool that harnesses the power of Large Language
Models (LLMs) to automate the compilation and continued maintenance of an inventory of
state and local codes and ordinances pertaining to energy infrastructure.

At a high level, COMPASS does two things: it *retrieves* the right ordinance
documents for each jurisdiction you ask about, and then *extracts* structured data from
those documents into a versioned database that downstream users can query as a CSV, Excel
workbook, or GeoPackage.

.. image:: https://raw.githubusercontent.com/NatLabRockies/COMPASS/main/docs/source/_static/overview.png
    :alt: High-level overview of the INFRA-COMPASS pipeline
    :align: center
    :width: 100%

What makes COMPASS different from simply asking ChatGPT for ordinance data is the
architecture around the LLM call:

- **Structured, downstream-ready output** — consistent CSV rows with stable column
  names, units, and feature labels that drop straight into siting and capacity-modeling
  tools like `reV <https://github.com/NREL/reV>`_, GIS workflows, or any pipeline that
  needs setbacks, height limits, and noise thresholds as numbers rather than prose.
- **Hallucination guardrails** — cleaned text is checked against the source and dropped
  if it drifts too far, so fabricated values never reach the database.
- **Source-URL traceability** — every record carries a URL back to the original
  ordinance document, so any value can be audited or spot-checked.
- **Cost control** — cheap heuristic filters reject obviously irrelevant text before
  any LLM call runs, making it tractable to extract data across hundreds of
  jurisdictions.


Read more about the tool in the `documentation <https://natlabrockies.github.io/COMPASS/misc/about.html>`_.


Where is the extracted ordinance data?
======================================
The National Laboratories of the Rockies (NLR) typically runs the INFRA-COMPASS pipeline
annually and publishes refreshed datasets to OpenEI. The latest published ordinance datasets
are available here:

- Solar: https://data.openei.org/submissions/8519
- Wind: https://data.openei.org/submissions/8602


Installing COMPASS
==================
The quickest way to install COMPASS for users is from PyPI:

.. code-block:: bash

    pip install infra-compass

If you would like to install and run COMPASS from source, we recommend using `pixi <https://pixi.sh/latest/>`_:

.. code-block:: bash

    git clone git@github.com:NatLabRockies/COMPASS.git; cd COMPASS
    pixi run compass

For detailed instructions and troubleshooting, see the `installation documentation <https://natlabrockies.github.io/COMPASS/misc/installation.html>`_.


Quickstart
==========
To run a quick COMPASS demo, set up a personal OpenAI API key and run:

.. code-block:: shell

    pixi run openai-solar-demo <your API key>

This will run a full extraction pipeline for two counties using ``gpt-4o-mini`` (costs ~$0.45).
For more information on configuring a COMPASS run, see the
`execution basics example <https://natlabrockies.github.io/COMPASS/examples/execution_basics/README.html>`_.


Development
===========
Please see the `Development Guidelines <https://natlabrockies.github.io/COMPASS/dev/index.html>`_
if you wish to contribute code to this repository.
