# Counterparty Credit

An open, transparent MCP server that scores the credit health of public energy companies
from public data. Ask an agent how sound a utility, generator, midstream operator, or
power/gas marketer is; Counterparty Credit answers with a 0–100 score, a factor-by-factor
breakdown, and the public source behind every number.

It is **decision-support, not a credit rating** — every output is sourced, explainable, and
meant for human review. The point is a score you can argue with, not a black box.

Built by [ComtechAI](https://comtechai.com). Methodology version: `ccr-ref-1.3`.

## Status: v1, deliberately stable

This repo is a scope-frozen reference implementation. It stays published and working;
bug fixes and upstream-breakage patches are welcome, new capability is out of scope here.
See `DEVELOPMENT.md` for setup, tests, and contribution rules.

## How it works

One MCP tool, `counterparty.health`, takes a company name or ticker. It resolves the SEC
filer, pulls public financials and market data, scores four factors, and blends them into a
composite with a descriptive band (Strong / Stable / Watch / Stressed / Distressed).

| Factor | What it reads | Source |
|---|---|---|
| **F1 — Balance-sheet strength** | Leverage, interest coverage, current ratio | SEC EDGAR (XBRL) |
| **F3 — Market-implied risk** | Distance-to-default (naive Merton) + equity volatility | Tiingo daily prices + EDGAR |
| **F4 — Business-mix / commodity exposure** | Structural insulation of cash flows, by business type | Classification universe (27 names) |
| **F5 — Event / news** | Rating actions, covenant/liquidity events, unplanned outages | Google News RSS |

The composite is a **renormalized weighted blend over whatever factors actually compute this
run**. Reference weights are F1 0.20 · F3 0.15 · F4 0.25 · F5 0.15. When a factor's inputs are
missing — no market feed for F3, an unclassified name for F4 — that factor drops and its
weight redistributes across the rest. Nothing is imputed; a factor is either computed from
real data or absent.

Every result carries a `methodology_version` and an `as_of` date, and each factor names the
filing or feed behind it. Where a figure is a proxy (see limitations), the source line says so.

## Install

Requires Python 3.10–3.14.

```bash
python3 -m venv venv && source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -e .
```

## Use it

### From the command line

```bash
export SEC_USER_AGENT="Your Name you@example.com"   # SEC requires a contact User-Agent
export TIINGO_TOKEN="your_tiingo_key"               # optional; F3 is skipped without it
python3 -m counterparty_credit.cli "NextEra Energy"
python3 -m counterparty_credit.cli DUK
```

SEC returns HTTP 403 without a descriptive `User-Agent`. A free Tiingo token enables F3;
omit it and the tool scores on F1/F4/F5 and says so. Filings and the ticker map cache under
`~/.cache/counterparty-credit` for 24 hours.

### From Claude Desktop

Copy `claude_desktop_config.example.json` into your Claude Desktop config, set the `command`
to this repo's venv Python (absolute path) and your keys in `env`, then restart Claude and ask
*"How financially sound is NextEra as a counterparty?"* Claude calls the tool and reads back
the score, breakdown, and sources.

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

If the company can't be resolved or its data can't be retrieved, the tool **returns an error
rather than a number**. A score is only ever returned when it was actually computed.

## Methodology

Scoring reads from a `Methodology` config object, not hardcoded constants.
`Methodology.default()` is the open reference, locked at `ccr-ref-1.3`. The committed record:

- `src/counterparty_credit/methodology.py` — source of truth for all curves, weights, thresholds
- `docs/methodology-c0.md` — human-readable methodology of record
- `docs/methodology-c0.json` — machine spec (a test guards against drift)

A custom methodology states only its overrides and inherits the rest of the reference:

```bash
CCR_METHODOLOGY=/path/to/methodology.json python3 -m counterparty_credit.cli "NextEra Energy"
```

Because every result is stamped with its version, a custom config is visibly not the
reference. The locked numbers are a starting hypothesis, refined against real names; a
recalibration is a new version, never a silent rewrite.

## Limitations

These are deliberate and stated plainly. An honest scope is the point of a reference tool.

- **Not a credit rating.** Decision-support from public data. No issuer engagement, no
  non-public information, no rating-agency methodology.
- **F2 (liquidity / collateral) is withheld from the live blend.** Its v0 cash proxy returned
  near-identical scores regardless of credit quality, so it adds no discrimination. It is
  defined in the methodology but excluded until a real collateral-stress model replaces the
  proxy.
- **F3 needs a market feed.** Without a Tiingo token, or for a name without clean price data,
  F3 drops and its weight redistributes.
- **F4 covers a fixed 27-name universe** of North American energy issuers. Names outside it
  are scored without the business-mix factor rather than guessed at.
- **F5 keys on a fixed vocabulary.** It detects rating actions phrased as *upgrade* /
  *downgrade* (gated to require rating-agency context) and a set of credit events; it will
  miss rating actions phrased with other verbs, and headline sentiment is coarse.
- **Coverage may use a cash-paid proxy.** Some large filers tag no interest-expense concept;
  for those, coverage is computed from cash interest paid, which excludes capitalized
  interest. The source line flags this per name.
- **Point-in-time public data.** Figures are as-of the latest filing; a stale filing is
  flagged, not silently used.

## Layout

```
src/counterparty_credit/
  schema.py          # locked I/O contract (HealthResult)
  methodology.py     # config object — reference default + worksheet loader
  resolve.py         # name/ticker → CIK + ticker (SEC company_tickers.json)
  edgar.py           # XBRL companyfacts → financials (recency-aware tag selection)
  ratios.py          # leverage / coverage / liquidity
  market.py          # daily prices → price + annualized vol (Tiingo)
  dtd.py             # naive-Merton distance-to-default
  news.py            # recent headlines (Google News RSS)
  scoring.py         # F1, F3, F5 scorers
  f4_business_mix.py # F4 business-mix lookup over the universe
  universe.json      # 27-name classification universe
  score.py           # orchestration → weighted composite → HealthResult
  server.py          # MCP tool
  cli.py             # one-command live scoring
tests/
```

## Disclaimer

Counterparty Credit produces decision-support from public data. It is not a credit rating,
not investment advice, and not affiliated with any rating agency or the issuers it scores.
Outputs are sourced and intended for human review.