First commit

README.md

@@ -0,0 +1,88 @@
+# 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
+
+```bash
+sudo pacman -S baloo6 kcoreaddons6 pkgconf gcc
+```
+
+### Fedora
+
+```bash
+sudo dnf install kf6-baloo-devel kf6-kcoreaddons-devel pkgconf-pkg-config gcc
+```
+
+### openSuSE
+
+```bash
+zypper install baloo6-6 kcoreaddons6-dev pkgconf gcc
+```
+
+### Ubuntu / Debian (Testing/Unstable)
+
+```bash
+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.
+
+```bash
+pip install .
+```
+
+## CLI Usage
+
+The command bagheerasearch will be available after installation.
+
+```bash
+# 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:
+
+```Python
+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.