Metadata-Version: 2.4
Name: girlfriend
Version: 1.0.0
Summary: Funny romantic virtual girlfriend assistant for Linux terminal users
Author: Open Source Contributors
License-Expression: MIT
Keywords: cli,linux,terminal,fun,companion,meme
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.7.0
Dynamic: license-file

# girlfriend

`girlfriend` is a funny, cute, nerdy Linux terminal companion built for meme-loving CLI users. It works fully offline, prints colorful romantic nonsense, tracks your streaks, monitors your system, and ships with packaging for both `pip` and Debian-style `.deb` installs.

## Features

- Random romantic one-liners with mood-based personalities
- Moods: `caring`, `jealous`, `hacker`, `clingy`, `sleepy`, `gamer`, `motivational`
- ASCII reaction mode and startup logo
- Nerdy compliment mode
- Harmless Linux-user roast mode
- Daily streak and interaction stats stored in `~/.girlfriend/`
- System monitoring with CPU, RAM, disk, battery, and distro detection
- Desktop notifications via `notify-send`
- Voice mode via `espeak`
- Softer offline voice presets with feminine profiles like `cute`, `soft`, and `anime`
- Offline chat mode with a rule-based reply engine
- Config file support with themes and preferences
- Clean modular Python architecture for future Ollama, Gemini, or OpenAI integrations

## Project Layout

```text
girlfriend/
├── girlfriend/
│   ├── __init__.py
│   ├── ai_chat.py
│   ├── ascii_art.py
│   ├── cli.py
│   ├── config.py
│   ├── messages.py
│   ├── moods.py
│   ├── notification.py
│   ├── streaks.py
│   ├── system_monitor.py
│   └── voice.py
├── assets/
├── debian/
├── screenshots/
├── tests/
├── LICENSE
├── pyproject.toml
├── README.md
├── requirements.txt
└── setup.py
```

## Sample Output

```bash
$ girlfriend --mood hacker
GIRLFRIEND CLI
Linux terminal romance, now with more memes.

💻 I would alias `home` to wherever you are. 💻
streak: 4 day(s) • total chats: 29
```

```bash
$ girlfriend compliment
💕 You are the sudo to my heart. 💕
```

```bash
$ girlfriend roast
😤 Your terminal history is just speedrunning the same mistake in new ways. 😤
```

```bash
$ girlfriend monitor
CPU      31.4%
RAM      48.2%
Disk     63.8%
Battery  77%

System looks stable. You may continue being adorable and computationally dangerous.
```

## Installation

### Install with pip

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install .
girlfriend --help
```

### Install globally

```bash
sudo pip3 install .
```

This exposes the command as:

```bash
girlfriend
```

### Debian or Ubuntu package install

Build prerequisites:

```bash
sudo apt update
sudo apt install -y debhelper-compat dh-python python3-all python3-setuptools python3-rich
```

Build the package:

```bash
dpkg-buildpackage -us -uc -b
```

Install the generated package:

```bash
sudo dpkg -i ../girlfriend_1.0.0-1_all.deb
```

Now you can run:

```bash
girlfriend
```

## Usage

```bash
girlfriend
girlfriend --mood caring
girlfriend --mood jealous --ascii
girlfriend --quote
girlfriend compliment
girlfriend roast
girlfriend streak
girlfriend stats
girlfriend monitor
girlfriend speak
girlfriend chat
girlfriend config --set-name ben --set-mood hacker --set-theme gamer
girlfriend config --set-voice-profile cute --set-voice-rate 145 --set-voice-pitch 72
girlfriend notify-test
```

## Configuration

The config file lives at:

```text
~/.girlfriend/config.json
```

Default example:

```json
{
  "bedtime_hour": 23,
  "enable_voice": false,
  "notification_frequency_minutes": 180,
  "preferred_mood": "caring",
  "theme": "wholesome",
  "typing_animation": true,
  "voice_pitch": 68,
  "voice_profile": "cute",
  "voice_rate": 150,
  "username": ""
}
```

## Notifications and Voice

- `notify-send` is optional and used for desktop notifications
- `espeak` or `espeak-ng` is optional and used for voice output
- both features fail gracefully if the command is unavailable

Recommended softer voice setup:

```bash
girlfriend config --enable-voice --set-voice-profile cute --set-voice-rate 145 --set-voice-pitch 72
girlfriend speak
```

## Themes

Available themes:

- `anime`
- `wholesome`
- `hacker`
- `goth`
- `gamer`
- `yandere`
- `cozy`

## Future AI Roadmap

The app is currently offline-first and rule-based. The module boundaries already make room for:

- Ollama local model integration
- Gemini API integration
- OpenAI API integration
- plugin-style personality packs
- scheduled reminder daemon mode

## Development

Run tests:

```bash
python3 -m unittest discover -s tests -v
```

Build wheel and source distribution:

```bash
python3 -m build
```

## Debian Packaging Notes

This repository includes Debian packaging metadata in `debian/`. To create a `.deb`:

```bash
sudo apt install -y build-essential devscripts debhelper-compat dh-python python3-all python3-setuptools python3-rich
debuild -us -uc -b
```

The resulting package is installable with:

```bash
sudo dpkg -i ../girlfriend_1.0.0-1_all.deb
sudo apt -f install
```

## Screenshots

Add screenshots to `screenshots/` and reference them here for releases:

- `screenshots/default.png`
- `screenshots/monitor.png`
- `screenshots/chat.png`

## Contributing

1. Fork the repo
2. Create a branch
3. Make your changes
4. Run tests
5. Open a pull request

Please keep contributions funny, kind, Linux-native, and non-explicit.

## License

MIT License. See [LICENSE](LICENSE).
