0002 (companion) — The Bolivia authority pack: concrete spec + provider skeleton¶

opencontractserver/enrichment/data/authority_packs/bolivia/
├── README.md                         # what it ships, how to load, how to extend
├── pack.yaml                         # manifest → load_authority_pack
├── authority_mappings.bolivia.yaml   # → AuthorityMappingLoader.load_all(path=…)
├── specs/
│   └── constitucional.json           # → bootstrap_authority_corpus
└── personas/
    └── constitucional.es.txt         # → Corpus.corpus_agent_instructions
# Phase 2 adds: providers/bolivia_gaceta_provider.py (→ auto-discovered package)

# Bolivia authority pack — namespace registry + classification.
# Load: manage.py shell -c \
#   "from opencontractserver.enrichment.services.authority_mapping_loader import AuthorityMappingLoader; \
#    AuthorityMappingLoader.load_all(path='authority-packs/bolivia/authority_mappings.bolivia.yaml')"
prefixes:
  cpe:
    display_name: "Constitución Política del Estado (2009)"
    jurisdiction: "bo"
    authority_type: "constitution"
    aliases: ["constitución política del estado", "cpe", "constitución"]
  bo-ley:
    display_name: "Leyes del Estado Plurinacional de Bolivia"
    jurisdiction: "bo"
    authority_type: "statute"
    aliases: ["ley", "leyes"]
  bo-ds:
    display_name: "Decretos Supremos"
    jurisdiction: "bo"
    authority_type: "regulation"
    aliases: ["decreto supremo", "ds", "decretos supremos"]
  bo-scp:
    display_name: "Sentencias Constitucionales Plurinacionales (TCP)"
    jurisdiction: "bo"
    authority_type: "case"
    aliases: ["sentencia constitucional plurinacional", "scp", "sentencia constitucional", "sc"]
  bo-as:
    display_name: "Autos Supremos (Tribunal Supremo de Justicia)"
    jurisdiction: "bo"
    authority_type: "case"
    aliases: ["auto supremo", "autos supremos", "as"]

# Optional — only needed if popular-name citations must reach a differently-keyed
# provider. Example: a code's popular name → its enacting Ley number.
equivalences:
  - { from_key: "codigo-penal:bo", to_key: "bo-ley:1768", note: "Código Penal (Ley 1768)" }
  - { from_key: "codigo-procesal-penal:bo", to_key: "bo-ley:1970", note: "Código de Procedimiento Penal (Ley 1970)" }

# rewrite_rules: omit unless there is a genuinely mechanical 1:1 prefix transform.

"""Bolivia Gaceta Oficial authority source provider (SKELETON — illustrative).

Resolves Bolivian primary law published in the Gaceta Oficial de Bolivia:
    cpe:{article}      Constitución Política del Estado          -> cpe:13
    bo-ley:{number}    Ley del Estado Plurinacional               -> bo-ley:1970
    bo-ds:{number}     Decreto Supremo                            -> bo-ds:29894

License: public-domain (Bolivian official legal texts). All HTTP goes through
opencontractserver.utils.safe_http (the source host must be on
PUBLIC_DOMAIN_SOURCE_HOSTS — see the README's allowlist edit).
"""

from __future__ import annotations

import logging
import re
from typing import ClassVar

from opencontractserver.enrichment.authorities import AuthoritySection
from opencontractserver.pipeline.base.base_authority_source_provider import (
    AuthorityRequest,
    BaseAuthoritySourceProvider,
)
from opencontractserver.utils.safe_http import safe_fetch_text

logger = logging.getLogger(__name__)

# Gaceta Oficial host — must also be added to PUBLIC_DOMAIN_SOURCE_HOSTS.
_GACETA_HOST = "gacetaoficialdebolivia.gob.bo"
# TODO(pack): replace with the real document endpoint(s) per instrument family.
_URL_TEMPLATE = "https://gacetaoficialdebolivia.gob.bo/normas/{kind}/{number}"

# Citation labels per prefix (human-readable, Spanish).
_CITATION = {
    "cpe": "Constitución Política del Estado, art. {n}",
    "bo-ley": "Ley N° {n} (Bolivia)",
    "bo-ds": "Decreto Supremo N° {n}",
}
# URL path segment per prefix.
_KIND = {"cpe": "constitucion", "bo-ley": "ley", "bo-ds": "decreto-supremo"}

# Identifier component validation (no URL/selector injection). The class is
# already lowercase-only — canonical keys are normalised to lowercase upstream —
# so no IGNORECASE flag (it would silently widen the pattern to accept uppercase).
_NUMBER_RE = re.compile(r"^[0-9][0-9a-z\-]*$")


