update-deps

name	update-deps
description	Update this GraphRAG uv-workspace monorepo's dependencies and repair the resulting breakages so every check and test passes again. Use when asked to update, upgrade, or bump dependencies/packages/versions, refresh or regenerate the lockfile, migrate to a new major of pandas/numpy/pydantic/pyarrow, resolve dependency-related test or lint failures, or run a "dependency sweep" — even if the user only names a single package. Covers editing pyproject.toml version specifiers across the root dev-deps and every packages/* member, re-locking with uv, and fixing code and tests for library API changes (e.g. pandas 3.0). USE FOR: update dependencies, upgrade packages, bump versions, dependency sweep, uv lock, uv sync, refresh lockfile, migrate pandas/numpy, "deps broke the tests", pyproject bump.
user-invocable	true

Update Dependencies (GraphRAG monorepo)

Goal

Raise dependency versions across this uv workspace, re-lock, and fix any code or test fallout until uv run poe check and uv run poe test_unit are both green — without touching the version machinery that the release process owns.

Hard rules (non-negotiable)

1. Only the Microsoft feed proxy. All resolves and syncs MUST use https://packagefeedproxy.microsoft.io/pypi/simple (the [[tool.uv.index]] configured in the root pyproject.toml). Never resolve against public PyPI, never add --index/--default-index/--index-url overrides, and never set UV_INDEX_URL or PIP_INDEX_URL to pypi.org. Do not disable or reorder the configured index.
2. Target versions must be at least 7 days old. Only bump to a version that was released more than 7 days ago. The proxy does not serve versions published within the last week — syncing to a too-new version WILL fail. Before pinning a specific version, verify its release date and pick the newest release older than 7 days; otherwise let the specifier float and let uv lock choose (it can only see eligible versions on the proxy anyway).

Layout facts

• This is a uv workspace monorepo. The root pyproject.toml holds the dev group under [dependency-groups] and the [tool.poe.tasks] commands.
• Runtime dependencies live in each member's packages/*/pyproject.toml under [project] dependencies.
• Workspace members are wired via [tool.uv.sources] ({ workspace = true }) and pinned to each other with graphrag-*==X.Y.Z lines.
• Package resolution goes through a Microsoft-internal index ([[tool.uv.index]]); expect that feed to be used, not public PyPI directly.

Do NOT edit these (release-owned)

1. Cross-package pins graphrag-cache==..., graphrag-llm==..., etc. in any package. These are rewritten automatically by scripts/update_workspace_dependency_versions.py from the semversioner version. Hand-editing them causes drift.
2. [project] version fields — managed by semversioner ("do not change the version here manually").
3. graspologic-native>=1.2,<1.3 — held below 1.3 on purpose; 1.3.x changes Leiden clustering output and breaks golden regression data. Only bump with a deliberate golden-data refresh, and say so explicitly.

Process

1. Baseline first. Confirm a clean working tree and that checks/tests already pass before changing anything, so later failures are attributable to the bump:

   • uv run poe check
   • uv run poe test_unit Prefer a dedicated branch (e.g. dep-sweep).

2. Decide the scope. Either a targeted set of packages the user named, or a full sweep. Edit the ~=/>=/< specifiers in the relevant [project] dependencies (packages/*/pyproject.toml) and the root dev group. Leave the release-owned lines above untouched.

3. Resolve and lock. All of these use the configured Microsoft feed proxy — do not pass any index override (see Hard rules).

   • For a full "get latest allowed" pass: uv lock --upgrade.
   • For targeted bumps after editing specifiers: uv lock.
   • Then install: uv sync --all-packages. If resolution fails, read the conflict, relax/adjust the offending specifier, and re-lock. Do not delete uv.lock to force it.
   • If a sync fails to find a version you just pinned, it is almost certainly younger than 7 days on the proxy — step down to the newest release older than one week.

4. Static checks. Run uv run poe check (this is ruff format --check + ruff check + pyright). Apply safe autofixes with uv run poe fix; format with uv run poe format. Fix remaining lint/type errors by hand — see Gotchas and the migration reference.

5. Tests. Run uv run poe test_unit (NOT uv run poe test, which runs the full coverage suite). Run uv run poe test_verbs and uv run poe test_integration when the change is broad or touches indexing/query. Investigate every new failure.

6. Repair breakages. For test/type failures caused by a library's API change, load references/migration-gotchas.md and apply the documented pattern. Keep fixes minimal and consistent with sibling code; prefer a real fix over a # noqa.

Gotchas (this repo)

• test_unit, not test. poe test runs coverage over everything and is slow; use test_unit for the fast feedback loop.
• Ruff runs in preview mode (preview = true, target-version = "py310"). Preview-only rules such as RUF069 (float equality) and ASYNC119 fire here even though they may not in other repos.
• Known pre-existing flake: tests/unit/indexing/test_profiling.py::TestWorkflowProfiler::test_handles_exception_in_context is timing-sensitive and can fail intermittently — it is not a dependency regression.
• uv sync --all-packages (not bare uv sync) to install every workspace member.
• pandas is on the 3.0 line and numpy on 2.x. Their major-version API changes are the usual source of post-bump breakage — see the reference file.
• Version-bump edits touch many pyproject.toml files; make sure you did not accidentally modify a graphrag-*== pin or a version field while editing nearby specifiers.

Load-on-demand reference

When a bump breaks tests or type-checking with a library API change (especially pandas or numpy), read references/migration-gotchas.md for verified, repo-specific fix patterns before improvising.

Completion checklist

• All resolves/syncs used the packagefeedproxy.microsoft.io index; no public-PyPI or index-override was introduced.
• No dependency was bumped to a version released within the last 7 days.
• Only intended specifiers changed; no graphrag-*== pin or version field edited.
• uv.lock regenerated via uv lock/uv lock --upgrade (not hand-edited or deleted).
• uv run poe check passes (ruff format, ruff lint, pyright).
• uv run poe test_unit passes (ignoring only the known profiling flake).
• Broader suites run if the change was broad (test_verbs/test_integration).
• A semversioner changelog entry was added.
• Any risky/held pin (e.g. graspologic-native) left in place unless explicitly bumped.