기여하기

기여하기

Pydantic AI에 기여해 주시면 정말 감사해요!

출처: 문서

본문

우리가 일하는 방식 — 짧은 버전

Pydantic AI는 작은 팀이 유지관리해요. 우리는 가장 많은 사용자에게 이익이 되는 것을 기준으로 자체 우선순위를 정하고, 그 순서대로 이슈와 PR을 처리해요. 도착한 순서가 아니라요.

• 버그를 찾았나요? 명확한 설명과 최소 재현 예제로 이슈를 여세요. Logfire 추적 링크를 포함하면 디버깅이 극적으로 빨라져요.
• 기능이나 API 변경을 원하나요? 해결하려는 문제를 묘사하는 이슈를 여세요. 코드로 시작하지 마세요.
• 기능 구축을 돕고 싶나요? 왜 필요하고 어떤 컨텍스트를 가져오는지 설명하며 이슈에 댓글을 달아요. 우리는 이것을 "챔피언(champion)"이 되는 것이라고 불러요. 아래에 더 설명할게요.
• 수정하거나 공유할 코드가 있나요? 유지관리자가 이슈에서 접근 방식에 동의하고 당신에게 배정했는지 확인하세요. 그런 다음 PR을 여세요.

이 페이지의 나머지는 우리가 왜 이렇게 일하는지, 무엇을 기대할 수 있는지 설명해요.

코드를 쓰기 전에

사소하지 않은 어떤 것이든 코드를 쓰기 전에 접근 방식에 대해 유지관리자와 정렬하세요. 미리 정렬된 PR은 우리가 처음 보는 것보다 훨씬 빨리 합류돼요.

사소한 수정

오타, 끊어진 링크, 작은 문서 개선, 명백한 한 줄 수정: 그냥 PR을 여세요. 이슈는 필요 없어요.

버그 수정

수정이 합리적으로 두 가지 이상의 방식으로 갈 수 있거나, 실제로 버그인지 확실하지 않다면: 먼저 이슈를 여세요. 최소 재현 예제와 이상적으로는 문제를 보여주는 Logfire 추적 링크를 포함하세요. 잘 범위가 정해진 버그에 대해서는 우리가 내부에서 수정을 생성할 수 있어요. 당신이 할 수 있는 가장 가치 있는 일은 명확한 보고서를 제출하고 수정이 당신의 사용 사례에서 작동하는지 검증하는 것이에요.

기능, 통합, 또는 API 변경

코드를 쓰기 전에 변경이 코어에 있어야 하는지 물어보세요. 대부분의 새 에이전트 동작은 Pydantic AI Harness, 공식 기능 라이브러리에 속해요. 이 저장소가 아니라요. Pydantic AI 코어는 에이전트 루프, 모델 프로바이더, 그리고 모델별 지원이 필요하거나 에이전트 경험에 기본적인 기능을 위한 거예요. 독립형 기능 — 가드레일, 메모리, 컨텍스트 관리, 파일 시스템 접근 등 — 은 더 빨리 반복할 수 있는 하네스에 속해요. 전체 구별은 무엇이 어디로 가나요?를 참고하세요.

아이디어가 기능이면 pydantic-ai-harness에 이슈를 여세요. pydantic-ai-<name> 규칙을 사용해 기능을 자체 패키지로 게시할 수도 있어요. 기능 패키지 게시 참고. 기능이 실제 사용자와 안정적인 API를 갖게 되면 업스트림(하네스나 코어)으로 올리는 것을 논의할 수 있어요.

코어에 속한다면:

1. 먼저 검색하세요. 기존 이슈가 당신의 필요를 다루면 댓글을 달아요. 가장 가까운 것이 단지 관련만 있다면 새 이슈를 열고 연결하세요.
2. 해결책뿐 아니라 문제를 묘사하세요. 무엇을 만들고 있는지, 무엇이 막히는지, 무엇을 시도했는지 말해 주세요. 이 컨텍스트는 코드보다 더 중요해요.
3. 구축 전에 계획을 제안하세요. 이슈에 짧은 계획을 게시하거나 PLAN.md만 있는 초안 PR을 여세요. 더 큰 기능은 기여자와 설계를 반복하기 위해 짧은 영상 통화를 해요. 20분 통화가 주 단위의 비동기 리뷰 주기를 아낄 수 있어요.
4. 배정을 기다리세요. PR을 열기 전에 유지관리자가 접근 방식에 동의하고 이슈를 당신에게 배정해야 해요. 배정되지 않은 PR은 자동으로 닫힐 수 있어요.

