Skip to content
arrahman13Public

About

FeedWatch — an OpenMinion 0.1 SDK agent that watches public RSS/Atom feeds and emits validated Markdown digests of only the new items, with program-side guardrails against fabricated content. Built for Cortensor Hackathon #5 on DoraHacks.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

4 Commits

Folders and files

Repository files navigation

FeedWatch — a release & news monitoring digest agent

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.

What it does

  1. Fetches — in a first agent turn, the agent itself calls the OpenMinion tool fetch_new_items once 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.
  2. Reasons — in a second turn of the same session, an Agent with a Pydantic output_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 (see enforce_digest_invariants in feedwatch.py): whether anything is new, the item count in the headline, and that real items are highlighted.
  3. 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.

How the OpenMinion SDK is used

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 with instructions and a turn timeout_seconds.
  • Tools — feed fetching is a decorated tool (@tool(min_scope="READ_ONLY", idempotent=True)). It is also listed in forced_tools for the fetch turn, and the program verifies stats["tool_calls"] > 0 afterwards: 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 raises AgentOutputValidationError, which main() handles explicitly; provider failures raise ProviderError. 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 its session_id, thread_id, and run_state as 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.

Setup

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 check

Tuning for slow local models (learned the hard way — see NOTES.md)

The 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_seconds defaults to 60s; a single prompt-processing pass on a slow CPU can take longer. We use 900.
  • 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-chat

No code changes are needed — feedwatch.py just uses the configured feedwatch agent.

Run

# 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-state

Output: 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.

Demo

A step-by-step storyboard for the 1–5 minute demo video is in demo-script.md.

Project layout

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)

License

MIT — see LICENSE. FeedWatch's own code is MIT; OpenMinion is Apache-2.0 and remains under its own license.

About

FeedWatch — an OpenMinion 0.1 SDK agent that watches public RSS/Atom feeds and emits validated Markdown digests of only the new items, with program-side guardrails against fabricated content. Built for Cortensor Hackathon #5 on DoraHacks.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages