Overview

The Corporate Credit Clustering Tool applies domain-guided unsupervised machine learning to produce a structured financial-risk segmentation of companies. The output is a model-relative credit-risk benchmark, not a formal credit rating.

The core question the model answers is: given a company's audited financial profile, how does it compare to a large universe of publicly listed companies across six dimensions of financial risk?

Data sources

The benchmark model is trained on annual financial statement data from SEC EDGAR filings, sourced through structured XBRL facts.

Different XBRL tags for economically similar items (e.g. multiple revenue tags) are resolved through deterministic concept mapping: preferred tags are selected first, with fallback tags used when preferred tags are missing.

Feature engineering

The same feature engineering logic is applied during model training and during private-company scoring. This consistency is critical — the scored company must be represented in the same feature space as the training data.

Derived accounting values

Base ratios

All ratio calculations are protected against very small denominators. When a denominator is below the minimum threshold, the ratio is treated as missing rather than producing an extreme value.

Bounded risk transformation

Raw ratios have different units and scales. The model maps each ratio to a bounded component risk score on [0, 1]:

• For ratios where higher values indicate more risk (e.g. debt/assets): score = clip((x − low) / (high − low), 0, 1)
• For ratios where lower values indicate more risk (e.g. interest coverage): score = clip((good − x) / (good − bad), 0, 1)

Result: 0 = low risk for that component, 1 = high risk. This makes the feature space mathematically suitable for Euclidean-distance-based clustering and financially interpretable.

Thresholds are analyst-defined and professionally calibrated. Debt-service thresholds are intentionally conservative — strong interest coverage is treated as low risk, while merely positive coverage can still carry moderate risk.

Domain feature aggregation — missing-component renormalization

Component risks are aggregated into domain features using fixed per-domain weights. When a component is NaN for a specific row (for example, net_debt_to_ebitda_risk cannot be computed for a company with negative or zero EBITDA), the remaining components are renormalized to their available weight share. Formally:

domain_feature = Σ(w_i × risk_i for present i) / Σ(w_i for present i)

Consequences:

• A domain feature is NaN only when every component in that domain is missing — an edge case that rarely occurs in practice.
• Debt-free companies (CFO/debt undefined), negative-EBITDA companies, and companies missing specific statement items receive valid domain scores based on what can actually be computed.
• When all components are present, the output is identical to a standard weighted sum (component weights within each domain sum to 1.0). There is no backward-compatibility break for complete data.
• The same renormalization applies to the scorecard credit score, which aggregates the six domain features with their stated domain weights.

Six domain features

Component risks are aggregated into six domain features. These six features are the direct model inputs — each company becomes a six-dimensional risk vector. Component weights within each domain sum to 1.0. Missing components are renormalized out (see above).

All six features are already bounded [0, 1] and directionally aligned (higher = more risk). The model does not apply StandardScaler before clustering, because scaling would destroy the intentional financial meaning of the bounded risk space.

Clustering

The model groups companies into five risk tiers based on their six-dimensional risk vectors. The algorithm identifies natural groupings in the financial-risk space — companies with similar risk profiles are placed in the same tier.

Five tiers were selected to produce an interpretable, practical risk scale. The selection balances mathematical cluster quality (measured by silhouette score, Calinski-Harabasz index, and Davies-Bouldin index) with financial interpretability and business communication value.

After clustering, tiers are ranked by their median scorecard credit score — from the strongest financial profile (rank 1) to the weakest (rank 5). Cluster IDs assigned by the algorithm are arbitrary; the ordered risk rank is the meaningful business scale.

Scorecard credit score

The scorecard credit score is a weighted index of the six domain risk features, scaled to [0, 100], with renormalization over the domains that are actually available:

score = 100 × Σ(w_d × risk_d for available d) / Σ(w_d for available d)

The score is not itself the clustering model input. It is used to rank the clusters after training, to explain a company's continuous risk position, and to support report interpretation. When all six domains are available, the sum of weights equals 1.0 and the formula reduces to a standard weighted average.

Soft cluster affinity

After cluster assignment, distances to all centroids are converted to soft affinities using an exponential distance kernel:

a_j = exp(-d_j / T) / Σ_i exp(-d_i / T)

Where d_j is the distance to centroid j and T is a temperature parameter (default 1.0). Higher temperature produces flatter affinity distributions (more uncertainty); lower temperature sharpens the assignment.

Affinity measures how centrally the company sits within its assigned tier. Near-default affinity measures how similar the company is to the weakest tier centroid, regardless of which tier it was assigned to.

Guardrails

Guardrails are a post-model professional interpretation layer. They detect specific financial red flags that may require analyst caution — particularly when the cluster label may appear stronger than the raw financials justify.

Guardrail families include: leverage (high debt/assets, high debt/EBITDA), coverage (weak interest coverage), liquidity (current ratio below 1.0, quick ratio below 0.5), and structural distress (negative equity, liabilities exceeding assets).

Guardrails do not change the cluster assignment. They provide a professional interpretation overlay that qualifies the model output.

Scenario analysis

The report includes mechanical stress scenarios that modify the base financials and rescore the company. Typical scenarios:

