Add Renewable Component Library (RCL) integration

.gitignore

@@ -35,6 +35,9 @@ site/
 # OS junk
 .DS_Store
 
+# RCL downloaded equipment files
+rcl_downloads/
+
 public
 *.ipynb_checkpoints
 api_call_endpoints.py

AGENTS.md

@@ -52,6 +52,46 @@ Use this workflow when the user has an existing data model in their own system a
 
 **API key**: Set env var `SF_API_KEY` (preferred) or pass `api_key=` to any function.
 
+## Complementary: Search and Download Equipment from RCL
+
+Use this workflow when the user needs PV module (PAN) or inverter (OND) files from DNV's curated Renewable Component Library. The RCL provides access to validated equipment files without requiring users to source them manually. This workflow complements the use cases above — after downloading equipment files, proceed to Use case 1, 2, or 3.
+
+```python
+import solarfarmer as sf
+sf.configure_logging()
+
+# Search for high-power bifacial modules (zero-cost call)
+result = sf.rcl.list_modules(
+    manufacturer_contains="LONGi",
+    p_nom_gte=550,
+    bifaciality_factor_gte=0.7,
+    top=10,
+)
+print(f"Found {result['total']} matching modules")
+
+# Check rate limit before downloading (zero-cost call)
+status = sf.rcl.get_rate_limit_status()
+print(f"{status.remaining}/{status.limit} downloads remaining")
+
+# Download a specific module file (costs 1 credit)
+item = result["items"][0]
+sf.rcl.download_file(
+    item["fileUuid"],
+    item["filename"],
+    directory_path="./equipment/",
+)
+
+# Or integrate directly with PVSystem (downloads only if single match)
+plant = sf.PVSystem(name="My Plant", latitude=45.5, longitude=10.3, ...)
+plant.set_module_from_rcl(
+    manufacturer_contains="Canadian Solar",
+    model_contains="CS7N-715TB-AG",
+    directory_path="./equipment/",
+)
+```
+
+**Rate limiting**: Downloads are capped monthly. Use `sf.rcl.get_rate_limit_status()` (zero-cost) to check remaining quota.
+
 ---
 
 ## Core Principles
@@ -73,6 +113,7 @@ Use this workflow when the user has an existing data model in their own system a
   - **Results models**: `CalculationResults` (in `energy_calculation_results.py`) wraps API outputs and provides convenience properties and accessors such as `performance_ratio_bifacial`, `get_performance()`, `print_annual_results()`, `loss_tree_timeseries()`, and `pvsyst_timeseries()`.
   - **`PVSystem`** (`@dataclass`, `solarfarmer/models/pvsystem/pvsystem.py`): **Mutable** high-level builder. Not a Pydantic model. Acts as an entry point for Use case 2; internally converts to `EnergyCalculationInputs` before the API call. Key utility methods: `describe()`, `make_copy()`, `produce_payload()`, `payload_to_file()`, `to_file()`, `from_file()`.
 - **config.py**: Configuration constants, environment variables, timeouts. Single source of truth for URLs and defaults.
+- **rcl.py**: Renewable Component Library client. Exports `list_modules()`, `list_inverters()`, `download_file()`, `get_rate_limit_status()`. Uses `RCLClient` from `api.py`. Returns lightweight TypedDict responses (`RCLCatalogResponse`) and dataclass (`RCLRateLimitInfo`).
 
 ### Naming Conventions
 - Files: `endpoint_modelchains.py`, `test_endpoint_modelchain.py` (endpoint features use singular endpoint name in tests)
@@ -190,6 +231,9 @@ The following are **named workflows** for structuring developer work. They are N
 | Add polling timeout logic | EndpointDev workflow | Requires config constants, async pattern |
 | Help SDK user run a calculation | Default referencing Quickstart | Refer to copilot-instructions.md quickstart |
 | Convert weather data to SF format | Default | Use `sf.from_dataframe()`, `sf.from_pvlib()`, or `sf.from_solcast()` |
+| Search RCL for modules/inverters | Default | Use `sf.rcl.list_modules()`, `sf.rcl.list_inverters()` |
+| Download equipment from RCL | Default | Use `sf.rcl.download_file()` |
+| Integrate RCL with PVSystem | Default | Use `plant.set_module_from_rcl()`, `plant.set_inverter_from_rcl()` |
 
 ## Tool Restrictions
 

docs/api.md

