Skip to content

04-tech-stack.md

Latest commit

Β 

History

History
176 lines (147 loc) Β· 8.75 KB

04-tech-stack.md

File metadata and controls

176 lines (147 loc) Β· 8.75 KB

InfoMesh β€” 기술 μŠ€νƒ 및 μ½”λ”© κ·œμΉ™

1. 기술 μŠ€νƒ

λ ˆμ΄μ–΄ 기술 λΉ„κ³ 
μ–Έμ–΄ Python 3.12+ μ΅œμ‹  문법 μ‚¬μš© (νƒ€μž… 힌트, match, type λ¬Έ, StrEnum, TypeVar κΈ°λ³Έκ°’ λ“±)
P2P λ„€νŠΈμ›Œν¬ libp2p (py-libp2p) DHT, NAT νŠΈλž˜λ²„μ„€, μ•”ν˜Έν™” λ‚΄μž₯
DHT Kademlia κ²€μ¦λœ λΆ„μ‚° ν•΄μ‹œ ν…Œμ΄λΈ” (인덱슀 + 크둀링 쑰율)
크둀링 httpx + asyncio 비동기 κ³ μ„±λŠ₯ HTTP ν΄λΌμ΄μ–ΈνŠΈ
HTML νŒŒμ‹± trafilatura λ³Έλ¬Έ μΆ”μΆœ 정확도 졜고
ν‚€μ›Œλ“œ 인덱슀 SQLite FTS5 μ„€μΉ˜ λΆˆν•„μš”, μž„λ² λ””λ“œ μ „λ¬Έ 검색
벑터 인덱슀 ChromaDB μ‹œλ§¨ν‹± 검색, μž„λ² λ”© μ €μž₯
MCP μ„œλ²„ mcp-python-sdk VS Code / Claude 연동
관리 API FastAPI 둜컬 μƒνƒœ 쑰회/μ„€μ • λ³€κ²½
직렬화 msgpack JSON보닀 λΉ λ₯΄κ³  μž‘μŒ
μ••μΆ• zstd 레벨 쑰절 κ°€λŠ₯ μ••μΆ•; μœ μ‚¬ λ¬Έμ„œμ— λ”•μ…”λ„ˆλ¦¬ λͺ¨λ“œ 지원
둜컬 LLM ollama / llama.cpp 선택적 둜컬 μš”μ•½ (Qwen 2.5, Llama 3.x λ“±)
λ‘œκΉ… structlog λͺ¨λ“  라이브러리 μ½”λ“œμ˜ κ΅¬μ‘°ν™”λœ λ‘œκΉ…
νŒ¨ν‚€μ§€ λ§€λ‹ˆμ € uv λΉ λ₯Έ Python νŒ¨ν‚€μ§€/ν”„λ‘œμ νŠΈ λ§€λ‹ˆμ € (pip/venv λŒ€μ²΄)

선택적 / 폴백 μ˜μ‘΄μ„±

νŒ¨ν‚€μ§€ μ‚¬μš© μ‹œμ 
BeautifulSoup4 trafilatura μ‹€νŒ¨ μ‹œ HTML νŒŒμ‹± 폴백
vLLM κ³ μ„±λŠ₯ GPU μΆ”λ‘  (올라마/llama.cpp λŒ€μ•ˆ)
sentence-transformers ChromaDB 벑터 인덱슀용 μž„λ² λ”© 생성

2. ν”„λ‘œμ νŠΈ ꡬ쑰

