mcp-bcrp 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

mcp_bcrp/__init__.py

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

mcp_bcrp/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.1.1'
-__version_tuple__ = version_tuple = (0, 1, 1)
+__version__ = version = '0.1.3'
+__version_tuple__ = version_tuple = (0, 1, 3)
 
 __commit_id__ = commit_id = None

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/search_engine.py

@@ -2,18 +2,18 @@
 Deterministic Search Engine for BCRP Series.
 
 Pipeline:
-1. Canonical Normalization (lowercase, remove accents, stopwords)
-2. Attribute Extraction (currency, horizon, component)
+1. Canonical Normalization (lowercase, remove accents, synonyms)
+2. Attribute Extraction (currency, horizon, component, side)
 3. Hard Filters
-4. Fuzzy Scoring with RapidFuzz
-5. Ambiguity Detection
+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
+from typing import Dict, Any, List
 
 try:
     from rapidfuzz import fuzz
@@ -25,16 +25,24 @@ logger = logging.getLogger("mcp_bcrp")
 
 class SearchEngine:
     """
-    Deterministic Search Engine for BCRP Series.
+    Interactive 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
+    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'}
+    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):
         """
@@ -51,72 +59,60 @@ class SearchEngine:
         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.
+        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 from normalized text.
-        
-        Args:
-            text_norm: Normalized text string.
-            
-        Returns:
-            Dictionary with currency, horizon, component, and scale.
-        """
+        """Extract structured attributes to help disambiguate."""
         attrs = {
             "currency": None,
+            "side": None,  # compra / venta
             "horizon": None,
-            "component": None,
-            "scale": None
+            "component": None
         }
         
         tokens = set(text_norm.split())
         
-        # Currency detection
+        # 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'
             
-        # Horizon detection
-        if "corto" in text_norm:
+        # 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 text_norm:
+        elif "largo" in tokens:
             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."""
+        """Pre-calculate normalized search corpus."""
         if self.df.empty:
             self.search_corpus = []
             return
@@ -127,16 +123,18 @@ class SearchEngine:
             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": row.get("Código de serie") or row.get("Codigo de serie"),
+                "codigo_serie": code,
                 "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']
+                "side": attrs['side'],
+                "horizon": attrs['horizon']
             }
             processed.append(item)
             
@@ -144,19 +142,11 @@ class SearchEngine:
 
     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.
