eqlx.org / eqlx-portfolio

Python library · MCP server · v0.2 · Apache-2.0

What a loan book can lose in a bad year.

Loans are judged one by one, but they fail together. eqlx-portfolio looks at all of them at once and says how much could be lost in a bad year, how much capital that takes, and which borrowers and sectors drive it. Then it says what a new loan has to earn to be worth that capital.

View on GitHub See an example Price a loan How it was tested

What goes in, what comes out

No model inside, no network. Same input, same answer.

You give

the loans: amount, chance of default, loss if it defaults
each borrower's sector
how strongly borrowers move together

eqlx-portfolio computes

thousands of possible years, good and bad
who defaults together in each
the total loss of every year
or the same by formula, without simulation

You get

the loss in an ordinary year and in a bad one
the capital that covers the gap
each borrower's and sector's share of the risk
what one more loan would change

One loan book, start to finish

A made-up book of 500 borrowers. What you enter, what the tool computes, what comes back.

1You enter the book

One file of loans, one file of assumptions.

Loans	621 loans to 500 borrowers
Lent in total	995 million
Sectors	6
Moving togetherinside a sector, by sector	12 % to 24 %
Sectors with each other	50 %

2The tool plays 200,000 possible years

In most years little is lost. In a few, many borrowers fail at once. Share of years by loss:

under 5 million

27.8 %

5 to 10

25.4 %

10 to 20

27.8 %

20 to 40

15.3 %

40 to 60

2.9 %

60 to 90

0.70 %

over 90

0.10 %

3An ordinary year and a bad one

The average hides the bad year. Loss in millions, out of 995 lent:

An ordinary yearthe average

12.7

1 year in 100or worse

57.2

1 year in 1,000or worse

91.3

band 88.7 to 93.6 how far chance could move the last figure

4Where the risk sits

Share of the money lent, and share of the loss in the worst years.

construction

of the money

41.1 %

of the risk

69.1 %

services

of the money

19.4 %

of the risk

13.0 %

manufacturing

of the money

14.8 %

of the risk

6.8 %

retail

of the money

11.7 %

of the risk

4.7 %

5Who drives it

Four borrowers hold 18 % of the money and 39 % of the risk.

Borrower	of the money	of the risk
B0004construction	4.0 %	12.7 %
B0003construction	4.7 %	10.6 %
B0005construction	4.2 %	8.8 %
B0001construction	5.5 %	7.4 %

6One more loan of 50 million

Same loan, same expected loss (0.45 million). Extra loss in the worst years, in millions:

to construction17.1 % of the loan

+8.5

to energy7.6 % of the loan

+3.8

2.2 times it lands where the book is already heavy

78.6million of capital · covers all but 1 year in 1,000

What comes back

Expected loss 12.7 million. Loss in the 1-in-1,000 year 91.3 million; the capital is the difference. Construction is 41 % of the money and 69 % of the risk. Every figure comes with the steps that produced it.

7.9 % of the book

Two commands: eqlx-portfolio sample demo, then eqlx-portfolio run demo/loans.csv --config demo/settings.json. Every figure above is their output. The book is made up; no real borrower is behind it.

What the new loan has to earn

The loan of step 6, three years, offered at 43 %. Is that enough for the capital it ties up?

What the rate is made of

For the construction borrower, the lowest rate that still earns the bank's target return:

Fundingwhat the bank pays for the money	40.00 %
Expected lossthe average cost of defaults	1.11 %
Operating cost	1.03 %
Capitalthe target return on the capital tied up	1.62 %
Break-even rate	43.76 %

Inputs: funding 40 %, target return 45 % after 30 % tax, capital earning 38 %, operating cost 1 %. All yours to set.

Four ways to count the capital

Break-even rate by where the capital figure comes from. Bars show the capital part; the other 42.14 % is the same in all four.

to constructionthis book's capital · 16.2 % tied up

43.76 %

to energythis book's capital · 6.7 % tied up

42.82 %

eitherBasel formula · 7.7 % tied up

42.91 %

either100 % risk weight · 12.0 % tied up

43.34 %

43 % on offer enough for energy, not for construction

A formula or a risk weight prices both borrowers the same. Only the book itself can tell them apart.

The tool states the break-even rate. It does not recommend a price.

