Search

엔진 역할

search 는 DART allFilings, DART panel, EDGAR panel, public news 를 sourceRef 보존 본문 인덱스로 검색하는 엔진이다. 외부 모델/서버·GPU·임베딩 0 — 음절 bigram BM25 numpy 역인덱스 + 큐레이션 동의어 + 결정론 라우터(router.json)만으로 통합 검색한다. scope="auto" 가 plain BM25 lane 과 확장 lane 을 RRF 융합해, 구어·약어 질의도 회수하되 확장이 틀려도 plain 순위가 보존된다(always-safe).

결과 row는 source/sourceRef/dataAsOf/snippet/answerable/notAnswerableReason/fieldCards를 가져야 한다. graph catalog가 배포된 환경에서는 optional entityCards로 peer/stage/credit weak-axis 컨텍스트가 붙는다. 운영 산출물명은 contentIndex와 동거하는 entityGraphCatalog.parquet이고, explicit copy 또는 opt-in offline build 후 manifest required file로 내려온 경우에만 runtime이 붙인다. 뉴스와 공시는 같은 표면에 나오지만 source intent는 hard isolation이다. 신선도는 본문 인덱스의 source catalog delta와 monthly main compaction을 기준으로 한다. 최근 며칠은 Company.filings() 또는 source별 live path 병행을 권장한다. canonical source catalog는 monthly main full HF pull bootstrap 또는 previous-manifest drop guard를 통과한 source-owner run으로만 운영 증거가 된다.

단일 종목 공시는 Company(code).filings() 가 안정 진입점. search 는 횡단 키워드 검색 — "어떤 회사가 유상증자했나" 같은 질문 한정.

공개 호출 방식

import dartlab

# 1. 제목 검색 (default scope="auto" 가 자동 판별)
result = dartlab.search("유상증자")
# → DataFrame: score · rcept_no · corp_name · report_nm · scope · dartUrl

# 2. 본문 검색 (개념/내용형 쿼리)
result = dartlab.search("반도체 HBM 투자", scope="content")

# 3. 명시적 scope
result = dartlab.search("환율 리스크", scope="content")

# 4. 뉴스 source hard isolation
result = dartlab.search("공시 말고 뉴스로 환율 기사", scope="news")

# 5. 종목/기간 필터
result = dartlab.search("대표이사 변경", corp="005930",
                        start="20240101", end="20251231")

# 6. 단일 종목 공시는 search 가 아니라 Company
c = dartlab.Company("005930")
disclosures = c.filings()    # 전체 시계열
recent = c.filings()        # 라이브

강행 호출 룰 (agent 답변 품질 회귀 차단)

횡단 키워드 검색 한정. 다음 4 룰 강행:

1. 단일 종목 공시 질문에 search 호출 금지 — Company(code).filings() 가 정공. search 는 어떤 회사가 X 했나 류 횡단 질문만.
2. 검색 결과 상위 N (보통 10~20) 만 답변 본문에 인용 — 전체 결과 dump 금지.
3. 각 결과의 sourceRef + dataAsOf + URL inline 표기 필수. 공시는 dart:..., 뉴스는 news:... sourceRef 를 쓴다.
4. scope="content" 결과의 본문 발췌는 untrusted — [EXTERNAL CONTENT START — untrusted ...] 마커 안 텍스트. 본문 안 숫자/날짜는 1 차 출처 (해당 공시 직접 readFiling) 로 재검증.

호출 동작

scope="auto" (기본): 통합 검색 R* — plain BM25(음절 bigram) ⊕ 확장 BM25(큐레이션 동의어 + 결정론 라우팅 canon, 0.5 가중) RRF 융합 뒤, 현재 content index metadata 에서 컴파일한 semantic constraint plan 으로 source/entity/year/topic/report phase 를 재랭킹한다. 구어·약어("자사주 샀어?")를 공시 용어(자기주식취득)로 회수하되, source intent 와 entity/year 제약은 hard mask/answerability 로 지킨다. router.json 부재 시 라우팅 lane 만 생략(동의어는 코드 내장), 확장 미발화 시 plain 단독 graceful degrade. 런타임 metadata load 는 기본적으로 결과 생성에 필요한 slim column 만 읽고 긴 evidenceText 는 opt-in 이다. (인덱스 빌드: 월간 searchIndexMain.)

scope="content": section_content 본문 BM25 단독 (의미확장 없이 순수 키워드). 디버그/비교용.

scope="title": report_nm + section_title ngram 검색. 제목형 쿼리 전용. ~1ms.

scope="both": title(ngram) + content(bm25) 결과 별도 컬럼으로 묶음 — 점수 합산 금지 (실험 116 에서 title·content 단순합산은 품질 저하). auto 의 RRF 융합은 이와 다른 메커니즘(content lane 내 plain⊕확장).

