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

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

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

Quickstart

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, an authenticated youtrack-cli, and a reachable self-hosted Ollama with nomic-embed-text pulled. Full walkthrough in the quickstart.

Documentation

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

Doc	What it covers
Installation	Prerequisites and install
Quickstart	Zero → first analysis
CLI reference	Every command, flag, and exit code
Configuration	Env vars + `config.toml` with defaults
Architecture	The hybrid scoring pipeline
Privacy & security	What leaves your infra (nothing)
Releasing	Tag-driven PyPI release process
Contributing	The `just check` gate and PR workflow

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

Development

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

See CONTRIBUTING.md. Licensed under the MIT License.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

yt_issue_reviewer-0.3.8.tar.gz (248.9 kB view details)

Uploaded Jul 10, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

yt_issue_reviewer-0.3.8-py3-none-any.whl (33.4 kB view details)

Uploaded Jul 10, 2026 Python 3

File details

Details for the file yt_issue_reviewer-0.3.8.tar.gz.

File metadata

Download URL: yt_issue_reviewer-0.3.8.tar.gz
Upload date: Jul 10, 2026
Size: 248.9 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for yt_issue_reviewer-0.3.8.tar.gz
Algorithm	Hash digest
SHA256	`6877a0167301efa6c3e7c3254d40bc314bbefedcebcceaf4248296db478b49e1`
MD5	`e10750cd23c278f7ea21a8543de49bbd`
BLAKE2b-256	`c1e79a055962a2df7b62c6d8846535400ba41329cf89242540e102a4b6294022`

See more details on using hashes here.

Provenance

The following attestation bundles were made for yt_issue_reviewer-0.3.8.tar.gz:

Publisher: release.yml on ryancheley/yt-issue-reviewer

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: yt_issue_reviewer-0.3.8.tar.gz
- Subject digest: 6877a0167301efa6c3e7c3254d40bc314bbefedcebcceaf4248296db478b49e1
- Sigstore transparency entry: 2134640559
- Sigstore integration time: Jul 10, 2026
Source repository:
- Permalink: ryancheley/yt-issue-reviewer@62a5b993175c2ff28273cc69acdc11d337de5900
- Branch / Tag: refs/tags/v0.3.8
- Owner: https://github.com/ryancheley
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@62a5b993175c2ff28273cc69acdc11d337de5900
- Trigger Event: push