depscout 0.1.0__tar.gz

depscout-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+.pytest_cache/
+.venv
+.depscout
+eval/
+uv.lock
+tests/
+.python-version

depscout-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miguel Soares
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

depscout-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: depscout
+Version: 0.1.0
+Summary: Upgrade intelligence for your Python dependencies
+Project-URL: Homepage, https://github.com/zemmsoares/depscout
+Project-URL: Issues, https://github.com/zemmsoares/depscout/issues
+Author: Miguel Soares
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: ollama>=0.6.1
+Requires-Dist: rich>=14.0.0
+Requires-Dist: typer>=0.12.0
+Description-Content-Type: text/markdown
+
+# depscout
+
+Scans your Python project dependencies and uses an LLM to flag what's worth acting on - outdated packages, unmaintained libraries, and better alternatives.
+
+
+## Install
+
+```bash
+pip install depscout
+# or
+uv tool install depscout
+```
+
+## Setup
+
+**Ollama (Local):**
+```bash
+depscout config provider ollama
+ollama pull qwen2.5:4b
+depscout config model qwen2.5:4b
+```
+
+**OpenAI:**
+```bash
+depscout config provider openai
+depscout config openai-key sk-...
+depscout config model gpt-4o-mini
+```
+
+**GitHub token (optional):** avoids rate limits if you have many dependencies
+```bash
+depscout config github-token ghp_...
+```
+
+## Commands
+
+```
+depscout scan [PATH]        AI analysis — surfaces insights
+depscout check [PATH]       Version check only, no AI
+depscout status             Show current config
+depscout config             List all config options
+```
+
+## Contributing
+PRs are welcome!

depscout-0.1.0/README.md

@@ -0,0 +1,45 @@
+# depscout
+
+Scans your Python project dependencies and uses an LLM to flag what's worth acting on - outdated packages, unmaintained libraries, and better alternatives.
+
+
+## Install
+
+```bash
+pip install depscout
+# or
+uv tool install depscout
+```
+
+## Setup
+
+**Ollama (Local):**
+```bash
+depscout config provider ollama
+ollama pull qwen2.5:4b
+depscout config model qwen2.5:4b
+```
+
+**OpenAI:**
+```bash
+depscout config provider openai
+depscout config openai-key sk-...
+depscout config model gpt-4o-mini
+```
+
+**GitHub token (optional):** avoids rate limits if you have many dependencies
+```bash
+depscout config github-token ghp_...
+```
+
+## Commands
+
+```
+depscout scan [PATH]        AI analysis — surfaces insights
+depscout check [PATH]       Version check only, no AI
+depscout status             Show current config
+depscout config             List all config options
+```
+
+## Contributing
+PRs are welcome!

depscout-0.1.0/depscout/analyst.py