+        Resolve query with interactive candidate logic.
         """
         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())
@@ -164,74 +154,76 @@ class SearchEngine:
         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'])
+        # 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'])
             
-            # Penalize missing query tokens
-            q_extras = len(q_tokens - c['tokens'])
-            final_score = score - (5 * q_extras)
+            # 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 final_score >= 80:
-                scored_candidates.append({
-                    "series": c,
-                    "score": final_score,
-                    "original_score": score,
-                    "missing_query_tokens": q_tokens - c['tokens']
+            if score >= 65:
+                scored.append({
+                    "codigo_serie": c['codigo_serie'],
+                    "name": c['name_original'],
+                    "score": score
                 })
 
-        scored_candidates.sort(key=lambda x: x['score'], reverse=True)
+        scored.sort(key=lambda x: x['score'], reverse=True)
         
-        if not scored_candidates:
-            return {"error": "no_match", "reason": "low_score"}
+        if not scored:
+            return {"error": "no_match", "reason": "low_confidence"}
 
-        top = scored_candidates[0]
+        # Logic for result type
+        top_score = scored[0]['score']
         
-        # Single match: return directly
-        if len(scored_candidates) == 1:
+        # 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": top['series']['codigo_serie'],
-                "confidence": round(top['score'] / 100.0, 2),
-                "name": top['series']['name_original']
+                "codigo_serie": high_tier[0]['codigo_serie'],
+                "confidence": round(high_tier[0]['score'] / 100.0, 2),
+                "name": high_tier[0]['name']
             }
-            
-        # 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"
+        # 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']
             }
-             
-        # Deterministic winner
+
+        # 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 {
-            "codigo_serie": top['series']['codigo_serie'],
-            "confidence": round(top['score'] / 100.0, 2),
-            "name": top['series']['name_original']
+            "error": "ambiguedad",
+            "reason": "multiple_candidates",
+            "candidates": candidates
         }

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.1.dist-info → mcp_bcrp-0.1.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-bcrp
-Version: 0.1.1
+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
@@ -14,13 +14,14 @@ Classifier: Intended Audience :: Financial and Insurance Industry
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 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 :: Scientific/Engineering :: Information Analysis
-Requires-Python: >=3.10
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: fastmcp>=0.1.0
@@ -36,16 +37,14 @@ Dynamic: license-file
 # mcp-bcrp
 
 [![Python Version](https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white)](https://www.python.org/downloads/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
-[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-purple?logo=Claude&logoColor=white)](https://modelcontextprotocol.io/)
-[![BCRP API](https://img.shields.io/badge/API-BCRP-red)](https://estadisticas.bcrp.gob.pe/)
-[![Code Style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![GitHub](https://img.shields.io/badge/GitHub-Repository-blue?logo=github)](https://github.com/MaykolMedrano/mcp_bcrp)
+[![PyPI](https://img.shields.io/pypi/v/mcp-bcrp.svg)](https://pypi.org/project/mcp-bcrp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
----
-
-**MCP Server for Banco Central de Reserva del Peru (BCRP) Statistical API**
+[![User Guide](https://img.shields.io/badge/Guide-User_Guide_(Spanish)-green?style=for-the-badge&logo=jupyter)](https://github.com/MaykolMedrano/mcp_bcrp/blob/main/examples/Guia_Usuario_BCRP.ipynb)
+[![Colab](https://img.shields.io/badge/Open_in_Colab-blue?style=for-the-badge&logo=googlecolab)](https://colab.research.google.com/github/MaykolMedrano/mcp_bcrp/blob/main/examples/Guia_Usuario_BCRP.ipynb)
 
-A Model Context Protocol (MCP) server providing programmatic access to Peru's official macroeconomic statistics. This library enables AI assistants and Python applications to query over 5,000 economic indicators directly from the Central Reserve Bank of Peru.
+MCP Server and Python library for the **Banco Central de Reserva del Perú (BCRP)** Statistical API. Access over 5,000 macroeconomic indicators directly from your AI agent or Python environment.
 
 ---
 
@@ -122,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.3.dist-info/RECORD

@@ -0,0 +1,12 @@
+mcp_bcrp/__init__.py,sha256=tDnFxTiEWd9EF_GFYjpFywIVsg3jOTHv8cVr0l5FzUM,371
+mcp_bcrp/__main__.py,sha256=Y12G_44op5TA9oV_KphVmLgGV8GJob5Nxig7yPsib9c,142
+mcp_bcrp/_version.py,sha256=q5nF98G8SoVeJqaknL0xdyxtv0egsqb0fK06_84Izu8,704
+mcp_bcrp/client.py,sha256=8i5nNHecSHh8wE9a7F7XkV0kNfYOImk_JcUNKvVuJSs,12488
+mcp_bcrp/search_engine.py,sha256=SaopNOpRK7k0DN3-kLEOV8I1O_3EMX-Iaja-Qfg23pE,7681
+mcp_bcrp/server.py,sha256=_GUn8xdNB8SfRvZTgJvUsyZfnrI8Z_kUin34XQ1nfDU,11931
+mcp_bcrp-0.1.3.dist-info/licenses/LICENSE,sha256=Btzdu2kIoMbdSp6OyCLupB1aRgpTCJ_szMimgEnpkkE,1056
+mcp_bcrp-0.1.3.dist-info/METADATA,sha256=jdwcGyZOAv_f5gSfjgR2i1jx95AGIcSxvL4qV7K4tWg,12861
+mcp_bcrp-0.1.3.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+mcp_bcrp-0.1.3.dist-info/entry_points.txt,sha256=HXAROyWwyye03ILbKKY_wx83ddOAQQD6KI2sDy-yo6E,53
+mcp_bcrp-0.1.3.dist-info/top_level.txt,sha256=AgccxOm73j9R2xAkb1azi9QQQeQjAiTkD1q-1k_625U,9
+mcp_bcrp-0.1.3.dist-info/RECORD,,

mcp_bcrp-0.1.1.dist-info/RECORD

@@ -1,12 +0,0 @@
-mcp_bcrp/__init__.py,sha256=4DGcjFkG5LnJ82vAbTS_Zx0VR52FZg56WIZ9H_UXJQE,371
-mcp_bcrp/__main__.py,sha256=Y12G_44op5TA9oV_KphVmLgGV8GJob5Nxig7yPsib9c,142
-mcp_bcrp/_version.py,sha256=m8HxkqoKGw_wAJtc4ZokpJKNLXqp4zwnNhbnfDtro7w,704
-mcp_bcrp/client.py,sha256=yeI2m9v6ThsoTcNw4rud1p-CjKeCSUDgWVGtT3e9Pqo,11754
-mcp_bcrp/search_engine.py,sha256=5vktoUgqJHfPyHZ9qYAuqxgSqioiGunjwdLE9Tfp7jo,7670
-mcp_bcrp/server.py,sha256=QhnsAt-Kf7kTnaO5kzcELJSv0ibdptHWTyxVBeegKMU,12435
-mcp_bcrp-0.1.1.dist-info/licenses/LICENSE,sha256=Btzdu2kIoMbdSp6OyCLupB1aRgpTCJ_szMimgEnpkkE,1056
-mcp_bcrp-0.1.1.dist-info/METADATA,sha256=Fq54BswjdBdzaVr28DgtJM1YTQliKBbBughdbhVuRjE,12679
-mcp_bcrp-0.1.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-mcp_bcrp-0.1.1.dist-info/entry_points.txt,sha256=HXAROyWwyye03ILbKKY_wx83ddOAQQD6KI2sDy-yo6E,53
-mcp_bcrp-0.1.1.dist-info/top_level.txt,sha256=AgccxOm73j9R2xAkb1azi9QQQeQjAiTkD1q-1k_625U,9
-mcp_bcrp-0.1.1.dist-info/RECORD,,