infomesh/
β”œβ”€β”€ pyproject.toml
β”œβ”€β”€ infomesh/
β”‚   β”œβ”€β”€ __init__.py          # νŒ¨ν‚€μ§€ 루트
β”‚   β”œβ”€β”€ __main__.py          # CLI μ§„μž…μ 
β”‚   β”œβ”€β”€ config.py            # μ„€μ • 관리
β”‚   β”œβ”€β”€ services.py          # 쀑앙 AppContext + index_document μ˜€μΌ€μŠ€νŠΈλ ˆμ΄μ…˜
β”‚   β”œβ”€β”€ p2p/                 # P2P λ„€νŠΈμ›Œν¬ λ ˆμ΄μ–΄
β”‚   β”‚   β”œβ”€β”€ node.py          #   ν”Όμ–΄ 메인 ν”„λ‘œμ„ΈμŠ€
β”‚   β”‚   β”œβ”€β”€ dht.py           #   Kademlia DHT
β”‚   β”‚   β”œβ”€β”€ routing.py       #   쿼리 λΌμš°νŒ…
β”‚   β”‚   β”œβ”€β”€ replication.py   #   λ¬Έμ„œ/인덱슀 볡제
β”‚   β”‚   └── protocol.py      #   λ©”μ‹œμ§€ ν”„λ‘œν† μ½œ μ •μ˜
β”‚   β”œβ”€β”€ crawler/             # μ›Ή 크둀러
β”‚   β”‚   β”œβ”€β”€ worker.py        #   비동기 크둀링 μ›Œμ»€
β”‚   β”‚   β”œβ”€β”€ scheduler.py     #   URL ν• λ‹Ή (DHT 기반)
β”‚   β”‚   β”œβ”€β”€ parser.py        #   HTML β†’ ν…μŠ€νŠΈ μΆ”μΆœ
β”‚   β”‚   β”œβ”€β”€ robots.py        #   robots.txt μ€€μˆ˜
β”‚   β”‚   β”œβ”€β”€ dedup.py         #   쀑볡 제거 νŒŒμ΄ν”„λΌμΈ (URL, SHA-256, SimHash)
β”‚   β”‚   β”œβ”€β”€ seeds.py         #   μ‹œλ“œ URL 관리 및 μΉ΄ν…Œκ³ λ¦¬ 선택
β”‚   β”‚   └── crawl_loop.py    #   연속 μ‹œλ“œ-크둀링 루프 (services.pyμ—μ„œ μΆ”μΆœ)
β”‚   β”œβ”€β”€ index/               # 검색 인덱슀
β”‚   β”‚   β”œβ”€β”€ local_store.py   #   SQLite FTS5 둜컬 인덱슀
β”‚   β”‚   β”œβ”€β”€ vector_store.py  #   ChromaDB 벑터 인덱슀
β”‚   β”‚   β”œβ”€β”€ distributed.py   #   DHT μ—­μΈλ±μŠ€ λ°œν–‰/질의
β”‚   β”‚   └── ranking.py       #   BM25 + 신선도 + 신뒰도
β”‚   β”œβ”€β”€ search/              # 검색 엔진
β”‚   β”‚   β”œβ”€β”€ query.py         #   쿼리 νŒŒμ‹± + λΆ„μ‚° 검색 μ˜€μΌ€μŠ€νŠΈλ ˆμ΄μ…˜
β”‚   β”‚   └── merge.py         #   닀쀑 λ…Έλ“œ κ²°κ³Ό 병합
β”‚   β”œβ”€β”€ mcp/                 # MCP μ„œλ²„ (SRP: 4개 λͺ¨λ“ˆλ‘œ 뢄리)
β”‚   β”‚   β”œβ”€β”€ server.py        #   μ—°κ²° λ ˆμ΄μ–΄: Server 생성, 툴 λ””μŠ€νŒ¨μΉ˜, μ‹€ν–‰κΈ°
β”‚   β”‚   β”œβ”€β”€ tools.py         #   툴 μŠ€ν‚€λ§ˆ μ •μ˜ + ν•„ν„° μΆ”μΆœ
β”‚   β”‚   β”œβ”€β”€ handlers.py      #   툴 ν•Έλ“€λŸ¬ κ΅¬ν˜„ (handle_search λ“±)
β”‚   β”‚   └── session.py       #   SearchSession, AnalyticsTracker, WebhookRegistry
β”‚   β”œβ”€β”€ api/                 # 둜컬 관리 API
β”‚   β”‚   └── local_api.py     #   FastAPI (μƒνƒœ 쑰회, μ„€μ • λ³€κ²½)
β”‚   β”œβ”€β”€ credits/             # μΈμ„Όν‹°λΈŒ μ‹œμŠ€ν…œ
β”‚   β”‚   β”œβ”€β”€ types.py         #   ActionType, CreditState, λ°μ΄ν„°ν΄λž˜μŠ€ (ledger.pyμ—μ„œ μΆ”μΆœ)
β”‚   β”‚   └── ledger.py        #   SQLite 기반 ν¬λ ˆλ”§ 원μž₯ (types.pyμ—μ„œ νƒ€μž… μž„ν¬νŠΈ)
β”‚   β”œβ”€β”€ trust/               # μ‹ λ’° & 무결성
β”‚   β”‚   β”œβ”€β”€ attestation.py   #   μ½˜ν…μΈ  증λͺ… 체인 (μ„œλͺ…, 검증)
β”‚   β”‚   β”œβ”€β”€ audit.py         #   랜덀 감사 μ‹œμŠ€ν…œ
β”‚   β”‚   └── scoring.py       #   톡합 μ‹ λ’° 점수 계산
β”‚   β”œβ”€β”€ summarizer/          # 둜컬 LLM μš”μ•½
β”‚   β”‚   β”œβ”€β”€ engine.py        #   LLM λ°±μ—”λ“œ 좔상화 (ollama, llama.cpp)
β”‚   β”‚   β”œβ”€β”€ summarize.py     #   μ½˜ν…μΈ  μš”μ•½ νŒŒμ΄ν”„λΌμΈ
β”‚   β”‚   └── verify.py        #   μš”μ•½ 검증 (ν‚€νŒ©νŠΈ 액컀링, NLI)
β”‚   └── compression/         # 데이터 μ••μΆ•
β”‚       └── zstd.py          #   zstd μ••μΆ• + λ”•μ…”λ„ˆλ¦¬ 지원
β”œβ”€β”€ bootstrap/
β”‚   └── nodes.json           # λΆ€νŠΈμŠ€νŠΈλž© λ…Έλ“œ λͺ©λ‘
β”œβ”€β”€ seeds/                   # λ‚΄μž₯ μ‹œλ“œ URL λͺ©λ‘
β”‚   β”œβ”€β”€ tech-docs.txt        #   기술 λ¬Έμ„œ URL
β”‚   β”œβ”€β”€ academic.txt         #   ν•™μˆ  λ…Όλ¬Έ μ†ŒμŠ€ URL
β”‚   └── encyclopedia.txt     #   백과사전 URL
β”œβ”€β”€ tests/
β”‚   β”œβ”€β”€ conftest.py          # 곡유 ν”½μŠ€μ²˜
β”‚   β”œβ”€β”€ test_dht.py
β”‚   β”œβ”€β”€ test_crawler.py
β”‚   β”œβ”€β”€ test_index.py
β”‚   β”œβ”€β”€ test_search.py
β”‚   β”œβ”€β”€ test_credits.py
β”‚   β”œβ”€β”€ test_trust.py
β”‚   β”œβ”€β”€ test_summarizer.py
β”‚   β”œβ”€β”€ test_mcp.py
β”‚   β”œβ”€β”€ test_services.py     # μ„œλΉ„μŠ€ λ ˆμ΄μ–΄ ν…ŒμŠ€νŠΈ
β”‚   └── test_mcp_handlers.py # MCP ν•Έλ“€λŸ¬ ν…ŒμŠ€νŠΈ
└── docs/

