---
title: KasperStocks
emoji: 📈
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 8501
pinned: false
---

# Kasper

Kasper is a Discord-first long-term investing and retirement-planning bot with a Streamlit companion dashboard.

## Included files

- `bot.py` — single-file Discord bot
- `streamlit_app.py` — Streamlit dashboard companion
- `requirements.txt` — Python dependencies
- `.env.example` — environment variable template

## Main bot features

- slash commands and old-style prefix commands
- `/welcome` and `!welcome`
- `/instructions` and `!instructions`
- `/role` and `!role` with a button that toggles the `Kasper` role
- phased contribution projection calculator
- target monthly contribution calculator
- per-server watchlists
- per-server alert channel / role config
- placeholder daily scanner loop for future stock logic

## Setup

### 1. Create the Discord bot and invite it

In the Discord Developer Portal:
- create an application
- create a bot user
- enable the intents you need, especially **Server Members Intent** and **Message Content Intent**
- invite the bot with permissions such as:
  - View Channels
  - Send Messages
  - Embed Links
  - Read Message History
  - Use Slash Commands
  - Manage Roles

### 2. Configure credentials

Copy `.env.example` to `.env` and fill in your values:

```bash
cp .env.example .env
```

You can also paste the token and application ID directly into `bot.py`, but `.env` is cleaner.

### 3. Install requirements

```bash
pip install -r requirements.txt
```

### 4. Run the bot

```bash
python bot.py
```

### 5. Run the Streamlit dashboard

```bash
streamlit run streamlit_app.py
```

## Command summary

### Public
- `/welcome` or `!welcome`
- `/instructions` or `!instructions`
- `/role` or `!role`
- `/calculator` or `!calculator`
- `/project` or `!project`
- `/targetcalc` or `!targetcalc`
- `/addwatch` or `!addwatch`
- `/removewatch` or `!removewatch`
- `/listwatch` or `!listwatch`
- `/serverinfo` or `!serverinfo`

### Admin
- `/setalertchannel` or `!setalertchannel`
- `/setalertroleid` or `!setalertroleid`
- `/setadminroles` or `!setadminroles`
- `/setscanner` or `!setscanner`
- `/testalert` or `!testalert`
- `/sync` or `!sync`

## Notes on hosting

### Discord bot
A Discord bot usually needs to stay connected to Discord's Gateway, so it behaves like an always-on process rather than a typical stateless web app.

### Streamlit UI
The Streamlit app is a better fit for Hugging Face Spaces than the always-on Discord bot process. The strongest setup is usually:
- Discord bot on a stable always-on host
- Streamlit dashboard on Hugging Face Spaces

## Local data files

Kasper stores server data in `./kasper_data/`:
- `guild_config.json`
- `watchlists.json`
- `alert_log.json`

## Next recommended upgrade

Swap the placeholder scanner in `bot.py` for a real free-data pipeline built around:
- SEC filings
- free EOD price source
- local feature store
- long-term stock scoring and buy-zone logic