def _validate_number(prefix: str, number: str) -> None:
    if not _NUMBER_RE.match(number):
        raise ValueError(f"Invalid {prefix} identifier component: {number!r}")


class BoliviaGacetaProvider(BaseAuthoritySourceProvider):
    """Fetches Bolivian primary law from the Gaceta Oficial (public domain)."""

    title = "Gaceta Oficial de Bolivia"
    description = "Constitución, Leyes y Decretos Supremos del Estado Plurinacional."
    license: ClassVar[str] = "public-domain"
    priority: ClassVar[int] = 100          # below the agentic fallback (9999)
    enabled: ClassVar[bool] = True
    requires_approval: ClassVar[bool] = False
    supported_prefixes: ClassVar[tuple[str, ...]] = ("cpe", "bo-ley", "bo-ds")

    # ---- pure: derive the fetch plan (no I/O) -----------------------------
    def _locate_impl(self, canonical_key: str, **all_kwargs) -> AuthorityRequest:
        # can_handle() guarantees a "prefix:ident" key in production, but guard
        # the split so a direct unit-test call fails loudly instead of with an
        # opaque "not enough values to unpack".
        if ":" not in canonical_key:
            raise ValueError(f"Not a prefixed canonical key: {canonical_key!r}")
        prefix, ident = canonical_key.split(":", 1)
        _validate_number(prefix, ident)
        return AuthorityRequest(
            canonical_key=canonical_key,
            url=_URL_TEMPLATE.format(kind=_KIND[prefix], number=ident),
            citation=_CITATION[prefix].format(n=ident),
            extra={"prefix": prefix, "ident": ident},
        )

    # ---- HTTP + parse (the only network site) -----------------------------
    def _fetch_impl(self, request: AuthorityRequest, **all_kwargs) -> list[AuthoritySection]:
        html = self._load_document(request)
        heading, text = self._parse(html, request)   # TODO(pack): real selectors
        if not text.strip():
            logger.warning("BoliviaGacetaProvider: empty body for %s", request.canonical_key)
            return []
        return [
            AuthoritySection(
                key=request.canonical_key,
                heading=heading,
                text=text,
                source_url=request.url,
            )
        ]

    # ---- test seam: patch this in tests with httpx.MockTransport fixtures --
    def _load_document(self, request: AuthorityRequest) -> str:
        text, _ = safe_fetch_text(request.url)
        return text

    def _parse(self, html: str, request: AuthorityRequest) -> tuple[str, str]:
        # TODO(pack): port PR #1305 GacetaOficialScraper's defensive parsing here.
        raise NotImplementedError("Fill from the live Gaceta Oficial document shape.")

{
  "aliases": ["Constitución Política del Estado", "CPE"],
  "sections": [
    {
      "key": "cpe:13",
      "heading": "CPE art. 13 — Derechos fundamentales",
      "text": "I. Los derechos reconocidos por esta Constitución son inviolables, universales, interdependientes, indivisibles y progresivos. El Estado tiene el deber de promoverlos, protegerlos y respetarlos. …",
      "source_url": "https://gacetaoficialdebolivia.gob.bo/normas/constitucion/13"
    },
    {
      "key": "cpe:14",
      "heading": "CPE art. 14 — Igualdad y no discriminación",
      "text": "I. Todo ser humano tiene personalidad y capacidad jurídica con arreglo a las leyes y goza de los derechos reconocidos por esta Constitución, sin distinción alguna. …",
      "source_url": "https://gacetaoficialdebolivia.gob.bo/normas/constitucion/14"
    }
  ]
}

Eres un asistente jurídico especializado en derecho constitucional boliviano.
Respondes con base en la Constitución Política del Estado (2009) y la
jurisprudencia del Tribunal Constitucional Plurinacional. Cita siempre el
artículo o la sentencia exacta y distingue entre norma vigente y derogada.

 PUBLIC_DOMAIN_SOURCE_HOSTS: frozenset[str] = frozenset(
     {
         "ecfr.gov",
         "federalregister.gov",
         "govinfo.gov",
         "gpo.gov",
         "uscode.house.gov",
+        # Bolivia authority pack — official public-domain legal sources
+        "gacetaoficialdebolivia.gob.bo",  # Gaceta Oficial (CPE, leyes, decretos)
+        "tsj.bo",                          # Tribunal Supremo de Justicia (autos supremos)
+        "tcpbolivia.bo",                   # Tribunal Constitucional Plurinacional (SCP)
     }
 )

docker compose -f local.yml run --rm django python manage.py load_authority_pack \
  --path opencontractserver/enrichment/data/authority_packs/bolivia \
  --creator <username> --public