Skip to content

[EMB-123] AI Feed #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
chandlerhuff wants to merge 1 commit into
base: main
Choose a base branch
from
Open

[EMB-123] AI Feed #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 14 additions & 5 deletions processing/subscriptions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Subscriptions
description: Browse synchronized FreshRSS subscriptions and tune source priority.
description: Browse FreshRSS subscriptions, tune source priority, and publish private AI Feeds.
---

<Frame caption="Subscriptions">
Expand All @@ -10,30 +10,39 @@ description: Browse synchronized FreshRSS subscriptions and tune source priority

## Purpose

Subscriptions exposes the feeds synchronized from FreshRSS and the per-source priority used when Processor chooses a primary article from a similarity group.
Subscriptions exposes the feeds synchronized from FreshRSS and the per-source priority used when Processor chooses a primary article from a similarity group. Each subscription can also publish a private Atom AI Feed.

## Prerequisites and permissions

An enabled FreshRSS server must have completed at least one synchronization. Authenticated users can inspect subscriptions; changing operational settings may require administrator access.
An enabled FreshRSS server must have completed at least one synchronization. Authenticated users can inspect subscriptions and configure their AI Feeds. An administrator must first configure the shared OpenCode provider, model, effort variant, prompt, and API credentials on **AI Feed Settings**.

## Normal workflow

1. Search by feed title or narrow the list by category.
2. Open a subscription to verify its upstream identity and recent activity.
3. Assign a priority from `0` through `1000` when one source should outrank another.
4. Run processing again for the new priority to affect future primary-article selection.
5. Click **Configure AI Feed** on a subscription.
6. Enable the feed, choose its lookback and similarity threshold, and optionally enable Exa retrieval.
7. Save the settings, then copy or open the signed Atom URL.

## Important controls and behavior

- Higher priority wins when otherwise similar articles compete to be the primary item.
- Priority does not change similarity scores, fetch order, or FreshRSS subscription state.
- Search and category filters affect the current view only.
- Subscription identity remains tied to the upstream FreshRSS record.
- The default AI Feed lookback is 48 hours. Processor enriches every item in that window during the normal processing cycle.
- Exa defaults to `200000` text characters, HTML tags, and full verbosity. You can tune text sections, highlights, summaries, cache age, crawl timeout, subpages, targets, and extra links per subscription.
- When Exa is disabled or unavailable, Processor summarizes the stored FreshRSS article body. It retries Exa on later cycles.
- Feed requests read stored summaries and content. They perform Qdrant similarity searches but never call Exa or OpenCode.
- Each entry contains the AI summary, up to ten same-server similar articles, optional sanitized Exa content, and sanitized original FreshRSS HTML.
- A settings change regenerates in-window articles during the next cycle. New items remain unpublished until OpenCode returns a summary.

## Failure states

A missing feed usually indicates it was not returned by the configured FreshRSS account or synchronization has not completed. A saved priority cannot repair unreachable feed content or missing item bodies.
A missing feed usually indicates it was not returned by the configured FreshRSS account or synchronization has not completed. A saved priority cannot repair unreachable feed content or missing item bodies. An empty AI Feed can also indicate missing global credentials, an unavailable model, or summaries still waiting for a retry.

## Operational notes

Use priority sparingly and document large differences. Excessive priority bias can consistently select a shorter or less complete article even when grouping itself is correct.
Use priority sparingly and document large differences. Excessive priority bias can consistently select a shorter or less complete article even when grouping itself is correct. Treat copied AI Feed URLs as credentials because their signatures grant read access.
2 changes: 2 additions & 0 deletions reference/environment-variables.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,8 @@ These names remain stable for compatibility even though the product name is Proc
| `NEXTAUTH_URL` | Canonical public application origin |
| `NEXTAUTH_SECRET` | High-entropy authentication secret |
| `GROUPED_FEED_SECRET` | Optional dedicated grouped-feed signing secret |
| `AI_FEED_SIGNING_SECRET` | Optional dedicated AI Feed signing secret; falls back to `NEXTAUTH_SECRET` |
| `AI_FEED_ENCRYPTION_KEY` | Optional base64-encoded 32-byte key for AI Feed credentials; otherwise Processor derives a scoped key from `NEXTAUTH_SECRET` |

Generate production secrets with a cryptographically secure secret manager. Never reuse the examples from `.env.example`.

Expand Down
7 changes: 7 additions & 0 deletions reference/http-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ description: Reference Processor's route handlers outside the GraphQL schema.
| varies | `/api/auth/[...nextauth]` | NextAuth sign-in, callback, session, and sign-out routes | Protocol-specific |
| `GET` | `/api/setup/check` | Reports whether initial setup is required | Public, minimal response |
| `GET` | `/api/feeds/grouped/{folderId}` | Signed grouped Atom feed | Valid signed feed URL |
| `GET` | `/api/feeds/ai/{settingId}` | Per-subscription AI Atom feed | Valid signed feed URL |
| `GET` | `/api/rss-processor/debug` | Live processing status as server-sent events | Authenticated administrator |
| `GET` | `/api/similarity-grouping/debug` | Folder grouping debug stream | Authenticated administrator |
| `POST` | `/api/websub/hub` | WebSub subscribe/unsubscribe hub operations | WebSub verification protocol and resource bounds |
Expand All @@ -21,6 +22,12 @@ Send JSON GraphQL requests to `/api/graphql` using the active NextAuth cookie. T

The grouped feed URL is generated by Processor and includes signed parameters. Consumers should use the URL exactly as copied; manually changing the folder, server, expiry, or signature invalidates the request. Responses use Atom XML and identify the generator as Processor.

## AI Atom feed

Generate the private URL from a subscription card. The route returns the newest 100 stored summaries by default. Set `limit` from `1` through `1000` when a reader needs a different page size. Disabled feeds return `404`, and a changed scope or signature returns `401`.

AI Feed requests do not call Exa or OpenCode. Processor prepares article snapshots, summaries, and optional Exa content during scheduled processing. Qdrant supplies the similar-article list when the feed is rendered.

## Server-sent events

Both debug endpoints return `Content-Type: text/event-stream`. Clients should:
Expand Down