Metadata-Version: 2.4
Name: xfriend-telegram
Version: 0.1.0
Summary: X/Friend on Telegram — chat with your AI girlfriend or boyfriend: text replies, pictures and voice notes.
Author: codysaudio
License-Expression: MIT
Keywords: telegram,bot,ai,companion,girlfriend,boyfriend,tts,voice
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: python-telegram-bot>=21.0
Requires-Dist: xfriend>=0.1.1
Requires-Dist: secretvoice>=0.1.0
Requires-Dist: PyYAML>=6.0

<div align="center">

# 💬 X/Friend on Telegram

### Chat with your **AI girlfriend or boyfriend** right in Telegram.

Text replies, **pictures**, and **voice notes** — every chat gets its own
isolated companion with her/his own memory, voice, and mood. Powered by the
[X/Friend framework](https://github.com/saudiodev/xfriend) and
[SecretVoice](https://github.com/saudiodev/secretvoice-sdk).

</div>

---

## What you get

Talk to Mia (or your own companion) like a late-night text. The model decides
when the moment calls for more than words:

- 💬 **text replies** — fast, streaming-free, natural
- 🖼️ **pictures** — when the image module is enabled, she/he can send photos
  (Wavespeed Qwen, edited from a fixed reference image, with LoRA styles)
- 🎧 **voice notes** — 29 SecretVoice voices to choose from, switched on the fly
- 🧠 **memory** — per-chat isolated: rolling scene summary, durable facts,
  `/new` to start fresh

## Commands

```
/voices            — the 29 voices she/he can speak in
/voice <id>        — switch voice, e.g. /voice whisper, /voice blaze
/new               — wipe this chat's memory and start over
/help              — this
```

## Setup

### 1. Get a bot token

Talk to [@BotFather](https://t.me/BotFather) → `/newbot` → pick a name →
copy the token.

### 2. Install & configure

```bash
pip install xfriend-telegram
```

Edit `xfriend.yaml` (persona, LLM provider, voice, image module) and `persona.md`
(your companion's personality). Export the keys:

```bash
export TELEGRAM_BOT_TOKEN="123456:ABC..."
export VENICE_INFERENCE_KEY="..."      # her brain (or XAI_API_KEY / LONGCAT_API_KEY)
export SECRETVOICE_API_KEY="..."       # her voice
export WAVESPEED_API_KEY="..."         # only if image.enabled: true
```

### 3. Run

```bash
xfriend-telegram
```

Message your bot and say hi. 💘

## Customizing

- **Your own companion** — rewrite `persona.md` and/or the `name` in
  `xfriend.yaml`. Want a him? Change the persona and `/voice blaze`.
- **Pictures** — set `image.enabled: true` and point `image.base_image` at a
  portrait of the companion; she/he then sends edits of that reference image.
- **LoRA styles** — add `image.loras` entries for themed looks, including
  adult styles.
- **Another LLM** — `llm.provider: grok` (or `longcat`, or `custom` with your
  own OpenAI-compatible `base_url`).

## How it works

Each Telegram chat maps to its own `X/Friend` instance
(`build_companion(config, companion_id=f"{name}-{chat_id}")`), so memories never
bleed between conversations. Incoming messages run the companion's turn engine
in a worker thread; the reply is split under Telegram's 4096-char limit, and any
media the companion produces (images / voice notes) is forwarded as photos or
voice messages. A per-chat lock serializes turns, so she never talks over
herself.

## Development

```bash
pip install -e .
python -m pytest
```

## Links

- [X/Friend framework](https://github.com/saudiodev/xfriend) — the engine
- [SecretVoice SDK](https://github.com/saudiodev/secretvoice-sdk) — the voices

## License

MIT