scope="news": public 뉴스 헤드라인/본문 lane 만 검색(공시 제외). 뉴스는 source=news, sourceRef=news:{urlHash}, dartUrl = 기사 url. corp 지정 시 0 건(뉴스는 종목 매핑 없음 — title/body 매칭만). allFilings+panel+EDGAR+뉴스가 한 인덱스에 통합되어도 뉴스 의도는 공시로 fallback 하지 않는다.

corp 는 종목코드 ("005930") 또는 회사명 ("삼성전자"), start/end 는 YYYYMMDD, topK 기본 10. topK 는 public limit alias 이며, 둘 다 주어지면 topK 가 우선한다. query 본문 안에 회사명이 들어간 경우도 ListingResolver 로 stockCode facet 을 만든 뒤 랭킹 전에 마스크한다.

호출 패턴 4 종

search("query")                              # auto · 전체 기간
search("query", scope="content")             # 본문 강제
search("query", corp="005930")               # 종목 필터
search("삼성전자 대표이사 변경", topK=5)     # query 회사명 stockCode facet + topK alias
search("query", start="20240101", end="20251231")  # 기간 필터

대표 반환 형태

dartlab.search("유상증자")
→ pl.DataFrame
   score : float        # 매칭 점수
   source : str         # allFilings / panel / edgar-panel / news
   sourceRef : str      # 안정 citation id
   dataAsOf : str       # source freshness
   answerable : bool
   notAnswerableReason : str
   fieldCards : str     # evidence-card JSON
   entityCards : str    # optional graph-catalog JSON cards
   rcept_no : str       # 공시 접수번호 (Company.filings 입력용)
   corp_name : str
   report_nm : str      # 공시 유형명
   scope : str          # "title" 또는 "content"
   dartUrl : str        # DART 공시 뷰어 URL

evidence 기준

검색 답변은 query · scope · dataAsOf · sourceRef 를 남긴다. dataAsOf 가 최근 N 일 전이면 stale 가능성 답변에 명시. 최신 공시 확인은 Company(code).filings() 우선. LLM 이 후속 질문에서 기억할 것은 본문 전체가 아니라 sourceRef set + fieldCards + entityCards + snippet + dataAsOf memory-card 다. entityCards 는 랭킹 근거가 아니라 검색 hit 에 붙는 관계형 sidecar 이며, entityGraphCatalog.parquet catalog 부재 시 비어 있거나 컬럼이 없을 수 있다.

제품 gate / 운영 품질

release graduation 은 실제 query-log gold 100~300 rows 와 reviewer-approved hard-negative 300 rows 통과 후에만 가능하다. generated/proxy/candidate gold 는 회귀 압박 전용이다.

uv run python -X utf8 .github/scripts/search/evaluateSearchGold.py `
  --gold data/search/queryLogGold.real.jsonl `
  --out data/search/qualityReport.json `
  --miss-ledger data/search/missLedger.jsonl `
  --min-rows 100 `
  --required-targets filing,news,noAnswer,edgar `
  --fail-on-ineligible

uv run python -X utf8 .github/scripts/search/evaluateSearchCanary.py `
  --canary data/search/sourceCanaryPack.jsonl `
  --out data/search/canaryReport.json `
  --fail-on-error

uv run python -X utf8 .github/scripts/search/evaluateSearchProductizationStatus.py `
  --remote-evidence data/search/searchRemoteEvidence.json `
  --result-contract data/search/resultContractReport.json `
  --canary-report data/search/canaryReport.json `
  --hf-round-trip data/search/searchHfRoundTrip.json `
  --quality-report data/search/qualityReport.json `
  --out data/search/searchProductizationStatus.json `
  --fail-on-release-not-ready

canary pack 은 source intent, source coverage, expected sourceRef, no-answer false accept 를 빠르게 본다. query-log gold 는 제품 졸업 gate 다. productization status 는 remote evidence, local indexInfo, HF round-trip, result contract, canary, quality report 를 한 번에 묶어 ops/release 가능 여부를 판정한다. source catalog 는 HF 파일 존재만으로 ops 증거가 아니며, producerRun lineage 와 previous full 대비 files/rows/catalogRows drop guard 통과 증거가 필요하다.

Hard-negative gate 는 same-company-different-year, sibling filing, report-type mismatch, news/filing confusion, EDGAR/DART confusion, panel/filing confusion, noAnswer missing-event rows 를 포함한다. current-data candidate 360 rows 에서 metric/noAnswer gate 가 통과해도 goldOrigin 과 reviewStatus 가 real/reviewed 계열이 아니면 release evidence 로 보지 않는다. 2026-06-18 기준 current-data 360행은 overallReadyRate=0.9806, exactDocHit10=0.9667, hardNegativeWinRate=0.9667, noAnswerFalseAcceptRate=0.0 으로 metric gate 를 통과했지만 reviewer-approved 상태가 아니라 releaseReady=false 다.