주의

사전 정렬 없이 대형 기능 PR을 쓰는 것은 기여가 지연되거나 닫히는 가장 흔한 이유예요.

챔피언

"챔피언"은 기능이 필요하고, 문제에 대한 컨텍스트가 있으며, 그것을 올바르게 만드는 데 시간을 투자할 의향이 있는 사람이에요. 기능을 챔피언하고 싶다면:

• 이슈에 댓글로: 무엇을 만들고 있는지, 왜 이것이 필요한지, 무엇을 기여할 수 있는지(도메인 지식, 테스팅, 검증)를 설명하세요.
• 우리는 생산 사용 사례를 가진 챔피언이 하나 이상 나선 기능을 우선순위로 둬요. 챔피언이 없는 기능은 우리가 스스로 우선순위를 정하거나 실제 컨텍스트를 가진 사람이 나타날 때까지 백로그에 남아요.
• 챔피언이 되는 것은 코드를 쓰는 것을 뜻하지 않아요. 계획을 다듬고 결과를 검증하는 것을 뜻해요. 중요한 기능에 대해서는 설계를 함께 반복하기 위해 통화를 잡을 거예요.

챔피언은 기능이 출시될 때 공동 저자로 기록돼요.

리뷰 중 기대할 것

우리는 제출 순서가 아니라 우선순위 순서로 PR을 리뷰해요

우리는 모든 새 PR을 자동으로 트라이지하지 않아요. 사전 정렬하지 않은 이슈의 PR은, 아무리 잘 쓰여도 리뷰 큐에 없어요. 유지관리자가 이슈에서 변경에 동의하고 당신에게 배정하지 않았다면 우리가 당신의 PR을 보지 못했다고 가정하세요.

이전에 관여한 코드가 있는 PR조차도: 우리는 모든 기여 코드를 완성품이 아니라 출발점으로 취급해요. 리뷰와 우선순위는 코드에 얼마나 노력이 들었는지가 아니라 그 기능이 프로젝트에 얼마나 중요한지에 근거해요. 이것은 전통적인 오픈소스의 방식과 다른 점이고, 신호 없는 채 PR을 방치해 두기보다 솔직하게 말하는 걸 선호해요.

PR이 어디 있는지 알고 싶다면 가장 좋은 방법은 Pydantic Slack의 #pydantic-ai에 핑하는 거예요.

우리는 당신의 코드를 다시 쓰거나 대체할 수 있어요

우리는 기여 코드를 예시로 취급해요. 제안된 변경을 보여주고 접근 방식이 작동함을 증명하는 출발점이지, 우리가 병합하는 최종 형태가 아니에요. 사소하지 않은 변경에서 가장 유용한 것은 폴리시된 병합 준비 구현이 아니라 계획과 작동하는 예제예요.

어떤 PR에서든 우리는 당신의 브랜치에 커밋을 푸시하거나, 당신의 것을 대체하는 후속 PR을 열거나, 처음부터 다시 쓸 수 있어요. 보안 이유로 우리는 기여 코드를 그대로 병합하기보다 다시 쓰는 쪽을 선호해요. 여전히 원저자로 기록될 거예요.

사전 정렬하지 않은 PR에서는 초록 CI를 쫓거나, 자동 리뷰 댓글마다 대응하거나, 병합 충돌을 위해 리베이스하는 데 노력을 쓰지 마세요. 변경을 앞으로 가져가면 그 폴리시는 우리가 다시 쓸 때 버려져요. 접근 방식을 작동하게 만든 다음 멈추고 Slack에서 핑하세요.

열린 PR에 force-push 업데이트를 하지 마세요. 그 커밋을 다시 쓰면 이전 리뷰가 무효화돼요. 대신 후속 커밋을 푸시하세요. 병합할 때 스쿼시할 거예요.

자동 리뷰는 자문일 뿐 게이트가 아니에요

PR은 Devin과 우리 자체 도구로 자동 리뷰돼요. 이 리뷰는 자문적이에요:

• 봇 승인은 PR이 병합 준비가 됐다는 뜻이 아니에요. 인간 유지관리자의 리뷰만 인정돼요.
• 봇 발견사항은 당신이 행동해야 한다는 뜻이 아니에요. 동의하지 않으면 말하세요.
• 자동 리뷰가 PR에서 노이즈를 만들고 있으면 말해 주세요. 우리가 그 피드백으로 도구를 재조정해요.

