Metadata-Version: 2.4
Name: funes-core
Version: 0.1.0
Summary: Local, offline semantic image search powered by CLIP and sqlite-vector.
Author: Rodrigo Oliveira
Author-email: Rodrigo Oliveira <rodrigo18br@hotmail.com>
License-Expression: MIT
Requires-Dist: fastembed>=0.7.0
Requires-Dist: numpy>=1.24
Requires-Dist: pyqt6>=6.7
Requires-Dist: sqliteai-vector>=1.0.0
Requires-Python: >=3.9
Project-URL: Homepage, https://github.com/rodrigo18br/funes
Description-Content-Type: text/markdown

# Funes

> Nosotros, de un vistazo, percibimos tres copas en una mesa; Funes, todos los vástagos y racimos y frutos que comprende una parra. Sabía las formas de las nubes australes del amanecer del treinta de abril de mil ochocientos ochenta y dos y podía compararlas en el recuerdo con las vetas de un libro en pasta española que solo había mirado una vez y con las líneas de la espuma que un remo levantó en el Río Negro la víspera de la acción del Quebracho. Esos recuerdos no eran simples; cada imagen visual estaba ligada a sensaciones musculares, térmicas, etc. Podía reconstruir todos los sueños, todos los entresueños.

*Funes* is a large image explorer with focus on semantic search and image similarity done in a local, fast and accessible way to a large range of devices.

Users can import large collections of images which are indexed using vector embeddings. It's possible to either enter natural language queries to retrieve images that best match the query content, or get the most similar images from another one in the library.

No cloud storage, paying embedding models or GPU use is necessary. Everything runs locally, on CPU, in a scallable and fast way.

## Generating embeddings

Usually, embeddings are generated by using an API of some commercial model that charges for its access. Furthermore, there are concerns of privacy, if there's sensitive material being processed, and dependency of a external service that could go down at any moment.

There is the alternative of running a local model, which requires a GPU powerful enough for a decent model. This compromises the use of underpowered devices and introduces some concerns with energy consumption.

The solution used by Funes is fastembed (https://github.com/qdrant/fastembed/), "a lightweight, fast, Python library built for embedding generation". Fastembed supports the model CLIP (https://huggingface.co/docs/transformers/model_doc/clip), a multimodal vision and language model which generates embeddings with similarity scores optimized for semantic content.

## Vector storage and search

In order to avoid remote storage of embeddings, sqlite-vector (https://github.com/sqliteai/sqlite-vector) is used to store and retrieve the generated vectors. This also avoids the concerns with running local servers and managing docker containers.

## Installing

Install using `pip`:

```bash
pip install funes
```

## Python package

Funes can be used as a Python package by importing the search engine and storage classes:

```python
from funes import SearchEngine, SQLiteStore

with SQLiteStore("funes.db") as store:
    engine = SearchEngine(store)
    results = engine.search_text("a dog on a beach")
```

The command-line interface is installed separately as `funes-cli`:

```bash
funes-cli index ./images
funes-cli search "a dog on a beach"
funes-cli search --image ./cat.jpg
```

## Desktop interface

Launch the Qt interface with:

```bash
uv run funes
```

To point the interface at a specific SQLite database, pass the path:

```bash
uv run funes ./funes.db
```
