{"id":15009664,"url":"https://github.com/typicalhog/randevu-py","last_synced_at":"2026-02-19T13:02:57.866Z","repository":{"id":239786402,"uuid":"800702251","full_name":"TypicalHog/randevu-py","owner":"TypicalHog","description":"Universal Probabilistic Daily Reminder Coordination System for Anything","archived":false,"fork":false,"pushed_at":"2025-03-16T02:24:21.000Z","size":24,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-16T02:41:19.915Z","etag":null,"topics":["algorithms","blake3","coordination","cryptography","daily","datetime","deterministic","foss","hash","offline","probability","py","python","randevu","random","rdv","rdvt","reminders","rendezvous","universal"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/randevu","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TypicalHog.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-14T20:43:33.000Z","updated_at":"2025-03-16T01:50:44.000Z","dependencies_parsed_at":"2024-09-28T17:00:55.980Z","dependency_job_id":"a4f7de35-9a0d-4012-abe8-5c85ee7e6a04","html_url":"https://github.com/TypicalHog/randevu-py","commit_stats":null,"previous_names":["typicalhog/randevu-py"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TypicalHog%2Frandevu-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TypicalHog%2Frandevu-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TypicalHog%2Frandevu-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TypicalHog%2Frandevu-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TypicalHog","download_url":"https://codeload.github.com/TypicalHog/randevu-py/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244056427,"owners_count":20390720,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algorithms","blake3","coordination","cryptography","daily","datetime","deterministic","foss","hash","offline","probability","py","python","randevu","random","rdv","rdvt","reminders","rendezvous","universal"],"created_at":"2024-09-24T19:27:16.831Z","updated_at":"2025-10-19T07:51:16.606Z","avatar_url":"https://github.com/TypicalHog.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RANDEVU\n**Universal Probabilistic Daily Reminder Coordination System for Anything**  \n\n- UNIVERSAL - reminders for the same object are the same for everyone  \n- PROBABILISTIC - reminders are calculated using a simple probabilistic\nalgorithm based on powers of 2  \n- DAILY - reminders are following a daily schedule/interval (UTC)  \n- INTRADAY - infinite optional intraday reminder times (RDVT - added in version\n2.0 as an extension to the existing system)  \n- GENERIC - applicable to anything and everything, literally (where it makes\nsense, see use cases)  \n- FOSS - in the public domain (Unlicense or MIT or Apache-2.0)  \n- OFFLINE - no internet connection required  \n- PORTABLE - simple code, easy to port anywhere where blake3 is available  \n- DETERMINISTIC - easily computable and predictable for any object and any date  \n- PSEUDORANDOM - reminders are spaced randomly and uniformly  \n- ADJUSTABLE - user can decide how frequently (roughly) they'd like to see\nreminders for each object  \n\nhttps://github.com/TypicalHog/randevu (Rust - **REFERENCE IMPLEMENTATION**)  \nhttps://github.com/TypicalHog/randevu-ts (TypeScript)  \n**https://github.com/TypicalHog/randevu-py (Python)**  \nThe above implementations are available on Crates.io, PyPI, and npm as **randevu**.  \nFeel free to contribute, create an implementation in another (missing) language,\nor even an alternative one for 1 (or more) of the 3 languages I've already\ncreated a repository and crate/module/package for.  \n\n## EXAMPLE USAGE\n```python\nfrom datetime import datetime, timezone\nfrom randevu import rdv, rdvt\n\nobject = \"THE_SIMPSONS\"\ndate = datetime.now(timezone.utc)\nrdv_value = rdv(object, date)\nrdvt_value = rdvt(0, object, date)\n\nprint(f\"Object {object} has RDV{rdv_value} today with RDVT0 at {rdvt_value}\")\n\n```\n\n---\n\n**I'm aware of the fact that README.md is a confusing jungle of words, random**\n**thoughts, and ideas. (Will work on it)**  \nI kinda suck at explaining stuff and structuring text in an organized manner.\nI'm sorry about that. :/  \nI gave it my best, and I'll keep trying to improve it in the future.  \nThis whole document will probably be revamped entirely. Stuff will be explained\nbetter, irrelevant things, tangents, thoughts and rambles removed, etc.  \nI would also like to write something like a proper spec for the RANDEVU\nalgorithm/system.  \nI'm thinking about creating a FAQ section/document where I'll explain various\naspects of the system and anything else I'd like to clarify or expand on in more\ndetail.  \nAlso thinking about adding some visual analogies (infographics) with coin\ntossing and such which I believe have enormous potential in terms of making the\nsystem easier to explain, as well as understand.  \n\n---\n\n## KEY CONCEPTS\n- OBJECT - a string representing anything that is representable with a string of\ncharacters (a game, a movie, a person, a song, a place, a video, a topic,\na word, a book, a number, a brand, a post, an event, an item, a website, an app,\na quote, an action, a movement or **literally** anything else)  \n- DATE - a date (UTC) for which we want to calculate the RDV for  \n- RDV - a positive integer representing the level/significance/rarity of a\nreminder for a certain OBJECT on a specific DATE  \n\n**(New feature of version 2.0)**  \n- RDVT - one of an infinite number of random moments in a day (0-24h UTC) when\nan object has its reminders for that day, allows for infinite precision  \n- RANK - RDVT rank, ranked 0 (most significant) to infinity - RDVT0, RDVT1...  \n\n## RDV CALCULATION\n`RDV = number of leading zero bits in blake3::keyed_hash(key: DATE, data: OBJECT)`  \nNote: The previous version (1.0) used a different algorithm, so the RDV values\nbetween the two versions have changed and are completely un-correlated.  \nBy implementing this change, I've eliminated 2/3 blake3 hash calculations and\nimproved performance (not that it mattered).  \nBut now I can calculate about 10 million RDV values per second on my PC.  \nI have strong reasons to believe such major changes won't be happening in the\nfuture and that this is the final version of the algorithm.  \nIt was still a good time to do such a fundamental change to the algorithm, since\nRANDEVU had essentially no adoption apart from myself and a small community I'm\na part of.  \n\n## HOW IT WORKS AND POTENTIAL USE CASES\nImagine a system that assigns a special number (RDV) to every object each day.  \nThe number assigned to each object is different for each object and changes\ndaily.  \nThe number has a 50% chance to be 0, 25% chance to be 1, 12.5% to be 2, and so\non (each number being twice as rare).  \nI've based everything around base-2 (simplest numerical base after unary), it\nmakes everything fit together so perfectly (you'll probably see why when you\nlearn more about how the system works).  \nBy making each reminder level twice as rare - we can achive effectively\ninfinitely infrequent reminders, as well as daily ones, and a pretty good range\nof reminders of various frequencies in between.  \nIf an object has a reminder RDV4, that also implies RDV3, RDV2, RDV1 and RDV0.  \nUsers can then choose to set a threshold value for each object and if the RDV\nvalue for a specific object is greater than or equal to the threshold - the user\nmay decide to do something with that object.  \nFor example, one may decide to watch a certain video once its RDV value (RDV\nvalue for that specific video) hits their desired threshold.  \nThreshold allows one to decide how often they would like to be \"reminded of\" a\ncertain object.  \n0 -\u003e every day, 1 -\u003e every 2 days (on average - it's random), 2 -\u003e 4 days, 3 -\u003e\n8 days, and so on (allows for essentially infinite frequencies of reminders,\nthough ones above 10 happen quite rarely - 2^10 = 1024 days).  \nIf multiple people used this system to get reminded of the same things - they\nwould all get reminded of them on the same days and thus be able to coordinate\nmeetings/actions related to the objects in question.  \nThis could allow fans of a \"dead\" game (game with no or little players online)\nto all meet and play it on the same day, let's say once every 256 days.  \nPeople could re-watch their favorite movies or videos and discuss them with\nother fellow fans on the same days.  \nThis system can be applied to anything.  \nIt can be used to assign special appreciation/remembrance days to your favorite\nbooks, songs, artists, events, or (as I already said) - ANYTHING.  \nOne could have a huge list of objects they care about and never again risk\nforgetting any of them - since they will be reminded of them eventually (for\nexample - bookmarks).  \n\n## RDVT CALCULATION AND USE CASES\nRDVT is a newly added (version 2.0) feature of the RANDEVU system and an\noptional extension of the RDV algorithm.  \nWe calculate the hash the same way as for RDV, except we append a RANK integer\nto the DATE inside the key, separated by an '_'. And we don't count leading zero\nbits.  \nInstead, we iterate over the bits in the hash and add increments to the RDVT\ntime (which starts at 00:00h, midnight). For each 1 we add an increment, and do\nnothing if the bit is 0.  \nAn increment starts at 12h, and we divide it by half after processing each bit.  \nFor example, if the first 4 bits are 0110 - this will result in a time value of\n09:00h (0 * 12h + 1 * 6h + 1 * 3h + 0 * 1.5h...).  \nNote that there are 256 bits and we keep doing this until we reach 1 ns (or\nmillisecond/microsecond, depending on the implementation).  \nThis means we get a different uniform pseudorandom time (0-24h) for each RANK.  \nIf users find the daily RDV reminder too broad and would like a more specific\ntime for the reminder - they can calculate one or more RDVT times and choose\none.  \nSince RDVT0 is the most important/main time, users should choose the\nlowest-ranked RDVT that works for them - this increases the chances other people\nwill also choose the same RDVT time as them, thus increasing the chances of an\ninteraction.  \nLet's say a certain YouTube video has an RDV10 today. We could have a browser\nextension or a website that would schedule streams (like video premieres) for\nthat video at the first 10 RDVT times (RDVT0-9).  \nFans of that video could all come re-watch it live with others at one of the\nRDVT times, and perhaps chat about it in the live chat (assuming the feature\nexisted) while experiencing it together.  \nThis is just one super specific hypothetical use case I came up with.  \n\n---\n\n## OBJECT NAMING CONVENTION (non-exhaustive examples)\nOBJECT is a string (preferably uppercase A-Z, 0-9). No spaces allowed.  \nSpaces and any other characters should be replaced with a single underscore\n('_').  \nCharacters outside of this set should only be used for external identifiers that\nare case-sensitive or contain other symbols, for example, YOUTUBE video IDs.  \n\n```\nXONOTIC (all letters should be uppercase)\n\nSTAR_WARS (spaces and dashes in multi-word objects should be replaced with _)\n\nTHE_MATRIX_1999 (movies should have a year of release at the end)\n\nGRAND_THEFT_AUTO_5 (objects should be referenced by their full name, Roman\nnumerals should be replaced with Arabic ones)\n\nASAP_ROCKY ($ should be replaced with S, same for other similar instances)\n\nC_PLUS_PLUS (++ should be replaced with _PLUS_PLUS)\n\nC_SHARP (# should be replaced with _SHARP, in other contexts it could be _HASH\nor omitted)\n\nYEAR_2000 (years should have a YEAR_ prefix)\n\nFRIDAY (weekdays and months should not be abbreviated, same as all other\nobjects)\n\n2023-08-25 (dates should be in ISO 8601 format, YYYY-MM-DD)\n\nNO_MANS_SKY (apostrophe in MAN'S should be dropped)\n\nHARRY_POTTER_SMOKES_WEED_Cdfkq2Nmb3c (video ID should be appended to the video\ntitle, double underscore is fine if the ID starts with one, IDs are allowed to\nuse dashes and lowercase letters)\n\nGETTING_BANGED_BY_GREEN_BOOMERS_MINECRAFT_BETA_1_7_3_SOLO_SURVIVAL_NO_COMMENTARY_OJzsmWBQE3I\n(brackets, quotation marks, colons, and other punctuation should be dropped,\nperiods in version numbers like 1.7.3 should be replaced with _)\n\nNUMBER_69 (numbers should have a NUMBER_ prefix)\n\n```\n\n### WHY THIS VERY SPECIFIC AND STRICT CONVENTION THO?\n\n**TO MAKE SURE EVERYONE GETS THE SAME REMINDERS FOR THE SAME THINGS ON THE SAME**\n**DAYS.**  \n\nDue to how the algorithm works - even just a single character difference between\ntwo objects causes the system to generate completely different reminders for\neach.  \nFor example: WEED, weed, Weed, and W33D would all be treated as different and\nindependent objects with completely unrelated reminders.  \nOne can think of objects like passwords - the same password gets you the same\nreminders as everyone else using said password.  \nIf one wanted to get completely different reminders from other people for a\nspecific object - they could append extra characters to it.  \nHowever, this is not the focus of the system. The whole point is to help people\ncoordinate getting reminded about stuff at the same time as everyone else.  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypicalhog%2Frandevu-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftypicalhog%2Frandevu-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypicalhog%2Frandevu-py/lists"}