Built with the OpenMinion 0.1 Python SDK for Cortensor Hackathon #5.
FeedWatch is a small monitoring agent that watches public RSS/Atom feeds — by default the GitHub release feeds of projects a builder depends on — and produces a short, structured Markdown digest of only what is new since the last run. Run it on a schedule (cron, CI, a loop) and it behaves like a quiet release assistant: new releases and stories are summarized once, then never repeated.
- Fetches — in a first agent turn, the agent itself calls the
OpenMinion tool
fetch_new_itemsonce per watched feed. The tool downloads and parses the feed with the Python standard library only, and de-duplicates items against a local state file (.feedwatch/state.json). If the turn ends with zero tool calls, the program refuses to continue: a digest written without fetched data would be fabricated. - Reasons — in a second turn of the same session, an
Agentwith a Pydanticoutput_type(Digest) turns the fetched items into a validated structured digest: a headline, an overview, and up to 8 highlights with category and one-sentence summaries. Program-side guardrails then enforce the facts that must never be wrong (seeenforce_digest_invariantsinfeedwatch.py): whether anything is new, the item count in the headline, and that real items are highlighted. - Reports — the program renders the digest to
digests/digest-<UTC timestamp>.md. Links in the output are copied from the fetched items by the program, never generated by the model, so they cannot be hallucinated. Only after the digest is written are the item ids committed to the state file, so a failed run does not silently drop items.
--max-items N bounds how many unseen items per feed one run digests,
so a large backlog drains over successive runs instead of producing one
huge digest. Once a feed's backlog is drained, the next run reports
"Nothing new since the last run" with an empty highlight list,
because every item is already in the state file — that repeat run is the
built-in sanity check.
Default watched feeds:
| Feed name | URL | Why |
|---|---|---|
openminion-releases |
https://github.com/OpenMinion/openminion/releases.atom |
the SDK this project is built on |
ollama-releases |
https://github.com/ollama/ollama/releases.atom |
the local model runtime used for the reference runs |
hn-frontpage |
https://news.ycombinator.com/rss |
general tech signal |
Any RSS 2.0 or Atom feed works; see --feed / --only below.
FeedWatch is a thin application around the SDK's public Python facade
(from openminion import Agent, tool):
- Agent execution — two
Agent.run()turns per digest (fetch, then summarize), configured withinstructionsand a turntimeout_seconds. - Tools — feed fetching is a decorated tool
(
@tool(min_scope="READ_ONLY", idempotent=True)). It is also listed inforced_toolsfor the fetch turn, and the program verifiesstats["tool_calls"] > 0afterwards: with a separate digest turn, a small model otherwise happily "summarizes" data it never fetched. Repeat calls within a run return the cached payload, which keeps the tool honestly idempotent. - Typed / structured output —
output_type=Digest(a Pydantic model) on the second turn. Invalid model output raisesAgentOutputValidationError, whichmain()handles explicitly; provider failures raiseProviderError. Both paths exit non-zero with the raw evidence. - Sessions — both turns share one session per run; each run starts a
fresh session (
feedwatch-<UTC timestamp>) instead of reusing one forever. Reused sessions hurt twice in testing: their growing context overflowed a local model's 4k window, and earlier no-tool answers taught the model to answer the fetch turn from "memory". Durable memory for this workflow is the state file, not chat history. Each run prints itssession_id,thread_id, andrun_stateas diagnostics. - Provider neutrality — no provider is named in the code. The model
comes entirely from OpenMinion's config (
openminion setup), so the same program runs against local Ollama, Cortensor Portal, OpenRouter, or any other preset without a code change.
See NOTES.md for the full Building Blocks Tested and What We Learned notes, including bugs and rough edges found.
Requirements: Python 3.11+ (tested on 3.12), and a model provider. The reference setup below uses local Ollama — no API key, no account, no cost. Any other OpenMinion provider works the same way.
# 1. Install the SDK (0.1.x) into a virtualenv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt # openminion==0.1.22
# 2. Install Ollama and pull a small tool-capable model
# (https://ollama.com/download), then:
ollama pull qwen2.5:1.5b
# 3. Configure OpenMinion once, project-locally
export OPENMINION_HOME="$PWD"
openminion setup --provider ollama --model qwen2.5:1.5b \
--agent feedwatch --no-chat
openminion doctor --check-turn # optional sanity checkThe defaults assume a fast hosted model. On a small local model —
especially on a throttled/shared CPU — adjust three things in
.openminion/agents.json:
- Provider request timeout:
providers.ollama.timeout_secondsdefaults to 60s; a single prompt-processing pass on a slow CPU can take longer. We use900. - Brain extras: turn off the auxiliary fact-extraction call
(
"brain": {"auto_fact_extraction": {"enabled": false}}) — a batch agent does not need it, and it costs a full extra model call per turn. - Model context window: Ollama's default 4096-token context is too
small for a two-turn session (we measured a 5,249-token request being
rejected). Create the local model with a larger window, e.g. a
Modelfile with
PARAMETER num_ctx 16384.
On a normal laptop or any hosted model these runs take seconds to a
minute; the reference runs in runs/ were made on a heavily throttled
shared VM (about 1.5 effective CPUs, ~30 tokens/s prompt processing) and
took 15–20 minutes each. The workflow is identical — only the wall clock
differs.
To use Cortensor Portal instead (optional; Portal access is limited and coordinated by the Cortensor team):
export CORTENSOR_API_KEY="..." # from the Cortensor Portal
export OPENMINION_HOME="$PWD"
openminion setup --provider cortensor-portal --model oss-20b \
--agent feedwatch --no-chatNo code changes are needed — feedwatch.py just uses the configured
feedwatch agent.
# Full run over the default feeds
python feedwatch.py
# Watch only the release feeds, at most 5 new items each
python feedwatch.py --only openminion-releases,ollama-releases --max-items 5
# Add your own feed (any RSS/Atom URL)
python feedwatch.py --feed my-project=https://github.com/OWNER/REPO/releases.atom
# Forget everything previously seen and start over
python feedwatch.py --reset-stateOutput: the digest is printed to stdout and saved to
digests/digest-<timestamp>.md. A sample produced by a real run is in
examples/sample-digest.md; raw run logs
are under runs/.
Exit codes: 0 success (including "nothing new"), 1 provider failure,
2 model output failed schema validation.
A step-by-step storyboard for the 1–5 minute demo video is in demo-script.md.
feedwatch.py the whole agent (fetch tool + workflow + renderer)
requirements.txt pinned SDK version
examples/sample-digest.md a real digest produced by a local run
runs/ raw stdout/stderr logs of the reference runs
NOTES.md Building Blocks Tested + What We Learned
demo-script.md demo video storyboard
.feedwatch/state.json runtime state (git-ignored, created on first run)
.openminion/ project-local OpenMinion config/state (git-ignored)
MIT — see LICENSE. FeedWatch's own code is MIT; OpenMinion is Apache-2.0 and remains under its own license.