LangChain Python 모노레포 아키텍처 분석 보고서

╔══════════════════════════════════════════════════════════════════════════╗
║                         LangChain 시스템                                 ║
║                                                                          ║
║  ┌─────────────────────────────────────────────────────────────────┐    ║
║  │                    애플리케이션 레이어                             │    ║
║  │  사용자 코드 / LangGraph 그래프 / LangServe API 서버              │    ║
║  └───────────────────────┬─────────────────────────────────────────┘    ║
║                          │ 호출                                          ║
║  ┌───────────────────────▼─────────────────────────────────────────┐    ║
║  │                langchain (메인 패키지)                            │    ║
║  │                                                                  │    ║
║  │  agents/ ──┬── chains/         retrievers/ ── memory/           │    ║
║  │            ├── tools/          embeddings/ ── callbacks/        │    ║
║  │            ├── llms/           vectorstores/── output_parsers/  │    ║
║  │            └── document_loaders/                                │    ║
║  └──────────────────────┬──────────────────────────────────────────┘    ║
║                         │ 상속/구현                                       ║
║  ┌──────────────────────▼──────────────────────────────────────────┐    ║
║  │                langchain-core (기반 레이어)                       │    ║
║  │                                                                  │    ║
║  │  Runnable ──┬── BaseLanguageModel (BaseLLM / BaseChatModel)     │    ║
║  │  Protocol   ├── BaseRetriever                                    │    ║
║  │             ├── BaseTool                                         │    ║
║  │             ├── VectorStore                                      │    ║
║  │             ├── BasePromptTemplate                               │    ║
║  │             ├── BaseOutputParser                                 │    ║
║  │             └── CallbackManager                                  │    ║
║  └──────────┬─────────────────────────────────┬─────────────────────┘    ║
║             │ 구현                              │ 구현                      ║
║             ▼                                  ▼                          ║
║  ┌──────────────────────┐         ┌────────────────────────────────────┐  ║
║  │   파트너 패키지 (15개) │         │         외부 서비스                  │  ║
║  │                      │         │                                    │  ║
║  │  langchain-openai    │         │  OpenAI / Anthropic / Google       │  ║
║  │  langchain-anthropic │  ──────▶│  Groq / Mistral / HuggingFace     │  ║
║  │  langchain-ollama    │         │  Chroma / Qdrant / LangSmith       │  ║
║  │  langchain-chroma    │         │  (로컬 모델 포함)                    │  ║
║  │  + 11개 추가          │         └────────────────────────────────────┘  ║
║  └──────────────────────┘                                                ║
╚══════════════════════════════════════════════════════════════════════════╝

langchain/ (모노레포 루트)
├── libs/
│   ├── core/                # langchain-core v1.2.18 — 기반 추상화
│   ├── langchain_v1/        # langchain v1.2.12 — 활성 메인 패키지
│   ├── langchain/           # langchain-classic v1.0.2 — 레거시 (유지보수 모드)
│   ├── partners/            # 15개 파트너 통합 패키지
│   │   ├── openai/
│   │   ├── anthropic/
│   │   ├── ollama/
│   │   ├── groq/
│   │   ├── mistralai/
│   │   ├── huggingface/
│   │   ├── chroma/
│   │   ├── qdrant/
│   │   └── ... (7개 추가)
│   ├── text-splitters/      # langchain-text-splitters v1.1.1
│   ├── standard-tests/      # langchain-tests v1.1.5 — 공유 테스트 슈트
│   └── model-profiles/      # 모델 설정 프로파일 관리
└── .github/
    └── workflows/           # 19개+ CI/CD 워크플로우

partners/{provider}/
├── pyproject.toml                  # 패키지 메타데이터
├── langchain_{provider}/
│   ├── __init__.py
│   ├── chat_models.py              # ChatModel 구현체
│   ├── llms.py                     # LLM 구현체
│   ├── embeddings.py               # 임베딩 구현체
│   ├── output_parsers/             # 커스텀 출력 파서
│   ├── tools/                      # 도구 통합
│   └── data/                       # 모델 프로파일 JSON
├── tests/
│   ├── unit_tests/
│   └── integration_tests/
├── Makefile
└── uv.lock