우선순위

우리는 리뷰할 수 있는 것보다 훨씬 많은 기여를 받고, 가장 영향이 큰 곳에 집중해요. 모든 PR, 심지어 좋은 것에도 도달하겠다고 약속할 수 없어요. 신호 없는 채 열려 두기보다 미리 말하는 걸 선호해요.

우리가 우선순위를 정하는 방법:

• 사용자 수요 — 더 많은 사용자가 필요로 하는 기능이 우선순위를 받아요. 생산 사용 사례를 가진 챔피언 지원 기능이 추측적 추가보다 위에 서요.
• 프로바이더 중요성 — 프론티어 프로바이더(Anthropic, OpenAI, Google) 또는 우리가 많이 쓰이는 걸 아는 프로바이더에 영향을 주는 작업이 우선순위를 받아요. 틈새 프로바이더를 위한 모델 통합은 기다릴 거예요. Anthropic 수정은 그러지 않아요.
• 로드맵 정렬 — 현재 집중 영역과 정렬되는 기능이 우선순위를 받아요. 지금으로서는 capabilities/hooks API, 프로바이더 적응형 툴, Pydantic AI Harness 기능 라이브러리를 포함해요.
• 코어보다 기능 — 기능으로 살 수 있는 기능은 Pydantic AI Harness로 가거나 자체 패키지로 출시해야 해요. 그것이 종종 가장 빠른 경로예요. 견인력을 얻으면 돌아와서 업스트림을 논의할 수 있어요.

PR이나 이슈가 조용해졌다면

1. Pydantic Slack의 #pydantic-ai에 링크와 함께 핑하세요.
2. 무엇이 필요한지 말하세요. "한번 봐줄 수 있나요?", "막혔어요 — 레이더에 있나요?", "이거 닫을까요?" 모두 괜찮아요.
3. 인간 응답 없이 몇 주를 기다렸다면 플래그하세요. 그것은 우리 쪽 처리 실패이고 우리가 알고 싶어해요.

설치와 설정

포크를 클론하고 repo 디렉토리로 cd하세요:

git clone [email protected]:<your username>/pydantic-ai.git
cd pydantic-ai

uv를 설치하세요. 지원되는 최소 uv 버전은 repository의 pyproject.toml에 있는 tool.uv.required-version이 정해요.

pydantic-ai, 모든 의존성, pre-commit 훅을 설치하세요. pre-commit이 없으면 uv로 그것도 설치해요:

make install

테스트 실행 등

대부분 필요한 명령은 make로 관리해요.

사용 가능한 명령의 자세한 내용은:

make help

코드 포맷팅, 린팅, 정적 타입 검사, 커버리지 리포트 생성과 함께 테스트를 실행하려면:

make

타입 검사

make typecheck는 프로젝트의 모든 파일에 대해 Pyright를 실행해요.

pre-commit 훅은 대신 make typecheck-changed를 실행하는데, Pyright가 마지막으로 통과한 이후 내용이 바뀐 파일과 그것을 전이적으로 import하는 모든 것을 검사해요. git 디렉토리 아래에 통과한 것을 기록하므로 기록은 워크트리별이고 절대 커밋되지 않아요.

CI는 그 같은 훅을 실행하고, 실행할 때마다 모든 것을 검사해요. GitHub Actions는 항상 CI를 설정하므로, 그것이 보이면 make typecheck-changed는 아무것도 좁히지 않고 전체 프로젝트를 make typecheck-pyright에 넘겨요. 새 러너는 좁힐 기록이 애초에 없어요. CI는 Pyright가 읽는 아무것도 건드리지 않는 풀 리퀘스트에서는 여전히 이전처럼 훅을 완전히 건너뛰고, 기록된 실행 이후 바뀌지 않은 tests/ 아래 파일은 절대 검사하지 않아요.

로컬에서는 Pyright가 정적으로 해석하는 import를 따르고, 기록된 이후 바뀌지 않은 tests/ 파일은 검사하지 않아요. 라이브러리 변경이 테스트 파일의 타입을 깨뜨리는 경우를 위한 게이트는 CI예요. 좁힘을 불완전하게 만들 수 있는 것이 있으면(첫 실행, 새 Pyright/Python 버전, pyproject.toml/uv.lock/Makefile 변경, 다른 파일로 해석되는 import, 설치된 것을 가릴 새 최상위 모듈, 프로젝트 절반 이상에 닿는 변경) 좁히기를 포기하고 Pyright가 보고하는 모든 추적 파일에 대해 실행해요. 전체 프로젝트를 make typecheck-pyright에 넘기는 것은 CI, Python 3.11 이전 인터프리터, 재현할 수 없는 Pyright 구성뿐이에요.

