Daguerre's Hoard

In a video's detail, Export an interval creates a separate MP4 from start/end seconds or the ready player's position. CPU FFmpeg transcodes the first video and optional first audio track as H.264/AAC; originals remain unchanged. The receipt separates the requested interval from the measured output duration and offers playback and downloads of the MP4 and JSON receipt. Frame/container timing can differ; this is not lossless trimming or a multi-track editor. The existing optional FFmpeg is required. Closing the view does not cancel an export already started. UI, HTTP and videos_export_clip MCP use the same native operation.

The photo viewer pages through already indexed similar photos, twelve at a time, with names, folders, native relevance bands and index notes. The displayed total is the number ranked by the current index, not a count of confirmed matches. Load more keeps earlier pages on error and uses the engine's next offset. This does not start indexing, download a model or alter original images.

In Library and Search, Add selection to album groups the selected loaded photos in one action. Enter a new or suggested existing album name; matching ignores case and accents. The receipt shows the actual album name/ID, whether it was created, newly added relationships, total photos and unknown IDs. Existing members are not duplicated. Selection export and A/B comparison remain available. Photos are referenced, never copied or moved. This does not select unloaded search results or impose the export's 20-photo limit on albums (native maximum: 500 IDs per call). Errors keep the name/selection for retry; editing the name during a request keeps that draft while the receipt identifies the actual album.

In Search, leave the description blank to use the existing date, place, folder, camera and orientation filters together. This returns the native chronological listing without similarity scores, showing how many photos are displayed out of the filtered total (up to 50; refine filters when more remain). Editing criteria discards obsolete results and pending responses while keeping the form and A/B choices. Description searches keep their existing behavior. The existing HTTP search and photos_search MCP tool remain unchanged.

In a photo's rating and retouch panel, save its recipe exposure (−5 to +5 EV) or clear only that setting. Other recipe values and metadata remain. Saving a recipe does not render an image; the separate export control remains available.

In a photo's rating panel, Mark as rejected stores the native rating -1; Clear rejection sets it to 0 (unrated). Neither action deletes or moves the photo. Label/keyword drafts stay editable, and native save/sidecar receipts apply.

On narrow screens, the sidebar keeps compact navigation and a model-status indicator. Every destination retains its translated accessible name, hover help and current-page marker; the status indicator opens Settings. The photo workspace fits below the Studio header so the footer remains visible.

Compare photos in Library and Search opens an inline A/B panel over the currently loaded list. Select either photo by name/folder, swap A/B or open its existing detail viewer. Desktop shows both native previews side by side; mobile stacks them in the normal page scroll. Detail requests are independent and old responses never replace a newly selected photo. A selection outside the current filtered list asks for a new choice without showing unrelated metadata. Saved dates/source, dimensions, file size and available camera/exposure metadata remain attached to their photo. Previews do not promise original resolution or 1:1 inspection. No automatic quality ranking, original/sidecar/recipe edit or new API/MCP tool is added. Selection export and the individual viewer stay available; copilot receives A/B IDs/order and loaded metadata, and refresh preserves choices that remain available. Normal library caches, thumbnails and call logs keep their existing behavior.

The visual studio preserves Photos, Layers and Develop and incorporates the complete vector editor under /vector/. Both modules start OFF; discovery opens no engines and activation does not scan folders, recover prior jobs or attach old editor sessions. Common projects transfer a photo into an editable vector document, retain revisions, and export a PNG back into the photo library. See the studio manual for source builds, API/MCP operations, data layout and current verification limits. Text and vision use the configured Faustus global model; saved local model overrides remain readable but cannot select an inference fallback.

Projects also retain diagram figures: import a complete .vfigure, inspect its PNG at actual size or 2×, and download its source while modules are OFF. Explicitly activated Vector and Layers can create native raster copies, retaining the source document, revision and selected page/state alongside those copies.

The Windows x64 package includes all three web surfaces, assets and six native executables. Installation uses an external profile and explicit startup; see the manual for commands. Installed CPU checks preserve configuration/token and complete photo→vector→PNG; actual desktop save dialogues still require visual verification.

The photo lightbox also matches exposure and colour to a reference, creating PNG copies of the current photo or a series. UI, HTTP and MCP share the same operation and saved parameters; originals and retouch recipes stay intact.

