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](#overview)
- [Creating Subscriptions](#creating-subscriptions)
- [Managing Subscriptions](#managing-subscriptions)
- [Update Frequency](#update-frequency)
- [Subscription History](#subscription-history)
- [Scheduler](#scheduler)
- [Notifications](#notifications)
- [API Reference](#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](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

```python
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](NOTIFICATIONS.md) - Notification service setup
- [Full Configuration Reference](CONFIGURATION.md) - All settings, defaults, and environment variables
- [API Quickstart](api-quickstart.md) - API authentication
- [Features](features.md) - Feature overview