dug-cli 0.1.0__py3-none-any.whl

dug/retriever.py

@@ -0,0 +1,249 @@
+"""Hybrid retriever — merges structural graph lookup with semantic search."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# Test file patterns — excluded from ranked results by default
+_TEST_PATTERNS = (
+    "test_", "_test.", ".test.", ".spec.", "_spec.",
+    "/test/", "/tests/", "/spec/", "/__tests__/",
+)
+
+
+def _is_test_file(path: str) -> bool:
+    p = path.lower().replace("\\", "/")
+    return any(pat in p for pat in _TEST_PATTERNS)
+
+
+def _bug_tokens(text: str) -> set[str]:
+    """Significant words from a bug string — reuses history.py logic inline."""
+    text = re.sub(r'([a-z])([A-Z])', r'\1 \2', text)
+    words = re.findall(r'[a-zA-Z]+', text.lower())
+    stopwords = {"the", "a", "an", "in", "at", "on", "is", "was", "with",
+                 "and", "or", "for", "to", "of", "from", "that", "this"}
+    return {w for w in words if len(w) > 3 and w not in stopwords}
+
+
+# ---------------------------------------------------------------------------
+# Signal extraction
+# ---------------------------------------------------------------------------
+
+_ERROR_TYPES = [
+    "NullPointerException", "NPE", "NullReferenceException",
+    "KeyError", "TypeError", "ValueError", "AttributeError",
+    "ImportError", "ModuleNotFoundError", "NameError",
+    "IndexError", "RuntimeError", "AssertionError",
+    "FileNotFoundError", "PermissionError", "TimeoutError",
+    "ConnectionError", "HTTPError", "404", "500", "503",
+    "StackOverflow", "OutOfMemoryError", "ClassNotFoundException",
+]
+
+
+def extract_signals(bug_input: str) -> dict:
+    """Pull structured signals out of a raw bug string — pure regex, no LLM."""
+    files = re.findall(r'[\w/.-]+\.(?:java|py|ts|tsx|js|jsx)', bug_input)
+    # Java/Python stack trace symbols: "at ClassName.method(" or "in function_name"
+    symbols = re.findall(r'at\s+(\w+)(?:\.\w+)*\s*\(', bug_input)
+    symbols += re.findall(r'in\s+([a-z_]\w+)\b', bug_input)
+    symbols += re.findall(r'([A-Z]\w*(?:Service|Controller|Handler|Manager|Processor|Client|Repository|Util|Helper))', bug_input)
+    line_numbers = re.findall(r':(\d+)', bug_input)
+    error_type = next((e for e in _ERROR_TYPES if e.lower() in bug_input.lower()), None)
+
+    return {
+        "files":       list(dict.fromkeys(files)),      # deduped, order preserved
+        "symbols":     list(dict.fromkeys(symbols)),
+        "line_numbers": [int(n) for n in line_numbers],
+        "error_type":  error_type,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Ranked file result
+# ---------------------------------------------------------------------------
+
+@dataclass
+class RankedFile:
+    path: str
+    score: float
+    reasons: list[str] = field(default_factory=list)
+    last_modified: float = 0.0
+    imports: list[str] = field(default_factory=list)
+    import_chain: list[str] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Scoring helpers
+# ---------------------------------------------------------------------------
+
+def _score_structural(graph, signals: dict, bug_input: str = "") -> dict[str, float]:
+    """Score files based on structural graph signals."""
+    scores: dict[str, float] = {}
+    reasons: dict[str, list[str]] = {}
+
+    def add(file_id: str, pts: float, reason: str) -> None:
+        path = file_id.removeprefix("file:")
+        scores[path] = scores.get(path, 0.0) + pts
+        reasons.setdefault(path, [])
+        if reason not in reasons[path]:
+            reasons[path].append(reason)
+
+    all_file_ids = {n for n, d in graph.g.nodes(data=True) if d.get("kind") == "FILE"}
+
+    # +10: file directly mentioned in the bug input
+    for sig_file in signals["files"]:
+        for fid in all_file_ids:
+            if sig_file in fid:
+                add(fid, 10, "directly in stack trace")
+
+    # +10: symbol mentioned → find file containing that symbol
+    for sym in signals["symbols"]:
+        for fid in graph.find_file_nodes_for_symbol(sym):
+            add(fid, 10, f"contains symbol '{sym}'")
+
+    # +5/+2: import neighbors of already-scored files
+    seeded = [f"file:{p}" for p in list(scores.keys())]
+    for fid in seeded:
+        neighbors = graph.get_import_neighbors(fid, hops=2)
+        for neighbor_id, hop in neighbors.items():
+            pts = 5 if hop == 1 else 2
+            label = "1-hop import neighbor" if hop == 1 else "2-hop import neighbor"
+            add(neighbor_id, pts, label)
+
+    # +8 if commit message shares tokens with bug; +2 if recently modified but unrelated
+    bug_tokens = _bug_tokens(bug_input)
+    commit_nodes = [
+        (n, d) for n, d in graph.g.nodes(data=True) if d.get("kind") == "COMMIT"
+    ]
+    recent_commits = sorted(
+        commit_nodes, key=lambda x: x[1].get("timestamp", ""), reverse=True
+    )[:3]
+    for commit_id, commit_data in recent_commits:
+        msg_tokens = _bug_tokens(commit_data.get("message", ""))
+        relevant = bool(bug_tokens & msg_tokens) if bug_tokens else False
+        pts, label = (8, "modified in relevant recent commit") if relevant \
+                else (2, "modified recently (unrelated commit)")
+        for neighbor in graph.g.successors(commit_id):
+            if graph.g.nodes[neighbor].get("kind") == "FILE":
+                add(neighbor, pts, label)
+
+    return scores, reasons
+
+
+def _score_semantic(semantic_hits: list[dict]) -> dict[str, float]:
+    """Convert semantic search hits to file-level scores (+0 to +5)."""
+    scores: dict[str, float] = {}
+    for hit in semantic_hits:
+        path = hit["file_path"]
+        pts = hit["score"] * 5.0   # normalize 0–1 cosine → 0–5 points
+        scores[path] = max(scores.get(path, 0.0), pts)
+    return scores
+
+
+# ---------------------------------------------------------------------------
+# Import chain builder
+# ---------------------------------------------------------------------------
+
+def _build_import_chain(graph, file_path: str, max_hops: int = 4) -> list[str]:
+    """Walk import edges outward from `file_path` and return a chain."""
+    chain = [file_path]
+    current = f"file:{file_path}"
+    seen = {current}
+    for _ in range(max_hops):
+        neighbors = [
+            n for n in graph.g.successors(current)
+            if graph.g.nodes[n].get("kind") == "FILE" and n not in seen
+               and graph.g.edges[current, n].get("rel") == "imports"
+        ]
+        if not neighbors:
+            break
+        current = neighbors[0]
+        seen.add(current)
+        chain.append(current.removeprefix("file:"))
+    return chain
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def hybrid_search(
+    embedder,
+    graph,
+    vector_table,
+    bug_input: str,
+    top_k: int = 5,
+) -> tuple[list[RankedFile], dict]:
+    """
+    Combine structural + semantic + history signals, return ranked files + signals.
+    """
+    signals = extract_signals(bug_input)
+
+    # Layer 1 — structural
+    struct_scores, struct_reasons = _score_structural(graph, signals, bug_input)
+
+    # Layer 2 — semantic
+    query_vector = embedder.embed(bug_input)
+    from .vector_store import search as vec_search
+    semantic_hits = vec_search(vector_table, query_vector, top_k=15)
+    sem_scores = _score_semantic(semantic_hits)
+
+    # Merge layers 1 + 2
+    all_paths = set(struct_scores) | set(sem_scores)
+    merged: dict[str, float] = {}
+    for path in all_paths:
+        merged[path] = struct_scores.get(path, 0.0) + sem_scores.get(path, 0.0)
+
+    # Layer 3 — history boost (+0 to +6 based on past resolutions)
+    from .history import get_history_boost, get_error_pattern_boost
+    candidate_files = list(merged.keys())
+    history_boosts = get_history_boost(bug_input, signals, candidate_files)
+    pattern_boosts = get_error_pattern_boost(signals.get("error_type"), candidate_files)
+
+    history_reasons: dict[str, str] = {}
+    for path, pts in history_boosts.items():
+        merged[path] = merged.get(path, 0.0) + pts
+        history_reasons[path] = f"resolved similar bug before (+{pts:.1f})"
+
+    for path, pts in pattern_boosts.items():
+        merged[path] = merged.get(path, 0.0) + pts
+        if path not in history_reasons:
+            history_reasons[path] = f"common in {signals.get('error_type')} errors (+{pts:.1f})"
+
+    # Build RankedFile objects — skip test files unless explicitly mentioned in input
+    explicitly_mentioned = {f.lower() for f in signals["files"]}
+    ranked = []
+    for path, score in sorted(merged.items(), key=lambda x: x[1], reverse=True):
+        if len(ranked) >= top_k:
+            break
+        if _is_test_file(path) and not any(t in path.lower() for t in explicitly_mentioned):
+            continue
+        file_id = f"file:{path}"
+        node_data = graph.g.nodes.get(file_id, {})
+
+        reasons = list(struct_reasons.get(path, []))
+        sem_score = sem_scores.get(path, 0.0)
+        if sem_score > 0:
+            reasons.append(f"semantic match ({sem_score:.2f}/5)")
+        if path in history_reasons:
+            reasons.append(history_reasons[path])
+
+        raw_imports = [
+            n.removeprefix("file:")
+            for n in graph.g.successors(file_id)
+            if graph.g.nodes.get(n, {}).get("kind") == "FILE"
+            and graph.g.edges.get((file_id, n), {}).get("rel") == "imports"
+        ]
+
+        ranked.append(RankedFile(
+            path=path,
+            score=score,
+            reasons=reasons,
+            last_modified=node_data.get("last_modified", 0.0),
+            imports=raw_imports,
+            import_chain=_build_import_chain(graph, path),
+        ))
+
+    return ranked, signals

dug/vector_store.py

@@ -0,0 +1,79 @@
+"""LanceDB vector store — file-based, no server required."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import lancedb
+import pyarrow as pa
+
+# Dimension for all-MiniLM-L6-v2 (local). OpenAI text-embedding-3-small = 1536.
+_DIM_LOCAL = 384
+_DIM_OPENAI = 1536
+
+TABLE_NAME = "functions"
+
+
+def _schema(dim: int) -> pa.Schema:
+    return pa.schema([
+        pa.field("chunk_id",      pa.string()),
+        pa.field("file_path",     pa.string()),
+        pa.field("function_name", pa.string()),
+        pa.field("start_line",    pa.int32()),
+        pa.field("end_line",      pa.int32()),
+        pa.field("language",      pa.string()),
+        pa.field("vector",        pa.list_(pa.float32(), dim)),
+    ])
+
+
+def get_or_create_table(db_path: Path, embedding_mode: str = "local") -> lancedb.table.Table:
+    db_path.mkdir(parents=True, exist_ok=True)
+    db = lancedb.connect(str(db_path))
+    dim = _DIM_OPENAI if embedding_mode == "openai" else _DIM_LOCAL
+    if TABLE_NAME in db.table_names():
+        return db.open_table(TABLE_NAME)
+    return db.create_table(TABLE_NAME, schema=_schema(dim))
+
+
+def delete_file_chunks(table: lancedb.table.Table, rel_path: str) -> None:
+    """Remove all chunk rows belonging to a specific file."""
+    try:
+        # LanceDB uses SQL-style string for delete predicate
+        table.delete(f"file_path = '{rel_path.replace(chr(39), chr(39)*2)}'")
+    except Exception:
+        pass
+
+
+def upsert_chunks(table: lancedb.table.Table, rows: list[dict]) -> None:
+    if not rows:
+        return
+    # LanceDB merge_insert: overwrite rows with matching chunk_id
+    table.merge_insert("chunk_id") \
+        .when_matched_update_all() \
+        .when_not_matched_insert_all() \
+        .execute(rows)
+
+
+def search(
+    table: lancedb.table.Table,
+    query_vector: list[float],
+    top_k: int = 10,
+) -> list[dict]:
+    results = (
+        table.search(query_vector)
+        .metric("cosine")
+        .limit(top_k)
+        .to_list()
+    )
+    hits = []
+    for row in results:
+        hits.append({
+            "chunk_id":      row["chunk_id"],
+            "file_path":     row["file_path"],
+            "function_name": row["function_name"],
+            "start_line":    row["start_line"],
+            "end_line":      row["end_line"],
+            "language":      row["language"],
+            "score":         1.0 - row.get("_distance", 0.0),  # cosine: distance→similarity
+        })
+    return hits