@@ -0,0 +1,242 @@
+import json
+import os
+import re
+from datetime import date
+
+import ollama
+
+import depscout.deps as _deps
+from depscout import config as cfg
+
+DEFAULT_OPENAI_MODEL = "gpt-4.1"
+
+
+def _build_prompt(deps):
+    lines = []
+    for name, info in deps.items():
+        current = info.get("current", "unknown")
+        latest = info.get("latest", "unknown")
+        changelog = info.get("changelog", "")
+
+        version_status = f"{current} → {latest}" if current != latest else f"{current} (up to date)"
+        lines.append(f"- {name}: {version_status}")
+        if info.get("summary"):
+            lines.append(f"  summary: {info['summary']}")
+        if info.get("github_description") and info.get("github_description") != info.get("summary"):
+            lines.append(f"  github description: {info['github_description']}")
+        if info.get("github_readme"):
+            lines.append(f"  github readme (first 500 chars): {info['github_readme'][:500]}")
+        if info.get("dev_status"):
+            lines.append(f"  status: {info['dev_status']}")
+        if info.get("last_release_date"):
+            lines.append(f"  last release: {info['last_release_date']}")
+        if info.get("pushed_at"):
+            lines.append(f"  last commit: {info['pushed_at']}")
+        if info.get("stars") is not None:
+            lines.append(f"  stars: {info['stars']}, forks: {info.get('forks', 'unknown')}, open issues: {info.get('open_issues', 'unknown')}")
+        if info.get("archived") or info.get("disabled"):
+            lines.append(f"  archived: yes")
+        if info.get("topics"):
+            lines.append(f"  topics: {', '.join(info['topics'])}")
+        if info.get("requires_python"):
+            lines.append(f"  requires python: {info['requires_python']}")
+        if info.get("vulnerabilities"):
+            cves = ", ".join(v.get("id", "unknown") for v in info["vulnerabilities"])
+            lines.append(f"  known vulnerabilities: {cves}")
+        if changelog:
+            for entry in changelog:
+                notes = entry["notes"].replace("\r\n", "\n").replace("\r", "\n")
+                notes = re.sub(r"<!--.*?-->", "", notes, flags=re.DOTALL)
+                notes = re.sub(r"^#{1,6}\s+.*$", "", notes, flags=re.MULTILINE)
+                notes = re.sub(r"\*\*Full Changelog\*\*.*", "", notes)
+                notes = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", notes)
+                notes = re.sub(r"\n{2,}", "\n", notes).strip()
+                lines.append(f"  [{entry['version']}] {notes[:500]}")
+
+    dep_summary = "\n".join(lines)
+
+    return f"""You are a Python dependency advisor. A developer ran your tool on their project.
+Today's date is {date.today()}.
+
+Here are their dependencies:
+{dep_summary}
+
+Generate 0 to 5 concise insights that would actually help this developer.
+
+MANDATORY — always generate an insight if any of these are true:
+- The changelog contains a CVE or security advisory (non-negotiable, always flag)
+- The package is significantly behind and breaking changes affect the developer
+
+OPTIONAL — generate an insight if genuinely useful:
+- A better modern alternative exists that the community now prefers
+- The package is unmaintained or losing community support
+- A deprecated pattern or API is in use
+
+If none of the above apply, return an empty array [].
+
+Rules:
+- One insight per package maximum
+- Every insight must include all four fields: package, title, body, category
+- Do not add any fields beyond the four specified
+- Return ONLY a raw JSON array — no markdown, no code fences, no explanation
+
+Each object must have EXACTLY these four keys, no more, no less:
+  "package"  — the exact package name this insight is about
+  "title"    — one short sentence under 70 characters
+  "body"     — 1 to 2 sentences of concrete, specific explanation
+  "category" — exactly one of: outdated, alternative, pattern, unmaintained
+
+Example of valid output format (these are NOT based on the dependencies above):
+[
+  {{
+    "package": "example-pkg",
+    "title": "example-pkg is 6 major versions behind",
+    "body": "You are on 0.1.0 but the latest is 0.6.1. The client API changed significantly — generate() responses are now typed objects, not plain dicts.",
+    "category": "outdated"
+  }},
+  {{
+    "package": "another-pkg",
+    "title": "another-pkg 2.23.0 has unpatched CVEs — upgrade to 2.32.4+",
+    "body": "CVE-2024-47081 (credential leak via netrc) and a cert verification bypass were fixed in 2.32.x. You are 9 versions behind and exposed to these vulnerabilities.",
+    "category": "outdated"
+  }}
+]
+
+Now generate insights for the dependencies listed above:"""
+
+
+def _parse_response(raw):
+    raw = re.sub(r"<think>.*?</think>", "", raw, flags=re.DOTALL).strip()
+    raw = re.sub(r"```[a-z]*\n?", "", raw).strip()
+    start = raw.find("[")
+    end = raw.rfind("]") + 1
+    if start == -1 or end == 0:
+        return []
+    try:
+        insights = json.loads(raw[start:end])
+        required = {"package", "title", "body", "category"}
+        return [i for i in insights if required.issubset(i.keys())]
+    except json.JSONDecodeError:
+        return []
+
+
+def _deduplicate(insights):
+    seen = set()
+    result = []
+    for insight in insights:
+        pkg = insight.get("package", "")
+        if pkg not in seen:
+            seen.add(pkg)
+            result.append(insight)
+    return result
+
+
+def _filter_factual_errors(insights, deps):
+    result = []
+    for insight in insights:
+        pkg = insight.get("package", "")
+        info = deps.get(pkg)
+        if insight.get("category") == "outdated" and info:
+            if info.get("current") == info.get("latest"):
+                continue
+        result.append(insight)
+    return result
+
+
+def _resolve_ollama_model(configured_model):
+    if configured_model:
+        return configured_model
+    try:
+        installed = [m.model for m in ollama.list().models]
+    except Exception:
+        raise RuntimeError(
+            "Could not connect to Ollama. Make sure it is running: ollama serve\n"
+            "Or use OpenAI instead: depscout config openai-key sk-..."
+        )
+    if not installed:
+        raise RuntimeError(
+            "No Ollama models installed. Pull one first, for example:\n"
+            "  ollama pull qwen2.5:4b\n"
+            "Or use OpenAI instead: depscout config openai-key sk-..."
+        )
+    if len(installed) == 1:
+        return installed[0]
+    names = "\n".join(f"  {m}" for m in installed)
+    raise RuntimeError(
+        f"Multiple Ollama models installed. Pick one:\n{names}\n\n"
+        f"Run: depscout config model <model-name>"
+    )
+
+
+def _resolve_provider():
+    provider = os.environ.get("DEPSCOUT_PROVIDER") or cfg.get("provider")
+    model = os.environ.get("DEPSCOUT_MODEL") or cfg.get("model")
+    api_key = os.environ.get("OPENAI_API_KEY") or cfg.get("openai_key")
+
+    if provider == "openai":
+        if not api_key:
+            raise RuntimeError(
+                "Provider is set to 'openai' but no API key found.\n"
+                "Run: depscout config openai-key sk-..."
+            )
+        return "openai", model or DEFAULT_OPENAI_MODEL, api_key
+
+    return "ollama", _resolve_ollama_model(model), None
+
+
+def _call_llm(prompt):
+    provider, model, api_key = _resolve_provider()
+
+    if provider == "openai":
+        import httpx
+        r = httpx.post(
+            "https://api.openai.com/v1/chat/completions",
+            headers={"Authorization": f"Bearer {api_key}"},
+            json={"model": model, "messages": [{"role": "user", "content": prompt}]},
+            timeout=30,
+        )
+        r.raise_for_status()
+        return r.json()["choices"][0]["message"]["content"], model
+
+    response = ollama.generate(model=model, prompt=prompt, options={"num_ctx": 8192}, think=False)
+    return response["response"], model
+
+
+def _save_debug(prompt, raw_response, insights, model_used):
+    from datetime import datetime
+    if _deps.CACHE_DIR is None:
+        return
+    debug_dir = _deps.CACHE_DIR / "debug"
+    debug_dir.mkdir(exist_ok=True)
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    with open(debug_dir / f"{timestamp}.json", "w") as f:
+        json.dump({
+            "model": model_used,
+            "timestamp": timestamp,
+            "prompt": prompt,
+            "raw_response": raw_response,
+            "parsed_insights": insights,
+        }, f, indent=2)
+
+
+def analyze(deps=None):
+    if deps is None:
+        with open(_deps.DEPS_FILE) as f:
+            deps = json.load(f)
+
+    prompt = _build_prompt(deps)
+    raw, model_used = _call_llm(prompt)
+
+    if not raw.strip():
+        raise RuntimeError(f"Model {model_used!r} returned an empty response.")
+
+    insights = _parse_response(raw)
+    insights = _deduplicate(insights)
+    insights = _filter_factual_errors(insights, deps)
+
+    # _save_debug(prompt, raw, insights, model_used)
+
+    with open(_deps.CACHE_DIR / "insights.json", "w") as f:
+        json.dump(insights, f, indent=4)
+
+    return insights

