Referenced Adapter

"쉬운 경우: 파일이 이미 글이야. 읽고, 안 건드리고, 넘겨."

수집의 단순한 절반

referenced adapter 는 변환이 필요 없는 소스를 다뤄: 마크다운, 일반 텍스트 — 바이트가 디코드되면 곧 문서인 파일. 깨서 열 PDF 도, 벗길 HTML 도 없어. adapter 의 일 전부는 파일을 읽고, canonical 텍스트로 디코드하고, 그 텍스트를 chunker 에 넘기는 거야. 수집 레이어를 지나는 가장 짧은 경로고, 개인 코퍼스 대부분이 여기 살아.

읽되, 절대 다시 쓰지 마

어떤 adapter — referenced 든 captured 든 — 의 철칙 하나는 소스를 읽고 절대 안 고친다는 거야. referenced adapter 는 파일을 열고, 바이트를 디코드하고, canonical 텍스트 더하기 해시를 내. 디스크의 파일은 안 건드려져: 같은 바이트, 같은 수정 시간, 전부 같아. 이게 수집이-파일을-절대-안-옮김 원칙을 가장 낮은 레벨에서 강제한 거야. adapter 는 일방 밸브야; 텍스트가 흘러나오고, 아무것도 소스로 안 흘러들어.

adapter 인터페이스가 봉합선이야

모든 코퍼스 클래스는, 단순하든 복잡하든, 같은 좁은 인터페이스에서 엔진의 나머지를 만나: 소스가 주어지면, canonical 텍스트와 content 해시를 낸다. 그 균일한 봉합선이 chunker, 색인기, 모든 하류가 텍스트가 어디서 왔는지 행복하게 모르게 두는 거야. 마크다운 파일과 변환된 PDF 가 둘 다 해시 달린 canonical 텍스트로 도착해; adapter 뒤 기계는 둘을 구별 못 하고 할 필요도 없어. 그 봉합선을 깨끗이 정의하는 게 새 소스 타입 추가를 작고 국소적인 변경으로 만드는 거야.

'이걸 어떻게 읽지?' 를 하나의 균일한 인터페이스 뒤에 격리해. 세계의 다양성 — 인코딩, 포맷, 변환 — 은 단일 경계, adapter 에서 흡수돼야 하고, 그걸 절대 지나 새면 안 돼. 모든 하류는 하나의 깨끗한 타입을 받아야 해: provenance 달린 canonical 텍스트. 입력의 지저분한 다양성이 가장자리에 격리되면, 시스템 코어가 단순하고 포맷 불가지론적일 수 있어.

단순한 소스도 adapter 를 벌어

일반 텍스트는 adapter 가 필요하기엔 너무 사소하다 생각할 수 있어 — 그냥 파일 열면 되잖아? 근데 여기서도 디코드 결정이 있어: 어느 텍스트 인코딩, 줄 끝을 어떻게 다룰지, 뭐가 canonical 형태로 카운트되는지. 가장 단순한 소스도 adapter 로 라우팅하면 '이게 어떻게 canonical 텍스트로 읽히지?' 가 답해지는 곳이 모든 소스 타입에 정확히 하나 있는 거야. 경계에서의 일관성이 그게 드는 몇 줄보다 값져; 대안은 코드베이스에 흩어져 자기끼리 어긋나는 디코드 로직이야.

Code

referenced adapter: 제자리에서 읽어, canonical 텍스트 + 해시를 내·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

인터페이스는 '소스 in, canonical-텍스트-더하기-해시 out' 같은 거여야 해. 하류 코드가 '이게 PDF 야 마크다운 파일이야?' 로 분기해야 하면, adapter 경계가 실패한 거야 — 그 분기는 코어가 아니라 adapter 안에 속해.

수집의 단순한 절반

읽되, 절대 다시 쓰지 마

adapter 인터페이스가 봉합선이야

단순한 소스도 adapter 를 벌어

Code

External links

Exercise

Progress

댓글 0