0009. Hạ cấp pydantic-ai 2.0 → 1.x (và giới hạn pydantic/click) để tích hợp runtime Kitaru

Trạng thái: Đã chấp nhận Ngày: 2026-06-28

Bối cảnh

ADR-0008 đã chọn Kitaru để có runtime bền bỉ (nhiệm vụ 057-062). Việc thực hiện ngay lập tức đạt được một tường cứng: kitaru 0.18.0 (bản phát hành mới nhất) không thể đồng giải quyết với các chân lõi của bộ decode. Kitaru kéo vào zenml[local]>=0.95.1 cộng với bộ chuyển đổi PydanticAI của nó, áp đặt một chuỗi giới hạn trên ngăn xếp decode tinh gọn vi phạm:

Không có tập hợp con bổ sung nào và không có kitaru mới hơn/trước phát hành nào được giải quyết — kitaru's KitaruAgent bộ chuyển đổi, cái nào ADR-0008 phụ thuộc vào, chỉ hỗ trợ decode pydantic-ai 1.x. được áp dụng pydantic-ai 2.0 một cách có chủ ý ( vòng lặp agent + capstone M1 được xây dựng trên đó), vì vậy đây là một ngã ba chính hãng, nổi lên ở /implement-night cổng: hạ cấp dự án, cô lập kitaru trong môi trường riêng của nó hoặc trì hoãn. Quyết định (do con người kiểm soát) đã hạ cấp.

Một mức tăng đột biến đã đo lường chi phí thực tế trước khi cam kết:

• Độ phân giải hội tụ sau khi quay lui pydantic→2.12, pydantic-ai→1.x, click→8.2, starlette→0.49, và thả kitaru mcp thêm (nó xung đột với mcp của chính pydantic-ai).
• Nó kéo theo ~40 gói chuyển tiếp — zenml, temporalio, sqlalchemy, sqlmodel, tokenizers, xai-sdk, … - một dấu ấn lớn đối với một CLI được "cố tình giữ ánh sáng".
• Sự cố mã nhỏ và tập trung: 51 bài kiểm tra đơn vị, chia sẻ một số API pydantic-ai 1.x↔2.0 miếng chêm. Tất cả các mô-đun lõi vẫn được nhập hoàn toàn dưới 1.x; sự phá vỡ chiếm ưu thế là usage API — 2.0 run.result.usage.input_tokens (thuộc tính) là 1.x run.usage() với request_tokens/response_tokens. Các lỗi tập hợp hoàn toàn trong vòng lặp agent / công cụ thông qua- đường dẫn agent/app-e2e dẫn đến một bước ngoặt thực sự.

Quyết định

1. Ghim vào các phạm vi tương thích với kitaru trong pyproject.toml: pydantic>=2.0,<2.13, pydantic-ai-slim[google,openai]>=1.95,<1.96, click>=8.1,<8.3; thêm kitaru[local,pydantic-ai,llm]>=0.18.0. uv.lock chụp cây được giải quyết đầy đủ.

   Sửa đổi (28-06-2026, nhiệm vụ 058). Mã pin này ban đầu được sử dụng pydantic-ai>=1.89,<1.104 — cái meta pydantic-ai gói. Điều đó đã sai: gói meta kéo thêm mọi nhà cung cấp (mistral/temporal/…), và mistral phần bổ sung bị kéo mistralai giải phóng giới hạn trình phân giải tại pydantic-ai-slim 1.94.0 — mà ** có trước ngày pydantic_ai.tools.AgentNativeTool**, một biểu tượng kitaru's KitaruAgent nhập bộ chuyển đổi khi tải. Vì vậy, cây bị khóa thậm chí không thể nhập bộ chuyển đổi ADR-0008 phụ thuộc vào (sự tăng đột biến về chải chuốt đã đo lường chi phí thử nghiệm của việc hạ cấp nhưng không bao giờ đã nhập khẩu KitaruAgent). Cách khắc phục: phụ thuộc vào pydantic-ai-slim[google,openai] - chỉ sử dụng decode các lớp mô hình gemini + openai/openrouter — và tăng giá lên 1,95 (phiên bản đầu tiên với AgentNativeTool). Giải quyết thành 1.95.1: nhập bộ điều hợp, bộ đầy đủ vẫn có màu xanh, và ~40 lỗi chuyển tiếp không cần thiết (temporalio/xai-sdk/mcp/tokenizers/…) bị loại bỏ. Giới hạn <1.96 vì 1.99+ phá vỡ lại 51 thử nghiệm vòng lặp agent (độ lệch API 1.x↔1.x, cùng loại với bản gốc hạ cấp). Đạt được cam kết của nhiệm vụ 058, hoàn thiện nhiệm vụ 063.

2. Bỏ kitaru xuống mcp thêm. Nó ghim mcp 1.19.x chống lại pydantic-ai mcp >=1.24. decode có không có tính năng MCP cho đến bước 15; hãy xem lại phần bổ sung (hoặc một bộ kitaru tương thích) sau đó.