Known limitations

Correct terminology

Authentication

All API endpoints require a personal API key passed in the X-API-Key HTTP header.

Obtaining your API key

1. Sign in and go to My profile.
2. Click New key, enter a label, and click Create.
3. Copy the full key immediately — it is shown only once.
4. Store it securely (environment variable, secrets manager).

Using your key

X-API-Key: ccct_sk_your_key_here

POST /api/v1/score

Score one company by submitting financial data as a JSON body. This is the recommended method for programmatic access.

GET /api/v1/score

Score one company using URL query parameters. Useful for quick testing and simple integrations.

Request fields

Required

Optional — identity

Optional — financial inputs

All monetary fields are optional floats. All values must be in the currency specified (or converted via fx_to_model_currency). Omit fields that are not available — the model will score with available inputs and report feature_coverage_pct.

Response fields

Error codes

Error responses include a detail field with a human-readable explanation.

Python example

import requests

API_KEY = "ccct_sk_your_key_here"
BASE_URL = "http://localhost:8080"

payload = {
    "company_name": "Acme Corp",
    "fiscal_year": 2024,
    "assets": 29_721_275,
    "liabilities": 20_638_824,
    "equity": 9_082_353,
    "cash": 34_805,
    "current_assets": 10_037_746,
    "current_liabilities": 12_722_353,
    "long_term_debt": 7_910_588,
    "short_term_debt": 1_478_235,
    "revenue": 48_585_294,
    "net_income": 949_412,
    "operating_income": 1_664_706,
    "interest_expense": 597_647,
    "depreciation_amortization": 2_713_000,
    "cfo": 3_558_235,
    "capex": 588_235,
}

response = requests.post(
    f"{BASE_URL}/api/v1/score",
    json=payload,
    headers={"X-API-Key": API_KEY},
)

response.raise_for_status()
result = response.json()

print(f"Risk tier:  {result['cluster_label']}")
print(f"Score:      {result['scorecard_credit_score']:.1f} / 100")
print(f"Guardrail:  {result['guardrail_level'] or 'Clear'}")
print(f"Coverage:   {result['feature_coverage_pct'] * 100:.0f}%")

cURL example

curl -X POST http://localhost:8080/api/v1/score \
  -H "X-API-Key: ccct_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Corp",
    "fiscal_year": 2024,
    "assets": 29721275,
    "liabilities": 20638824,
    "equity": 9082353,
    "revenue": 48585294,
    "net_income": 949412,
    "operating_income": 1664706,
    "interest_expense": 597647,
    "long_term_debt": 7910588,
    "short_term_debt": 1478235,
    "cfo": 3558235
  }'

GET with query parameters

curl "http://localhost:8080/api/v1/score?\
company_name=Acme+Corp\
&fiscal_year=2024\
&assets=29721275\
&revenue=48585294\
&operating_income=1664706\
&interest_expense=597647" \
  -H "X-API-Key: ccct_sk_your_key_here"

JavaScript example

const API_KEY = "ccct_sk_your_key_here";
const BASE_URL = "http://localhost:8080";

const payload = {
  company_name: "Acme Corp",
  fiscal_year: 2024,
  assets: 29721275,
  liabilities: 20638824,
  equity: 9082353,
  revenue: 48585294,
  net_income: 949412,
  operating_income: 1664706,
  interest_expense: 597647,
  long_term_debt: 7910588,
  short_term_debt: 1478235,
  cfo: 3558235,
};

const response = await fetch(`${BASE_URL}/api/v1/score`, {
  method: "POST",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

if (!response.ok) {
  const err = await response.json();
  throw new Error(err.detail);
}

const result = await response.json();
console.log(`Risk tier: ${result.cluster_label}`);
console.log(`Score:     ${result.scorecard_credit_score.toFixed(1)} / 100`);

Batch file format

For bulk scoring, upload an Excel (.xlsx) or CSV file with one company per row.

Download the template

Go to Batch upload and click Download template (.xlsx). The template contains the correct column headers and an example row.

Column specifications

ZIP output structure

credit_reports_5_companies.zip
├── acme_corp/
│   ├── acme_corp_score_report.xlsx
│   └── acme_corp_credit_report.pdf
├── beta_industries/
│   ├── beta_industries_score_report.xlsx
│   └── beta_industries_credit_report.pdf
└── ...

If a company fails to score, a _ERROR.txt file is included in that company's folder with the error message.

Best practices

• Store your API key as an environment variable, never hardcoded in source files.
• Use POST with JSON body for production integrations. GET with query params is convenient for testing but unsuitable for sensitive financial data.
• Check feature_coverage_pct in every response. Results with coverage below 0.67 should be reviewed manually.
• Check guardrail_level before using results. Override required means the result needs manual analyst review.
• Do not interpret assigned_cluster directly — always use risk_rank and cluster_label.
• Do not present results as formal credit ratings. See the Methodology tab for correct terminology.
• Use the interactive docs at /docs for live endpoint testing during development.
• Deactivate unused API keys from your profile page to reduce attack surface.
• For Excel-based workflows, use the batch upload with a template file rather than calling the API for each company separately.