pearthink123 / revive-companion

What is revive-companion?

revive-companion is a Python library that helps AI companions decide when and whether to reach out to users. Instead of sending messages on fixed schedules or randomly, it uses probability theory to model "longing" -- the engine rolls dice based on Poisson processes, infers what the user is doing via Bayesian inference, and only sends when the interaction is worth it. The core API is three lines: create an engine, tick it periodically, and send a message if the result says to. It ships with adapters for OpenAI, Anthropic, and any OpenAI-compatible API, plus a Streamlit dashboard to visualize the decision curves.

Why is it gaining traction?

The hook is the math. Developers tired of "engaged flag = send more" logic find the probabilistic approach refreshing. The engine actually infers hidden user states -- sleeping, busy, idle, needing care -- and adjusts behavior accordingly. Quiet hours, anti-spam cooldowns, and state-based utility thresholds are built in rather than bolted on. The README walks through the longing curve over an eight-hour period, showing probability climbing from 7% to 95% -- that visualization makes the behavior concrete.

Who should use this?

Build teams working on AI companions, chatbots, or proactive notification systems will find the timing logic useful. Health app developers could adapt the state inference for check-in timing. Game developers might use it for NPC engagement. It's less useful for simple bots that only respond to user input.

Verdict

The probabilistic framework is solid and the documentation is thorough for a 13-star project. With 124 tests and a working dashboard, the codebase shows care. At 0.800000011920929% credibility, this is a young project that needs real-world usage to prove out the models. Worth exploring if you need smart timing, but treat the default parameters as starting points rather than production-ready constants.