bruno
2f2a5e9b4a
Introduce an admin portal (React + Nginx), WebSocket routing, and API versioning middleware with `/api/v1/` prefix deprecation. Add master API key authentication, new Prometheus metrics for AI token consumption and active WebSockets, and extend S3 config with a public endpoint URL. Update test paths and fixtures to align with the new routing structure.
46 lines
2.3 KiB
Markdown
46 lines
2.3 KiB
Markdown
# 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.
|
|
```bash
|
|
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.
|