depscout-0.1.0/depscout/cli.py

@@ -0,0 +1,191 @@
+import importlib.metadata
+import os
+
+import typer
+from rich.console import Console
+
+from depscout.analyst import analyze
+from depscout.deps import scan as collect
+from depscout.enrich import enrich
+from depscout import config as cfg
+
+app = typer.Typer(
+    no_args_is_help=True,
+    add_completion=False,
+    help="Upgrade intelligence for your Python dependencies.",
+    pretty_exceptions_enable=False,
+)
+console = Console()
+
+CATEGORY_COLORS = {
+    "outdated": "yellow",
+    "alternative": "cyan",
+    "pattern": "magenta",
+    "unmaintained": "red",
+}
+
+CONFIG_KEYS = {
+    "provider":     ("ollama or openai", "depscout config provider ollama"),
+    "model":        ("model name to use", "depscout config model qwen2.5:4b"),
+    "openai-key":   ("OpenAI API key",    "depscout config openai-key sk-..."),
+    "github-token": ("GitHub token for richer analysis and higher rate limits", "depscout config github-token ghp_..."),
+}
+
+
+def _render_insights(insights):
+    if not insights:
+        console.print("[green]All dependencies look good.[/green]")
+        return
+
+    console.print(f"\n  [bold]{len(insights)} insights for your project[/bold]\n")
+
+    for insight in insights:
+        package = insight.get("package", "")
+        title = insight.get("title", "")
+        body = insight.get("body", "")
+        category = insight.get("category", "")
+        color = CATEGORY_COLORS.get(category, "white")
+
+        console.print(f"  [bold]{package}[/bold]  [dim {color}]{category}[/dim {color}]")
+        console.print(f"  [bold {color}]▸ {title}[/bold {color}]")
+        console.print(f"    [dim]{body}[/dim]")
+        console.print()
+
+
+@app.command()
+def scan(path: str = typer.Argument(".", help="Project root to scan")):
+    """Analyze dependencies with AI and surface actionable insights."""
+    with console.status("[dim]Collecting dependencies...[/dim]"):
+        deps = collect(path)
+
+    if not deps:
+        console.print("[yellow]No dependencies found.[/yellow] Make sure the directory contains a pyproject.toml or requirements*.txt file.")
+        raise typer.Exit(1)
+
+    with console.status("[dim]Fetching changelogs...[/dim]"):
+        enrich()
+
+    try:
+        with console.status("[dim]Analyzing with LLM...[/dim]"):
+            insights = analyze()
+    except RuntimeError as e:
+        console.print(f"[red]Analysis failed:[/red] {e}")
+        raise typer.Exit(1)
+    except Exception as e:
+        if "connection" in str(e).lower() or "refused" in str(e).lower():
+            console.print("[red]Could not connect to Ollama.[/red] Make sure Ollama is running: [bold]ollama serve[/bold]")
+        else:
+            console.print(f"[red]Unexpected error:[/red] {e}")
+        raise typer.Exit(1)
+
+    _render_insights(insights)
+
+
+@app.command()
+def check(path: str = typer.Argument(".", help="Project root to scan")):
+    """Check for newer versions without AI — fast and free."""
+    with console.status("[dim]Fetching latest versions from PyPI...[/dim]"):
+        deps = collect(path)
+
+    if not deps:
+        console.print("[yellow]No dependencies found.[/yellow] Make sure the directory contains a pyproject.toml or requirements*.txt file.")
+        raise typer.Exit(1)
+
+    outdated = {name: info for name, info in deps.items() if info.get("current") and info.get("latest") and info["current"] != info["latest"]}
+    up_to_date = {name: info for name, info in deps.items() if name not in outdated}
+
+    if not outdated:
+        console.print(f"\n  [green]All {len(deps)} dependencies are up to date.[/green]\n")
+        return
+
+    pkg_width = max(len(n) for n in outdated) + 2
+
+    console.print(f"\n  [bold]{len(outdated)} of {len(deps)} packages have updates[/bold]\n")
+    for name, info in sorted(outdated.items()):
+        console.print(f"  [bold]{name:<{pkg_width}}[/bold][yellow]{info['current']}[/yellow]  →  [green]{info['latest']}[/green]")
+
+    if up_to_date:
+        console.print(f"\n  [dim]{len(up_to_date)} packages are current[/dim]")
+    console.print()
+
+
+@app.command()
+def status():
+    """Show active provider, model, and configuration."""
+    from depscout.analyst import _resolve_provider
+    import ollama
+
+    console.print()
+
+    try:
+        provider, model, _ = _resolve_provider()
+        console.print(f"  [bold]provider[/bold]    {provider}")
+        console.print(f"  [bold]model[/bold]       {model}")
+    except RuntimeError as e:
+        console.print(f"  [bold]provider[/bold]    [red]not configured[/red]  [dim]{e}[/dim]")
+
+    github_token = os.environ.get("GITHUB_TOKEN") or cfg.get("github_token")
+    console.print(f"  [bold]github[/bold]      {'[green]token set[/green]' if github_token else '[dim]no token — rate-limited[/dim]'}")
+
+    openai_key = os.environ.get("OPENAI_API_KEY") or cfg.get("openai_key")
+    console.print(f"  [bold]openai key[/bold]  {'[green]set[/green]' if openai_key else '[dim]not set[/dim]'}")
+
+    try:
+        installed = [m.model for m in ollama.list().models]
+        models_str = ", ".join(installed) if installed else "no models installed"
+        console.print(f"  [bold]ollama[/bold]      [green]running[/green]  [dim]{models_str}[/dim]")
+    except Exception:
+        console.print(f"  [bold]ollama[/bold]      [dim]not running[/dim]")
+
+    console.print()
+    console.print(f"  [dim]config file: {cfg.CONFIG_FILE}[/dim]")
+    console.print()
+
+
+@app.command()
+def config(
+    key: str = typer.Argument(None, help="Config key"),
+    value: str = typer.Argument(None, help="Value to set"),
+):
+    """Set a configuration value.
+
+    Available keys:
+
+      provider      ollama or openai
+      model         model name (e.g. qwen2.5:4b or gpt-4o-mini)
+      openai-key    your OpenAI API key
+      github-token  GitHub token for richer analysis
+
+    Examples:
+
+      depscout config provider openai
+      depscout config model gpt-4o-mini
+      depscout config openai-key sk-...
+      depscout config github-token ghp_...
+    """
+    if key is None or value is None:
+        console.print()
+        console.print("  [bold]Available config keys:[/bold]\n")
+        key_width = max(len(k) for k in CONFIG_KEYS) + 2
+        for k, (desc, example) in CONFIG_KEYS.items():
+            console.print(f"  [bold]{k:<{key_width}}[/bold][dim]{desc}[/dim]")
+            console.print(f"  {' ' * key_width}[dim italic]{example}[/dim italic]")
+            console.print()
+        raise typer.Exit()
+
+    cfg.set(key.replace("-", "_"), value)
+    console.print(f"[dim]{key} saved.[/dim]")
+
+
+@app.command()
+def version():
+    """Show depscout version."""
+    try:
+        v = importlib.metadata.version("depscout")
+    except importlib.metadata.PackageNotFoundError:
+        v = "dev"
+    console.print(f"depscout {v}")
+
+
+def entrypoint():
+    app()

