Introduction
Athena OS helps track your portfolio performance and metrics. In this tutorial, we'll use the freely available Yahoo! Finance API to generate reports and metrics, as well as review your front-end.
Installing Athena OS
Getting started is simple. Install Athena OS via pip (Python 3.10 or later required):
pip install athenaos
That's it — you now have access to the athenaos command-line tool and all its dependencies.
Setting Up Your Portfolio
We'll set up a dummy portfolio where you buy shares in Nvidia (listed on the NASDAQ) and BYD (listed on the Hong Kong Stock Exchange, HKSE). This will help show how to track your finances, convert money, and more.
Download the portfolio here.
Trades and other decisions are all tracked in Excel, so you can manually edit them. Each transaction has the following fields:
- SYMBOL — the ticker. Since we're using Yahoo! Finance, we'll stick to the conventions there, such as appending ".HK" for HKSE-listed companies.
- DATE AND TIME — the date and time of the transaction. You can include only the date, or a full time stamp like
2026-02-15T14:30:00-05:00 which includes the year, month, date, time, and timezone (-5 hours from GMT, in the case above). If you don't provide a time or time zone, we assume the time zone is New York-based, and that the transaction took place at 12pm.
- TRANSACTION TYPE — you can use one of these transaction types:
CASH_IN, CURRENCY_EXCHANGE, BUY, SELL, DIVIDEND, INTEREST, FEE, or CASH_OUT. We'll cover the first four in this tutorial.
- PRICE — the price paid per 1 unit of the ticker.
- QUANTITY — the quantity purchased.
- CURRENCY — the currency used.
First, let's deposit $25K USD into the account and spend half of it on Nvidia. Below are the values for the NVDA purchase at $190 at the start of the year.
| Symbol |
Date and Time |
Transaction Type |
Price |
Quantity |
Currency |
| n/a |
2026-01-01 |
CASH_IN |
1 |
25,000 |
USD |
| NVDA |
2026-01-05 |
BUY |
190 |
65 |
USD |
Next, suppose we converted USD to Hong Kong Dollars (HKD) and bought BYD (1211.HK) shares in early February. Those two transactions are below.
| Symbol |
Date and Time |
Transaction Type |
Price |
Quantity |
Currency |
| HKD |
2026-02-01 |
CURRENCY_EXCHANGE |
0.125 |
80,000 |
USD |
| 1211.HK |
2026-02-03 |
BUY |
90 |
800 |
HKD |
For currency conversions (CURRENCY_EXCHANGE), the SYMBOL is the target currency (e.g. "HKD") and the CURRENCY is the source currency (e.g., "USD"). The price is how much of the CURRENCY it costs to buy 1 unit of the target (SYMBOL) currency.
In the case above, we converted about $10K USD to 80,000 Hong Kong Dollars on February 1, then waited about 2 days to buy BYD.
You can download this basic portfolio as an Excel file.
Running Your First Report
Once you have the portfolio file, the rest is easy! To get your positions, run the following:
athenaos report first-portfolio.xlsx
You should see the following output. Note that depending on when you run this, the numbers will be different since we're pulling delayed market data from Yahoo! Finance.
athenaos report
█████╗ ████████╗██╗ ██╗███████╗███╗ ██╗ █████╗
██╔══██╗╚══██╔══╝██║ ██║██╔════╝████╗ ██║██╔══██╗
███████║ ██║ ███████║█████╗ ██╔██╗ ██║███████║
██╔══██║ ██║ ██╔══██║██╔══╝ ██║╚██╗██║██╔══██║
██║ ██║ ██║ ██║ ██║███████╗██║ ╚████║██║ ██║
╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═══╝╚═╝ ╚═╝
ATHENA — Agentic Toolkit for Holistic Economic Narratives and Analysis
⚠ This is an experimental investing toolkit. All ideas, research,
and analysis should be verified by a human. Nothing here should be
construed as investment advice.
Open Positions on 2026-02-25 21:12 EST
┏━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ ┃ ┃ Unit Price ┃ ┃ ┃ ┃
┃ ┃ ┃ (Book → ┃ Book Value ┃ Market Value ┃ ┃
┃ Symbol ┃ Quantity ┃ Market) ┃ (USD) ┃ (USD) ┃ Gain/Loss % ┃
┡━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
│ NVDA │ 65 │ $190.00 → │ $12,350.00 │ $12,711.40 │ +2.93% │
│ │ │ $195.56 │ │ │ │
│ 1211.HK │ 800 │ $11.52 → │ $9,213.29 │ $9,986.18 │ +8.39% │
│ │ │ $12.48 │ │ │ │
└─────────┴──────────┴────────────────┴────────────────┴───────────────┴─────────────┘
Cash Balances
┏━━━━━━━━━━┳━━━━━━━━━━┓
┃ Currency ┃ Balance ┃
┡━━━━━━━━━━╇━━━━━━━━━━┩
│ HKD │ 8,000.00 │
│ USD │ 2,650.00 │
└──────────┴──────────┘
╭───────────────────────────────────── Summary ──────────────────────────────────────╮
│ Total Portfolio Value: $26,371.28 │
╰────────────────────────────────────────────────────────────────────────────────────╯
Advanced Metrics
To get more advanced metrics, run this command instead:
athenaos metrics first-portfolio.xlsx
athenaos metrics
█████╗ ████████╗██╗ ██╗███████╗███╗ ██╗ █████╗
██╔══██╗╚══██╔══╝██║ ██║██╔════╝████╗ ██║██╔══██╗
███████║ ██║ ███████║█████╗ ██╔██╗ ██║███████║
██╔══██║ ██║ ██╔══██║██╔══╝ ██║╚██╗██║██╔══██║
██║ ██║ ██║ ██║ ██║███████╗██║ ╚████║██║ ██║
╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═══╝╚═╝ ╚═╝
ATHENA — Agentic Toolkit for Holistic Economic Narratives and Analysis
⚠ This is an experimental investing toolkit. All ideas, research,
and analysis should be verified by a human. Nothing here should be
construed as investment advice.
Portfolio Metrics Report - 2026-02-25 21:13 EST
Currency: USD | Risk-Free Rate: 5.00% | Confidence: 95%
Risk-Adjusted Return Metrics
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┓
┃ Metric ┃ Daily ┃ Annualized ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━┩
│ Sharpe Ratio │ 0.0890 │ 1.7012 │
│ Sharpe Ratio (DTB3) │ 0.0888 │ 1.4099 │
│ Sortino Ratio │ 0.1561 │ 2.9829 │
└─────────────────────┴────────┴────────────┘
Alpha & Beta (vs Market Benchmarks)
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━┓
┃ Benchmark ┃ Alpha (Annual) ┃ Beta ┃ R² ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━┩
│ S&P 500 (^GSPC) │ 23.72% │ 0.75 │ 23.25% │
│ NASDAQ (^IXIC) │ 31.24% │ 0.63 │ 28.46% │
└─────────────────┴────────────────┴──────┴────────┘
Volatility Metrics
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┓
┃ Metric ┃ Daily ┃ Annualized ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━┩
│ Total Volatility │ 0.96% │ 18.34% │
│ Upside Volatility │ 0.96% │ 18.39% │
│ Downside Volatility │ 0.64% │ 12.29% │
└─────────────────────┴───────┴────────────┘
Volatility Ratio (Down/Up): 0.6683 - More upside variability
Drawdown Metrics
┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Metric ┃ Value ┃ Details ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Maximum Drawdown │ -4.46% │ Peak: 2026-02-01 → Trough: 2026-02-05 │
└──────────────────┴────────┴───────────────────────────────────────┘
Value at Risk (95% Confidence)
┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Metric ┃ Historical ┃ Parametric ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ Value at Risk (VaR) │ -1.39% │ -1.48% │
│ Conditional VaR (CVaR) │ -1.73% │ -1.73% │
└────────────────────────┴────────────┴────────────┘
Win Rate Metrics
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
┃ Metric ┃ Closed Positions ┃ All Positions ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
│ Win Rate │ No closed positions │ 100.0% │
│ Total Positions │ 0 │ 2 │
│ Winning │ 0 │ 2 │
│ Losing │ 0 │ 0 │
│ Breakeven │ 0 │ 0 │
│ Average Win │ N/A │ $562.03 │
│ Average Loss │ N/A │ N/A │
│ Win/Loss Ratio │ N/A │ N/A │
│ Total Gain/Loss │ $0.00 │ $1,124.06 │
└─────────────────┴─────────────────────┴───────────────┘
╭───────────────────────────────── Summary Insights ─────────────────────────────────╮
│ ✓ Good risk-adjusted returns (Sharpe > 1.0) │
│ ✓ Low maximum drawdown (<10%) │
╰────────────────────────────────────────────────────────────────────────────────────╯
Using the Frontend
To launch the interactive frontend, run:
athenaos frontend first-portfolio.xlsx
This will take a few minutes to load data, but once it does, you'll be able to visit http://127.0.0.1:4770 on your computer and analyze your portfolio via widgets.
Next Steps
... and that's it! You can now review your metrics, run analyses via the frontend, and more. If you want to learn how to run more advanced features, check back on the site or visit our community!