README.md

---
title: Munger Engine
emoji: 🚀
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
---

# Munger Engine

**Munger Engine** is a specialized stock analysis tool and API designed to replicate and automate value investing strategies (inspired by Charlie Munger). It processes market data, applies fundamental filters, and generates trading signals.

## Features

- **Automated Analysis**: Scans stocks using Yahoo Finance data.
- **Value Filters**: ROE > 15%, Debt/Equity < 50, and technical checks (WMA200).
- **API First**: Exposes signals, ticker details, and sync status via a REST API.
- **Dockerized**: Ready for deployment on Hugging Face Spaces.
- **Secure**: Protected by API Key authentication.

## Documentation

- **[API Documentation](docs/API.md)**: Endpoints, authentication, and examples.
- **[Requirements](docs/funct_reqs.md)**: Functional and technical requirements.
- **[Postman Collection](docs/munger-api.postman_collection.json)**: Importable collection for testing.

## Getting Started

### Prerequisites

- Node.js (v22+)
- Docker (optional, for containerized run)

### Installation

1. Clone the repository:
   ```bash
   git clone https://github.com/Diego-Romero-NTT/munger-engine.git
   cd munger-engine
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Configure Environment:
   Create a `.env` file with:
   ```env
   API_KEY=your_generated_secure_key
   ALPACA_KEY=your_alpaca_key (optional for portfolio check)
   ALPACA_SECRET=your_alpaca_secret (optional)
   NEXT_PUBLIC_SYNC_PASSWORD=Pelikan23!
   ```

4. Run Development Server:
   ```bash
   npm run dev
   ```

### Deployment

This project is configured for **Hugging Face Spaces** using Docker.

- **Push to Space**:
  ```bash
  git push origin main
  ```
  (Assumes `origin` is configured to push to both GitHub and HF).

## License

[MIT](LICENSE)