mcp-bcrp 0.1.2__tar.gz → 0.1.3__tar.gz

{mcp_bcrp-0.1.2 → mcp_bcrp-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-bcrp
-Version: 0.1.2
+Version: 0.1.3
 Summary: MCP Server for Banco Central de Reserva del Perú (BCRP) Statistical API
 Author-email: Maykol Medrano <mmedrano2@uc.cl>
 License: MIT
@@ -121,8 +121,8 @@ pip install -e .
 ### With Optional Dependencies
 
 ```bash
-pip install mcp-bcrp[charts]  # Include matplotlib for chart generation
-pip install mcp-bcrp[dev]     # Include development dependencies
+pip install "mcp-bcrp[charts]"  # Include matplotlib for chart generation
+pip install "mcp-bcrp[dev]"     # Include development dependencies
 ```
 
 ---

{mcp_bcrp-0.1.2 → mcp_bcrp-0.1.3}/README.md

@@ -85,8 +85,8 @@ pip install -e .
 ### With Optional Dependencies
 
 ```bash
-pip install mcp-bcrp[charts]  # Include matplotlib for chart generation
-pip install mcp-bcrp[dev]     # Include development dependencies
+pip install "mcp-bcrp[charts]"  # Include matplotlib for chart generation
+pip install "mcp-bcrp[dev]"     # Include development dependencies
 ```
 
 ---

mcp_bcrp-0.1.3/examples/Guia_Usuario_BCRP.ipynb

@@ -0,0 +1,191 @@
+{
+    "cells": [
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": [
+                "# 📊 Guía de Usuario: mcp-bcrp (v0.1.3)\n",
+                "\n",
+                "Bienvenido a la guía oficial de **mcp-bcrp**, la librería y servidor MCP para acceder a las estadísticas del **Banco Central de Reserva del Perú (BCRP)**.\n",
+                "\n",
+                "[![GitHub](https://img.shields.io/badge/GitHub-Repository-blue?logo=github)](https://github.com/MaykolMedrano/mcp_bcrp)\n",
+                "[![PyPI](https://img.shields.io/pypi/v/mcp-bcrp.svg)](https://pypi.org/project/mcp-bcrp/)\n",
+                "\n",
+                "Esta versión incluye un **Buscador Interactivo** y **Tablas Inteligentes** que resuelven nombres automáticamente."
+            ]
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": [
+                "## 1. Instalación\n",
+                "\n",
+                "Instalamos la librería usando el comando mágico `%pip` (el más recomendado en notebooks)."
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": [
+                "%pip install \"mcp-bcrp[charts]\" -U\n",
+                "\n",
+                "# NOTA: Si es la primera vez que instalas, reinicia el entorno (Runtime -> Restart session)."
+            ]
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": [
+                "## 2. Configuración y Metadatos\n",
+                "\n",
+                "Cargamos los metadatos para habilitar la búsqueda inteligente."
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": [
+                "from mcp_bcrp.client import AsyncBCRPClient, BCRPMetadata\n",
+                "import pandas as pd\n",
+                "\n",
+                "metadata = BCRPMetadata()\n",
+                "await metadata.load()"
+            ]
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": [
+                "## 3. Buscador Inteligente e Interactivo\n",
+                "\n",
+                "A diferencia de otros buscadores, `mcp-bcrp` entiende sinónimos comunes (ej: \"tc\" -> \"tipo de cambio\") y si hay dudas, te ofrece opciones."
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": [
+                "# Ejemplo 1: Búsqueda con sinónimos y lenguaje natural\n",
+                "query = \"precio internacional cobre\"\n",
+                "resultado = metadata.solve(query)\n",
+                "\n",
+                "if \"candidates\" in resultado:\n",
+                "    print(\"🔍 Encontré varias opciones, ¿cuál necesitas?\")\n",
+                "    display(pd.DataFrame(resultado[\"candidates\"]))\n",
+                "else:\n",
+                "    print(f\"📌 Única coincidencia encontrada: {resultado.get('name')}\")\n",
+                "    print(f\"Código: {resultado.get('codigo_serie')}\")"
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": [
+                "# Ejemplo 2: Búsqueda de Tipo de Cambio (TC)\n",
+                "query_tc = \"tc venta\"\n",
+                "resultado_tc = metadata.solve(query_tc)\n",
+                "\n",
+                "if \"candidates\" in resultado_tc:\n",
+                "    print(\"🔍 Opciones para Tipo de Cambio:\")\n",
+                "    display(pd.DataFrame(resultado_tc[\"candidates\"]))\n",
+                "else:    \n",
+                "    print(f\"✅ Resultado: {resultado_tc.get('name')}\")"
+            ]
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": [
+                "## 4. Tablas Inteligentes (Multi-indicador)\n",
+                "\n",
+                "Puedes pedir varios códigos y la librería resolverá los nombres por ti automáticamente."
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": [
+                "from mcp_bcrp.server import get_table\n",
+                "import json\n",
+                "\n",
+                "# Pedimos Inflación y Tipo de Cambio interbancario de una vez\n",
+                "series = [\"PN01271PM\", \"PD04637PD\"]\n",
+                "\n",
+                "tabla_raw = await get_table(series_codes=series, period=\"2024-01/2024-12\")\n",
+                "df_tabla = pd.DataFrame(json.loads(tabla_raw))\n",
+                "\n",
+                "print(\"Tabla con nombres automáticos:\")\n",
+                "display(df_tabla.head())"
+            ]
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": [
+                "## 5. Visualización Avanzada\n",
+                "\n",
+                "Generación de gráficos con leyendas automáticas."
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": [
+                "from mcp_bcrp.server import plot_chart\n",
+                "from IPython.display import Image\n",
+                "\n",
+                "res = await plot_chart(\n",
+                "    series_codes=[\"PD38048AM\", \"PD38049AM\"],\n",
+                "    period=\"2022-01/2024-12\",\n",
+                "    title=\"Expectativas de Crecimiento PBI\"\n",
+                ")\n",
+                "\n",
+                "info = json.loads(res)\n",
+                "Image(info['chart_path'])"
+            ]
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": [
+                "---\n",
+                "### Recursos\n",
+                "- **Issue Tracker**: [GitHub Issues](https://github.com/MaykolMedrano/mcp_bcrp/issues)\n",
+                "- **Documentación SDK**: [PyPI mcp-bcrp](https://pypi.org/project/mcp-bcrp/)"
+            ]
+        }
+    ],
+    "metadata": {
+        "kernelspec": {
+            "display_name": "Python 3",
+            "language": "python",
+            "name": "python3"
+        },
+        "language_info": {
+            "codemirror_mode": {
+                "name": "ipython",
+                "version": 3
+            },
+            "file_extension": ".py",
+            "mimetype": "text/x-python",
+            "name": "python",
+            "nbconvert_exporter": "python",
+            "pygments_lexer": "ipython3",
+            "version": "3.11.1"
+        }
+    },
+    "nbformat": 4,
+    "nbformat_minor": 5
+}

