Metadata-Version: 2.4
Name: srxy
Version: 1.7.0
Summary: Find files by what you mean — from the terminal or Python.
Author: Daniel Illescas Romero
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.16.1
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: magika>=1.0.3
Requires-Dist: pywin32>=312 ; sys_platform == 'win32'
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: torch>=2.13 ; extra == 'semantic'
Requires-Dist: torchaudio>=2.11 ; extra == 'semantic'
Requires-Dist: torchvision>=0.28 ; extra == 'semantic'
Requires-Python: >=3.11
Provides-Extra: semantic
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+**. Prefer [uv](https://docs.astral.sh/uv/) (`pipx install …` is fine too).

### Desktop installers (preferred)

Grab the latest installers from [GitHub Releases](https://github.com/illescasDaniel/srxy/releases/latest) — AppImages, DMGs, and the Windows `.exe` are all there. You can also [buy the installers](https://www.daniel-ir.eu/shop/p/srxy) from the official site (includes a **signed** macOS build). Details: [docs/installers.md](docs/installers.md).

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

### Terminal install (PyPI release)

| Hardware | Command |
|----------|---------|
| **Linux + NVIDIA GPU** /<br>**macOS Apple Silicon** | `uv tool install 'srxy[semantic]'` |
| **Windows + NVIDIA GPU** | `uv tool install 'srxy[semantic]' --with torch --with torchvision --with torchaudio --index https://download.pytorch.org/whl/cu130` |
| **No GPU / core-only** | `uv tool install srxy` |

`[semantic]` adds smarter search (PyTorch, CLIP, Whisper) and is intended for machines with a GPU — CPU-only semantic is too slow for most users. On Windows, `pywin32` (Explorer tags) is included automatically. PyPI’s Windows torch is **CPU-only**, so the GPU line uses `--with`/`--index` to pull CUDA wheels. macOS system `python3` may be too old — [Installation](docs/installation.md#macos).

### Latest development version

Install the current `develop` branch as a standalone tool (same layout as PyPI, but built from git):

```bash
uv tool install "srxy @ git+https://github.com/illescasDaniel/srxy@develop"
uv tool install "srxy[semantic] @ git+https://github.com/illescasDaniel/srxy@develop"   # GPU
uv tool install --force "srxy @ git+https://github.com/illescasDaniel/srxy@develop"     # update in place
```

On **Windows + NVIDIA**, add the CUDA wheels (checkout `[tool.uv.sources]` does not apply to `uv tool install`):

```bash
uv tool install "srxy[semantic] @ git+https://github.com/illescasDaniel/srxy@develop" \
  --with torch --with torchvision --with torchaudio \
  --index https://download.pytorch.org/whl/cu130
```

**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
```

| macOS | Linux | Windows |
|:-----:|:-----:|:-------:|
| <img src="docs/images/gui-macos.png" alt="srxy GUI on macOS" width="280" /> | <img src="docs/images/gui-linux.png" alt="srxy GUI on Linux" width="280" /> | <img src="docs/images/gui-windows.png" alt="srxy GUI on Windows" width="280" /> |

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

**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 / macOS / Windows installers (free Releases + shop) |
| [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) | Sync tasks, quality gate, `--full`, fixtures, pytest |

## Development

Requires [uv](https://docs.astral.sh/uv/). First-time checkout setup uses the platform-aware sync script (stdlib-only — no project venv required):

```bash
uv run --no-project python scripts/dev/sync.py                     # dev env (default-groups = ["dev"])
uv run --no-project python scripts/dev/sync.py --group uploader    # dev + twine (PyPI upload)
uv run --no-project python scripts/dev/sync.py --no-default-groups # runtime only, no pytest/ruff
```

Wrappers: `./scripts/dev/sync.sh` (Unix) or `powershell -File .\scripts\dev\sync.ps1` (Windows).

Once `.venv` exists, thin Taskipy aliases also work:

```bash
uv run task sync-dev
uv run task sync-uploader
uv run task checks-fix
uv run task checks              # day-to-day (auto-scope)
uv run task checks-gui          # core+gui when working on the GUI
uv run task checks-full         # before release
uv run task checks-full-cpu     # + forced-CPU transcribe matrix
```

CI runs `core+gui+tui` buckets (no heavy/real-model suite). Details: [docs/development.md](docs/development.md).

Agent memory bank (per-branch project state): [memory/README.md](memory/README.md).

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

## License

MIT — see [LICENSE](LICENSE).
