FreshRSS / FreshRSS/Extensions

OrcaRouter provider support for the LLM Classification extension

Open
#521 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
PHP
Stars
712
Forks
117
Avg merge
5h 10m
Merged PRs (30d)
9

Description

FreshRSS lets people run their own feed reader, and this repository is where the FreshRSS team maintains the official extensions, with automated tests and review. The LLM Classification extension stands out: it tags incoming articles on insert via any OpenAI-compatible API, constrained to answer with a strict `{"tags": [...]}` JSON structure, and it caches responses and reuses tags when an updated article's prompt hash is unchanged, so organizing large feed lists costs very few calls.

Because the extension is configured around an API base URL, a bearer-token API key, and a model name, an additional provider fits its current shape. I'm an engineer on the OrcaRouter team, and I'd like to propose OrcaRouter as an optional, documented provider here, giving FreshRSS admins a way to reach several models through one endpoint.

## Proposal

The specific ask is additive: recognize OrcaRouter as an optional provider for the LLM Classification extension, alongside the OpenAI, Ollama, and LocalAI setups it already documents. Nothing would replace or change existing providers, and no existing configuration would be affected.

OrcaRouter exposes an OpenAI-compatible API and uses standard API-key authentication, so it would slot into the extension's existing `api_url`, `api_key`, and `model` settings and its current `/chat/completions` request path, with no new authentication flow. Nothing is implemented or tested yet; this is a proposal to discuss and, if it seems worthwhile, to implement.

## Why it could matter for FreshRSS users

A few angles seem relevant for self-hosters running this extension:

- **One endpoint, several models.** Classification is steady, low-latency metadata work, and reaching different chat and reasoning models without reconfiguring the extension keeps setup simple.
- **Automatic routing and provider failover.** If the primary upstream is rate-limited or down, requests can fail over to another provider, which matters for a hook that fires on every incoming article.
- **Prompt caching and usage tracking.** Per-article classification is repetitive, so prompt caching cuts cost, and consolidated usage and budget visibility helps admins who share a FreshRSS instance with family or a small team.

## Ecosystem and disclosure

OrcaRouter is already listed by open-source projects including RAGFlow, Dify, and promptfoo; more examples are at https://www.orcarouter.ai/built-with.

One transparent note: OrcaRouter runs an optional open-source partner program in which approved OSS projects can receive a 5% revenue share from OrcaRouter usage attributed to their integration. Participation is not a prerequisite for this proposal, and we would be glad to follow any disclosure or governance rules the FreshRSS project has.

If this seems useful, I would welcome the maintainers' thoughts on where such a provider should be documented, and with your go-ahead I would be happy to open a PR.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by locating the LLM Classification extension's existing provider documentation and its /chat/completions entry point; compare the OpenAI, Ollama, and LocalAI configurations. Done means maintainers agree the optional OrcaRouter provider belongs in scope, its api_url, api_key, and model setup is documented, and automated tests cover the unchanged request contract.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
api, backend
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.