AIR Credit Intelligence

Compare one company's AIR Implied Rating at two dates and explain the move in notches. Pass `company_id` (a UUID returned by get_entity) and `start_date`; `end_date` defaults to the latest score. Dates are YYYY-MM-DD, YYYY-MM or YYYY, and each resolves to the score for the month containing it, or the latest earlier month (`requested_date` vs `as_of_date`). A year alone means January as `start_date` and December as `end_date`. Returned fields: - `start`, `end`: at each date, `air_credit_risk_score` (the AIR Risk Score, 0 to 1, higher is riskier), `air_rating` (the AIR Implied Rating, AAA to C) and `notch`. - `total_notches` (fractional), `letter_notches` and `direction`: positive is an upgrade. - `bridge`: the move split exactly into steps whose `notches` add up to `total_notches`. Step `group` 'market' is market repricing (how the market re-priced each factor with the company's financials held fixed, plus a market-wide shift); 'company' is the company's own financials changing, with `metrics` showing each measure before and after and `causes` noting known data events; 'bank' is bank-score effects (banks only); 'other' holds a "Scoring differences" step when present: the part of the move that re-scoring with today's model files doesn't reproduce. It is unexplained, not a driver, and `bridge.checks.notes` gives the detail. - `notches_by_group`: the market / company / bank / other totals. `key_steps`: the largest steps. The steps account for the whole move. If `bridge` is null, `message` says why; the ratings and notch change are still valid. The first request for a pair of dates can take several seconds.

compare_rating_periods

Compare two companies' AIR Implied Ratings in the same month and explain the gap in notches. Pass `company_id` and `other_company_id` (UUIDs returned by get_entity). `as_of_date` (YYYY-MM-DD, YYYY-MM or YYYY) defaults to the latest month both companies have scores; both are always compared as of the same month. The comparison runs from `other_company_id` (`start`) to `company_id` (`end`). Each has `air_credit_risk_score` (the AIR Risk Score, 0 to 1, higher is riskier), `air_rating` (the AIR Implied Rating, AAA to C) and `notch`. - `total_notches` > 0 means company_id is rated better (safer) than other_company_id; `direction` is 'higher', 'lower' or 'same'. - `bridge` steps are each category's gap in notches (positive means company_id is safer on that category) and add up to `total_notches`. A step's `metrics` show company_id's value (`value`) against other_company_id's (`value_before`). - `key_steps`: the largest gaps. If `bridge` is null (the two were scored by different model versions that month), `message` says so; the ratings and notch gap are still valid.

compare_company_ratings

Explain the latest AIR credit rating using AIR model drivers and financial context. Pass `company_id` (a UUID returned by get_entity).

get_rating_explanation

Search AIR companies by fuzzy name or ticker and return possible entity matches. The response contains a `status` field: `exact_match` (one literal name/ticker hit), `multiple_matches` (the caller MUST ask the user to disambiguate), or `no_match`. Never auto-select a company from `multiple_matches` — always confirm with the user first.

get_entity

Get the latest AIR Risk Score and AIR Implied Rating for a resolved company. Returned fields: - `air_credit_risk_score`: the AIR Risk Score, AIR's model estimate of credit risk, from 0 (lowest risk) to 1 (highest), e.g. 0.42. - `air_rating`: the AIR Implied Rating, the letter grade nearest the AIR Risk Score on the AAA (best) to C scale, e.g. "BBB". - `score_date`: the date of the score. `financials_date`: the quarter-end of the financials it used. Pass `company_id` (a UUID returned by get_entity).

get_credit_rating

Get a company's AIR Risk Score and AIR Implied Rating over time. Pass `company_id` (a UUID returned by get_entity). `start_date` and `end_date` are optional (YYYY-MM-DD, YYYY-MM or YYYY); the window defaults to the 5 years up to the latest score. A year alone means January as `start_date` and December as `end_date`. A date resolves to the score for the month containing it, or the latest earlier month, never a later one. Returned fields: - `points`: one per period at `frequency` (the period's last month; the latest score is always included), each with `air_credit_risk_score` (the AIR Risk Score, 0 to 1, higher is riskier, e.g. 0.42), `air_rating` (the AIR Implied Rating, AAA to C, e.g. "BBB"), `notch` and `financials_date`. - `rating_changes`: every month-on-month AIR Implied Rating change in the window, whatever the frequency. - `summary`: first, latest, best and worst points, plus the notch move and `direction`. `notch` is the position on the rating scale (C = 0 ... AAA = 20; investment grade is above 10.5). Notch changes are positive for an upgrade and negative for a downgrade. Scores move monthly even without new financials, because market pricing changes: an unchanged `financials_date` means the move came from the market, not a new filing. To explain why the rating moved between two dates, call compare_rating_periods.

get_rating_history

Run a stateless AIR credit scenario and return predictions plus financial parameters. Results are NOT stored. Accepts structured `changes` or a supported natural-language `question`. Each item in `changes` has: - field: one of revenues, cost_of_revenue, operating_expenses, interest_expense, research_and_development, long_term_debt, liabilities, inventory, accounts_payable, net_cash_flow_from_operating_activities, net_cash_flow_from_investing_activities, net_cash_flow_from_financing_activities - change_type: 'percent' or 'absolute' - change_value: number. For percent use a fraction (-0.20 = -20%, 0.05 = +5%). For absolute use the raw dollar amount (e.g. -1000000000 = -$1B). - year: integer >= 1 (default 1 = first projected year) Translation examples: 'revenues fall 20% next year' -> [{field:'revenues', change_type:'percent', change_value:-0.20, year:1}] 'operating expenses up 5%' -> [{field:'operating_expenses', change_type:'percent', change_value:0.05, year:1}] 'long term debt down $1B' -> [{field:'long_term_debt', change_type:'absolute', change_value:-1000000000, year:1}] 'revenues -10% AND opex +5% in year 2' -> [{field:'revenues', change_type:'percent', change_value:-0.10, year:2}, {field:'operating_expenses', change_type:'percent', change_value:0.05, year:2}] If the user's scenario cannot be expressed using these fields, ASK the user to rephrase using one of the supported fields instead of skipping the call. Always pass `company_id` (UUID from get_entity) plus `changes` or `question`.

run_credit_scenario