btgsolutions-dataservices-python-client 4.0.0__tar.gz → 4.2.0__tar.gz

{btgsolutions_dataservices_python_client-4.0.0/btgsolutions_dataservices_python_client.egg-info → btgsolutions_dataservices_python_client-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: btgsolutions_dataservices_python_client
-Version: 4.0.0
+Version: 4.2.0
 Summary: Python package containing several classes and data for extracting and manipulating market and trading data.
 Home-page: https://github.com/BTG-Pactual-Solutions/btgsolutions-dataservices-python-client
 Author: BTG Solutions Data Services powered by BTG Pactual Solutions
@@ -521,12 +521,70 @@ company_data = btg.CompanyData(api_key='YOUR_API_KEY')
 company_data.all_financial_tables(ticker='PETR4')
 ```
 
+#### REST Technical Catalogs
+
+Technical endpoint descriptions for REST APIs are exported by the package so
+MCPs and other connectors can reuse the same source of truth instead of
+duplicating endpoint semantics locally.
+
+```python
+from btgsolutions_dataservices.rest import (
+    DATASERVICES_ENDPOINTS,
+    DATASERVICES_ENDPOINT_RELATIONSHIPS,
+    get_dataservices_tool_description,
+)
+
+print(get_dataservices_tool_description("get_quotes"))
+print(get_dataservices_tool_description("get_book_scope"))
+```
+
+The Data Services catalog covers quotes, candles, intraday trades, last events,
+reference data, corporate events, company fundamental data, HFN news,
+stock-loan data, bulk market data, broker reference, broker analytics and
+book-scope endpoints. It documents parameters, endpoint relationships such as
+available-ticker discovery before market-data calls, broker-reference discovery
+before broker analytics, HFN filter discovery before news queries, corporate
+events before adjusted price analysis, and book-scope constraints for
+microstructure analysis.
+
+The REST catalogs also document cross-domain relationships between Public
+Sources and market-data services: company directory resolution feeds ticker
+reference, quotes, candles, stock-loan, broker analytics and book-scope tools;
+sector classification feeds peer-market comparisons; fund holdings feed
+underlying ticker market analysis; ownership/free-float feeds liquidity context;
+and disclosures, official notices, HFN news and corporate events feed event
+window analysis.
+
 #### Alternative Data - Metadata
 
+Technical endpoint descriptions for the public-sources alternative-data APIs are
+exported by the package so MCPs and other connectors can reuse the same source
+of truth:
+
+```python
+from btgsolutions_dataservices.rest import (
+    PUBLIC_SOURCES_ENDPOINTS,
+    PUBLIC_SOURCES_ENDPOINT_RELATIONSHIPS,
+    get_public_sources_tool_description,
+)
+
+print(get_public_sources_tool_description("get_company_board"))
+```
+
+The catalog documents endpoint parameters, known data gaps, excluded endpoints,
+and relationships such as: company metadata resolving identifiers for governance
+and ownership calls; macro indicator metadata feeding macro observations; asset
+metadata feeding maximum-theoretical-margin calls; financial statement type
+metadata feeding statement queries; assemblies and ownership notices feeding
+notice summaries; and fund holdings/asset fund holders linking funds with
+company tickers.
+
 ```python
 import btgsolutions_dataservices as btg
 meta = btg.AlternativeDataMetadata(api_key='YOUR_API_KEY')
 meta.get_company_directory(query='PETROBRAS', jurisdiction='BR')
+meta.list_companies(query='PETROBRAS', jurisdiction='BR')
+meta.list_etfs(query='BOVA')
 meta.get_company_sector(identifier='PETR4')
 meta.get_taxonomy(system='b3')
 meta.get_cnae(code='6422100')
@@ -543,19 +601,21 @@ meta.get_available_indicators()
 ```python
 import btgsolutions_dataservices as btg
 companies = btg.AlternativeDataCompanies(api_key='YOUR_API_KEY')
+companies.list_companies(query='PETROBRAS', jurisdiction='BR')
 companies.get_board(company_id='VALE3', body='board')
 companies.get_governance_summary(company_id='ITUB4')
 companies.get_governance_history(company_id='PETR4', start_date='2023-01-01', end_date='2024-12-31')
 companies.get_governance_documents(company_id='PETR4', start_date='2024-01-01', end_date='2024-12-31')
 companies.get_governance_compensation(company_id='VALE3', fiscal_year='2024')
 companies.get_governance_related_party(company_id='ITUB4')
-companies.get_governance_beneficial_ownership(company_id='VALE3')
+companies.get_governance_beneficial_ownership(company_id='AAPL')  # UK PSC / US SEC proxy data; not BR listed-company ownership
 companies.get_corporate_registry(company_id='PETR4', direction='partners')
 companies.get_corporate_registry(company_id='PETR4', direction='investees')
 companies.get_insider_trades(company_id='AAPL', start_date='2024-01-01', end_date='2024-12-31')
 companies.get_board_changes(company_id='VALE3', event='appointed')
-companies.get_financial_statements(company_id='PETR4', statement='income_statement', quarter='Q42024')
-companies.get_financial_notes(company_id='VALE3', quarter='Q42024')
+companies.get_assemblies(company_id='PINE4')
+companies.get_financial_statements(company_id='PETR4', statement='income_statement', quarter='4T24')
+companies.get_financial_notes(company_id='VALE3', quarter='4T24')
 companies.get_disclosures(company_id='PETR4', document_type='repurchase')
 companies.get_disclosures(company_id='PETR4', document_type='insider')
 ```
@@ -574,11 +634,13 @@ people.get_appointments(person_id='slug:Jean Paul Lemann', group_by='company')
 ```python
 import btgsolutions_dataservices as btg
 funds = btg.AlternativeDataFunds(api_key='YOUR_API_KEY')
-funds.get_holdings(fund_id='73.232.530/0001-46', reference_date='2024-12-31')
-funds.get_exposures(fund_id='73.232.530/0001-46', exposure_type='asset_class')
-funds.get_history(fund_id='73.232.530/0001-46', start_date='2024-01-01', end_date='2024-12-31')
-funds.get_lookthrough(fund_id='73.232.530/0001-46')
-funds.get_manager_aggregate_holdings(manager_id='ITAÚ ASSET MANAGEMENT')
+funds.list_etfs(query='BOVA')
+funds.get_holdings(fund_id='BOVA11', reference_date='2024-12-31')
+funds.get_exposures(fund_id='BOVA11', exposure_type='asset_class')
+funds.get_history(fund_id='BOVA11', start_date='2024-01-01', end_date='2024-12-31')
+funds.get_lookthrough(fund_id='BOVA11')
+# Manager aggregation requires an exact covered manager CNPJ/name, not ETF issuer slugs, ETF tickers or fund CNPJs.
+# funds.get_manager_aggregate_holdings(manager_id='...')
 ```
 
 #### Alternative Data - Ownership
@@ -591,6 +653,7 @@ ownership.get_ownership_current(company_id='ITUB4')
 ownership.get_ownership_history(company_id='PETR4', start_date='2023-01-01', end_date='2024-12-31')
 ownership.get_ownership_change_events(company_id='VALE3', start_date='2024-01-01', end_date='2024-12-31')
 ownership.get_ownership_official_notices(company_id='PETR4')
+ownership.get_notice_summary(url='https://www.rad.cvm.gov.br/ENETWEB/frmGerenciaPastaDeArquivos.aspx?numProtocolo=1234567')
 ownership.get_ownership_control_group(company_id='VALE3')
 ownership.get_ownership_free_float(company_id='PETR4')
 ownership.get_shareholder_holdings(shareholder_id='00.000.000/0001-91')
@@ -610,9 +673,12 @@ macro.get_macro_indicators(indicator='comexstat', year='2024', state='SP')
 macro.get_macro_indicators(indicator='rreo', year='2024', period='6')
 macro.get_maximum_theoretical_margin(asset='PETR4', report_date='2024-12-31')
 macro.get_dpmfi(start_date='2024-01', end_date='2024-12', status='dados_oficiais')
+macro.get_dpmfi(snapshot_date='2026-06-24', limit=10)  # reproducible scoped snapshot
 macro.get_dpmfi_composition(bond_type='IPCA')
 ```
 
+`AlternativeDataMacroMarkets` exposes the public-sources market-data endpoint for B3 maximum theoretical margin. The direct market-data `investor-categories` endpoint is intentionally not exposed in this package.
+
 ### Reference Data
 
 #### Corporate Events

{btgsolutions_dataservices_python_client-4.0.0 → btgsolutions_dataservices_python_client-4.2.0}/README.md

@@ -494,16 +494,74 @@ company_data.interims(ticker='PETR4')
 
 ```python
 import btgsolutions_dataservices as btg
-company_data = btg.CompanyData(api_key='YOUR_API_KEY')
-company_data.all_financial_tables(ticker='PETR4')
-```
-
-#### Alternative Data - Metadata
-
-```python
-import btgsolutions_dataservices as btg
-meta = btg.AlternativeDataMetadata(api_key='YOUR_API_KEY')
+company_data = btg.CompanyData(api_key='YOUR_API_KEY')
+company_data.all_financial_tables(ticker='PETR4')
+```
+
+#### REST Technical Catalogs
+
+Technical endpoint descriptions for REST APIs are exported by the package so
+MCPs and other connectors can reuse the same source of truth instead of
+duplicating endpoint semantics locally.
+
+```python
+from btgsolutions_dataservices.rest import (
+    DATASERVICES_ENDPOINTS,
+    DATASERVICES_ENDPOINT_RELATIONSHIPS,
+    get_dataservices_tool_description,
+)
+
+print(get_dataservices_tool_description("get_quotes"))
+print(get_dataservices_tool_description("get_book_scope"))
+```
+
+The Data Services catalog covers quotes, candles, intraday trades, last events,
+reference data, corporate events, company fundamental data, HFN news,
+stock-loan data, bulk market data, broker reference, broker analytics and
+book-scope endpoints. It documents parameters, endpoint relationships such as
+available-ticker discovery before market-data calls, broker-reference discovery
+before broker analytics, HFN filter discovery before news queries, corporate
+events before adjusted price analysis, and book-scope constraints for
+microstructure analysis.
+
+The REST catalogs also document cross-domain relationships between Public
+Sources and market-data services: company directory resolution feeds ticker
+reference, quotes, candles, stock-loan, broker analytics and book-scope tools;
+sector classification feeds peer-market comparisons; fund holdings feed
+underlying ticker market analysis; ownership/free-float feeds liquidity context;
+and disclosures, official notices, HFN news and corporate events feed event
+window analysis.
+
+#### Alternative Data - Metadata
+
+Technical endpoint descriptions for the public-sources alternative-data APIs are
+exported by the package so MCPs and other connectors can reuse the same source
+of truth:
+
+```python
+from btgsolutions_dataservices.rest import (
+    PUBLIC_SOURCES_ENDPOINTS,
+    PUBLIC_SOURCES_ENDPOINT_RELATIONSHIPS,
+    get_public_sources_tool_description,
+)
+
+print(get_public_sources_tool_description("get_company_board"))
+```
+
+The catalog documents endpoint parameters, known data gaps, excluded endpoints,
+and relationships such as: company metadata resolving identifiers for governance
+and ownership calls; macro indicator metadata feeding macro observations; asset
+metadata feeding maximum-theoretical-margin calls; financial statement type
+metadata feeding statement queries; assemblies and ownership notices feeding
+notice summaries; and fund holdings/asset fund holders linking funds with
+company tickers.
+
+```python
+import btgsolutions_dataservices as btg
+meta = btg.AlternativeDataMetadata(api_key='YOUR_API_KEY')
 meta.get_company_directory(query='PETROBRAS', jurisdiction='BR')
+meta.list_companies(query='PETROBRAS', jurisdiction='BR')
+meta.list_etfs(query='BOVA')
 meta.get_company_sector(identifier='PETR4')
 meta.get_taxonomy(system='b3')
 meta.get_cnae(code='6422100')
@@ -520,19 +578,21 @@ meta.get_available_indicators()
 ```python
 import btgsolutions_dataservices as btg
 companies = btg.AlternativeDataCompanies(api_key='YOUR_API_KEY')
+companies.list_companies(query='PETROBRAS', jurisdiction='BR')
 companies.get_board(company_id='VALE3', body='board')
 companies.get_governance_summary(company_id='ITUB4')
-companies.get_governance_history(company_id='PETR4', start_date='2023-01-01', end_date='2024-12-31')
-companies.get_governance_documents(company_id='PETR4', start_date='2024-01-01', end_date='2024-12-31')
-companies.get_governance_compensation(company_id='VALE3', fiscal_year='2024')
-companies.get_governance_related_party(company_id='ITUB4')
-companies.get_governance_beneficial_ownership(company_id='VALE3')
-companies.get_corporate_registry(company_id='PETR4', direction='partners')
-companies.get_corporate_registry(company_id='PETR4', direction='investees')
-companies.get_insider_trades(company_id='AAPL', start_date='2024-01-01', end_date='2024-12-31')
+companies.get_governance_history(company_id='PETR4', start_date='2023-01-01', end_date='2024-12-31')
+companies.get_governance_documents(company_id='PETR4', start_date='2024-01-01', end_date='2024-12-31')
+companies.get_governance_compensation(company_id='VALE3', fiscal_year='2024')
+companies.get_governance_related_party(company_id='ITUB4')
+companies.get_governance_beneficial_ownership(company_id='AAPL')  # UK PSC / US SEC proxy data; not BR listed-company ownership
+companies.get_corporate_registry(company_id='PETR4', direction='partners')
+companies.get_corporate_registry(company_id='PETR4', direction='investees')
+companies.get_insider_trades(company_id='AAPL', start_date='2024-01-01', end_date='2024-12-31')
 companies.get_board_changes(company_id='VALE3', event='appointed')
-companies.get_financial_statements(company_id='PETR4', statement='income_statement', quarter='Q42024')
-companies.get_financial_notes(company_id='VALE3', quarter='Q42024')
+companies.get_assemblies(company_id='PINE4')
+companies.get_financial_statements(company_id='PETR4', statement='income_statement', quarter='4T24')
+companies.get_financial_notes(company_id='VALE3', quarter='4T24')
 companies.get_disclosures(company_id='PETR4', document_type='repurchase')
 companies.get_disclosures(company_id='PETR4', document_type='insider')
 ```
@@ -550,12 +610,14 @@ people.get_appointments(person_id='slug:Jean Paul Lemann', group_by='company')
 
 ```python
 import btgsolutions_dataservices as btg
-funds = btg.AlternativeDataFunds(api_key='YOUR_API_KEY')
-funds.get_holdings(fund_id='73.232.530/0001-46', reference_date='2024-12-31')
-funds.get_exposures(fund_id='73.232.530/0001-46', exposure_type='asset_class')
-funds.get_history(fund_id='73.232.530/0001-46', start_date='2024-01-01', end_date='2024-12-31')
-funds.get_lookthrough(fund_id='73.232.530/0001-46')
-funds.get_manager_aggregate_holdings(manager_id='ITAÚ ASSET MANAGEMENT')
+funds = btg.AlternativeDataFunds(api_key='YOUR_API_KEY')
+funds.list_etfs(query='BOVA')
+funds.get_holdings(fund_id='BOVA11', reference_date='2024-12-31')
+funds.get_exposures(fund_id='BOVA11', exposure_type='asset_class')
+funds.get_history(fund_id='BOVA11', start_date='2024-01-01', end_date='2024-12-31')
+funds.get_lookthrough(fund_id='BOVA11')
+# Manager aggregation requires an exact covered manager CNPJ/name, not ETF issuer slugs, ETF tickers or fund CNPJs.
+# funds.get_manager_aggregate_holdings(manager_id='...')
 ```
 
 #### Alternative Data - Ownership
@@ -568,6 +630,7 @@ ownership.get_ownership_current(company_id='ITUB4')
 ownership.get_ownership_history(company_id='PETR4', start_date='2023-01-01', end_date='2024-12-31')
 ownership.get_ownership_change_events(company_id='VALE3', start_date='2024-01-01', end_date='2024-12-31')
 ownership.get_ownership_official_notices(company_id='PETR4')
+ownership.get_notice_summary(url='https://www.rad.cvm.gov.br/ENETWEB/frmGerenciaPastaDeArquivos.aspx?numProtocolo=1234567')
 ownership.get_ownership_control_group(company_id='VALE3')
 ownership.get_ownership_free_float(company_id='PETR4')
 ownership.get_shareholder_holdings(shareholder_id='00.000.000/0001-91')
@@ -585,11 +648,14 @@ macro.get_macro_indicators(indicator='ipca_contributions', start_date='2024-01',
 macro.get_macro_indicators(indicator='gdp', type='yoy')
 macro.get_macro_indicators(indicator='comexstat', year='2024', state='SP')
 macro.get_macro_indicators(indicator='rreo', year='2024', period='6')
-macro.get_maximum_theoretical_margin(asset='PETR4', report_date='2024-12-31')
-macro.get_dpmfi(start_date='2024-01', end_date='2024-12', status='dados_oficiais')
-macro.get_dpmfi_composition(bond_type='IPCA')
+macro.get_maximum_theoretical_margin(asset='PETR4', report_date='2024-12-31')
+macro.get_dpmfi(start_date='2024-01', end_date='2024-12', status='dados_oficiais')
+macro.get_dpmfi(snapshot_date='2026-06-24', limit=10)  # reproducible scoped snapshot
+macro.get_dpmfi_composition(bond_type='IPCA')
 ```
 
+`AlternativeDataMacroMarkets` exposes the public-sources market-data endpoint for B3 maximum theoretical margin. The direct market-data `investor-categories` endpoint is intentionally not exposed in this package.
+
 ### Reference Data
 
 #### Corporate Events

{btgsolutions_dataservices_python_client-4.0.0 → btgsolutions_dataservices_python_client-4.2.0}/btgsolutions_dataservices/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "4.0.0"
+__version__ = "4.2.0"
 
 from .websocket import *
 from .rest import *

{btgsolutions_dataservices_python_client-4.0.0 → btgsolutions_dataservices_python_client-4.2.0}/btgsolutions_dataservices/rest/__init__.py

@@ -22,3 +22,29 @@ from .alternative_data_people import AlternativeDataPeople
 from .alternative_data_funds import AlternativeDataFunds
 from .alternative_data_ownership import AlternativeDataOwnership
 from .alternative_data_macro_markets import AlternativeDataMacroMarkets
+from .alternative_data_catalog import (
+    PUBLIC_SOURCES_CONVENTIONS,
+    PUBLIC_SOURCES_DATA_GAPS,
+    PUBLIC_SOURCES_ENDPOINT_DESCRIPTIONS,
+    PUBLIC_SOURCES_ENDPOINT_RELATIONSHIPS,
+    PUBLIC_SOURCES_ENDPOINTS,
+    PUBLIC_SOURCES_EXCLUDED_ENDPOINTS,
+    PUBLIC_SOURCES_TOOL_DESCRIPTIONS,
+    PUBLIC_SOURCES_TOOL_ENDPOINTS,
+    get_public_sources_endpoint,
+    get_public_sources_endpoint_description,
+    get_public_sources_tool_description,
+    get_public_sources_tool_manifest,
+)
+from .dataservices_catalog import (
+    DATASERVICES_CONVENTIONS,
+    DATASERVICES_ENDPOINT_DESCRIPTIONS,
+    DATASERVICES_ENDPOINT_RELATIONSHIPS,
+    DATASERVICES_ENDPOINTS,
+    DATASERVICES_TOOL_DESCRIPTIONS,
+    DATASERVICES_TOOL_ENDPOINTS,
+    get_dataservices_endpoint,
+    get_dataservices_endpoint_description,
+    get_dataservices_tool_description,
+    get_dataservices_tool_manifest,
+)