deploy: dartlab API + MCP server

.gitattributes

@@ -33,3 +33,9 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+src/dartlab/analysis/financial/research/__pycache__/narrative.cpython-312.pyc filter=lfs diff=lfs merge=lfs -text
+src/dartlab/providers/dart/__pycache__/company.cpython-312.pyc filter=lfs diff=lfs merge=lfs -text
+src/dartlab/providers/dart/__pycache__/company.cpython-313.pyc filter=lfs diff=lfs merge=lfs -text
+src/dartlab/providers/edgar/__pycache__/company.cpython-312.pyc filter=lfs diff=lfs merge=lfs -text
+src/dartlab/providers/edgar/__pycache__/company.cpython-313.pyc filter=lfs diff=lfs merge=lfs -text
+src/dartlab/review/__pycache__/builders.cpython-312.pyc filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,24 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# uv 설치
+RUN pip install --no-cache-dir uv
+
+# 의존성 먼저 (캐시 레이어)
+COPY pyproject.toml uv.lock ./
+RUN uv pip install --system .
+
+# 소스 복사
+COPY src/ src/
+
+# HF Spaces 환경변수
+ENV SPACE_ID=eddmpython/dartlab
+ENV DARTLAB_MCP_HTTP=1
+ENV DARTLAB_CORS_ORIGINS=*
+ENV DARTLAB_HOST=0.0.0.0
+ENV DARTLAB_PORT=7860
+
+EXPOSE 7860
+
+CMD ["python", "-m", "dartlab.server"]

README.md

@@ -1,10 +1,37 @@
 ---
-title: Dartlab
-emoji: 🦀
-colorFrom: red
-colorTo: red
+title: dartlab
+emoji: 📊
+colorFrom: blue
+colorTo: indigo
 sdk: docker
-pinned: false
+app_port: 7860
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# dartlab — 한국 전자공시 분석 API + MCP 서버
+
+설치 없이 사용:
+- **REST API**: `https://eddmpython-dartlab.hf.space/api/*`
+- **MCP (Claude Desktop)**: `https://eddmpython-dartlab.hf.space/mcp/sse`
+
+## MCP 설정
+
+`claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "dartlab": {
+      "url": "https://eddmpython-dartlab.hf.space/mcp/sse"
+    }
+  }
+}
+```
+
+## API 예시
+
+```bash
+# 공시 목록
+curl "https://eddmpython-dartlab.hf.space/api/dart/filings?corp=005930"
+
+# 재무제표
+curl "https://eddmpython-dartlab.hf.space/api/dart/finance/005930?year=2024"
+```

pyproject.toml

