parsimony-bde 0.0.1__tar.gz

parsimony_bde-0.0.1/.gitignore

@@ -0,0 +1,40 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+
+.venv/
+.env
+.env.*
+!.env.example
+
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+uv.lock
+
+.vscode/
+.council/
+PLAN-*.md
+.idea/
+*.swp
+.DS_Store
+
+outputs/
+logs/
+# Recorded HTTP cassettes must never be committed — respx mocks are hand-authored
+# from upstream API documentation. A pre-commit / CI regex scan is the belt; this
+# ignore is the braces. Override per-file via `!` if you need a hand-authored
+# fixture checked in.
+packages/*/tests/fixtures/**
+!packages/*/tests/fixtures/README.md

parsimony_bde-0.0.1/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog — parsimony-bde
+
+All notable changes to `parsimony-bde` will be documented in this file. The
+format is based on [Keep a Changelog](https://keepachangelog.com/) and
+this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.8.0] — 2026-06-08
+
+A full-process completeness pass over the connector (documentation re-compiled
+and every claim re-verified against the live BIEST endpoints).
+
+### Added
+
+- **Bank Lending Survey recovered.** The `pb` catalog chapter lists family/table
+  aliases (`PB_1_1.1`) that the BIEST web service rejects with HTTP 412
+  ("no existe"), so all 262 of those series were previously un-fetchable. The
+  real fetchable codes (`DPB…`) live only inside the bulk `pb.zip`; the
+  enumerator now reads them from there, recovering ~350 Bank Lending Survey
+  series as searchable and fetchable (`enumerate.py`, `_catalog.parse_pb_zip`).
+- **Bilingual catalog.** The published catalog CSVs are Spanish-only, so search
+  used to be Spanish-only (the discovery index is lexical/BM25 at this
+  cardinality — no multilingual embedding bridge). `build_bde_catalog` now
+  enriches each entry's `title` with the English short description from
+  `favoritas(idioma=en)` where BdE serves one (Spanish title kept as fallback),
+  while the Spanish long description rides along in `description` — both are
+  indexed, so an agent searching in English or Spanish gets lexical hits
+  (`enrich.py`). The enrichment is batched, retried, and split-on-failure so a
+  flaky network can't silently drop a batch's English titles.
+
+### Fixed
+
+- **Catalog de-duplication.** A series can be listed under more than one thematic
+  chapter (~24% of raw rows were cross-chapter repeats). `enumerate_bde` now
+  de-dups by series code (first chapter in order wins), so the catalog is the
+  ~15.5k unique series rather than ~20.5k rows with non-deterministic per-row
+  `category`.
+- **Frequency-dependent `time_range`.** `bde_fetch` rejected valid daily-series
+  ranges (`3M`/`12M`/`36M`) and accepted `MAX` that BdE 412s for daily series.
+  The accepted set is now the documented union and BdE validates the
+  frequency-specific rule server-side.
+- **Typed error for invalid requests.** An unknown series code or a
+  frequency-incompatible range (BdE HTTP 412) now surfaces as
+  `InvalidParameterError` carrying BdE's own message, instead of a generic
+  `ProviderError(412)` that reads like a transient server fault.
+
+## [0.5.0] — 2026-05-06
+
+### Changed
+
+- Adapted to `parsimony-core==0.5`. Connector code no longer constructs `Provenance` directly; the framework authors all provenance fields in `Connector._wrap_result`. Source-specific extras (where present) move to `Result.with_properties(**kwargs)`. Drops the `provenance=` and `params=` kwargs from `OutputConfig.build_table_result` / `Result.from_dataframe` call sites.
+- Bump `parsimony-core` pin from `>=0.4.0,<0.5` to `>=0.5.0,<0.6` (and `[standard-onnx]` extra accordingly on catalog-publishing packages).
+## [0.4.0] — 2026-04-24
+
+Part of the first coordinated release of the
+[`parsimony-connectors`](https://github.com/ockham-sh/parsimony-connectors)
+monorepo under `parsimony-core==0.4`.
+
+### Changed
+
+- Connector rewritten against the kernel's `parsimony.discover` surface
+  (`iter_providers`, `load`, `load_all`) and the `@connector(env=...)`
+  decorator-level env-var declaration that replaced module-level
+  `ENV_VARS`.
+- Pin bumped to `parsimony-core>=0.4,<0.5`.

parsimony_bde-0.0.1/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Ockham.sh
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

parsimony_bde-0.0.1/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: parsimony-bde
+Version: 0.0.1
+Summary: Banco de España connector for the parsimony framework
+Project-URL: Homepage, https://www.bde.es
+Project-URL: Repository, https://github.com/ockham-sh/parsimony-connectors
+Project-URL: Issues, https://github.com/ockham-sh/parsimony-connectors/issues
+Author-email: "Ockham.sh" <team@ockham.sh>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: bde,connectors,data,finance,parsimony
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pandas<3,>=2.3.0
+Requires-Dist: parsimony-core[catalog]>=0.0.1
+Requires-Dist: parsimony-shared>=0.0.1
+Requires-Dist: pydantic<3,>=2.11.1
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Requires-Dist: respx>=0.22.0; extra == 'dev'
+Requires-Dist: ruff>=0.15.10; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# parsimony-bde
+
+Banco de España connector — Spanish macroeconomic, monetary, and financial time series via the BIEST REST API.
+
+Part of the [parsimony-connectors](https://github.com/ockham-sh/parsimony-connectors) monorepo. Distributed standalone on PyPI as `parsimony-bde`.
+
+## Connectors
+
+| Name | Kind | Description |
+|---|---|---|
+| `bde_fetch` | connector | Fetch one or more BdE time series by series code (comma-separated). |
+| `enumerate_bde` | enumerator | Discover BdE series from six catalog CSV chapters plus the Bank Lending Survey (recovered from `pb.zip`). |
+| `bde_search` | connector | Semantic-search the published BdE catalog snapshot; returns ranked series codes. |
+
+`bde_fetch`'s `time_range` is frequency-dependent (BdE validates it): monthly /
+quarterly series take `30M`/`60M`/`MAX`, daily series take `3M`/`12M`/`36M` (not
+`MAX`), and any frequency accepts a 4-digit year (e.g. `2024`). A range that
+doesn't fit a series' frequency is reported as an `InvalidParameterError`.
+
+## Install
+
+```bash
+pip install parsimony-bde
+```
+
+Pulls in `parsimony-core>=0.7,<0.8` automatically. Verify discovery:
+
+```bash
+python -c "from parsimony import discover; print([p.name for p in discover.iter_providers()])"
+```
+
+## Configuration
+
+No API key required — the BdE BIEST API is open and unauthenticated.
+
+`bde_search` reads a published catalog snapshot (default `hf://parsimony-dev/bde`).
+Override the snapshot location with the `PARSIMONY_BDE_CATALOG_URL` environment
+variable, or pass `catalog_url=` at call time.
+
+## Quick start
+
+```python
+from parsimony_bde import CONNECTORS
+
+result = CONNECTORS["bde_fetch"](key="D_1NBAF472")
+print(result.data.head())
+```
+
+For multi-plugin composition (autoloads everything installed):
+
+```python
+from parsimony import discover
+connectors = discover.load_all()
+```
+
+## Catalogs
+
+`enumerate_bde` discovers the full BdE series catalog — ~15.5k unique series
+across six published CSV chapters (`be`, `cf`, `ie`, `si`, `tc`, `ti`), plus the
+Bank Lending Survey. The survey's CSV chapter lists only un-fetchable family
+aliases (`PB_1_1.1`), so its real fetchable codes (`DPB…`) are recovered from the
+bulk `pb.zip`. Rows are de-duplicated by series code (a series can appear under
+more than one thematic chapter). Maintainers build a `Catalog` snapshot from the
+enumerator (see `scripts/build_catalog.py`) and push it to the snapshot URL that
+`bde_search` reads. The crawl is expensive (the CF/Financial-Accounts chapter
+alone is several thousand series), so it runs offline as a publish job — never at
+query time.
+
+A small tail (~1% of catalog codes, mostly dollar-denominated `…$…` financial
+accounts variants and a handful of external-sector series) is listed in the CSV
+catalog but not served by the web service; fetching such a code returns a clear
+`InvalidParameterError` rather than data.
+
+## Provider
+
+- Homepage: https://www.bde.es
+- API docs: https://www.bde.es/webbe/en/estadisticas/recursos/api-estadisticas-bde.html
+- Series browser: https://app.bde.es/bie_www/bie_wwwias/xml/Arranque.html (BIEST)
+
+## License
+
+See [LICENSE](./LICENSE).

parsimony_bde-0.0.1/README.md

@@ -0,0 +1,82 @@
+# parsimony-bde
+
+Banco de España connector — Spanish macroeconomic, monetary, and financial time series via the BIEST REST API.
+
+Part of the [parsimony-connectors](https://github.com/ockham-sh/parsimony-connectors) monorepo. Distributed standalone on PyPI as `parsimony-bde`.
+
+## Connectors
+
+| Name | Kind | Description |
+|---|---|---|
+| `bde_fetch` | connector | Fetch one or more BdE time series by series code (comma-separated). |
+| `enumerate_bde` | enumerator | Discover BdE series from six catalog CSV chapters plus the Bank Lending Survey (recovered from `pb.zip`). |
+| `bde_search` | connector | Semantic-search the published BdE catalog snapshot; returns ranked series codes. |
+
+`bde_fetch`'s `time_range` is frequency-dependent (BdE validates it): monthly /
+quarterly series take `30M`/`60M`/`MAX`, daily series take `3M`/`12M`/`36M` (not
+`MAX`), and any frequency accepts a 4-digit year (e.g. `2024`). A range that
+doesn't fit a series' frequency is reported as an `InvalidParameterError`.
+
+## Install
+
+```bash
+pip install parsimony-bde
+```
+
+Pulls in `parsimony-core>=0.7,<0.8` automatically. Verify discovery:
+
+```bash
+python -c "from parsimony import discover; print([p.name for p in discover.iter_providers()])"
+```
+
+## Configuration
+
+No API key required — the BdE BIEST API is open and unauthenticated.
+
+`bde_search` reads a published catalog snapshot (default `hf://parsimony-dev/bde`).
+Override the snapshot location with the `PARSIMONY_BDE_CATALOG_URL` environment
+variable, or pass `catalog_url=` at call time.
+
+## Quick start
+
+```python
+from parsimony_bde import CONNECTORS
+
+result = CONNECTORS["bde_fetch"](key="D_1NBAF472")
+print(result.data.head())
+```
+
+For multi-plugin composition (autoloads everything installed):
+
+```python
+from parsimony import discover
+connectors = discover.load_all()
+```
+
+## Catalogs
+
+`enumerate_bde` discovers the full BdE series catalog — ~15.5k unique series
+across six published CSV chapters (`be`, `cf`, `ie`, `si`, `tc`, `ti`), plus the
+Bank Lending Survey. The survey's CSV chapter lists only un-fetchable family
+aliases (`PB_1_1.1`), so its real fetchable codes (`DPB…`) are recovered from the
+bulk `pb.zip`. Rows are de-duplicated by series code (a series can appear under
+more than one thematic chapter). Maintainers build a `Catalog` snapshot from the
+enumerator (see `scripts/build_catalog.py`) and push it to the snapshot URL that
+`bde_search` reads. The crawl is expensive (the CF/Financial-Accounts chapter
+alone is several thousand series), so it runs offline as a publish job — never at
+query time.
+
+A small tail (~1% of catalog codes, mostly dollar-denominated `…$…` financial
+accounts variants and a handful of external-sector series) is listed in the CSV
+catalog but not served by the web service; fetching such a code returns a clear
+`InvalidParameterError` rather than data.
+
+## Provider
+
+- Homepage: https://www.bde.es
+- API docs: https://www.bde.es/webbe/en/estadisticas/recursos/api-estadisticas-bde.html
+- Series browser: https://app.bde.es/bie_www/bie_wwwias/xml/Arranque.html (BIEST)
+
+## License
+
+See [LICENSE](./LICENSE).

parsimony_bde-0.0.1/parsimony_bde/__init__.py

@@ -0,0 +1,10 @@
+"""Banco de España (BdE): fetch + catalog enumeration."""
+
+from __future__ import annotations
+
+from parsimony_bde.connectors import CONNECTORS, load
+from parsimony_bde.connectors.enumerate import enumerate_bde
+from parsimony_bde.connectors.fetch import bde_fetch
+from parsimony_bde.search import bde_search
+
+__all__ = ["CONNECTORS", "load", "bde_fetch", "enumerate_bde", "bde_search"]

parsimony_bde-0.0.1/parsimony_bde/_http.py

@@ -0,0 +1,82 @@
+"""BdE REST and catalog CSV transport."""
+
+from __future__ import annotations
+
+BASE_URL = "https://app.bde.es/bierest/resources/srdatosapp"
+CATALOG_CSV_BASE_URL = "https://www.bde.es/webbe/es/estadisticas/compartido/datos/csv"
+CATALOG_ZIP_BASE_URL = "https://www.bde.es/webbe/es/estadisticas/compartido/datos/zip"
+
+# Six of the seven published catalog chapters list API-fetchable ``serie`` codes
+# directly in their CSV. The seventh — ``pb`` (Bank Lending Survey) — is the
+# odd one out: its CSV ``serie`` column holds *family/table* codes (``PB_1_1.1``)
+# that the BIEST web service rejects with HTTP 412 "no existe". The real
+# fetchable codes for that survey live only inside the bulk ``pb.zip`` value
+# files, so ``pb`` is enumerated from the ZIP instead (see ``PB_ZIP_URL`` and
+# ``connectors/_catalog.parse_pb_zip``). Live-verified 2026-06-08.
+CATALOG_CHAPTERS: tuple[tuple[str, str], ...] = (
+    ("be", "General Statistics"),
+    ("cf", "Financial Accounts"),
+    ("ie", "International Economy"),
+    ("si", "Financial Indicators"),
+    ("tc", "Exchange Rates"),
+    ("ti", "Interest Rates"),
+)
+
+# Bank Lending Survey — recovered from the bulk ZIP, not the CSV catalog.
+PB_ZIP_URL = f"{CATALOG_ZIP_BASE_URL}/pb.zip"
+PB_CATEGORY = "Bank Lending Survey"
+
+CSV_ENCODING = "cp1252"
+CSV_HEADERS: tuple[str, ...] = (
+    "serie",
+    "seq",
+    "alias",
+    "file",
+    "description",
+    "var_type",
+    "unit_code",
+    "exponent",
+    "decimals",
+    "unit_desc",
+    "frequency_raw",
+    "start_date",
+    "end_date",
+    "n_obs",
+    "title",
+    "source_org",
+    "notes",
+)
+
+FREQ_MAP_RAW = {
+    "DIARIA": "Daily",
+    "LABORABLE": "Business Daily",
+    "SEMANAL": "Weekly",
+    "QUINCENAL": "Bi-weekly",
+    "MENSUAL": "Monthly",
+    "TRIMESTRAL": "Quarterly",
+    "SEMESTRAL": "Semi-annual",
+    "ANUAL": "Annual",
+}
+
+FREQ_MAP = {
+    "D": "Daily",
+    "M": "Monthly",
+    "Q": "Quarterly",
+    "A": "Annual",
+    "S": "Semi-annual",
+    "W": "Weekly",
+    "B": "Business Daily",
+}
+
+COLUMN_MAP = {
+    "serie": "key",
+    "descripcion": "description",
+    "descripcionCorta": "title",
+    "codFrecuencia": "freq",
+    "decimales": "decimals",
+    "simbolo": "symbol",
+    "fechaInicio": "start_date",
+    "fechaFin": "end_date",
+    "fechas": "date",
+    "valores": "value",
+}

parsimony_bde-0.0.1/parsimony_bde/catalog_build.py

@@ -0,0 +1,35 @@
+"""Build the Banco de España catalog snapshot."""
+
+from __future__ import annotations
+
+import logging
+
+from parsimony.catalog import Catalog
+from parsimony.catalog.policy import discovery_indexes
+from parsimony.catalog.source import entities_from_raw
+
+from parsimony_bde.connectors.enumerate import enumerate_bde
+from parsimony_bde.outputs import BDE_ENUMERATE_OUTPUT
+
+logger = logging.getLogger(__name__)
+
+CATALOG_NAMESPACE = "bde"
+
+
+def build_bde_catalog() -> Catalog:
+    """Enumerate and build the Banco de España catalog.
+
+    Titles and descriptions are in Spanish — BdE's published catalog CSV
+    chapters have no English variant.
+    """
+    result = enumerate_bde()
+    df = result.data
+
+    entries = entities_from_raw(df, BDE_ENUMERATE_OUTPUT)
+    catalog = Catalog(CATALOG_NAMESPACE, indexes=discovery_indexes(entries), default_field="title")
+    catalog.set_entities(entries)
+    catalog.build()
+    return catalog
+
+
+__all__ = ["CATALOG_NAMESPACE", "build_bde_catalog"]

parsimony_bde-0.0.1/parsimony_bde/connectors/__init__.py

@@ -0,0 +1,21 @@
+"""bde connector registry."""
+
+from __future__ import annotations
+
+from parsimony.connector import Connectors
+
+from parsimony_bde.connectors.enumerate import enumerate_bde
+from parsimony_bde.connectors.fetch import bde_fetch
+from parsimony_bde.search import bde_search
+
+CONNECTORS = Connectors([bde_fetch, enumerate_bde, bde_search])
+
+
+def load(*, catalog_url: str | None = None) -> Connectors:
+    """Return :data:`CONNECTORS` with an optional catalog URL bound on search."""
+    if catalog_url is None:
+        return CONNECTORS
+    return CONNECTORS.bind(catalog_url=catalog_url)
+
+
+__all__ = ["CONNECTORS", "load"]

parsimony_bde-0.0.1/parsimony_bde/connectors/_catalog.py

@@ -0,0 +1,199 @@
+"""BdE catalog CSV parsing helpers."""
+
+from __future__ import annotations
+
+import csv
+import io
+import logging
+import unicodedata
+import zipfile
+
+from parsimony_bde._http import CSV_HEADERS, FREQ_MAP_RAW, PB_CATEGORY
+
+logger = logging.getLogger(__name__)
+
+
+def _fold(text: str) -> str:
+    """Upper-case and strip accents so Spanish row labels match regardless of
+    encoding round-trips (``DESCRIPCIÓN`` == ``DESCRIPCION``)."""
+    nfkd = unicodedata.normalize("NFKD", text)
+    return "".join(c for c in nfkd if not unicodedata.combining(c)).strip().upper()
+
+
+# Row labels (accent-folded) in the transposed ``pb.zip`` value files.
+_PB_NOMBRE = "NOMBRE DE LA SERIE"
+_PB_ALIAS = "ALIAS DE LA SERIE"
+_PB_DESC = "DESCRIPCION DE LA SERIE"
+_PB_UNIT = "DESCRIPCION DE LAS UNIDADES"
+_PB_FREQ = "FRECUENCIA"
+_PB_SEQ = "NUMERO SECUENCIAL"
+_PB_META_LABELS = frozenset({_PB_NOMBRE, _PB_ALIAS, _PB_DESC, _PB_UNIT, _PB_FREQ, _PB_SEQ})
+
+
+def split_title_path(raw: str) -> tuple[str, str]:
+    """Split a "/"-separated BdE title-path into (dataset, leaf_title)."""
+    if "/" not in raw:
+        return "", raw.strip()
+    parts = [p.strip() for p in raw.split("/") if p.strip()]
+    if not parts:
+        return "", raw.strip()
+    if len(parts) == 1:
+        return "", parts[0]
+    if all(":" in p for p in parts):
+        return " › ".join(parts), ""
+    return " › ".join(parts[:-1]), parts[-1]
+
+
+def parse_catalog_csv(text: str, *, category: str) -> list[dict[str, str]]:
+    """Parse one ``catalogo_*.csv`` payload into enumerator rows."""
+    reader = csv.reader(io.StringIO(text))
+    rows: list[dict[str, str]] = []
+
+    header_seen = False
+    for raw_row in reader:
+        if not raw_row:
+            continue
+        if not header_seen:
+            header_seen = True
+            continue
+        if len(raw_row) < len(CSV_HEADERS):
+            logger.debug(
+                "skipping malformed BdE catalog row (got %d cols, expected %d)",
+                len(raw_row),
+                len(CSV_HEADERS),
+            )
+            continue
+
+        record = dict(zip(CSV_HEADERS, raw_row, strict=False))
+        serie = (record.get("serie") or "").strip()
+        if not serie:
+            continue
+
+        title_raw = (record.get("title") or "").strip()
+        dataset, leaf_title = split_title_path(title_raw)
+        title = leaf_title or (record.get("description") or "").strip() or serie
+
+        freq_raw = (record.get("frequency_raw") or "").strip().upper()
+        frequency = FREQ_MAP_RAW.get(freq_raw, freq_raw.title() if freq_raw else "")
+
+        rows.append(
+            {
+                "key": serie,
+                "title": title,
+                "description": (record.get("description") or "").strip(),
+                "source": "bde_biest",
+                "alias": (record.get("alias") or "").strip(),
+                "dataset": dataset,
+                "category": category,
+                "frequency": frequency,
+                "unit": (record.get("unit_desc") or record.get("unit_code") or "").strip(),
+                "decimals": (record.get("decimals") or "").strip(),
+                "start_date": (record.get("start_date") or "").strip(),
+                "end_date": (record.get("end_date") or "").strip(),
+                "n_obs": (record.get("n_obs") or "").strip(),
+                "source_org": (record.get("source_org") or "").strip(),
+            }
+        )
+    return rows
+
+
+def _parse_pb_member(text: str) -> list[dict[str, str]]:
+    """Parse one transposed ``pb_*.csv`` value file from ``pb.zip``.
+
+    The Bank Lending Survey files are laid out column-per-series: row 0 holds the
+    real fetchable ``serie`` codes (``DPB…``), row 2 their ``PB_x_y.z`` aliases,
+    plus description / units / frequency rows, then one row per observation date.
+    We read the metadata rows (the values are fetched live by ``bde_fetch``) and
+    derive ``start_date`` / ``end_date`` / ``n_obs`` per column from the date
+    rows so the catalog entry matches the richness of the CSV chapters.
+    """
+    reader = csv.reader(io.StringIO(text))
+    by_label: dict[str, list[str]] = {}
+    date_rows: list[tuple[str, list[str]]] = []
+    for raw_row in reader:
+        if not raw_row:
+            continue
+        label = _fold(raw_row[0])
+        cells = [c.strip() for c in raw_row[1:]]
+        if label in _PB_META_LABELS:
+            by_label[label] = cells
+        elif label:
+            date_rows.append((raw_row[0].strip(), cells))
+
+    names = by_label.get(_PB_NOMBRE, [])
+    if not names:
+        return []
+    aliases = by_label.get(_PB_ALIAS, [])
+    descs = by_label.get(_PB_DESC, [])
+    units = by_label.get(_PB_UNIT, [])
+    freqs = by_label.get(_PB_FREQ, [])
+
+    rows: list[dict[str, str]] = []
+    for j, raw_key in enumerate(names):
+        key = raw_key.strip()
+        # Real BdE series codes never contain whitespace; a value with a space is
+        # a stray header label from a non-transposed member and is skipped.
+        if not key or " " in key:
+            continue
+        # Span/count from the date rows where this column carries a value.
+        present = [label for label, cells in date_rows if j < len(cells) and cells[j] != ""]
+        desc = descs[j].strip() if j < len(descs) else ""
+        freq_raw = (freqs[j].strip().upper() if j < len(freqs) else "")
+        rows.append(
+            {
+                "key": key,
+                "title": desc or key,
+                "description": desc,
+                "source": "bde_biest",
+                "alias": aliases[j].strip() if j < len(aliases) else "",
+                "dataset": "",
+                "category": PB_CATEGORY,
+                "frequency": FREQ_MAP_RAW.get(freq_raw, freq_raw.title() if freq_raw else ""),
+                "unit": units[j].strip() if j < len(units) else "",
+                "decimals": "",
+                "start_date": present[0] if present else "",
+                "end_date": present[-1] if present else "",
+                "n_obs": str(len(present)) if present else "",
+                "source_org": "Banco de España",
+            }
+        )
+    return rows
+
+
+def parse_pb_zip(zip_bytes: bytes) -> list[dict[str, str]]:
+    """Parse every member of the Bank Lending Survey ``pb.zip`` into enumerator
+    rows keyed by the real fetchable ``DPB…`` series code.
+
+    Best-effort, mirroring the CSV crawl: a corrupt member is logged and skipped
+    so a partial survey still enumerates. De-dups within the archive by key
+    (a series can recur across family files)."""
+    rows: list[dict[str, str]] = []
+    seen: set[str] = set()
+    try:
+        with zipfile.ZipFile(io.BytesIO(zip_bytes)) as archive:
+            for member in archive.namelist():
+                basename = member.rsplit("/", 1)[-1].lower()
+                # The archive bundles the standard ``catalogo_pb.csv``
+                # (un-fetchable alias catalog) next to the transposed
+                # ``pb_*.csv`` value files. Only the value files carry the real
+                # fetchable codes.
+                if not (basename.startswith("pb_") and basename.endswith(".csv")):
+                    continue
+                try:
+                    raw = archive.read(member)
+                except (KeyError, zipfile.BadZipFile):
+                    logger.warning("BdE pb.zip member %r unreadable; skipping", member)
+                    continue
+                try:
+                    text = raw.decode("cp1252")
+                except UnicodeDecodeError:
+                    text = raw.decode("latin-1", errors="replace")
+                for row in _parse_pb_member(text):
+                    if row["key"] in seen:
+                        continue
+                    seen.add(row["key"])
+                    rows.append(row)
+    except zipfile.BadZipFile:
+        logger.warning("BdE pb.zip is not a valid archive; skipping Bank Lending Survey")
+        return []
+    return rows

parsimony_bde-0.0.1/parsimony_bde/connectors/enumerate.py

@@ -0,0 +1,112 @@
+"""BdE catalog enumeration connector.
+
+Discovers BdE statistical series from the published catalog. Six of the seven
+chapters are crawled as ``catalogo_*.csv`` files; the seventh, the Bank Lending
+Survey (``pb``), is recovered from the bulk ``pb.zip`` because its CSV lists
+un-fetchable family aliases rather than real series codes (see ``_http`` and
+``_catalog.parse_pb_zip``). The crawl uses the shared ``ThrottledJsonFetcher``
+(throttled, retrying serial fan-out over a raw ``httpx.Client``).
+
+Best-effort by design: a per-source failure is logged and skipped so a partial
+catalog is still produced (catalog publish jobs check ``len(df) == 0``
+separately). The combined rows are de-duplicated by ``key`` — a series can be
+listed under more than one thematic chapter (≈24% of raw rows are such
+cross-chapter repeats), and the first occurrence in chapter order wins so the
+result is deterministic. The returned frame matches ``ENUMERATE_COLUMNS``
+exactly, as the ``@enumerator`` contract requires (it drops unmapped columns
+then demands an exact match against the declared schema).
+"""
+
+from __future__ import annotations
+
+import logging
+
+import httpx
+import pandas as pd
+from parsimony.connector import enumerator
+from parsimony_shared.cb_enumerate import MetadataCrawlConfig, ThrottledJsonFetcher
+
+from parsimony_bde._http import (
+    CATALOG_CHAPTERS,
+    CATALOG_CSV_BASE_URL,
+    CSV_ENCODING,
+    PB_ZIP_URL,
+)
+from parsimony_bde.connectors._catalog import parse_catalog_csv, parse_pb_zip
+from parsimony_bde.outputs import BDE_ENUMERATE_OUTPUT, ENUMERATE_COLUMNS
+
+logger = logging.getLogger(__name__)
+
+METADATA_CRAWL = MetadataCrawlConfig(inter_request_delay_s=0.25)
+
+
+def _fetch_catalog_chapter(
+    fetcher: ThrottledJsonFetcher,
+    chapter: str,
+    category: str,
+) -> list[dict[str, str]]:
+    """Fetch + decode + parse one ``catalogo_*.csv`` chapter into enumerator rows."""
+    url = f"{CATALOG_CSV_BASE_URL}/catalogo_{chapter}.csv"
+    raw_bytes = fetcher.get_content(url, label=f"catalogo_{chapter}")
+    if raw_bytes is None:
+        logger.warning("BdE catalog chapter %r unavailable after retries", chapter)
+        return []
+    try:
+        text = raw_bytes.decode(CSV_ENCODING)
+    except UnicodeDecodeError:
+        text = raw_bytes.decode("latin-1", errors="replace")
+    return parse_catalog_csv(text, category=category)
+
+
+def _fetch_pb_survey(fetcher: ThrottledJsonFetcher) -> list[dict[str, str]]:
+    """Fetch + parse the Bank Lending Survey bulk ``pb.zip`` into enumerator rows."""
+    raw_bytes = fetcher.get_content(PB_ZIP_URL, label="pb_zip")
+    if raw_bytes is None:
+        logger.warning("BdE Bank Lending Survey (pb.zip) unavailable after retries")
+        return []
+    return parse_pb_zip(raw_bytes)
+
+
+def _dedupe_by_key(rows: list[dict[str, str]]) -> list[dict[str, str]]:
+    """Keep the first row per ``key`` (cross-chapter repeats collapse here)."""
+    seen: set[str] = set()
+    deduped: list[dict[str, str]] = []
+    for row in rows:
+        key = row["key"]
+        if key in seen:
+            continue
+        seen.add(key)
+        deduped.append(row)
+    return deduped
+
+
+@enumerator(output=BDE_ENUMERATE_OUTPUT, tags=["macro", "es"])
+def enumerate_bde() -> pd.DataFrame:
+    """Enumerate BdE statistical series from the published catalog (6 CSV chapters
+    + the Bank Lending Survey recovered from ``pb.zip``), de-duplicated by code.
+
+    Titles and descriptions are in Spanish — BdE's catalog CSV chapters have no
+    English variant.
+    """
+    rows: list[dict[str, str]] = []
+    with httpx.Client(timeout=60.0, follow_redirects=True) as client:
+        fetcher = ThrottledJsonFetcher(
+            client,
+            provider="bde",
+            config=METADATA_CRAWL,
+            logger=logger,
+        )
+
+        def _one(chapter: str, category: str) -> list[dict[str, str]]:
+            return _fetch_catalog_chapter(fetcher, chapter, category)
+
+        # Order matters: CSV chapters come before pb.zip so that on a
+        # cross-source duplicate the CSV chapter wins in _dedupe_by_key (first
+        # occurrence). Process serially to preserve that order.
+        for chapter, category in CATALOG_CHAPTERS:
+            rows.extend(_one(chapter, category))
+        rows.extend(_fetch_pb_survey(fetcher))
+
+    # @enumerator drops unmapped columns then requires an EXACT match — build
+    # the frame with exactly the declared columns (header-only if all failed).
+    return pd.DataFrame(_dedupe_by_key(rows), columns=list(ENUMERATE_COLUMNS))

parsimony_bde-0.0.1/parsimony_bde/connectors/fetch.py

@@ -0,0 +1,175 @@
+"""BdE series fetch connector.
+
+Banco de España BIEST is a **keyless** public JSON API — no api_key, no
+``secrets=``/``bind()``/``load()``, no ``UnauthorizedError``. The
+``listaSeries`` endpoint returns long-format JSON (``fechas``/``valores``
+parallel arrays) which we reshape into one row per (series, observation).
+"""
+
+from __future__ import annotations
+
+import contextlib
+from datetime import datetime
+from typing import Annotated, Any, NoReturn
+
+import httpx
+import pandas as pd
+from parsimony import Namespace
+from parsimony.connector import connector
+from parsimony.errors import EmptyDataError, InvalidParameterError, ParseError
+from parsimony.transport import map_http_error, map_timeout_error
+from parsimony.transport.helpers import make_http_client
+
+from parsimony_bde._http import BASE_URL
+from parsimony_bde.outputs import BDE_FETCH_OUTPUT
+
+# ``rango`` is frequency-dependent and BdE validates it server-side:
+#   monthly / quarterly / semestral : 30M, 60M, MAX, or a 4-digit year
+#   daily / business-daily          : 3M, 12M, 36M, or a 4-digit year (NOT MAX)
+#   annual                          : 60M, MAX, or a 4-digit year
+# A single request may mix frequencies, so the connector can't know the right
+# vocabulary up front. We accept the union of literal codes here and let BdE
+# reject a code that doesn't apply to a series' frequency — its HTTP 412 is
+# surfaced as InvalidParameterError (see ``_raise_bde_http_error``).
+_VALID_RANGES = frozenset({"3M", "12M", "36M", "30M", "60M", "MAX"})
+_VALID_LANGS = frozenset({"en", "es"})
+
+
+def _validate_time_range(time_range: str | None) -> str | None:
+    """Normalise and validate the ``time_range`` argument.
+
+    Accepts ``3M``/``12M``/``36M``/``30M``/``60M``/``MAX`` (case-insensitive) or
+    a 4-digit year. Which codes are valid depends on the series frequency (BdE
+    enforces that), so this only screens out plainly malformed values. Returns
+    the validated value, or ``None`` for the default range.
+    """
+    if time_range is None:
+        return None
+    value = time_range.strip()
+    if not value:
+        return None
+    if value.upper() in _VALID_RANGES:
+        return value.upper()
+    if value.isdigit() and len(value) == 4:  # a 4-digit calendar year
+        return value
+    raise InvalidParameterError(
+        "bde",
+        f"Invalid time_range '{time_range}'. Use 3M/12M/36M/30M/60M/MAX "
+        "(frequency-dependent) or a 4-digit year (e.g. 2024).",
+    )
+
+
+def _raise_bde_http_error(exc: httpx.HTTPStatusError, keys: list[str]) -> NoReturn:
+    """Map a BdE ``listaSeries`` HTTP error to a typed connector error.
+
+    BdE answers an invalid series code or a frequency-incompatible ``rango`` with
+    HTTP 412 and a ``{"errNum", "errMsgUsr", "errMsgDebug"}`` body — a caller
+    input problem, so it surfaces as :class:`InvalidParameterError` carrying
+    BdE's own message. Everything else defers to the canonical mapping.
+    """
+    if exc.response.status_code == 412:
+        detail = ""
+        with contextlib.suppress(Exception):
+            body = exc.response.json()
+            if isinstance(body, dict):
+                detail = (body.get("errMsgDebug") or body.get("errMsgUsr") or "").strip()
+        raise InvalidParameterError(
+            "bde",
+            detail or f"BdE rejected the request for series: {','.join(keys)}",
+        ) from exc
+    map_http_error(exc, provider="bde", op_name="series")
+
+
+def _parse_bde_response(json_data: list[dict[str, Any]]) -> pd.DataFrame:
+    """Parse BdE long-format JSON into a flat ``key,title,date,value`` frame."""
+    all_rows: list[dict[str, Any]] = []
+
+    for series in json_data:
+        key = series.get("serie", "")
+        title = series.get("descripcionCorta") or series.get("descripcion") or key
+        dates = series.get("fechas", [])
+        values = series.get("valores", [])
+
+        if not dates or not values:
+            continue
+
+        for date_str, raw_value in zip(dates, values, strict=False):
+            try:
+                value = float(raw_value) if raw_value not in (None, "", "NaN") else None
+            except (ValueError, TypeError):
+                value = None
+
+            date_val = date_str
+            if isinstance(date_str, str) and "T" in date_str:
+                with contextlib.suppress(ValueError):
+                    date_val = datetime.strptime(date_str[:10], "%Y-%m-%d").strftime("%Y-%m-%d")
+
+            all_rows.append({"key": key, "title": title, "date": date_val, "value": value})
+
+    if not all_rows:
+        return pd.DataFrame(columns=["key", "title", "date", "value"])
+    return pd.DataFrame(all_rows)
+
+
+@connector(output=BDE_FETCH_OUTPUT, tags=["macro", "es"])
+def bde_fetch(
+    key: Annotated[str, Namespace("bde")],
+    time_range: str | None = None,
+    lang: str = "en",
+) -> pd.DataFrame:
+    """Fetch Banco de España time series by series code(s).
+
+    ``key`` is one or more comma-separated BdE series codes (e.g.
+    ``D_1NBAF472,DTCCBCEUSDEUR.B``); all are fetched in a single request.
+    ``time_range`` is frequency-dependent: monthly/quarterly series take
+    ``30M``/``60M``/``MAX``, daily series take ``3M``/``12M``/``36M`` (not
+    ``MAX``), and any frequency accepts a 4-digit year (e.g. ``2024``); ``None``
+    returns BdE's default range. A range that doesn't fit a series' frequency is
+    rejected by BdE as an ``InvalidParameterError``. ``lang`` selects the title
+    language (``en`` or ``es``). Returns one row per observation with ``key``,
+    ``title``, ``date``, ``value``.
+    """
+    keys = [k.strip() for k in key.split(",") if k.strip()]
+    if not keys:
+        raise InvalidParameterError("bde", "At least one series code required")
+    if lang not in _VALID_LANGS:
+        raise InvalidParameterError("bde", "lang must be 'en' or 'es'")
+    resolved_range = _validate_time_range(time_range)
+
+    req_params: dict[str, Any] = {
+        "idioma": lang,
+        "series": ",".join(keys),
+        "rango": resolved_range,
+    }
+    http = make_http_client(BASE_URL, timeout=60.0)
+    filtered = {k: v for k, v in req_params.items() if v is not None}
+    try:
+        response = http.request("GET", "/listaSeries", params=filtered or None)
+        response.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        _raise_bde_http_error(exc, keys)
+    except httpx.TimeoutException as exc:
+        map_timeout_error(exc, provider="bde", op_name="series")
+    try:
+        body = response.json()
+    except ValueError as exc:
+        raise ParseError(provider="bde") from exc
+
+    if not isinstance(body, list):
+        raise ParseError("bde", f"unexpected response shape for series: {','.join(keys)}")
+    if not body:
+        raise EmptyDataError(
+            "bde",
+            message=f"BdE returned no series for: {','.join(keys)}",
+            query_params={"key": key, "time_range": time_range, "lang": lang},
+        )
+
+    df = _parse_bde_response(body)
+    if df.empty:
+        raise EmptyDataError(
+            "bde",
+            message=f"No observations parsed for: {','.join(keys)}",
+            query_params={"key": key, "time_range": time_range, "lang": lang},
+        )
+
+    return df

parsimony_bde-0.0.1/parsimony_bde/outputs.py

@@ -0,0 +1,50 @@
+"""BdE connector output schemas."""
+
+from __future__ import annotations
+
+from parsimony.result import Column, ColumnRole, OutputConfig
+
+BDE_ENUMERATE_OUTPUT = OutputConfig(
+    columns=[
+        Column(name="key", role=ColumnRole.KEY, namespace="bde"),
+        Column(name="title", role=ColumnRole.TITLE),
+        Column(name="description", role=ColumnRole.METADATA),
+        Column(name="source", role=ColumnRole.METADATA),
+        Column(name="alias", role=ColumnRole.METADATA),
+        Column(name="dataset", role=ColumnRole.METADATA),
+        Column(name="category", role=ColumnRole.METADATA),
+        Column(name="frequency", role=ColumnRole.METADATA),
+        Column(name="unit", role=ColumnRole.METADATA),
+        Column(name="decimals", role=ColumnRole.METADATA),
+        Column(name="start_date", role=ColumnRole.METADATA),
+        Column(name="end_date", role=ColumnRole.METADATA),
+        Column(name="n_obs", role=ColumnRole.METADATA),
+        Column(name="source_org", role=ColumnRole.METADATA),
+    ]
+)
+
+BDE_FETCH_OUTPUT = OutputConfig(
+    columns=[
+        Column(name="key", role=ColumnRole.KEY, namespace="bde"),
+        Column(name="title", role=ColumnRole.TITLE),
+        Column(name="date", dtype="datetime", role=ColumnRole.DATA),
+        Column(name="value", dtype="numeric", role=ColumnRole.DATA),
+    ]
+)
+
+ENUMERATE_COLUMNS: tuple[str, ...] = (
+    "key",
+    "title",
+    "description",
+    "source",
+    "alias",
+    "dataset",
+    "category",
+    "frequency",
+    "unit",
+    "decimals",
+    "start_date",
+    "end_date",
+    "n_obs",
+    "source_org",
+)

parsimony_bde-0.0.1/parsimony_bde/search.py

@@ -0,0 +1,34 @@
+"""Semantic search over the published Banco de España (BdE) catalog."""
+
+from __future__ import annotations
+
+from parsimony.catalog.search import CatalogSearchParams, make_local_search_connector
+from parsimony.result import Column, ColumnRole, OutputConfig
+
+from parsimony_bde.catalog_build import build_bde_catalog
+
+BdeSearchParams = CatalogSearchParams
+
+PARSIMONY_BDE_CATALOG_URL_ENV = "PARSIMONY_BDE_CATALOG_URL"
+
+BDE_SEARCH_OUTPUT = OutputConfig(
+    columns=[
+        Column(name="code", role=ColumnRole.KEY, namespace="bde"),
+        Column(name="title", role=ColumnRole.TITLE),
+        Column(name="score", role=ColumnRole.DATA),
+    ]
+)
+
+bde_search = make_local_search_connector(
+    provider="bde",
+    default_url="hf://parsimony-dev/bde",
+    catalog_url_env_var=PARSIMONY_BDE_CATALOG_URL_ENV,
+    build_catalog=build_bde_catalog,
+    tags=["macro", "es", "tool"],
+    description=(
+        "Semantic-search the Banco de España (BdE) catalog. "
+        "Titles and descriptions are in Spanish. "
+        "Pass returned serie code to bde_fetch(key=...)."
+    ),
+    output_columns=BDE_SEARCH_OUTPUT.columns,
+)

parsimony_bde-0.0.1/pyproject.toml

@@ -0,0 +1,80 @@
+[project]
+name = "parsimony-bde"
+version = "0.0.1"
+description = "Banco de España connector for the parsimony framework"
+authors = [{ name = "Ockham.sh", email = "team@ockham.sh" }]
+license = "Apache-2.0"
+readme = "README.md"
+requires-python = ">=3.11"
+keywords = ["finance", "data", "connectors", "parsimony", "bde"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "parsimony-core[catalog]>=0.0.1",
+    "parsimony-shared>=0.0.1",
+    "pydantic>=2.11.1,<3",
+    "pandas>=2.3.0,<3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-cov>=5.0",
+    "respx>=0.22.0",
+    "ruff>=0.15.10",
+    "mypy>=1.10",
+]
+
+[project.urls]
+Homepage = "https://www.bde.es"
+Repository = "https://github.com/ockham-sh/parsimony-connectors"
+Issues = "https://github.com/ockham-sh/parsimony-connectors/issues"
+
+[project.entry-points."parsimony.providers"]
+bde = "parsimony_bde"
+
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["parsimony_bde"]
+
+[tool.hatch.build.targets.sdist]
+include = ["parsimony_bde", "README.md", "LICENSE", "CHANGELOG.md"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ruff.lint.per-file-ignores]
+# Publish scripts call logging.basicConfig() before importing parsimony so
+# the kernel's INFO logs surface during the long-running publish pipeline.
+"scripts/*" = ["E402"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_ignores = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+addopts = "--import-mode=importlib -m 'not integration'"
+markers = [
+    "integration: hits live APIs (may be slow, requires env vars)",
+]