@@ -18,6 +18,7 @@ The SolarFarmer SDK is organized into the following main categories:
 - [**Endpoint Functions**](#endpoint-functions): Core functions for making API calls
 - [**Main Classes**](#main-classes): Key data models for calculations and plant design
 - [**Weather Utilities**](#weather-utilities): Convert DataFrames to SolarFarmer weather files (requires `pandas`)
+- [**Renewable Component Library (RCL)**](#renewable-component-library-rcl): Search and download PV modules and inverters specification files
 
 ### Configuration & Design
 
@@ -113,6 +114,71 @@ Data dictionary describing the SolarFarmer TSV weather file format: required and
 
 ---
 
+## Renewable Component Library (RCL)
+
+Search and download PV modules (PAN files) and inverters (OND files) from DNV's curated component database. See the [RCL documentation](getting-started/rcl-component-library.md) for usage examples.
+
+!!! warning "Rate Limiting"
+    Each file download counts against your monthly quota. Use `get_rate_limit_status()` to check your remaining downloads.
+
+### `list_modules()`
+
+::: solarfarmer.rcl.list_modules
+    options:
+      extra:
+        show_root_toc_entry: false
+        show_root_members: true
+
+### `list_inverters()`
+
+::: solarfarmer.rcl.list_inverters
+    options:
+      extra:
+        show_root_toc_entry: false
+        show_root_members: true
+
+### `download_file()`
+
+::: solarfarmer.rcl.download_file
+    options:
+      extra:
+        show_root_toc_entry: false
+        show_root_members: true
+
+### `get_rate_limit_status()`
+
+::: solarfarmer.rcl.get_rate_limit_status
+    options:
+      extra:
+        show_root_toc_entry: false
+        show_root_members: true
+
+### `RCLRateLimitInfo`
+
+::: solarfarmer.rcl.RCLRateLimitInfo
+    options:
+      extra:
+        show_root_toc_entry: false
+        show_root_members: true
+
+### `RCLCatalogItem`
+
+::: solarfarmer.rcl.RCLCatalogItem
+    options:
+      extra:
+        show_root_toc_entry: false
+        show_root_members: true
+
+### `RCLCatalogResponse`
+
+::: solarfarmer.rcl.RCLCatalogResponse
+    options:
+      extra:
+        show_root_toc_entry: false
+        show_root_members: true
+
+---
+
 ## Main Classes
 
 The core classes handle the complete workflow from plant design to results analysis:

docs/getting-started/end-to-end-examples.md

@@ -16,6 +16,7 @@ These examples provide detailed explorations of specific API features and workfl
 | [Creating Plants with PVSystem](#creating-plants-with-pvsystem) | Master plant design with the PVSystem class | Workflow 2 | Designing new plants |
 | [Creating Plants with EnergyCalculationInputs](#creating-plants-with-energycalculationinputs) | Build flexible plant configurations with Pydantic model payloads | Workflow 3 | Advanced integration and batch processing |
 | [Terminating Asynchronous Calculations](#terminating-asynchronous-calculations) | Manage long-running 3D calculations | Workflow 3 | Advanced integration and async 3D workflows |
+| [Using the Renewable Component Library](#using-the-renewable-component-library) | Search and download PV modules and inverters from DNV's catalog | All | Equipment sourcing |
 
 ---
 
@@ -77,6 +78,22 @@ These examples provide detailed explorations of specific API features and workfl
 
 ---
 
+## Using the Renewable Component Library
+
+**Notebook:** [Example_RCL_Catalog.ipynb](https://github.com/dnv-opensource/solarfarmer-python-sdk/blob/main/docs/notebooks/Example_RCL_Catalog.ipynb){ target="_blank" .external }
+
+**Topics Covered:**
+
+- Searching for PV modules and inverters in DNV's curated catalog
+- Filtering by manufacturer, power, efficiency, and other specifications
+- Managing rate limits and download quotas
+- Downloading PAN and OND equipment files
+- Integrating RCL with PVSystem for automatic equipment assignment
+
+**Use this when:** You need validated equipment files for energy calculations and want to source them from DNV's Renewable Component Library rather than managing files manually.
+
+---
+
 ## Terminating Asynchronous Calculations
 
 **Notebook:** [Example_TerminateAsync_endpoint.ipynb](https://github.com/dnv-opensource/solarfarmer-python-sdk/blob/main/docs/notebooks/Example_TerminateAsync_endpoint.ipynb){ target="_blank" .external }

docs/getting-started/index.md

@@ -90,6 +90,27 @@ Results from `PVSystem` are approximations based on simplified layout assumption
 
 ---
 
+### [Renewable Component Library (RCL)](rcl-component-library.md)
+
+**For:** Users who need validated PAN/OND equipment files
+
+**Goal:** Search and download PV modules and inverters from DNV's curated component database
+
+**Key Functions:**
+
+- `sf.rcl.list_modules()` - Search the module catalog
+- `sf.rcl.list_inverters()` - Search the inverter catalog
+- `sf.rcl.download_file()` - Download PAN/OND files
+- `sf.rcl.get_rate_limit_status()` - Check remaining download quota
+
+**Time to First Result:** 5 minutes
+
+!!! example
+    Search for bifacial modules from a specific manufacturer, download the PAN file,
+    and use it with any workflow above.
+
+---
+
 ## Integrated Class Examples
 
 Once you know your workflow, see how the classes work together in real-world scenarios.
@@ -100,11 +121,12 @@ Once you know your workflow, see how the classes work together in real-world sce
 
 ## Need Help Deciding?
 
-| I want to... | Go to Workflow |
+| I want to... | Go to |
 |---|---|
 | Run calculations on existing API files | [Workflow 1](workflow-1-existing-api-files.md) |
 | Design a new plant from scratch | [Workflow 2](workflow-2-pvplant-builder.md) |
 | Integrate SolarFarmer into my software | [Workflow 3](workflow-3-plantbuilder-advanced.md) |
+| Find and download equipment files | [RCL Component Library](rcl-component-library.md) |
 | See real code examples | [Quick Start Examples](quick-start-examples.md) |
 
 ---