원본을 그 자리에서 읽는 어댑터

"쉬운 경우에는 파일이 이미 글이야. 읽고, 손대지 말고, 다음 단계로 넘겨."

변환할 필요가 없는 소스

referenced adapter는 마크다운과 일반 텍스트처럼 바이트를 디코드하면 곧바로 문서가 되는 파일을 다뤄. PDF를 풀거나 HTML 태그를 걷어낼 필요가 없어. 파일을 읽어 정규 텍스트로 만들고 해시를 계산한 뒤 chunker에 넘기는 것이 전부야. 개인 코퍼스에서 가장 흔하고 짧은 수집 경로지.

읽기만 하고 원본에는 아무것도 돌려보내지 않아

referenced든 captured든 모든 adapter는 소스를 읽을 수만 있어. referenced adapter가 파일 바이트를 읽고 디코드해도 디스크의 내용과 수정 시각은 그대로 남아. 원본을 다른 위치로 옮기거나 검색에 맞게 고치지 않는다는 원칙을 가장 낮은 층에서 지키는 거야. 텍스트는 adapter 밖으로 흐르지만 변경은 소스 쪽으로 거슬러 올라가지 않아.

모든 형식이 같은 출구로 나와

adapter의 좁은 계약은 '소스를 받아 정규 텍스트와 내용 해시를 내놓는다'야. 마크다운 파일을 읽었든 PDF를 변환했든 이 경계를 지난 뒤에는 같은 모양이 돼. chunker와 인덱서는 입력이 어떤 형식이었는지 알 필요가 없고, 새 파일 형식을 지원할 때도 새 adapter 하나만 추가하면 돼.

'이 소스를 어떻게 읽을까?'라는 질문을 adapter 안에 가둬. 인코딩과 파일 형식, 변환의 차이는 입력 경계에서 흡수하고, 하류에는 출처 정보가 붙은 정규 텍스트 하나만 보여줘. 그래야 코어가 형식별 예외로 뒤덮이지 않아.

평범한 텍스트에도 한 번의 결정은 필요해

'그냥 파일을 열면 되지'라고 생각하기 쉽지만, 텍스트에도 UTF-8 같은 인코딩과 줄 끝 처리, 무엇을 정규 형태로 볼지 결정이 있어. 가장 단순한 소스까지 adapter를 통하게 하면 그 결정을 내리는 곳이 하나로 모여. 그렇지 않으면 코드 곳곳에서 조금씩 다른 방식으로 디코드하고, 같은 파일을 읽고도 서로 다른 해시와 문자 위치를 만들 수 있어. 몇 줄의 adapter가 그 어긋남을 막아주는 거야.

Code

참조형 어댑터는 원본을 제자리에서 읽고 정규 텍스트와 해시를 내놓아·python

class ReferencedAdapter:
    """The file's bytes ARE the document. Read, decode, hash — never modify."""

    def to_canonical(self, path: str) -> Document:
        raw = Path(path).read_bytes()             # read-only; source untouched
        text = raw.decode("utf-8")                # bytes -> canonical text, one decision
        return Document(
            relpath=path,
            text=text,                            # what the chunker will slice
            doc_sha256=sha256(raw),               # provenance
        )

# The chunker and indexer never learn this was a .md vs a .txt vs a converted PDF.
# They receive one shape — canonical text + hash — from every adapter. That
# uniformity is what keeps the core format-agnostic.

Exercise

여러 소스 형식을 수집하는 시스템의 adapter 인터페이스를 설계해. 모든 adapter가 구현할 함수 하나를 쓰고, 무엇을 받아 무엇을 돌려주는지 적어. 하류 코드를 건드리지 않고 adapter 하나만 추가해 새 형식을 지원할 수 있는지도 확인해. 어렵다면 형식별 세부가 경계 밖으로 새는 곳을 찾아 인터페이스 뒤로 옮겨.

Hint

인터페이스는 소스를 받아 정규 텍스트와 해시를 내놓는 한 가지 모양이어야 해. 하류 코드가 '이게 PDF야, 마크다운 파일이야?'라고 다시 분기한다면 어댑터 경계가 제 역할을 못 한 거야. 형식에 따른 분기는 코어가 아니라 어댑터 안에 있어야 해.

변환할 필요가 없는 소스

읽기만 하고 원본에는 아무것도 돌려보내지 않아

모든 형식이 같은 출구로 나와

평범한 텍스트에도 한 번의 결정은 필요해

Code

External links

Exercise

Progress

댓글 0