class Runnable[Input, Output](ABC, Generic[Input, Output]):
    """범용 호출 프로토콜 — 모든 LangChain 컴포넌트의 기반"""

    # 동기 인터페이스
    def invoke(self, input: Input, config: RunnableConfig) -> Output: ...
    def batch(self, inputs: list[Input]) -> list[Output]: ...
    def stream(self, input: Input) -> Iterator[Output]: ...

    # 비동기 인터페이스
    async def ainvoke(self, input: Input) -> Output: ...
    async def abatch(self, inputs: list[Input]) -> list[Output]: ...
    async def astream(self, input: Input) -> AsyncIterator[Output]: ...

    # 고급 스트리밍
    async def astream_log(self, input: Input) -> AsyncIterator[RunLogPatch]: ...
    async def astream_events(self, input: Input) -> AsyncIterator[StreamEvent]: ...

    # 조합 연산자
    def pipe(self, other: Runnable) -> RunnableSequence: ...
    def __or__(self, other: Runnable) -> RunnableSequence: ...  # | 연산자

    # 설정 변형
    def with_config(self, config: RunnableConfig) -> Runnable: ...
    def with_fallbacks(self, fallbacks: list[Runnable]) -> RunnableWithFallbacks: ...
    def with_retry(self, ...) -> RunnableRetry: ...
    def configurable_fields(...) -> RunnableConfigurableFields: ...

# LangChain Expression Language (LCEL)
chain = (
    {"context": retriever, "question": RunnablePassthrough()}
    | prompt
    | llm
    | output_parser
)

# 동기/비동기 동일 인터페이스
result = chain.invoke("사용자 질문")
result = await chain.ainvoke("사용자 질문")

# 스트리밍
for chunk in chain.stream("사용자 질문"):
    print(chunk, end="", flush=True)

[Runnable.invoke() 호출]
        │
        ▼
CallbackManager
  ├── on_llm_start(serialized, prompts)     ← LLM 호출 시작
  │       │ 스트리밍
  │       ▼
  ├── on_llm_new_token(token)               ← 토큰 수신 (스트리밍)
  │       │ 완료
  │       ▼
  ├── on_llm_end(response)                  ← LLM 응답 완료
  │
  ├── on_tool_start(tool, input)            ← 도구 실행 시작
  ├── on_tool_end(output)                   ← 도구 실행 완료
  │
  ├── on_retriever_start(query)             ← 검색 시작
  ├── on_retriever_end(documents)           ← 검색 완료
  │
  └── → LangSmithTracer / 커스텀 핸들러

BaseMessage(Serializable)
├── content: str | list[BaseMessageContentBlock]
│   # BaseMessageContentBlock:
│   # - TextContentBlock    → 텍스트
│   # - ImageContentBlock   → 이미지 (멀티모달)
│   # - FileContentBlock    → 파일 첨부
│   # - ToolUseBlock        → 도구 호출 요청
│   # - ToolCallBlock       → 도구 호출 결과
│
├── HumanMessage      ← 사용자 입력
├── AIMessage         ← 모델 응답 (tool_calls 포함)
│   └── AIMessageChunk  ← 스트리밍 조각
├── SystemMessage     ← 시스템 지시
├── ToolMessage       ← 도구 실행 결과
└── FunctionMessage   ← (레거시, deprecated)

BaseLanguageModel (Runnable[LanguageModelInput, str])
├── BaseLLM                       ← 텍스트 완성 (레거시)
│   └── invoke(str) -> str
│
└── BaseChatModel                 ← 채팅 인터페이스 (현재 표준)
    ├── invoke(List[BaseMessage]) -> AIMessage
    ├── stream()  -> Iterator[AIMessageChunk]
    └── with_structured_output()  → Pydantic 모델 출력

BaseTool (RunnableSerializable[ToolInput, ToolOutput])
├── name: str
├── description: str
├── args_schema: Type[BaseModel]         ← Pydantic 스키마
│
├── StructuredTool                       ← Pydantic 기반
├── Tool                                 ← 함수 기반
└── ToolCollection                       ← 다중 도구 묶음

Document(BaseModel)
├── page_content: str          ← 문서 내용
└── metadata: dict             ← 출처, 날짜 등

langchain (v1.2.12)
├── langchain-core (≥1.2.10)
├── langgraph (≥1.1.1)
└── pydantic (≥2.7.4)

langchain-core (v1.2.18)
├── langsmith (≥0.3.45)       ← 관측
├── tenacity (≥8.1.0)         ← 재시도
├── pydantic (≥2.7.4)         ← 직렬화
├── PyYAML                     ← 설정
└── typing-extensions

langchain-classic (v1.0.2)    ← 레거시
├── langchain-core
├── langchain-text-splitters
└── SQLAlchemy, requests