@@ -0,0 +1,228 @@
+[project]
+name = "dartlab"
+version = "0.9.6"
+description = "DART 전자공시 + EDGAR 공시를 하나의 회사 맵으로 — Python 재무 분석 라이브러리"
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.12"
+authors = [
+    {name = "eddmpython"}
+]
+keywords = [
+    "dart",
+    "edgar",
+    "sec",
+    "financial-statements",
+    "korea",
+    "disclosure",
+    "accounting",
+    "polars",
+    "sections",
+    "mcp",
+    "ai-analysis",
+    "annual-report",
+    "10-k",
+    "xbrl",
+    "전자공시",
+    "재무제표",
+    "사업보고서",
+    "공시분석",
+    "다트",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Office/Business :: Financial :: Accounting",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Natural Language :: Korean",
+    "Natural Language :: English",
+    "Typing :: Typed",
+]
+dependencies = [
+    # core
+    "beautifulsoup4>=4.14.3,<5",
+    "lxml>=6.0.2,<7",
+    "httpx>=0.28.1,<1",
+    "polars>=1.0.0,<2",
+    "rich>=14.3.3,<15",
+    "huggingface-hub>=0.20.0,<1",
+    "openpyxl>=3.1.5,<4",
+    "diff-match-patch>=20230430",
+    "numpy>=1.26.0,<3",
+    "marimo>=0.22.0",
+    # ai providers
+    "openai>=1.0.0,<3",
+    "google-genai>=1.0.0,<2",
+    "anthropic>=0.30.0,<2",
+    # server (dartlab ai)
+    "fastapi>=0.135.1,<1",
+    "uvicorn[standard]>=0.30.0,<1",
+    "sse-starlette>=2.0.0,<3",
+    "mcp[cli]>=1.0",
+    "qrcode>=7.0,<9",
+    # viz
+    "plotly>=5.0.0,<6",
+]
+
+[project.scripts]
+dartlab = "dartlab.cli.main:main"
+
+[project.entry-points."dartlab.plugins"]
+
+[project.urls]
+Homepage = "https://eddmpython.github.io/dartlab/"
+Repository = "https://github.com/eddmpython/dartlab"
+Documentation = "https://eddmpython.github.io/dartlab/docs/"
+Issues = "https://github.com/eddmpython/dartlab/issues"
+Changelog = "https://eddmpython.github.io/dartlab/docs/changelog"
+Demo = "https://huggingface.co/spaces/eddmpython/dartlab"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dartlab"]
+artifacts = [
+    "src/dartlab/ui/build/**",
+]
+exclude = [
+    "**/_reference/**",
+    "src/dartlab/engines/edinet/**",
+    "src/dartlab/engines/esg/**",
+    "src/dartlab/engines/event/**",
+    "src/dartlab/engines/supply/**",
+    "src/dartlab/engines/watch/**",
+]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/dartlab/**/*.py",
+    "src/dartlab/**/*.json",
+    "src/dartlab/**/*.parquet",
+    "src/dartlab/ui/build/**",
+    "README.md",
+    "LICENSE",
+]
+exclude = [
+    "**/_reference/**",
+    "src/dartlab/engines/edinet/**",
+    "src/dartlab/engines/esg/**",
+    "src/dartlab/engines/event/**",
+    "src/dartlab/engines/supply/**",
+    "src/dartlab/engines/watch/**",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+exclude = ["experiments", "*/_reference"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+ignore = ["E402", "E501", "E741", "F841"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py", "bench_*.py"]
+addopts = "-v --tb=short"
+asyncio_mode = "auto"
+markers = [
+    "requires_data: 로컬 parquet 데이터 필요 (CI에서 skip)",
+    "unit: 순수 로직/mock만 — 데이터 로드 없음, 병렬 안전",
+    "integration: Company 1개 로딩 필요 — 중간 무게",
+    "heavy: 대량 데이터 로드 — 단독 실행 필수",
+]
+
+[tool.coverage.run]
+source = ["dartlab"]
+omit = [
+    "src/dartlab/engines/ai/providers/*",
+    "src/dartlab/review/*",
+]
+
+[tool.coverage.report]
+show_missing = true
+skip_empty = true
+exclude_lines = [
+    "pragma: no cover",
+    "if __name__",
+    "raise NotImplementedError",
+]
+fail_under = 30
+
+[tool.pyright]
+pythonVersion = "3.12"
+typeCheckingMode = "basic"
+include = ["src/dartlab"]
+exclude = [
+    "src/dartlab/engines/ai/providers/**",
+    "ui/**",
+    "experiments/**",
+]
+reportMissingTypeStubs = false
+reportUnknownParameterType = false
+reportUnknownMemberType = false
+reportUnknownVariableType = false
+
+[tool.bandit]
+exclude_dirs = ["experiments", "tests"]
+skips = ["B101"]
+
+[tool.deptry]
+# 옵셔널 통합 의존성 — 사용자가 별도 설치할 때만 동작 (런타임 ImportError 가드 있음)
+extend_exclude = [
+    "src/dartlab/.*/_reference/.*",  # 학습/실험 코드, 런타임 미사용
+]
+[tool.deptry.per_rule_ignores]
+DEP001 = [
+    # ── channel 어댑터 (외부 메신저 옵셔널) ──
+    "discord", "slack_bolt", "telegram",
+    # ── CLI 인터랙티브 옵셔널 ──
+    "prompt_toolkit",
+    # ── display 옵셔널 ──
+    "great_tables", "itables", "IPython",
+    # ── gather 옵셔널 ──
+    "FinanceDataReader", "tavily",
+    # ── _reference 학습/실험 ──
+    "agents", "owlready2", "rapidfuzz", "edgar",
+    # ── transitive deps (다른 패키지가 끌어옴) ──
+    "dotenv",      # python-dotenv
+    "google",      # google-genai
+    "yaml",        # pyyaml
+    "bs4",         # beautifulsoup4
+    "starlette",   # fastapi가 끌어옴
+    "pydantic",    # fastapi가 끌어옴
+]
+DEP002 = [
+    "beautifulsoup4",  # bs4 직접 import
+    "google-genai",    # google.genai 사용 (gemini provider)
+    "marimo",          # 노트북 컴파일/배포 도구
+]
+
+[dependency-groups]
+dev = [
+    "build>=1.4.0",
+    "dartlab[all]",
+    "hatchling>=1.29.0",
+    "hypothesis>=6.100.0",
+    "pillow>=12.1.1",
+    "pre-commit>=4.0.0",
+    "pyright>=1.1.0",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=0.24.0",
+    "pytest-benchmark>=5.0.0",
+    "pytest-cov>=6.0.0",
+    "radon>=6.0.0",
+    "vulture>=2.0",
+]

src/dartlab/STATUS.md

@@ -0,0 +1,81 @@
+# src/dartlab
+
+## 개요
+DART 공시 데이터 활용 라이브러리. 종목코드 기반 API.
+
+## 구조
+```
+dartlab/
+├── core/                    # 공통 기반 (데이터 로딩, 보고서 선택, 테이블 파싱, 주석 추출)
+├── finance/                 # 재무 데이터 (36개 모듈)
+│   ├── summary/             # 요약재무정보 시계열
+│   ├── statements/          # 연결재무제표 (BS, IS, CF)
+│   ├── segment/             # 부문별 보고 (주석)
+│   ├── affiliate/           # 관계기업·공동기업 (주석)
+│   ├── costByNature/        # 비용의 성격별 분류 (주석)
+│   ├── tangibleAsset/       # 유형자산 (주석)
+│   ├── notesDetail/         # 주석 상세 (23개 키워드)
+│   ├── dividend/            # 배당
+│   ├── majorHolder/         # 최대주주·주주현황
+│   ├── shareCapital/        # 주식 현황
+│   ├── employee/            # 직원 현황
+│   ├── subsidiary/          # 자회사 투자
+│   ├── bond/                # 채무증권
+│   ├── audit/               # 감사의견·보수
+│   ├── executive/           # 임원 현황
+│   ├── executivePay/        # 임원 보수
+│   ├── boardOfDirectors/    # 이사회
+│   ├── capitalChange/       # 자본금 변동
+│   ├── contingentLiability/ # 우발부채
+│   ├── internalControl/     # 내부통제
+│   ├── relatedPartyTx/      # 관계자 거래
+│   ├── rnd/                 # R&D 비용
+│   ├── sanction/            # 제재 현황
+│   ├── affiliateGroup/      # 계열사 목록
+│   ├── fundraising/         # 증자/감자
+│   ├── productService/      # 주요 제품/서비스
+│   ├── salesOrder/          # 매출/수주
+│   ├── riskDerivative/      # 위험관리/파생거래
+│   ├── articlesOfIncorporation/ # 정관
+│   ├── otherFinance/        # 기타 재무
+│   ├── companyHistory/      # 회사 연혁
+│   ├── shareholderMeeting/  # 주주총회
+│   ├── auditSystem/         # 감사제도
+│   ├── investmentInOther/   # 타법인출자
+│   └── companyOverviewDetail/ # 회사개요 상세
+├── disclosure/              # 공시 서술형 (4개 모듈)
+│   ├── business/            # 사업의 내용
+│   ├── companyOverview/     # 회사의 개요 (정량)
+│   ├── mdna/                # MD&A
+│   └── rawMaterial/         # 원재료·설비
+├── company.py               # 통합 접근 (property 기반, lazy + cache)
+├── notes.py                 # K-IFRS 주석 통합 접근
+└── config.py                # 전역 설정 (verbose)
+```
+
+## API 요약
+```python
+import dartlab
+
+c = dartlab.Company("005930")
+c.index                 # 회사 구조 인덱스
+c.show("BS")            # topic payload
+c.trace("dividend")     # source trace
+c.BS                    # 재무상태표 DataFrame
+c.dividend              # 배당 시계열 DataFrame
+
+import dartlab
+dartlab.verbose = False  # 진행 표시 끄기
+```
+
+## 현황
+- 2026-03-06: core/ + finance/summary/ 초기 구축
+- 2026-03-06: finance/statements/, segment/, affiliate/ 추가
+- 2026-03-06: 전체 패키지 개선 — stockCode 시그니처, 핫라인 설계, API_SPEC.md
+- 2026-03-07: finance/ 11개 모듈 추가 (dividend~bond, costByNature)
+- 2026-03-07: disclosure/ 4개 모듈 추가 (business, companyOverview, mdna, rawMaterial)
+- 2026-03-07: finance/ 주석 모듈 추가 (notesDetail, tangibleAsset)
+- 2026-03-07: finance/ 7개 모듈 추가 (audit~internalControl, rnd, sanction)
+- 2026-03-07: finance/ 7개 모듈 추가 (affiliateGroup~companyHistory, shareholderMeeting~investmentInOther, companyOverviewDetail)
+- 2026-03-08: analyze → fsSummary 리네이밍, 계정명 특수문자 정리
+- 2026-03-08: Company 재설계 — property 기반 접근, Notes 통합, all(), verbose 설정

src/dartlab/__init__.py

@@ -0,0 +1,1032 @@
+"""DART 공시 데이터 활용 라이브러리."""
+
+import sys
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+from dartlab import ai as llm  # noqa: F401 — 하위호환
+from dartlab import config, core  # noqa: F401 — 하위호환
+from dartlab.audit import queryAudit, runAudit  # noqa: F401 — 하위호환
+from dartlab.company import Company
+from dartlab.core.env import loadEnv as _loadEnv
+from dartlab.core.select import ChartResult, SelectResult
+from dartlab.gather.fred import Fred
+from dartlab.gather.listing import codeToName, fuzzySearch, getKindList, nameToCode  # noqa: F401
+from dartlab.listing import listing  # noqa: F401 — 목록 조회 단일 진입점
+from dartlab.providers.dart.company import Company as _DartEngineCompany
+from dartlab.providers.dart.openapi.dart import OpenDart
+from dartlab.providers.edgar.openapi.edgar import OpenEdgar
+from dartlab.review import Review
+
+# .env 자동 로드 — API 키 등 환경변수
+_loadEnv()
+
+try:
+    __version__ = _pkg_version("dartlab")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+
+def search(
+    query: str,
+    *,
+    corp: str | None = None,
+    start: str | None = None,
+    end: str | None = None,
+    topK: int = 10,
+):
+    """공시 원문 검색. *(alpha)*
+
+    Ngram+Synonym 기반 검색. 모델 불필요, cold start 0ms.
+    DART 공시 뷰어 링크(dartUrl) 포함.
+
+    Capabilities:
+        - 전체 공시 원문 검색 (수시공시 포함)
+        - 자연어 동의어 확장 ("돈을 빌렸다" → 사채/차입/전환사채)
+        - 종목/기간 필터 지원
+        - DART 공시 뷰어 링크 포함 (dartUrl 컬럼)
+
+    Requires:
+        데이터: allFilings (수집 + buildIndex 필요)
+
+    AIContext:
+        공시 내용을 자연어로 찾을 때 사용. 결과의 dartUrl로 원문 확인 가능.
+        종목 찾기는 Company("삼성전자")를 사용.
+
+    Guide:
+        - "유상증자 한 회사?" -> search("유상증자 결정")
+        - "삼성전자 최근 공시?" -> search("공시", corp="005930")
+
+    SeeAlso:
+        - Company: 종목코드/회사명으로 Company 생성
+        - listing: 전체 상장법인 목록
+
+    Args:
+        query: 검색어 (한국어). "유상증자 결정", "대표이사 변경" 등.
+        corp: 종목 필터 (종목코드 "005930" 또는 회사명 "삼성전자").
+        start: 시작일 (YYYYMMDD).
+        end: 종료일 (YYYYMMDD).
+        topK: 반환 건수 (기본 10).
+
+    Returns
+    -------
+    pl.DataFrame
+        score : float — 매칭 점수 (BM25F 가중)
+        rcept_no : str — 접수번호 (DART 고유 ID)
+        corp_name : str — 회사명
+        rcept_dt : str — 접수일 (YYYYMMDD)
+        report_nm : str — 공시 유형명
+        section_title : str — 섹션 제목
+        text : str — 본문 텍스트 (최대 2000자)
+        dartUrl : str — DART 공시 뷰어 URL
+
+    Example::
+
+        import dartlab
+        dartlab.search("유상증자 결정")
+        dartlab.search("대표이사 변경", corp="005930")
+        dartlab.search("전환사채", start="20240101", topK=5)
+    """
+    # R33-1: 빈 query 거부
+    if not query or not query.strip():
+        raise ValueError(
+            "search 의 query 가 비어 있습니다. 검색어를 1자 이상 전달하세요. 예: dartlab.search('유상증자')"
+        )
+    from dartlab.core.search import search as _search
+
+    return _search(query, corp=corp, start=start, end=end, topK=topK)
+
+
+def searchName(keyword: str):
+    """종목명/코드로 종목 찾기 (KR + US).
+
+    Args:
+        keyword: 종목명, 종목코드, 또는 ticker.
+
+    Returns:
+        pl.DataFrame — 종목 검색 결과.
+
+    Example::
+
+        dartlab.searchName("삼성전자")
+        dartlab.searchName("AAPL")
+    """
+    # R33-2: 빈 keyword 거부
+    if not keyword or not keyword.strip():
+        raise ValueError(
+            "searchName 의 keyword 가 비어 있습니다. 종목명/코드를 1자 이상 전달하세요. "
+            "예: dartlab.searchName('삼성전자') 또는 dartlab.searchName('AAPL')"
+        )
+    if any("\uac00" <= ch <= "\ud7a3" for ch in keyword):
+        return _DartEngineCompany.search(keyword)
+    if keyword.isascii() and keyword.isalpha():
+        try:
+            from dartlab.providers.edgar.company import Company as _US
+
+            return _US.search(keyword)
+        except (ImportError, AttributeError, NotImplementedError):
+            pass
+    return _DartEngineCompany.search(keyword)
+
+
+def collect(
+    *codes: str,
+    categories: list[str] | None = None,
+    incremental: bool = True,
+) -> dict[str, dict[str, int]]:
+    """지정 종목 DART 데이터 수집 (OpenAPI).
+
+    Capabilities:
+        - 종목별 DART 공시 데��터 직접 수집 (finance, docs, report)
+        - 멀티키 병렬 수집 (DART_API_KEYS 쉼표 구분)
+        - 증분 수집 — 이미 있는 데이터는 건너뜀
+        - 카테고리별 선택 수집
+
+    Requires:
+        API 키: DART_API_KEY
+
+    AIContext:
+        사용자가 특정 종목의 최신 데이터를 직접 수집할 때 사용.
+
+    Guide:
+        - "데이터 수집해줘" -> DART_API_KEY 필요. dartlab.setup("dart-key", "YOUR_KEY")로 설정 안내
+        - "삼성전자 재무 데이터 수집" -> collect("005930", categories=["finance"])
+        - 보안: 키는 로컬 .env에만 저장, 외부 전송 절대 없음
+
+    SeeAlso:
+        - Company: 수집된 데이터로 Company 생성하여 분석
+        - search: 종목코드 모를 때 먼저 검색
+
+    Args:
+        *codes: 종목코드 1개 이상 ("005930", "000660").
+        categories: 수집 카테고리 ["finance", "docs", "report"]. None이면 전체.
+        incremental: True면 증분 수집 (기본). False면 전체 재수집.
+
+    Returns:
+        dict — 종목코드별 카테고리별 수집 건수.
+
+    Example::
+
+        import dartlab
+        dartlab.collect("005930")                              # 삼성전자 전체
+        dartlab.collect("005930", "000660", categories=["finance"])  # 재무만
+    """
+    from dartlab.providers.dart.openapi.batch import batchCollect
+
+    return batchCollect(list(codes), categories=categories, incremental=incremental)
+
+
+def collectAll(
+    *,
+    categories: list[str] | None = None,
+    mode: str = "new",
+    maxWorkers: int | None = None,
+    incremental: bool = True,
+) -> dict[str, dict[str, int]]:
+    """전체 상장종목 DART 데이터 일괄 수집.
+
+    Capabilities:
+        - 전체 상장종목 DART 공시 데이터 일괄 수집
+        - 미수집 종목만 선별 수집 (mode="new") 또는 전체 재수집 (mode="all")
+        - 멀티키 병렬 수집 (DART_API_KEYS 쉼표 구분)
+        - 카테고리별 선택 (finance, docs, report)
+
+    Requires:
+        API 키: DART_API_KEY
+
+    Guide:
+        - "전종목 데이터 수집" -> collectAll() 안내. DART_API_KEY 필요
+        - "재무 데이터만 수집" -> collectAll(categories=["finance"])
+        - 보안: 키는 로컬 .env에만 저장, 외부 전송 절대 없음
+
+    SeeAlso:
+        - collect: 특정 종목만 수집
+        - downloadAll: HuggingFace 사전구축 데이터 (API 키 불필요, 더 빠름)
+
+    Args:
+        categories: 수집 카테고리 ["finance", "docs", "report"]. None이면 전체.
+        mode: "new" (미수집만, 기본) 또는 "all" (전체 재수집).
+        maxWorkers: 병렬 워커 수. None이면 키 수에 따라 자동.
+        incremental: True면 증분 수집. False면 전체 재수집.
+
+    Returns:
+        dict — 종목코드별 카테고리별 수집 건수.
+
+    Example::
+
+        import dartlab
+        dartlab.collectAll()                          # 전체 미수집 종목
+        dartlab.collectAll(categories=["finance"])    # 재무만
+        dartlab.collectAll(mode="all")                # 기수집 포함 전체
+    """
+    from dartlab.providers.dart.openapi.batch import batchCollectAll
+
+    return batchCollectAll(
+        categories=categories,
+        mode=mode,
+        maxWorkers=maxWorkers,
+        incremental=incremental,
+    )
+
+
+def downloadAll(category: str = "finance", *, forceUpdate: bool = False) -> None:
+    """HuggingFace에서 전체 시장 데이터 다운로드.
+
+    Capabilities:
+        - HuggingFace 사전 구축 데이터 일괄 다운로드
+        - finance (~600MB, 2700+종목), docs (~8GB, 2500+종목), report (~320MB, 2700+종목)
+        - 이어받기/병렬 다운로드 지원 (huggingface_hub)
+        - 전사 분석(scanAccount, governance, digest 등)에 필요한 데이터 사전 준비
+
+    Requires:
+        없음 (HuggingFace 공개 데이터셋)
+
+    Guide:
+        - "데이터 어떻게 받아?" -> downloadAll("finance") 안내. API 키 불필요
+        - "scan 쓰려면?" -> downloadAll("finance") + downloadAll("report") 필요
+        - finance 먼저 (600MB), report 다음 (320MB), docs는 대용량 주의 (8GB)
+
+    SeeAlso:
+        - scan: 다운로드된 데이터로 전종목 비교
+        - collect: DART API로 직접 수집 (최신 데이터, API 키 필요)
+
+    Args:
+        category: "finance" (재무 ~600MB), "docs" (공시 ~8GB), "report" (보고서 ~320MB).
+        forceUpdate: True면 이미 있는 파일도 최신으로 갱신.
+
+    Returns:
+        None.
+
+    Example::
+
+        import dartlab
+        dartlab.downloadAll("finance")   # 재무 전체 — scanAccount/scanRatio 등에 필요
+        dartlab.downloadAll("report")    # 보고서 전체 — governance/workforce/capital/debt에 필요
+        dartlab.downloadAll("docs")      # 공시 전체 — digest에 필요 (대용량 ~8GB)
+    """
+    from dartlab.core.dataLoader import downloadAll as _downloadAll
+
+    _downloadAll(category, forceUpdate=forceUpdate)
+
+
+def checkFreshness(stockCode: str, *, forceCheck: bool = False):
+    """종목의 로컬 데이터가 최신인지 DART API로 확인.
+
+    Capabilities:
+        - 로컬 데이터와 DART 서버의 최신 공시 비교
+        - 누락 공시 수 + 최신 여부 판정
+        - 캐시된 결과 재사용 (forceCheck=False)
+
+    Requires:
+        API 키: DART_API_KEY
+
+    AIContext:
+        - 분석 전 데이터 최신성 확인에 사용
+        - isFresh=False이면 collect()로 갱신 권장
+        - missingCount로 누락 규모 파악 후 수집 우선순위 판단
+
+    Guide:
+        - "내 데이터 최신이야?" -> checkFreshness("005930")
+        - "공시 누락 있어?" -> checkFreshness로 missingCount 확인
+        - "데이터 업데이트 필요해?" -> checkFreshness 후 collect 안내
+
+    SeeAlso:
+        - collect: 누락 공시 실제 수집 (checkFreshness에서 발견한 gap 채우기)
+        - Company: 종목 데이터 접근 (최신 데이터 기반 분석)
+
+    Args:
+        stockCode: 종목코드 ("005930").
+        forceCheck: True면 캐시 무시, DART API 강제 조회.
+
+    Returns:
+        FreshnessResult — isFresh (bool), missingCount (int), lastLocalDate, lastRemoteDate.
+
+    Example::
+
+        import dartlab
+        result = dartlab.checkFreshness("005930")
+        result.isFresh       # True/False
+        result.missingCount  # 누락 공시 수
+    """
+    from dartlab.providers.dart.openapi.freshness import (
+        checkFreshness as _check,
+    )
+
+    return _check(stockCode, forceCheck=forceCheck)
+
+
+def setup(provider: str | None = None):
+    """AI provider 설정 안내 + 인터랙티브 설정.
+
+    Capabilities:
+        - 전체 AI provider 설정 현황 테이블 표시
+        - provider별 대화형 설정 (키 입력 → .env 저장)
+        - ChatGPT OAuth 브라우저 로그인
+        - OpenAI/Gemini/Groq/Cerebras/Mistral API 키 설정
+        - Ollama 로컬 LLM 설치 안내
+
+    Requires:
+        없음
+
+    AIContext:
+        - AI 분석 기능 사용 전 provider 설정 상태 확인
+        - 미설정 provider 감지 시 setup() 안내로 연결
+        - 설정 완료 여부를 프로그래밍 방식으로 체크 가능
+
+    Guide:
+        - "AI 설정 어떻게 해?" -> setup()으로 전체 현황 확인
+        - "ChatGPT 연결하고 싶어" -> setup("chatgpt")
+        - "OpenAI 키 등록" -> setup("openai")
+        - "Ollama 어떻게 써?" -> setup("ollama")
+
+    SeeAlso:
+        - ask: AI 질문 (setup 완료 후 사용)
+        - chat: AI 대화 (setup 완료 후 사용)
+        - llm.configure: 프로그래밍 방식 provider 설정
+
+    Args:
+        provider: provider명 또는 alias. None이면 전체 현황 표시.
+            지원: "chatgpt", "openai", "gemini", "groq", "cerebras",
+            "mistral", "ollama", "codex", "custom".
+
+    Returns:
+        None (터미널/노트북에 안내 출력).
+
+    Example::
+
+        import dartlab
+        dartlab.setup()              # 전체 provider 현황
+        dartlab.setup("chatgpt")     # ChatGPT OAuth 브라우저 로그인
+        dartlab.setup("openai")      # OpenAI API 키 설정
+        dartlab.setup("ollama")      # Ollama 설치 안내
+    """
+    from dartlab.core.ai.guide import (
+        providers_status,
+        resolve_alias,
+    )
+
+    if provider is None:
+        print(providers_status())
+        return
+
+    provider = resolve_alias(provider)
+
+    if provider == "oauth-codex":
+        _setup_oauth_interactive()
+    else:
+        _setup_apikey_interactive(provider)
+
+
+def _setup_oauth_interactive():
+    """노트북/CLI에서 ChatGPT OAuth 브라우저 로그인."""
+    try:
+        from dartlab.ai.providers.support.oauth_token import is_authenticated
+
+        if is_authenticated():
+            print("\n  ✓ ChatGPT OAuth 이미 인증되어 있습니다.")
+            print('  재인증: dartlab.setup("chatgpt")  # 재실행하면 갱신\n')
+            return
+    except ImportError:
+        pass
+
+    try:
+        from dartlab.cli.commands.setup import _do_oauth_login
+
+        _do_oauth_login()
+    except ImportError:
+        print("\n  ChatGPT OAuth 브라우저 로그인:")
+        print("  CLI에서 실행: dartlab setup oauth-codex\n")
+
+
+def _setup_apikey_interactive(provider: str):
+    """API 키 기반 provider 인터랙티브 설정."""
+    from dartlab.guide.providers import _PROVIDERS
+
+    spec = _PROVIDERS.get(provider)
+    if spec is None or not spec.env_key:
+        from dartlab.core.ai.guide import provider_guide
+
+        print(provider_guide(provider))
+        return
+
+    from dartlab.guide.env import promptAndSave
+
+    promptAndSave(
+        spec.env_key,
+        label=spec.label,
+        guide=spec.signupUrl or spec.description,
+    )
+
+
+def _auto_stream(gen) -> str:
+    """Generator를 소비하면서 stdout에 스트리밍 출력, 전체 텍스트 반환."""
+    import sys
+
+    chunks: list[str] = []
+    for chunk in gen:
+        chunks.append(chunk)
+        sys.stdout.write(chunk)
+        sys.stdout.flush()
+    sys.stdout.write("\n")
+    sys.stdout.flush()
+    return "".join(chunks)
+
+
+def ask(
+    *args: str,
+    include: list[str] | None = None,
+    exclude: list[str] | None = None,
+    provider: str | None = None,
+    model: str | None = None,
+    stream: bool = True,
+    raw: bool = False,
+    reflect: bool = False,
+    pattern: str | None = None,
+    template: str | None = None,
+    modules: list[str] | None = None,
+    **kwargs,
+):
+    """LLM에게 기업에 대해 질문.
+
+    Capabilities:
+        - 자연어로 기업 분석 질문 (종목 자동 감지)
+        - 스트리밍 출력 (기본) / 배치 반환 / Generator 직접 제어
+        - 엔진 자동 계산 → LLM 해석 (Engine-First)
+        - 데이터 모듈 include/exclude로 분석 범위 제어
+        - 자체 검증 (reflect=True)
+
+    Requires:
+        AI: provider 설정 (dartlab.setup() 참조)
+
+    AIContext:
+        - 재무비율, 추세, 동종업계 비교를 자동 계산하여 LLM에 제공
+        - sections 서술형 데이터 + finance 숫자 데이터 동시 주입
+        - tool calling provider에서는 LLM이 추가 데이터 자율 탐색
+
+    Guide:
+        - "삼성전자 분석해줘" -> ask("삼성전자 재무건전성 분석해줘")
+        - "이 회사 괜찮아?" -> ask("종목코드", "이 회사 투자해도 괜찮아?")
+        - "AI 설정 어떻게 해?" -> dartlab.setup()으로 provider/키 설정 안내
+        - provider 미설정 시 자동 감지. 설정 방법: dartlab.llm.configure(provider="openai", api_key="sk-...")
+        - 보안: API 키는 로컬 .env에만 저장, 외부 전송 절대 없음
+
+    SeeAlso:
+        - chat: 대화형 연속 분석 (멀티턴)
+        - Company: 프로그래밍 방식 데이터 접근
+        - scan: 전종목 비교 (ask보다 직접적)
+
+    Args:
+        *args: 자연어 질문 (1개) 또는 (종목, 질문) 2개.
+        provider: LLM provider ("openai", "codex", "oauth-codex", "ollama").
+        model: 모델 override.
+        stream: True면 스트리밍 출력 (기본값). False면 조용히 전체 텍스트 반환.
+        raw: True면 Generator를 직접 반환 (커스텀 UI용).
+        include: 포함할 데이터 모듈.
+        exclude: 제외할 데이터 모듈.
+        reflect: True면 답변 자체 검증 (1회 reflection).
+
+    Returns:
+        str | None: 전체 답변 텍스트. 설정 오류 시 None. (raw=True일 때만 Generator[str])
+
+    Example::
+
+        import dartlab
+        dartlab.llm.configure(provider="openai", api_key="sk-...")
+
+        # 호출하면 스트리밍 출력 + 전체 텍스트 반환
+        answer = dartlab.ask("삼성전자 재무건전성 분석해줘")
+
+        # provider + model 지정
+        answer = dartlab.ask("삼성전자 분석", provider="openai", model="gpt-4o")
+
+        # (종목, 질문) 분리
+        answer = dartlab.ask("005930", "영업이익률 추세는?")
+
+        # 조용히 전체 텍스트만 (배치용)
+        answer = dartlab.ask("삼성전자 분석", stream=False)
+
+        # Generator 직접 제어 (커스텀 UI용)
+        for chunk in dartlab.ask("삼성전자 분석", raw=True):
+            custom_process(chunk)
+    """
+    from dartlab.ai.runtime.standalone import ask as _ask
+
+    # provider 미지정 시 auto-detect
+    if provider is None:
+        from dartlab.core.ai.detect import auto_detect_provider
+
+        detected = auto_detect_provider()
+        if detected is None:
+            from dartlab.core.ai.guide import no_provider_message
+
+            print(no_provider_message())
+            return None
+        provider = detected
+
+    if len(args) == 2:
+        import warnings
+
+        warnings.warn(
+            "dartlab.ask(stock, question) is deprecated. Use dartlab.ask('삼성전자 분석해줘') instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        company = Company(args[0])
+        question = args[1]
+    elif len(args) == 1:
+        company = None
+        question = args[0]
+    elif len(args) == 0:
+        print("\n  질문을 입력해 주세요.")
+        print("  예: dartlab.ask('삼성전자 재무건전성 분석해줘')")
+        print("  예: dartlab.ask('005930', '영업이익률 추세는?')\n")
+        return None
+    else:
+        print(f"\n  인자는 1~2개만 허용됩니다 (받은 수: {len(args)})")
+        print("  예: dartlab.ask('삼성전자 분석해줘')")
+        print("  예: dartlab.ask('005930', '영업이익률 추세는?')\n")
+        return None
+
+    # kwargs에서 company 제거 (내부에서 직접 전달)
+    kwargs.pop("company", None)
+    _call_kwargs = dict(
+        company=company,
+        include=include,
+        exclude=exclude,
+        provider=provider,
+        model=model,
+        reflect=reflect,
+        pattern=pattern,
+        template=template,
+        modules=modules,
+        **kwargs,
+    )
+
+    if raw:
+        return _ask(question, stream=stream, **_call_kwargs)
+
+    if not stream:
+        return _ask(question, stream=False, **_call_kwargs)
+
+    gen = _ask(question, stream=True, **_call_kwargs)
+    return _auto_stream(gen)
+
+
+def templates(name: str | None = None):
+    """분석 템플릿 목록 또는 특정 템플릿 내용.
+
+    Example::
+
+        dartlab.templates()          # 전체 목록
+        dartlab.templates("가치투자") # 특정 템플릿 내용
+    """
+    from dartlab.ai import templates as _templates
+
+    return _templates(name)
+
+
+def saveTemplate(name: str, *, content: str | None = None, file: str | None = None):
+    """사용자 분석 템플릿 저장. ~/.dartlab/templates/{name}.md
+
+    Example::
+
+        dartlab.saveTemplate("my_style", content="## 내 기준\\n- ROE > 15%")
+    """
+    from dartlab.ai import saveTemplate as _save
+
+    return _save(name, content=content, file=file)
+
+
+def chat(
+    *args: str,
+    provider: str | None = None,
+    model: str | None = None,
+    max_turns: int = 5,
+    on_tool_call=None,
+    on_tool_result=None,
+    **kwargs,
+) -> str:
+    """에이전트 모드: LLM이 도구를 선택하여 심화 분석.
+
+    Capabilities:
+        - LLM이 dartlab 도구를 자율적으로 선택/실행
+        - 원본 공시 탐색, 계정 시계열 비교, 섹터 통계 등 심화 분석
+        - 최대 N회 도구 호출 반복 (multi-turn)
+        - 도구 호출/결과 콜백으로 UI 연동
+        - 종목 없이도 동작 (시장 전체 질문, 메타 질문 등)
+
+    Requires:
+        AI: provider 설정 (tool calling 지원 provider 권장)
+
+    AIContext:
+        - ask()와 동일한 기본 컨텍스트 + 저수준 도구 접근
+        - LLM이 부족하다 판단하면 추가 데이터 자율 수집
+        - company=None이면 scan/gather/system 도구만 활성화
+
+    Guide:
+        - "깊게 분석해줘" -> chat("005930", "배당 추세를 분석하고 이상 징후를 찾아줘")
+        - "시장 전체 거버넌스 비교" -> chat("코스피 거버넌스 좋은 회사 찾아줘")
+        - "dartlab 뭐 할 수 있어?" -> chat("dartlab 기능 알려줘")
+        - ask()보다 심화 분석이 필요할 때 사용. LLM이 자율적으로 도구 호출
+
+    SeeAlso:
+        - ask: 단일 질문 (간단한 분석)
+        - Company: 프로그래밍 방식 직접 접근
+        - scan: 전종목 횡단분석
+
+    Args:
+        *args: (종목, 질문) 2개 또는 질문만 1개.
+        provider: LLM provider.
+        model: 모델 override.
+        max_turns: 최대 도구 호출 반복 횟수.
+
+    Returns:
+        str: 최종 답변 텍스트.
+
+    Example::
+
+        import dartlab
+        dartlab.chat("005930", "배당 추세를 분석하고 이상 징후를 찾아줘")
+        dartlab.chat("코스피 ROE 높은 회사 알려줘")  # 종목 없이 시장 질문
+    """
+    from dartlab.ai.runtime.standalone import chat as _chat
+
+    if len(args) == 2:
+        company = Company(args[0])
+        question = args[1]
+    elif len(args) == 1:
+        from dartlab.core.resolve import resolve_from_text
+
+        company, question = resolve_from_text(args[0])
+        if company is None:
+            question = args[0]
+    elif len(args) == 0:
+        print("\n  질문을 입력해 주세요.")
+        print("  예: dartlab.chat('005930', '배당 추세 분석해줘')")
+        print("  예: dartlab.chat('코스피 ROE 높은 회사 알려줘')\n")
+        return ""
+    else:
+        print(f"\n  인자는 1~2개만 허용됩니다 (받은 수: {len(args)})")
+        return ""
+
+    return _chat(
+        company,
+        question,
+        provider=provider,
+        model=model,
+        max_turns=max_turns,
+        on_tool_call=on_tool_call,
+        on_tool_result=on_tool_result,
+        **kwargs,
+    )
+
+
+def plugins():
+    """로드된 플러그인 목록 반환.
+
+    Capabilities:
+        - 설치된 dartlab 플러그인 자동 탐색
+        - 플러그인 메타데이터 (이름, 버전, 제공 topic) 조회
+
+    Requires:
+        없음
+
+    AIContext:
+        - 확장 기능 탐색 시 설치된 플러그인 목록 확인
+        - 플러그인이 제공하는 topic을 show()에서 사용 가능
+        - 플러그인 유무에 따라 분석 범위 동적 결정
+
+    Guide:
+        - "플러그인 뭐 있어?" -> plugins()
+        - "확장 기능 목록" -> plugins()로 설치된 플러그인 확인
+        - "ESG 플러그인 있어?" -> plugins()에서 검색
+
+    SeeAlso:
+        - reload_plugins: 새 플러그인 설치 후 재스캔
+        - Company.show: 플러그인 topic 조회 (plugins가 제공한 topic 사용)
+
+    Args:
+        없음.
+
+    Returns:
+        list[PluginMeta] — 로드된 플러그인 목록.
+
+    Example::
+
+        import dartlab
+        dartlab.plugins()  # [PluginMeta(name="esg-scores", ...)]
+    """
+    from dartlab.core.plugins import discover, get_loaded_plugins
+
+    discover()
+    return get_loaded_plugins()
+
+
+def reload_plugins():
+    """플러그인 재스캔 — pip install 후 재시작 없이 즉시 인식.
+
+    Capabilities:
+        - 새로 설치한 플러그인 즉시 인식 (세션 재시작 불필요)
+        - entry_points 재스캔
+
+    Requires:
+        없음
+
+    AIContext:
+        - pip install 후 세션 재시작 없이 플러그인 즉시 활성화
+        - 새로 인식된 topic이 Company.show()에서 바로 사용 가능
+
+    Guide:
+        - "새 플러그인 설치했는데 안 보여" -> reload_plugins()
+        - "플러그인 재스캔" -> reload_plugins()
+
+    SeeAlso:
+        - plugins: 현재 로드된 플러그인 확인 (reload 전후 비교)
+        - Company.show: 플러그인 topic 조회
+
+    Args:
+        없음.
+
+    Returns:
+        list[PluginMeta] — 재스캔 후 플러그인 목록.
+
+    Example::
+
+        # 1. 새 플러그인 설치
+        # !uv pip install dartlab-plugin-esg
+
+        # 2. 재스캔
+        dartlab.reload_plugins()
+
+        # 3. 즉시 사용
+        dartlab.Company("005930").show("esgScore")
+    """
+    from dartlab.core.plugins import rediscover
+
+    return rediscover()
+
+
+class _Module(sys.modules[__name__].__class__):
+    """dartlab.verbose / dartlab.dataDir / dartlab.chart|table|text 프록시."""
+
+    @property
+    def verbose(self):
+        """전역 verbose 설정 조회."""
+        return config.verbose
+
+    @verbose.setter
+    def verbose(self, value):
+        config.verbose = value
+
+    @property
+    def askLog(self):
+        """ask/chat 로그 활성화 조회."""
+        return config.askLog
+
+    @askLog.setter
+    def askLog(self, value):
+        config.askLog = bool(value)
+
+    @property
+    def dataDir(self):
+        """데이터 저장 디렉토리 경로 조회."""
+        return config.dataDir
+
+    @dataDir.setter
+    def dataDir(self, value):
+        config.dataDir = str(value)
+
+    def __getattr__(self, name):
+        if name == "scan":
+            from dartlab.scan import Scan
+
+            instance = Scan()
+            setattr(self, name, instance)
+            return instance
+        if name == "analysis":
+            from dartlab.analysis.financial import Analysis
+
+            instance = Analysis()
+            setattr(self, name, instance)
+            return instance
+        if name == "credit":
+            from dartlab.credit import credit
+
+            setattr(self, name, credit)
+            return credit
+        if name == "quant":
+            from dartlab.quant import Quant
+
+            instance = Quant()
+            setattr(self, name, instance)
+            return instance
+        if name == "macro":
+            from dartlab.macro import Macro
+
+            instance = Macro()
+            setattr(self, name, instance)
+            return instance
+        if name == "topdown":
+            from dartlab.topdown import _TopdownEntry
+
+            instance = _TopdownEntry()
+            setattr(self, name, instance)
+            return instance
+        if name == "viz":
+            import dartlab.viz as _viz
+
+            setattr(self, name, _viz)
+            return _viz
+        if name == "chart":
+            # 하위호환: dartlab.chart → dartlab.viz
+            import dartlab.viz as _viz
+
+            setattr(self, name, _viz)
+            return _viz
+        if name == "table":
+            from dartlab.table import Table
+
+            instance = Table()
+            setattr(self, name, instance)
+            return instance
+        if name == "text":
+            import importlib
+
+            mod = importlib.import_module("dartlab.tools.text")
+            setattr(self, name, mod)
+            return mod
+        raise AttributeError(f"module 'dartlab' has no attribute {name!r}")
+
+
+sys.modules[__name__].__class__ = _Module
+
+# gather 모듈을 GatherEntry callable로 덮어쓰기
+# (gather 서브모듈이 top-level import로 이미 로드되므로 __getattr__ lazy 불가)
+from dartlab.gather.entry import GatherEntry as _GatherEntry
+
+sys.modules[__name__].gather = _GatherEntry()
+
+# topdown도 같은 문제 — 모듈 import가 __getattr__보다 우선이라 callable로 덮어쓴다
+from dartlab.topdown import _TopdownEntry as _TopdownEntry
+
+sys.modules[__name__].topdown = _TopdownEntry()
+
+# scan/analysis/credit/quant — 어떤 import 체인이 모듈을 먼저 로드하면
+# 모듈 클래스의 __getattr__이 동작 안 함 (CI에서 발견된 회귀).
+# 해결: 모듈 자체를 callable로 패치 — 모듈 객체에 __call__을 직접 부여.
+import types as _types
+
+
+def _makeCallableModule(modName: str, instanceFactory):
+    """이미 로드된 서브모듈에 __call__을 부여하여 callable하게 만든다.
+
+    서브모듈(rank, _helpers 등)도 그대로 import 가능. instance 메소드는 lazy 호출.
+    """
+    mod = sys.modules.get(modName)
+    if mod is None:
+        return
+
+    class _CallableModule(_types.ModuleType):
+        _instance = None
+
+        def __call__(self, *args, **kwargs):
+            if self._instance is None:
+                self._instance = instanceFactory()
+            return self._instance(*args, **kwargs)
+
+        def __getattr__(self, name):
+            if self._instance is None:
+                self._instance = instanceFactory()
+            try:
+                return getattr(self._instance, name)
+            except AttributeError:
+                raise AttributeError(f"module '{modName}' has no attribute '{name}'") from None
+
+    mod.__class__ = _CallableModule
+
+
+def _scanFactory():
+    from dartlab.scan import Scan
+
+    return Scan()
+
+
+def _analysisFactory():
+    from dartlab.analysis.financial import Analysis
+
+    return Analysis()
+
+
+def _quantFactory():
+    from dartlab.quant import Quant
+
+    return Quant()
+
+
+# scan/analysis/quant — 모듈 자체를 callable로 변환
+import dartlab.analysis.financial as _analysis_mod  # noqa: F401
+import dartlab.quant as _quant_mod  # noqa: F401
+import dartlab.scan as _scan_mod  # noqa: F401
+
+_makeCallableModule("dartlab.scan", _scanFactory)
+_makeCallableModule("dartlab.analysis.financial", _analysisFactory)
+_makeCallableModule("dartlab.quant", _quantFactory)
+
+# credit은 함수형 (이미 callable)
+from dartlab.credit import credit as _credit_callable
+
+sys.modules[__name__].credit = _credit_callable
+
+
+__all__ = [
+    "Company",
+    "Fred",
+    "OpenDart",
+    "OpenEdgar",
+    "config",
+    "ask",
+    "chat",
+    "setup",
+    "search",
+    "listing",
+    "collect",
+    "collectAll",
+    "downloadAll",
+    "scan",
+    "analysis",
+    "gather",
+    "quant",
+    "credit",
+    "macro",
+    "topdown",
+    "verbose",
+    "dataDir",
+    "codeToName",
+    "nameToCode",
+    "searchName",
+    "Review",
+    "SelectResult",
+    "ChartResult",
+    "capabilities",
+]
+
+
+def capabilities(key: str | None = None, *, search: str | None = None) -> dict | list[str]:
+    """dartlab 전체 기능 카탈로그 조회.
+
+    Capabilities:
+        CAPABILITIES dict에서 부분 조회 가능.
+        key 없이 호출 시 전체 키 목록(summary 포함) 반환.
+        key 지정 시 해당 항목의 상세(guide, capabilities, seeAlso 등) 반환.
+        search 지정 시 자연어 질문 기반 관련 API 검색 (상위 10개).
+
+    Requires:
+        없음
+
+    AIContext:
+        AI가 "dartlab에 뭐가 있는지" 모를 때 탐색용.
+        capabilities() → 목차 확인 → capabilities("analysis") → 상세 확인 → execute_code.
+        capabilities(search="재무건전성") → 질문 관련 API 검색 → 코드 생성.
+
+    Guide:
+        - "dartlab 뭐 할 수 있어?" -> capabilities()
+        - "분석 기능 뭐 있어?" -> capabilities("analysis")
+        - "scan 어떻게 써?" -> capabilities("scan")
+        - "재무건전성 관련 API?" -> capabilities(search="재무건전성")
+
+    SeeAlso:
+        - ask: AI 질문 (capabilities로 기능 파악 후 ask로 분석)
+        - setup: AI provider 설정 (capabilities 확인 후 설정)
+
+    Args:
+        key: 조회할 기능 키. None이면 전체 목차.
+        search: 자연어 질문 기반 검색. key와 동시 사용 불가.
+
+    Returns:
+        dict | list[str] — key 있으면 해당 항목 dict, 없으면 키+summary 목록.
+
+    Example::
+
+        dartlab.capabilities()                       # 전체 목차
+        dartlab.capabilities("analysis")             # analysis 상세 (guide, capabilities)
+        dartlab.capabilities("Company.analysis")     # Company.analysis 상세
+        dartlab.capabilities("scan")                 # scan 상세
+        dartlab.capabilities(search="재무건전성")     # 질문 기반 검색 → 상위 10개
+    """
+    if search is not None:
+        from dartlab.core._capabilitySearch import searchCapabilities
+
+        results = searchCapabilities(search)
+        return {key: entry for key, entry, _score in results}
+
+    from dartlab.core._generatedCapabilities import CAPABILITIES
+
+    if key is None:
+        return {k: v.get("summary", "") for k, v in CAPABILITIES.items()}
+    if key in CAPABILITIES:
+        return CAPABILITIES[key]
+    # 부분 매칭: "analysis" → "Company.analysis" 등도 포함
+    matched = {k: v for k, v in CAPABILITIES.items() if key.lower() in k.lower()}
+    if matched:
+        return matched
+    return {}

src/dartlab/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m dartlab` to invoke the CLI."""
+
+from dartlab.cli.main import main
+
+raise SystemExit(main())

src/dartlab/ai/STATUS.md

@@ -0,0 +1,200 @@
+# AI Engine — Provider 현황 및 유지보수 체크리스트
+
+## Provider 목록 (7개)
+
+| Provider | 파일 | 인증 | 기본 모델 | 안정성 |
+|----------|------|------|----------|--------|
+| `openai` | openai_compat.py | API Key | gpt-4o | **안정** — 공식 SDK |
+| `ollama` | ollama.py | 없음 (localhost) | llama3.1 | **안정** — 로컬 |
+| `custom` | openai_compat.py | API Key | gpt-4o | **안정** — OpenAI 호환 |
+| `chatgpt` | providers/__init__.py alias | `codex`로 정규화 | codex mirror | **호환용 alias** — 공개 surface 비노출 |
+| `codex` | codex.py | CLI 세션 | CLI config 또는 gpt-4.1 | **공식 경로 우선** — Codex CLI 의존 |
+| `oauth-codex` | oauthCodex.py | ChatGPT OAuth | gpt-5.4 | **공개 경로** — 비공식 backend API 의존 |
+| `claude-code` | claude_code.py | CLI 세션 | sonnet | **보류중** — OAuth 지원 전 비공개 |
+
+---
+
+## 현재 공개 경로
+
+- ChatGPT 구독 계정 경로는 2개다.
+  - `codex`: Codex CLI 로그인 기반
+  - `oauth-codex`: ChatGPT OAuth 직접 연결 기반
+- 공개 provider surface는 `codex`, `oauth-codex`, `openai`, `ollama`, `custom`만 유지한다.
+- `claude` provider는 public surface에서 제거되었고 legacy/internal 코드로만 남아 있다.
+- `chatgpt`는 기존 설정/호환성 때문에 내부 alias로만 남아 있으며 실제 구현은 `codex`로 정규화된다.
+- `chatgpt-oauth`는 내부/호환 alias로만 남아 있으며 실제 구현은 `oauth-codex`로 정규화된다.
+
+## Tool Runtime 기반
+
+- 도구 등록/실행은 `tool_runtime.py`의 `ToolRuntime`으로 분리되기 시작했다.
+- `tools_registry.py`는 현재 호환 래퍼 역할을 하며, 세션별/에이전트별 isolated runtime 생성이 가능하다.
+- coding executor는 `coding_runtime.py`로 분리되기 시작했고, backend registry를 통해 관리한다.
+- 표준 코드 작업 진입점은 `run_coding_task`이며 `run_codex_task`는 Codex compatibility alias로 유지한다.
+- 다음 단계는 Codex 외 backend를 이 runtime 뒤에 추가하되, 공개 provider surface와는 분리하는 것이다.
+
+## ChatGPT OAuth Provider — 핵심 리스크
+
+### 왜 취약한가
+
+`oauth-codex` provider는 **OpenAI 비공식 내부 API** (`chatgpt.com/backend-api/codex/responses`)를 사용한다.
+공식 OpenAI API (`api.openai.com`)가 아니므로 **예고 없이 변경/차단될 수 있다**.
+
+### 정기 체크 항목
+
+**1. 엔드포인트 변경**
+- 현재: `https://chatgpt.com/backend-api/codex/responses`
+- 파일: [oauthCodex.py](providers/oauthCodex.py) `CODEX_API_BASE`, `CODEX_RESPONSES_PATH`
+- OpenAI가 URL 경로를 변경하면 즉시 404/403 발생
+- 확인법: `dartlab status` 실행 → chatgpt available 확인
+
+**2. OAuth 인증 파라미터**
+- Client ID: `app_EMoamEEZ73f0CkXaXp7hrann` (Codex CLI에서 추출)
+- 파일: [oauthToken.py](../oauthToken.py) `CHATGPT_CLIENT_ID`
+- OpenAI가 client_id를 갱신하거나 revoke하면 로그인 불가
+- 확인법: OAuth 로그인 시도 → "invalid_client" 에러 여부
+
+**3. SSE 이벤트 타입**
+- 현재 파싱하는 타입 3개:
+  - `response.output_text.delta` — 텍스트 청크
+  - `response.content_part.delta` — 컨텐츠 청크
+  - `response.output_item.done` — 아이템 완료
+- 파일: [oauthCodex.py](providers/oauthCodex.py) `stream()`, `_parse_sse_response()`
+- OpenAI가 이벤트 스키마를 변경하면 응답이 빈 문자열로 돌아옴
+- 확인법: 스트리밍 응답이 도착하는데 텍스트가 비어있으면 이벤트 타입 변경 의심
+
+**4. 요청 헤더**
+- `originator: codex_cli_rs` — Codex CLI 사칭
+- `OpenAI-Beta: responses=experimental` — 실험 API 플래그
+- 파일: [oauthCodex.py](providers/oauthCodex.py) `_build_headers()`
+- 이 헤더 없이는 403 반환됨
+- OpenAI가 originator 검증을 강화하면 차단됨
+
+**5. 모델 목록**
+- `AVAILABLE_MODELS` 리스트는 수동 관리
+- 파일: [oauthCodex.py](providers/oauthCodex.py) `AVAILABLE_MODELS`
+- 새 모델 출시/폐기 시 수동 업데이트 필요
+- GPT-4 시리즈 (gpt-4, gpt-4-turbo 등)는 이미 제거됨
+
+**6. 토큰 만료 정책**
+- access_token: expires_in 기준 (현재 ~1시간)
+- refresh_token: 만료 정책 불명 (OpenAI 미공개)
+- 파일: [oauthToken.py](../oauthToken.py) `get_valid_token()`, `refresh_access_token()`
+- refresh_token이 만료되면 재로그인 필요
+- 확인법: 며칠 방치 후 요청 → 401 + refresh 실패 여부
+
+### 브레이킹 체인지 대응 순서
+
+1. 사용자가 "ChatGPT 안됨" 보고
+2. `dartlab status` 로 available 확인
+3. available=False → OAuth 로그인 재시도
+4. 로그인 실패 → client_id 변경 확인 (opencode-openai-codex-auth 참조)
+5. 로그인 성공인데 API 호출 실패 → 엔드포인트/헤더 변경 확인
+6. API 호출 성공인데 응답 비어있음 → SSE 이벤트 타입 변경 확인
+
+### 생태계 비교 — 누가 같은 API를 쓰는가
+
+ChatGPT OAuth(`chatgpt.com/backend-api`)를 사용하는 프로젝트는 **전부 openai/codex CLI 역공학** 기반이다.
+
+| 프로젝트 | 언어 | Client ID | 모델 목록 | refresh 실패 처리 | 토큰 저장 |
+|----------|------|-----------|----------|------------------|----------|
+| **openai/codex** (공식) | Rust | 하드코딩 | `/models` 동적 + 5분 캐시 | 4가지 분류 | 파일/키링/메모리 3중 |
+| **opencode plugin** | TS | 동일 복제 | 사용자 설정 의존 | 단순 throw | 프레임워크 위임 |
+| **ai-sdk-provider** | TS | 동일 복제 | 3개 하드코딩 | 단순 throw | codex auth.json 재사용 |
+| **dartlab** (현재) | Python | 동일 복제 | 13개 하드코딩 | None 반환 | `~/.dartlab/oauth_token.json` |
+
+**공통 특징:**
+- Client ID `app_EMoamEEZ73f0CkXaXp7hrann` 전원 동일 (OpenAI public OAuth client)
+- `originator: codex_cli_rs` 헤더 전원 동일
+- OpenAI가 이 값들을 바꾸면 **전부 동시에 깨짐**
+
+**openai/codex만의 차별점 (dartlab에 없는 것):**
+1. Token Exchange — OAuth 토큰 → `api.openai.com` 호환 API Key 변환
+2. Device Code Flow — headless 환경 (서버, SSH) 인증 지원
+3. 모델 목록 동적 조회 — `/models` 엔드포인트 + 캐시 + bundled fallback
+4. Keyring 저장 — OS 키체인 (macOS Keychain, Windows Credential Manager)
+5. refresh 실패 4단계 분류 — expired / reused / revoked / other
+6. WebSocket SSE 이중 지원
+
+**참고: opencode와 oh-my-opencode(현 oh-my-openagent)는 ChatGPT OAuth를 사용하지 않는다.**
+- opencode: GitHub Copilot API 인증 (다른 시스템)
+- oh-my-openagent: MCP 서버 표준 OAuth 2.0 + PKCE (플러그인)
+
+### 추적 대상 레포지토리
+
+변경사항 감지를 위해 다음 레포를 추적한다.
+
+| 레포 | 추적 이유 | Watch 대상 |
+|------|----------|-----------|
+| **openai/codex** | canonical 구현. Client ID, 엔드포인트, 헤더의 원본 | `codex-rs/core/src/auth.rs`, `model_provider_info.rs` |
+| **numman-ali/opencode-openai-codex-auth** | 빠른 변경 반영 (TS라 읽기 쉬움) | `lib/auth/`, `lib/constants.ts` |
+| **ben-vargas/ai-sdk-provider-chatgpt-oauth** | Vercel AI SDK 호환 참조 | `src/auth/` |
+
+### 향후 개선 후보 (codex에서 가져올 수 있는 것)
+
+1. **모델 목록 동적 조회** — `chatgpt.com/backend-api/codex/models` 호출 + JSON 캐시
+2. **refresh 실패 분류** — expired/reused/revoked 구분하여 사용자에게 구체적 안내
+3. **Token Exchange** — OAuth → API Key 변환으로 `api.openai.com` 호환 (듀얼 엔드포인트)
+
+---
+
+## Codex CLI Provider — 리스크
+
+### 왜 취약한가
+
+`codex` provider는 OpenAI `codex` CLI 바이너리를 subprocess로 호출한다.
+CLI의 JSONL 출력 포맷이 변경되면 파싱 실패.
+
+### 현재 동작
+
+- `~/.codex/config.toml`의 model 설정을 우선 흡수
+- `codex --help`, `codex exec --help`를 읽어 command/sandbox capability를 동적 감지
+- 일반 질의는 `read-only`, 코드 수정 의도는 `workspace-write` sandbox 우선
+- 별도 `run_codex_task` tool로 다른 provider에서도 Codex CLI 코드 작업 위임 가능
+
+### 체크 항목
+
+- CLI 출력 포맷: `item.completed.item.agent_message.text` 경로
+- CLI 플래그: `--json`, `--sandbox ...`, `--model ...`, `--skip-git-repo-check`
+- CLI 설치: `npm install -g @openai/codex`
+- 파일: [codex.py](providers/codex.py)
+
+---
+
+## Claude Code CLI Provider — 보류중
+
+### 현재 상태
+
+VSCode 환경에서 `CLAUDECODE` 환경변수가 설정되어 SDK fallback 모드로 진입하지만,
+SDK fallback에서 API key 추출(`claude auth status --json`)이 또 subprocess를 호출하는 순환 문제.
+
+### 알려진 이슈
+
+- 테스트 31/32 pass, `test_complete_timeout` 1개 fail
+- VSCode 내에서 CLI 호출이 hang되는 케이스 (중첩 세션)
+- `_probe_cli()` 8초 타임아웃으로 hang 감지 후 SDK 전환
+- 파일: [claude_code.py](providers/claude_code.py)
+
+---
+
+## 안정 Provider — 특이사항 없음
+
+### openai / custom (openai_compat.py)
+- 공식 `openai` Python SDK 사용
+- 버전 업데이트 시 SDK breaking change만 주의
+- tool calling 지원
+
+### claude (claude.py)
+- 공식 `anthropic` Python SDK + OpenAI 프록시 이중 모드
+- base_url 있으면 OpenAI 호환, 없으면 Anthropic 네이티브
+
+### ollama (ollama.py)
+- localhost:11434 OpenAI 호환 엔드포인트
+- `preload()`, `get_installed_models()`, `complete_json()` 추가 기능
+- tool calling 지원 (v0.3.0+)
+
+---
+
+## 마지막 점검일
+
+- 2026-03-10: ChatGPT OAuth 정상 동작 확인 (gpt-5.4)
+- 2026-03-10: Claude Code 보류 (VSCode 환경이슈)

src/dartlab/ai/__init__.py

@@ -0,0 +1,161 @@
+"""LLM 기반 적극적 분석가. dartlab을 도구로 삼아 주체적으로 분석하고, 사용자의 분석 학습을 돕는다."""
+
+from __future__ import annotations
+
+from dartlab.ai.types import LLMConfig, LLMResponse
+from dartlab.core.ai import (
+    AI_ROLES,
+    DEFAULT_ROLE,
+    get_profile_manager,
+    get_provider_spec,
+    normalize_provider,
+    normalize_role,
+)
+
+
+def configure(
+    provider: str = "codex",
+    model: str | None = None,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    role: str | None = None,
+    temperature: float = 0.3,
+    max_tokens: int = 4096,
+    system_prompt: str | None = None,
+) -> None:
+    """공통 AI profile을 갱신한다."""
+    normalized = normalize_provider(provider) or provider
+    if get_provider_spec(normalized) is None:
+        raise ValueError(f"지원하지 않는 provider: {provider}")
+    normalized_role = normalize_role(role)
+    if role is not None and normalized_role is None:
+        raise ValueError(f"지원하지 않는 role: {role}. 지원: {AI_ROLES}")
+    manager = get_profile_manager()
+    manager.update(
+        provider=normalized,
+        model=model,
+        role=normalized_role,
+        base_url=base_url,
+        temperature=temperature,
+        max_tokens=max_tokens,
+        system_prompt=system_prompt,
+        updated_by="code",
+    )
+    if api_key:
+        spec = get_provider_spec(normalized)
+        if spec and spec.auth_kind == "api_key":
+            manager.save_api_key(normalized, api_key, updated_by="code")
+
+
+def get_config(provider: str | None = None, *, role: str | None = None) -> LLMConfig:
+    """현재 글로벌 LLM 설정 반환."""
+    normalized_role = normalize_role(role)
+    resolved = get_profile_manager().resolve(provider=provider, role=normalized_role)
+    return LLMConfig(**resolved)
+
+
+def status(provider: str | None = None, *, role: str | None = None) -> dict:
+    """LLM 설정 및 provider 상태 확인."""
+    from dartlab.ai.providers import create_provider
+
+    normalized_role = normalize_role(role)
+    config = get_config(provider, role=normalized_role)
+    selected_provider = config.provider
+    llm = create_provider(config)
+    available = llm.check_available()
+
+    result = {
+        "provider": selected_provider,
+        "role": normalized_role or DEFAULT_ROLE,
+        "model": llm.resolved_model,
+        "available": available,
+        "defaultProvider": get_profile_manager().load().default_provider,
+    }
+
+    if selected_provider == "ollama":
+        from dartlab.ai.providers.support.ollama_setup import detect_ollama
+
+        result["ollama"] = detect_ollama()
+
+    if selected_provider == "codex":
+        from dartlab.ai.providers.support.cli_setup import detect_codex
+
+        result["codex"] = detect_codex()
+
+    if selected_provider == "oauth-codex":
+        from dartlab.ai.providers.support import oauth_token as oauthToken
+
+        token_stored = False
+        try:
+            token_stored = oauthToken.load_token() is not None
+        except (OSError, ValueError):
+            token_stored = False
+
+        try:
+            authenticated = oauthToken.is_authenticated()
+            account_id = oauthToken.get_account_id() if authenticated else None
+        except (
+            AttributeError,
+            OSError,
+            RuntimeError,
+            ValueError,
+            oauthToken.TokenRefreshError,
+        ):
+            authenticated = False
+            account_id = None
+
+        result["oauth-codex"] = {
+            "authenticated": authenticated,
+            "tokenStored": token_stored,
+            "accountId": account_id,
+        }
+
+    return result
+
+
+from dartlab.ai.tools.plugin import get_plugin_registry, tool
+
+
+def templates(name: str | None = None):
+    """분석 템플릿 목록 또는 특정 템플릿 내용 반환.
+
+    Args:
+        name: None이면 전체 목록, 지정하면 해당 템플릿 내용.
+
+    Returns:
+        list[dict] (목록) 또는 str (내용) 또는 None.
+    """
+    from dartlab.ai.patterns import get_template, list_templates
+
+    if name is None:
+        return list_templates()
+    return get_template(name)
+
+
+def saveTemplate(name: str, *, content: str | None = None, file: str | None = None):
+    """사용자 분석 템플릿 저장. ~/.dartlab/templates/{name}.md
+
+    Args:
+        name: 템플릿 이름.
+        content: 마크다운 내용.
+        file: 파일 경로 (content 대신).
+
+    Returns:
+        Path — 저장된 파일 경로.
+    """
+    from dartlab.ai.patterns import save_template
+
+    return save_template(name, content=content, file=file)
+
+
+__all__ = [
+    "configure",
+    "get_config",
+    "status",
+    "LLMConfig",
+    "LLMResponse",
+    "tool",
+    "get_plugin_registry",
+    "templates",
+    "saveTemplate",
+]

src/dartlab/ai/context/__init__.py

@@ -0,0 +1,38 @@
+"""ai/context — Context Engineering 레이어 (Phase 1).
+
+Anthropic / DSPy / Manus 계열의 context engineering 패턴을 dartlab에 적용.
+prompt engineering 단계의 고정 텍스트 블록 주입을 동적 컨텍스트 빌더로 대체.
+
+핵심 사상:
+- intent 분류 → selector 동적 호출 → ContextBundle 조립
+- 토큰 예산 우선순위 트리밍
+- TOON 인코딩으로 같은 데이터를 30~60% 적은 토큰으로 주입
+- selfai 폐기 학습 적용: 자동 최적화 X. 모든 선택은 명시적 결정론.
+
+진입점:
+    from dartlab.ai.context import ContextBuilder
+    bundle = ContextBuilder(question=q, company=c, provider="gemini").build()
+
+레이아웃:
+    intent.py    — 질문 → Intent (6막 + compare + concept)
+    selectors/   — Intent별 컨텍스트 선택자
+    budget.py    — provider별 토큰 한도 + 우선순위 트리밍
+    encoder.py   — TOON 인코딩
+    builder.py   — ContextBuilder 메인 진입점
+    bundle.py    — ContextBundle dataclass
+"""
+
+from __future__ import annotations
+
+from dartlab.ai.context.builder import ContextBuilder
+from dartlab.ai.context.bundle import ContextBundle, ContextPart, PartPriority
+from dartlab.ai.context.intent import Intent, classifyIntent
+
+__all__ = [
+    "ContextBuilder",
+    "ContextBundle",
+    "ContextPart",
+    "Intent",
+    "PartPriority",
+    "classifyIntent",
+]

src/dartlab/ai/context/aiview.py

@@ -0,0 +1,360 @@
+"""AI용 데이터 맥락 보강 — 엔진 반환값을 AI가 이해하기 좋은 형태로 변환.
+
+모든 엔진의 dict/DataFrame을 자동 감지해서 맥락을 보강한다.
+엔진별 수작업 0 — 구조(history + period + 숫자)만 보고 판단.
+
+삽입 위치: _calcToContextPart()에서 encodeAuto() 직전.
+    calc result → **autoEnrich()** → encodeAuto(TOON) → ContextPart
+
+근거:
+- Kim et al. (시카고대, 2024): 재무제표 + 맥락 → 이익 방향 60% 정확도
+- TAP4LLM (EMNLP 2024): 서브테이블 + 보강 → +7.93%p
+- 실험 110 A/B: enriched가 raw 대비 코드 0라운드, 해석 명확성 압도
+
+Examples::
+
+    # analysis calc 결과
+    raw = calcMarginTrend(company)
+    # {"history": [{"period": "2025", "operatingMargin": 13.07, ...}, ...]}
+
+    enriched = autoEnrich(raw)
+    # {"_summary": "영업이익률 13.1% · 전기비 +2.2pp(소폭 개선) · 5년평균 위 1.2pp",
+    #  "history": [...],  ← 원본 유지
+    #  "_context": {"marginTrend": {"avg5y": 11.86, "yoy_pp": +2.19, ...}}}
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# ── 비율 필드 감지 키워드 ─────────────────────────────────
+
+_RATIO_KEYWORDS = frozenset({
+    "margin", "ratio", "rate", "roe", "roa", "roic", "turnover",
+    "pct", "yield", "percent", "coverage", "leverage", "yoy",
+    "dso", "dio", "dpo", "ccc", "dol", "payout",
+})
+
+
+def _isRatioField(field: str, value: Any) -> bool:
+    """비율 필드인지 판단 (이름 + 값 범위)."""
+    lower = field.lower()
+    if any(kw in lower for kw in _RATIO_KEYWORDS):
+        return True
+    # 값이 -200~500 범위이고 float이면 비율일 가능성
+    if isinstance(value, (int, float)) and -200 <= value <= 500:
+        # 금액은 보통 1e6 이상
+        return abs(value) < 1e6
+    return False
+
+
+# ── 변화 판단 ─────────────────────────────────────────────
+
+def _judgeChange(delta: float | None, isRatio: bool) -> str:
+    if delta is None:
+        return ""
+    t = 1.0 if isRatio else 5.0
+    if abs(delta) < t * 0.5:
+        return "보합"
+    elif abs(delta) < t * 2:
+        return "소폭 개선" if delta > 0 else "소폭 악화"
+    elif abs(delta) < t * 5:
+        return "개선" if delta > 0 else "악화"
+    else:
+        return "대폭 개선" if delta > 0 else "대폭 악화"
+
+
+# ── 한글 필드명 ───────────────────────────────────────────
+
+_KOREAN = {
+    "operatingMargin": "영업이익률", "netMargin": "순이익률",
+    "grossMargin": "매출총이익률", "roe": "ROE", "roa": "ROA",
+    "roic": "ROIC", "revenue": "매출", "operatingIncome": "영업이익",
+    "netIncome": "순이익", "debtRatio": "부채비율",
+    "equityRatio": "자기자본비율", "ocf": "영업CF", "fcf": "FCF",
+    "capex": "CAPEX", "ccc": "CCC", "dso": "매출채권회수일",
+    "dio": "재고회전일", "dpo": "매입채무회전일",
+    "totalAssetTurnover": "총자산회전율", "revenueYoy": "매출YoY",
+    "operatingIncomeYoy": "영업이익YoY", "netIncomeYoy": "순이익YoY",
+    "costOfSalesRatio": "매출원가율", "sgaRatio": "판관비율",
+    "ocfToNi": "영업CF/순이익", "ocfMargin": "영업CF마진",
+    "interestCoverage": "이자보상배율", "pattern": "CF패턴",
+}
+
+
+def _koreanName(field: str) -> str:
+    return _KOREAN.get(field, field)
+
+
+def _formatNum(value: Any, field: str = "") -> str:
+    if value is None:
+        return "-"
+    if _isRatioField(field, value):
+        return f"{value:.1f}%"
+    if isinstance(value, (int, float)) and abs(value) > 1e12:
+        return f"{value / 1e12:.1f}조"
+    if isinstance(value, (int, float)) and abs(value) > 1e8:
+        return f"{value / 1e8:,.0f}억"
+    if isinstance(value, float):
+        return f"{value:,.1f}"
+    return str(value)
+
+
+# ── 핵심: autoEnrich ─────────────────────────────────────
+
+def autoEnrich(data: dict | list | None, *, company: Any = None, calc_fn: Any = None) -> dict | list | None:
+    """엔진 반환값을 자동 감지해서 AI용 맥락 보강.
+
+    3가지 패턴 자동 감지:
+    - dict with history[] → 시계열 보강 (5년 평균, YoY, 판단)
+    - list[dict] → history 배열로 취급
+    - flat dict → 핵심 필드 요약
+
+    엔진이 새 축을 추가해도 history + period + 숫자 패턴만 유지하면 자동 적용.
+    """
+    if data is None:
+        return None
+
+    # list[dict] — history 배열 직접 전달된 경우
+    if isinstance(data, list) and data and isinstance(data[0], dict):
+        return _enrichHistory(data)
+
+    if not isinstance(data, dict):
+        return data
+
+    # 독스트링 스키마 추출 (있으면 확정 기반, 없으면 자동 감지 fallback)
+    _schema = parseReturnsSchema(calc_fn) if callable(calc_fn) else None
+
+    # 최상위에 바로 history[]가 있는 경우 (개별 calc 결과: {"history": [...], "displayHints": {...}})
+    if "history" in data and isinstance(data["history"], list) and data["history"]:
+        summary = _summarizeHistory(data["history"], "data", schema=_schema)
+        if summary:
+            enriched = dict(data)
+            enriched["_summary"] = summary
+            return enriched
+        return data
+
+    # 중첩 history — 전체 analysis dict: {"marginTrend": {"history": [...]}, ...}
+    tsKeys = [
+        k for k, v in data.items()
+        if isinstance(v, dict)
+        and "history" in v
+        and isinstance(v["history"], list)
+        and v["history"]
+    ]
+    if tsKeys:
+        return _enrichDictWithHistory(data, tsKeys, company=company)
+
+    # flat dict (숫자 키가 있는) — credit, quant
+    numericKeys = [k for k, v in data.items() if isinstance(v, (int, float))]
+    if numericKeys:
+        return _enrichFlat(data)
+
+    return data
+
+
+# ── 패턴 1: dict with history[] ──────────────────────────
+
+def _enrichDictWithHistory(
+    data: dict, tsKeys: list[str], *, company: Any = None,
+) -> dict:
+    """history[] 시계열을 자동 보강. 모든 analysis 축에 범용 적용."""
+    summaries: list[str] = []
+
+    for tsKey in tsKeys:
+        hist = data[tsKey]["history"]
+        if not hist:
+            continue
+        summary = _summarizeHistory(hist, tsKey)
+        if summary:
+            summaries.append(summary)
+
+    # _summary 필드에 전체 요약 삽입 (원본 data에 추가)
+    enriched = dict(data)
+    if summaries:
+        enriched["_summary"] = " / ".join(summaries[:4])
+
+    return enriched
+
+
+def _enrichHistory(rows: list[dict]) -> dict:
+    """history 배열 직접 전달 시."""
+    summary = _summarizeHistory(rows, "data")
+    return {"_summary": summary, "history": rows} if summary else {"history": rows}
+
+
+def _summarizeHistory(hist: list[dict], label: str, *, schema: dict | None = None) -> str:
+    """history 배열에서 비율 필드를 자동 감지, 핵심 3개의 요약문 생성."""
+    if not hist or len(hist) < 2:
+        return ""
+
+    latest = hist[0]
+    prev = hist[1]
+
+    # 모든 숫자 필드 감지
+    numericFields = [
+        k for k, v in latest.items()
+        if isinstance(v, (int, float)) and k != "period"
+    ]
+    if not numericFields:
+        return ""
+
+    fieldInfos: list[dict] = []
+    for field in numericFields:
+        values = [h.get(field) for h in hist[:5] if h.get(field) is not None]
+        if not values:
+            continue
+
+        current = values[0]
+        # 독스트링 스키마 우선, 없으면 자동 감지 fallback
+        schemaResult = isRatioBySchema(field, schema) if schema else None
+        isRatio = schemaResult if schemaResult is not None else _isRatioField(field, current)
+        prevVal = values[1] if len(values) >= 2 else None
+        avg5 = sum(values) / len(values)
+
+        # YoY — 비율은 pp 차이, 금액은 변화율(%)
+        yoy = None
+        if prevVal is not None:
+            if isRatio:
+                yoy = current - prevVal
+            elif prevVal != 0:
+                yoy = (current - prevVal) / abs(prevVal) * 100
+
+        # 5년 평균 대비
+        vsAvg = None
+        if isRatio:
+            vsAvg = current - avg5
+        elif avg5 != 0:
+            vsAvg = (current - avg5) / abs(avg5) * 100
+
+        fieldInfos.append({
+            "field": field,
+            "current": current,
+            "isRatio": isRatio,
+            "yoy": round(yoy, 2) if yoy is not None else None,
+            "vsAvg": round(vsAvg, 2) if vsAvg is not None else None,
+            "judgment": _judgeChange(yoy, isRatio),
+            "avg5": round(avg5, 2),
+        })
+
+    # 비율 필드 우선, 변화가 큰 순
+    ratios = [f for f in fieldInfos if f["isRatio"]]
+    amounts = [f for f in fieldInfos if not f["isRatio"]]
+    picked = sorted(ratios, key=lambda x: abs(x["yoy"] or 0), reverse=True)[:3]
+    if not picked:
+        picked = sorted(amounts, key=lambda x: abs(x["yoy"] or 0), reverse=True)[:2]
+
+    # 요약 문장 생성
+    parts = []
+    for fi in picked:
+        unit = "pp" if fi["isRatio"] else "%"
+        segs = [f"{_koreanName(fi['field'])} {_formatNum(fi['current'], fi['field'])}"]
+        if fi["yoy"] is not None:
+            segs.append(f"전기비 {fi['yoy']:+.1f}{unit}({fi['judgment']})")
+        if fi["vsAvg"] is not None:
+            pos = "위" if fi["vsAvg"] > 0 else "아래"
+            segs.append(f"5년평균 {pos} {abs(fi['vsAvg']):.1f}{unit}")
+        parts.append(" · ".join(segs))
+
+    return f"[{label}] {' | '.join(parts)}" if parts else ""
+
+
+# ── 패턴 2: flat dict ────────────────────────────────────
+
+def _enrichFlat(data: dict) -> dict:
+    """flat dict 보강 — credit, quant 결과."""
+    summaryParts = []
+    for k, v in data.items():
+        if isinstance(v, str) and len(v) < 50:
+            summaryParts.append(f"{_koreanName(k)}={v}")
+        elif isinstance(v, (int, float)):
+            summaryParts.append(f"{_koreanName(k)}={_formatNum(v, k)}")
+    if not summaryParts:
+        return data
+    enriched = dict(data)
+    enriched["_summary"] = " · ".join(summaryParts[:6])
+    return enriched
+
+
+# ── 독스트링 기반 스키마 파싱 ──────────────────────────────
+
+import re
+from functools import lru_cache
+from typing import Callable
+
+_UNIT_PATTERN = re.compile(r"\((%|원|일|배|점)\)")
+
+
+@lru_cache(maxsize=256)
+def parseReturnsSchema(fn: Callable) -> dict[str, dict] | None:
+    """함수의 docstring에서 Returns 스키마를 파싱.
+
+    Returns dict 예시::
+
+        {
+            "operatingMargin": {"type": "float", "unit": "%", "desc": "영업이익률"},
+            "revenue": {"type": "float", "unit": "원", "desc": "매출"},
+        }
+
+    독스트링에 Returns 섹션이 없으면 None.
+    """
+    doc = getattr(fn, "__doc__", None)
+    if not doc:
+        return None
+
+    # Returns 섹션 추출
+    lines = doc.split("\n")
+    inReturns = False
+    returnsLines: list[str] = []
+    for line in lines:
+        stripped = line.strip()
+        if stripped == "Returns":
+            inReturns = True
+            continue
+        if inReturns and stripped.startswith("-------"):
+            continue
+        if inReturns:
+            # 다른 섹션 시작 감지 (Raises, Examples, Notes, Guide, See Also)
+            if stripped and not stripped[0].isspace() and stripped[0] != " " and ":" not in stripped and stripped in (
+                "Raises", "Examples", "Notes", "Guide", "See Also", "Parameters",
+            ):
+                break
+            # 빈 줄 다음에 섹션 헤더가 올 수 있음
+            if stripped and re.match(r"^[A-Z][a-z]", stripped) and not any(c in stripped for c in (":", "—", "-")):
+                break
+            returnsLines.append(line)
+
+    if not returnsLines:
+        return None
+
+    # 키 : 타입 — 설명 (단위) 패턴 파싱
+    schema: dict[str, dict] = {}
+    for line in returnsLines:
+        # "    operatingMargin : float — 영업이익률 (%)" 패턴
+        m = re.match(r"\s+(\w+)\s*:\s*(\w[\w\[\]]*)\s*[—-]\s*(.+)", line)
+        if not m:
+            continue
+        key, typ, desc = m.group(1), m.group(2), m.group(3).strip()
+
+        # 단위 추출
+        unit_match = _UNIT_PATTERN.search(desc)
+        unit = unit_match.group(1) if unit_match else None
+
+        schema[key] = {"type": typ, "desc": desc, "unit": unit}
+
+    return schema if schema else None
+
+
+def isRatioBySchema(field: str, schema: dict[str, dict] | None) -> bool | None:
+    """스키마에서 필드의 단위를 확인해서 비율인지 확정.
+
+    Returns True(비율)/False(금액)/None(스키마에 없음 → fallback 필요).
+    """
+    if schema is None or field not in schema:
+        return None
+    unit = schema[field].get("unit")
+    if unit == "%":
+        return True
+    if unit in ("원", "일"):
+        return False
+    return None

src/dartlab/ai/context/budget.py

@@ -0,0 +1,68 @@
+"""토큰 예산 + 우선순위 트리밍.
+
+provider별 컨텍스트 한도를 기준으로 ContextPart 리스트를 정리.
+CRITICAL은 절대 제거하지 않고, OPTIONAL부터 자른다.
+"""
+
+from __future__ import annotations
+
+from dartlab.ai.context.bundle import ContextPart, PartPriority
+
+# provider별 안전 컨텍스트 예산 (system + user 합계 기준 권장치)
+# 보수적으로 설정 — 응답 토큰 여유 확보.
+_PROVIDER_BUDGETS: dict[str, int] = {
+    "gemini": 30000,
+    "openai": 12000,
+    "groq": 6000,
+    "cerebras": 6000,
+    "mistral": 8000,
+    "ollama": 4000,
+    "claude": 30000,
+    "claude_code": 30000,
+    "codex": 12000,
+    "oauth_codex": 12000,
+}
+
+_DEFAULT_BUDGET = 8000
+
+
+def budgetFor(provider: str | None) -> int:
+    """provider 이름 → 권장 컨텍스트 예산 토큰."""
+    if not provider:
+        return _DEFAULT_BUDGET
+    return _PROVIDER_BUDGETS.get(provider.lower(), _DEFAULT_BUDGET)
+
+
+def trim(
+    parts: list[ContextPart],
+    *,
+    budgetTokens: int,
+) -> tuple[list[ContextPart], list[str]]:
+    """우선순위 기반 트리밍.
+
+    Returns:
+        (kept, droppedKeys)
+        - kept: 예산 안에 들어간 parts (priority 내림차순)
+        - droppedKeys: 잘려나간 part key 리스트
+    """
+    # priority 내림차순 정렬 (높은 우선순위 먼저)
+    sorted_parts = sorted(parts, key=lambda p: p.priority, reverse=True)
+
+    kept: list[ContextPart] = []
+    dropped: list[str] = []
+    used = 0
+
+    for part in sorted_parts:
+        # CRITICAL은 예산 초과해도 무조건 포함 (안전장치)
+        if part.priority == PartPriority.CRITICAL:
+            kept.append(part)
+            used += part.estimatedTokens
+            continue
+
+        if used + part.estimatedTokens <= budgetTokens:
+            kept.append(part)
+            used += part.estimatedTokens
+        else:
+            dropped.append(part.key)
+
+    return kept, dropped

src/dartlab/ai/context/builder.py

@@ -0,0 +1,195 @@
+"""ContextBuilder — Phase 1 메인 진입점.
+
+질문 + Company + provider → ContextBundle.
+
+설계:
+1. classifyIntent() 로 질문 의도 파악
+2. legacy selectors 호출 → 기존 5개 pre-grounding을 ContextPart로
+3. (Phase 1.5) intent별 act selector 호출
+4. budget.trim() 으로 토큰 예산 적용
+5. ContextBundle 반환
+
+Phase 1 보장: 기존 _analyze_inner 동작과 동일 (legacy selectors만 사용).
+DARTLAB_CONTEXT_V2=1 환경 변수로 활성화.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from dartlab.ai.context.budget import budgetFor, trim
+from dartlab.ai.context.bundle import ContextBundle, ContextPart
+from dartlab.ai.context.intent import Intent, classifyIntent
+from dartlab.ai.context.selectors import (
+    selectCompanySearch,
+    selectDisclosureBrief,
+    selectExternalSearch,
+    selectInsightHints,
+    selectMemoryHints,
+    selectPlaybookBullets,
+)
+
+
+@dataclass
+class ContextBuilder:
+    """질문 → ContextBundle 빌더.
+
+    사용::
+
+        bundle = ContextBuilder(
+            question="삼성전자 마진 추세는?",
+            company=c,
+            provider="gemini",
+        ).build()
+
+        userParts = bundle.toUserParts()  # 기존 _analyze_inner 호환
+    """
+
+    question: str
+    company: Any | None = None
+    provider: str | None = None
+    budgetTokens: int | None = None  # None → provider별 기본값
+
+    def build(self) -> ContextBundle:
+        if not self.question or not self.question.strip():
+            return ContextBundle(intent=Intent.ACT_ALL.value)
+
+        # Company 메타 추출
+        stockCode = (
+            getattr(self.company, "stockCode", None) or getattr(self.company, "ticker", None)
+            if self.company is not None
+            else None
+        )
+        corpName = getattr(self.company, "corpName", None) if self.company is not None else None
+
+        # 1. Intent 분류
+        intentResult = classifyIntent(self.question, hasCompany=self.company is not None)
+
+        # 2. selector 호출 (legacy + ACE playbook + analysis calc)
+        parts: list[ContextPart] = []
+        parts.extend(selectCompanySearch(self.question, self.company))
+        parts.extend(selectDisclosureBrief(stockCode))
+        parts.extend(selectExternalSearch(self.question, stockCode, corpName))
+        parts.extend(selectMemoryHints(stockCode))
+        parts.extend(selectInsightHints(stockCode, self.company))
+        # ACE evolving playbook — intent별 학습된 분석 지침 주입
+        parts.extend(selectPlaybookBullets(intentResult.intent.value, self.company))
+        # intent → analysis calc selector 라우팅
+        parts.extend(self._selectCalcForIntent(intentResult.intent))
+        # Phase 2: 인과 질문("왜") → graph traversal
+        try:
+            from dartlab.ai.context.selectors.graph import selectGraphCauses
+
+            parts.extend(selectGraphCauses(self.question, self.company))
+        except ImportError:
+            pass
+
+        # 3. 분석 대상 라벨 (CRITICAL — 항상 포함)
+        if corpName and stockCode:
+            from dartlab.ai.context.bundle import PartPriority
+            from dartlab.ai.context.encoder import estimateTokens
+
+            label = f"분석 대상: {corpName} (종목코드: {stockCode})"
+            parts.insert(
+                0,
+                ContextPart(
+                    key="company.label",
+                    text=label,
+                    priority=PartPriority.CRITICAL,
+                    estimatedTokens=estimateTokens(label),
+                    source="company.meta",
+                ),
+            )
+
+        # 4. concept selector (Company 불필요)
+        if intentResult.intent == Intent.CONCEPT:
+            try:
+                from dartlab.ai.context.selectors.concept import selectConcept
+
+                parts.extend(selectConcept(self.question))
+            except ImportError:
+                pass
+
+        # 5. 예산 트리밍
+        budget = self.budgetTokens or budgetFor(self.provider)
+        kept, dropped = trim(parts, budgetTokens=budget)
+
+        totalTokens = sum(p.estimatedTokens for p in kept)
+        return ContextBundle(
+            parts=kept,
+            intent=intentResult.intent.value,
+            totalTokens=totalTokens,
+            droppedKeys=dropped,
+        )
+
+    def _selectCalcForIntent(self, intent: Intent) -> list[ContextPart]:
+        """intent → analysis calc selector 라우팅.
+
+        Company 없으면 빈 리스트. calc 실패 시 빈 리스트 (graceful).
+        ACT_ALL → 핵심 3개(margin + cashflow + distress)만.
+        """
+        if self.company is None:
+            return []
+        try:
+            _ROUTER = {
+                Intent.ACT1_BUSINESS: "dartlab.ai.context.selectors.act1",
+                Intent.ACT2_PROFIT: "dartlab.ai.context.selectors.act2",
+                Intent.ACT3_CASH: "dartlab.ai.context.selectors.act3",
+                Intent.ACT4_STABILITY: "dartlab.ai.context.selectors.act4",
+                Intent.ACT5_CAPITAL: "dartlab.ai.context.selectors.act5",
+                Intent.ACT6_OUTLOOK: "dartlab.ai.context.selectors.act6",
+                Intent.COMPARE: "dartlab.ai.context.selectors.compare",
+            }
+            if intent == Intent.ACT_ALL:
+                # 핵심 3축만 주입 (마진 + 현금흐름 + 안정성)
+                parts: list[ContextPart] = []
+                try:
+                    from dartlab.ai.context.selectors.act2 import selectAct2
+
+                    parts.extend(selectAct2(self.company))
+                except (ImportError, Exception):
+                    pass
+                try:
+                    from dartlab.ai.context.selectors.act3 import selectAct3
+
+                    parts.extend(selectAct3(self.company))
+                except (ImportError, Exception):
+                    pass
+                try:
+                    from dartlab.ai.context.selectors.act4 import selectAct4
+
+                    parts.extend(selectAct4(self.company))
+                except (ImportError, Exception):
+                    pass
+                return parts
+
+            module_path = _ROUTER.get(intent)
+            if not module_path:
+                return []
+
+            import importlib
+
+            mod = importlib.import_module(module_path)
+            # 함수 이름 규칙: selectAct{N}, selectCompare
+            fn_name = (
+                f"select{intent.value.split('_')[0].title()}"
+                if "_" in intent.value
+                else f"select{intent.value.title()}"
+            )
+            # 실제 함수명 매핑
+            _FN_NAMES = {
+                Intent.ACT1_BUSINESS: "selectAct1",
+                Intent.ACT2_PROFIT: "selectAct2",
+                Intent.ACT3_CASH: "selectAct3",
+                Intent.ACT4_STABILITY: "selectAct4",
+                Intent.ACT5_CAPITAL: "selectAct5",
+                Intent.ACT6_OUTLOOK: "selectAct6",
+                Intent.COMPARE: "selectCompare",
+            }
+            fn = getattr(mod, _FN_NAMES[intent])
+            if intent == Intent.COMPARE:
+                return fn(self.company)
+            return fn(self.company)
+        except (ImportError, AttributeError, KeyError, Exception):
+            return []

src/dartlab/ai/context/bundle.py

@@ -0,0 +1,66 @@
+"""ContextBundle — ContextBuilder 출력 자료구조.
+
+builder는 selector들이 만든 ContextPart 리스트를 priority + budget에 따라
+트리밍하여 최종 ContextBundle을 만든다. 소비자(_analyze_inner)는
+bundle.toUserParts() 로 기존 userParts 리스트와 호환되는 형태를 얻는다.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import IntEnum
+
+
+class PartPriority(IntEnum):
+    """우선순위 — 낮을수록 먼저 트리밍된다.
+
+    예산 부족 시 LOW부터 제거하고 CRITICAL은 절대 제거하지 않는다.
+    """
+
+    CRITICAL = 100  # 분석 대상 종목/회사명 — 절대 트리밍 금지
+    HIGH = 80  # analysis calc 결과 (intent 매칭)
+    MEDIUM = 60  # 인사이트, 그래프 traversal
+    LOW = 40  # 외부 검색, 메모리 힌트
+    OPTIONAL = 20  # few-shot 예시
+
+
+@dataclass(frozen=True)
+class ContextPart:
+    """단일 컨텍스트 블록.
+
+    selector가 생성하고 builder가 budget에 따라 취사선택한다.
+    """
+
+    key: str  # selector 식별자 (예: "act2.marginTrend")
+    text: str  # 사람이 읽는 텍스트 (TOON 또는 마크다운)
+    priority: PartPriority
+    estimatedTokens: int  # rough — len(text) // 3 정도면 충분
+    source: str = ""  # 출처 (예: "calc:profitability", "knowledgedb:insight")
+
+    def __post_init__(self) -> None:
+        if not self.text:
+            raise ValueError(f"ContextPart.text empty: key={self.key}")
+
+
+@dataclass
+class ContextBundle:
+    """ContextBuilder 최종 출력.
+
+    소비자는 toUserParts() 로 기존 코드 (_analyze_inner) 와 호환되는 리스트를 얻는다.
+    parts 는 priority 내림차순 정렬되어 있다.
+    """
+
+    parts: list[ContextPart] = field(default_factory=list)
+    intent: str = ""
+    totalTokens: int = 0
+    droppedKeys: list[str] = field(default_factory=list)  # budget으로 잘린 part keys
+
+    def toUserParts(self) -> list[str]:
+        """기존 _analyze_inner userParts 호환 — text 리스트만."""
+        return [p.text for p in self.parts]
+
+    def keys(self) -> list[str]:
+        return [p.key for p in self.parts]
+
+    def __len__(self) -> int:
+        return len(self.parts)

src/dartlab/ai/context/encoder.py

@@ -0,0 +1,115 @@
+"""TOON (Token-Oriented Object Notation) 인코더.
+
+LLM 입력용 압축 표현. 같은 데이터를 JSON 대비 30~60% 적은 토큰으로 주입.
+일부 케이스(작은 dict)에는 효과 없음 — encodeAuto가 작은 입력은 JSON 유지.
+
+참조: TOON 사양 (2026, llm-data 압축 포맷)
+- 키: 한 번만 등장 (헤더 행)
+- 값: 행 단위 정렬
+- 깊은 중첩 최소화 (LLM 어텐션이 가장 잘 처리하는 형태)
+
+dartlab은 외부 의존성 추가 없이 자체 구현 — 단순 직렬화.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def _isFlatList(value: Any) -> bool:
+    """list[dict] 형태이고 모든 dict가 같은 키 집합인지."""
+    if not isinstance(value, list) or not value:
+        return False
+    if not all(isinstance(x, dict) for x in value):
+        return False
+    first_keys = tuple(value[0].keys())
+    return all(tuple(x.keys()) == first_keys for x in value)
+
+
+def _encodeFlatList(rows: list[dict[str, Any]]) -> str:
+    """list[dict] → TOON 표 형식.
+
+    예::
+
+        [{"a": 1, "b": 2}, {"a": 3, "b": 4}]
+        →
+        a|b
+        1|2
+        3|4
+    """
+    if not rows:
+        return ""
+    keys = list(rows[0].keys())
+    header = "|".join(keys)
+    lines = [header]
+    for row in rows:
+        cells = []
+        for k in keys:
+            v = row.get(k)
+            if v is None:
+                cells.append("")
+            elif isinstance(v, (int, float, str, bool)):
+                cells.append(str(v))
+            else:
+                cells.append(json.dumps(v, ensure_ascii=False, default=str))
+        lines.append("|".join(cells))
+    return "\n".join(lines)
+
+
+def _encodeDict(d: dict[str, Any], depth: int = 0) -> str:
+    """dict → TOON key:value 행 형식. 중첩 list[dict]는 표로 변환."""
+    if not d:
+        return ""
+    lines = []
+    indent = "  " * depth
+    for k, v in d.items():
+        if _isFlatList(v):
+            lines.append(f"{indent}{k}:")
+            table = _encodeFlatList(v)
+            lines.extend(f"{indent}  {ln}" for ln in table.split("\n"))
+        elif isinstance(v, dict):
+            lines.append(f"{indent}{k}:")
+            lines.append(_encodeDict(v, depth + 1))
+        elif isinstance(v, list):
+            # 단순 list[scalar] — 한 줄에 ,로
+            lines.append(f"{indent}{k}: " + ", ".join(str(x) for x in v))
+        elif v is None:
+            lines.append(f"{indent}{k}: -")
+        else:
+            lines.append(f"{indent}{k}: {v}")
+    return "\n".join(lines)
+
+
+def encodeTOON(data: Any) -> str:
+    """임의 데이터 → TOON 텍스트.
+
+    list[dict] (균질) → 표 형식
+    dict → key:value (중첩 처리)
+    그 외 → JSON fallback
+    """
+    if _isFlatList(data):
+        return _encodeFlatList(data)
+    if isinstance(data, dict):
+        return _encodeDict(data)
+    return json.dumps(data, ensure_ascii=False, default=str)
+
+
+def encodeAuto(data: Any, *, jsonThresholdChars: int = 200) -> str:
+    """작은 입력은 JSON, 큰 입력은 TOON.
+
+    작은 dict는 JSON이 더 짧을 수 있음 (헤더 오버헤드 없음).
+    """
+    js = json.dumps(data, ensure_ascii=False, default=str)
+    if len(js) < jsonThresholdChars:
+        return js
+    toon = encodeTOON(data)
+    # TOON이 더 길면 JSON 사용 (안전장치)
+    return toon if len(toon) < len(js) else js
+
+
+def estimateTokens(text: str) -> int:
+    """rough 토큰 추정 — 한국어 + 영문 혼합 기준 평균 1토큰 ≈ 2.5 chars."""
+    if not text:
+        return 0
+    return max(1, len(text) // 3)

src/dartlab/ai/context/intent.py

@@ -0,0 +1,236 @@
+"""Intent 분류 — 질문 → 6막 + compare + concept.
+
+LLM 호출 없이 키워드 매칭 + Company 상태 + 패턴으로 결정론적 분류.
+selfai 폐기 학습 적용: ML 없음, 모든 규칙은 명시적 코드.
+
+8개 Intent:
+    act1_business    — 사업이해 (수익구조, 성장성)
+    act2_profit      — 수익성 (마진, 비용구조)
+    act3_cash        — 현금흐름 (CF, 이익품질)
+    act4_stability   — 안정성 (부채, 신용)
+    act5_capital     — 자본배분 (배당, ROIC)
+    act6_outlook     — 전망 (가치평가, 매크로)
+    compare          — 시장 비교 (scan)
+    concept          — 개념질문 (capabilities, docs)
+
+오분류 fallback: act_all (핵심 축 요약 주입)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class Intent(str, Enum):
+    ACT1_BUSINESS = "act1_business"
+    ACT2_PROFIT = "act2_profit"
+    ACT3_CASH = "act3_cash"
+    ACT4_STABILITY = "act4_stability"
+    ACT5_CAPITAL = "act5_capital"
+    ACT6_OUTLOOK = "act6_outlook"
+    COMPARE = "compare"
+    CONCEPT = "concept"
+    ACT_ALL = "act_all"  # fallback — 의도가 명확하지 않거나 종합 질문
+
+
+# ── 키워드 사전 ────────────────────────────────────────────
+# 각 막에 배타적으로 강한 신호만 등록. 약한 키워드는 act_all로 떨어져도 OK.
+
+_KEYWORDS: dict[Intent, tuple[str, ...]] = {
+    Intent.ACT1_BUSINESS: (
+        "사업",
+        "비즈니스",
+        "매출구성",
+        "사업부",
+        "세그먼트",
+        "segment",
+        "제품",
+        "서비스",
+        "고객",
+        "시장점유",
+        "시장 점유",
+        "성장",
+        "뭐하는",
+        "뭘 하는",
+        "어떤 회사",
+        "뭐 해서",
+        "뭐해서",
+        "돈 벌",
+        "돈벌",
+        "수익원",
+    ),
+    Intent.ACT2_PROFIT: (
+        "수익성",
+        "마진",
+        "영업이익률",
+        "순이익률",
+        "ROIC",
+        "ROE",
+        "ROA",
+        "비용구조",
+        "원가",
+        "판관비",
+        "이익률",
+        "수익",
+        "벌고",
+    ),
+    Intent.ACT3_CASH: (
+        "현금",
+        "현금흐름",
+        "OCF",
+        "FCF",
+        "이익품질",
+        "운전자본",
+        "감가상각",
+        "발생액",
+        "현금전환",
+    ),
+    Intent.ACT4_STABILITY: (
+        "부채",
+        "안정성",
+        "재무건전",
+        "이자보상",
+        "유동",
+        "차입",
+        "신용",
+        "부실",
+        "Z-Score",
+        "ICR",
+        "디폴트",
+        "default",
+    ),
+    Intent.ACT5_CAPITAL: (
+        "배당",
+        "자사주",
+        "자본배분",
+        "주주환원",
+        "유보",
+        "재투자",
+        "CAPEX",
+        "WACC",
+    ),
+    Intent.ACT6_OUTLOOK: (
+        "전망",
+        "예측",
+        "추정",
+        "valuation",
+        "DCF",
+        "PER",
+        "PBR",
+        "목표가",
+        "적정가",
+        "고평가",
+        "저평가",
+        "안전마진",
+        "매크로",
+        "환율",
+        "금리",
+        "유가",
+    ),
+    Intent.COMPARE: (
+        "비교",
+        "랭킹",
+        "순위",
+        "상위",
+        "하위",
+        "대비",
+        "vs",
+        "VS",
+        "동종",
+        "동종업계",
+        "peer",
+        "scan",
+        "스캔",
+        "전종목",
+        "업종 평균",
+        "업종평균",
+        # NOTE: "보다 큰/작은/높/낮" 은 두 지표 간 비교에도 자주 쓰여 제외.
+        # COMPARE 는 회사 간 비교일 때만 매칭되도록 명시적 키워드만 둔다.
+    ),
+    Intent.CONCEPT: (
+        "사용법",
+        "어떻게 쓰",
+        "어떻게 사용",
+        "어떻게 호출",
+        "방법 알려",
+        "예시",
+        "예제",
+        "튜토리얼",
+        "dartlab",
+        "ask(",
+        "show(",
+        "select(",
+        "analysis(",
+        "review(",
+        "공시 어디",
+        "어디서 찾",
+    ),
+}
+
+
+@dataclass(frozen=True)
+class IntentResult:
+    intent: Intent
+    confidence: float  # 0.0~1.0 — 매칭된 키워드 / 후보 키워드 비율
+    matchedKeywords: tuple[str, ...]
+
+
+def _scoreIntent(question: str, intent: Intent) -> tuple[float, tuple[str, ...]]:
+    """단일 intent 점수 + 매칭된 키워드 반환."""
+    q = question.lower()
+    keywords = _KEYWORDS[intent]
+    matched = tuple(kw for kw in keywords if kw.lower() in q)
+    if not matched:
+        return 0.0, ()
+    # 매칭 키워드 수 / 후보 수 — 정규화. 단순 카운트 우선.
+    score = len(matched) / max(len(keywords), 1)
+    # 매칭 1개라도 있으면 최소 0.2 보장 (희소 키워드 보호)
+    return max(score, 0.2), matched
+
+
+def classifyIntent(
+    question: str,
+    *,
+    hasCompany: bool = False,
+) -> IntentResult:
+    """질문 → IntentResult.
+
+    Args:
+        question: 사용자 질문
+        hasCompany: Company 객체 존재 여부 (없으면 CONCEPT/COMPARE 가중치)
+
+    Returns:
+        IntentResult — 가장 높은 점수의 intent. 동점은 정의 순서.
+    """
+    if not question or not question.strip():
+        return IntentResult(Intent.ACT_ALL, 0.0, ())
+
+    scores: list[tuple[Intent, float, tuple[str, ...]]] = []
+    for intent in (
+        Intent.COMPARE,  # compare 먼저 — "비교" 키워드가 다른 막과 섞일 때 우선
+        Intent.CONCEPT,
+        Intent.ACT2_PROFIT,
+        Intent.ACT3_CASH,
+        Intent.ACT4_STABILITY,
+        Intent.ACT5_CAPITAL,
+        Intent.ACT6_OUTLOOK,
+        Intent.ACT1_BUSINESS,
+    ):
+        score, matched = _scoreIntent(question, intent)
+        if score > 0:
+            scores.append((intent, score, matched))
+
+    if not scores:
+        return IntentResult(Intent.ACT_ALL, 0.0, ())
+
+    # Company 없으면 막 관련 intent는 의미 없음 → CONCEPT/COMPARE 우대
+    if not hasCompany:
+        prioritized = [s for s in scores if s[0] in (Intent.CONCEPT, Intent.COMPARE)]
+        if prioritized:
+            scores = prioritized
+
+    # 최고 점수 선택 (동점은 위 순서 유지)
+    scores.sort(key=lambda s: s[1], reverse=True)
+    best = scores[0]
+    return IntentResult(best[0], best[1], best[2])

src/dartlab/ai/context/playbook.py

@@ -0,0 +1,220 @@
+"""ACE Curator/Reflector — dartlab 결정론 구현.
+
+논문: arxiv.org/abs/2510.04618 (ICLR 2026, Stanford+UCB+SambaNova)
+
+ACE 3 컴포넌트 매핑:
+    Generator  = ai/runtime/core.py::_streamWithCodeExecution (이미 있음)
+    Reflector  = extractBullets() — 응답 텍스트에서 bullet 추출 (결정론)
+    Curator    = curate() — KnowledgeDB.upsert_bullet 위임 (delta merge)
+
+핵심 규칙 (논문):
+    1. delta merge — 기존 bullet 절대 삭제 X. context collapse 방지.
+    2. bullet은 한 줄 (200자 cap), 중첩 금지.
+    3. success/fail 카운트 → quality (Beta posterior 근사).
+    4. retrieval은 quality desc, 섹터 우선 매칭.
+
+selfai 폐기 학습 적용:
+    - LLM Reflector 안 씀 (페이퍼는 LLM Reflector 사용).
+    - dartlab은 결정론 regex/패턴 추출만 — 디버깅 가능, 토큰 비용 0.
+    - 효과 검증 후 LLM Reflector 단계 도입 검토.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# ── Reflector: 응답 → bullet 결정론 추출 ───────────────────
+
+# 의미 있는 한 줄 패턴 (한국어 분석 응답 기준)
+_BULLET_HEADERS = (
+    "결론",
+    "핵심",
+    "요약",
+    "판단",
+    "주의",
+    "리스크",
+    "강점",
+    "약점",
+    "관전",
+    "관찰",
+)
+
+_BULLET_LINE_RE = re.compile(
+    r"^\s*[-*•]\s*(.+?)$",
+    re.MULTILINE,
+)
+
+_HEADER_LINE_RE = re.compile(
+    rf"(?:{'|'.join(_BULLET_HEADERS)})[:：]\s*([^\n]{{8,180}})",
+)
+
+# 너무 짧거나 무의미한 패턴 차단
+_NOISE_RE = re.compile(r"^(있다|없다|확인|분석|참고|참조)\.?$")
+
+
+def _cleanBullet(text: str) -> str | None:
+    """bullet 정제 — 길이/노이즈 필터."""
+    text = re.sub(r"\s+", " ", text).strip()
+    text = text.strip("-*•·#> .").strip()
+    if not text:
+        return None
+    if len(text) < 8 or len(text) > 200:
+        return None
+    if _NOISE_RE.match(text):
+        return None
+    # 코드/표 라인 제외
+    if "|" in text and text.count("|") >= 3:
+        return None
+    if text.startswith("```"):
+        return None
+    return text
+
+
+def extractBullets(response_text: str, *, max_bullets: int = 8) -> list[str]:
+    """응답 텍스트 → 핵심 bullet 리스트.
+
+    추출 우선순위:
+    1. "결론:", "핵심:", "주의:" 등 헤더 매칭 (가장 신뢰)
+    2. 마크다운 리스트 항목 (- / * / •)
+    3. 위 둘 다 없으면 빈 리스트 (조용히 실패)
+    """
+    if not response_text:
+        return []
+    bullets: list[str] = []
+    seen: set[str] = set()
+
+    # 1. 헤더 매칭
+    for m in _HEADER_LINE_RE.finditer(response_text):
+        cleaned = _cleanBullet(m.group(1))
+        if cleaned and cleaned not in seen:
+            bullets.append(cleaned)
+            seen.add(cleaned)
+            if len(bullets) >= max_bullets:
+                return bullets
+
+    # 2. 마크다운 리스트
+    for m in _BULLET_LINE_RE.finditer(response_text):
+        cleaned = _cleanBullet(m.group(1))
+        if cleaned and cleaned not in seen:
+            bullets.append(cleaned)
+            seen.add(cleaned)
+            if len(bullets) >= max_bullets:
+                return bullets
+
+    return bullets
+
+
+# ── grade → outcome 매핑 ──────────────────────────────────
+
+
+def gradeToOutcome(grade: str | None) -> str:
+    """KnowledgeDB executions.grade → upsert_bullet outcome.
+
+    dartlab grade 체계:
+        G — Good (성공)
+        T — Trivial (보통, neutral)
+        C — Crash (실패)
+        V — Vague (실패 — 모호한 답변)
+        P — Partial (성공 — 부분적이지만 가치 있음)
+    """
+    g = (grade or "").upper().strip()
+    if g in ("G", "P"):
+        return "success"
+    if g in ("C", "V"):
+        return "fail"
+    return "neutral"
+
+
+# ── Curator: bullet 묶음을 KnowledgeDB로 영속 ────────────
+
+
+@dataclass
+class CurateResult:
+    intent: str
+    sector: str
+    inserted: int
+    skipped: int
+
+
+def curate(
+    *,
+    intent: str,
+    response_text: str,
+    grade: str | None,
+    sector: str = "",
+    source: str = "reflection",
+) -> CurateResult:
+    """Reflector + Curator 한 번에 호출.
+
+    1. extractBullets — 결정론 추출
+    2. gradeToOutcome — success/fail/neutral 결정
+    3. KnowledgeDB.upsert_bullet — delta merge
+
+    실패 (DB 없음/import 실패) 시 빈 결과 반환, 예외 전파 X.
+    """
+    if not intent or not response_text:
+        return CurateResult(intent or "", sector, 0, 0)
+
+    bullets = extractBullets(response_text)
+    if not bullets:
+        return CurateResult(intent, sector, 0, 0)
+
+    outcome = gradeToOutcome(grade)
+    inserted = 0
+    skipped = 0
+    try:
+        from dartlab.ai.persistence import KnowledgeDB
+
+        db = KnowledgeDB.get()
+    except ImportError:
+        return CurateResult(intent, sector, 0, len(bullets))
+
+    for b in bullets:
+        try:
+            db.upsert_bullet(
+                intent=intent,
+                bullet=b,
+                sector=sector,
+                outcome=outcome,
+                source=source,
+            )
+            inserted += 1
+        except (OSError, RuntimeError):
+            skipped += 1
+
+    return CurateResult(intent, sector, inserted, skipped)
+
+
+# ── Generator 측: bullet retrieval ─────────────────────────
+
+
+def retrieveBullets(
+    intent: str,
+    *,
+    sector: str = "",
+    limit: int = 6,
+    min_quality: float = 0.4,
+) -> list[str]:
+    """intent별 playbook bullet retrieval.
+
+    ContextBuilder 의 selector 가 호출. KnowledgeDB 없거나 비어있으면 빈 리스트.
+    """
+    if not intent:
+        return []
+    try:
+        from dartlab.ai.persistence import KnowledgeDB
+
+        db = KnowledgeDB.get()
+    except ImportError:
+        return []
+    try:
+        rows = db.get_bullets(
+            intent=intent,
+            sector=sector,
+            limit=limit,
+            min_quality=min_quality,
+        )
+    except (OSError, RuntimeError):
+        return []
+    return [r[0] for r in rows]

src/dartlab/ai/context/selectors/__init__.py

@@ -0,0 +1,32 @@
+"""ContextBuilder selectors — Intent별 컨텍스트 생산자.
+
+각 selector는 (question, company, intent) → list[ContextPart] 형태.
+순수 함수, 부수효과 없음. 실패 시 빈 리스트 반환 (에러 전파 금지).
+
+Phase 1 (현재):
+    legacy.py — 기존 ai/runtime/core.py의 pre-grounding 5개 헬퍼 래핑
+                (손실 없는 이주, A/B 비교 가능)
+
+Phase 1.5 (다음):
+    act1~6.py, compare.py, concept.py — analysis calc 결과를 intent별로 선택 주입
+"""
+
+from __future__ import annotations
+
+from dartlab.ai.context.selectors.legacy import (
+    selectCompanySearch,
+    selectDisclosureBrief,
+    selectExternalSearch,
+    selectInsightHints,
+    selectMemoryHints,
+)
+from dartlab.ai.context.selectors.playbook import selectPlaybookBullets
+
+__all__ = [
+    "selectCompanySearch",
+    "selectDisclosureBrief",
+    "selectExternalSearch",
+    "selectInsightHints",
+    "selectMemoryHints",
+    "selectPlaybookBullets",
+]