depscout-0.1.0/depscout/config.py

@@ -0,0 +1,26 @@
+import json
+import os
+import pathlib
+
+CONFIG_FILE = pathlib.Path.home() / ".config" / "depscout" / "config.json"
+
+
+def get(key):
+    try:
+        with open(CONFIG_FILE) as f:
+            return json.load(f).get(key)
+    except Exception:
+        return None
+
+
+def set(key, value):
+    CONFIG_FILE.parent.mkdir(parents=True, exist_ok=True)
+    data = {}
+    try:
+        with open(CONFIG_FILE) as f:
+            data = json.load(f)
+    except Exception:
+        pass
+    data[key] = value
+    with open(CONFIG_FILE, "w") as f:
+        json.dump(data, f, indent=2)

depscout-0.1.0/depscout/deps.py

@@ -0,0 +1,133 @@
+import glob
+import hashlib
+import importlib.metadata
+import json
+import os
+import pathlib
+import re
+import tomllib
+
+import httpx
+
+
+def _cache_dir(root: str) -> pathlib.Path:
+    project_hash = hashlib.md5(str(pathlib.Path(root).resolve()).encode()).hexdigest()[:8]
+    return pathlib.Path.home() / ".cache" / "depscout" / project_hash
+
+CACHE_DIR: pathlib.Path | None = None
+DEPS_FILE: str | None = None
+
+
+def _parse_dep_spec(dep_str):
+    dep_str = dep_str.strip()
+    match = re.match(r"^([A-Za-z0-9_.-]+).*?==([A-Za-z0-9_.]+)", dep_str)
+    if match:
+        return match.group(1).lower(), match.group(2)
+    name = re.split(r"[><=!;\[\s]", dep_str)[0].strip().lower()
+    return name, None
+
+
+def _parse_pyproject(path):
+    with open(path, "rb") as f:
+        data = tomllib.load(f)
+    deps = {}
+    for dep in data.get("project", {}).get("dependencies", []):
+        name, version = _parse_dep_spec(dep)
+        if name and name != "python":
+            deps[name] = version
+    return deps
+
+
+def _parse_requirements(path):
+    deps = {}
+    with open(path) as f:
+        for line in f:
+            line = line.strip()
+            if not line or line.startswith("#") or line.startswith("-"):
+                continue
+            name, version = _parse_dep_spec(line)
+            if name:
+                deps[name] = version
+    return deps
+
+
+def _normalize_github_url(url):
+    if not url:
+        return None
+    match = re.search(r"github\.com/([^/]+/[^/\s?#]+)", url)
+    if not match:
+        return None
+    return f"https://github.com/{match.group(1).rstrip('/')}"
+
+
+def _pypi_info(name):
+    try:
+        r = httpx.get(f"https://pypi.org/pypi/{name}/json", timeout=5)
+        if r.status_code == 200:
+            data = r.json()
+            info = data["info"]
+            urls = info.get("project_urls") or {}
+            raw_github = next((u for u in urls.values() if "github.com" in u), None)
+            github_url = _normalize_github_url(raw_github)
+            classifiers = info.get("classifiers") or []
+            dev_status = next((c.split(" :: ")[-1] for c in classifiers if c.startswith("Development Status")), None)
+            latest_files = data["releases"].get(info["version"], [])
+            last_release_date = latest_files[0]["upload_time"][:10] if latest_files else None
+            docs_url = urls.get("Documentation") or urls.get("Docs") or info.get("docs_url")
+            return {
+                "latest": info["version"],
+                "github_url": github_url,
+                "docs_url": docs_url,
+                "summary": info.get("summary"),
+                "description": info.get("description"),
+                "dev_status": dev_status,
+                "last_release_date": last_release_date,
+                "requires_python": info.get("requires_python"),
+                "requires_dist": info.get("requires_dist") or [],
+                "vulnerabilities": data.get("vulnerabilities") or [],
+            }
+    except Exception:
+        pass
+    return None
+
+
+def scan(root="."):
+    global CACHE_DIR, DEPS_FILE
+    CACHE_DIR = _cache_dir(root)
+    DEPS_FILE = str(CACHE_DIR / "deps.json")
+
+    deps_by_name = {}
+
+    pyproject = os.path.join(root, "pyproject.toml")
+    if os.path.exists(pyproject):
+        deps_by_name.update(_parse_pyproject(pyproject))
+
+    for req in glob.glob(os.path.join(root, "requirements*.txt")):
+        deps_by_name.update(_parse_requirements(req))
+
+    deps = {}
+    for name, _ in deps_by_name.items():
+        try:
+            current = importlib.metadata.version(name)
+        except Exception:
+            current = None
+        info = _pypi_info(name)
+        deps[name] = {
+            "current": current,
+            "latest": info["latest"] if info else None,
+            "github_url": info["github_url"] if info else None,
+            "docs_url": info["docs_url"] if info else None,
+            "summary": info["summary"] if info else None,
+            "description": info["description"] if info else None,
+            "dev_status": info["dev_status"] if info else None,
+            "last_release_date": info["last_release_date"] if info else None,
+            "requires_python": info["requires_python"] if info else None,
+            "requires_dist": info["requires_dist"] if info else [],
+            "vulnerabilities": info["vulnerabilities"] if info else [],
+        }
+
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    with open(DEPS_FILE, "w") as f:
+        json.dump(deps, f, indent=4)
+
+    return deps

