Metadata-Version: 2.4
Name: srxy
Version: 1.6.5
Summary: Find files by what you mean — from the terminal or Python.
License-Expression: MIT
License-File: LICENSE
Requires-Dist: cryptography>=44.0
Requires-Dist: exifread>=3.5
Requires-Dist: jellyfish>=1.2
Requires-Dist: mutagen>=1.48
Requires-Dist: openpyxl>=3.1
Requires-Dist: pillow>=12.3
Requires-Dist: pillow-heif>=1.4
Requires-Dist: pypdf>=6.14
Requires-Dist: pytesseract>=0.3
Requires-Dist: pyside6>=6.6
Requires-Dist: python-docx>=1.2
Requires-Dist: python-pptx>=1.0
Requires-Dist: rapidfuzz>=3.14
Requires-Dist: textual>=3.0
Requires-Dist: wordfreq>=3.1
Requires-Dist: faster-whisper>=1.2 ; extra == 'semantic'
Requires-Dist: nvidia-cublas-cu12 ; (sys_platform == 'linux' and extra == 'semantic') or (sys_platform == 'win32' and extra == 'semantic')
Requires-Dist: rawpy>=0.27 ; extra == 'semantic'
Requires-Dist: sentence-transformers>=5.6 ; extra == 'semantic'
Requires-Dist: pywin32>=312 ; extra == 'windows'
Requires-Python: >=3.11
Provides-Extra: semantic
Provides-Extra: windows
Description-Content-Type: text/markdown

# Srxy

[![CI](https://github.com/illescasDaniel/srxy/actions/workflows/ci.yml/badge.svg)](https://github.com/illescasDaniel/srxy/actions/workflows/ci.yml)
[![version](https://img.shields.io/pypi/v/srxy)](https://pypi.org/project/srxy/)
[![PyPI](https://img.shields.io/badge/PyPI-srxy-3775A9?logo=pypi&logoColor=white)](https://pypi.org/project/srxy/)

**Find files by what you mean — terminal or Python.**

Fuzzy, phonetic, and semantic matching across filenames, documents, photos, audio, video, and OS tags. On a desktop session, **srxy opens a GUI by default**; use `--tui` for the terminal UI or `--cli` for scripts and pipes.

## Installation

Needs **Python 3.11+**. `uv tool install 'srxy[semantic]'` recommended; `pipx install 'srxy[semantic]'` also works; `pipx install srxy` for core-only in a venv. Windows: add `[windows]` for Explorer tags. macOS: system `python3` may be too old — [Installation](docs/installation.md#macos).

**Platform setup (ffmpeg, tesseract):** [docs/installation.md](docs/installation.md). Privacy / third-party notice: [docs/privacy.md](docs/privacy.md).

## Quick start

**GUI (default on a graphical session):**

```bash
srxy                          # empty query/path
srxy "registry" ./src         # pre-filled; auto-starts
```

<img src="docs/images/gui.png" alt="srxy GUI" width="550" />

Walkthrough: [docs/gui.md](docs/gui.md). Architecture: [docs/architecture.md](docs/architecture.md).

**Desktop installers (Linux + macOS):**

Two Linux AppImages from [GitHub Releases](https://github.com/illescasDaniel/srxy/releases/latest) (decompress the `.xz`, make executable, and run; no host `libfuse2`):

| Artifact | What you get |
|----------|----------------|
| `srxy-*-installer-*.AppImage.xz` | **Offline wizard** — full PySide UI; install / update / reinstall / uninstall |
| `srxy-*-installer-online-*.AppImage.xz` | **Online one-click** — slim Go bootstrap; opens your browser to a localhost page and installs from PyPI |

Default prefix: `~/Applications/srxy`. The online AppImage needs a network connection on first launch (downloads `uv`, managed Python, and srxy into `~/.cache/srxy/online-bootstrap/`); later runs reuse the cache. It vendors PATH / tesseract / ffmpeg automatically and enables smarter-search packages only when a GPU is detected — model weights download later when you use those features. No reinstall/uninstall UI on the online path (use the offline wizard or remove the prefix).

Two macOS `.dmg` installers from the same [GitHub Releases](https://github.com/illescasDaniel/srxy/releases/latest) page (open the DMG and double-click the app; default prefix `~/Applications/srxy`):

| Artifact | What you get |
|----------|----------------|
| `srxy-*-installer-*.dmg` | **Offline wizard** — full PySide UI; install / update / reinstall / uninstall |
| `srxy-*-installer-online-*.dmg` | **Online one-click** — slim Go bootstrap; localhost browser UI; installs from PyPI |

These macOS DMGs are currently **unsigned** (Gatekeeper may warn or block on first open); a signed and notarized release is coming soon. A Windows offline installer (`.exe`, Inno Setup) is also available from the same releases page (unsigned; SmartScreen may warn). PyPI / `uv tool install` remain the primary paths on every platform. Guide: [docs/installers.md](docs/installers.md). Privacy / third-party notice: [docs/privacy.md](docs/privacy.md).

<img src="docs/images/installer.png" alt="srxy offline desktop installer" width="400" />

<img src="docs/images/installer-online.png" alt="srxy online web installer" width="400" />

**TUI:**

```bash
srxy --tui
srxy --tui "registry" ./src
srxy --tui "transform" ./docs --ocr
```

<img src="docs/images/tui.svg" alt="srxy TUI" width="400" />

Live scan progress, sortable results, preview pane, option chips, clipboard copy. Full walkthrough: [docs/tui.md](docs/tui.md).

**Plain CLI:**

```bash
srxy "registry" ./src --cli
srxy "revenue" ./docs --json
srxy "dog at the beach" ~/Pictures --semantic-image --content-only
srxy "revenue" ./docs --semantic-all --content-only
```

Boolean queries (`|`, `&`), scope flags, format table: [docs/cli.md](docs/cli.md).

**Python:**

```python
from pathlib import Path
from srxy import magic_file_search, magic_search

magic_file_search(Path("./src"), "registry", threshold=0.3)
magic_search([{"name": "salad"}], "salat", fields=["name"])
```

API reference: [docs/python-api.md](docs/python-api.md) · [docs/api-reference.md](docs/api-reference.md).

## Documentation

| Guide | Contents |
|-------|----------|
| [Installation](docs/installation.md) | uv tool / pipx, macOS/Linux/Windows, ffmpeg, tesseract |
| [Desktop installers](docs/installers.md) | Linux AppImages + macOS DMGs (offline + online) |
| [TUI](docs/tui.md) | Layout, keybindings, clipboard, release checklist |
| [CLI reference](docs/cli.md) | Flags, formats, boolean queries, exit codes |
| [Power-ups](docs/power-ups.md) | OCR, semantic, CLIP, transcription, models |
| [Python API](docs/python-api.md) | `magic_file_search`, `search`, `Q`, match types |
| [API reference](docs/api-reference.md) | Generated signatures from `srxy.__all__` |
| [Development](docs/development.md) | Quality gate, `--full`, fixtures, pytest |

## Development

Requires [uv](https://docs.astral.sh/uv/).

```bash
uv sync --extra semantic
uv run task checks-fix
uv run task checks              # day-to-day
uv run task checks-full         # before release
uv run task checks-full-cpu     # + forced-CPU transcribe matrix
```

CI runs unit tests only (`unit` marker, excluding `semantic` and `transcribe`). Details: [docs/development.md](docs/development.md).

Try fixtures: `srxy "axolotl" ./tests/fixtures/file_search`

## License

MIT — see [LICENSE](LICENSE).