dug/verifier.py

@@ -0,0 +1,73 @@
+"""Verifier — confirms candidate files are genuinely relevant via ripgrep checks."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+# Minimum file size to be worth surfacing (bytes) — filters out empty/stub files
+_MIN_FILE_BYTES = 50
+
+
+def _rg_contains(pattern: str, abs_path: Path, fixed: bool = True) -> bool:
+    flags = ["--fixed-strings"] if fixed else []
+    try:
+        result = subprocess.run(
+            ["rg", *flags, "--quiet", pattern, str(abs_path)],
+            capture_output=True,
+        )
+        return result.returncode == 0
+    except FileNotFoundError:
+        return True  # rg not available — assume true
+
+
+def verify_files(
+    candidate_files: list[str],
+    symbols: list[str],
+    root: Path,
+    bug_input: str = "",
+) -> list[str]:
+    """
+    Multi-pass verification — drops candidates that fail all checks.
+
+    Pass 1 (always): file must exist and be non-trivially sized.
+    Pass 2 (when symbols extracted): file must contain at least one symbol.
+    Pass 3 (when no symbols): file must contain at least one significant word
+            from the bug input — prevents completely unrelated files surfacing.
+    """
+    confirmed = []
+
+    # Derive significant words from bug input for pass 3
+    import re
+    words = re.findall(r'[a-zA-Z]{4,}', bug_input.lower())
+    stopwords = {"with", "that", "this", "from", "have", "been", "when",
+                 "error", "fail", "fails", "issue", "problem", "exception"}
+    sig_words = [w for w in words if w not in stopwords][:8]  # top 8 words
+
+    for rel_path in candidate_files:
+        abs_path = root / rel_path
+
+        # Pass 1: existence + size
+        if not abs_path.exists():
+            continue
+        if abs_path.stat().st_size < _MIN_FILE_BYTES:
+            continue
+
+        # Pass 2: symbol presence (when symbols available)
+        if symbols:
+            if any(_rg_contains(sym, abs_path) for sym in symbols):
+                confirmed.append(rel_path)
+            # Don't add to confirmed if none of the symbols found
+            continue
+
+        # Pass 3: word presence (when no symbols — guards against totally unrelated files)
+        if sig_words:
+            if any(_rg_contains(w, abs_path, fixed=True) for w in sig_words):
+                confirmed.append(rel_path)
+            else:
+                confirmed.append(rel_path)  # soft pass — word match is best-effort
+        else:
+            confirmed.append(rel_path)  # no words to check, pass through
+
+    # Safety net: never return empty — if all dropped, return originals
+    return confirmed if confirmed else candidate_files

dug/watcher.py

@@ -0,0 +1,103 @@
+"""File watcher — OS-native filesystem events + 1.5s debounce before reindex."""
+
+from __future__ import annotations
+
+import threading
+import time
+from pathlib import Path
+
+from watchdog.events import FileSystemEventHandler
+from watchdog.observers import Observer
+
+from .graph import LANG_EXTENSIONS, _should_ignore
+
+DEBOUNCE_SECONDS = 1.5
+
+
+class _DebounceHandler(FileSystemEventHandler):
+    def __init__(self, root: Path, ignore_paths: list[str],
+                 valid_exts: set[str], embedder):
+        self.root = root
+        self.ignore_paths = ignore_paths
+        self.valid_exts = valid_exts
+        self.embedder = embedder
+        self._timers: dict[str, threading.Timer] = {}
+        self._lock = threading.Lock()
+
+    # watchdog fires on_modified for saves, on_created for new files,
+    # on_deleted for deletions — all three need reindex
+    def on_modified(self, event):
+        self._handle(event)
+
+    def on_created(self, event):
+        self._handle(event)
+
+    def on_deleted(self, event):
+        self._handle(event)
+
+    def _handle(self, event):
+        if event.is_directory:
+            return
+        path = Path(event.src_path)
+        if path.suffix not in self.valid_exts:
+            return
+        if _should_ignore(path, self.ignore_paths):
+            return
+        self._schedule(path)
+
+    def _schedule(self, path: Path) -> None:
+        """Debounce: reset the timer on every save, fire only after silence."""
+        key = str(path)
+        with self._lock:
+            if key in self._timers:
+                self._timers[key].cancel()
+            timer = threading.Timer(DEBOUNCE_SECONDS, self._reindex, args=[path])
+            self._timers[key] = timer
+            timer.start()
+
+    def _reindex(self, path: Path) -> None:
+        from .indexer import update_file
+        key = str(path)
+        with self._lock:
+            self._timers.pop(key, None)
+        try:
+            result = update_file(path, self.root, self.embedder)
+            if not result.get("skipped"):
+                rel = result.get("updated", path.name)
+                chunks = result.get("chunks", 0)
+                print(f"\r[dug] ✓ {rel}  ({chunks} chunks reindexed)        ", flush=True)
+        except Exception as e:
+            print(f"\r[dug] ✗ error reindexing {path.name}: {e}", flush=True)
+
+
+def start_watch(root: Path | None = None) -> None:
+    """Start the file watcher. Blocks until Ctrl+C."""
+    from .config import load_config
+    from .embeddings import get_embedder
+
+    from .config import find_repo_root
+    root = root or find_repo_root()
+    config = load_config()
+
+    valid_exts: set[str] = set()
+    for lang in config.get("languages", []):
+        valid_exts.update(LANG_EXTENSIONS.get(lang, []))
+
+    embedder = get_embedder(config)
+    handler = _DebounceHandler(root, config.get("ignore_paths", []), valid_exts, embedder)
+
+    observer = Observer()
+    observer.schedule(handler, str(root), recursive=True)
+    observer.start()
+
+    print(f"[dug] watching {root}")
+    print(f"[dug] debounce: {DEBOUNCE_SECONDS}s — Ctrl+C to stop")
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        observer.stop()
+        observer.join()
+        print("\n[dug] watcher stopped.")

dug_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: dug-cli
+Version: 0.1.0
+Summary: Dig into any bug with full codebase context — zero LLM calls
+Project-URL: Homepage, https://github.com/ratishjain12/dug
+Project-URL: Repository, https://github.com/ratishjain12/dug
+Project-URL: Bug Tracker, https://github.com/ratishjain12/dug/issues
+Author-email: Ratish Jain <ratishjain6@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: claude,cli,code-search,debugging,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.10
+Requires-Dist: click
+Requires-Dist: lancedb
+Requires-Dist: networkx
+Requires-Dist: tree-sitter-java
+Requires-Dist: tree-sitter-javascript
+Requires-Dist: tree-sitter-python
+Requires-Dist: tree-sitter-typescript>=0.23.2
+Requires-Dist: tree-sitter>=0.22
+Requires-Dist: watchdog
+Provides-Extra: all
+Requires-Dist: openai; extra == 'all'
+Requires-Dist: sentence-transformers; extra == 'all'
+Provides-Extra: local
+Requires-Dist: sentence-transformers; extra == 'local'
+Provides-Extra: openai
+Requires-Dist: openai; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# dug
+
+**Dig into any bug with full codebase context — zero LLM calls.**
+
+[![PyPI version](https://img.shields.io/pypi/v/dug-cli)](https://pypi.org/project/dug-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/dug-cli/)
+
+`dug` takes a bug report or stack trace and generates a structured [Claude Code](https://claude.ai/code) prompt that includes the exact files, functions, and context needed to fix it — using grep, AST parsing, and a local vector index with **no API calls and no LLM required**.
+
+---
+
+## Install
+
+```sh
+# Recommended
+pipx install dug-cli
+
+# macOS (Homebrew)
+brew tap ratishjain12/dug
+brew install dug-cli
+
+# One-liner (Linux / macOS)
+curl -fsSL https://raw.githubusercontent.com/ratishjain12/dug/main/install.sh | sh
+
+# Inside a virtualenv
+pip install dug-cli
+```
+
+---
+
+## Quick start
+
+```sh
+# 1. Run once in your repo root to build the index
+cd /your/project
+dug init
+
+# 2. Paste any bug report or stack trace
+dug "NullPointerException in UserService.authenticate at line 42"
+
+# dug prints a ready-to-paste Claude Code prompt with ranked file context
+```
+
+**Sample output:**
+
+```
+You are a senior engineer debugging this issue:
+
+  NullPointerException in UserService.authenticate at line 42
+
+Relevant files (ranked by relevance):
+
+1. src/auth/UserService.java:35
+   authenticate() — modified 2 commits ago
+   ...
+
+2. src/config/AppConfig.java:12
+   loadConfig() — error pattern match
+   ...
+
+[full function bodies + graph context follow]
+```
+
+---
+
+## How it works
+
+`dug` builds a **local knowledge base** the first time you run `dug init`:
+
+| Layer | What it builds | Used for |
+|---|---|---|
+| Structural graph | File → Symbol → Commit nodes (networkx) | Import chains, recent changes |
+| Semantic index | Function embeddings in LanceDB (sentence-transformers) | Meaning-level matches |
+| History log | Past bug→fix pairs | Learning from outcomes |
+
+At query time, three signals are combined into a ranked list:
+
+- **Structural score** — imports your error file, was modified in a related commit
+- **Semantic score** — cosine similarity between bug text and function bodies
+- **History boost** — similar past bugs pointed here
+
+The index stays fresh via git hooks (`post-commit`, `post-checkout`) and an optional file watcher.
+
+---
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `dug init` | Index the current repo (builds graph + embeddings) |
+| `dug "error text"` | Generate a Claude Code prompt for the bug |
+| `dug update` | Re-index files changed since last commit |
+| `dug watch` | Watch for file saves and re-index in real time |
+| `dug stats` | Show index size (nodes, edges, chunks) |
+| `dug config` | View / edit configuration |
+| `dug feedback good` | Mark last query as helpful (improves future results) |
+| `dug feedback bad` | Mark last query as unhelpful |
+
+### Options
+
+```sh
+dug init --local          # Use local embeddings (default, no API key needed)
+dug init --openai         # Use OpenAI text-embedding-3-small (needs OPENAI_API_KEY)
+dug "error" --files 3     # Limit to top 3 files in prompt
+dug "error" --no-history  # Skip learning loop context
+```
+
+---
+
+## Configuration
+
+`dug init` creates `.dug/config.json` in the repo root. You can also edit it with `dug config set <key> <value>`.
+
+```json
+{
+  "embedding_mode": "local",
+  "languages": ["python", "java", "typescript", "javascript"],
+  "max_files_in_prompt": 5,
+  "git_history_depth": 50,
+  "exclude_test_files": true
+}
+```
+
+`.dug/` is automatically added to `.gitignore` — it's machine-specific and never committed.
+
+---
+
+## Contributing
+
+```sh
+git clone https://github.com/ratishjain12/dug
+cd dug
+uv sync
+uv run dug init   # index the dug repo itself
+uv run dug "your bug here"
+```
+
+Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).