📈 Caterpillar Stock Analysis Platform

Empowering investors with AI-driven insights and comprehensive stock analysis

Caterpillar is a comprehensive, AI-powered stock analysis platform that democratizes financial insights for everyone. Whether you're a seasoned investor or just starting your financial journey, our platform provides professional-grade analysis tools with an intuitive, user-friendly interface.

🚀 Key Features

🎯 Comprehensive Stock Analysis

Transform raw market data into actionable insights with our multi-layered analysis approach:

• 📊 Fundamental Analysis: Deep dive into financial metrics using real-time yfinance data
• 📰 Sentiment Analysis: AI-powered news sentiment tracking with FinBERT integration
• 🎯 Investment Recommendations: Smart categorization (Safe, Neutral, Bullish) based on comprehensive data
• 💬 AI Financial Expert: Interactive chat with specialized financial AI for personalized insights
• 📈 TradingView Integration: Professional-grade charts and technical analysis tools

🤖 Flexible AI Integration

Choose your preferred AI provider with seamless integration:

• 🧠 OpenAI GPT-4: Industry-leading language model for financial analysis
• 🌟 Google Gemini: Advanced multimodal AI capabilities
• 🔑 Personal API Keys: Use your own API keys for enhanced privacy and control
• 🔄 Smart Fallback: Automatic fallback to system defaults when needed
• ⚡ Real-time Processing: Lightning-fast AI responses with WebSocket integration

🚀 Quick Start

Get Caterpillar up and running in minutes with our streamlined setup process.

📋 Prerequisites

Before you begin, ensure you have the following installed:

• Python 3.8+ - Download here
• pip - Usually comes with Python
• Git - Download here

🔧 Installation

1. Clone the Repository

git clone https://github.com/semarainc/caterpillar-stock-analysis.git
cd caterpillar-stock-analysis

2. Set Up Virtual Environment

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Linux/Mac:
source venv/bin/activate

# On Windows:
venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Configure Environment (Optional)

Create a .env file in the root directory for system-wide AI provider keys:

# OpenAI Configuration (Optional - users can set their own)
OPENAI_API_KEY=your-openai-api-key-here
OPENAI_BASE_URL=https://api.openai.com/v1/

# Google Gemini Configuration (Optional - users can set their own)
GEMINI_API_KEY=your-gemini-api-key-here

# MarketAux API Configuration (Optional - for news sentiment analysis)
MARKETAUX_API_KEY=your-marketaux-api-key-here
# Or use multiple keys for better rate limits:
MARKETAUX_API_KEY_1=your-first-marketaux-key
MARKETAUX_API_KEY_2=your-second-marketaux-key
MARKETAUX_API_KEY_3=your-third-marketaux-key

💡 Pro Tip: Environment variables are optional! Users can configure their own AI provider keys through the settings page.

5. Launch the Application

Choose your preferred mode:

Development Mode (with auto-reload):

uvicorn main:app --reload --host 0.0.0.0 --port 8000

Production Mode (optimized performance):

uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

🎉 That's it! Open your browser and navigate to http://localhost:8000

🔑 First-Time Setup

When you first run Caterpillar, we automatically create an admin account for you:

⚠️ Security Notice: Please change the default password immediately after your first login for security purposes.

🎯 What's Next?

1. Login with the admin credentials
2. Explore the stock analysis features
3. Configure your AI provider preferences in Settings
4. Create additional user accounts if needed
5. Start analyzing your favorite stocks!

🌐 Platform Overview

🏠 Public Access

No registration required - jump right in and explore:

• 🏠 Home Dashboard (/) - Main stock analysis interface with real-time data
• 🔐 Login Portal (/static/login.html) - Secure user authentication
• 📝 Registration (/static/register.html) - Quick and easy account creation

🔒 Member Features

Unlock advanced capabilities with a free account:

• ⚙️ Personal Settings (/static/settings.html) - Customize your AI provider preferences and account details
• 👥 Admin Console (/static/admin.html) - Comprehensive user management (Administrator access only)

🔌 API Endpoints

Authentication

• POST /api/auth/login - Login user
• POST /api/auth/register - Register user baru
• POST /api/auth/logout - Logout user
• GET /api/auth/me - Get current user info
• POST /api/auth/change-password - Change password

User Settings

• GET /api/settings - Get user settings
• PUT /api/settings - Update user settings (LLM provider & API keys)

Admin (Admin Only)

• GET /api/admin/users - List all users
• POST /api/admin/users - Create new user
• PUT /api/admin/users/{user_id} - Update user
• DELETE /api/admin/users/{user_id} - Delete user
• POST /api/admin/users/{user_id}/reset-password - Reset user password

Stock Analysis

• GET /api/analyze-progress?stock={symbol} - Analyze stock (SSE stream)
• WebSocket /api/chat?stock={symbol}&token={token} - Chat with AI expert
• GET /api/top-stocks - Get top profitable stocks
• GET /api/sectors-tickers - Get S&P 500 sectors & tickers
• GET /api/health - Health check

🗄️ Database Schema

Users Table

- id (INTEGER PRIMARY KEY)
- username (TEXT UNIQUE)
- email (TEXT UNIQUE)
- password_hash (TEXT)
- role (TEXT: 'admin' | 'user')
- is_active (INTEGER: 0 | 1)
- created_at (TIMESTAMP)
- updated_at (TIMESTAMP)

User Settings Table

- id (INTEGER PRIMARY KEY)
- user_id (INTEGER FOREIGN KEY)
- llm_provider (TEXT: 'openai' | 'gemini')
- openai_api_key (TEXT)
- gemini_api_key (TEXT)
- created_at (TIMESTAMP)
- updated_at (TIMESTAMP)

