chore: replace poetry with uv

Migrate the project from Poetry to uv for dependency management and
environment handling. This includes updating the build system,
configuration files, and CI/CD workflows.

- Replace `pyproject.toml` Poetry configuration with PEP 621 `[project]`
  and PEP 735 `[dependency-groups]` metadata.
- Update `Dockerfile` to use `uv` for installing dependencies.
- Update GitHub Actions workflow to use `astral-sh/setup-uv`.
- Update documentation (README, MIGRATION_STATUS, UPGRADE_PLAN) to
  reflect `uv sync` and `uv run` commands.
- Update all test scripts, examples, and internal error messages to
  use `uv` instead of `poetry`.
- Switch build backend from `poetry-core` to `hatchling`.

Author: kodzonko

.github/workflows/ci.yml

@@ -16,47 +16,33 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-
-      - name: Install Poetry
-        uses: snok/install-poetry@v1
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
         with:
-          virtualenvs-create: true
-          virtualenvs-in-project: true
+          enable-cache: true
 
-      - name: Load cached venv
-        id: cached-poetry-dependencies
-        uses: actions/cache@v4
-        with:
-          path: .venv
-          key: venv-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
 
       - name: Install dependencies
-        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
-        run: poetry install --no-interaction --no-root
-
-      - name: Install project
-        run: poetry install --no-interaction
+        run: uv sync --locked --python ${{ matrix.python-version }}
 
       - name: Run linting
-        run: poetry run black --check src tests
+        run: uv run black --check src tests
 
       - name: Type checking
-        run: poetry run mypy src --ignore-missing-imports
+        run: uv run mypy src --ignore-missing-imports
         continue-on-error: true
 
       - name: Security scan
-        run: poetry run bandit -r src/ -ll -x tests
+        run: uv run bandit -r src/ -ll -x tests
 
       - name: Dependency vulnerability scan
-        run: poetry run safety check || true
+        run: uv run safety check || true
         continue-on-error: true
 
       - name: Run tests
-        run: poetry run pytest tests/ -v --cov=src --cov-report=xml --cov-report=term-missing
+        run: uv run pytest tests/ -v --cov=src --cov-report=xml --cov-report=term-missing
 
       - name: Upload coverage to Codecov
         if: matrix.python-version == '3.11'

Dockerfile

@@ -1,15 +1,10 @@
 FROM python:3.12-slim
 
-# Install system deps (curl for Poetry installer)
-RUN apt-get update && apt-get install -y \
-    curl \
-    && rm -rf /var/lib/apt/lists/*
+# Install uv by copying its static binaries from the official image (pinned tag).
+COPY --from=ghcr.io/astral-sh/uv:0.11.19 /uv /uvx /bin/
 
-# Install Poetry globally
-RUN curl -sSL https://install.python-poetry.org | python3 -
-
-# Add Poetry to PATH
-ENV PATH="/root/.local/bin:${PATH}"
+# Copy files into the container as the root user by default.
+ENV UV_LINK_MODE=copy
 
 # Note: Claude Code CLI is bundled with claude-agent-sdk >= 0.1.8
 # No separate Node.js/npm installation required
@@ -20,11 +15,13 @@ COPY . /app
 # Set working directory
 WORKDIR /app
 
-# Install Python dependencies with Poetry
-RUN poetry install --no-root
+# Install Python dependencies with uv into a project-local virtual environment.
+# `--locked` fails the build if uv.lock is out of date with pyproject.toml (rather than
+# silently using a stale lock); `--no-dev` skips dev-only tooling.
+RUN uv sync --locked --no-dev
 
 # Expose the port (default 8000)
 EXPOSE 8000
 
 # Run the app with Uvicorn (development mode with reload; switch to --no-reload for prod)
-CMD ["poetry", "run", "uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]
+CMD ["uv", "run", "uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]