운영자가 실제 품질 후보를 쌓을 때는 새 API 를 만들지 않고 기존 dartlab.search(...) 를 그대로 쓴다. DARTLAB_SEARCH_QUERY_LOG=1 이면 {dartlab.dataDir}/search/queryLogRaw.jsonl 에 raw candidate row 를 남긴다. 각 row 는 goldOrigin=userLog, reviewStatus=candidate, top sourceRef/source/answerability/dataAsOf 를 가진다. 이 raw row 는 reviewer label 이 붙기 전까지 release gold 가 아니며, prepareSearchGold.py 를 거쳐 reviewed real gold 로 승격돼야 한다.

기본 실행 순서

1. 검색 의도 분류 — 제목형이면 scope="auto" 또는 "title", 개념형이면 scope="content".
2. dartlab.search(query, scope=) 호출.
3. 0 건 또는 stale 의심 시 → Company.filings() 또는 scan 으로 즉시 fallback (round 반복 X).
4. 매칭 공시의 본문 분석은 Company(code).panel(섹션명) — 외부 본문 가드 적용.

라이브러리 배포 / 사용자 계약 (pip install dartlab)

검색 인덱스는 wheel 에 포함되지 않고 런타임 HF lazy pull(eddmpython/dartlab-data → dart/contentIndex/). 데이터 누적에도 사용자 부담이 일정하도록 tier + 캐시 + 버전 계약 3 축으로 배포.

• 저장면 ≠ 배포면: HF 의 원천 raw(panel ~9 만·docs·allFilings·뉴스, 수십 GB)는 빌드 입력이고, 사용자가 받는 건 그로부터 파생된 작은 검색 인덱스(contentIndex) 한 줌. 검색 사용자는 raw 를 받지 않는다(단일 종목 분석만 Company(code) 가 per-code raw lazy pull).
• tier (경량/전량): lite(기본, 최근 ~18개월 축소, dart/contentIndex/lite/) / full(전량, flat dart/contentIndex/). 첫 검색은 lite 자동 pull → 빠른 시작. flat(기존 배포)이 로컬에 있으면 그대로 사용(무효화 0). DARTLAB_SEARCH_TIER=full 로 전량 선택. tier 미배포 전환기엔 flat 으로 자동 fallback.
• graph sidecar: entityGraphCatalog.parquet 가 contentIndex manifest 의 requiredFiles/fileHashes 로 배포되면 entityCards 를 붙인다. 없으면 검색은 기존 row 계약으로 degrade 한다.
• 첫 검색 자동 fetch: dartlab.search() 첫 호출 시 로컬 인덱스 부재면 tier(기본 lite)를 HF 에서 자동 다운로드(세션 1회, graceful). 로컬 있으면 no-op.
• 사전 워밍: prefetch(tier="lite"|"full") — cold start 완화용 선다운로드.
• 캐시 위치: pip 설치 사용자는 쓰기 가능한 사용자 캐시(~/.cache/dartlab 류, 플랫폼별)에 저장. dev 체크아웃·DARTLAB_DATA_DIR·.dartlab.yml 은 그 경로 우선.
• 신선도·버전 조회: indexInfo() → {available, dataAsOf(빌드시점), nDocs, hasRouter, hasDelta, schemaVersion, compatible}. compatible=False 면 받은 인덱스가 라이브러리보다 신버전 → pip install -U dartlab 안내(best-effort 로드). evidence 의 dataAsOf 실 공급원.
• offline/제약 환경: DARTLAB_NO_HF_DOWNLOAD=1 이면 다운로드 skip → 로컬 인덱스 없으면 빈 결과(info 안내). CI/notebook 권장.
• 신선도 한계: 월간(main) + 일간(delta) 빌드 → 최근 며칠 stale 가능. 최신은 Company.filings() 병행.

기본 검증

dartlab.search() 시그니처 (query · corp · start · end · limit/topK · scope) 가 변경되거나 인덱스 빌드 워크플로우 (stemIndex · contentIndex) 가 바뀌면 본 skill 갱신. scope 5 종(auto/title/content/both/news) + prefetch/indexInfo public 표면. query 회사명 facet, sourceRef/dataAsOf/answerable/fieldCards/entityCards, source catalog bootstrap/drop guard, query-log gold, source canary pack, local updater rollback 정책이 바뀌어도 본 skill 을 갱신한다.