depscout-0.1.0/depscout/enrich.py

@@ -0,0 +1,111 @@
+import json
+import os
+import base64
+
+import httpx
+
+import depscout.deps as _deps
+from depscout import config as cfg
+
+
+def _github_headers():
+    token = os.environ.get("GITHUB_TOKEN") or cfg.get("github_token")
+    return {"Authorization": f"Bearer {token}"} if token else {}
+
+
+def _github_api(path, params=""):
+    url = f"https://api.github.com/{path.lstrip('/')}{params}"
+    try:
+        r = httpx.get(url, headers=_github_headers(), timeout=5)
+        if r.status_code == 200:
+            return r.json()
+    except Exception:
+        pass
+    return None
+
+
+def _repo_path(github_url):
+    return github_url.replace("https://github.com/", "").rstrip("/")
+
+
+def _fetch_repo_info(github_url):
+    data = _github_api(f"repos/{_repo_path(github_url)}")
+    if not data:
+        return {}
+    return {
+        "github_description": data.get("description"),
+        "stars": data.get("stargazers_count"),
+        "forks": data.get("forks_count"),
+        "open_issues": data.get("open_issues_count"),
+        "license": data["license"]["name"] if data.get("license") else None,
+        "homepage": data.get("homepage"),
+        "topics": data.get("topics") or [],
+        "archived": data.get("archived", False),
+        "pushed_at": (data.get("pushed_at") or "")[:10],
+    }
+
+
+def _fetch_readme(github_url):
+    data = _github_api(f"repos/{_repo_path(github_url)}/readme")
+    if not data or not data.get("content"):
+        return None
+    try:
+        return base64.b64decode(data["content"]).decode("utf-8", errors="ignore")
+    except Exception:
+        return None
+
+
+def _fetch_changelog(github_url, current_version):
+    data = _github_api(f"repos/{_repo_path(github_url)}/releases", "?per_page=50")
+    if not data:
+        return []
+
+    entries = []
+    for release in data:
+        if release.get("draft") or release.get("prerelease"):
+            continue
+        tag = release.get("tag_name", "").lstrip("v")
+        body = release.get("body", "").strip()
+        if tag == current_version:
+            break
+        if tag and body:
+            entries.append({"version": release["tag_name"], "notes": body})
+
+    return entries[:10]
+
+
+def enrich():
+    with open(_deps.DEPS_FILE) as f:
+        deps = json.load(f)
+
+    changed = False
+    for _, info in deps.items():
+        github_url = info.get("github_url")
+        if not github_url:
+            continue
+
+        repo_info = _fetch_repo_info(github_url)
+        if repo_info:
+            info.update(repo_info)
+            changed = True
+
+        readme = _fetch_readme(github_url)
+        if readme is not None:
+            info["github_readme"] = readme
+            changed = True
+
+        current = info.get("current")
+        latest = info.get("latest")
+        is_outdated = current and latest and current != latest
+        already_enriched = "changelog" in info and info.get("changelog_fetched_for_version") == latest
+
+        if is_outdated and not already_enriched:
+            info["changelog"] = _fetch_changelog(github_url, current)
+            info["changelog_fetched_for_version"] = latest
+            changed = True
+
+    if changed:
+        with open(_deps.DEPS_FILE, "w") as f:
+            json.dump(deps, f, indent=4)
+
+    return deps

depscout-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "depscout"
+version = "0.1.0"
+description = "Upgrade intelligence for your Python dependencies"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+
+authors = [
+    { name = "Miguel Soares" }
+]
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+import-names = ["depscout"]
+license-files = ["LICENSE"]
+
+dependencies = [
+    "rich>=14.0.0",
+    "typer>=0.12.0",
+    "httpx>=0.25.0",
+    "ollama>=0.6.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/zemmsoares/depscout"
+Issues = "https://github.com/zemmsoares/depscout/issues"
+
+[project.scripts]
+depscout = "depscout.cli:entrypoint"
+
+[tool.hatch.build.targets.wheel]
+packages = ["depscout"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"