Bagheera Search Tool

Bagheera is an advanced search utility and library for the KDE Baloo indexing service. It provides a flexible Python interface to perform logical queries, recursive searches, and metadata retrieval, specifically optimized for KDE Frameworks 6 (KF6).

Features

• Modular Architecture: Use it as a standalone CLI tool or as a Python library (BagheeraSearcher).
• KF6 Native: Compiled against KF6Baloo and KF6CoreAddons using pkg-config for robust path detection.
• Natural Language Dates: Supports queries like MODIFIED YESTERDAY or MODIFIED LAST THREE WEEKS.
• Advanced Logic: Complex filtering with AND, OR, and parenthesis, plus image dimension checks (PORTRAIT, LANDSCAPE, SQUARE).
• Persistence: Automatically remembers the last used --sort order in user configuration.

Prerequisites

Before installing, ensure your system has the following KF6 development libraries and tools:

Arch Linux

sudo pacman -S baloo6 kcoreaddons6 pkgconf gcc

Fedora

sudo dnf install kf6-baloo-devel kf6-kcoreaddons-devel pkgconf-pkg-config gcc

openSuSE

zypper install baloo6-6 kcoreaddons6-dev pkgconf gcc

Ubuntu / Debian (Testing/Unstable)

sudo apt install libkf6baloo-dev libkf6coreaddons-dev pkg-config gcc

Installation

1. Clone the repository and ensure your C wrapper source (baloo_wrapper.c) is present in the root directory.

2. Install via pip: This will automatically trigger the compilation of the C wrapper and install Python dependencies like lmdb.

pip install .

CLI Usage

The command bagheerasearch will be available after installation.

# Search for images modified this week
bagheerasearch --type image "MODIFIED THIS WEEK"

# Recursive search in a specific directory excluding portraits
bagheerasearch -d ~/Pictures -r "nature" --exclude "PORTRAIT"

# Show file IDs and use Konsole-friendly output
bagheerasearch "vacation" -i -k

Library Usage

You can integrate Bagheera into your own projects:

from bagheera_search_lib import BagheeraSearcher

searcher = BagheeraSearcher()
results = searcher.search("MODIFIED TODAY", {"limit": 10}, {"recursive": None})

for item in results:
    print(f"Found: {item['path']}")

Configuration

User settings (like the last used sort order) are stored in: ~/.config/bagheerasearch/config.json

License

Copyright (C) 2026 by Ignacio Serantes.