Sessions Table

- id (INTEGER PRIMARY KEY)
- user_id (INTEGER FOREIGN KEY)
- token (TEXT UNIQUE)
- expires_at (TIMESTAMP)
- created_at (TIMESTAMP)

Analysis Cache Table

- id (INTEGER PRIMARY KEY)
- stock (TEXT)
- analysis_date (TEXT)
- result_json (TEXT)
- created_at (TIMESTAMP)

🔐 Security Features

1. Password Hashing - SHA256 hashing untuk password
2. Token-based Authentication - Secure token dengan expiry 30 hari
3. Role-based Access Control - Admin vs User permissions
4. Session Management - Auto cleanup expired sessions
5. API Key Protection - User API keys disimpan terpisah per user

⚙️ Environment Variables for Production

*Users can set their own AI provider API keys through the settings interface

📝 Usage Guide

Untuk User Biasa:

1. Register akun baru di /static/register.html
2. Login dengan credentials
3. (Optional) Set LLM provider & API key di Settings
4. Mulai analisis saham di homepage
5. Chat dengan AI expert untuk insights lebih lanjut

Untuk Admin:

1. Login dengan admin credentials
2. Akses Admin Panel untuk manage users
3. Create, update, atau delete users
4. Reset password users jika diperlukan
5. Monitor user activities

🛠️ Tech Stack

• Backend: FastAPI, Python 3.8+
• Database: SQLite3
• Authentication: Token-based (custom implementation)
• LLM Providers: OpenAI GPT-4, Google Gemini
• Frontend: Vanilla JavaScript, HTML5, CSS3
• Charts: TradingView Widgets
• Stock Data: yfinance, stocknews
• Sentiment Analysis: Transformers (FinBERT)

📦 Project Structure

caterpillar_2/
├── backend/
│   ├── Fundamental.py          # Fundamental analysis
│   ├── sentiment.py            # Sentiment analysis
│   ├── investment_analysis.py  # Investment recommendations
│   ├── database.py             # Database operations & user management
│   ├── auth.py                 # Authentication dependencies
│   ├── api_routes.py           # API endpoints
│   ├── llm_provider.py         # LLM provider abstraction
│   ├── analysis_cache.py       # Analysis caching
│   ├── googlenews.py           # News fetching
│   ├── top_stocks_search.py    # Top stocks finder
│   └── models.py               # Pydantic models
├── frontend/
│   ├── index.html              # Main page
│   ├── login.html              # Login page
│   ├── register.html           # Register page
│   ├── admin.html              # Admin panel
│   ├── settings.html           # User settings
│   ├── app.js                  # Main JavaScript
│   └── style.css               # Styles
├── main.py                     # FastAPI application
├── requirements.txt            # Python dependencies
├── Dockerfile                  # Docker configuration
├── docker-compose.yml          # Docker compose
└── README.md                   # This file

🐛 Troubleshooting

Database tidak ter-initialize

• Pastikan aplikasi memiliki write permission di directory
• Cek log untuk error messages
• Delete app_database.sqlite3 dan restart aplikasi

Admin user tidak bisa login

• Default password: admin123
• Jika lupa password, delete database dan restart aplikasi

LLM tidak merespon

• Cek API key valid
• Cek koneksi internet
• Cek quota API key
• Lihat logs untuk error details

WebSocket connection failed

• Pastikan port tidak diblock firewall
• Cek CORS settings
• Untuk production, gunakan wss:// (secure WebSocket)

🤝 Contributing

We believe in the power of community! Caterpillar is open source and we welcome contributions from developers of all skill levels.

🌟 How to Contribute

1. 🍴 Fork the repository
2. 🌿 Create a feature branch (git checkout -b feature/amazing-feature)
3. 💻 Commit your changes (git commit -m 'Add some amazing feature')
4. 📤 Push to the branch (git push origin feature/amazing-feature)
5. 🔄 Open a Pull Request

🐛 Bug Reports

Found a bug? We'd love to hear about it! Please open an issue with:

• Clear description of the problem
• Steps to reproduce
• Expected vs actual behavior
• Screenshots (if applicable)

💡 Feature Requests

Have an idea for a new feature? Open an issue and tell us:

• What problem does it solve?
• How should it work?
• Any implementation ideas?

📋 Development Guidelines

• Follow PEP 8 for Python code
• Write clear, descriptive commit messages
• Add tests for new features
• Update documentation as needed
• Be respectful and inclusive in all interactions

🛡️ Security

Security is paramount in financial applications. If you discover a security vulnerability, please:

1. DO NOT open a public issue
2. Email us directly at [email protected]
3. Provide detailed information about the vulnerability
4. Allow us time to address the issue before public disclosure

We appreciate responsible disclosure and will acknowledge your contribution.

📊 Project Stats

• Language: Python 3.8+
• Framework: FastAPI
• Database: SQLite3 (production-ready)
• Frontend: Vanilla JavaScript, HTML5, CSS3
• AI Integration: OpenAI GPT-4, Google Gemini
• License: GPL v2.0

📄 License

Caterpillar Stock Analysis Platform is licensed under the GNU General Public License v2.0.

🔓 What This Means

• ✅ Free to use for personal and commercial purposes
• ✅ Free to modify and customize for your needs
• ✅ Free to distribute copies of the software
• ✅ Source code must remain open if you distribute
• ✅ Derivative works must also be GPL v2.0 licensed

For the complete license text, see the LICENSE file.