pobblebonk 0.0.1__tar.gz

pobblebonk-0.0.1/.gitignore

@@ -0,0 +1,9 @@
+_docs/
+_proc/
+.venv/
+__pycache__/
+.ipynb_checkpoints/
+*.egg-info/
+sidebar.yml
+.pytest_cache/
+.kosha/

pobblebonk-0.0.1/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.5
+Name: pobblebonk
+Version: 0.0.1
+Summary: the clock and the notebook for an agent: schedules, lists and notes on honker, in one file
+Project-URL: Repository, https://github.com/vedicreader/pobblebonk
+Project-URL: Documentation, https://vedicreader.github.io/pobblebonk/
+Author-email: Karthik <karthik.rajgopal@hotmail.com>
+License: Apache-2.0
+Keywords: acp,agents,cron,honker,nbdev,reminders,scheduler,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Requires-Dist: fastcore>=2.2.14
+Requires-Dist: honker>=0.5.0
+Description-Content-Type: text/markdown
+
+# pobblebonk
+
+
+<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
+
+> the clock and the notebook for an agent
+
+`pobblebonk` adds callbacks, durable lists, and per-reader notes to [honker](https://github.com/russellromney/honker). Schedules, queued work, list items, retries, and notes share one SQLite file.
+
+There is no scheduler daemon. Call [`Pob.tick()`](https://vedicreader.github.io/pobblebonk/core.html#pob.tick) from cron, launchd, or a systemd timer. Each tick asks honker for due fires and runs their callbacks.
+
+## Install
+
+``` sh
+uv add pobblebonk
+```
+
+Python 3.12 or later is required.
+
+## Schedule a callback
+
+Register a callback, add its schedule, then call `tick`. The callback return value becomes a note.
+
+``` python
+import time
+
+pob = Pob()
+beats = []
+
+@pob.on('heartbeat')
+def beat(fire):
+    beats.append(fire.fire_at)
+    return f'beat {len(beats)} at {fire.fire_at}'
+
+pob.add('heartbeat', every='1s')
+for _ in range(3):
+    time.sleep(1.05)
+    pob.tick()
+
+beats
+```
+
+`fire.fire_at` is the scheduled boundary, not the time the callback happened. The one-second gaps show that the cadence held.
+
+``` python
+[b-a for a, b in zip(beats, beats[1:])]
+```
+
+`drain` returns the notes a reader has not seen. Each reader has an independent cursor.
+
+``` python
+pob.drain('leela').attrgot('body')
+```
+
+``` python
+pob.drain('leela'), len(pob.drain('phone'))
+```
+
+## Run ordinary Python
+
+A callback is a Python function. It can call a library, write a file, or run a command.
+
+``` python
+import subprocess
+
+pob2 = Pob()
+
+@pob2.on('git roundup')
+def roundup(fire):
+    out = subprocess.run(['git', 'log', '--oneline', '--since=30 days ago'],
+                         capture_output=True, text=True).stdout.strip().splitlines()
+    return f'{len(out)} commits in the last 30 days'
+
+pob2.add('git roundup', cron='0 17 * * *')      # 5pm daily
+time.sleep(1.05)
+pob2.tick(at=int(time.time()) + 86400).ran[0].result
+```
+
+## Give a callback a durable list
+
+`push` adds an item to a named list. A schedule with `needs` runs only when that list is not empty. Its callback receives the open items as `fire.list`.
+
+The callback marks its items used when it returns. If it raises, the items remain open for the retry. A `key` makes repeated open items idempotent.
+
+``` python
+pob3 = Pob()
+
+@pob3.on('cart')
+def cart(fire):
+    return 'added: ' + ', '.join(i.text for i in fire.list)
+
+pob3.add('cart', cron='0 20 * * 3', needs='shopping')     # 8pm on Wednesdays
+pob3.push('shopping', 'yoghurt, the greek one', key='img_2201.heic')
+pob3.push('shopping', 'yoghurt, the greek one', key='img_2201.heic')   # the same photo twice
+pob3.push('shopping', 'oat milk')
+pob3.items('shopping').attrgot('text')
+```
+
+``` python
+time.sleep(1.05)
+got = pob3.tick(at=int(time.time()) + 7*86400).ran[0]
+got.status, got.result, got.used
+```
+
+When the list is empty, the next fire is `skipped`. It is not a callback failure and produces no note.
+
+``` python
+time.sleep(1.05)
+nxt = pob3.tick(at=int(time.time()) + 14*86400).ran[0]
+nxt.status, nxt.why
+```
+
+## Use a model callback
+
+A model is another callable dependency. The documentation build does not run this example because it needs a LiteRT model.
+
+``` python
+import rishi
+
+pob4 = Pob()
+
+@pob4.on('news')
+def digest(fire):
+    chat = rishi.Chat('litert-community/gemma-4-E2B-it-litert-lm')
+    topics = ', '.join(i.text for i in fire.list)
+    return str(chat(f'Name one thing worth reading about each of: {topics}. One line each.'))
+
+pob4.add('news', cron='0 7 * * *', needs='interests')
+pob4.push('interests', 'sanskrit grammar')
+pob4.push('interests', 'sqlite internals')
+pob4.tick()
+```
+
+## Operate schedules
+
+Use `pause`, `resume`, `update`, and `drop` to maintain schedules. `update` changes only the fields you pass. `drop` also unregisters the callback in the current process.
+
+``` python
+pob4.pause('news')
+pob4.update('news', cron='30 7 * * *', retries=5)
+pob4.resume('news')
+pob4.drop('news')
+```
+
+``` python
+# Queue due fires without running callbacks.
+queued = pob.tick(run=False)
+
+# Run queued fires separately, with a bounded batch.
+results = pob.work(worker='scheduler', limit=100)
+```
+
+## Failures and missed fires
+
+A fire retries with exponential backoff when its callback raises. The default attempt budget is three. Set `retries` on [`Pob`](https://vedicreader.github.io/pobblebonk/core.html#pob) or on one schedule. After the final attempt, the fire is dead-lettered and a note records the error.
+
+`catchup='once'` keeps the latest fire missed while the machine was off. This is the default. `catchup='all'` keeps every missed fire.
+
+Use `tick(run=False)` when scheduling and callback execution belong in separate processes. It queues due fires without running them. `work` claims and runs queued fires.
+
+``` python
+pob = Pob('~/.pobblebonk/pob.db', retries=3)
+pob.add('roundup', cron='0 17 * * *', catchup='once', retries=5)
+```
+
+## Run the tick
+
+The process that calls `tick` must register the callbacks first. A small script is enough.
+
+``` python
+# tick.py
+from pobblebonk.core import Pob
+
+pob = Pob('~/.pobblebonk/pob.db')
+
+@pob.on('cart')
+def cart(fire):
+    return 'added: ' + ', '.join(item.text for item in fire.list)
+
+if __name__ == '__main__':
+    print(pob.tick())
+```
+
+Run it once a minute. A tick with nothing due is one SQL call.
+
+``` cron
+* * * * * cd ~/myapp && uv run python tick.py
+```
+
+Use a launchd `StartInterval` of 60 on macOS or a systemd timer with `OnCalendar=minutely` on Linux.
+
+## Share an existing database
+
+Pass an open honker database to keep pobblebonk data beside another application.
+
+``` python
+import honker
+
+db = honker.open('app.db')
+pob = Pob(db=db)
+```
+
+## Develop
+
+``` sh
+uv sync --group dev
+uv run nbdev-export
+uv run nbdev-test
+uv run nbdev-clean
+```
+
+`nbs/00_core.ipynb` contains the implementation and tests. `nbs/index.ipynb` generates this README.

pobblebonk-0.0.1/README.md

@@ -0,0 +1,212 @@
+# pobblebonk
+
+
+<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
+
+> the clock and the notebook for an agent
+
+`pobblebonk` adds callbacks, durable lists, and per-reader notes to [honker](https://github.com/russellromney/honker). Schedules, queued work, list items, retries, and notes share one SQLite file.
+
+There is no scheduler daemon. Call [`Pob.tick()`](https://vedicreader.github.io/pobblebonk/core.html#pob.tick) from cron, launchd, or a systemd timer. Each tick asks honker for due fires and runs their callbacks.
+
+## Install
+
+``` sh
+uv add pobblebonk
+```
+
+Python 3.12 or later is required.
+
+## Schedule a callback
+
+Register a callback, add its schedule, then call `tick`. The callback return value becomes a note.
+
+``` python
+import time
+
+pob = Pob()
+beats = []
+
+@pob.on('heartbeat')
+def beat(fire):
+    beats.append(fire.fire_at)
+    return f'beat {len(beats)} at {fire.fire_at}'
+
+pob.add('heartbeat', every='1s')
+for _ in range(3):
+    time.sleep(1.05)
+    pob.tick()
+
+beats
+```
+
+`fire.fire_at` is the scheduled boundary, not the time the callback happened. The one-second gaps show that the cadence held.
+
+``` python
+[b-a for a, b in zip(beats, beats[1:])]
+```
+
+`drain` returns the notes a reader has not seen. Each reader has an independent cursor.
+
+``` python
+pob.drain('leela').attrgot('body')
+```
+
+``` python
+pob.drain('leela'), len(pob.drain('phone'))
+```
+
+## Run ordinary Python
+
+A callback is a Python function. It can call a library, write a file, or run a command.
+
+``` python
+import subprocess
+
+pob2 = Pob()
+
+@pob2.on('git roundup')
+def roundup(fire):
+    out = subprocess.run(['git', 'log', '--oneline', '--since=30 days ago'],
+                         capture_output=True, text=True).stdout.strip().splitlines()
+    return f'{len(out)} commits in the last 30 days'
+
+pob2.add('git roundup', cron='0 17 * * *')      # 5pm daily
+time.sleep(1.05)
+pob2.tick(at=int(time.time()) + 86400).ran[0].result
+```
+
+## Give a callback a durable list
+
+`push` adds an item to a named list. A schedule with `needs` runs only when that list is not empty. Its callback receives the open items as `fire.list`.
+
+The callback marks its items used when it returns. If it raises, the items remain open for the retry. A `key` makes repeated open items idempotent.
+
+``` python
+pob3 = Pob()
+
+@pob3.on('cart')
+def cart(fire):
+    return 'added: ' + ', '.join(i.text for i in fire.list)
+
+pob3.add('cart', cron='0 20 * * 3', needs='shopping')     # 8pm on Wednesdays
+pob3.push('shopping', 'yoghurt, the greek one', key='img_2201.heic')
+pob3.push('shopping', 'yoghurt, the greek one', key='img_2201.heic')   # the same photo twice
+pob3.push('shopping', 'oat milk')
+pob3.items('shopping').attrgot('text')
+```
+
+``` python
+time.sleep(1.05)
+got = pob3.tick(at=int(time.time()) + 7*86400).ran[0]
+got.status, got.result, got.used
+```
+
+When the list is empty, the next fire is `skipped`. It is not a callback failure and produces no note.
+
+``` python
+time.sleep(1.05)
+nxt = pob3.tick(at=int(time.time()) + 14*86400).ran[0]
+nxt.status, nxt.why
+```
+
+## Use a model callback
+
+A model is another callable dependency. The documentation build does not run this example because it needs a LiteRT model.
+
+``` python
+import rishi
+
+pob4 = Pob()
+
+@pob4.on('news')
+def digest(fire):
+    chat = rishi.Chat('litert-community/gemma-4-E2B-it-litert-lm')
+    topics = ', '.join(i.text for i in fire.list)
+    return str(chat(f'Name one thing worth reading about each of: {topics}. One line each.'))
+
+pob4.add('news', cron='0 7 * * *', needs='interests')
+pob4.push('interests', 'sanskrit grammar')
+pob4.push('interests', 'sqlite internals')
+pob4.tick()
+```
+
+## Operate schedules
+
+Use `pause`, `resume`, `update`, and `drop` to maintain schedules. `update` changes only the fields you pass. `drop` also unregisters the callback in the current process.
+
+``` python
+pob4.pause('news')
+pob4.update('news', cron='30 7 * * *', retries=5)
+pob4.resume('news')
+pob4.drop('news')
+```
+
+``` python
+# Queue due fires without running callbacks.
+queued = pob.tick(run=False)
+
+# Run queued fires separately, with a bounded batch.
+results = pob.work(worker='scheduler', limit=100)
+```
+
+## Failures and missed fires
+
+A fire retries with exponential backoff when its callback raises. The default attempt budget is three. Set `retries` on [`Pob`](https://vedicreader.github.io/pobblebonk/core.html#pob) or on one schedule. After the final attempt, the fire is dead-lettered and a note records the error.
+
+`catchup='once'` keeps the latest fire missed while the machine was off. This is the default. `catchup='all'` keeps every missed fire.
+
+Use `tick(run=False)` when scheduling and callback execution belong in separate processes. It queues due fires without running them. `work` claims and runs queued fires.
+
+``` python
+pob = Pob('~/.pobblebonk/pob.db', retries=3)
+pob.add('roundup', cron='0 17 * * *', catchup='once', retries=5)
+```
+
+## Run the tick
+
+The process that calls `tick` must register the callbacks first. A small script is enough.
+
+``` python
+# tick.py
+from pobblebonk.core import Pob
+
+pob = Pob('~/.pobblebonk/pob.db')
+
+@pob.on('cart')
+def cart(fire):
+    return 'added: ' + ', '.join(item.text for item in fire.list)
+
+if __name__ == '__main__':
+    print(pob.tick())
+```
+
+Run it once a minute. A tick with nothing due is one SQL call.
+
+``` cron
+* * * * * cd ~/myapp && uv run python tick.py
+```
+
+Use a launchd `StartInterval` of 60 on macOS or a systemd timer with `OnCalendar=minutely` on Linux.
+
+## Share an existing database
+
+Pass an open honker database to keep pobblebonk data beside another application.
+
+``` python
+import honker
+
+db = honker.open('app.db')
+pob = Pob(db=db)
+```
+
+## Develop
+
+``` sh
+uv sync --group dev
+uv run nbdev-export
+uv run nbdev-test
+uv run nbdev-clean
+```
+
+`nbs/00_core.ipynb` contains the implementation and tests. `nbs/index.ipynb` generates this README.

pobblebonk-0.0.1/pobblebonk/__init__.py

@@ -0,0 +1,2 @@
+__version__ = "0.0.1"
+from .core import *

pobblebonk-0.0.1/pobblebonk/_modidx.py

@@ -0,0 +1,37 @@
+# Autogenerated by nbdev
+
+d = { 'settings': { 'branch': 'main',
+                'doc_baseurl': '/pobblebonk',
+                'doc_host': 'https://vedicreader.github.io',
+                'git_url': 'https://github.com/vedicreader/pobblebonk',
+                'lib_path': 'pobblebonk'},
+  'syms': { 'pobblebonk.core': { 'pobblebonk.core.Pob': ('core.html#pob', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob.__init__': ('core.html#pob.__init__', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob.__repr__': ('core.html#pob.__repr__', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob._done': ('core.html#pob._done', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob._failed': ('core.html#pob._failed', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob._fire': ('core.html#pob._fire', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob._row': ('core.html#pob._row', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob._run': ('core.html#pob._run', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob.add': ('core.html#pob.add', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob.all': ('core.html#pob.all', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob.drain': ('core.html#pob.drain', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob.drop': ('core.html#pob.drop', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob.due': ('core.html#pob.due', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob.get': ('core.html#pob.get', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob.items': ('core.html#pob.items', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob.note': ('core.html#pob.note', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob.notes': ('core.html#pob.notes', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob.on': ('core.html#pob.on', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob.pause': ('core.html#pob.pause', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob.push': ('core.html#pob.push', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob.resume': ('core.html#pob.resume', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob.tick': ('core.html#pob.tick', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob.update': ('core.html#pob.update', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob.used': ('core.html#pob.used', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.Pob.work': ('core.html#pob.work', 'pobblebonk/core.py'),
+                                 'pobblebonk.core._note': ('core.html#_note', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.backoff': ('core.html#backoff', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.clip': ('core.html#clip', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.secs': ('core.html#secs', 'pobblebonk/core.py'),
+                                 'pobblebonk.core.superseded': ('core.html#superseded', 'pobblebonk/core.py')}}}

pobblebonk-0.0.1/pobblebonk/core.py

@@ -0,0 +1,306 @@
+"""schedules, the lists they read, and the notes they leave
+
+Docs: https://vedicreader.github.io/pobblebonk/core.html.md"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/00_core.ipynb.
+
+# %% auto #0
+__all__ = ['FIRES', 'NOTES', 'RETRIES', 'BASE', 'MAX_TEXT', 'CATCHUP', 'secs', 'backoff', 'clip', 'Pob', 'superseded']
+
+# %% ../nbs/00_core.ipynb #8b4162b7
+import json, re, time
+from pathlib import Path
+from tempfile import mkdtemp
+
+import honker
+from fastcore.all import AttrDict, L, first, ifnone, patch, dict2obj
+from honker import crontab, every_s
+
+# %% ../nbs/00_core.ipynb #2dc2cc67
+_DUR = re.compile(r'([\d.]+)\s*([smhdwMy])', re.I)
+_MULT = dict(s=1, m=60, h=3600, d=86400, w=604800, M=2629800, y=31557600)
+
+# %% ../nbs/00_core.ipynb #a807caa9
+def secs(every) -> int:
+    "Whole seconds from `'30m'`, `'6h'`, `'1w'`, `'1h30m'`, or a number."
+    try: return int(float(every))
+    except (TypeError, ValueError): pass
+    if not (ms := _DUR.findall(str(every))): raise ValueError(f'not a duration: {every!r}')
+    return int(sum(float(n) * _MULT[u.lower()] for n, u in ms))
+
+# %% ../nbs/00_core.ipynb #57b9ddaf
+FIRES = 'pob.fires'          # the honker queue every schedule fires into
+NOTES = 'pob.notes'          # the honker stream a person reads
+RETRIES = 5                  # attempts a fire gets before it is dead-lettered
+BASE = 30                    # seconds before the first retry; doubles per attempt
+
+# %% ../nbs/00_core.ipynb #6ecca23b
+def backoff(attempt:int,       # failures so far; 1 on the first
+            base:float=BASE,   # the first delay, in seconds
+            cap:float=3600,    # longest a retry ever waits
+            ) -> float:
+    'Doubling delay: 30s, 60s, 120s, 240s, capped. A bot wall clears on its own or it does not.'
+    return min(base * 2 ** max(0, attempt - 1), cap)
+
+# %% ../nbs/00_core.ipynb #755f5560
+MAX_TEXT = 20_000            # chars kept of a note body; an answer is a note, not a document
+def clip(s, mx:int=MAX_TEXT) -> str:
+    'Text short enough to store, saying what it dropped rather than losing it quietly.'
+    s = '' if s is None else str(s)
+    return s if len(s) <= mx else s[:mx] + f'\n... [{len(s)-mx} more chars]'
+
+# %% ../nbs/00_core.ipynb #25758930
+class Pob:
+    "A honker database, the one table honker has not got, and the callbacks a fire runs."
+    def __init__(self,
+                 path=None,          # the file; None makes a temporary one
+                 db=None,            # or a honker database something else already opened
+                 retries:int=RETRIES,# attempts a failing fire gets before it is dead-lettered
+                 base:float=BASE):   # seconds before the first retry; doubles per attempt
+        # honker watches `PRAGMA data_version` on a file, so `:memory:` is not an option
+        if db is None and path is None: path = Path(mkdtemp())/'pob.db'
+        self.db = db if db is not None else honker.open(str(path))
+        self.retries, self.base = max(1, int(retries)), float(base)
+        self.q, self.stream = self.db.queue(FIRES), self.db.stream(NOTES)
+        self.sched, self.runners = honker.Scheduler(self.db), {}
+        with self.db.transaction() as tx:
+            tx.execute('CREATE TABLE IF NOT EXISTS pob_items (id INTEGER PRIMARY KEY, topic TEXT, '
+                       'text TEXT, key TEXT, at REAL, used_at REAL, used_by TEXT)')
+            tx.execute('CREATE INDEX IF NOT EXISTS pob_items_open ON pob_items(topic, at) '
+                       'WHERE used_at IS NULL')
+            tx.execute('CREATE UNIQUE INDEX IF NOT EXISTS pob_items_key ON pob_items(topic, key) '
+                       'WHERE key IS NOT NULL AND used_at IS NULL')
+
+# %% ../nbs/00_core.ipynb #4a1865e6
+@patch
+def note(self:Pob, title:str, body:str='', **meta):
+    'Leave one note.'
+    self.stream.publish(dict(title=str(title), body=clip(body), **meta))
+
+def _note(r): return AttrDict(json.loads(r['payload']), offset=r['offset'])
+@patch
+def notes(self:Pob, limit:int=50) -> L:
+    'Every note, newest first, whatever any reader has seen.'
+    return L(self.db.query('SELECT offset, payload FROM _honker_stream WHERE topic=? '
+                           'ORDER BY offset DESC LIMIT ?', [NOTES, limit])).map(_note)
+
+@patch
+def drain(self:Pob, reader:str, limit:int=50) -> L:
+    'Every note this reader has not had. What a turn calls before it answers you.'
+    got = L(self.db.query('SELECT offset, payload FROM _honker_stream WHERE topic=? AND offset>? '
+                          'ORDER BY offset LIMIT ?',
+                          [NOTES, self.stream.get_offset(str(reader)), limit]))
+    if got: self.stream.save_offset(str(reader), got[-1]['offset'])
+    return got.map(_note)
+
+# %% ../nbs/00_core.ipynb #0396b45d138a
+@patch
+def due(self:Pob) -> int:
+    'Fires queued and not yet run.'
+    return self.db.query("SELECT count(*) n FROM _honker_live WHERE queue=? AND state='pending' AND run_at <= unixepoch()",
+                         [FIRES])[0]['n']
+@patch
+def all(self:Pob) -> L:
+    'Every schedule, with its payload parsed.'
+    return L(self.sched.list()).map(lambda r: AttrDict(r, payload=json.loads(r['payload'] or 'null')))
+
+@patch
+def __repr__(self:Pob):
+        return f'Pob({len(self.all())} schedules, {self.due()} due, {len(self.notes())} notes)'
+
+
+# %% ../nbs/00_core.ipynb #21d054f1
+CATCHUP = ('once', 'all')    # what to do with the fires missed while the machine was off
+@patch
+def add(self:Pob,
+        name:str,             # what you call it; unique, and what a note is titled with
+        cron:str=None,        # a five-field cron expression
+        every=None,           # or a duration: `'30m'`, `'1w'`, or seconds
+        needs:str=None,       # a list topic this cannot run without
+        catchup:str='once',   # `once` runs the latest missed fire, `all` runs every one
+        retries:int=None,     # attempts a failing fire gets; None -> the Pob's own
+        **payload             # anything the callback wants
+) -> AttrDict:
+    'Write down a standing instruction.'
+    if bool(cron) == bool(every): raise ValueError('a schedule needs one of `cron` or `every`')
+    if catchup not in CATCHUP: raise ValueError(f'catchup must be one of {CATCHUP}: {catchup!r}')
+    self.sched.add(name=str(name), queue=FIRES, payload=dict(
+        schedule=str(name), needs=needs, catchup=catchup, **payload),
+        schedule=crontab(cron) if cron else every_s(secs(every)),
+        max_attempts=max(1, int(ifnone(retries, self.retries))))
+    return self.get(name)
+
+@patch
+def on(self:Pob, name:str):
+    'Decorator naming the callback a fire of `name` runs.'
+    def _f(fn):
+        self.runners[str(name)] = fn
+        return fn
+    return _f
+
+@patch
+def get(self:Pob, name:str) -> AttrDict: return first(r for r in self.all() if r['name'] == str(name))
+
+@patch
+def pause(self:Pob, name:str) -> bool: return self.sched.pause(str(name))
+
+@patch
+def resume(self:Pob, name:str) -> bool: return self.sched.resume(str(name))
+
+@patch
+def drop(self:Pob, name:str) -> bool:
+    self.runners.pop(str(name), None)
+    return self.sched.remove(str(name))
+
+@patch
+def update(self:Pob,
+           name:str,          # schedule to change
+           cron:str=None,     # new cron expression
+           every=None,        # or a new duration
+           priority:int=None, # new queue priority
+           retries:int=None,  # new attempt budget
+           **payload          # payload fields to add or replace
+) -> AttrDict:
+    'Change an existing schedule without replacing fields that are not given.'
+    if cron is not None and every is not None: raise ValueError('a schedule update accepts only one of `cron` or `every`')
+    if 'catchup' in payload and payload['catchup'] not in CATCHUP:
+        raise ValueError(f'catchup must be one of {CATCHUP}: {payload["catchup"]!r}')
+    if (was := self.get(name)) is None: return None
+    changes = {}
+    if cron is not None: changes['schedule'] = crontab(cron)
+    elif every is not None: changes['schedule'] = every_s(secs(every))
+    if priority is not None: changes['priority'] = int(priority)
+    if retries is not None: changes['max_attempts'] = max(1, int(retries))
+    if payload: changes['payload'] = {**(was.payload or {}), **payload, 'schedule': str(name)}
+    self.sched.update(str(name), **changes)
+    return self.get(name)
+
+# %% ../nbs/00_core.ipynb #1014ad54
+@patch
+def push(self:Pob,
+         topic:str,      # which list
+         text:str,       # the line the callback reads
+         key:str=None,   # send the same thing twice and it stays one item
+         at:float=None
+) -> AttrDict:
+    'Add one item, or give back the open one that `key` already names.'
+    at = ifnone(at, time.time())
+    with self.db.transaction() as tx:
+        if key is not None and (was := tx.query(
+                'SELECT * FROM pob_items WHERE topic=? AND key=? AND used_at IS NULL',
+                [str(topic), key])): return AttrDict(was[0])
+        got = tx.query('INSERT INTO pob_items (topic, text, key, at) VALUES (?,?,?,?) RETURNING *',
+                       [str(topic), clip(text), key, at])
+    return AttrDict(got[0])
+
+@patch
+def items(self:Pob, topic:str, limit:int=200) -> L:
+    'The open items on `topic`, oldest first.'
+    return L(self.db.query('SELECT * FROM pob_items WHERE topic=? AND used_at IS NULL '
+                           'ORDER BY at LIMIT ?', [str(topic), limit])).map(AttrDict)
+
+# %% ../nbs/00_core.ipynb #f156da8b
+@patch
+def used(self:Pob, ids, by:str='', at:float=None) -> int:
+    'Mark items done, once the work that consumed them succeeded.'
+    if not (ids := L(ids)): return 0
+    qs = ','.join('?'*len(ids))
+    with self.db.transaction() as tx:
+        return len(tx.query(f'UPDATE pob_items SET used_at=?, used_by=? WHERE id IN ({qs}) '
+                            'AND used_at IS NULL RETURNING id',
+                            [ifnone(at, time.time()), str(by), *ids]))
+
+# %% ../nbs/00_core.ipynb #708046dc
+def superseded(fires, keep_latest) -> set:
+    'Older job IDs for schedules that keep only their latest missed fire.'
+    fires, keep_latest = L(fires), set(keep_latest)
+    return {
+        f['job_id']
+        for name in {f['name'] for f in fires} & keep_latest
+        for f in fires.filter(lambda f: f['name'] == name)[:-1]
+    }
+
+# %% ../nbs/00_core.ipynb #b5e1bce7
+@patch
+def tick(
+    self:Pob,
+    at:float=None,        # when this tick is happening; now when unset
+    worker:str='tick',    # the lease holder recorded on each job
+    run:bool=True,        # False queues the fires and runs none of them
+) -> AttrDict:
+    'Create due fires, apply catch-up policy, then run the remaining jobs.'
+    at = int(ifnone(at, time.time()))
+    with self.db.transaction() as tx: fires = L(json.loads(tx.query('SELECT honker_scheduler_tick(?) AS f',[at])[0]['f']))
+    keep_latest = {schedule.name for schedule in self.all() if schedule.payload.get('catchup', 'once') == 'once'}
+    dropped = {job_id for job_id in superseded(fires, keep_latest) if self.q.cancel(job_id)}
+    kept = fires.filter(lambda fire: fire['job_id'] not in dropped)
+    fire_times = {fire['job_id']: fire['fire_at'] for fire in kept}
+    return dict2obj(dict(fired=kept,cancelled=len(dropped),ran=self.work(worker, at, when=fire_times) if run else L()))
+
+# %% ../nbs/00_core.ipynb #65b5766a
+@patch
+def _row(self:Pob, job) -> AttrDict:
+    'fetch specific honker job'
+    return AttrDict(first(self.db.query('SELECT * FROM _honker_live WHERE id=?', [job.id])) or {})
+
+# %% ../nbs/00_core.ipynb #9e7d9518
+@patch
+def _failed(self:Pob, job, row, name:str, exc:Exception) -> AttrDict:
+    'Retry a failed callback while attempts remain, else dead-letter it.'
+    err = f'{type(exc).__name__}: {exc}'
+    left = max(0, int(row.get('max_attempts') or job.max_attempts or 1) - job.attempts)
+    if left:
+        delay = backoff(job.attempts, self.base)
+        if job.retry(int(delay),err): return AttrDict(name=name,status='retry',error=err,attempt=job.attempts,attempts_left=left,after=delay)
+    job.fail(err)
+    self.note(name, f'gave up after {job.attempts} tries. {err}', ref=job.id, dead=True)
+    return AttrDict(name=name, status='error', error=err, attempt=job.attempts)
+
+# %% ../nbs/00_core.ipynb #83ba6c2c
+@patch
+def _done(self:Pob, job, name:str, got, res) -> AttrDict:
+    'Store a successful callback result and finish its fire.'
+    self.q.save_result(job.id, res)
+    if got: self.used(got.attrgot('id'), by=name)
+    body = res if isinstance(res, str) else json.dumps(res, default=str)
+    self.note(name, body, ref=job.id, used=len(got))
+    job.ack()
+    return AttrDict(name=name, status='ok', result=res, used=len(got))
+
+# %% ../nbs/00_core.ipynb #b034d25c
+@patch
+def _fire(self:Pob, job, at:int, fire_at:int=None):
+    'Build the value passed to a fire callback.'
+    p, row = AttrDict(job.payload or {}), self._row(job)
+    got = self.items(p.needs) if p.get('needs') else L()
+    fire_at = ifnone(fire_at, row.get('run_at') or at)
+    return AttrDict(p, at=at, fire_at=fire_at, list=got, job=job.id), row
+
+# %% ../nbs/00_core.ipynb #df9981a3
+@patch
+def _run(self:Pob, job, at:int, fire_at:int=None) -> AttrDict:
+    'Run one claimed fire.'
+    p = AttrDict(job.payload or {})
+    name = p.get('schedule') or ''
+    if (fn := self.runners.get(name)) is None:
+        job.fail(err := f'no callback registered for {name!r}')
+        self.note(name, err, ref=job.id, dead=True)
+        return AttrDict(name=name, status='error', error=err)
+    fire, row = self._fire(job, at, fire_at)
+    got = fire.list
+    if fire.get('needs') and not got:
+        job.ack()
+        return AttrDict(name=name, status='skipped', why=f'the {fire.needs} list is empty')
+    try: res = fn(fire)
+    except Exception as e: return self._failed(job, row, name, e)
+    return self._done(job, name, got, res)
+
+# %% ../nbs/00_core.ipynb #f8d9c278
+@patch
+def work(self:Pob, worker:str='tick', at:float=None, limit:int=100, when:dict=None) -> L:
+    'Claim and run every fire that is due.'
+    at, when, out = int(ifnone(at, time.time())), when or {}, L()
+    while len(out) < limit:
+        if (job := self.q.claim_one(worker)) is None: break
+        out.append(self._run(job, at, when.get(job.id)))
+    return out

pobblebonk-0.0.1/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pobblebonk"
+dynamic = ["version"]
+description = "the clock and the notebook for an agent: schedules, lists and notes on honker, in one file"
+readme = "README.md"
+requires-python = ">=3.12"
+license = {text = "Apache-2.0"}
+authors = [{name = "Karthik", email = "karthik.rajgopal@hotmail.com"}]
+keywords = ['nbdev', 'sqlite', 'honker', 'cron', 'scheduler', 'reminders', 'agents', 'acp']
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "honker>=0.5.0",
+    "fastcore>=2.2.14",
+]
+
+[project.entry-points.nbdev]
+pobblebonk = "pobblebonk._modidx:d"
+
+[project.urls]
+Repository = "https://github.com/vedicreader/pobblebonk"
+Documentation = "https://vedicreader.github.io/pobblebonk/"
+
+[tool.nbdev]
+
+[tool.hatch.build.targets.wheel]
+packages = ["pobblebonk"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/pobblebonk", "/README.md", "/pyproject.toml"]
+
+[tool.hatch.version]
+path = "pobblebonk/__init__.py"
+
+[dependency-groups]
+dev = [
+    "nbdev>=3.3.12",
+    "notebook>=7.6.1",
+    "slopometer>=0.0.1",
+]