pyield 0.57.2__tar.gz → 0.58.1__tar.gz

{pyield-0.57.2 → pyield-0.58.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyield
-Version: 0.57.2
+Version: 0.58.1
 Summary: Polars-powered toolkit for Brazilian fixed income analysis
 Keywords: fixed-income,brazil,finance,analysis,bonds
 Author: Carlos Carvalho
@@ -78,13 +78,13 @@ uv add pyield
 | `yd.di1` | módulo | Curva DI1 e interpolação | `dados`, `interpolar_taxas`, `interpolar_taxa`, `datas_disponiveis` |
 | `yd.tpf` | módulo | Títulos públicos federais | `taxas`, `taxas_historicas`, `vencimentos`, `estoque`, `leiloes`, `benchmarks`, `curva_pre`, `premios_pre`, `secundario` |
 | `yd.rmd(aba)` | função | Relatório Mensal da Dívida do Tesouro Nacional | |
-| `yd.lft` | módulo | LFT | `dados`, `vencimentos`, `cotacao`, `pu`, `taxa`, `vna`, `rentabilidade`, `rentabilidade_expr` |
+| `yd.lft` | módulo | LFT | `dados`, `vencimentos`, `cotacao`, `pu`, `taxa`, `rentabilidade`, `rentabilidade_expr` |
 | `yd.ltn` | módulo | LTN | `dados`, `vencimentos`, `pu`, `taxa`, `duration_expr`, `dv01`, `dv01_expr`, `rentabilidade`, `rentabilidade_expr`, `taxas_forward` |
 | `yd.ntnb` | módulo | NTN-B | `dados`, `vencimentos`, `datas_pagamento`, `fluxos_caixa`, `cotacao`, `pu`, `taxa`, `taxas_zero`, `duration`, `dv01`, `dv01_expr`, `implicitas`, `curva` |
 | `yd.ntnb1` | módulo | NTN-B1 (Educa+ e Renda+) | `NomeComercial`, `datas_pagamento`, `fluxos_caixa`, `cotacao`, `cotacao_curva_zero`, `taxa_curva_zero`, `pu`, `duration`, `dv01` |
 | `yd.ntnbp` | módulo | NTN-B Principal | `cotacao`, `taxa`, `pu`, `dv01` |
 | `yd.ntnc` | módulo | NTN-C | `dados`, `datas_pagamento`, `fluxos_caixa`, `cotacao`, `pu`, `taxa`, `duration`, `duration_expr`, `dv01`, `dv01_expr` |
-| `yd.ntnf` | módulo | NTN-F | `dados`, `vencimentos`, `datas_pagamento`, `fluxos_caixa`, `pu`, `taxa`, `taxas_zero`, `premio`, `premio_limpo`, `premio_limpo_expr`, `rentabilidade`, `rentabilidade_expr`, `duration`, `duration_expr`, `dv01`, `dv01_expr` |
+| `yd.ntnf` | módulo | NTN-F | `dados`, `vencimentos`, `datas_pagamento`, `fluxos_caixa`, `pu`, `taxa`, `taxas_zero`, `taxas_zero_forwards`, `premio`, `premio_limpo`, `premio_limpo_expr`, `rentabilidade`, `rentabilidade_expr`, `duration`, `duration_expr`, `dv01`, `dv01_expr` |
 | `yd.vna` | módulo | Valores nominais atualizados dos títulos públicos | `valor`, `historico`, `projetado`, `vigencia` |
 | `yd.copom` | módulo | Calendário automático do Copom | `calendario`, `proxima_reuniao` |
 | `yd.compromissadas(...)` | função | Leilões de operações compromissadas do BCB | `inicio`, `fim` |
@@ -102,6 +102,32 @@ documentação detalhada e as assinaturas públicas.
 
 ## Compatibilidade da API
 
+### Cotações em base 100 — 0.58.0
+
+As funções escalares de cálculo dos títulos também aceitam taxas percentuais
+explícitas, como `"5.75%"` ou `"5,75%"`, equivalentes a `0.0575`.
+Números continuam em formato decimal; strings sem `%` são rejeitadas.
+
+As funções `cotacao` de `yd.lft`, `yd.ntnb`, `yd.ntnc`, `yd.ntnbp` e
+`yd.ntnb1` passam a retornar base 100 com quatro casas decimais:
+`0.993651` passa a ser `99.3651`. As funções `pu` desses títulos recebem a
+cotação nessa mesma base e aplicam `VNA * cotacao / 100`.
+
+A coluna `valor_pagamento` de `fluxos_caixa` de NTN-B, NTN-C e NTN-B1 e o
+retorno de `ntnb1.cotacao_curva_zero` também passam para base 100. Esta última
+mantém a soma sem truncamento para calibrar a TIR equivalente.
+
+Para migrar, multiplique cotações e fluxos antigos armazenados por 100, remova
+multiplicações por 100 usadas apenas para exibir cotações e ajuste cálculos
+manuais de PU para dividir por 100. A composição `pu(vna, cotacao(...))`
+preserva a unidade e as regras de precisão do preço. Taxas continuam em formato
+decimal, e VNA e PU continuam em reais.
+
+As funções `yd.ltn.dv01` e `yd.ntnf.dv01` não recebem mais um PU de referência:
+calculam a redução do PU teórico para um aumento de 1 ponto-base na taxa.
+
+### Demais alterações
+
 Este resumo parte da API da `0.56.0`. Mudanças que já faziam parte dessa versão
 ou de versões anteriores estão no histórico das
 [releases do GitHub](https://github.com/crdcj/PYield/releases).
@@ -116,11 +142,14 @@ ou de versões anteriores estão no histórico das
 | `pyield.tpf.vna.calcular_vna(...)` | `yd.vna.calcular_vna(...)` |
 | `yd.ntnb.vna(data)` | `yd.vna.valor("NTN-B", data)` |
 | `yd.ntnb.vnas()` | `yd.vna.historico("NTN-B")` |
-| `vna_projetado(...)` nos módulos de títulos | `yd.vna.projetado(titulo, data, vna_base, inflacao)` |
+| `vna_projetado(...)` nos módulos de títulos | `yd.vna.projetado(titulo, data, vna_base, inflacao)`; para LFT, use `selic=` |
 | `vigencia(data)` nos módulos de títulos | `yd.vna.vigencia(titulo, data)` |
 
-Os módulos públicos de títulos ficam disponíveis na raiz, enquanto as
-implementações continuam organizadas internamente em `pyield/tpf/titulos/`.
+O namespace público segue a autonomia semântica do conceito que o usuário
+precisa conhecer, e não apenas a fonte dos dados ou sua relação temática com
+outro domínio. Por isso, conceitos como `yd.ltn`, `yd.ntnb`, `yd.vna` e `yd.rmd`
+ficam na raiz, enquanto as implementações podem continuar agrupadas
+internamente por domínio para manter o código coeso.
 Consulte as [releases](https://github.com/crdcj/PYield/releases) para o
 histórico completo.
 

{pyield-0.57.2 → pyield-0.58.1}/README.md

@@ -53,13 +53,13 @@ uv add pyield
 | `yd.di1` | módulo | Curva DI1 e interpolação | `dados`, `interpolar_taxas`, `interpolar_taxa`, `datas_disponiveis` |
 | `yd.tpf` | módulo | Títulos públicos federais | `taxas`, `taxas_historicas`, `vencimentos`, `estoque`, `leiloes`, `benchmarks`, `curva_pre`, `premios_pre`, `secundario` |
 | `yd.rmd(aba)` | função | Relatório Mensal da Dívida do Tesouro Nacional | |
-| `yd.lft` | módulo | LFT | `dados`, `vencimentos`, `cotacao`, `pu`, `taxa`, `vna`, `rentabilidade`, `rentabilidade_expr` |
+| `yd.lft` | módulo | LFT | `dados`, `vencimentos`, `cotacao`, `pu`, `taxa`, `rentabilidade`, `rentabilidade_expr` |
 | `yd.ltn` | módulo | LTN | `dados`, `vencimentos`, `pu`, `taxa`, `duration_expr`, `dv01`, `dv01_expr`, `rentabilidade`, `rentabilidade_expr`, `taxas_forward` |
 | `yd.ntnb` | módulo | NTN-B | `dados`, `vencimentos`, `datas_pagamento`, `fluxos_caixa`, `cotacao`, `pu`, `taxa`, `taxas_zero`, `duration`, `dv01`, `dv01_expr`, `implicitas`, `curva` |
 | `yd.ntnb1` | módulo | NTN-B1 (Educa+ e Renda+) | `NomeComercial`, `datas_pagamento`, `fluxos_caixa`, `cotacao`, `cotacao_curva_zero`, `taxa_curva_zero`, `pu`, `duration`, `dv01` |
 | `yd.ntnbp` | módulo | NTN-B Principal | `cotacao`, `taxa`, `pu`, `dv01` |
 | `yd.ntnc` | módulo | NTN-C | `dados`, `datas_pagamento`, `fluxos_caixa`, `cotacao`, `pu`, `taxa`, `duration`, `duration_expr`, `dv01`, `dv01_expr` |
-| `yd.ntnf` | módulo | NTN-F | `dados`, `vencimentos`, `datas_pagamento`, `fluxos_caixa`, `pu`, `taxa`, `taxas_zero`, `premio`, `premio_limpo`, `premio_limpo_expr`, `rentabilidade`, `rentabilidade_expr`, `duration`, `duration_expr`, `dv01`, `dv01_expr` |
+| `yd.ntnf` | módulo | NTN-F | `dados`, `vencimentos`, `datas_pagamento`, `fluxos_caixa`, `pu`, `taxa`, `taxas_zero`, `taxas_zero_forwards`, `premio`, `premio_limpo`, `premio_limpo_expr`, `rentabilidade`, `rentabilidade_expr`, `duration`, `duration_expr`, `dv01`, `dv01_expr` |
 | `yd.vna` | módulo | Valores nominais atualizados dos títulos públicos | `valor`, `historico`, `projetado`, `vigencia` |
 | `yd.copom` | módulo | Calendário automático do Copom | `calendario`, `proxima_reuniao` |
 | `yd.compromissadas(...)` | função | Leilões de operações compromissadas do BCB | `inicio`, `fim` |
@@ -77,6 +77,32 @@ documentação detalhada e as assinaturas públicas.
 
 ## Compatibilidade da API
 
+### Cotações em base 100 — 0.58.0
+
+As funções escalares de cálculo dos títulos também aceitam taxas percentuais
+explícitas, como `"5.75%"` ou `"5,75%"`, equivalentes a `0.0575`.
+Números continuam em formato decimal; strings sem `%` são rejeitadas.
+
+As funções `cotacao` de `yd.lft`, `yd.ntnb`, `yd.ntnc`, `yd.ntnbp` e
+`yd.ntnb1` passam a retornar base 100 com quatro casas decimais:
+`0.993651` passa a ser `99.3651`. As funções `pu` desses títulos recebem a
+cotação nessa mesma base e aplicam `VNA * cotacao / 100`.
+
+A coluna `valor_pagamento` de `fluxos_caixa` de NTN-B, NTN-C e NTN-B1 e o
+retorno de `ntnb1.cotacao_curva_zero` também passam para base 100. Esta última
+mantém a soma sem truncamento para calibrar a TIR equivalente.
+
+Para migrar, multiplique cotações e fluxos antigos armazenados por 100, remova
+multiplicações por 100 usadas apenas para exibir cotações e ajuste cálculos
+manuais de PU para dividir por 100. A composição `pu(vna, cotacao(...))`
+preserva a unidade e as regras de precisão do preço. Taxas continuam em formato
+decimal, e VNA e PU continuam em reais.
+
+As funções `yd.ltn.dv01` e `yd.ntnf.dv01` não recebem mais um PU de referência:
+calculam a redução do PU teórico para um aumento de 1 ponto-base na taxa.
+
+### Demais alterações
+
 Este resumo parte da API da `0.56.0`. Mudanças que já faziam parte dessa versão
 ou de versões anteriores estão no histórico das
 [releases do GitHub](https://github.com/crdcj/PYield/releases).
@@ -91,11 +117,14 @@ ou de versões anteriores estão no histórico das
 | `pyield.tpf.vna.calcular_vna(...)` | `yd.vna.calcular_vna(...)` |
 | `yd.ntnb.vna(data)` | `yd.vna.valor("NTN-B", data)` |
 | `yd.ntnb.vnas()` | `yd.vna.historico("NTN-B")` |
-| `vna_projetado(...)` nos módulos de títulos | `yd.vna.projetado(titulo, data, vna_base, inflacao)` |
+| `vna_projetado(...)` nos módulos de títulos | `yd.vna.projetado(titulo, data, vna_base, inflacao)`; para LFT, use `selic=` |
 | `vigencia(data)` nos módulos de títulos | `yd.vna.vigencia(titulo, data)` |
 
-Os módulos públicos de títulos ficam disponíveis na raiz, enquanto as
-implementações continuam organizadas internamente em `pyield/tpf/titulos/`.
+O namespace público segue a autonomia semântica do conceito que o usuário
+precisa conhecer, e não apenas a fonte dos dados ou sua relação temática com
+outro domínio. Por isso, conceitos como `yd.ltn`, `yd.ntnb`, `yd.vna` e `yd.rmd`
+ficam na raiz, enquanto as implementações podem continuar agrupadas
+internamente por domínio para manter o código coeso.
 Consulte as [releases](https://github.com/crdcj/PYield/releases) para o
 histórico completo.
 

{pyield-0.57.2 → pyield-0.58.1}/pyield/__init__.py

@@ -11,13 +11,12 @@ from pyield.futuro import di1
 # Ordem intencional: alguns módulos importam `di1` a partir de `pyield`
 # durante a inicialização do pacote.
 from pyield import cpm, copom, selic, tpf, vna
-from pyield.cpm import probabilidades as _cpm_probabilidades  # noqa: F401
 from pyield.bc.sgs import ptax, ptax_serie
 from pyield.compromissada import compromissadas
 from pyield.fwd import forward, forwards, forwards_expr
 from pyield.interpolador import Interpolador, interpolar
 from pyield.relogio import agora, hoje
-from pyield.tpf.rmd import rmd
+from pyield.rmd import rmd
 from pyield.tpf.titulos import lft, ltn, ntnb, ntnb1, ntnbp, ntnc, ntnf
 
 try:

{pyield-0.57.2 → pyield-0.58.1}/pyield/_internal/cache.py

@@ -15,6 +15,11 @@ def ttl_cache(ttl: int = _TTL_PADRAO, maxsize: int = _TAMANHO_MAXIMO):
     Args:
         ttl: Tempo de vida de cada entrada em segundos.
         maxsize: Número máximo de entradas no cache.
+
+    Notes:
+        O wrapper consome _atualizar=True para ignorar e renovar apenas a
+        entrada consultada. Erros são propagados, preservando a entrada
+        anterior até sua expiração.
     """
 
     def decorador(func):
@@ -22,9 +27,10 @@ def ttl_cache(ttl: int = _TTL_PADRAO, maxsize: int = _TAMANHO_MAXIMO):
 
         @wraps(func)
         def wrapper(*args, **kwargs):
+            atualizar = kwargs.pop("_atualizar", False)
             chave = (args, tuple(sorted(kwargs.items())))
             agora = time.monotonic()
-            if chave in _cache:
+            if not atualizar and chave in _cache:
                 resultado, expira_em = _cache[chave]
                 if agora < expira_em:
                     return resultado

{pyield-0.57.2 → pyield-0.58.1}/pyield/b3/boletim.py

@@ -436,10 +436,6 @@ def buscar(
         >>> # Múltiplos contratos de uma vez
         >>> df = yd.b3.boletim.buscar("26-04-2024", ["DI1", "DAP"])
 
-        >>> # Feriado ou fim de semana (retorna DataFrame vazio)
-        >>> df = yd.b3.boletim.buscar("25-12-2023", "DI1")
-        >>> df.is_empty()
-        True
     """
     if any_is_empty(data):
         return pl.DataFrame()

{pyield-0.57.2 → pyield-0.58.1}/pyield/bc/leiloes.py

@@ -93,13 +93,13 @@ def _processar_df(df: pl.DataFrame) -> pl.DataFrame:
         pl.when(pl.col("titulo") == "LTN")
         .then(
             ltn.dv01_expr(
-                "data_liquidacao", "data_vencimento", "taxa_media", "pu_medio"
+                "data_liquidacao", "data_vencimento", "taxa_media"
             )
         )
         .when(pl.col("titulo") == "NTN-F")
         .then(
             ntnf.dv01_expr(
-                "data_liquidacao", "data_vencimento", "taxa_media", "pu_medio"
+                "data_liquidacao", "data_vencimento", "taxa_media"
             )
         )
         .when(pl.col("titulo") == "NTN-B")

{pyield-0.57.2 → pyield-0.58.1}/pyield/bc/sgs.py

@@ -2,6 +2,7 @@
 
 Séries disponíveis:
     - PTAX Venda (SGS 1)
+    - SELIC Diária (SGS 11)
     - SELIC Meta (SGS 432)
     - SELIC Over (SGS 1178)
 
@@ -16,7 +17,7 @@ Exemplo de resposta JSON da API do BCB:
 
 Notas de implementação:
     - Intervalos longos são divididos automaticamente em blocos seguros.
-    - SELIC Over e Meta: valores percentuais convertidos para decimal
+        - SELIC Diária, Over e Meta: valores percentuais convertidos para decimal
       (divididos por 100) e arredondados para 10 casas decimais.
     - PTAX Venda: valor absoluto em R$ arredondado para 4 casas.
 """
@@ -54,6 +55,7 @@ class SerieSGS(Enum):
     """Enum para as séries disponíveis no SGS do Banco Central."""
 
     PTAX_VENDA = 1
+    SELIC_DIARIA = 11
     SELIC_META = 432
     SELIC_OVER = 1178
 

{pyield-0.57.2 → pyield-0.58.1}/pyield/cpm/__init__.py

@@ -350,3 +350,7 @@ def data(date: DateLike) -> pl.DataFrame:
         pl.col("preco_ajuste"),
         pl.col("dias_uteis"),
     ).sort("data_expiracao", "variacao_strike_bps")
+
+
+# Importado após as definições porque probabilidades utiliza este módulo.
+from pyield.cpm import probabilidades as probabilidades  # noqa: E402, PLC0414

pyield-0.58.1/pyield/cpm/probabilidades.py

@@ -0,0 +1,347 @@
+"""
+probabilidades — Probabilidades implícitas das reuniões do COPOM a partir dos
+preços das opções CPM.
+
+O contrato CPM é uma opção europeia cash-or-nothing. No apreçamento neutro ao
+risco, o preço de ajuste da B3 em pontos (0–100) representa a probabilidade
+implícita de cada cenário de alteração da Selic, descontada pela taxa DI até o
+vencimento (Manual de Apreçamento da B3, §3.5).
+
+Convenções de probabilidade
+---------------------------
+    prob_bruta = preco_ajuste * fator_desconto / 100
+
+            Probabilidade neutra ao risco direta segundo o Manual da B3 §3.5
+            (fórmula invertida):
+
+          p_n(K) = PR_n * exp(+n * r_n) / N
+
+      onde
+          PR_n  = preco_ajuste ("Preço de Referência" da B3, pontos 0–100)
+          N     = 100 (valor nocional fixo)
+          n     = dias_uteis / 252 (tempo em anos, convenção de dias úteis)
+          r_n   = ln(1 + taxa_di1) (taxa DI1 continuamente capitalizada até o
+                  vencimento)
+          taxa_di1 = taxa DI1 interpolada por flat-forward entre a data de
+                     referência e a data de expiração
+
+      O preco_ajuste de cpm.data() é o "Preço de Referência" oficial da B3,
+      obtido no endpoint CSV: o preço exibido no painel da B3 ("Probabilidades
+      da Taxa Selic Meta") e resultado da metodologia P1/P2/P3/P4 da B3. Pode
+      ser nulo para datas com mais de aproximadamente um mês, quando o
+      endpoint CSV não está disponível.
+
+      Pode não somar 1,0 por reunião devido ao spread entre oferta e demanda ou
+      ao apreçamento P1/P2 da B3. Quando dias_uteis == 0 (o próprio dia da
+      reunião), fator_desconto == 1,0 exatamente e prob_bruta se reduz a
+      preco_ajuste / 100.
+
+  prob = prob_bruta / soma(prob_bruta) no grupo de data_expiracao
+      Normalizada para que cada reunião some exatamente 1,0. Este é o ajuste de
+      apreçamento P3 da B3. Use esta coluna para análise de cenários e gráficos.
+
+  prob_acumulada = soma acumulada de prob, ordenada por
+      variacao_strike_bps em ordem crescente.
+
+Observações sobre preco_ajuste nulo
+-----------------------------------
+Às vezes os contratos CPM são listados sem preço de ajuste (não há apreçamento
+oficial da B3 para aquele strike na data, ou o endpoint CSV não está disponível
+para datas antigas). Strikes com preco_ajuste nulo são excluídos da saída de
+probabilidades porque:
+
+  1. Sua contribuição para a distribuição normalizada é indefinida.
+  2. ``group_by().agg(sum())`` do Polars retorna 0,0 (e não nulo) para grupos
+     totalmente nulos, o que quebraria a invariável ``prob.sum() == 1.0`` por
+     reunião.
+
+Como consequência, uma reunião em que TODOS os strikes listados tenham preços
+nulos (por exemplo, CPMH25 no dia da reunião do COPOM de janeiro de 2025) não
+aparecerá na saída. O ranking_reuniao é, portanto, atribuído somente entre as
+reuniões com preços e sempre forma uma sequência consecutiva [1, 2, ..., n].
+
+Observações sobre o fallback do DI1
+-----------------------------------
+Se os dados do DI1 não estiverem disponíveis para a data de referência (erro de
+rede, feriado etc.), taxa_di1 assume 0,0 e fator_desconto assume 1,0. Assim,
+prob_bruta se reduz a preco_ajuste / 100, equivalente à fórmula antiga
+(incorreta). Essa degradação é registrada como aviso, mas nunca gera uma
+exceção.
+"""
+
+import logging
+
+import polars as pl
+
+from pyield import cpm
+from pyield._internal.converters import converter_datas
+from pyield._internal.types import DateLike
+from pyield.futuro import di1
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Schema
+# ---------------------------------------------------------------------------
+
+
+def _empty_schema() -> pl.DataFrame:
+    return pl.DataFrame(
+        schema={
+            "data_referencia": pl.Date,
+            "data_fim_reuniao": pl.Date,
+            "data_expiracao": pl.Date,
+            "ranking_reuniao": pl.Int32,
+            "variacao_strike_bps": pl.Int32,
+            "dias_uteis": pl.Int32,
+            "preco_ajuste": pl.Float64,
+            "taxa_di1": pl.Float64,
+            "fator_desconto": pl.Float64,
+            "prob_bruta": pl.Float64,
+            "prob": pl.Float64,
+            "prob_acumulada": pl.Float64,
+        }
+    )
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _add_meeting_rank(df: pl.DataFrame) -> pl.DataFrame:
+    """
+    Adiciona ranking_reuniao: 1 = data_expiracao mais próxima, 2 = seguinte, etc.
+    Calculado como dense rank sobre data_expiracao.
+    """
+    return df.with_columns(
+        ranking_reuniao=pl.col("data_expiracao").rank("dense").cast(pl.Int32)
+    )
+
+
+def _add_discount_factors(df: pl.DataFrame) -> pl.DataFrame:
+    """
+    Adiciona as colunas de taxa DI1 e fator de desconto.
+
+    A função usa ``di1.interpolar_taxas()`` de forma vetorizada para buscar
+    todas as taxas DI1 em uma única chamada, com uma busca e um interpolador por
+    data_referencia única. Em seguida, calcula os fatores de desconto com
+    expressões Polars.
+
+    Método de interpolação
+    ----------------------
+    ``di1.interpolar_taxas()`` implementa o Manual da B3 §1.4.2 — Flat Forward
+    252, que interpola de forma log-linear os fatores acumulados do DI1 (valores
+    de PU):
+
+        fa_j = (1 + r_j)^(du_j/252)          # fator acumulado no vértice j
+        fa_k = (1 + r_k)^(du_k/252)          # fator acumulado no vértice k
+        ft   = (du - du_j) / (du_k - du_j)   # fração do intervalo
+        r    = (fa_j * (fa_k / fa_j)^ft)^(252/du) - 1
+
+    Isso equivale à interpolação log-linear dos preços de ajuste do DI1
+    (PU = 100_000 / (1+r)^(du/252)), daí a expressão "interpolação exponencial
+    dos preços de ajuste do DI1" no Manual de Apreçamento do CPM §3.5.
+
+    Não é o método §1.4.1 (Exponencial 252), que interpola diretamente as taxas:
+        r = (1 + r_j) * ((1 + r_k)/(1 + r_j))^ft - 1
+    Os dois métodos divergem alguns pontos-base em vencimentos intermediários
+    (por exemplo, aproximadamente 4,6 pontos-base em du=17 para taxas na faixa
+    da Selic em 2026).
+
+    Na ausência de dados do DI1, usa taxa_di1=0,0 e fator_desconto=1,0.
+    """
+    pairs = (
+        df.select("data_referencia", "data_expiracao", "dias_uteis")
+        .unique(subset=["data_referencia", "data_expiracao"])
+        .sort("data_referencia", "data_expiracao")
+    )
+
+    # Chamada vetorizada: um fetch por data_referencia única
+    try:
+        rates = di1.interpolar_taxas(
+            datas_referencia=pairs["data_referencia"],
+            datas_vencimento=pairs["data_expiracao"],
+            extrapolar=True,
+        )
+    except Exception:
+        logger.warning("Falha na busca DI1; usando fallback taxa=0.0.")
+        rates = pl.Series("taxa_interpolada", [None] * len(pairs), dtype=pl.Float64)
+
+    discount_df = (
+        pairs.with_columns(
+            taxa_di1=rates.fill_null(0.0).fill_nan(0.0),
+        )
+        .with_columns(
+            fator_desconto=(
+                (pl.col("dias_uteis") / 252 * (1 + pl.col("taxa_di1")).log()).exp()
+            ),
+        )
+        .select("data_referencia", "data_expiracao", "taxa_di1", "fator_desconto")
+    )
+
+    return df.join(discount_df, on=["data_referencia", "data_expiracao"], how="left")
+
+
+def _add_probabilities(df: pl.DataFrame) -> pl.DataFrame:
+    """
+    Adiciona as colunas prob_bruta, prob e prob_acumulada conforme o Manual da
+    B3 §3.5.
+
+    Assume que o DataFrame já foi filtrado para um tipo de opção e para linhas
+    com preco_ajuste não nulo, e que ``_add_discount_factors`` já foi chamada
+    para adicionar taxa_di1 e fator_desconto.
+
+    prob_bruta = preco_ajuste * fator_desconto / 100
+    prob = prob_bruta / soma(prob_bruta) no grupo de data_expiracao
+    prob_acumulada = soma acumulada de prob, ordenada por
+        variacao_strike_bps em ordem crescente.
+    """
+    df = _add_discount_factors(df)
+
+    return (
+        df.sort("data_expiracao", "variacao_strike_bps")
+        .with_columns(
+            prob_bruta=(pl.col("preco_ajuste") * pl.col("fator_desconto") / 100),
+        )
+        .with_columns(
+            prob=(
+                pl.col("prob_bruta") / pl.col("prob_bruta").sum().over("data_expiracao")
+            ),
+        )
+        .with_columns(prob_acumulada=pl.col("prob").cum_sum().over("data_expiracao"))
+    )
+
+
+# ---------------------------------------------------------------------------
+# API pública
+# ---------------------------------------------------------------------------
+
+
+def all_meetings(
+    date: DateLike,
+    option_type: str = "call",
+) -> pl.DataFrame:
+    """
+    Calcula as probabilidades implícitas de todas as reuniões do COPOM com
+    contratos CPM negociados na data informada em `date`.
+
+    Somente strikes com `preco_ajuste` não nulo são incluídos. Reuniões em que
+    todos os strikes listados têm preço nulo são excluídas integralmente (ver
+    as observações no nível do módulo).
+
+    Args:
+        date: Data de referência da consulta; aceita os formatos de `DateLike`.
+        option_type: Tipo de opção, `"call"` ou `"put"`. O padrão é `"call"`,
+            que na prática é o lado mais líquido.
+
+    Returns:
+        `polars.DataFrame` ordenado por `ranking_reuniao` e
+        `variacao_strike_bps`. Em caso de ausência de dados, retorna um
+        DataFrame vazio com o schema correto.
+
+    Output Columns:
+        - data_referencia (Date): Data de negociação.
+        - data_fim_reuniao (Date): Último dia da reunião do COPOM.
+        - data_expiracao (Date): Data de expiração do contrato CPM.
+        - ranking_reuniao (Int32): 1 para a reunião mais próxima com preços.
+        - variacao_strike_bps (Int32): Variação do strike em pontos-base,
+            crescente dentro de cada reunião.
+        - dias_uteis (Int32): Dias úteis até a expiração.
+        - preco_ajuste (Float64): Preço de Referência da B3 em pontos (0–100).
+        - taxa_di1 (Float64): Taxa DI1 interpolada até a expiração.
+        - fator_desconto (Float64): Fator aplicado na inversão da fórmula da B3,
+            calculado como `exp(dias_uteis / 252 * ln(1 + taxa_di1))`.
+        - prob_bruta (Float64): Probabilidade antes da normalização,
+            calculada como `preco_ajuste * fator_desconto / 100`.
+        - prob (Float64): Probabilidade normalizada, calculada como
+            `prob_bruta / soma(prob_bruta)` por `data_expiracao`, com soma
+            1,0 por reunião.
+        - prob_acumulada (Float64): Probabilidade acumulada em ordem
+            crescente de strike.
+
+    Examples:
+        >>> import pyield as yd
+        >>> import polars as pl
+        >>> df = yd.cpm.probabilidades.all_meetings("29-01-2025")  # doctest: +SKIP
+        >>> df.is_empty() or df["ranking_reuniao"].min() == 1  # doctest: +SKIP
+        True
+        >>> sums = df.group_by("data_expiracao").agg(
+        ...     pl.col("prob").sum()
+        ... )  # doctest: +SKIP
+        >>> df.is_empty() or (sums["prob"] - 1.0).abs().max() < 1e-9  # doctest: +SKIP
+        True
+    """
+    raw = cpm.data(date)
+    if raw.is_empty():
+        return _empty_schema()
+
+    df = (
+        raw.filter(pl.col("tipo_opcao") == option_type)
+        # Excluir strikes sem preço de ajuste — ver docstring do módulo.
+        .filter(pl.col("preco_ajuste").is_not_null())
+        .pipe(_add_meeting_rank)
+        .pipe(_add_probabilities)
+        .select(
+            "data_referencia",
+            "data_fim_reuniao",
+            "data_expiracao",
+            "ranking_reuniao",
+            "variacao_strike_bps",
+            "dias_uteis",
+            "preco_ajuste",
+            "taxa_di1",
+            "fator_desconto",
+            "prob_bruta",
+            "prob",
+            "prob_acumulada",
+        )
+        .sort("ranking_reuniao", "variacao_strike_bps")
+    )
+
+    return df if not df.is_empty() else _empty_schema()
+
+
+def meeting(
+    date: DateLike,
+    expiration: DateLike | None = None,
+    option_type: str = "call",
+) -> pl.DataFrame:
+    """
+    Calcula as probabilidades implícitas de uma única reunião do COPOM.
+
+    Args:
+        date: Data de referência da consulta.
+        expiration: Data de expiração do contrato CPM da reunião desejada, ou
+            `None` para selecionar a reunião mais próxima com preços. A expiração
+            corresponde ao primeiro dia útil após o término da reunião.
+        option_type: Tipo de opção, `"call"` ou `"put"`. O padrão é `"call"`.
+
+    Returns:
+        `polars.DataFrame` com o mesmo schema de `all_meetings()`, filtrado
+        para uma única reunião. `ranking_reuniao` é sempre 1 nesta saída,
+        relativo à reunião selecionada, e não ao conjunto de reuniões.
+
+    Examples:
+        >>> import pyield as yd
+        >>> df = yd.cpm.probabilidades.meeting("29-01-2025")  # doctest: +SKIP
+        >>> df.is_empty() or abs(df["prob"].sum() - 1.0) < 1e-9  # doctest: +SKIP
+        True
+        >>> df.is_empty() or df["prob_acumulada"].tail(
+        ...     1
+        ... ).item() == 1.0  # doctest: +SKIP
+        True
+    """
+    df = all_meetings(date, option_type=option_type)
+    if df.is_empty():
+        return _empty_schema()
+
+    if expiration is None:
+        target_expiry = df.filter(pl.col("ranking_reuniao") == 1)["data_expiracao"][0]
+    else:
+        target_expiry = converter_datas(expiration)
+
+    return df.filter(pl.col("data_expiracao") == target_expiry).with_columns(
+        ranking_reuniao=pl.lit(1, dtype=pl.Int32)
+    )