langchain-{provider}          ← 파트너 패키지
├── langchain-core
├── {provider-sdk}             ← openai≥2.26.0, anthropic SDK 등
└── tiktoken (OpenAI 전용)

langchain-tests (v1.1.5)      ← 테스트 슈트
├── langchain-core
├── pytest, pytest-asyncio
└── httpx, vcrpy

make lock          # uv.lock 재생성
make check-lock    # 락파일 최신 여부 검증
make test          # 단위 테스트 실행 (네트워크 없음)
make lint          # ruff로 코드 린팅
make format        # ruff로 코드 포매팅
make spell_check   # 오탈자 검사

# 테스트 그룹 설치
uv sync --group test

# 전체 그룹 설치
uv sync --all-groups

# 특정 테스트 실행
uv run --group test pytest tests/unit_tests/test_specific.py

# 타입 체킹
uv run --group lint mypy .

# 각 패키지의 pyproject.toml
[tool.uv.sources]
langchain-core = { path = "../core", editable = true }
langchain-tests = { path = "../standard-tests", editable = true }

feat(scope): 새 기능 추가
fix(scope): 버그 수정
chore(scope): 인프라 변경
docs(scope): 문서 수정
refactor(scope): 리팩토링
test(scope): 테스트 추가/수정

예시:
- feat(core): add streaming support to Runnable
- fix(openai): handle rate limit errors gracefully
- chore(anthropic): update infrastructure dependencies

langchain/
├── libs/
│   ├── core/
│   │   ├── langchain_core/
│   │   │   ├── runnables/          # 18개 파일 (base.py 222KB)
│   │   │   ├── language_models/
│   │   │   ├── callbacks/          # manager.py 85KB+
│   │   │   ├── messages/           # 14개 파일
│   │   │   ├── prompts/            # 14개 파일
│   │   │   ├── tools/              # 6개 파일
│   │   │   ├── output_parsers/     # 13개 파일
│   │   │   ├── vectorstores/
│   │   │   ├── retrievers.py
│   │   │   ├── embeddings/
│   │   │   ├── load/               # 4개 파일
│   │   │   ├── tracers/
│   │   │   └── utils/              # 17개 모듈
│   │   └── pyproject.toml
│   │
│   ├── langchain_v1/
│   │   ├── langchain/
│   │   │   ├── agents/             # 30개 서브디렉토리
│   │   │   ├── chains/             # 43개 서브디렉토리
│   │   │   ├── document_loaders/   # 149개 서브디렉토리
│   │   │   ├── llms/               # 86개 서브디렉토리
│   │   │   ├── vectorstores/       # 71개 서브디렉토리
│   │   │   └── tools/              # 74개 서브디렉토리
│   │   └── pyproject.toml
│   │
│   ├── partners/
│   │   ├── openai/
│   │   │   ├── langchain_openai/
│   │   │   │   ├── chat_models.py
│   │   │   │   ├── llms.py
│   │   │   │   ├── embeddings/
│   │   │   │   ├── middleware/
│   │   │   │   └── data/           # 모델 프로파일
│   │   │   └── pyproject.toml
│   │   ├── anthropic/
│   │   ├── ollama/
│   │   └── ... (12개 추가)
│   │
│   ├── standard-tests/
│   │   └── langchain_tests/
│   │       ├── integration_tests/
│   │       │   ├── chat_models.py  # 128KB 종합 테스트
│   │       │   ├── embeddings.py
│   │       │   └── vectorstores.py # 31KB
│   │       └── unit_tests/
│   │
│   ├── text-splitters/
│   ├── model-profiles/
│   └── Makefile
│
└── .github/
    ├── workflows/              # 19개+ YAML 파일
    └── ISSUE_TEMPLATE/

# 모든 컴포넌트가 동일한 인터페이스를 구현
prompt    : Runnable[dict, PromptValue]
llm       : Runnable[PromptValue, AIMessage]
parser    : Runnable[AIMessage, str]

# 파이프 연결 (RunnableSequence 생성)
chain = prompt | llm | parser

# 파트너 패키지 테스트 예시
from langchain_tests.integration_tests import ChatModelIntegrationTests

class TestChatOpenAI(ChatModelIntegrationTests):
    @property
    def chat_model_class(self) -> type:
        return ChatOpenAI

    @property
    def chat_model_params(self) -> dict:
        return {"model": "gpt-4o-mini"}