The library, search results and albums can now export a photo selection as a standalone HTML gallery, numbered JPEG contact sheet and JSON manifest. Select up to 20 photos, name the gallery, then open or download the actual outputs. The UI uses the existing native photos_export capability; previews are up to 512 px and originals are unchanged.

Named after Louis Daguerre, whose 1839 daguerreotype was the first practical photograph.

A local photo library with indexing, editing, vector illustration and ranked search.

Español · Quick start · Connect to Faustus · MCP reference · Portfolio

Actual application, synthetic demo data: 87 generated images (gradients and simple shapes, not real photos) with EXIF dates, GPS for three cities, and planted duplicates.

Why

A language model can read a text file, but a folder of 20,000 photos is opaque to it: it cannot tell which one shows the whiteboard from March, where a trip was, or that three copies of the same picture are taking up space. Pasting images into a chat does not scale, and describing photos from their file names invites confident guesses.

Daguerre indexes your folders on your own machine (CLIP image embeddings through ONNX Runtime, no PyTorch, no cloud call), reads EXIF and GPS, reverse-geocodes offline, and finds exact and near duplicates. The model gets short, filtered, numbered results with stable ids and a relevance band (strong/medium/weak) on each one. A vision model can ask for a single contact-sheet image of the candidates and check ten photos for the price of one image before it claims anything; a text-only model never receives an image it did not ask for. Daguerre never modifies, moves or deletes an original file; that invariant is tested. The one file it may write next to a photo is an optional .xmp sidecar with your ratings and retouch recipe, off by default (see Ratings, retouch recipes and .xmp sidecars).

Related MCP server: Local Image Search (Japanese) MCP Server

Use cases

Eight scenarios, each walked in the browser and, for the agent ones, over real MCP stdio by a script that plays a small local model (docs/USE_CASES.md; what was found and fixed is in docs/USABILITY_REPORT.md):

