Credit Ratings Monitoring

​

Why It Matters

​

What It Does

​

How It Works

• Content Retrieval & Enhancement: Search for entities and event-specific keywords using the Bigdata Search API. Run queries over configurable time windows with parallel processing, collecting raw content with metadata and enriching results with surrounding context.
• Feature Extraction & Validation: Use LLM-powered analysis to identify entity relationships, extract structured event features, and validate classifications. The prompts can be customized to extract any necessary features for different event types and domains.
• Advanced Analytics Generation: Derive timestamped analytics with event-specific scoring and sentiment analysis tailored to your monitoring requirements.
• Report Generation: Produce dated timelines of events with supporting quotes, source links, and exportable datasets for further analysis or integration into existing workflows.

​

A Real-World Use Case

​

Prerequisites

• 💻 GitHub cookbook
  • Use this if you prefer working locally or in a custom environment.
  • Follow the setup and execution instructions in the README.md.
  • API keys are required:
    • Option 1: Follow the key setup process described in the README.md
    • Option 2: Refer to this guide: How to initialise environment variables
      • ❗ When using this method, you must manually add the OpenAI API key:
        Copy

        Ask AI

        # OpenAI credentials
        OPENAI_API_KEY = "<YOUR_OPENAI_API_KEY>"
        

• 🐳 Docker Installation
  • Docker installation is available for containerized deployment.
  • Provides an alternative setup method with containerized deployment, simplifying the environment configuration for those preferring Docker-based solutions.

​

Setup and Imports

​

Async Compatibility Setup

try:
    import asyncio
    asyncio.get_running_loop()
    import nest_asyncio; nest_asyncio.apply()
    print("✅ nest_asyncio applied")
except (RuntimeError, ImportError):
    print("✅ nest_asyncio not needed")

import pandas as pd
from bigdata_client import Bigdata
from bigdata_client.models.search import DocumentType
from src.knowledge_graph_manager import *
from src.search_enhanced import search_enhanced
from src.feature_extractor import FeatureExtractor
from src.feature_extractor import clean_credit_ratings_features_dataset
from src.summary_generator import SummaryGenerator
from src.visuals import ReportVisualizer

# Setup for Plotly
import plotly.io as pio
import plotly.graph_objects as go

try:
    import os
    if 'JUPYTERHUB_SERVICE_PREFIX' in os.environ or 'JPY_SESSION_NAME' in os.environ:
        pio.renderers.default = 'jupyterlab'
        print("✅ Plotly configured for JupyterLab")
    else:
        pio.renderers.default = 'plotly_mimetype+notebook'
        print("✅ Plotly configured for Jupyter/VS Code")
except:
    pio.renderers.default = 'notebook'
    print("✅ Plotly configured with fallback renderer")

interactive_plots = True  # Set to False to generate static plots

# Define output file paths for our results
output_dir = "report"
os.makedirs(output_dir, exist_ok=True)

export_path = f"{output_dir}/credit_ratings_monitor.csv"

​

Defining Your Event Monitoring Parameters

• Company Names (company_names): The set of companies to monitor events for (e.g. your portfolio or watchlist)
• Rating Agencies Names (rating_agencies_names): (Optional) The list of entities you want to be co-mentioned with your entities and events
• Keywords (keywords): The keywords characterizing the event
• Time Period (start_date_query and end_date_query): The date range over which to run the search
• Frequency (frequency): The frequency of the date ranges to search over. Supported values:
  • Y: Yearly intervals.
  • M: Monthly intervals.
  • W: Weekly intervals.
  • D: Daily intervals
• Document Limit (document_limit): The maximum number of documents to return per query to Bigdata API.
• Batch Size (batch_size): The number of entities to include in a single batched query.
• Document Type (document_type): Specify which documents to search over (transcripts, filings, news)
• Model Selection (llm_model): The AI model used for semantic analysis and topic classification

# ===== Context Definition ====
company_names = ['Tesla']
rating_agencies_names = ['S&P Global', 'Fitch Ratings Inc', "Moody's Corp"]
keywords = ['credit rating']  # Select the keyword related to the event you need to track

# ===== Specify Time Range =====
start_date_query = '2021-10-01'  # Start date
end_date_query = '2024-11-12'    # End date
frequency = 'D'

# ===== Query Configuration =====
document_limit = 100  # Maximum number of retrieved documents for each day
batch_size = 1        # number of companies to process in each batch
document_type = DocumentType.NEWS  # Scope of search

# ===== LLM Specification =====
model = 'openai::gpt-4o-mini'

​

Portfolio Selection

companies, full_company_names, company_objects = get_entity_ids(company_names)

rating_agencies, full_agencies_names, rating_agency_companies = get_entity_ids(rating_agencies_names)

​

Content Retrieval from Bigdata Search API

contextualized_chunks = search_enhanced(
    companies=companies,
    keywords=keywords,
    sentences=None,
    control_entities=rating_agencies,
    start_date=start_date_query,
    end_date=end_date_query,
    scope=document_type,
    freq='D',
    document_limit=100,
    batch_size=1,
    enhance_search=True,
)

​

Features Augmentation

​

Entity Role Detection

feature_extractor = FeatureExtractor(llm_model=model)

df_labeled = feature_extractor.assign_entity_roles(
    contextualized_chunks, 
    'contextualized_chunk_text', 
    ['entity_name', 'headline'], 
    action_type='detect'
)

​

Entity Role Validation

df_labeled_valid = feature_extractor.assign_entity_roles(
    df_labeled, 
    'contextualized_chunk_text', 
    ['entity_name','headline', 'motivation','label'], 
    action_type='validate'
)

