pearthink123/revive-companion

revive-companion is a Python library that decides when an AI companion should send a message to its user. Most chatbots either follow a fixed schedule, like "ping every two hours", or send something at random, which the author argues feels either rigid or pointless. This library replaces that logic with a probability engine designed to make the timing of outgoing messages feel more like the way a person thinks about a friend during the day. It works in three pieces. The first piece, based on a Poisson process, sets the moments at which the AI even considers reaching out, so the spacing between attempts looks naturally varied rather than clockwork. The second piece, drawn from information theory, asks whether sending a message right now would actually add anything new, and skips it if not. The third piece, Bayesian inference, tries to guess what the user is probably doing right now from the available signals, and looks up a utility number for that state. Chatting with someone else, busy, or sleeping all lead to staying quiet. Idle online or seemingly needing care lead to reaching out. The README spells out the core math. Each check computes a hit probability, 1 minus e raised to the power of negative lambda times t, where lambda is a longing rate. When a check does not fire, the rate creeps up; when the engine decides to send, it resets. Over a quiet night, the probability climbs from about 7 percent to 95 percent across the early hours. Using it is meant to be small. The main entry point is a class called PoissonLove. Each tick returns whether a message should be sent and a suggested prompt; the app calls record_send after sending and record_reply when the user replies. Adapters are included for OpenAI, Anthropic, and any HTTP backend such as Ollama, and the README shows the same pattern wired into Telegram, Discord, Slack, or WeChat bots. The package ships with a YAML config file, a Streamlit dashboard that plots the longing curve and decision log, demo scripts, and 124 tests. The README also has a long section about consent and safety, with built-in quiet hours, an anti-spam cooldown of at least one hour between messages, and explicit advice that users should opt in and be able to turn the feature off at any time.