{"id":26101578,"url":"https://github.com/austin-starks/finangpt-pro","last_synced_at":"2025-04-06T22:06:00.184Z","repository":{"id":278988311,"uuid":"937347387","full_name":"austin-starks/FinAnGPT-Pro","owner":"austin-starks","description":"A script for creating your very own AI-Powered stock screener","archived":false,"fork":false,"pushed_at":"2025-03-05T15:50:41.000Z","size":93,"stargazers_count":193,"open_issues_count":0,"forks_count":20,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-30T21:05:49.578Z","etag":null,"topics":["ai","analysis","finance","prompt-engineering","tech"],"latest_commit_sha":null,"homepage":"https://nexustrade.io/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/austin-starks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-22T21:23:00.000Z","updated_at":"2025-03-28T08:27:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"19b7fe02-f1ea-4917-a552-03731446bf13","html_url":"https://github.com/austin-starks/FinAnGPT-Pro","commit_stats":null,"previous_names":["austin-starks/finangpt-pro"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/austin-starks%2FFinAnGPT-Pro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/austin-starks%2FFinAnGPT-Pro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/austin-starks%2FFinAnGPT-Pro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/austin-starks%2FFinAnGPT-Pro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/austin-starks","download_url":"https://codeload.github.com/austin-starks/FinAnGPT-Pro/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247557767,"owners_count":20958047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","analysis","finance","prompt-engineering","tech"],"created_at":"2025-03-09T18:04:33.953Z","updated_at":"2025-04-06T22:06:00.160Z","avatar_url":"https://github.com/austin-starks.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Financial Data Downloader \u0026 AI Query System\n\nThis project is based on the article [Grok is Overrated. Do This To Transform ANY LLM to a Super-Intelligent Financial Analyst](https://medium.com/p/40f697092399). It downloads financial data (quarterly and annual) for stocks from EOD Historical Data and stores it in both MongoDB and Google BigQuery. It also includes an AI-powered natural language interface for querying the financial data.\n\nFor a more comprehensive, UI-based solution with additional features like algorithmic trading, check out [NexusTrade](https://nexustrade.io/).\n\n## Prerequisites\n\nBefore you begin, ensure you have the following:\n\n- **Node.js** (version 18 or higher) and **npm** installed.\n- **MongoDB** installed and running locally or accessible via a connection string.\n- **Google Cloud Platform (GCP) account** with BigQuery enabled.\n- **Requesty API key** ([Sign up for Requesty here](https://app.requesty.ai/join?ref=e0603ee5) - referral link).\n- An **EOD Historical Data API key** ([Sign up for a free or paid plan here](https://eodhd.com/pricing?via=austinstarks\u0026ref1=nexustrade) - referral link).\n- (Optional) **Ollama** installed and running locally ([Download here](https://ollama.com/download)) if you want to use local LLM capabilities instead of Requesty.\n- A `.env` file in the root directory with the following variables:\n\n  ```\n  CLOUD_DB=\"mongodb://localhost:27017/your_cloud_db\" # Replace with your MongoDB connection string\n  LOCAL_DB=\"mongodb://localhost:27017/your_local_db\" # Replace with your MongoDB connection string\n  EODHD_API_KEY=\"YOUR_EODHD_API_KEY\" # Replace with your EODHD API key\n  REQUESTY_API_KEY=\"YOUR_REQUESTY_API_KEY\" # Replace with your Requesty API key\n  GOOGLE_APPLICATION_CREDENTIALS_JSON='{\"type\": \"service_account\", ...}' # Replace with your GCP service account credentials JSON\n  OLLAMA_SERVICE_URL=\"http://localhost:11434\" # Optional: Only needed if using Ollama instead of Requesty\n  ```\n\n  **Important:** The `GOOGLE_APPLICATION_CREDENTIALS_JSON` environment variable should contain the _entire_ JSON content of your Google Cloud service account key. This is necessary for authenticating with BigQuery. Make sure this is properly formatted and secured.\n\n## Setup\n\n1.  **Clone the repository:**\n\n    ```bash\n    git clone https://github.com/austin-starks/FinAnGPT-Pro\n    cd FinAnGPT-Pro\n    ```\n\n2.  **Install dependencies:**\n\n    ```bash\n    npm install\n    ```\n\n## Configuration\n\n1.  **Create a `.env` file** in the root directory of the project. Populate it with the necessary environment variables as described in the \"Prerequisites\" section. **Do not commit this file to your repository!**\n\n2.  **Set up Google Cloud credentials:**\n\n    - Create a Google Cloud service account with BigQuery Data Editor permissions.\n    - Download the service account key as a JSON file.\n    - Set the `GOOGLE_APPLICATION_CREDENTIALS_JSON` environment variable to the contents of this file. **Ensure proper JSON formatting.**\n\n## Running the Script\n\nYou have two options for running the script:\n\n**Option 1: Using `node` directly (requires compilation)**\n\n1.  **Compile the TypeScript code:**\n\n    ```bash\n    npm run build\n    ```\n\n    This will create a `dist` directory with the compiled JavaScript files.\n\n2.  **Run the compiled script:**\n\n    ```bash\n    node dist/index.js\n    ```\n\n**Option 2: Using `ts-node` (for development/easier execution)**\n\n1.  **Install `ts-node` globally (if you haven't already):**\n\n    ```bash\n    npm install -g ts-node\n    ```\n\n2.  **Run the script directly:**\n\n    ```bash\n    ts-node index.ts\n    ```\n\n## Usage\n\n### Downloading Financial Data\n\n1. **For all stocks in your watchlist:**\n\n   - The project includes a `tickers.csv` file with a pre-populated list of major US stocks\n   - You can modify this file to add or remove tickers (one ticker per line, skip the header row)\n   - Run the upload script:\n\n   ```bash\n   ts-node upload.ts\n   ```\n\n2. **For a single stock:**\n   - Modify the `upload.ts` script to use `processAndSaveEarningsForOneStock`:\n   ```typescript\n   // In upload.ts\n   const processor = new EarningsProcessor();\n   await processor.processAndSaveEarningsForOneStock(\"AAPL\"); // Replace with your desired ticker\n   ```\n\n### File Structure\n\n```\n.\n├── src/\n│   ├── models/\n│   │   └── StockFinancials.ts\n│   └── services/\n│       ├── databases/\n│       │   ├── bigQuery.ts\n│       │   └── mongo.ts\n│       ├── fundamentalApi/\n│       │   └── EodhdClient.ts\n│       └── llmApi/\n│           ├── clients/\n│           │   ├── OllamaServiceClient.ts\n│           │   └── RequestyServiceClient.ts\n│           └── logs/\n│               ├── ollamaChatLogs.ts\n│               └── requestyChatLogs.ts\n├── tickers.csv\n├── .env\n├── upload.ts\n├── chat.ts\n└── README.md\n```\n\n### Querying Financial Data with AI\n\nThe project includes a natural language interface for querying financial data. You can ask questions in plain English about the stored financial data.\n\nTo use the AI query system:\n\n1. **Run the chat script:**\n\n   ```bash\n   ts-node chat.ts\n   ```\n\n2. **Example queries you can try:**\n   - \"What stocks have the highest revenue?\"\n   - \"Show me companies with increasing free cash flow over the last 4 quarters\"\n   - \"Which companies have the highest net income in their latest annual report?\"\n   - \"List the top 10 companies by EBITDA margin\"\n\nThe system will convert your natural language query into SQL, execute it against BigQuery, and return the results.\n\n### Example Output\n\nHere's a sample response when asking about companies with the highest net income:\n\n```\nHere's a summary of the stocks with the highest reported net income:\n\n**Summary:**\nThe top companies by net income are primarily in the technology and finance sectors. Alphabet (GOOG/GOOGL) leads, followed by Berkshire Hathaway (BRK-A/BRK-B), Apple (AAPL), and Microsoft (MSFT).\n\n**Top Stocks by Net Income:**\n\n| Ticker | Symbol | Net Income (USD) | Date       |\n|--------|--------|------------------|------------|\n| GOOG   | GOOG   | 100,118,000,000 | 2025-02-05 |\n| GOOGL  | GOOGL  | 100,118,000,000 | 2025-02-05 |\n| BRK-B  | BRK-B  | 96,223,000,000  | 2024-02-26 |\n| BRK-A  | BRK-A  | 96,223,000,000  | 2024-02-26 |\n| AAPL   | AAPL   | 93,736,000,000  | 2024-11-01 |\n\n**Insights:**\n- The data includes both Class A and Class B shares for Alphabet and Berkshire Hathaway\n- Most recent data is from early 2025 reporting period\n```\n\n## Important Considerations\n\n- **Error Handling:** The script includes basic error handling, but you may want to enhance it for production use. Consider adding more robust logging and retry mechanisms.\n- **Rate Limiting:** Be mindful of the EOD Historical Data API's rate limits. Implement appropriate delays or batching to avoid exceeding the limits.\n- **Data Validation:** The script filters numeric fields before inserting into BigQuery. You may want to add more comprehensive data validation to ensure data quality.\n- **BigQuery Costs:** Be aware of BigQuery's pricing model. Storing and querying large datasets can incur costs. Optimize your queries and data storage strategies to minimize expenses.\n- **MongoDB Connection:** Ensure your MongoDB instance is running and accessible from the machine running the script.\n- **Security:** Protect your API keys and service account credentials. Do not hardcode them in your code or commit them to your repository. Use environment variables and secure storage mechanisms.\n\n## Contributing\n\nContributions are welcome! Please submit a pull request with your changes.\n\n## License\n\n[MIT License](LICENSE)\n\n### Using Ollama for Local LLM Queries\n\nThis project supports using Ollama as a local LLM alternative to cloud-based services. To use Ollama:\n\n1. **Install Ollama:**\n\n   - Download and install from [ollama.com/download](https://ollama.com/download)\n   - Follow the installation instructions for your operating system\n\n2. **Pull your desired model:**\n\n   ```bash\n   ollama pull llama2  # or mistral, codellama, etc.\n   ```\n\n3. **Ensure Ollama is running:**\n\n   - The service should be running on http://localhost:11434\n   - Verify by checking if the service responds: `curl http://localhost:11434/api/tags`\n\n4. **Configure the environment:**\n   - Make sure your `.env` file includes: `OLLAMA_SERVICE_URL=\"http://localhost:11434\"`\n   - The system will automatically use Ollama for queries when configured\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faustin-starks%2Ffinangpt-pro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faustin-starks%2Ffinangpt-pro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faustin-starks%2Ffinangpt-pro/lists"}