가득한 실행은 PYRIGHT_THREADS가 다르게 말하지 않는 한 단일 프로세스예요. CI가 그것을 auto로 설정해요. 이 변수는 Pyright의 병렬 검사 단계를 켜는데, 같은 진단을 더 짧은 벽 시계로 도달해요. auto는 논리 코어당 최대 한 워커, 양의 정수는 상한을 둬요. make typecheck-pyright만 읽어서 훅은 전체 프로젝트를 넘기는 실행(CI, Python 3.11 이전 인터프리터, 재현할 수 없는 Pyright 구성)에서만 그것을 채택해요.

export PYRIGHT_THREADS=auto

명령당 설정하지 말고 export하세요. 모든 make typecheck가 채택하도록요. 각 워커는 전체 Node 프로세스라서, 그것들을 담을 메모리가 있는 머신에서만 제 몫을 해요. 이미 한계에 가까운 것은 스왑해 기본보다 느려져요. 변수를 해제하거나 1로 설정하면 단일 프로세스로 돌아가요. Pyright가 양의 정수로 읽을 수 없는 것(0, off 포함)은 auto를 의미해요.

문서 변경

docs/navigation.yml이 Pydantic AI 문서의 사이드바, 공개 라우트, 리다이렉트를 소유해요. 페이지를 추가·제거·이동할 때 업데이트하세요.

docs/navigation.yml의 모든 라우트는 Pydantic AI 문서 루트에 상대적이에요. 각 페이지에 완전한 canonical 라우트를 slug로 주고, aliases는 리다이렉트 소스에만 사용하세요. 둘 다 /ai나 앞 슬래시로 시작하지 마세요.

내비게이션 변경을 검증하려면 유지관리자에게 풀 리퀘스트에 trigger:docs 라벨을 추가해 달라고 하세요. 이것은 pydantic/unified-docs에서 내비게이션 매니페스트, 참조되는 Markdown 파일, 라우트, 별칭, 리다이렉트를 검사하고 결과를 PR에 게시해요. 렌더링된 미리보기를 구축하지 않아요.

CI는 문서 페이지 사이의 모든 링크(앵커 포함)가 해석되는지 검사하고 Cannot find fragment에서 실패해요. 헤딩의 앵커는 그것의 텍스트에서 생성되므로, 하나를 이름 바꾸면 그것을 가리키는 모든 링크가 조용히 끊겨요. 헤딩이 링크되는 곳에서는 {#custom-id}로 그 앵커를 고정하세요. 그러면 헤딩 텍스트는 앵커를 옮기지 않고 바뀔 수 있어요.

Pydantic AI에 새 모델 추가 규칙

Pydantic AI 유지관리자의 과도한 워크로드를 피하기 위해, 모든 모델 기여를 받아들일 수는 없어요. 그래서 새 모델을 언제 받고 받지 않을지에 대한 다음 규칙을 정해요. 이것이 실망과 낭비된 작업의 가능성을 줄이길 바래요.

• 추가 의존성이 있는 새 모델을 추가하려면, 그 의존성이 PyPI에서 3개월 이상 지속적으로 월 다운로드 50만+ 필요해요.
• 다른 모델의 로직을 내부적으로 사용하고 추가 의존성이 없는 새 모델을 추가하려면, 그 모델의 GitHub 조직이 총 2만+ 별 필요해요.
• 그저 커스텀 URL과 API 키인 다른 어떤 모델에 대해서는, 사용할 URL에 대한 링크와 지시문이 있는 한 단락 설명을 추가하게 되어 기뻐요.
• 더 많은 로직이 필요한 다른 어떤 모델에 대해서는, pydantic-ai-slim에 의존하고 우리의 Model ABC를 상속하는 모델을 구현하는 자체 Python 패키지 pydantic-ai-xxx를 릴리스할 것을 권장해요.

모델 추가에 대해 확실하지 않으면 이슈를 만들어 주세요.

더 알아보기 (Learn more)

• Pydantic AI 문서 홈
• Pydantic AI 저장소