• First run: add Pictures (a path pasted with Explorer's quotes works), download the image model from Settings while the bar counts the megabytes, and search "sunset over the sea".

• One photo by content and date: "do you still have the photo of the dog on the beach from last summer?" The model searches "dog on the beach" with a date range, gets text only, and says how sure it is.

• Free up space: exact copies keep the camera-roll original, and "Copy paths of the extra copies" leaves the keeper out; near duplicates are shown as "up to", to check group by group.

• Albums by the agent: "make an album 'Lisboa 2024' with the whole trip": filters alone (place="Lisbon", July 2024), paged with next_offset, cover the trip.

• With other tools: a vertical portrait for a CV that the assistant then copies with its own file tools, and the clapperboard and green-screen shots of a short-film shoot collected in one album.

• Memories and places: "on this day" with places, and Places grouped by country and city.

What is implemented

• Editable Compositor import: .comp directories containing a verified raster subset can become separate Daguerre Layers .dglayers pixel layers through craft_import_compositor. Includes a per-layer report, original-byte hashes, native save/reopen checks and PNG previews. Unsupported content blocks import before writing; groups, masks, adjustments and complex transforms remain gaps. Configuration, supported subset and limitations.

Shared models

Photo captions and query translation use the exact global model selected in Faustus through an owned composition of the unchanged HoardLink SDK. Each job pins endpoint, model and connection revision; unavailable or stale selection is an error. Daguerre never chooses a local fallback or loads a text/vision model. Saved legacy local URLs/model names remain readable for continuity. Other photo functions and vector editing work without a chat model. See the studio manual.

Historical screenshot of the shared-model settings. The current studio uses only the configured Faustus global service.

Connect it to Faustus

Daguerre is a plugin for Faustus, a local AI workspace, and declares itself with faustus-plugin.json. Start the app, then in Faustus open Connectors -> Nearby apps -> Add. Faustus finds it on 127.0.0.1:8814, reads the manifest from the app's working directory and launches the MCP adapter itself.

photos_export(ids=[...], title="Summer selection") turns up to 20 chosen photos into a portable HTML gallery with its previews embedded, a numbered contact sheet and manifest.json. Selection order and deliberate repeats are preserved; every preview/cell maps to a stable photo ID, original path and content hash. The files live under data/exports/; originals are read without modification. The same title, ordered selection, photo bytes and exported metadata reuse the same export. Missing/unreadable photos are listed in omitted, with complete=false. The tool returns text and file paths, so a text-only model can prepare the collection too. This is a preview gallery; full-resolution originals and a flipbook reader are not packaged.

It works with any MCP client over stdio:

{
  "mcpServers": {
    "daguerre": {
      "command": "C:/path/to/daguerres-hoard/.venv/Scripts/python.exe",
      "args": ["C:/path/to/daguerres-hoard/daguerre_hoard/mcp_server.py"],
      "env": { "DAGUERRE_URL": "http://127.0.0.1:8814" }
    }
  }
}

On Linux or macOS the interpreter is daguerres-hoard/.venv/bin/python.

Arguments, output shapes, error codes and limits: docs/MCP.md. The skill that tells the model when and how to use the tools: skills/find-photos/SKILL.md.

Actual application: "sunset over the sea" with the real CLIP model on the synthetic demo images.

The lightbox: preview of the original, EXIF, place, captions, albums and visually similar photos.

Ratings, retouch recipes and .xmp sidecars

Every photo can carry a rating (-1 rejected, 0-5 stars), a label, keywords and a retouch recipe: a small, non-destructive description of a develop. All of it lives in Daguerre's database and the photo is never changed. Set it in the lightbox (Rating and retouch), with PUT /api/photos/{id}/edits or with the photos_set_edits tool; photos_describe and photos_edits show it.

The lightbox's Recipe white balance fields edit stored temperature and tint. Save sends only changed settings; Clear removes only that setting. A missing setting is distinct from tint zero. These settings are saved for compatible RAW developers; Daguerre does not render them in its preview, and the Kelvin field does not measure the temperature of JPEG/TIFF pixels. Existing XMP writing preferences apply. Pending label, keyword and exposure drafts remain separate.

Writing is opt-in. Settings -> Write .xmp sidecars next to edited photos (off by default; an assistant cannot turn it on). With it on, every edit also writes IMG_0001.xmp next to IMG_0001.jpg (the RAW-developer convention; an existing IMG_0001.jpg.xmp is used instead if that is the file you have). The photo itself is never touched. An existing sidecar is merged, never replaced: it is parsed, only the properties above are updated in place, and every other namespace, field, list and unmapped develop setting stays as it was. The first time Daguerre changes a sidecar it did not write, it copies the original to data/xmp-backups/. A sidecar that is not valid XMP is left alone and the edit is kept in Daguerre with the error. Writes are atomic (temp file + rename).

Reading is always on. Each scan reads a new or changed sidecar (one stat per photo when nothing changed) and, the first time it sees a file with no sidecar, the XMP embedded in the JPEG/TIFF/PNG/WebP. The sidecar's rating, label and keywords win; its develop settings overlay the stored recipe as a starting point (for example crs:Exposure2012="+0.85" becomes exposure: 0.85). What Daguerre has no equivalent for (tone curves, HSL, sharpening, masks...) and any value outside its ranges is listed as imported, not applied and stays in the file. Develop settings embedded in a finished JPEG are already baked into its pixels, so they are only listed, never turned into a recipe. If the sidecar changed on disk, an edit or photos_edits reads it first, so a hand edit is not overwritten. Removing a sidecar keeps the edits.

XML from files is untrusted: documents with a DOCTYPE or entity declarations (entity expansion, external entities) are rejected before anything expands, and size, depth and node count are capped. No network access is involved.

Limits: Daguerre renders only the recipe's exposure (craft_develop_photo); the other settings are data for RAW developers. RAW formats (CR3, NEF, ARW, DNG...) are not indexed by Daguerre yet, so sidecars are used for the formats it does index. IMG_1.jpg and IMG_1.png in one folder share IMG_1.xmp, as in RAW developers. Comments in a merged sidecar are dropped and its whitespace is normalised. Extended XMP (more than 64 KB in a JPEG) is not read. Temperature is in Kelvin, as in RAW files; the relative scale used for JPEGs is reported as not applied.

Faustus assistant

Once the shared Hoard Link launcher is installed, the app shows the family's Faustus panel (a floating button). The conversation, the model and the tools live in Faustus; this app only tells the panel what is open.

• Context per view. The panel receives the page and the objects open in it, with real ids: a photo (file name only, not the path; taken date, place, size, caption cut to 240 characters, video link, and rating, label and up to 20 keywords from its edits), an album (name, photo count, creator, ids of its first 20 photos) and a video (name, duration, date, frame count, size). The open album also names the project. Creation forms (new) give no object.

• Unsaved fields. The panel asks for them with the daguerre:context-request window event. The forms photo-edits, photo-album-add, album-new and search answer with the fields typed so far and a dirty flag.

• Refresh. When the assistant finishes a turn the open view reloads in place (hoard:copilot-turn-end / window.hoardCopilot.onTurnEnd, merged into one reload). Fields you are typing keep your value; untouched ones follow the new data.

• Saving. The edit form sends only the fields you changed (label as text, keywords as a list) to PUT /api/photos/{id}/edits, which leaves rating, label, keywords and recipe alone when they are not sent; an explicit empty value clears one. Adding to an album by name keeps what it holds, and removing photos keeps the others. No endpoint changed.

• Tests. cd frontend && npm test (node --test copilot-context.test.mjs) and python -m pytest tests/test_xmp_sidecars.py.

Quick start

Requirements: Python 3.11 or newer and Node.js 22 (only to build the interface once). The image model is not bundled: Settings -> Image model downloads it (about 600 MB) when you ask; until then search works on colours only and says so.

Windows (PowerShell)

git clone https://github.com/Luissalet/DaguerresHoard.git
cd DaguerresHoard
.\scripts\start.ps1 -Demo      # first run: creates .venv, installs the lock, builds the UI, opens the browser

Or double-click Iniciar Daguerre.cmd (and Detener Daguerre.cmd to stop). More launcher options:

.\scripts\start.ps1              # your own library in data\
.\scripts\start.ps1 -Port 8820 -NoBrowser
.\scripts\stop.ps1

start.ps1 prefers Python 3.13 when it is installed in C:\Python313, reinstalls dependencies whenever requirements-lock.txt changes, starts the app hidden with the repository as working directory, waits for /api/health and opens the browser. Logs go to data\logs\. stop.ps1 stops the process listening on the port after confirming it is Daguerre.

The same steps by hand:

python -m venv .venv
.venv\Scripts\python -m pip install -r requirements-lock.txt
.venv\Scripts\python scripts/build_studio_assets.py
.venv\Scripts\python scripts/build_engines.py
.venv\Scripts\python daguerre_hoard/studio_native/durer/scripts/build_engine.py
.venv\Scripts\python -m daguerre_hoard --demo     # synthetic library in data-demo\
.venv\Scripts\python -m daguerre_hoard            # your own library, http://127.0.0.1:8814

Linux / macOS

git clone https://github.com/Luissalet/DaguerresHoard.git
cd DaguerresHoard
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-lock.txt
.venv/bin/python scripts/build_studio_assets.py
.venv/bin/python scripts/build_engines.py
.venv/bin/python daguerre_hoard/studio_native/durer/scripts/build_engine.py
.venv/bin/python -m daguerre_hoard --demo --no-browser   # synthetic library in data-demo/
curl http://127.0.0.1:8814/api/health                 # {"service":"daguerres-hoard",...}

Then open http://127.0.0.1:8814. Flags: --port, --data-dir (or DAGUERRE_DATA_DIR), --demo, --no-browser. Everything Daguerre writes lives in the data folder (data/ by default, data-demo/ with --demo): database, thumbnails, vectors, model cache, logs.

Architecture

FastAPI and SQLite (WAL) around a plain-Python engine, a React 19 + Vite interface, and a standalone MCP adapter that talks to the app over HTTP. Modules, data model, the indexing pipeline, threads and the duplicate index are described in docs/ARCHITECTURE.md.

flowchart LR
    UI["React UI"] -->|"HTTP (UI routes)"| API["FastAPI app<br/>127.0.0.1:8814"]
    AI["AI assistant<br/>(Faustus or any MCP client)"] -->|"MCP stdio"| MCP["mcp_server.py"]
    MCP -->|"HTTP /api/agent/* (audited)"| API
    API --> ENG["Library engine"]
    ENG --> DB[("SQLite (WAL)<br/>index, albums, audit")]
    ENG --> CLIP["CLIP ViT-B/32<br/>ONNX Runtime"]
    ENG -->|"read only"| PICS[/"Your photo folders"/]
    ENG --> HL["HoardLink"] -->|"loopback only"| LLM["Faustus global model"]

Near duplicates in the demo library: each planted downscaled copy is grouped with its original, keeper first.

Timeline: months with sample thumbnails; a month opens its photos.

Development

.venv/bin/python -m pytest -q            # local tests, no model downloads or GPU
.venv/bin/python -m pytest -q -m model   # 1 opt-in test with the real CLIP model (downloads it if missing)
.venv/bin/python scripts/build_studio_assets.py
.venv/bin/python scripts/build_engines.py
.venv/bin/python daguerre_hoard/studio_native/durer/scripts/build_engine.py # TypeScript strict

(On Windows: .venv\Scripts\python -m pytest -q.)

The default suite covers: originals untouched after indexing, duplicates and album work; incremental rescans; moved files keeping their id; corrupt files not stopping a scan; serialised concurrent scans; the data folder never indexed as photos; re-embedding after an embedder change; EXIF as cameras write it (sub-IFD, tuples, zeroed dates) and GPS signs; thumbnail orientation; every supported format including HEIC; the near-duplicate index against brute force on 8,000 hashes; union-find and the keeper rule; contact-sheet and photos_show size caps; fallback-embedder ranking and its determinism across processes; the vector store; reverse geocoding on a fixture, including parent cities from real GeoNames rows; filter validation, paging and an empty result naming the filter to relax; the HTTP guard, path traversal attempts and error shapes; the manifest; the MCP adapter spawned over stdio against a live app (tool list, annotations, contact-sheet image, photos_show, albums, errors, and the message when the app is down); and the shared model backend (overrides that never return the Faustus token, captions through a mocked server, a caption batch that yields to and postpones for a busy model, a broken backend.json, and query translation only on the UI route). The model test indexes the demo scenes with real CLIP and checks that four English descriptions find the right scene.

CI (.github/workflows/ci.yml) runs the suite on Ubuntu and Windows with Python 3.11, 3.12 and 3.13, builds the UI with Node 22, and drives start.ps1/stop.ps1 on Windows.

Privacy and security

• Binds to 127.0.0.1 only; the shared Hoard Link guard rejects another Host header (DNS rebinding; DAGUERRE_ALLOWED_HOSTS opens a LAN name or a tailnet), cross-site requests that are not top-level navigations and framing from another site, and the assistant's /api/agent/<tool> routes answer only to the bearer token in data/mcp-token. No CORS, no telemetry.

• The only internet requests are the ones you start in Settings: the CLIP model from Hugging Face and the GeoNames dataset. Captions and query translation use the configured Faustus family service; provider credentials stay there.

• Every assistant call is recorded under Assistant activity (tool, arguments, duration, result or error); the interface's own clicks use separate routes and are not mixed in.

• Originals are only read. The one file written outside data/ is the optional <photo name>.xmp sidecar, only while Write .xmp sidecars is on (off by default), merged and backed up as described above. Removing a folder in Settings forgets Daguerre's own data about it (index rows, thumbnails, album entries), never the files. The agent can add folders and albums but not remove anything.

• Place names come from GeoNames (CC BY 4.0) when the full dataset is downloaded.

Known limits and roadmap

• No file-system watcher: rescans are started by you, the agent or a new folder.

• Vector search is brute-force cosine: fine to about 200,000 photos on one machine; an ANN index can sit behind the same interface later.

• A near-duplicate group can chain different look-alike photos, which is why its space is shown as "up to"; a tighter grouping (bounded group diameter, a CLIP check) needs validating on real photos first.

• Byte-identical copies can still appear side by side in search results and albums.

• There is no first-run checklist yet: an amber banner and the Settings badge point to the image model download.

• A few reasons and country names still appear in English in the Spanish interface.

• CLIP relevance bands and near-duplicate thresholds were tuned on synthetic images; they need a check on large real libraries.

Design notes from the use-case walkthroughs: docs/USE_CASES.md, docs/USABILITY_REPORT.md.

License

MIT.

Incorporated image engines

Daguerre contains complete layered-image and development engines and desktop editors, built from detached source with own names and formats. The photo lightbox creates copies, develops them, exports results and opens the full editor. Thirty public MCP tools preserve all22 previous names; historical projects remain importable and originals untouched. See the engine guide for builds, formats, provenance and verified scope.

Native connections

Former MCP and Hub identities can use the incorporated cold compatibility adapters without the retired repositories. See native connections. Modules still require explicit activation.