agentseek-schedule-sqlalchemy is an agentseek contrib package that exposes a Bub plugin for
persisting APScheduler jobs in a SQLAlchemy-backed store.
| Field | Value |
|---|---|
| Distribution | agentseek-schedule-sqlalchemy |
| Python package | agentseek_schedule_sqlalchemy |
| Bub entry point | schedule |
| Config section / surface | schedule |
| Root install path | uv sync |
| Test target | make test |
It targets the Bub runtime shape used by both plain Bub and the agentseek distribution, where:
- scheduled jobs must survive process restarts
- scheduling must work in
bub chat - the same scheduler may also be started by a gateway channel at runtime
The package exposes the Bub plugin entry point schedule and uses BackgroundScheduler, so
scheduler startup is not tied to a specific async event loop or to the schedule channel being
enabled.
The root agentseek workspace already includes this package as a workspace dependency. From the repository root, the normal sync is enough:
uv syncInstall from the monorepo package directory when you are adding this plugin to another local project:
uv add ./contrib/agentseek-schedule-sqlalchemyInstall directly from GitHub:
uv pip install "git+https://github.com/ob-labs/agentseek.git#subdirectory=contrib/agentseek-schedule-sqlalchemy"When vendoring this package into another workspace, declare both the dependency and the source:
[project]
dependencies = [
"agentseek-schedule-sqlalchemy",
]
[tool.uv.sources]
agentseek-schedule-sqlalchemy = { workspace = true }
[tool.uv.workspace]
members = [
"contrib/agentseek-schedule-sqlalchemy",
]The runtime config surface follows Bub semantics: the plugin registers a Bub config section named
schedule, matching its Bub entry point. The package name stays agentseek-schedule-sqlalchemy
because it belongs to the agentseek distribution namespace.
uv run agentseek onboard can now collect this section interactively for agentseek-managed
setups. It writes schedule.url and schedule.tablename into config.yml.
config.yml example:
schedule:
url: sqlite+pysqlite:///./agentseek-schedule.db
tablename: apscheduler_jobsThe same fields can also come from environment variables:
| agentseek variable | Bub variable | Purpose |
|---|---|---|
AGENTSEEK_SCHEDULE_SQLALCHEMY_URL |
BUB_SCHEDULE_SQLALCHEMY_URL |
Primary SQLAlchemy database URL for APScheduler jobs. |
AGENTSEEK_TAPESTORE_SQLALCHEMY_URL |
BUB_TAPESTORE_SQLALCHEMY_URL |
Fallback database URL when the schedule-specific URL is unset. |
AGENTSEEK_SCHEDULE_SQLALCHEMY_TABLENAME |
BUB_SCHEDULE_SQLALCHEMY_TABLENAME |
Optional table name. Defaults to apscheduler_jobs. |
Resolution order:
- use the schedule-specific URL from environment or
.envwhen set - otherwise fall back to the shared tapestore SQLAlchemy URL from environment or
.env - otherwise use
config.ymlschedule.urlwhen present - otherwise scheduler creation may fail and the plugin will log a warning and stay disabled
Example:
export AGENTSEEK_SCHEDULE_SQLALCHEMY_URL=sqlite:////tmp/agentseek-schedule.sqliteWhen both prefixes are present for the same setting, the BUB_* value wins. This keeps the plugin compatible with plain Bub while matching agentseek's global alias behavior.
Use a dedicated schedule database:
export AGENTSEEK_SCHEDULE_SQLALCHEMY_URL=sqlite+pysqlite:///./agentseek-schedule.db
uv run agentseek chatOr reuse the same SQLAlchemy URL as a tape store plugin:
export AGENTSEEK_TAPESTORE_SQLALCHEMY_URL=sqlite+pysqlite:///./agentseek-runtime.db
uv run agentseek chatThe second form only controls the scheduler fallback URL. A separate tape store plugin is still responsible for tape persistence.
ScheduleImpl follows the standard bub-schedule runtime model: load_state() exposes the
scheduler in state, while the schedule lifecycle channel binds the live BubFramework, starts
the scheduler, and shuts it down when the channel stops. Scheduled reminders are async jobs that
deliver messages through the currently running framework.
If scheduler construction fails, the plugin does not crash the framework:
provide_channels()logs the same warning and returns noschedulechannel
Current tests cover these behaviors:
- SQLAlchemy job store round-trip persistence with SQLite
ScheduleImpl.load_state()exposes the injected scheduleronboard_config()can write theschedulesection- registered
scheduleconfig resolves fromconfig.yml - environment variables override
config.ymlfor registered settings - settings resolution from
AGENTSEEK_SCHEDULE_SQLALCHEMY_URL - compatibility with
BUB_SCHEDULE_SQLALCHEMY_URL - fallback from
AGENTSEEK_TAPESTORE_SQLALCHEMY_URL schedule.triggerexecutes both sync and async jobsschedule.triggerdoes not shift an interval job'snext_run_time- scheduled reminders deliver through the live schedule framework
From the repository root:
make testOr run only this package's tests:
uv run python -m pytest contrib/agentseek-schedule-sqlalchemy/src/tests- this package only provides scheduling infrastructure; actual reminder delivery still depends on the surrounding Bub runtime or agentseek distribution setup and enabled channels
- session scoping is based on the
session_idstored in job kwargs - persistence quality and locking semantics depend on the configured SQLAlchemy backend