HotPulse

A self-hosted AI news radar powered by Ollama.

Turn noisy headlines into useful daily briefings. HotPulse collects news from multiple sources, filters relevant stories, groups reports about the same event, and ranks coverage by source diversity, quality and freshness.

Run it locally with no paid AI API required. Read your briefings on the web or access them through RSS, a JSON API and an MCP server.

See it in action

Screenshots show built-in demo data. Companies and figures in the demo are fictional.

Built-in channels

Add your own channel through YAML configuration.

Features

• Local AI with a fallback. Use Ollama on your own machine without paid AI APIs. If the model is unavailable, keyword-based rules keep the pipeline working.
• Two-pass scoring. Each story receives two model evaluations using different generation settings. Their combined score must meet a source-tier threshold.
• Event grouping. Related reports are grouped using headline overlap, shared distinctive names, optional embeddings and a model-assisted tie-breaker.
• Source-aware ranking. Stories rank by distinct-source coverage, source quality, relevance and freshness. Repeated articles from one source do not count as independent coverage.
• Opportunity tracking. Extract deadlines, funding, eligibility and location, including whether Pakistani applicants can apply. Items identified as expired are excluded from picks.
• Ten languages. English, Urdu, Arabic, Hindi, Chinese, Spanish, French, Turkish, Indonesian and Bengali, with automatic right-to-left layouts where appropriate.
• Cached translations. Pre-translate selected stories into configured languages or translate other items on demand.
• Daily and weekly briefings. Rule-based selection with an AI-written introduction. A numeric consistency check rejects introductions containing numbers absent from the selected stories.
• Social drafts. Generate X and Threads drafts for selected stories.
• RSS, API and MCP. Channel feeds, briefing feeds, documented JSON endpoints and five MCP tools.
• Admin controls. Run the pipeline, inspect failing sources, add feeds, override picks, re-analyse items and copy social drafts.
• Resilient processing. Cache model responses, isolate feed failures and validate generated output.

Quick start

Requires Python 3.10+.

git clone https://github.com/hamza01055/hotpulse.git
cd hotpulse

python -m venv .venv

Activate the virtual environment:

# Linux / macOS
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

Install and configure:

pip install -e .

Copy .env.example to .env:

# Linux / macOS
cp .env.example .env

# Windows PowerShell
Copy-Item .env.example .env

Check which sources your network can reach, then start the site:

hotpulse sources --test
hotpulse serve

Open http://127.0.0.1:8000. HotPulse collects real news from every source a few seconds after it starts, then every 30 minutes while the server is running.

Windows: if hotpulse is blocked by Smart App Control ("An Application Control policy has blocked this file"), run the same commands as python -m hotpulse.cli serve, python -m hotpulse.cli sources --test, and so on.

Try it offline with sample data (optional)

hotpulse demo loads fictional stories so you can explore the site without a network. Remove them before going live with hotpulse demo --clear.

Enable local AI

1. Install Ollama.
2. Download a model:

ollama pull qwen2.5:3b

1. Set the matching model in .env:

OLLAMA_MODEL=qwen2.5:3b

1. Check your configuration:

hotpulse doctor

Larger alternatives include:

ollama pull qwen2.5:7b
ollama pull qwen2.5:14b

Start with the smaller model and increase the size if your machine has enough available memory. Requirements and processing speed vary with model quantization, context length, hardware and workload.

Other Ollama chat models may work if they reliably produce the required JSON output.

Optional embeddings

For embedding-assisted story grouping:

ollama pull nomic-embed-text

Set:

OLLAMA_EMBED_MODEL=nomic-embed-text

Docker

Copy .env.example to .env, then set a long random admin token:

ADMIN_TOKEN=replace-with-a-long-random-secret

Start the site and Ollama:

docker compose up -d

The first startup downloads the configured model and may take longer.

How it works

flowchart TD
    S["RSS, JSON and job APIs"] --> C["Collect and deduplicate"]
    C --> P["Filter irrelevant items"]
    P --> SC["Evaluate twice"]
    SC --> W["Generate structured summaries"]
    W --> G["Group related reports"]
    G --> H["Rank events"]
    H --> B["Daily and weekly briefings"]
    W --> T["Translate"]
    H --> O["Web, RSS, API, MCP and social drafts"]
    B --> O
    T --> O

Heat combines the tier weights of distinct sources, a score multiplier and a freshness decay with a 24-hour half-life.

Make it yours

Configuration lives in config/:

To add a Climate channel:

1. Copy config/channels/ai.yaml to config/channels/climate.yaml.
2. Update its rubric, categories, keywords and sources.
3. Add climate to the channel list in config/site.yaml.
4. Restart HotPulse.

Tuning

• Raise thresholds if too many weak stories are selected.
• Refine the rubric when valuable stories are missed.
• Use T1 for official sources, T2 for established reporting and T3 for aggregators.
• Inspect both scores and their explanations on the admin Items page.

API and MCP

Interactive API documentation: /api/docs

Available MCP tools:

• latest_news
• search_news
• hot_events
• daily_briefing
• open_opportunities

For a client supporting Streamable HTTP, configure:

http://127.0.0.1:8000/mcp

Connection steps depend on the MCP client and version.

Commands

hotpulse init
hotpulse run [--channel ai]
hotpulse serve [--host 0.0.0.0 --port 8000 --no-scheduler]
hotpulse demo [--ai | --clear]
hotpulse digest [--today] [--kind weekly] [--channel X]
hotpulse sources [--test]
hotpulse doctor

Public deployment

1. Set a long random ADMIN_TOKEN and your public SITE_URL in .env.
2. Deploy with Docker, or run hotpulse serve --host 0.0.0.0 behind an HTTPS reverse proxy such as Caddy or Nginx.
3. Size the host for both the application and your chosen model.

You can run Ollama on a separate machine and configure OLLAMA_URL accordingly. Keep that connection private or appropriately protected.

Reliability and limitations

• Two evaluations provide an additional filtering step; they are not independent fact-checks.
• Article content is marked as untrusted material in prompts. This is a mitigation, not a guarantee against prompt injection.
• Generated links are validated, and unsupported links are dropped.
• Model responses are cached to reduce repeated processing.
• Feed failures are isolated so other sources can continue.
• Summaries, translations and extracted eligibility may contain errors. Check the original source before applying for an opportunity.
• Local inference avoids sending article content to a paid model API, but collecting live feeds still requires network requests.

Development

pip install -e ".[dev]"
pytest -q

The test suite includes 60 automated tests, using fake feeds and a fake Ollama server without live network access.

The stack uses Python, FastAPI, SQLite, Jinja templates, CSS and JavaScript, with no frontend build step.

Support and feedback

Found a bug or have a feature idea? Open an issue.

If HotPulse is useful to you, consider giving the repository a ⭐.

Credits

Inspired by ideas from AIHOT, including dual scoring, event grouping and source-diversity ranking.

HotPulse is an independent Python rewrite with a different stack and feature set. No AIHOT code, prompts or branding are included; see NOTICE.

License

MIT License.