learningcircuit--local-deep-research/docs/news-subscriptions.md

News Subscriptions Guide

This guide covers the News Subscription system for automated research monitoring and news tracking.

Table of Contents

• Overview
• Creating Subscriptions
• Managing Subscriptions
• Update Frequency
• Subscription History
• Scheduler
• Notifications
• API Reference

---

Overview

News Subscriptions allow you to:

• Monitor topics with automatic periodic research
• Track search queries as living news feeds
• Get notifications when new content is found
• Organize subscriptions into folders

Access subscriptions at: http://localhost:5000/news/subscriptions

Subscription Types

Type	Description	Use Case
Search	Recurring search query	"AI regulations news"
Topic	Topic monitoring with evolution tracking	"Machine Learning"

---

Creating Subscriptions

From the Web UI

1. Navigate to News → Subscriptions
2. Click New Subscription
3. Configure your subscription:

Basic Settings

Field	Description
Query/Topic	What to search for
Name	Friendly name (optional)
Frequency	How often to update
Folder	Organization folder (optional)

Research Settings

Field	Default	Description
Model Provider	OLLAMA	LLM provider to use
Model	(varies)	Specific model
Search Engine	(your default search tool)	Search engine to use
Iterations	3	Research depth
Questions per Iteration	5	Breadth per cycle
Strategy	source-based	Research approach

Submit Options

• Create & Run Now - Save and immediately execute
• Test Run - Test configuration without saving
• Create Subscription - Save for scheduled execution

From Research Results

When viewing research results, click Subscribe to create a subscription based on that query.

---

Managing Subscriptions

Dashboard Overview

The subscriptions dashboard shows:

Metric	Description
Total	All subscriptions
Active	Currently running
Paused	Temporarily stopped
Updates Today	Refreshes in last 24h

Subscription Actions

Action	Description
Run Now	Execute immediately
Pause	Stop scheduled updates
Resume	Restart paused subscription
Edit	Modify settings
View History	See past research runs
Delete	Remove subscription

Filtering & Search

• Search - Filter by name or query text
• Status - Show active, paused, or all
• Frequency - Filter by update interval
• Folder - Filter by organization folder

Folders

Organize subscriptions into folders:

1. Click Manage Folders
2. Create folders with names
3. Assign subscriptions to folders
4. Filter view by folder

---

Update Frequency

Preset Intervals

Frequency	Interval
Hourly	60 minutes
Every 3 hours	180 minutes
Every 6 hours	360 minutes
Every 12 hours	720 minutes
Daily	1440 minutes
Weekly	10080 minutes

Custom Intervals

Set any interval between 1 hour and 30 days (in minutes).

Jitter

A small random delay (up to 5 minutes) is added to prevent all subscriptions from running simultaneously.

---

Subscription History

View the research history for any subscription:

1. Click on a subscription
2. Select View History

History Details

Field	Description
Research Title	Query that was executed
Timestamp	When it ran
Status	Completed or failed
Duration	How long it took
Topics	Extracted topics

Click on any research run to view full results.

---

Scheduler

The scheduler runs subscriptions automatically in the background.

Scheduler Status

The status bar shows:

• Whether scheduler is running
• Number of active jobs
• Whether your subscriptions are tracked

Starting the Scheduler

The scheduler starts automatically when you log in. Your session remains active for 48 hours.

Manual Control

• Run Now - Execute any subscription immediately
• Pause - Stop a subscription temporarily
• Resume - Restart a paused subscription

Error Handling

If a subscription fails:

1. It retries with exponential backoff
2. After 10 consecutive failures, it's automatically disabled
3. You receive a notification about the error
4. You can manually resume it anytime

---

Notifications

Get notified when subscriptions update or encounter errors.

Notification Events

Event	Description
subscription_update	New content found
subscription_error	Update failed

Setup

Configure notifications in Settings → Notifications:

1. Add notification service URLs (Discord, Slack, Email, etc.)
2. Enable subscription notifications
3. Test your configuration

See NOTIFICATIONS.md for supported services.

---

API Reference

Subscription Endpoints

Endpoint	Method	Description
/news/api/subscriptions	GET	List all subscriptions
/news/api/subscriptions	POST	Create subscription
/news/api/subscriptions/<id>	GET	Get subscription details
/news/api/subscriptions/<id>	PUT	Update subscription
/news/api/subscriptions/<id>	DELETE	Delete subscription
/news/api/subscriptions/<id>/history	GET	Get subscription history

Folder Endpoints

Endpoint	Method	Description
/news/api/subscription/folders	GET	List folders
/news/api/subscription/folders	POST	Create folder

Scheduler Endpoints

Endpoint	Method	Description
/news/api/scheduler/status	GET	Get scheduler status
/news/api/scheduler/start	POST	Start scheduler

Example: Create Subscription

import requests

response = requests.post(
    "http://localhost:5000/news/api/subscriptions",
    json={
        "query": "AI safety news",
        "name": "AI Safety Updates",
        "refresh_minutes": 1440,  # Daily
        "model_provider": "ollama",
        "search_engine": "searxng",
        "iterations": 3
    },
    cookies={"session": your_session_cookie}
)

---

Troubleshooting

Subscription Not Updating

1. Check scheduler status (should be "Running")
2. Verify subscription is not paused
3. Check for errors in subscription history
4. Try "Run Now" to test manually

Too Many Updates

• Increase the update frequency (e.g., daily instead of hourly)
• Pause subscriptions you don't need actively

Missing Notifications

1. Verify notification service is configured
2. Test notification URL in settings
3. Check subscription notification events are enabled

Scheduler Not Starting

• Log out and log back in
• Check browser console for errors
• Verify server is running

---

See Also

• NOTIFICATIONS.md - Notification service setup
• Full Configuration Reference - All settings, defaults, and environment variables
• API Quickstart - API authentication
• Features - Feature overview