3. μ½”λ”© κ·œμΉ™

3.1 일반

  • μ–Έμ–΄: λͺ¨λ“  μ†ŒμŠ€ μ½”λ“œ, 주석, docstring, 컀밋 λ©”μ‹œμ§€, PR은 μ˜μ–΄λ‘œ μž‘μ„±.
  • Python 버전: 3.12+ β€” μ΅œμ‹  문법 μ‚¬μš© (match/case, type λ¬Έ, StrEnum, TypeVar κΈ°λ³Έκ°’).
  • 비동기 μš°μ„ : λͺ¨λ“  I/O λ°”μš΄λ“œ μ½”λ“œλŠ” async/await + asyncio μ‚¬μš©. 이벀트 λ£¨ν”„μ—μ„œ λΈ”λ‘œν‚Ή I/O κΈˆμ§€.
  • νƒ€μž… 힌트: λͺ¨λ“  곡개 ν•¨μˆ˜μ™€ 클래슀 속성에 ν•„μˆ˜. μ „λ°© μ°Έμ‘° μ‹œ from __future__ import annotations μ‚¬μš©.

3.2 μŠ€νƒ€μΌ & ν¬λ§€νŒ…

  • 포맀터: ruff format (κΈ°λ³Έ μ„€μ •, 쀄 길이 88).
  • λ¦°ν„°: ruff β€” select = ["E", "F", "I", "UP", "B", "SIM"].
  • μž„ν¬νŠΈ μˆœμ„œ: stdlib β†’ μ„œλ“œνŒŒν‹° β†’ 둜컬 (ruff/isort 적용).
  • os.path λŒ€μ‹  pathlib.Path μ„ ν˜Έ.

3.3 넀이밍