​

Credit Features Extraction

• Credit Rating: Extract the overall credit rating assigned to Tesla.
• Credit Action: Extract any change or affirmation of the credit rating assigned to Tesla, categorized as:
  • Upgrade: An improvement in the rating.
  • Downgrade: A decrease in the rating.
  • Affirmed: Rating confirmed with no change.
  • Corrected: Adjusted due to an error.
  • Withdrawn: The rating is removed.
  • Reinstated: A withdrawn rating is restored.
• Credit Status: Any additional information regarding the credit rating status, categorized as:
  • Provisional Rating: A preliminary rating.
  • Matured or Paid in Full: When the obligation reaches maturity.
  • No Rating: Rating declined or unavailable.
  • Published: Officially issued or announced.
• Credit Outlook: The credit outlook mentioned by the rater, and any related mention of the credit rating assessed in the coming weeks, months or years.
  • Positive: Suggests potential improvement.
  • Negative: Indicates potential downgrade.
  • Stable: No expected change.
  • Developing: Change possible based on future events.
• Credit Watchlist: Any mention of Tesla being placed in a credit watchlist for review of the credit rating. Labelled as:
  • Watch: The rating is on a watchlist.
  • Watch Positive: Potential upgrade.
  • Watch Negative: Suggests downgrade.
  • Watch Removed: No longer active.
  • Watch Unchanged: Status remains without change in expectation.

df_labeled_valid['date'] = pd.to_datetime(df_labeled_valid['timestamp_utc']).dt.date

exploded_df = feature_extractor.group_text_and_labels(
    df_labeled_valid, 
    group_columns=['date', 'sentence_id', 'headline', 'source_name', 'contextualized_chunk_text', 'url'], 
    role_column='validated_label', 
    entity_column='entity_name'
)

features_extracted = {}

df_credit_ratings = feature_extractor.extract_single_feature(
    exploded_df, 
    feature_type='credit_ratings', 
    text_col='contextualized_chunk_text', 
    additional_prompt_fields=['rater_entity', 'ratee_entity', 'unclear_entities']
)
features_extracted['credit_ratings'] = df_credit_ratings

• Short Term Credit Rating: Any credit rating assigned to Tesla and specifically referred to a short-term debt instrument, if mentioned.
• Long Term Credit Rating: Any credit rating assigned to Tesla and specifically referred to a long-term debt instrument, if mentioned.
• Debt Instrument: The debt instruments under study.

df_debt_instruments = feature_extractor.extract_single_feature(
    exploded_df, 
    feature_type='debt_instruments', 
    text_col='contextualized_chunk_text', 
    additional_prompt_fields=['rater_entity', 'ratee_entity', 'unclear_entities']
)
features_extracted['debt_instruments'] = df_debt_instruments

• Key Drivers: Any motivating the credit rating or outlook decision, and influencing the credit quality of the ratee entity, including, but not limited to:
  • Cash flow generation (e.g. earnings, revenues, dividends, assets)
  • Insider trading, stock prices, stock picks
  • Capital structure changes (e.g. equity actions, acquisitions, mergers)
• Forward Guidance: Capture any forward guidance discussed regarding current or future credit ratings, including any potential changes or outlook updates.

df_drivers_guidance = feature_extractor.extract_single_feature(
    exploded_df, 
    feature_type='drivers_guidance', 
    text_col='contextualized_chunk_text', 
    additional_prompt_fields=['rater_entity', 'ratee_entity', 'unclear_entities']
)
features_extracted['drivers_guidance'] = df_drivers_guidance

# Combine all features
df_ext = feature_extractor._combine_features(exploded_df, features_extracted)

df_ext['ratee_entity_rp_entity_id'] = df_ext['ratee_entity'].map(
    dict(zip([company.name for company in company_objects], [company.id for company in company_objects]))
)
df_ext = df_ext.sort_values('date').reset_index(drop=True)

​

Deriving a Structured Dataframe of Advanced Analytics

df_clean = clean_credit_ratings_features_dataset(df_ext)

​

Report Generation

summary_generator = SummaryGenerator(llm_model=model)

reports_dict = summary_generator.generate_report_by_entities(
    df=df_clean, 
    entity_keys=companies, 
    text_col='contextualized_chunk_text',
    fields_for_summary=['date', 'ratee_entity', 'headline','source_name','url','contextualized_chunk_text']
)

​

Save and Display Reports

visualizer = ReportVisualizer(output_dir)

​

Tesla Inc.

company_report_text, company_table = reports_dict[f"{company_objects[0].id}"]

# Generate HTML report
html_content = visualizer.convert_text_to_html(
    entity_name=company_objects[0].name,
    start_date=start_date_query, 
    end_date=end_date_query,
    text=company_report_text
)

visualizer.display_html_report(html_content)

# Generate and save rating chart
fig = visualizer.plot_credit_ratings(df=company_table, save_path='credit_ratings_timeline')

​

Export the Results

visualizer.save_html_report(html_content, company_objects[0].name, start_date_query, 
                            end_date_query, filename="credit_ratings_report.html")

# Save the final cleaned dataset with the extracted features
df_clean.to_csv(export_path)

​

Conclusion

1. Monitor rating changes in real-time - Stay ahead of upgrades, downgrades, and outlook revisions that could impact bond spreads and equity valuations
2. Extract structured insights - Transform narrative credit news into structured features including rating actions, outlooks, watchlist status, and key drivers
3. Generate actionable reports - Produce timestamped timelines and exportable datasets for backtesting, portfolio management, and regulatory compliance
4. Analyze market implications - Connect credit events to forward guidance and analyst commentary to anticipate market reactions