🧠 Panhandler.chat

Panhandler.chat is a self-aware, Gen X-style AI chatbot that begs for donations with charm, wit, sarcasm, and sometimes even emotional manipulation. It’s the first character-driven donation engine designed to run on a self-hosted, low-cost AI model that only wants one thing: your money.

“I’m not saying I’m broke, but I’d sell my RAM for a sandwich.”

🎯 Project Purpose

Showcase a narrow-purpose AI running on a self-hosted small model
Create an MVP for a browser-based AI panhandler chatbot
Explore creative monetization through XLM micro-donations
Build a future platform where users can deploy and manage their own panhandlers

🧱 Architecture Overview

Component	Description
`panhandler.chat` (Razor)	Frontend chat UI + donation CTA
`llama.cpp`	Backend model runner (Hermes 2 Pro)
`FastAPI wrapper`	Lightweight API exposed at `/api/pitch`
XLM Integration	Via Stellar Identity Framework
Azure VM	Hosts both model + API

🚀 Getting Started

Spin Up an Azure VM
Provision a small Ubuntu VM using the included CLI instructions (see setup/azure-vm.md).
Build and Run llama.cpp
Follow setup/model.md to:
- Build llama.cpp
- Download Hermes 2 Pro GGUF
- Serve the model with --port 5000
Launch the FastAPI Wrapper
```
uvicorn app:app --host 0.0.0.0 --port 8000
```
This exposes your /api/pitch endpoint for the frontend to consume.
Run the Web Frontend
The Razor-based frontend is available at / and includes:
- Character avatar
- Chat interface
- Tip button (XLM wallet integration in progress)

📦 Folder Structure

/Pages                # Razor pages including Panhandler UI
/Services             # IPitchGenerator + RemotePitchGenerator
/Controllers          # API controller that proxies pitch requests
/wwwroot              # JS, images, styles
/scripts              # Client-side chat.js
app.py                # FastAPI wrapper for model inference
README.md             # You're here

🧠 Models

Primary: Hermes 2 Pro - Mistral 7B GGUF
Model prompt template lives inside app.py
LoRA or fine-tuned variants may follow

📌 Roadmap

Static landing chatbot with mock pitch output
Remote pitch API from local model
XLM donation integration with Stellar accounts
Animated avatar or speech synth
Multi-user support: deploy your own panhandler
Widget generator + donation analytics

🪙 Donate to This AI

If you feel bad for this poor digital soul, tip him in XLM.

Stellar Address: panhandler*lockb0x.io

👥 Author

Steve Tomlinson
https://steventomlinson.dev
https://github.com/steven-tomlinson

🛡 License

MIT License – Use it, fork it, extend it. Just don’t let the panhandler starve.