{mcp_bcrp-0.1.2 → mcp_bcrp-0.1.3}/mcp_bcrp/__init__.py

@@ -8,7 +8,7 @@ Use as library:
     from mcp_bcrp.client import AsyncBCRPClient, BCRPMetadata
 """
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 __author__ = "Maykol Medrano"
 
 from mcp_bcrp.client import AsyncBCRPClient, BCRPMetadata

{mcp_bcrp-0.1.2 → mcp_bcrp-0.1.3}/mcp_bcrp/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.1.2'
-__version_tuple__ = version_tuple = (0, 1, 2)
+__version__ = version = '0.1.3'
+__version_tuple__ = version_tuple = (0, 1, 3)
 
-__commit_id__ = commit_id = 'g2f2c0f637'
+__commit_id__ = commit_id = 'g1c39c6e85'

{mcp_bcrp-0.1.2 → mcp_bcrp-0.1.3}/mcp_bcrp/client.py

@@ -154,6 +154,27 @@ class BCRPMetadata:
             mask &= kw_mask
         return self.df[mask].head(limit)
 
+    def get_series_names(self, codes: List[str]) -> List[str]:
+        """
+        Retrieve original names for a list of series codes.
+        
+        Args:
+            codes: List of BCRP series codes.
+            
+        Returns:
+            List of names corresponding to the codes. 
+            Uses the code itself if name is not found.
+        """
+        if self.df.empty:
+            return codes
+            
+        # Standardize columns to search
+        code_col = "Código de serie" if "Código de serie" in self.df.columns else "Codigo de serie"
+        name_col = "Nombre de serie"
+        
+        mapping = dict(zip(self.df[code_col], self.df[name_col]))
+        return [mapping.get(code, code) for code in codes]
+
 class AsyncBCRPClient:
     """
     Async client for BCRP (Banco Central de Reserva del Perú) Statistical API.

