Metadata-Version: 2.4
Name: yt-issue-reviewer
Version: 0.3.3
Summary: Find related issues across a YouTrack instance using self-hosted Ollama embeddings + local structural signals.
Project-URL: Homepage, https://github.com/ryancheley/yt-issue-reviewer
Project-URL: Repository, https://github.com/ryancheley/yt-issue-reviewer
Project-URL: Issues, https://github.com/ryancheley/yt-issue-reviewer/issues
Author: Ryan Cheley
License-Expression: MIT
License-File: LICENSE
Keywords: cli,datasette,duplicates,embeddings,issues,ollama,youtrack
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Bug Tracking
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: numpy>=2.0
Requires-Dist: ollama>=0.6
Requires-Dist: rich>=13.7
Description-Content-Type: text/markdown

# Related Issue Finder (`yt-issue-reviewer`)

[![Documentation Status](https://readthedocs.org/projects/yt-issue-reviewer/badge/?version=stable)](https://yt-issue-reviewer.readthedocs.io/en/stable/)

A run-on-demand CLI that helps a team lead find **related issues** across a YouTrack
instance — probable duplicates, issues about the same feature/root cause, and issues with
overlapping subject matter worded differently — so they can be merged, recognized, and
consolidated.

📖 **Documentation:** <https://yt-issue-reviewer.readthedocs.io/>

## Privacy & boundaries (non-negotiable)

- **Read-only** against YouTrack. This tool never links, merges, tags, or closes issues.
- **Self-hosted Ollama only** for embeddings and optional labels. Issue content never
  leaves infrastructure you control; there is no third-party hosted-AI fallback.
- All YouTrack access goes through the `youtrack_cli` package (the `yt` CLI).

## How it works

1. **Ingest** issues via `yt` and cache them locally in SQLite (Datasette-friendly).
2. **Embed** title+description via Ollama, caching vectors on
   `(issue_id, content_hash, model)` so unchanged issues are never re-embedded.
3. **Score** relatedness = weighted blend of semantic cosine similarity + local
   structural signals (shared tags, reporter overlap, temporal proximity).
4. **Group** high-scoring pairs into ranked groups (existing YouTrack links excluded).
5. **Report** ranked groups with human-readable evidence; optionally add a flag-gated,
   generated one-line label per group.

## Quickstart

```bash
uv sync
uv run yt-issue-reviewer doctor --ollama-host http://<host>:11434
uv run yt-issue-reviewer analyze --project PROJ --state open --min-score 0.6 --db ./yir.db
uv run yt-issue-reviewer show --db ./yir.db      # re-display a stored run, offline
datasette ./yir.db                                # browse results externally
```

Prerequisites: [uv](https://docs.astral.sh/uv/), an authenticated `youtrack-cli`, and a
reachable self-hosted Ollama with `nomic-embed-text` pulled. Full walkthrough in the
[quickstart](https://yt-issue-reviewer.readthedocs.io/en/stable/quickstart.html).

## Documentation

Full docs are hosted at **<https://yt-issue-reviewer.readthedocs.io/>**.

| Doc | What it covers |
|-----|----------------|
| [Installation](https://yt-issue-reviewer.readthedocs.io/en/stable/installation.html) | Prerequisites and install |
| [Quickstart](https://yt-issue-reviewer.readthedocs.io/en/stable/quickstart.html) | Zero → first analysis |
| [CLI reference](https://yt-issue-reviewer.readthedocs.io/en/stable/cli-reference.html) | Every command, flag, and exit code |
| [Configuration](https://yt-issue-reviewer.readthedocs.io/en/stable/configuration.html) | Env vars + `config.toml` with defaults |
| [Architecture](https://yt-issue-reviewer.readthedocs.io/en/stable/architecture.html) | The hybrid scoring pipeline |
| [Privacy & security](https://yt-issue-reviewer.readthedocs.io/en/stable/privacy-and-security.html) | What leaves your infra (nothing) |
| [Releasing](https://yt-issue-reviewer.readthedocs.io/en/stable/releasing.html) | Tag-driven PyPI release process |
| [Contributing](./CONTRIBUTING.md) | The `just check` gate and PR workflow |

The Markdown/RST sources live in [`docs/`](./docs); the full spec, plan, and contracts live
under `specs/001-related-issue-finder/`.

## Development

```bash
just --list      # all developer recipes
just check       # the exact CI gate: ruff, ruff format, ty, pytest, zizmor
```

See [CONTRIBUTING.md](./CONTRIBUTING.md). Licensed under the [MIT License](./LICENSE).