λŒ€μƒ κ·œμΉ™ μ˜ˆμ‹œ
λͺ¨λ“ˆ/νŒ¨ν‚€μ§€ snake_case local_store.py
클래슀 PascalCase SearchResult
ν•¨μˆ˜/λ©”μ„œλ“œ/λ³€μˆ˜ snake_case parse_query()
μƒμˆ˜ UPPER_SNAKE_CASE MAX_RETRIES
λΉ„κ³΅κ°œ 멀버 단일 밑쀄 _internal_state

3.4 μ—λŸ¬ 처리

  • ꡬ체적 μ˜ˆμ™Έ νƒ€μž… μ‚¬μš© β€” 빈 except: κΈˆμ§€.
  • structlog λ˜λŠ” stdlib logging μ‚¬μš© β€” 라이브러리 μ½”λ“œμ—μ„œ print() κΈˆμ§€.
  • λ„€νŠΈμ›Œν¬/IO μ‹€νŒ¨ μ‹œ μ§€μˆ˜ λ°±μ˜€ν”„(exponential backoff)둜 μž¬μ‹œλ„.

3.5 ν…ŒμŠ€νŒ…

  • ν”„λ ˆμž„μ›Œν¬: pytest + pytest-asyncio (비동기 ν…ŒμŠ€νŠΈ).
  • ν…ŒμŠ€νŠΈ νŒŒμΌμ€ μ†ŒμŠ€ λ ˆμ΄μ•„μ›ƒ 미러링: infomesh/p2p/dht.py β†’ tests/test_dht.py.
  • λͺ¨λ“  곡개 ν•¨μˆ˜/λ©”μ„œλ“œμ— μ΅œμ†Œ ν•˜λ‚˜μ˜ ν…ŒμŠ€νŠΈ.
  • 인라인 셋업보닀 fixture와 factory μ‚¬μš©.

4. μ˜μ‘΄μ„± & νŒ¨ν‚€μ§€ 관리

uv μ‚¬μš©

uvλ₯Ό λͺ¨λ“  μ˜μ‘΄μ„± ν•΄κ²°, 가상 ν™˜κ²½, ν”„λ‘œμ νŠΈ 관리에 μ‚¬μš©.

  • λͺ¨λ“  μ˜μ‘΄μ„±μ€ pyproject.toml의 [project.dependencies]에 μ„ μ–Έ.
  • 개발 μ˜μ‘΄μ„±μ€ [dependency-groups] (PEP 735) λ˜λŠ” [project.optional-dependencies.dev]에 μ„ μ–Έ.
  • μ΅œμ†Œ λ²„μ „λ§Œ κ³ μ • (예: httpx>=0.27), μ •ν™•ν•œ 버전 κ³ μ • μ—†μŒ.
  • 락 파일: uv.lock β€” μž¬ν˜„ κ°€λŠ₯ν•œ λΉŒλ“œλ₯Ό μœ„ν•΄ μ €μž₯μ†Œμ— 컀밋.
  • requirements.txt μ—†μŒ, pip μ—†μŒ β€” uv λͺ…λ Ήλ§Œ μ‚¬μš©.

μ£Όμš” λͺ…λ Ή

uv sync              # λͺ¨λ“  μ˜μ‘΄μ„± μ„€μΉ˜ (.venv μžλ™ 생성)
uv sync --dev        # 개발 μ˜μ‘΄μ„± 포함 μ„€μΉ˜
uv add <package>     # μƒˆ μ˜μ‘΄μ„± μΆ”κ°€
uv add --dev <pkg>   # 개발 μ˜μ‘΄μ„± μΆ”κ°€
uv run <command>     # ν”„λ‘œμ νŠΈ ν™˜κ²½μ—μ„œ λͺ…λ Ή μ‹€ν–‰
uv run pytest        # ν…ŒμŠ€νŠΈ μ‹€ν–‰
uv run infomesh start  # μ• ν”Œλ¦¬μΌ€μ΄μ…˜ μ‹€ν–‰

κ΄€λ ¨ λ¬Έμ„œ: κ°œμš” Β· μ•„ν‚€ν…μ²˜ Β· ν¬λ ˆλ”§ μ‹œμŠ€ν…œ Β· 법적 고렀사항 Β· μ‹ λ’° & 무결성 Β· λ³΄μ•ˆ 감사 Β· μ½˜μ†” λŒ€μ‹œλ³΄λ“œ Β· MCP 연동 Β· 배포 Β· FAQ