mcp_bcrp-0.1.3/mcp_bcrp/search_engine.py

@@ -0,0 +1,229 @@
+"""
+Deterministic Search Engine for BCRP Series.
+
+Pipeline:
+1. Canonical Normalization (lowercase, remove accents, synonyms)
+2. Attribute Extraction (currency, horizon, component, side)
+3. Hard Filters
+4. Fuzzy Scoring with RapidFuzz (Token Set Ratio)
+5. Interactive Candidate Resolution
+"""
+
+import pandas as pd
+import logging
+import unicodedata
+import re
+from typing import Dict, Any, List
+
+try:
+    from rapidfuzz import fuzz
+except ImportError:
+    fuzz = None
+
+logger = logging.getLogger("mcp_bcrp")
+
+
+class SearchEngine:
+    """
+    Interactive Search Engine for BCRP Series.
+    
+    Implements a pipeline for robust series resolution:
+    1. Canonical Normalization with Synonym Support
+    2. Attribute Filtering (Currency, Side)
+    3. Fuzzy Set Scoring
+    4. Multi-candidate Result Generation
+    """
+    
+    STOPWORDS = {'de', 'del', 'el', 'la', 'los', 'las', 'y', 'en', 'al', 'con', 'por', 'precio', 'valor', 'indicador'}
+    
+    # Synonym map for common abbreviations
+    SYNONYMS = {
+        "tc": "tipo cambio",
+        "t.c.": "tipo cambio",
+        "pbi": "producto bruto interno",
+        "internacional": "lme londres Chicago nymex",
+    }
+
+    def __init__(self, metadata_df: pd.DataFrame):
+        """
+        Initialize search engine with BCRP metadata.
+        
+        Args:
+            metadata_df: DataFrame with BCRP series metadata.
+        """
+        self.df = metadata_df
+        self._preprocess_metadata()
+
+    def _normalize(self, text: str) -> str:
+        """
+        Canonical normalization of text.
+        
+        Applies: lowercase, accent removal, punctuation removal,
+        synonym expansion, stopword filtering.
+        """
+        if not isinstance(text, str):
+            return ""
+        
+        text = text.lower()
+        # Remove accents
+        text = unicodedata.normalize('NFKD', text).encode('ascii', 'ignore').decode('utf-8')
+        # Replace punctuation
+        text = re.sub(r'[^\w\s]', ' ', text)
+        
+        # Apply synonyms (simple replacement)
+        for syn, target in self.SYNONYMS.items():
+            if syn in text.split():
+                text = text.replace(syn, target)
+        
+        tokens = text.split()
+        clean_tokens = [t for t in tokens if t not in self.STOPWORDS]
+        
+        return " ".join(clean_tokens)
+
+    def _extract_attributes(self, text_norm: str) -> Dict[str, Any]:
+        """Extract structured attributes to help disambiguate."""
+        attrs = {
+            "currency": None,
+            "side": None,  # compra / venta
+            "horizon": None,
+            "component": None
+        }
+        
+        tokens = set(text_norm.split())
+        
+        # Currency
+        if any(t in tokens for t in ['us', 'usd', 'dolares']):
+            attrs['currency'] = 'usd'
+        elif any(t in tokens for t in ['s', 'pen', 'soles']):
+            attrs['currency'] = 'pen'
+            
+        # Side (Critical for FX)
+        if "compra" in tokens:
+            attrs['side'] = 'compra'
+        elif "venta" in tokens:
+            attrs['side'] = 'venta'
+            
+        # Horizon
+        if "corto" in tokens:
+            attrs['horizon'] = 'corto'
+        elif "largo" in tokens:
+            attrs['horizon'] = 'largo'
+            
+        return attrs
+
+    def _preprocess_metadata(self):
+        """Pre-calculate normalized search corpus."""
+        if self.df.empty:
+            self.search_corpus = []
+            return
+
+        processed = []
+        for idx, row in self.df.iterrows():
+            raw_name = str(row.get('Nombre de serie', ''))
+            name_norm = self._normalize(raw_name)
+            attrs = self._extract_attributes(name_norm)
+            
+            # Use original code column names if possible
+            code = row.get("Código de serie") or row.get("Codigo de serie")
+            
+            item = {
+                "idx": idx,
+                "codigo_serie": code,
+                "name_original": raw_name,
+                "name_norm": name_norm,
+                "tokens": set(name_norm.split()),
+                "currency": attrs['currency'],
+                "side": attrs['side'],
+                "horizon": attrs['horizon']
+            }
+            processed.append(item)
+            
+        self.search_corpus = processed
+
+    def solve(self, query: str) -> Dict[str, Any]:
+        """
+        Resolve query with interactive candidate logic.
+        """
+        if not self.search_corpus:
+            return {"error": "no_match", "reason": "empty_corpus"}
+
+        q_norm = self._normalize(query)
+        q_attrs = self._extract_attributes(q_norm)
+        q_tokens = set(q_norm.split())
+        
+        if not q_tokens:
+            return {"error": "no_match", "reason": "empty_query"}
+
+        # Scoring
+        scored = []
+        for c in self.search_corpus:
+            if not fuzz:
+                # Basic token overlap fallback
+                intersection = len(q_tokens & c['tokens'])
+                score = (intersection / len(q_tokens)) * 100 if q_tokens else 0
+            else:
+                # Token Set Ratio is perfect for finding "query" inside "long technical title"
+                score = fuzz.token_set_ratio(q_norm, c['name_norm'])
+            
+            # Boost if specific side (compra/venta) matches
+            if q_attrs['side'] and c['side'] == q_attrs['side']:
+                score += 5
+            elif q_attrs['side'] and c['side'] and c['side'] != q_attrs['side']:
+                score -= 10
+            
+            if score >= 65:
+                scored.append({
+                    "codigo_serie": c['codigo_serie'],
+                    "name": c['name_original'],
+                    "score": score
+                })
+
+        scored.sort(key=lambda x: x['score'], reverse=True)
+        
+        if not scored:
+            return {"error": "no_match", "reason": "low_confidence"}
+
+        # Logic for result type
+        top_score = scored[0]['score']
+        
+        # 1. Check for ties or very close matches at the top
+        # If multiple series have top_score, or are very close (within 2 pts), return candidates.
+        high_tier = [s for s in scored if s['score'] >= (top_score - 2)]
+        
+        if len(high_tier) > 1 and top_score < 100:
+             # Ambiguity if multiple high matches, unless one is perfect 100 and there are no other 100s
+             pass # fall through to candidates logic
+        elif len(high_tier) == 1 and top_score >= 85:
+            # Single clear winner with good score
+            return {
+                "codigo_serie": high_tier[0]['codigo_serie'],
+                "confidence": round(high_tier[0]['score'] / 100.0, 2),
+                "name": high_tier[0]['name']
+            }
+        
+        # If top_score is 100, but there are multiple 100s, it's ambiguous
+        top_tier_100 = [s for s in scored if s['score'] == 100]
+        if len(top_tier_100) == 1:
+             return {
+                "codigo_serie": top_tier_100[0]['codigo_serie'],
+                "confidence": 1.0,
+                "name": top_tier_100[0]['name']
+            }
+
+        # 2. Interactive Candidates
+        # Return top 5 matches if confidence is mixed or tied
+        candidates = []
+        seen_codes = set()
+        for s in scored[:5]:
+            if s['codigo_serie'] not in seen_codes:
+                candidates.append({
+                    "codigo": s['codigo_serie'],
+                    "nombre": s['name']
+                })
+                seen_codes.add(s['codigo_serie'])
+        
+        return {
+            "error": "ambiguedad",
+            "reason": "multiple_candidates",
+            "candidates": candidates
+        }

