Track your portfolio, individual positions, forex, and other financial instruments in one place. Pull data from the Federal Reserve, Yahoo! Finance, and custom sources. Track metrics to benchmark yourself against hedge funds. Use LLMs to manage your portfolio.
Athena is a toolkit designed to easily track investments and delegate decision-making to a large language model. Our vision is to have LLMs help with tracking major news developments, run scenario analyses, and ultimately open and close positions.
The data structure lives in Excel; it can be edited by you to input positions, override choices, or incorporate your existing portfolios.
This is an experimental toolkit. It should be used to inform your research and does not represent any sort of official investment advice.
Install via pip:
pip install athenaosInstall via GitHub:
pip install git+https://github.com/wgryc/athena-os.gitIf you are cloning the repo and installing from local source, run the following: pip install -e . or pip install -e ".[dev]" to run tests.
Track your portfolio positions, currencies, and values:
athenaos report sample_transactions.xlsxHedge fund metrics around your portfolio performance:
athenaos metrics sample_transactions.xlsxTransactions and portfolio information are stored in Excel files and are easily editable by users. A transactions file needs the following columns:
- SYMBOL: the ticker symbol. By default, use the Yahoo Finance! ticker format. However, you can use anything that is supported by the pricing APIs you are using.
- DATE AND TIME: ISO format for the date-time transaction is preferred, but you can also use standard Excel dates. If time zone information is missing, we assume NYC time. If times are missing (i.e., only dates are provided) we assume 12pm NYC time.
- TRANSACTION TYPE: we support BUY, SELL, CASH_IN, CASH_OUT, DIVIDEND, INTEREST, FEE, and CURRENCY_EXCHANGE.
- PRICE: the price paid per unit of SYMBOL.
- QUANTITY: the quantity being purchased.
- CURRENCY: the currency being used. We currently support USD, CAD, EUR, TWD, SGD, AUD, JPY, KRW, GBP, BRL, CNY, HKD, MXN, ZAR, CHF, and THB.
When logging currency exchanges, 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.
Agents require connections to third-party APIs and API keys should be stored in a local .env file. If you are trading stocks, we recommend using the Massive API while for CBOE-traded commodities, we recommend DataBento. Finally, the current agents use the Emerging Trajectories "events" API to get information and trade on it.
athenaos demo --commodities demo_commodities.xlsxathenaos demo --meme-stocks demo_meme_stocks.xlsxathenaos demo --us-stocks demo_us_stocks.xlsxGenerate interactive HTML dashboards to visualize your portfolio performance, returns, and Sharpe ratio over time.
athenaos dashboard sample_transactions.xlsxThis creates a portfolio_dashboard.html file in the current directory. To specify a custom output filename:
athenaos dashboard sample_transactions.xlsx --output my_dashboard.htmlIf the output file already exists, Athena will automatically append "copy" to the filename to avoid overwriting.
Launch the interactive web frontend with AI-powered chat:
athenaos frontend sample_transactions.xlsxOr, set portfolio_file in config.json and run without arguments:
athenaos frontendThe frontend reads from a config.json file in the current directory. This replaces the old widgets.json format (which is still supported for backwards compatibility).
{
"portfolio_file": "sample_transactions.xlsx",
"widgets": [
{"tool": "stock_price_widget", "kwargs": {"symbol": "AAPL"}},
{"tool": "stock_price_widget", "kwargs": {"symbol": "MSFT"}}
],
"gateways": {
"telegram": {
"bot_token": "YOUR_BOT_TOKEN"
}
}
}You can connect a Telegram bot to Athena so that messages you send via Telegram are processed by the same AI chat. Responses appear both in Telegram and in the web frontend (with a "TELEGRAM" badge).
Setup:
- Open Telegram and message @BotFather.
- Send
/newbot, follow the prompts to name your bot, and copy the bot token. - Add the token to your
config.json:{ "gateways": { "telegram": { "bot_token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz" } } } - Start the frontend (
athenaos frontend). You should seeGateway started: telegramin the console. - Open your bot in Telegram and send a message. The AI will respond in Telegram, and both the question and answer will appear in the web chat panel in real time.
The gateway system is extensible -- additional platforms (Discord, Slack, etc.) can be added via the same gateways configuration pattern.
The athenaos frontend command can also run scheduled tasks when it is running in server mode. To facilitate data entry and review, the tasks are defined via an Excel file. This file has the following columns:
- TASK NAME: a short and pithy name for the task, for easy referencing in chats.
- SCHEDULE: define how often you want to schedule a task. You can write this in plain English (or language of your choice). "Once per hour" or "1230pm ET daily" are both acceptable.
- DESCRIPTION: the actual you want the agents to complete. Agents will choose their own tools unless you specifically call them out.
- LAST RUN: we ask the LLM to update the file to mention when the tool was last run.
- ADDED BY: options hare are typically "user" and "athena". The idea is to track who added the task, as Athena can add tasks directly, too.
Tasks can be added by Athena via tool use. There is a tab at the top of the frontend for easy visual editing of tasks, too.
The default is that there is no tasks file, and one should be added to the config.json (or equivalent file) with the tasks_file parameter.