The assumption that moves everything

How much borrowers have in common changes the capital, not the average loss.

The same book, four assumptions

Expected loss is 12.7 million in all four. Capital for the 1-in-1,000 year, in millions:

0 % in common

36.8

10 % in common

65.1

20 % in common

101.1

30 % in common

139.3

3.8 times from nothing in common to 30 %

The tool does not choose this number. You do, and it shows what follows.

Three ways to the same question

100 equal loans of 1 million, 2 % chance of default, 45 % lost in default, 20 % in common. Loss in the 1-in-1,000 year, in millions:

Simulation100 loans, as they are

10.80

Basel formulaas if infinitely many small loans

10.18

CreditRisk+solved by formula

9.90

+6 % what 100 loans add over infinitely many

The Basel formula assumes no single loan matters. Real books are lumpier. Two methods in one tool let you question one with the other.

How an agent uses it

The agent decides what to ask. The tool computes. It reads files in one folder, writes none, sends nothing.

DescribeWhat is in this loan file?

MeasureLoss in a bad year, and the capital

RankWhich borrowers and sectors drive it

Test a loanWhat would this new loan change, and what must it earn?

Change an assumptionAnd if sectors moved together more?

11 toolsall read-only

6 calls, 52 secondsa real agent wrote a committee memo on the book above

the reason, not "error"when an input is refused, the agent is told why

To connect it to Claude Code:

pip install "eqlx-portfolio[mcp]"
claude mcp add portfolio -- eqlx-portfolio mcp --root /path/to/folder

How it was tested

Against the two public documents that introduced these methods, and against arithmetic that does not share its code.

Matched to published figures

✓107.09 and 2.99CreditMetrics · value of one bond after a year, and its spread

✓3.18Same bond · with uncertain recovery

✓14 of 14CreditMetrics · rating thresholds of two borrowers

✓64 of 64CreditMetrics · joint rating table, each cell within 0.01 point

✓30 of 30CreditMetrics · simulated scenarios mapped to ratings

✓204.40CreditMetrics · worst 1 % value of two bonds

✓14,221,863CreditRisk+ · expected loss of its 25-borrower example

✓within 0.2 %CreditRisk+ · the example's 95th to 99.9th percentile losses

CreditMetrics Technical Document (J.P. Morgan, 1997) and CreditRisk+ (Credit Suisse First Boston, 1997). The CreditRisk+ spreadsheet rounds amounts by a rule the document does not give; the 0.2 % is that rounding.

Checked another way; no published figure exists

Simulated spreadAgainst an exact pair-by-pair formula.

Fine-grained booksAgainst the formula behind the Basel risk weights.

CreditRisk+Against closed forms to 14 decimals, and a brute-force simulation of the same model.

Risk sharesAdd up to the total, in both methods. A what-if matches a separate run to the last digit.

Loan pricingAgainst the closed form of the published scheme it follows, and a loan worked by hand. No published table to match.

Found on the way

Two figures printed in the 1997 document do not follow from its own tables. The tests assert the right value and show where the printed one comes from.

213.29mean value of the two-bond examplethe document prints 213.63

2.70one rating threshold of the BBB borrowerthe document prints 2.78

The first comes from one probability printed as 0.60 % where the document's own matrix has 0.26 %.

The whole

188 testsrun on every change

1 reviewindependent, before release; its 12 fixes are in, each with a test

same numberson old and new NumPy; the seed fixes the scenarios

What it does not do

It estimates nothingChance of default, loss in default and how borrowers move together are your inputs.

One year, defaults onlyA portfolio run counts a loss when a borrower defaults, not when its rating slips.

The far tail is thinA 1-in-1,000 figure rests on few simulated years. The band is printed next to it.

A break-even point, not a priceFunding, costs and the target return are your inputs. Competition and the customer are not in it.

Not regulatory capitalA measure for your own view of risk, not a figure for a supervisory filing.

View on GitHub All limits

pip install "eqlx-portfolio[mcp]"
eqlx-portfolio sample demo
eqlx-portfolio run demo/loans.csv --config demo/settings.json
eqlx-portfolio what-if demo/loans.csv --config demo/settings.json --new new_loan.csv
eqlx-portfolio price demo/loans.csv --config demo/settings.json --new new_loan.csv --terms terms.json