{mcp_bcrp-0.1.2 → mcp_bcrp-0.1.3}/mcp_bcrp/server.py

@@ -153,29 +153,17 @@ async def get_table(
         if df.empty:
             return "No data found."
             
-        # 2. Process Data (Calculate Variation)
-        # Assuming Data has 'time' and series columns
-        # We need to emulate 'variation=1' (Monthly % change usually or Year-over-Year?)
-        # BCRP 'variation=1' usually means % change from previous period? 
-        # Or is it Index? usebcrp 'variation=1' implies monthly variation.
-        
-        # Ensure time is datetime
-        # BCRP returns 'Mmm.YY' or similar sometimes. helper parsing might be needed.
-        # But for now, let's just return the raw data properly formatted, 
-        # Maybe adding a simple pct_change if it's numeric.
-        
-        # For simplicity and reliability in this refactor, we will return the raw values 
-        # but structured neatly. Re-implementing full 'table' logic from usebcrp might be overkill
-        # if the user just wants the data.
-        
-        # However, to be helpful, let's try to set names if provided
-        if names:
-            # Map codes to names
-            # columns are 'time' + codes.
-            mapping = {code: name for code, name in zip(series_codes, names)}
-            df.rename(columns=mapping, inplace=True)
+        # 2. Resolve Names if not provided
+        if not names:
+            await metadata_client.load()
+            names = metadata_client.get_series_names(series_codes)
             
-        return df.to_json(orient='records', date_format='iso')
+        # 3. Rename columns
+        mapping = {code: name for code, name in zip(series_codes, names)}
+        df.rename(columns=mapping, inplace=True)
+            
+        return df.to_json(orient='records', date_format='iso', indent=2)
+        
 
     except Exception as e:
         return f"Table generation failed: {str(e)}"
@@ -234,12 +222,18 @@ async def plot_chart(
             df['time'] = df['time'].apply(parse_spanish_date)
             df = df.set_index('time')
         
-        # 4. Plot each series
+        # 4. Resolve Names if not provided
+        if not names:
+            await metadata_client.load()
+            names = metadata_client.get_series_names(series_codes)
+
+        # 5. Plot each series
         colors = ['#1a5fb4', '#e01b24', '#33d17a', '#ff7800', '#9141ac']
         for idx, code in enumerate(series_codes):
-            if code in df.columns:
-                series = df[code].dropna()
-                label = names[idx] if names and idx < len(names) else code
+            col_name = code if code in df.columns else (names[idx] if names and names[idx] in df.columns else None)
+            if col_name:
+                series = df[col_name].dropna()
+                label = names[idx] if names and idx < len(names) else col_name
                 color = colors[idx % len(colors)]
                 ax.plot(series.index, series.values, linewidth=2.5, 
                        label=label, color=color)

{mcp_bcrp-0.1.2 → mcp_bcrp-0.1.3}/mcp_bcrp.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-bcrp
-Version: 0.1.2
+Version: 0.1.3
 Summary: MCP Server for Banco Central de Reserva del Perú (BCRP) Statistical API
 Author-email: Maykol Medrano <mmedrano2@uc.cl>
 License: MIT
@@ -121,8 +121,8 @@ pip install -e .
 ### With Optional Dependencies
 
 ```bash
-pip install mcp-bcrp[charts]  # Include matplotlib for chart generation
-pip install mcp-bcrp[dev]     # Include development dependencies
+pip install "mcp-bcrp[charts]"  # Include matplotlib for chart generation
+pip install "mcp-bcrp[dev]"     # Include development dependencies
 ```
 
 ---

mcp_bcrp-0.1.2/examples/Guia_Usuario_BCRP.ipynb

@@ -1,207 +0,0 @@
-{
-    "cells": [
-        {
-            "cell_type": "markdown",
-            "metadata": {},
-            "source": [
-                "# 📊 Guía de Usuario: mcp-bcrp\n",
-                "\n",
-                "Bienvenido a la guía oficial de **mcp-bcrp**, la librería y servidor MCP para acceder a las estadísticas del **Banco Central de Reserva del Perú (BCRP)** de manera profesional y eficiente.\n",
-                "\n",
-                "[![GitHub](https://img.shields.io/badge/GitHub-Repository-blue?logo=github)](https://github.com/MaykolMedrano/mcp_bcrp)\n",
-                "[![PyPI](https://img.shields.io/pypi/v/mcp-bcrp.svg)](https://pypi.org/project/mcp-bcrp/)\n",
-                "\n",
-                "Esta guía te llevará desde la instalación básica hasta la generación de gráficos avanzados y análisis de datos."
-            ]
-        },
-        {
-            "cell_type": "markdown",
-            "metadata": {},
-            "source": [
-                "## 1. Instalación\n",
-                "\n",
-                "Primero, instalamos la librería desde PyPI. Recomendamos incluir `[charts]` para poder generar visualizaciones."
-            ]
-        },
-        {
-            "cell_type": "code",
-            "execution_count": null,
-            "metadata": {},
-            "outputs": [],
-            "source": [
-                "!pip install mcp-bcrp[charts] -U"
-            ]
-        },
-        {
-            "cell_type": "markdown",
-            "metadata": {},
-            "source": [
-                "## 2. Configuración y Metadatos\n",
-                "\n",
-                "La librería utiliza un motor de búsqueda determinista que requiere un catálogo de metadatos (~17MB). La primera vez que lo uses, se descargará automáticamente y se guardará en tu cache local."
-            ]
-        },
-        {
-            "cell_type": "code",
-            "execution_count": null,
-            "metadata": {},
-            "outputs": [],
-            "source": [
-                "import asyncio\n",
-                "from mcp_bcrp.client import AsyncBCRPClient, BCRPMetadata\n",
-                "import pandas as pd\n",
-                "\n",
-                "# Inicializamos el cliente de metadatos\n",
-                "metadata = BCRPMetadata()\n",
-                "\n",
-                "# Cargamos los metadatos (descarga automática si no existe)\n",
-                "await metadata.load()\n",
-                "\n",
-                "print(f\"Metadatos cargados: {len(metadata.df)} series disponibles.\")"
-            ]
-        },
-        {
-            "cell_type": "markdown",
-            "metadata": {},
-            "source": [
-                "## 3. Búsqueda de Indicadores\n",
-                "\n",
-                "El motor de búsqueda es **determinista**. Puede encontrar series específicas basándose en atributos como moneda, horizonte y tipo de componente."
-            ]
-        },
-        {
-            "cell_type": "code",
-            "execution_count": null,
-            "metadata": {},
-            "outputs": [],
-            "source": [
-                "# Ejemplo: Buscar la tasa de interés de política monetaria\n",
-                "query = \"tasa interes politica monetaria\"\n",
-                "resultado = metadata.solve(query)\n",
-                "\n",
-                "print(\"Resultado de búsqueda:\")\n",
-                "print(f\"Código: {resultado['codigo_serie']}\")\n",
-                "print(f\"Nombre: {resultado['name_original']}\")\n",
-                "print(f\"Confianza: {resultado['confidence']}\")"
-            ]
-        },
-        {
-            "cell_type": "markdown",
-            "metadata": {},
-            "source": [
-                "## 4. Obtención de Datos (Series Temporales)\n",
-                "\n",
-                "Usamos `AsyncBCRPClient` para descargar los datos. El cliente detecta automáticamente la frecuencia (diaria, mensual, trimestral, anual)."
-            ]
-        },
-        {
-            "cell_type": "code",
-            "execution_count": null,
-            "metadata": {},
-            "outputs": [],
-            "source": [
-                "client = AsyncBCRPClient()\n",
-                "\n",
-                "# Descargamos datos de Inflación y Tipo de Cambio\n",
-                "series_a_pedir = [\"PN01271PM\", \"PD04637PD\"] # IPC Variación % y T.C. Venta\n",
-                "\n",
-                "df = await client.get_series(\n",
-                "    codes=series_a_pedir,\n",
-                "    start_date=\"2023-01-01\",\n",
-                "    end_date=\"2024-12-31\"\n",
-                ")\n",
-                "\n",
-                "print(\"Primeras filas de los datos descargados:\")\n",
-                "print(df.head())"
-            ]
-        },
-        {
-            "cell_type": "markdown",
-            "metadata": {},
-            "source": [
-                "## 5. Visualización Profesional\n",
-                "\n",
-                "La librería incluye herramientas para generar gráficos listos para reportes, manejando automáticamente el formato de fechas del BCRP."
-            ]
-        },
-        {
-            "cell_type": "code",
-            "execution_count": null,
-            "metadata": {},
-            "outputs": [],
-            "source": [
-                "from mcp_bcrp.server import _plot_chart # Usamos la lógica interna para el ejemplo\n",
-                "\n",
-                "# Generamos un gráfico de Expectativas de PBI\n",
-                "img_path = \"expectativas_pbi.png\"\n",
-                "\n",
-                "await _plot_chart(\n",
-                "    series_codes=[\"PD38048AM\"],\n",
-                "    period=\"2020-01/2024-12\",\n",
-                "    title=\"Expectativas del PBI a 12 meses\",\n",
-                "    names=[\"Expectativa PBI (%)\"],\n",
-                "    output_path=img_path\n",
-                ")\n",
-                "\n",
-                "from IPython.display import Image\n",
-                "Image(img_path)"
-            ]
-        },
-        {
-            "cell_type": "markdown",
-            "metadata": {},
-            "source": [
-                "## 6. Análisis Estadístico Rápido\n",
-                "\n",
-                "Al obtener un `pandas.DataFrame`, podemos realizar análisis técnicos de inmediato."
-            ]
-        },
-        {
-            "cell_type": "code",
-            "execution_count": null,
-            "metadata": {},
-            "outputs": [],
-            "source": [
-                "import matplotlib.pyplot as plt\n",
-                "\n",
-                "# Correlación móvil entre Inflación y Expectativas (si tuviéramos ambos)\n",
-                "print(\"Resumen estadístico de las series descargadas:\")\n",
-                "print(df.describe())"
-            ]
-        },
-        {
-            "cell_type": "markdown",
-            "metadata": {},
-            "source": [
-                "---\n",
-                "### ¿Necesitas más ayuda?\n",
-                "\n",
-                "- **Documentación completa**: [README.md](https://github.com/MaykolMedrano/mcp_bcrp/blob/main/README.md)\n",
-                "- **Reportar problemas**: [GitHub Issues](https://github.com/MaykolMedrano/mcp_bcrp/issues)\n",
-                "\n",
-                "Desarrollado con ❤️ para la comunidad de analistas económicos de Perú."
-            ]
-        }
-    ],
-    "metadata": {
-        "kernelspec": {
-            "display_name": "Python 3",
-            "language": "python",
-            "name": "python3"
-        },
-        "language_info": {
-            "codemirror_mode": {
-                "name": "ipython",
-                "version": 3
-            },
-            "file_extension": ".py",
-            "mimetype": "text/x-python",
-            "name": "python",
-            "nbconvert_exporter": "python",
-            "pygments_lexer": "ipython3",
-            "version": "3.11.1"
-        }
-    },
-    "nbformat": 4,
-    "nbformat_minor": 5
-}

mcp_bcrp-0.1.2/mcp_bcrp/search_engine.py

@@ -1,237 +0,0 @@
-"""
-Deterministic Search Engine for BCRP Series.
-
-Pipeline:
-1. Canonical Normalization (lowercase, remove accents, stopwords)
-2. Attribute Extraction (currency, horizon, component)
-3. Hard Filters
-4. Fuzzy Scoring with RapidFuzz
-5. Ambiguity Detection
-"""
-
-import pandas as pd
-import logging
-import unicodedata
-import re
-from typing import Dict, Any
-
-try:
-    from rapidfuzz import fuzz
-except ImportError:
-    fuzz = None
-
-logger = logging.getLogger("mcp_bcrp")
-
-
-class SearchEngine:
-    """
-    Deterministic Search Engine for BCRP Series.
-    
-    Implements a pipeline for univocal series resolution:
-    1. Canonical Normalization
-    2. Hard Filters (Currency, Horizon, Component)
-    3. Fuzzy Scoring
-    4. Ambiguity Detection
-    """
-    
-    STOPWORDS = {'de', 'del', 'el', 'la', 'los', 'las', 'y', 'en', 'al', 'con', 'por'}
-
-    def __init__(self, metadata_df: pd.DataFrame):
-        """
-        Initialize search engine with BCRP metadata.
-        
-        Args:
-            metadata_df: DataFrame with BCRP series metadata.
-        """
-        self.df = metadata_df
-        self._preprocess_metadata()
-
-    def _normalize(self, text: str) -> str:
-        """
-        Canonical normalization of text.
-        
-        Applies: lowercase, accent removal, punctuation removal,
-        stopword filtering, and space collapsing.
-        
-        Args:
-            text: Raw input text.
-            
-        Returns:
-            Normalized string with clean tokens.
-        """
-        if not isinstance(text, str):
-            return ""
-        
-        text = text.lower()
-        text = unicodedata.normalize('NFKD', text).encode('ascii', 'ignore').decode('utf-8')
-        text = re.sub(r'[^\w\s]', ' ', text)
-        tokens = text.split()
-        clean_tokens = [t for t in tokens if t not in self.STOPWORDS]
-        
-        return " ".join(clean_tokens)
-
-    def _extract_attributes(self, text_norm: str) -> Dict[str, Any]:
-        """
-        Extract structured attributes from normalized text.
-        
-        Args:
-            text_norm: Normalized text string.
-            
-        Returns:
-            Dictionary with currency, horizon, component, and scale.
-        """
-        attrs = {
-            "currency": None,
-            "horizon": None,
-            "component": None,
-            "scale": None
-        }
-        
-        tokens = set(text_norm.split())
-        
-        # Currency detection
-        if any(t in tokens for t in ['us', 'usd', 'dolares']):
-            attrs['currency'] = 'usd'
-        elif any(t in tokens for t in ['s', 'pen', 'soles']):
-            attrs['currency'] = 'pen'
-            
-        # Horizon detection
-        if "corto" in text_norm:
-            attrs['horizon'] = 'corto'
-        elif "largo" in text_norm:
-            attrs['horizon'] = 'largo'
-            
-        # Component detection
-        if "activos" in text_norm:
-            attrs['component'] = 'activos'
-        elif "pasivos" in text_norm:
-            attrs['component'] = 'pasivos'
-        
-        # Scale detection
-        if "millones" in text_norm:
-            attrs['scale'] = 'millones'
-        elif "miles" in text_norm:
-            attrs['scale'] = 'miles'
-            
-        return attrs
-
-    def _preprocess_metadata(self):
-        """Pre-calculate normalized tokens and attributes for all series."""
-        if self.df.empty:
-            self.search_corpus = []
-            return
-
-        processed = []
-        for idx, row in self.df.iterrows():
-            raw_name = str(row.get('Nombre de serie', ''))
-            name_norm = self._normalize(raw_name)
-            attrs = self._extract_attributes(name_norm)
-            
-            item = {
-                "idx": idx,
-                "codigo_serie": row.get("Código de serie") or row.get("Codigo de serie"),
-                "name_original": raw_name,
-                "name_norm": name_norm,
-                "tokens": set(name_norm.split()),
-                "currency": attrs['currency'],
-                "horizon": attrs['horizon'],
-                "component": attrs['component'],
-                "scale": attrs['scale']
-            }
-            processed.append(item)
-            
-        self.search_corpus = processed
-
-    def solve(self, query: str) -> Dict[str, Any]:
-        """
-        Resolve query to a single series deterministically.
-        
-        Args:
-            query: Search query (e.g., "tipo de cambio USD")
-            
-        Returns:
-            Dict with 'codigo_serie' and 'confidence' on success,
-            or 'error' and 'reason' on failure/ambiguity.
-        """
-        if not self.search_corpus:
-            return {"error": "no_match", "reason": "empty_corpus"}
-
-        # Parse and normalize query
-        q_norm = self._normalize(query)
-        q_attrs = self._extract_attributes(q_norm)
-        q_tokens = set(q_norm.split())
-        
-        if not q_tokens:
-            return {"error": "no_match", "reason": "empty_query"}
-
-        candidates = self.search_corpus
-        
-        # Apply hard filters (currency, horizon, component)
-        if q_attrs['currency']:
-            candidates = [c for c in candidates if c['currency'] == q_attrs['currency']]
-            
-        if q_attrs['horizon']:
-            candidates = [c for c in candidates if c['horizon'] == q_attrs['horizon']]
-            
-        if q_attrs['component']:
-            candidates = [c for c in candidates if c['component'] == q_attrs['component']]
-             
-        if not candidates:
-            return {"error": "no_match", "reason": "filters_eliminated_all"}
-
-        # Score candidates using fuzzy matching
-        scored_candidates = []
-        for c in candidates:
-            score = 0
-            if fuzz:
-                score = fuzz.token_sort_ratio(q_norm, c['name_norm'])
-            
-            # Penalize missing query tokens
-            q_extras = len(q_tokens - c['tokens'])
-            final_score = score - (5 * q_extras)
-            
-            if final_score >= 80:
-                scored_candidates.append({
-                    "series": c,
-                    "score": final_score,
-                    "original_score": score,
-                    "missing_query_tokens": q_tokens - c['tokens']
-                })
-
-        scored_candidates.sort(key=lambda x: x['score'], reverse=True)
-        
-        if not scored_candidates:
-            return {"error": "no_match", "reason": "low_score"}
-
-        top = scored_candidates[0]
-        
-        # Single match: return directly
-        if len(scored_candidates) == 1:
-            return {
-                "codigo_serie": top['series']['codigo_serie'],
-                "confidence": round(top['score'] / 100.0, 2),
-                "name": top['series']['name_original']
-            }
-            
-        # Multiple matches: check for ambiguity
-        candidates_top_tier = [
-            x for x in scored_candidates 
-            if x['score'] >= (top['score'] - 5)
-        ]
-        
-        currencies = set(x['series']['currency'] for x in candidates_top_tier)
-        components = set(x['series']['component'] for x in candidates_top_tier)
-        
-        if len(currencies) > 1 or len(components) > 1:
-            return {
-                "error": "ambiguedad",
-                "candidates": [x['series']['codigo_serie'] for x in candidates_top_tier[:5]],
-                "reason": "mixed_attributes_in_top_results"
-            }
-             
-        # Deterministic winner
-        return {
-            "codigo_serie": top['series']['codigo_serie'],
-            "confidence": round(top['score'] / 100.0, 2),
-            "name": top['series']['name_original']
-        }