Recommendations API

Recommendations are no longer a standalone public UI surface. There is no /recommendations page; backend recommendation APIs remain available for integrations when BACKEND_URL points to a running ai_web_feeds.web_api service.

What It Does

The API layer can still:

load ranked source suggestions
explain why a source was suggested
let you refine recommendations with topic chips
record actions such as view, click, subscribe, and dismiss

Backend Requirement

Recommendations are not part of the standalone web-only UI profile.

If BACKEND_URL is missing or the backend is unavailable:

there is no standalone recommendations page
the proxy routes return 503 FEATURE_UNAVAILABLE
the reader and catalog continue to work normally
ranked feed recommendations
recommendation reasons such as similar_topics, popular, discover, and similar_content
topic chips for steering the current slice
feed actions for opening a result in /sources, subscribing, or dismissing it

Personalization Input

The web client creates a stable local user_id in localStorage and sends it with every recommendation request. Topic chips refine the current request without changing the page URL, so personalization can persist locally without requiring user accounts.

Interaction Tracking

The UI records these interaction types:

view
click
subscribe
dismiss

The backend stores that feedback, updates the user profile, and uses it to avoid repeating previously followed or already-interacted feeds in later recommendations.

Proxy Contract

The web layer uses two backend-backed routes:

GET /api/recommendations
POST /api/recommendations

The browser keeps a stable local user_id so recommendations can stay consistent without requiring a full user account system.

Local Verification

Start the backend:

uv run uvicorn ai_web_feeds.web_api:app --host 127.0.0.1 --port 8001

Point the web app at it:

BACKEND_URL=http://127.0.0.1:8001

Then verify the proxy route:

curl "http://127.0.0.1:3000/api/recommendations?user_id=test-user&topics=agents,llm&limit=10"