Imago/docs/SHAARLI-INTEGRATION.md

Shaarli Integration

The Imago Hub can be integrated directly with Shaarli (the PHP-based bookmark manager) to automatically process and enhance your bookmarks when you save them.

Overview

When you save a new bookmark in Shaarli, you might want to:

1. Automatically fetch the URL and summarize the page content using AI
2. Generate tags automatically based on the page content
3. Archive full-page screenshots to Imago for offline reading

This repository includes a reference implementation for this architecture using the Imago Python SDK.

Components

The integration/shaarli/ directory contains:

• hub_plugin.py — A Python class (ShaarliHubPlugin) that acts as a middleware interacting with the imago-client SDK.
• config_example.env — Example environment variable file for the plugin layer.
• example_usage.py — A standalone script demonstrating how the plugin summarizes URLs.

Setup Instructions

1. Install the SDK: The script requires the Imago Python SDK.

   cd sdk
   pip install imago-client
   

2. Configure Environment variables: Copy integration/shaarli/config_example.env to .env and fill it with your Imago Admin API Key or a specific Client API Key provisioned with ai:use and images:write scopes.

3. Deploy as a microservice or hook: Since Shaarli is written in PHP, to hook python scripts into Shaarli you have a few options:

   • Option A (WebHook): Deploy a small FastAPI/Flask wrapper around hub_plugin.py and configure Shaarli's WebHook plugin to POST data to your wrapper whenever a new link is created.
   • Option B (Cron/Background Job): Have a Python daemon watch the Shaarli RSS/Atom feed or poll its REST API, grab new entries, process them via hub_plugin.py, and PATCH the bookmark back in Shaarli with the newly generated Description and Tags using the Shaarli REST API.

Example Flow (Option B)

1. You save https://github.com/imago-project/imago to Shaarli.
2. The Python daemon detects the new bookmark via Shaarli's API.
3. The daemon calls plugin.process_bookmark(url).
4. Imago leverages OpenRouter/Gemini to fetch and summarize the GitHub page.
5. Imago returns {"title": "...", "description": "...", "suggested_tags": ["github", "python", "ai"]}.
6. The daemon PATCHes the Shaarli API to enrich the bookmark.