3. Sửa chữa vòng lặp agent cho pydantic-ai 1.x, ở mức tối thiểu và tập trung. Sửa lỗi usage truy cập vào agent/loop.py (và bất kỳ miếng chêm 1.x anh chị em nào) đằng sau bề mặt công khai hiện có của decode — last_input_tokens thuộc tính vẫn ổn định để kích hoạt nén ADR-0006 và bối cảnh nhiệm vụ-047 máy đo tiếp tục hoạt động bình thường. không viết lại vòng lặp; 51 thất bại sụp đổ chỉ còn một số ít nguyên nhân gốc rễ.

4. Chấp nhận dấu chân chuyển tiếp nặng (zenml/temporalio/sqlalchemy/…) như chi phí vốn có của kitaru dựa trên zenml - được ghi lại một cách trung thực ở đây thay vì ẩn.

Sơ đồ

flowchart TB
    subgraph before["BEFORE — lean, pydantic-ai 2.0"]
        b1["pydantic 2.13 · pydantic-ai 2.0 · click 8.4<br/>~12 runtime deps"]
    end
    subgraph fork["fork at the /implement-night gate"]
        d{{"kitaru 0.18 needs pydantic-ai 1.x<br/>+ zenml caps pydantic/click"}}
    end
    subgraph after["AFTER — downgrade (this ADR)"]
        a1["pydantic 2.12 · pydantic-ai 1.x · click 8.2 · starlette 0.49<br/>+ kitaru → zenml · temporalio · sqlalchemy … (~40 pkgs)<br/>mcp extra dropped"]
        a2["agent/loop.py: usage shim (1.x run.usage())<br/>last_input_tokens surface unchanged · 51 tests repaired"]
        a1 --> a2
    end
    b1 --> d -->|chosen: downgrade| a1

    classDef before fill:#1565c0,stroke:#0d47a1,color:#ffffff;
    classDef forkc fill:#e65100,stroke:#bf360c,color:#ffffff;
    classDef after fill:#2e7d32,stroke:#1b5e20,color:#ffffff;
    class b1 before;
    class d forkc;
    class a1,a2 after;

hậu quả

• Bước 7 được bỏ chặn — cài đặt kitaru và các tác vụ 057-062 đang được xây dựng dựa trên các tác vụ tương tự build_agent() (hiện tại không cần cách ly quy trình con).
• Chi phí sử dụng là có thật và được ghi lại. cây runtime của decode tăng từ ~12 điểm lên một ngăn xếp lớp zenml/temporalio; bốn thư viện được khôi phục; cái mcp thêm được hoãn lại. Đây là giá của kitaru; ghi chú "có mục đích giữ ánh sáng" trong pyproject.toml không còn hoàn toàn đúng cho đường dẫn runtime. (Nhiệm vụ đã sửa đổi 058: chuyển từ meta pydantic-ai gói để pydantic-ai-slim[google,openai] — xem Quyết định §1 — loại bỏ ~40 trong số các giá trị chuyển tiếp đó, do đó hồi quy dấu chân nhỏ hơn đáng kể so với ghi nhận đầu tiên.)
• Cần sửa lại tuyên bố về sự phụ thuộc (nhiệm vụ 058). Mức tăng đột biến về chải chuốt của ADR này đã khẳng định hạ cấp "giải quyết" và bộ điều hợp hoạt động nhưng không bao giờ được nhập KitaruAgent. Giảm rủi ro cho nhiệm vụ 058 đã tìm thấy gói meta bị khóa pydantic-ai 1.94.0 thiếu AgentNativeTool và không thể nhập bộ chuyển đổi nào cả; chốt gói mỏng (Quyết định §1) là giải pháp khắc phục. Bài học: phải có ADR phụ thuộc thực hiện đường dẫn nhập thực tế của thứ mà nó bỏ chặn, không chỉ chạy lại bộ ứng dụng hiện có.
• Chỉ sửa chữa nhỏ chứ không phải viết lại. 51 thử nghiệm thất bại chia sẻ một vài miếng chêm API 1.x, giới hạn trong agent/loop.py đằng sau một bề mặt công cộng ổn định; 872 bài kiểm tra đã có màu xanh dưới 1.x.
• Mức trần mới. Cho đến khi kitaru hỗ trợ pydantic-ai 2.x, bộ decode không thể áp dụng pydantic-ai 2.x các tính năng và bước MCP (15) phải sử dụng kết hợp kitaru/mcp để giải quyết. sự cô lập fork (chạy runtime headless trong env pydantic-ai-1.x của chính nó trong khi TUI vẫn ở mức 2.0) vẫn là lối thoát được ghi lại nếu việc hạ cấp chung trở nên không thể thực hiện được.
• Có thể đảo ngược. Thay đổi là chân + uv.lock + miếng chêm vòng hạn chế; hoàn nguyên là git revert của nhiệm vụ 063 + uv sync. Thiết kế của ADR-0008 không bị ảnh hưởng - chỉ có sàn phiên bản được di chuyển.

Không có mục tiêu

• Cô lập kitaru trong một quy trình/venv riêng biệt (ngã ba thay thế — hoãn lại, giữ làm lối thoát nở).
• Khôi phục pydantic-ai 2.0 (bị chặn cho đến khi kitaru bắt kịp).
• Kitaru mcp thêm (xem lại ở bước 15).