diff --git a/.streamlit/config.toml b/.streamlit/config.toml deleted file mode 100644 index 10097aabe303621b02f86a514561cf4390aefcbc..0000000000000000000000000000000000000000 --- a/.streamlit/config.toml +++ /dev/null @@ -1,7 +0,0 @@ -[theme] -base = "dark" -primaryColor = "#ea4647" -backgroundColor = "#050811" -secondaryBackgroundColor = "#0f1219" -textColor = "#f1f5f9" -font = "sans serif" diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000000000000000000000000000000000000..3de25e1a2215a843a81c9dbc7f5d76d3c7119d2a --- /dev/null +++ b/Dockerfile @@ -0,0 +1,18 @@ +FROM python:3.12-slim + +WORKDIR /app + +RUN apt-get update && apt-get install -y --no-install-recommends \ + build-essential \ + && rm -rf /var/lib/apt/lists/* + +COPY pyproject.toml README.md ./ +COPY src/ src/ + +RUN pip install --no-cache-dir -e ".[ai]" + +ENV SPACE_ID=1 + +EXPOSE 7860 + +CMD ["python", "-m", "dartlab.server"] diff --git a/README.md b/README.md index 76f21d3b1d0758c1d4acb997d19474778ac8a064..0eb3e1e14e4a775e1ad6788c97410ce3d83411a4 100644 --- a/README.md +++ b/README.md @@ -3,9 +3,7 @@ title: DartLab emoji: ๐Ÿ“Š colorFrom: red colorTo: yellow -sdk: streamlit -sdk_version: "1.45.1" -app_file: app.py +sdk: docker pinned: true license: mit short_description: DART + EDGAR disclosure analysis diff --git a/README_PROJECT.md b/README_PROJECT.md new file mode 100644 index 0000000000000000000000000000000000000000..8ba73cf502cfd40de6decb84e4c4705d958175f9 --- /dev/null +++ b/README_PROJECT.md @@ -0,0 +1,1108 @@ +
+ +
+ +DartLab + +

DartLab

+ +

One stock code. The whole story.

+

DART + EDGAR filings, structured and comparable โ€” in one line of Python.

+ +

+PyPI +Python +License +CI +Docs +Blog +

+ +

+Docs ยท Blog ยท Live Demo ยท Marimo Notebooks ยท Open in Colab ยท ํ•œ๊ตญ์–ด ยท Sponsor +

+ +

+HuggingFace Data +

+ +
+ +> **Note:** DartLab is under active development. APIs may change between versions, and documentation may lag behind the latest code. + +## Install + +Requires **Python 3.12+**. + +```bash +# Core โ€” financial statements, sections, Company +uv add dartlab + +# or with pip +pip install dartlab +``` + +### Optional Extras + +Install only what you need: + +```bash +uv add "dartlab[ai]" # web UI, server, streaming (FastAPI + uvicorn) +uv add "dartlab[llm]" # LLM analysis (OpenAI) +uv add "dartlab[charts]" # Plotly charts, network graphs (plotly + networkx + scipy) +uv add "dartlab[mcp]" # MCP server for Claude Desktop / Code / Cursor +uv add "dartlab[channel]" # web UI + cloudflared tunnel sharing +uv add "dartlab[channel-ngrok]" # web UI + ngrok tunnel sharing +uv add "dartlab[channel-full]" # all channels + Telegram / Slack / Discord bots +uv add "dartlab[all]" # everything above (except channel bots) +``` + +**Common combinations:** + +```bash +# financial analysis + AI chat +uv add "dartlab[ai,llm]" + +# full analysis suite โ€” charts, AI, LLM +uv add "dartlab[ai,llm,charts]" + +# share analysis with team via tunnel +uv add "dartlab[channel]" +``` + +### From Source + +```bash +git clone https://github.com/eddmpython/dartlab.git +cd dartlab && uv pip install -e ".[all]" + +# or with pip +pip install -e ".[all]" +``` + +PyPI releases are published only when the core is stable. If you want the latest features (including experimental ones like audit, forecast, valuation), clone the repo directly โ€” but expect occasional breaking changes. + +### Desktop App (Alpha) + +Skip all installation steps โ€” download the standalone Windows launcher: + +- **[Download DartLab.exe](https://github.com/eddmpython/dartlab-desktop/releases/latest/download/DartLab.exe)** from [dartlab-desktop](https://github.com/eddmpython/dartlab-desktop) +- Also available from the [DartLab landing page](https://eddmpython.github.io/dartlab/) + +One-click launch โ€” no Python, no terminal, no package manager required. The desktop app bundles the web UI with a built-in Python runtime. + +> **Alpha** โ€” functional but incomplete. The desktop app is a Windows-only `.exe` launcher. macOS/Linux are not yet supported. + +--- + +**No data setup required.** When you create a `Company`, dartlab automatically downloads the required data from [HuggingFace](https://huggingface.co/datasets/eddmpython/dartlab-data) (DART) or SEC API (EDGAR). The second run loads instantly from local cache. + +## Quick Start + +Pick any company. Get the whole picture. + +```python +import dartlab + +# Samsung Electronics โ€” from raw filings to structured data +c = dartlab.Company("005930") +c.sections # every topic, every period, side by side +c.show("businessOverview") # what this company actually does +c.diff("businessOverview") # what changed since last year +c.BS # standardized balance sheet +c.ratios # 47 financial ratios, already calculated + +# Apple โ€” same interface, different country +us = dartlab.Company("AAPL") +us.show("business") +us.ratios + +# No code needed โ€” ask in natural language +dartlab.ask("Analyze Samsung Electronics financial health") +``` + +## What DartLab Is + +A public company files hundreds of pages every quarter. Inside those pages is everything โ€” revenue trends, risk warnings, management strategy, competitive position. The complete truth about a company, written by the company itself. + +Nobody reads it. + +Not because they don't want to. Because the same information is named differently by every company, structured differently every year, and scattered across formats designed for regulators, not readers. The same "revenue" appears as `ifrs-full_Revenue`, `dart_Revenue`, `SalesRevenue`, or dozens of Korean variations. + +DartLab changes who can access this information. Two engines turn raw filings into one comparable map: + +### The Two Problems DartLab Solves + +**1. The same company says different things differently every year.** + +Sections horizontalization normalizes every disclosure section into a **topic ร— period** grid. Different titles across years and industries all resolve to the same canonical topic: + +``` + 2025Q4 2024Q4 2024Q3 2023Q4 โ€ฆ +companyOverview โœ“ โœ“ โœ“ โœ“ +businessOverview โœ“ โœ“ โœ“ โœ“ +productService โœ“ โœ“ โœ“ โœ“ +salesOrder โœ“ โœ“ โ€” โœ“ +employee โœ“ โœ“ โœ“ โœ“ +dividend โœ“ โœ“ โœ“ โœ“ +audit โœ“ โœ“ โœ“ โœ“ +โ€ฆ (98 canonical topics) +``` + +``` +Before (raw section titles): After (canonical topic): +Samsung "II. ์‚ฌ์—…์˜ ๋‚ด์šฉ" โ†’ businessOverview +Hyundai "II. ์‚ฌ์—…์˜ ๋‚ด์šฉ [์ž๋™์ฐจ๋ถ€๋ฌธ]" โ†’ businessOverview +Kakao "2. ์‚ฌ์—…์˜ ๋‚ด์šฉ" โ†’ businessOverview +``` + +The mapping pipeline: **text normalization** โ†’ **545 hardcoded title mappings** โ†’ **73 regex patterns** โ†’ canonical topic. ~95%+ mapping rate across all listed companies. Each cell keeps the full text with heading/body separation, tables, and original evidence. Comparing "what did the company say about risk last year vs. this year" becomes a single `diff()` call. + +**2. Every company names the same number differently.** + +Account standardization normalizes every XBRL account through a 4-step pipeline: + +``` +Raw XBRL account_id + โ†’ Strip prefixes (ifrs-full_, dart_, ifrs_, ifrs-smes_) + โ†’ English ID synonyms (59 rules) + โ†’ Korean name synonyms (104 rules) + โ†’ Learned mapping table (34,249 entries) + โ†’ Result: revenue, operatingIncome, totalAssets, โ€ฆ +``` + +``` +Before (raw XBRL): After (standardized): +Company account_id account_nm โ†’ snakeId label +Samsung ifrs-full_Revenue ์ˆ˜์ต(๋งค์ถœ์•ก) โ†’ revenue ๋งค์ถœ์•ก +SK Hynix dart_Revenue ๋งค์ถœ์•ก โ†’ revenue ๋งค์ถœ์•ก +LG Energy Revenue ๋งค์ถœ โ†’ revenue ๋งค์ถœ์•ก +``` + +~97% mapping rate. Cross-company comparison requires zero manual work. Combined with `scanAccount` / `scanRatio`, you can compare a single metric across **2,700+ companies** in one call. + +### Principles โ€” Accessibility and Reliability + +These two principles govern every public API: + +**Accessibility** โ€” One stock code is all you need. `import dartlab` provides access to every feature. No internal DTOs, no extra imports, no data setup. `Company("005930")` auto-downloads from [HuggingFace](https://huggingface.co/datasets/eddmpython/dartlab-data). + +**Reliability** โ€” Numbers are raw originals from DART/EDGAR. Missing data returns `None`, never a guess. `trace(topic)` shows which source was chosen and why. Errors are never swallowed. + +### Company โ€” The Merged Map + +`Company` uses `sections` as the spine, then overlays stronger data sources: + +``` +Layer What it provides Priority +โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +docs Section text, tables, evidence Base spine +finance BS, IS, CF, ratios, time series Replaces numeric topics +report 28 structured APIs (DART only) Fills structured topics +โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +profile Merged view (default for users) Highest +``` + +```python +c.docs.sections # pure text source (sections spine) +c.finance.BS # authoritative financial statements +c.report.extract() # structured DART API data +c.profile.sections # merged view โ€” what users see by default +``` + +`c.sections` is the merged view. `c.trace("BS")` tells you which source was chosen and why. + +### Architecture โ€” Layered by Responsibility + +DartLab follows a strict layered architecture where each layer only depends on layers below it: + +``` +L0 core/ Protocols, finance utils, docs utils, registry +L1 providers/ Country-specific data (DART, EDGAR, EDINET) + gather/ External market data (Naver, Yahoo, FRED) + market/ Market-wide scanning (2,700+ companies) +L2 analysis/ Analytical engines (valuation, risk, insights, event study) +L3 ai/ LLM-powered analysis (9 providers) +``` + +Import direction is enforced by CI โ€” no reverse dependencies allowed. + +### Extensibility โ€” Zero Core Modification + +Adding a new country requires zero changes to core code: + +1. Create a provider package under `providers/` +2. Implement `canHandle(code) -> bool` and `priority() -> int` +3. Register via `entry_points` in `pyproject.toml` + +```python +dartlab.Company("005930") # โ†’ DART provider (priority 10) +dartlab.Company("AAPL") # โ†’ EDGAR provider (priority 20) +``` + +The facade iterates providers by priority โ€” first match wins. This follows the same pattern as OpenBB's provider system and scikit-learn's estimator registration. + +## Core Features + +### Show, Trace, Diff + +```python +c = dartlab.Company("005930") + +# show โ€” open any topic with source-aware priority +c.show("BS") # โ†’ finance DataFrame +c.show("overview") # โ†’ sections-based text + tables +c.show("dividend") # โ†’ report DataFrame (all quarters) +c.show("IS", period=["2024Q4", "2023Q4"]) # compare specific periods + +# trace โ€” why a topic came from docs, finance, or report +c.trace("BS") # โ†’ {"primarySource": "finance", ...} + +# diff โ€” text change detection (3 modes) +c.diff() # full summary +c.diff("businessOverview") # topic history +c.diff("businessOverview", "2024", "2025") # line-by-line diff +``` + +What the output looks like: + +``` +>>> c.show("businessOverview") +shape: (12, 5) +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ blockType โ”‚ nodeType โ”‚ 2024 โ”‚ 2023 โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ text โ”‚ heading โ”‚ 1. ์‚ฐ์—…์˜ ํŠน์„ฑ โ”‚ 1. ์‚ฐ์—…์˜ ํŠน์„ฑ โ”‚ +โ”‚ text โ”‚ body โ”‚ ๋ฐ˜๋„์ฒด ์‚ฐ์—…์€ ๊ธฐ์ˆ  ์ง‘์•ฝ์  โ€ฆ โ”‚ ๋ฐ˜๋„์ฒด ์‚ฐ์—…์€ ๊ธฐ์ˆ  ์ง‘์•ฝ์  โ€ฆ โ”‚ +โ”‚ table โ”‚ null โ”‚ DataFrame(5ร—3) โ”‚ DataFrame(5ร—3) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + +>>> c.diff("businessOverview", "2023", "2024") +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ status โ”‚ text โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ added โ”‚ AI ๋ฐ˜๋„์ฒด ์ˆ˜์š” ๊ธ‰์ฆ์— ๋”ฐ๋ฅธ HBM ๋งค์ถœ ํ™•๋Œ€ โ€ฆ โ”‚ +โ”‚ modified โ”‚ ๋งค์ถœ์•ก 258.9์กฐ์› โ†’ 300.9์กฐ์› โ”‚ +โ”‚ removed โ”‚ ๋ฐ˜๋„์ฒด ๋ถ€๋ฌธ ์ˆ˜์ต์„ฑ ์•…ํ™” ์šฐ๋ ค โ€ฆ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +### Finance + +```python +c.BS # balance sheet (account ร— period, newest first) +c.IS # income statement +c.CF # cash flow +c.ratios # ratio time series DataFrame (6 categories ร— period) +c.finance.ratioSeries # ratio time series across years +c.finance.timeseries # raw account time series +c.annual # annual time series +c.filings() # disclosure document list (Tier 1 Stable) +``` + +All accounts are normalized through the 4-step standardization pipeline โ€” Samsung's `revenue` and LG's `revenue` are the same `snakeId`. Ratios cover 6 categories: profitability, stability, growth, efficiency, cashflow, and valuation. + +### Market-wide Financial Screening + +Scan a single account or ratio across **all listed companies** in one call โ€” 2,700+ DART firms or 500+ EDGAR firms. Returns a wide Polars DataFrame (rows = companies, columns = periods, newest first). + +```python +import dartlab + +# scan a single account across all listed companies +dartlab.scanAccount("๋งค์ถœ์•ก") # revenue, quarterly standalone +dartlab.scanAccount("operating_profit", annual=True) # annual basis +dartlab.scanAccount("total_assets", market="edgar") # US EDGAR + +# scan a ratio across all listed companies +dartlab.scanRatio("roe") # quarterly ROE for all firms +dartlab.scanRatio("debtRatio", annual=True) # annual debt-to-equity + +# list available ratios (13 ratios: profitability, stability, growth, efficiency, cashflow) +dartlab.scanRatioList() +``` + +Accepts both Korean names (`๋งค์ถœ์•ก`) and English snakeIds (`sales`) โ€” same 4-step normalization as Company finance. Reads 2,700+ parquet files in parallel via ThreadPool, typically completes in ~3 seconds. + +> **Requires pre-downloaded data.** Market-wide functions (`scanAccount`, `screen`, `digest`, etc.) operate on local data โ€” individual `Company()` calls only download one firm at a time. Download all data first: +> ```python +> pip install dartlab[hf] +> dartlab.downloadAll("finance") # ~600 MB, 2,700+ firms +> dartlab.downloadAll("report") # ~320 MB (governance/workforce/capital/debt) +> dartlab.downloadAll("docs") # ~8 GB (digest/signal โ€” large) +> ``` + +## Review โ€” Structured Company Analysis + +> **Experimental** โ€” the review system is under active development. Templates, blocks, and output formats may change between versions. + +DartLab's review system assembles financial data into structured, readable reports. + +### Templates + +Pre-built block combinations that cover key analysis areas: + +```python +c = dartlab.Company("005930") + +c.review("์ˆ˜์ต๊ตฌ์กฐ") # revenue structure โ€” segments, growth, concentration +c.review("์ž๊ธˆ์กฐ๋‹ฌ") # capital structure โ€” debt, liquidity, interest burden +c.review() # all templates +``` + +### Block Assembly + +Every review is built from reusable blocks. Get the full block dictionary and assemble your own: + +```python +from dartlab.review import blocks, Review + +b = blocks(c) # dict of 16 pre-built blocks +list(b.keys()) # โ†’ ["profile", "segmentComposition", "growth", ...] + +# pick what you need +Review([ + b["segmentComposition"], + b["growth"], + c.select("IS", ["๋งค์ถœ์•ก"]), # mix with raw data +]) +``` + +### Reviewer โ€” AI Layer + +Add LLM-powered opinions on top of data blocks. Works with any provider: + +```python +c.reviewer() # all sections + AI opinion +c.reviewer("์ˆ˜์ต๊ตฌ์กฐ") # single section + AI +c.reviewer(guide="Evaluate from semiconductor cycle perspective") # custom guide +``` + +**Free AI providers** โ€” no paid API key required: + +| Provider | Setup | +|----------|-------| +| Gemini | `dartlab setup gemini` | +| Groq | `dartlab setup groq` | +| Cerebras | `dartlab setup cerebras` | +| Mistral | `dartlab setup mistral` | + +Or use any OpenAI-compatible endpoint: +```bash +dartlab setup custom --base-url http://localhost:11434/v1 # Ollama local +``` + +### Customization + +- **Templates**: Pre-defined block combinations (`์ˆ˜์ต๊ตฌ์กฐ`, `์ž๊ธˆ์กฐ๋‹ฌ`) +- **Free assembly**: Mix any blocks + raw DataFrames in `Review([...])` +- **Guide**: Pass `guide="..."` to `c.reviewer()` for domain-specific AI analysis +- **Layout**: `ReviewLayout(indentH1=2, gapAfterH1=1, ...)` for rendering control +- **Render formats**: `review.render("rich" | "html" | "markdown" | "json")` + +See [notebooks/marimo/sampleReview.py](notebooks/marimo/sampleReview.py) for interactive examples. + +## Additional Features + +> Features below are **beta** or **experimental** โ€” APIs may change. See [stability](docs/stability.md). + +### Insights (beta) + +> **Beta** โ€” API may change after a warning. See [stability](docs/stability.md). + +```python +c.insights # 10-area analysis +c.insights.grades() # โ†’ {"performance": "A", "profitability": "B", โ€ฆ} +c.insights.performance.grade # โ†’ "A" +c.insights.performance.details # โ†’ ["Revenue growth +8.3%", โ€ฆ] +c.insights.anomalies # โ†’ outliers and red flags + +# distress scorecard โ€” 6-model bankruptcy/fraud prediction +c.insights.distress # Altman Z-Score, Beneish M-Score, Ohlson O-Score, + # Merton Distance-to-Default, Piotroski F-Score, Sloan Ratio +``` + +### Valuation, Forecast & Simulation + +```python +dartlab.valuation("005930") # DCF + DDM + relative valuation +dartlab.forecast("005930") # revenue forecast (4-source ensemble) +dartlab.simulation("005930") # scenario simulation (macro presets) + +# also available as Company methods +c.valuation() +c.forecast(horizon=3) +c.simulation(scenarios=["adverse", "rate_hike"]) +``` + +Auto-detects currency โ€” KRW for DART companies, USD for EDGAR. Works with both `dartlab.valuation("AAPL")` and `dartlab.valuation("005930")`. + +### Audit (beta) + +> **Beta** โ€” API may change after a warning. See [stability](docs/stability.md). + +```python +dartlab.audit("005930") # 11 red flag detectors + +# Benford's Law (digit distribution), auditor change (PCAOB AS 3101), +# going concern (ISA 570), internal control (SOX 302/404), +# revenue quality (Dechow & Dichev), Merton default probability, ... +``` + +### Market Intelligence (beta) + +> **Beta** โ€” API may change after a warning. See [stability](docs/stability.md). + +```python +dartlab.digest() # market-wide disclosure change digest +dartlab.digest(sector="๋ฐ˜๋„์ฒด") # sector filter +dartlab.groupHealth() # group health: network ร— financial ratios +``` + +### Modules + +DartLab exposes 100+ modules across 6 categories: + +```bash +dartlab modules # list all modules +dartlab modules --category finance # filter by category +dartlab modules --search dividend # search by keyword +``` + +```python +c.topics # list all available topics for this company +``` + +Categories: `finance` (statements, ratios), `report` (dividend, governance, audit), `notes` (K-IFRS annotations), `disclosure` (narrative text), `analysis` (insights, rankings), `raw` (original parquets). + +### Charts & Visualization (beta) + +> **Beta** โ€” API may change after a warning. See [stability](docs/stability.md). + +```python +c = dartlab.Company("005930") + +# one-liner Plotly charts +dartlab.chart.revenue(c).show() # revenue + operating margin combo +dartlab.chart.cashflow(c).show() # operating/investing/financing CF +dartlab.chart.dividend(c).show() # DPS + yield + payout ratio +dartlab.chart.profitability(c).show() # ROE, operating margin, net margin + +# auto-detect all available charts +specs = dartlab.chart.auto_chart(c) +dartlab.chart.chart_from_spec(specs[0]).show() + +# generic charts from any DataFrame +dartlab.chart.line(c.dividend, y=["dps"]) +dartlab.chart.bar(df, x="year", y=["revenue", "operating_income"], stacked=True) +``` + +Data tools: + +```python +dartlab.table.yoy_change(c.dividend, value_cols=["dps"]) # add YoY% columns +dartlab.table.format_korean(c.BS, unit="๋ฐฑ๋งŒ์›") # 1.2์กฐ์›, 350์–ต์› +dartlab.table.summary_stats(c.dividend, value_cols=["dps"]) # mean/CAGR/trend +dartlab.text.extract_keywords(narrative) # frequency-based keywords +dartlab.text.sentiment_indicators(narrative) # positive/negative/risk +``` + +Install chart dependencies: `uv add "dartlab[charts]"` + +### Network โ€” Affiliate Map (beta) + +> **Beta** โ€” API may change after a warning. See [stability](docs/stability.md). + +```python +c = dartlab.Company("005930") + +# interactive vis.js graph in browser +c.network().show() # ego view (1 hop) +c.network(hops=2).show() # 2-hop neighborhood + +# DataFrame views +c.network("members") # group affiliates +c.network("edges") # investment/shareholder connections +c.network("cycles") # circular ownership paths + +# full market network +dartlab.network().show() +``` + +### Market Scan (beta) + +> **Beta** โ€” API may change after a warning. See [stability](docs/stability.md). + +```python +c = dartlab.Company("005930") + +# one company โ†’ market-wide +c.governance() # single company +c.governance("all") # full market DataFrame +dartlab.governance() # module-level scan +dartlab.workforce() +dartlab.capital() +dartlab.debt() + +# screening & benchmarking +dartlab.screen() # multi-factor screening +dartlab.benchmark() # peer comparison +dartlab.signal() # change detection signals +``` + +### Market Data Collection (beta) + +> **Beta** โ€” API may change after a warning. See [stability](docs/stability.md). + +The Gather engine collects external market data as **Polars DataFrames** โ€” timeseries by default. Every request goes through automatic fallback chains, circuit breaker isolation, and TTL caching. All methods are synchronous โ€” async parallel execution is handled internally. + +```python +import dartlab + +# OHLCV timeseries โ€” adjusted prices, 6000+ trading days in a single request +dartlab.price("005930") # KR: 1-year default, Polars DataFrame +dartlab.price("005930", start="2015-01-01") # custom range +dartlab.price("AAPL", market="US") # US via Yahoo Finance chart API +dartlab.price("005930", snapshot=True) # opt-in: current price snapshot + +# supply/demand flow timeseries (KR only) +dartlab.flow("005930") # DataFrame (date, foreignNet, institutionNet, ...) + +# macro indicators โ€” full wide DataFrame +dartlab.macro() # KR 12 indicators (CPI, rates, FX, production, ...) +dartlab.macro("US") # US 25 indicators (GDP, CPI, Fed Funds, S&P500, ...) +dartlab.macro("CPI") # single indicator (auto-detects KR) +dartlab.macro("FEDFUNDS") # single indicator (auto-detects US) + +# consensus, news +dartlab.consensus("005930") # target price & analyst opinion +dartlab.news("์‚ผ์„ฑ์ „์ž") # Google News RSS โ†’ DataFrame +``` + +**How data is collected โ€” don't worry, it's safe:** + +| Source | Data | Method | +|--------|------|--------| +| Naver Chart API | KR OHLCV (adjusted prices) | `fchart.stock.naver.com` โ€” 1 request per stock, max 6000 days | +| Yahoo Finance v8 | US/Global OHLCV | `query2.finance.yahoo.com/v8/finance/chart` โ€” public chart API | +| ECOS (Bank of Korea) | KR macro indicators | Official API with user's own key | +| FRED (St. Louis Fed) | US macro indicators | Official API with user's own key | +| Naver Mobile API | Consensus, flow, sector PER | `m.stock.naver.com/api` โ€” JSON endpoints | +| FMP | Fallback for US history | Financial Modeling Prep API (optional) | + +**Safety infrastructure:** + +- **Rate limiting** โ€” per-domain RPM caps (Naver 30, ECOS 30, FRED 120) with async queue +- **Circuit breaker** โ€” 3 consecutive failures โ†’ source disabled for 60s, half-open retry +- **Fallback chains** โ€” KR: naver โ†’ yahoo_direct โ†’ yahoo / US: yahoo_direct โ†’ fmp โ†’ yahoo +- **Stale-while-revalidate** โ€” returns cached data on failure, warns via `log.warning` +- **User-Agent rotation** โ€” randomized per request to avoid fingerprinting +- **No silent failures** โ€” all API errors logged at warning level, never swallowed +- **No scraping** โ€” all sources are public APIs or official data endpoints + +### Cross-Border Analysis (beta) + +> **Beta** โ€” API may change after a warning. See [stability](docs/stability.md). + +```python +c = dartlab.Company("005930") + +# keyword frequency across disclosure periods +c.keywordTrend(keyword="AI") # topic ร— period ร— keyword count +c.keywordTrend() # all 54 built-in keywords + +# news headlines +c.news() # recent 30 days +dartlab.news("AAPL", market="US") # US company news + +# global peer mapping (WICS โ†’ GICS sector) +dartlab.crossBorderPeers("005930") # โ†’ ["AAPL", "MSFT", "NVDA", "TSM", "AVGO"] + +# currency conversion (FRED-based) +from dartlab.engines.common.finance import getExchangeRate, convertValue +getExchangeRate("KRW") # KRW/USD rate +convertValue(1_000_000, "KRW", "USD") # โ†’ ~730.0 + +# audit opinion normalization (KR/EN/JP โ†’ canonical code) +from dartlab.engines.common.audit import normalizeAuditOpinion +normalizeAuditOpinion("์ ์ •") # โ†’ "unqualified" +normalizeAuditOpinion("Qualified") # โ†’ "qualified" +``` + +Disclosure gap detection runs automatically inside `c.insights` โ€” flags mismatches between text changes and financial health (e.g. risk text surges while financials are stable). + +### Export (experimental) + +> **Experimental** โ€” Breaking changes possible. Not for production. + +```bash +dartlab excel "005930" -o samsung.xlsx +``` + +Install: `uv add "dartlab[ai]"` (Excel export is included in the AI extras). + +### Plugins + +```python +dartlab.plugins() # list loaded plugins +dartlab.reload_plugins() # rescan after installing a plugin +``` + +Plugins can extend DartLab with custom data sources, tools, or analysis engines. See `dartlab plugin create --help` for scaffolding. + +## EDGAR (US) + +Same `Company` interface, same account standardization pipeline, different data source. EDGAR data is auto-fetched from the SEC API โ€” no pre-download needed: + +```python +us = dartlab.Company("AAPL") + +us.sections # 10-K/10-Q sections with heading/body +us.show("business") # business description +us.show("10-K::item1ARiskFactors") # risk factors +us.BS # SEC XBRL balance sheet +us.ratios # same 47 ratios +us.diff("10-K::item7Mdna") # MD&A text changes +us.insights # 10-area grades (A~F) + +# analyst functions โ€” auto-detect USD +dartlab.valuation("AAPL") # DCF + DDM + relative (USD) +dartlab.forecast("AAPL") # revenue forecast (USD) +dartlab.simulation("AAPL") # scenario simulation (US macro presets) +``` + +The interface is identical โ€” same methods, same structure: + +```python +# Korea (DART) # US (EDGAR) +c = dartlab.Company("005930") c = dartlab.Company("AAPL") +c.sections c.sections +c.show("businessOverview") c.show("business") +c.BS c.BS +c.ratios c.ratios +c.diff("businessOverview") c.diff("10-K::item7Mdna") +c.insights.grades() c.insights.grades() +``` + +### DART vs EDGAR Namespaces + +| | DART | EDGAR | +|---------------|:--------------:|:--------------:| +| `docs` | โœ“ | โœ“ | +| `finance` | โœ“ | โœ“ | +| `report` | โœ“ (28 API types) | โœ— (not applicable) | +| `profile` | โœ“ | โœ“ | + +DART has a `report` namespace with 28 structured disclosure APIs (dividend, governance, executive compensation, etc.). This does not exist in EDGAR โ€” SEC filings are structured differently. + +**EDGAR topic naming**: Topics use `{formType}::{itemId}` format. Short aliases also work: + +```python +us.show("10-K::item1Business") # full form +us.show("business") # short alias +us.show("risk") # โ†’ 10-K::item1ARiskFactors +us.show("mdna") # โ†’ 10-K::item7Mdna +``` + +## AI Analysis + +> **Experimental** โ€” the AI analysis layer and `analysis/` engines are under active development. APIs, output formats, and available tools may change between versions. + +> **Tip:** New to financial analysis or prefer natural language? Use `dartlab.ask()` โ€” the AI assistant handles everything from data download to analysis. No coding knowledge required. + +DartLab includes a built-in AI analysis layer that feeds structured company data to LLMs. **No code required** โ€” you can ask questions in plain language and DartLab handles everything: data selection, context assembly, and streaming the answer. + +```bash +# terminal one-liner โ€” no Python needed +dartlab ask "์‚ผ์„ฑ์ „์ž ์žฌ๋ฌด๊ฑด์ „์„ฑ ๋ถ„์„ํ•ด์ค˜" +``` + +DartLab structures the data, selects relevant context (financials, insights, sector benchmarks), and lets the LLM explain: + +``` +$ dartlab ask "์‚ผ์„ฑ์ „์ž ์žฌ๋ฌด๊ฑด์ „์„ฑ ๋ถ„์„ํ•ด์ค˜" + +์‚ผ์„ฑ์ „์ž์˜ ์žฌ๋ฌด๊ฑด์ „์„ฑ์€ A๋“ฑ๊ธ‰์ž…๋‹ˆ๋‹ค. + +โ–ธ ๋ถ€์ฑ„๋น„์œจ 31.8% โ€” ์—…์ข… ํ‰๊ท (45.2%) ๋Œ€๋น„ ์–‘ํ˜ธ +โ–ธ ์œ ๋™๋น„์œจ 258.6% โ€” 200% ์•ˆ์ „ ๊ธฐ์ค€ ์ƒํšŒ +โ–ธ ์ด์ž๋ณด์ƒ๋ฐฐ์ˆ˜ 22.1๋ฐฐ โ€” ์ด์ž ๋ถ€๋‹ด ๋งค์šฐ ๋‚ฎ์Œ +โ–ธ ROE ํšŒ๋ณต์„ธ: 1.6% โ†’ 10.2% (4๋ถ„๊ธฐ ์—ฐ์† ๊ฐœ์„ ) + +[๋ฐ์ดํ„ฐ ์ถœ์ฒ˜: 2024Q4 ์‚ฌ์—…๋ณด๊ณ ์„œ, dartlab insights ์—”์ง„] +``` + +For real-time market-wide disclosure questions (e.g. "์ตœ๊ทผ 7์ผ ์ˆ˜์ฃผ๊ณต์‹œ ์•Œ๋ ค์ค˜"), the AI uses your `OpenDART API key` to search recent filings directly. Store the key in project `.env` or via UI Settings. + +The 2-tier architecture means basic analysis works with any provider, while tool-calling providers (OpenAI, Claude) can go deeper by requesting additional data mid-conversation. + +### Python API + +```python +import dartlab + +# streams to stdout, returns full text +answer = dartlab.ask("์‚ผ์„ฑ์ „์ž ์žฌ๋ฌด๊ฑด์ „์„ฑ ๋ถ„์„ํ•ด์ค˜") + +# provider + model override +answer = dartlab.ask("์‚ผ์„ฑ์ „์ž ๋ถ„์„", provider="openai", model="gpt-4o") + +# data filtering +answer = dartlab.ask("์‚ผ์„ฑ์ „์ž ํ•ต์‹ฌ ํฌ์ธํŠธ", include=["BS", "IS"]) + +# analysis pattern (framework-guided) +answer = dartlab.ask("์‚ผ์„ฑ์ „์ž ๋ถ„์„", pattern="financial") + +# agent mode โ€” LLM selects tools for deeper analysis +answer = dartlab.chat("005930", "๋ฐฐ๋‹น ์ถ”์„ธ๋ฅผ ๋ถ„์„ํ•˜๊ณ  ์ด์ƒ ์ง•ํ›„๋ฅผ ์ฐพ์•„์ค˜") +``` + +### CLI + +```bash +# provider setup โ€” free providers first +dartlab setup # list all providers +dartlab setup gemini # Google Gemini (free) +dartlab setup groq # Groq (free) + +# status +dartlab status # all providers (table view) +dartlab status --cost # cumulative token/cost stats + +# ask questions (streaming by default) +dartlab ask "์‚ผ์„ฑ์ „์ž ์žฌ๋ฌด๊ฑด์ „์„ฑ ๋ถ„์„ํ•ด์ค˜" +dartlab ask "AAPL risk analysis" -p ollama +dartlab ask --continue "๋ฐฐ๋‹น ์ถ”์„ธ๋Š”?" + +# auto-generate report +dartlab report "์‚ผ์„ฑ์ „์ž" -o report.md + +# web UI +dartlab # open browser UI +dartlab --help # show all commands +``` + +
+All CLI commands (16) + +| Category | Command | Description | +|----------|---------|-------------| +| Data | `show` | Open any topic by name | +| Data | `search` | Find companies by name or code | +| Data | `statement` | BS / IS / CF / SCE output | +| Data | `sections` | Raw docs sections | +| Data | `profile` | Company index and facts | +| Data | `modules` | List all available modules | +| AI | `ask` | Natural language question | +| AI | `report` | Auto-generate analysis report | +| Export | `excel` | Export to Excel (experimental) | +| Collect | `collect` | Download / refresh / batch collect | +| Collect | `collect --check` | Check freshness (new filings) | +| Collect | `collect --incremental` | Incremental collect (missing only) | +| Server | `ai` | Launch web UI (localhost:8400) | +| Server | `share` | Tunnel sharing (ngrok / cloudflared) | +| Server | `status` | Provider connection status | +| Server | `setup` | Provider setup wizard | +| MCP | `mcp` | Start MCP stdio server | +| Plugin | `plugin` | Create / list plugins | + +
+ +### Providers + +**Free API key providers** โ€” sign up, paste the key, start analyzing: + +| Provider | Free Tier | Model | Setup | +|----------|-----------|-------|-------| +| `gemini` | Gemini 2.5 Pro/Flash free | Gemini 2.5 | `dartlab setup gemini` | +| `groq` | 6Kโ€“30K TPM free | LLaMA 3.3 70B | `dartlab setup groq` | +| `cerebras` | 1M tokens/day permanent | LLaMA 3.3 70B | `dartlab setup cerebras` | +| `mistral` | 1B tokens/month free | Mistral Small | `dartlab setup mistral` | + +**Other providers:** + +| Provider | Auth | Cost | Tool Calling | +|----------|------|------|:---:| +| `oauth-codex` | ChatGPT subscription (Plus/Team/Enterprise) | Included in subscription | Yes | +| `openai` | API key (`OPENAI_API_KEY`) | Pay-per-token | Yes | +| `ollama` | Local install, no account needed | Free | Depends on model | +| `codex` | Codex CLI installed locally | Free (uses your Codex session) | Yes | +| `custom` | Any OpenAI-compatible endpoint | Varies | Varies | + +**Auto-fallback:** Set multiple free API keys and DartLab automatically switches to the next provider when one hits its rate limit. Use `provider="free"` to enable the fallback chain: + +```python +dartlab.ask("์‚ผ์„ฑ์ „์ž ๋ถ„์„", provider="free") +``` + +**Why no Claude provider?** Anthropic does not offer OAuth-based access. Without OAuth, there is no way to let users authenticate with their existing subscription โ€” we would have to ask users to paste API keys, which goes against DartLab's frictionless design. If Anthropic adds OAuth support in the future, we will add a Claude provider. For now, Claude works through **MCP** (see below) โ€” Claude Desktop, Claude Code, and Cursor can call DartLab's 60 tools directly. + +**`oauth-codex`** is the recommended provider โ€” if you have a ChatGPT subscription, it works out of the box with no API keys. Run `dartlab setup oauth-codex` to authenticate. + +**Web UI (`dartlab`)** launches a browser-based chat interface for interactive analysis. This feature is currently **experimental** โ€” we are evaluating the right scope and UX for visualization and collaborative features. + +Install AI dependencies: `uv add "dartlab[ai]"` + +### Project Settings (`.dartlab.yml`) + +```yaml +company: 005930 # default company +provider: openai # default LLM provider +model: gpt-4o # default model +verbose: false +``` + +## MCP โ€” AI Assistant Integration + +DartLab includes a built-in [MCP](https://modelcontextprotocol.io/) server that exposes 60 tools (16 global + 44 per-company) to Claude Desktop, Claude Code, Cursor, and any MCP-compatible client. + +```bash +uv add "dartlab[mcp]" +``` + +### Claude Desktop + +Add to `claude_desktop_config.json`: + +```json +{ + "mcpServers": { + "dartlab": { + "command": "uv", + "args": ["run", "dartlab", "mcp"] + } + } +} +``` + +### Claude Code + +```bash +claude mcp add dartlab -- uv run dartlab mcp +``` + +Or add to `~/.claude/settings.json`: + +```json +{ + "mcpServers": { + "dartlab": { + "command": "uv", + "args": ["run", "dartlab", "mcp"] + } + } +} +``` + +### Cursor + +Add to `.cursor/mcp.json` with the same config format as Claude Desktop. + +### What's Available + +Once connected, your AI assistant can: + +- **Search** โ€” find companies by name or code (`search_company`) +- **Show** โ€” read any disclosure topic (`show_topic`, `list_topics`, `diff_topic`) +- **Finance** โ€” balance sheet, income statement, cash flow, ratios (`get_financial_statements`, `get_ratios`) +- **Analysis** โ€” insights, sector ranking, valuation (`get_insight`, `get_ranking`) +- **EDGAR** โ€” same tools work for US companies (`stock_code: "AAPL"`) + +Auto-generate config for your platform: + +```bash +dartlab mcp --config claude-desktop +dartlab mcp --config claude-code +dartlab mcp --config cursor +``` + +## OpenAPI โ€” Raw Public APIs + +Use source-native wrappers when you want raw disclosure APIs directly. + +### OpenDart (Korea) + +> **Note:** `Company` does **not** require an API key โ€” it uses pre-built datasets. +> `OpenDart` uses the raw DART API and requires a key from [opendart.fss.or.kr](https://opendart.fss.or.kr) (free). +> Recent filing-list AI questions across the whole market also use this key. In the UI, open Settings and manage `OpenDART API key` there. + +```python +from dartlab import OpenDart + +d = OpenDart() +d.search("์นด์นด์˜ค", listed=True) +d.filings("์‚ผ์„ฑ์ „์ž", "2024") +d.finstate("์‚ผ์„ฑ์ „์ž", 2024) +d.report("์‚ผ์„ฑ์ „์ž", "๋ฐฐ๋‹น", 2024) +``` + +### OpenEdgar (US) + +> **No API key required.** SEC EDGAR is a public API โ€” no registration needed. + +```python +from dartlab import OpenEdgar + +e = OpenEdgar() +e.search("Apple") +e.filings("AAPL", forms=["10-K", "10-Q"]) +e.companyFactsJson("AAPL") +``` + +## Data + +**No manual setup required.** When you create a `Company`, dartlab automatically downloads the required data. + +| Dataset | Coverage | Size | Source | +|---------|----------|------|--------| +| DART docs | 2,500+ companies | ~8 GB | [HuggingFace](https://huggingface.co/datasets/eddmpython/dartlab-data/tree/main/dart/docs) | +| DART finance | 2,700+ companies | ~600 MB | [HuggingFace](https://huggingface.co/datasets/eddmpython/dartlab-data/tree/main/dart/finance) | +| DART report | 2,700+ companies | ~320 MB | [HuggingFace](https://huggingface.co/datasets/eddmpython/dartlab-data/tree/main/dart/report) | +| EDGAR | On-demand | โ€” | SEC API (auto-fetched) | + +### 3-Step Data Pipeline + +``` +dartlab.Company("005930") + โ”‚ + โ”œโ”€ 1. Local cache โ”€โ”€โ”€โ”€ already have it? done (instant) + โ”‚ + โ”œโ”€ 2. HuggingFace โ”€โ”€โ”€โ”€ auto-download (~seconds, no key needed) + โ”‚ + โ””โ”€ 3. DART API โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ collect with your API key (needs key) +``` + +If a company is not in HuggingFace, dartlab collects data directly from DART โ€” this requires an API key: + +```bash +dartlab setup dart-key +``` + +### Freshness โ€” Automatic Update Detection + +DartLab uses a 3-layer freshness system to keep your local data current: + +| Layer | Method | Cost | +|-------|--------|------| +| L1 | HTTP HEAD โ†’ ETag comparison with HuggingFace | ~0.5s, few hundred bytes | +| L2 | Local file age (90-day TTL fallback) | instant (local) | +| L3 | DART API โ†’ `rcept_no` diff (requires API key) | 1 API call, ~1s | + +When you open a `Company`, dartlab checks if newer data exists. If a new disclosure was filed: + +```python +c = dartlab.Company("005930") +# [dartlab] โš  005930 โ€” ์ƒˆ ๊ณต์‹œ 2๊ฑด ๋ฐœ๊ฒฌ (์‚ฌ์—…๋ณด๊ณ ์„œ (2024.12)) +# โ€ข ์ฆ๋ถ„ ์ˆ˜์ง‘: dartlab collect --incremental 005930 +# โ€ข ๋˜๋Š” Python: c.update() + +c.update() # incremental collect โ€” only missing filings +``` + +```bash +# CLI freshness check +dartlab collect --check 005930 # single company +dartlab collect --check # scan all local companies (7 days) + +# incremental collect โ€” only missing filings +dartlab collect --incremental 005930 # single company +dartlab collect --incremental # all local companies with new filings +``` + +### Batch Collection (DART API) + +```bash +dartlab collect --batch # all listed, missing only +dartlab collect --batch -c finance 005930 # specific category + company +dartlab collect --batch --mode all # re-collect everything +``` + +## Try It Now + +### Live Demo (No Install) + +Try DartLab instantly โ€” no Python, no terminal, no setup: + +**[โ†’ Open Live Demo](https://huggingface.co/spaces/eddmpython/dartlab)** โ€” enter a stock code, see financials immediately + +Or open a [Colab notebook](https://colab.research.google.com/github/eddmpython/dartlab/blob/master/notebooks/showcase/01_quickstart.ipynb) in your browser. + +### Marimo Notebooks + +> Data is automatically downloaded on first use. No setup required unless collecting new companies directly from DART. + +```bash +uv add dartlab marimo +marimo edit notebooks/marimo/dartCompany.py # Korean company (DART) +marimo edit notebooks/marimo/edgarCompany.py # US company (EDGAR) +marimo edit notebooks/marimo/aiAnalysis.py # AI analysis examples +``` + +### Colab Notebooks + +**Showcase** (English โ€” global audience): + +| Notebook | Topic | +|---|---| +| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/eddmpython/dartlab/blob/master/notebooks/showcase/01_quickstart.ipynb) | **Quick Start** โ€” analyze any company in 3 lines | +| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/eddmpython/dartlab/blob/master/notebooks/showcase/02_financial_analysis.ipynb) | **Financial Analysis** โ€” statements, time series, ratios | +| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/eddmpython/dartlab/blob/master/notebooks/showcase/03_kr_us_compare.ipynb) | **Korea vs US** โ€” Samsung vs Apple side-by-side | +| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/eddmpython/dartlab/blob/master/notebooks/showcase/04_risk_diff.ipynb) | **Risk Diff** โ€” track disclosure changes (Bloomberg can't) | +| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/eddmpython/dartlab/blob/master/notebooks/showcase/05_sector_screening.ipynb) | **Sector Screening** โ€” 8 presets, sector benchmarks | +| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/eddmpython/dartlab/blob/master/notebooks/showcase/06_insight_anomaly.ipynb) | **Insight & Anomaly** โ€” 10-area grading, 6 anomaly rules | +| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/eddmpython/dartlab/blob/master/notebooks/showcase/07_network_governance.ipynb) | **Network & Governance** โ€” corporate relationship graph | +| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/eddmpython/dartlab/blob/master/notebooks/showcase/08_signal_trend.ipynb) | **Signal Trends** โ€” 48-keyword disclosure monitoring | +| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/eddmpython/dartlab/blob/master/notebooks/showcase/09_ai_analysis.ipynb) | **AI Analysis** โ€” `dartlab.ask()` with 9 LLM providers | +| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/eddmpython/dartlab/blob/master/notebooks/showcase/10_disclosure_deep_dive.ipynb) | **Disclosure Deep Dive** โ€” sections architecture | + +
+ํ•œ๊ตญ์–ด Tutorials + +| Notebook | Topic | +|---|---| +| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/eddmpython/dartlab/blob/master/notebooks/getting-started/quickstart.ipynb) | **๋น ๋ฅธ ์‹œ์ž‘** โ€” sections, show, trace, diff | +| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/eddmpython/dartlab/blob/master/notebooks/tutorials/02_financial_statements.ipynb) | **์žฌ๋ฌด์ œํ‘œ** โ€” BS, IS, CF | +| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/eddmpython/dartlab/blob/master/notebooks/tutorials/04_ratios.ipynb) | **์žฌ๋ฌด๋น„์œจ** โ€” 47๊ฐœ ๋น„์œจ | +| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/eddmpython/dartlab/blob/master/notebooks/tutorials/06_disclosure.ipynb) | **๊ณต์‹œ ํ…์ŠคํŠธ** โ€” sections ํŒŒ์‹ฑ | +| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/eddmpython/dartlab/blob/master/notebooks/tutorials/09_edgar.ipynb) | **EDGAR** โ€” ๋ฏธ๊ตญ SEC | + +
+ +## Documentation + +- Docs: https://eddmpython.github.io/dartlab/ +- Sections guide: https://eddmpython.github.io/dartlab/docs/getting-started/sections +- Quick start: https://eddmpython.github.io/dartlab/docs/getting-started/quickstart +- API overview: https://eddmpython.github.io/dartlab/docs/api/overview +- Beginner guide (Korean): https://eddmpython.github.io/dartlab/blog/dartlab-easy-start/ + +### Blog + +The [DartLab Blog](https://eddmpython.github.io/dartlab/blog/) covers practical disclosure analysis โ€” how to read reports, interpret patterns, and spot risk signals. 120+ articles across three categories: + +- **Disclosure Systems** โ€” structure and mechanics of DART/EDGAR filings +- **Report Reading** โ€” practical guide to audit reports, preliminary earnings, restatements +- **Financial Interpretation** โ€” financial statements, ratios, and disclosure signals + +## Stability + +| Tier | Scope | +|------|-------| +| **Stable** | DART Company (sections, show, trace, diff, BS/IS/CF, CIS, index, filings, profile), EDGAR Company core, valuation, forecast, simulation | +| **Beta** | EDGAR power-user (SCE, notes, freq, coverage), insights, distress, ratios, timeseries, network, governance, workforce, capital, debt, chart/table/text tools, ask/chat, OpenDart, OpenEdgar, Server API, MCP, CLI subcommands | +| **Experimental** | AI tool calling, export | +| **Alpha** | Desktop App (Windows .exe) โ€” functional but incomplete, Sections Viewer โ€” not yet fully structured | + +See [docs/stability.md](docs/stability.md). + +## Contributing + +The project prefers **experiments before engine changes**. If you want to propose a parser or mapping change, validate it in `experiments/` first and bring the verified result back into the engine. + +- **Experiment folder**: `experiments/XXX_camelCaseName/` โ€” each file must be independently runnable with actual results in its docstring +- **Data contributions** (e.g. `accountMappings.json`, `sectionMappings.json`): only accepted when backed by experiment evidence โ€” no manual bulk edits +- Issues and PRs in Korean or English are both welcome + +## License + +MIT diff --git a/app.py b/app.py deleted file mode 100644 index be890b237f3ab7dcee7dca48626569c0c11a9b72..0000000000000000000000000000000000000000 --- a/app.py +++ /dev/null @@ -1,623 +0,0 @@ -"""DartLab Streamlit Demo โ€” AI ์ฑ„ํŒ… ๊ธฐ๋ฐ˜ ๊ธฐ์—… ๋ถ„์„.""" - -from __future__ import annotations - -import gc -import io -import os -import re - -import pandas as pd -import streamlit as st - -import dartlab - -# โ”€โ”€ ์„ค์ • โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ - -_MAX_CACHE = 2 -_LOGO_URL = "https://raw.githubusercontent.com/eddmpython/dartlab/master/.github/assets/logo.png" -_BLOG_URL = "https://eddmpython.github.io/dartlab/blog/dartlab-easy-start/" -_DOCS_URL = "https://eddmpython.github.io/dartlab/docs/getting-started/quickstart" -_COLAB_URL = "https://colab.research.google.com/github/eddmpython/dartlab/blob/master/notebooks/showcase/01_quickstart.ipynb" -_REPO_URL = "https://github.com/eddmpython/dartlab" - -_HAS_OPENAI = bool(os.environ.get("OPENAI_API_KEY")) - -if _HAS_OPENAI: - dartlab.llm.configure(provider="openai", api_key=os.environ["OPENAI_API_KEY"]) - -# โ”€โ”€ ํŽ˜์ด์ง€ ์„ค์ • โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ - -st.set_page_config( - page_title="DartLab โ€” AI ๊ธฐ์—… ๋ถ„์„", - page_icon=None, - layout="centered", -) - -# โ”€โ”€ CSS โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ - -st.markdown(""" - -""", unsafe_allow_html=True) - - -# โ”€โ”€ ์œ ํ‹ธ โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ - - -def _toPandas(df): - """Polars/pandas DataFrame -> pandas.""" - if df is None: - return None - if hasattr(df, "to_pandas"): - return df.to_pandas() - return df - - -def _formatDf(df: pd.DataFrame) -> pd.DataFrame: - """์ˆซ์ž๋ฅผ ์ฒœ๋‹จ์œ„ ์ฝค๋งˆ ๋ฌธ์ž์—ด๋กœ ๋ณ€ํ™˜ (์†Œ์ˆ˜์  ์ œ๊ฑฐ).""" - if df is None or df.empty: - return df - result = df.copy() - for col in result.columns: - if pd.api.types.is_numeric_dtype(result[col]): - result[col] = result[col].apply( - lambda x: f"{int(x):,}" if pd.notna(x) and x == x else "" - ) - return result - - -def _toExcel(df: pd.DataFrame) -> bytes: - """DataFrame -> Excel bytes.""" - buf = io.BytesIO() - df.to_excel(buf, index=False, engine="openpyxl") - return buf.getvalue() - - -def _showDf(df: pd.DataFrame, key: str = "", downloadName: str = ""): - """DataFrame ํ‘œ์‹œ + Excel ๋‹ค์šด๋กœ๋“œ.""" - if df is None or df.empty: - st.caption("๋ฐ์ดํ„ฐ ์—†์Œ") - return - st.dataframe(_formatDf(df), use_container_width=True, hide_index=True, key=key or None) - if downloadName: - st.download_button( - label="Excel ๋‹ค์šด๋กœ๋“œ", - data=_toExcel(df), - file_name=f"{downloadName}.xlsx", - mime="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", - key=f"dl_{key}" if key else None, - ) - - -@st.cache_resource(max_entries=_MAX_CACHE) -def _getCompany(code: str): - """์บ์‹œ๋œ Company.""" - gc.collect() - return dartlab.Company(code) - - -# โ”€โ”€ ์ข…๋ชฉ์ฝ”๋“œ ์ถ”์ถœ โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ - - -def _extractCode(message: str) -> str | None: - """๋ฉ”์‹œ์ง€์—์„œ ์ข…๋ชฉ์ฝ”๋“œ/ํšŒ์‚ฌ๋ช… ์ถ”์ถœ.""" - msg = message.strip() - - # 6์ž๋ฆฌ ์ˆซ์ž - m = re.search(r"\b(\d{6})\b", msg) - if m: - return m.group(1) - - # ์˜๋ฌธ ํ‹ฐ์ปค (๋‹จ๋… ๋Œ€๋ฌธ์ž 1~5์ž) - m = re.search(r"\b([A-Z]{1,5})\b", msg) - if m: - return m.group(1) - - # ํ•œ๊ธ€ ํšŒ์‚ฌ๋ช… โ†’ dartlab.search - cleaned = re.sub( - r"(์—\s*๋Œ€ํ•ด|์—\s*๋Œ€ํ•œ|์—๋Œ€ํ•ด|์ข€|์˜|๋ฅผ|์„|์€|๋Š”|์ด|๊ฐ€|๋„|๋งŒ|๋ถ€ํ„ฐ|๊นŒ์ง€|ํ•˜๊ณ |์ด๋ž‘|๋ž‘|๋กœ|์œผ๋กœ|์™€|๊ณผ|ํ•œํ…Œ|์—์„œ|์—๊ฒŒ)\b", - " ", - msg, - ) - # ๋ถˆํ•„์š”ํ•œ ๋™์‚ฌ/์กฐ๋™์‚ฌ ์ œ๊ฑฐ - cleaned = re.sub( - r"\b(์•Œ๋ ค์ค˜|๋ณด์—ฌ์ค˜|๋ถ„์„|ํ•ด์ค˜|ํ•ด๋ด|์–ด๋•Œ|๋ณด์ž|๋ณผ๋ž˜|์ค˜|ํ•ด|์ข€|์š”)\b", - " ", - cleaned, - ) - tokens = re.findall(r"[๊ฐ€-ํžฃA-Za-z0-9]+", cleaned) - # ๊ธด ํ† ํฐ ์šฐ์„  (ํšŒ์‚ฌ๋ช…์ผ ๊ฐ€๋Šฅ์„ฑ ๋†’์Œ) - tokens.sort(key=len, reverse=True) - for token in tokens: - if len(token) >= 2: - try: - results = dartlab.search(token) - if results is not None and len(results) > 0: - return str(results[0, "์ข…๋ชฉ์ฝ”๋“œ"]) - except Exception: - continue - return None - - -def _detectTopic(message: str) -> str | None: - """๋ฉ”์‹œ์ง€์—์„œ ํŠน์ • topic ํ‚ค์›Œ๋“œ ๊ฐ์ง€.""" - topicMap = { - "๋ฐฐ๋‹น": "dividend", - "์ฃผ์ฃผ": "majorHolder", - "๋Œ€์ฃผ์ฃผ": "majorHolder", - "์ง์›": "employee", - "์ž„์›": "executive", - "์ž„์›๋ณด์ˆ˜": "executivePay", - "๋ณด์ˆ˜": "executivePay", - "์„ธ๊ทธ๋จผํŠธ": "segments", - "๋ถ€๋ฌธ": "segments", - "์‚ฌ์—…๋ถ€": "segments", - "์œ ํ˜•์ž์‚ฐ": "tangibleAsset", - "๋ฌดํ˜•์ž์‚ฐ": "intangibleAsset", - "์›์žฌ๋ฃŒ": "rawMaterial", - "์ˆ˜์ฃผ": "salesOrder", - "์ œํ’ˆ": "productService", - "์žํšŒ์‚ฌ": "subsidiary", - "์ข…์†": "subsidiary", - "๋ถ€์ฑ„": "contingentLiability", - "์šฐ๋ฐœ": "contingentLiability", - "ํŒŒ์ƒ": "riskDerivative", - "์‚ฌ์ฑ„": "bond", - "์ด์‚ฌํšŒ": "boardOfDirectors", - "๊ฐ์‚ฌ": "audit", - "์ž๋ณธ๋ณ€๋™": "capitalChange", - "์ž๊ธฐ์ฃผ์‹": "treasuryStock", - "์‚ฌ์—…๊ฐœ์š”": "business", - "์‚ฌ์—…๋ณด๊ณ ": "business", - "์—ฐํ˜": "companyHistory", - } - msg = message.lower() - for keyword, topic in topicMap.items(): - if keyword in msg: - return topic - return None - - -# โ”€โ”€ AI โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ - - -def _askAi(stockCode: str, question: str) -> str: - """AI ์งˆ๋ฌธ. OpenAI ์šฐ์„ , HF ๋ฌด๋ฃŒ fallback.""" - if _HAS_OPENAI: - try: - q = f"{stockCode} {question}" if stockCode else question - answer = dartlab.ask(q, stream=False, raw=False) - return answer or "์‘๋‹ต ์—†์Œ" - except Exception as e: - return f"๋ถ„์„ ์‹คํŒจ: {e}" - - try: - from huggingface_hub import InferenceClient - token = os.environ.get("HF_TOKEN") - client = InferenceClient( - model="meta-llama/Llama-3.1-8B-Instruct", - token=token if token else None, - ) - context = _buildAiContext(stockCode) - systemMsg = ( - "๋‹น์‹ ์€ ํ•œ๊ตญ ๊ธฐ์—… ์žฌ๋ฌด ๋ถ„์„ ์ „๋ฌธ๊ฐ€์ž…๋‹ˆ๋‹ค. " - "์•„๋ž˜ ์žฌ๋ฌด ๋ฐ์ดํ„ฐ๋ฅผ ๋ฐ”ํƒ•์œผ๋กœ ์‚ฌ์šฉ์ž์˜ ์งˆ๋ฌธ์— ํ•œ๊ตญ์–ด๋กœ ๋‹ต๋ณ€ํ•˜์„ธ์š”. " - "์ˆซ์ž๋Š” ์ฒœ๋‹จ์œ„ ์ฝค๋งˆ๋ฅผ ์‚ฌ์šฉํ•˜๊ณ , ๊ทผ๊ฑฐ๋ฅผ ๋ช…ํ™•ํžˆ ์ œ์‹œํ•˜์„ธ์š”.\n\n" - f"{context}" - ) - response = client.chat_completion( - messages=[ - {"role": "system", "content": systemMsg}, - {"role": "user", "content": question}, - ], - max_tokens=1024, - ) - return response.choices[0].message.content or "์‘๋‹ต ์—†์Œ" - except Exception as e: - return f"AI ๋ถ„์„ ์‹คํŒจ: {e}" - - -def _buildAiContext(stockCode: str) -> str: - """AI ์ปจํ…์ŠคํŠธ ๊ตฌ์„ฑ.""" - try: - c = _getCompany(stockCode) - except Exception: - return f"์ข…๋ชฉ์ฝ”๋“œ: {stockCode}" - - parts = [f"๊ธฐ์—…: {c.corpName} ({c.stockCode}), ์‹œ์žฅ: {c.market}"] - for name, attr in [("์†์ต๊ณ„์‚ฐ์„œ", "IS"), ("์žฌ๋ฌด์ƒํƒœํ‘œ", "BS"), ("์žฌ๋ฌด๋น„์œจ", "ratios")]: - try: - df = _toPandas(getattr(c, attr, None)) - if df is not None and not df.empty: - parts.append(f"\n[{name}]\n{df.head(15).to_string()}") - except Exception: - pass - return "\n".join(parts) - - -# โ”€โ”€ ๋Œ€์‹œ๋ณด๋“œ ๋ Œ๋”๋ง โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ - - -def _renderCompanyCard(c): - """๊ธฐ์—… ์นด๋“œ.""" - currency = "" - if hasattr(c, "currency") and c.currency: - currency = c.currency - currencyHtml = ( - f"
ํ†ตํ™”" - f"{currency}
" - if currency else "" - ) - st.markdown(f""" -
-

{c.corpName}

-
-
- ์ข…๋ชฉ์ฝ”๋“œ - {c.stockCode} -
-
- ์‹œ์žฅ - {c.market} -
- {currencyHtml} -
-
- """, unsafe_allow_html=True) - - -def _renderFullDashboard(c, code: str): - """์ „์ฒด ์žฌ๋ฌด ๋Œ€์‹œ๋ณด๋“œ.""" - _renderCompanyCard(c) - - # ์žฌ๋ฌด์ œํ‘œ - st.markdown('
์žฌ๋ฌด์ œํ‘œ
', unsafe_allow_html=True) - for label, attr in [("IS (์†์ต๊ณ„์‚ฐ์„œ)", "IS"), ("BS (์žฌ๋ฌด์ƒํƒœํ‘œ)", "BS"), - ("CF (ํ˜„๊ธˆํ๋ฆ„ํ‘œ)", "CF"), ("ratios (์žฌ๋ฌด๋น„์œจ)", "ratios")]: - with st.expander(label, expanded=(attr == "IS")): - try: - df = _toPandas(getattr(c, attr, None)) - _showDf(df, key=f"dash_{attr}", downloadName=f"{code}_{attr}") - except Exception: - st.caption("๋กœ๋“œ ์‹คํŒจ") - - # Sections - topics = [] - try: - topics = list(c.topics) if c.topics else [] - except Exception: - pass - - if topics: - st.markdown('
๊ณต์‹œ ๋ฐ์ดํ„ฐ
', unsafe_allow_html=True) - selectedTopic = st.selectbox("topic", topics, label_visibility="collapsed", key="dash_topic") - if selectedTopic: - try: - result = c.show(selectedTopic) - if result is not None: - if hasattr(result, "to_pandas"): - _showDf(_toPandas(result), key="dash_sec", downloadName=f"{code}_{selectedTopic}") - else: - st.markdown(str(result)) - except Exception as e: - st.caption(f"์กฐํšŒ ์‹คํŒจ: {e}") - - -def _renderTopicData(c, code: str, topic: str): - """ํŠน์ • topic ๋ฐ์ดํ„ฐ๋งŒ ๋ Œ๋”๋ง.""" - try: - result = c.show(topic) - if result is not None: - if hasattr(result, "to_pandas"): - _showDf(_toPandas(result), key=f"topic_{topic}", downloadName=f"{code}_{topic}") - else: - st.markdown(str(result)) - else: - st.caption(f"'{topic}' ๋ฐ์ดํ„ฐ ์—†์Œ") - except Exception as e: - st.caption(f"์กฐํšŒ ์‹คํŒจ: {e}") - - -# โ”€โ”€ ํ”„๋ฆฌ๋กœ๋“œ โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ - -@st.cache_resource -def _warmup(): - """listing ์บ์‹œ.""" - try: - dartlab.search("์‚ผ์„ฑ์ „์ž") - except Exception: - pass - return True - -_warmup() - - -# โ”€โ”€ ํ—ค๋” โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ - -st.markdown(f""" -
-
- DartLab -

DartLab

-

์ข…๋ชฉ์ฝ”๋“œ ํ•˜๋‚˜. ๊ธฐ์—…์˜ ์ „์ฒด ์ด์•ผ๊ธฐ.

-

DART / EDGAR ๊ณต์‹œ ๋ฐ์ดํ„ฐ๋ฅผ ๊ตฌ์กฐํ™”ํ•˜์—ฌ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค

-
-""", unsafe_allow_html=True) - - -# โ”€โ”€ ์„ธ์…˜ ์ดˆ๊ธฐํ™” โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ - -if "messages" not in st.session_state: - st.session_state.messages = [] -if "code" not in st.session_state: - st.session_state.code = "" - - -# โ”€โ”€ ๋Œ€์‹œ๋ณด๋“œ ์˜์—ญ (์ข…๋ชฉ์ด ์žˆ์œผ๋ฉด ํ‘œ์‹œ) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ - -if st.session_state.code: - try: - _dashCompany = _getCompany(st.session_state.code) - _renderFullDashboard(_dashCompany, st.session_state.code) - except Exception as e: - st.error(f"๊ธฐ์—… ๋กœ๋“œ ์‹คํŒจ: {e}") - - st.markdown("---") - - -# โ”€โ”€ ์ฑ„ํŒ… ์˜์—ญ โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ - -# ํžˆ์Šคํ† ๋ฆฌ ํ‘œ์‹œ -for msg in st.session_state.messages: - with st.chat_message(msg["role"]): - st.markdown(msg["content"]) - -# ์ž…๋ ฅ -if prompt := st.chat_input("์‚ผ์„ฑ์ „์ž์— ๋Œ€ํ•ด ์•Œ๋ ค์ค˜, ๋ฐฐ๋‹น ํ˜„ํ™ฉ์€? ..."): - # ์‚ฌ์šฉ์ž ๋ฉ”์‹œ์ง€ ํ‘œ์‹œ - st.session_state.messages.append({"role": "user", "content": prompt}) - with st.chat_message("user"): - st.markdown(prompt) - - # ์ข…๋ชฉ์ฝ”๋“œ ์ถ”์ถœ ์‹œ๋„ - newCode = _extractCode(prompt) - if newCode and newCode != st.session_state.code: - st.session_state.code = newCode - - code = st.session_state.code - - if not code: - # ์ข…๋ชฉ ๋ชป ์ฐพ์Œ - reply = "์ข…๋ชฉ์„ ์ฐพ์ง€ ๋ชปํ–ˆ์Šต๋‹ˆ๋‹ค. ํšŒ์‚ฌ๋ช…์ด๋‚˜ ์ข…๋ชฉ์ฝ”๋“œ๋ฅผ ํฌํ•จํ•ด์„œ ๋‹ค์‹œ ์งˆ๋ฌธํ•ด์ฃผ์„ธ์š”.\n\n์˜ˆ: ์‚ผ์„ฑ์ „์ž์— ๋Œ€ํ•ด ์•Œ๋ ค์ค˜, 005930 ๋ถ„์„, AAPL ์žฌ๋ฌด" - st.session_state.messages.append({"role": "assistant", "content": reply}) - with st.chat_message("assistant"): - st.markdown(reply) - else: - # ์‘๋‹ต ์ƒ์„ฑ - with st.chat_message("assistant"): - # ํŠน์ • topic ๊ฐ์ง€ - topic = _detectTopic(prompt) - - if topic: - # ํŠน์ • topic๋งŒ ๋ณด์—ฌ์ฃผ๊ธฐ - try: - c = _getCompany(code) - _renderTopicData(c, code, topic) - except Exception: - pass - - # AI ์š”์•ฝ - with st.spinner("๋ถ„์„ ์ค‘..."): - aiAnswer = _askAi(code, prompt) - st.markdown(aiAnswer) - - st.session_state.messages.append({"role": "assistant", "content": aiAnswer}) - - # ๋Œ€์‹œ๋ณด๋“œ ๊ฐฑ์‹ ์„ ์œ„ํ•ด rerun - if newCode and newCode != "": - st.rerun() - - -# โ”€โ”€ ์ดˆ๊ธฐ ์•ˆ๋‚ด (๋Œ€ํ™” ์—†์„ ๋•Œ) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ - -if not st.session_state.messages and not st.session_state.code: - st.markdown(""" -
-

- ์•„๋ž˜ ์ž…๋ ฅ์ฐฝ์— ์ž์—ฐ์–ด๋กœ ์งˆ๋ฌธํ•˜์„ธ์š” -

-

- ์‚ผ์„ฑ์ „์ž์— ๋Œ€ํ•ด ์•Œ๋ ค์ค˜ · - 005930 ๋ถ„์„ · - AAPL ์žฌ๋ฌด ๋ณด์—ฌ์ค˜ -

-

- ์ข…๋ชฉ์„ ๋งํ•˜๋ฉด ์žฌ๋ฌด์ œํ‘œ/๊ณต์‹œ ๋ฐ์ดํ„ฐ๊ฐ€ ๋ฐ”๋กœ ํ‘œ์‹œ๋˜๊ณ , AI๊ฐ€ ๋ถ„์„์„ ๋ง๋ถ™์ž…๋‹ˆ๋‹ค -

-
- """, unsafe_allow_html=True) - - -# โ”€โ”€ ํ‘ธํ„ฐ โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ - -st.markdown(f""" -
- ์ดˆ๋ณด์ž ๊ฐ€์ด๋“œ / - ๊ณต์‹ ๋ฌธ์„œ / - Colab / - GitHub -
- pip install dartlab - -
-""", unsafe_allow_html=True) diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000000000000000000000000000000000000..edfedd3275963548107dfee86436d176411d7539 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,240 @@ +[project] +name = "dartlab" +version = "0.7.10" +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 :: 5 - Production/Stable", + "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 = [ + "alive-progress>=3.3.0,<4", + "beautifulsoup4>=4.14.3,<5", + "lxml>=6.0.2,<7", + "marimo>=0.20.4,<1", + "openpyxl>=3.1.5,<4", + "diff-match-patch>=20230430", + "httpx>=0.28.1,<1", + "orjson>=3.10.0,<4", + "polars>=1.0.0,<2", + "requests>=2.32.5,<3", + "rich>=14.3.3,<15", + "plotly>=5.0.0,<6", + "mcp[cli]>=1.0", +] + +[project.optional-dependencies] +llm = [ + "openai>=1.0.0,<3", + "google-genai>=1.0.0,<2", +] +llm-anthropic = [ + "openai>=1.0.0,<3", + "google-genai>=1.0.0,<2", + "anthropic>=0.30.0,<2", +] +charts = [ + "networkx>=3.6.1,<4", + "scipy>=1.17.1,<2", +] +ai = [ + "fastapi>=0.135.1,<1", + "httpx>=0.28.1,<1", + "msgpack>=1.1.0,<2", + "uvicorn[standard]>=0.30.0,<1", + "sse-starlette>=2.0.0,<3", +] +mcp = [ + "mcp[cli]>=1.0,<2", +] +display = [ + "great-tables>=0.15.0,<1", + "itables>=2.0.0,<3", +] +altair = [ + "altair>=5.0.0,<6", +] +hf = [ + "huggingface-hub>=0.20.0,<1", +] +ui = [ + "dartlab[ai]", +] +channel = [ + "dartlab[ai]", + "pycloudflared>=0.3", +] +channel-ngrok = [ + "dartlab[ai]", + "pyngrok>=7.0,<8", +] +channel-full = [ + "dartlab[channel,channel-ngrok]", + "python-telegram-bot>=21.0,<22", + "slack-bolt>=1.18,<2", + "discord.py>=2.4,<3", +] +all = [ + "openai>=1.0.0,<3", + "anthropic>=0.30.0,<2", + "networkx>=3.6.1,<4", + "scipy>=1.17.1,<2", + "fastapi>=0.135.1,<1", + "httpx>=0.28.1,<1", + "msgpack>=1.1.0,<2", + "uvicorn[standard]>=0.30.0,<1", + "sse-starlette>=2.0.0,<3", +] + +[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"] +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", + "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"] +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/ui/*", + "src/dartlab/engines/ai/providers/*", +] + +[tool.coverage.report] +show_missing = true +skip_empty = true +exclude_lines = [ + "pragma: no cover", + "if __name__", + "raise NotImplementedError", +] + +[tool.pyright] +pythonVersion = "3.12" +typeCheckingMode = "basic" +include = ["src/dartlab"] +exclude = [ + "src/dartlab/engines/ai/providers/**", + "src/dartlab/ui/**", + "experiments/**", +] +reportMissingTypeStubs = false +reportUnknownParameterType = false +reportUnknownMemberType = false +reportUnknownVariableType = false + +[tool.bandit] +exclude_dirs = ["experiments", "tests"] +skips = ["B101"] + +[dependency-groups] +dev = [ + "build>=1.4.0", + "dartlab[all]", + "hatchling>=1.29.0", + "pillow>=12.1.1", + "pre-commit>=4.0.0", + "pyright>=1.1.0", + "pytest>=9.0.2", + "pytest-asyncio>=0.24.0", + "pytest-cov>=6.0.0", +] diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index e9e66e99b31fbbbba682987e32e4fc2a43a7aab7..0000000000000000000000000000000000000000 --- a/requirements.txt +++ /dev/null @@ -1,4 +0,0 @@ -dartlab>=0.7.8 -streamlit>=1.45,<2 -openpyxl>=3.1 -huggingface_hub>=0.25 diff --git a/src/dartlab/API_SPEC.md b/src/dartlab/API_SPEC.md new file mode 100644 index 0000000000000000000000000000000000000000..0b155bba27538cd4f37927f35e268571628ef978 --- /dev/null +++ b/src/dartlab/API_SPEC.md @@ -0,0 +1,450 @@ +# dartlab API ์ŠคํŽ™ + +์ด ๋ฌธ์„œ๋Š” `scripts/generateSpec.py`์— ์˜ํ•ด ์ž๋™ ์ƒ์„ฑ๋ฉ๋‹ˆ๋‹ค. ์ง์ ‘ ์ˆ˜์ •ํ•˜์ง€ ๋งˆ์„ธ์š”. + + +--- + +## Company (ํ†ตํ•ฉ facade) + +์ž…๋ ฅ์„ ์ž๋™ ํŒ๋ณ„ํ•˜์—ฌ DART ๋˜๋Š” EDGAR ์‹œ์žฅ ์ „์šฉ Company๋ฅผ ์ƒ์„ฑํ•œ๋‹ค. +ํ˜„์žฌ DART Company์˜ ๊ณต๊ฐœ ์ง„์ž…์ ์€ **index โ†’ show(topic) โ†’ trace(topic)** ์ด๋‹ค. +`profile`์€ ํ–ฅํ›„ terminal/notebook ๋ฌธ์„œํ˜• ๋ณด๊ณ ์„œ ๋ทฐ๋กœ ํ™•์žฅ๋  ์˜ˆ์ •์ด๋‹ค. + +```python +import dartlab + +kr = dartlab.Company("005930") +kr = dartlab.Company("์‚ผ์„ฑ์ „์ž") +us = dartlab.Company("AAPL") + +kr.market # "KR" +us.market # "US" +``` + +### ํŒ๋ณ„ ๊ทœ์น™ + +| ์ž…๋ ฅ | ๊ฒฐ๊ณผ | ์˜ˆ์‹œ | +|------|------|------| +| 6์ž๋ฆฌ ์ˆซ์ž | DART Company | `Company("005930")` | +| ํ•œ๊ธ€ ํฌํ•จ | DART Company | `Company("์‚ผ์„ฑ์ „์ž")` | +| ์˜๋ฌธ 1~5์ž๋ฆฌ | EDGAR Company | `Company("AAPL")` | + +## DART Company + +### ํ˜„์žฌ ๊ณต๊ฐœ ์ง„์ž…์  + +| surface | ์„ค๋ช… | +|---------|------| +| `index` | ํšŒ์‚ฌ ๋ฐ์ดํ„ฐ ๊ตฌ์กฐ ์ธ๋ฑ์Šค DataFrame | +| `show(topic)` | topic์˜ ์‹ค์ œ ๋ฐ์ดํ„ฐ payload ์กฐํšŒ | +| `trace(topic, period)` | docs / finance / report source provenance ์กฐํšŒ | +| `docs` | pure docs source namespace | +| `finance` | authoritative finance source namespace | +| `report` | authoritative structured disclosure source namespace | +| `profile` | ํ–ฅํ›„ ๋ณด๊ณ ์„œํ˜• ๋ Œ๋”์šฉ ์˜ˆ์•ฝ ๋ทฐ | + +### ์ •์  ๋ฉ”์„œ๋“œ + +| ๋ฉ”์„œ๋“œ | ๋ฐ˜ํ™˜ | ์„ค๋ช… | +|--------|------|------| +| `dartlab.providers.dart.Company.listing()` | DataFrame | KRX ์ „์ฒด ์ƒ์žฅ๋ฒ•์ธ ๋ชฉ๋ก | +| `dartlab.providers.dart.Company.search(keyword)` | DataFrame | ํšŒ์‚ฌ๋ช… ๋ถ€๋ถ„ ๊ฒ€์ƒ‰ | +| `dartlab.providers.dart.Company.status()` | DataFrame | ๋กœ์ปฌ ๋ณด์œ  ์ „์ฒด ์ข…๋ชฉ ์ธ๋ฑ์Šค | +| `dartlab.providers.dart.Company.resolve(codeOrName)` | str \| None | ์ข…๋ชฉ์ฝ”๋“œ/ํšŒ์‚ฌ๋ช… โ†’ ์ข…๋ชฉ์ฝ”๋“œ | + +### ํ•ต์‹ฌ property + +| property | ๋ฐ˜ํ™˜ | ์„ค๋ช… | +|----------|------|------| +| `BS` | DataFrame | ์žฌ๋ฌด์ƒํƒœํ‘œ | +| `IS` | DataFrame | ์†์ต๊ณ„์‚ฐ์„œ | +| `CIS` | DataFrame | ํฌ๊ด„์†์ต๊ณ„์‚ฐ์„œ | +| `CF` | DataFrame | ํ˜„๊ธˆํ๋ฆ„ํ‘œ | +| `SCE` | tuple \| DataFrame | ์ž๋ณธ๋ณ€๋™ํ‘œ | +| `sections` | DataFrame | merged topic x period company table | +| `timeseries` | (series, periods) | ๋ถ„๊ธฐ๋ณ„ standalone ์‹œ๊ณ„์—ด | +| `annual` | (series, years) | ์—ฐ๋„๋ณ„ ์‹œ๊ณ„์—ด | +| `ratios` | RatioResult | ์žฌ๋ฌด๋น„์œจ | +| `index` | DataFrame | ํšŒ์‚ฌ ๊ตฌ์กฐ ์ธ๋ฑ์Šค | +| `docs` | Accessor | pure docs source | +| `finance` | Accessor | authoritative finance source | +| `report` | Accessor | authoritative report source | +| `profile` | _BoardView | ํ–ฅํ›„ ๋ณด๊ณ ์„œํ˜• ๋ทฐ ์˜ˆ์•ฝ | +| `sector` | SectorInfo | ์„นํ„ฐ ๋ถ„๋ฅ˜ | +| `insights` | AnalysisResult | 7์˜์—ญ ์ธ์‚ฌ์ดํŠธ ๋“ฑ๊ธ‰ | +| `rank` | RankInfo | ์‹œ์žฅ ์ˆœ์œ„ | +| `notes` | Notes | K-IFRS ์ฃผ์„ ์ ‘๊ทผ | +| `market` | str | `"KR"` | + +### ๋ฉ”์„œ๋“œ + +| ๋ฉ”์„œ๋“œ | ๋ฐ˜ํ™˜ | ์„ค๋ช… | +|--------|------|------| +| `get(name)` | Result | ๋ชจ๋“ˆ ์ „์ฒด Result ๊ฐ์ฒด | +| `all()` | dict | ์ „์ฒด ๋ฐ์ดํ„ฐ dict | +| `show(topic, period=None, raw=False)` | Any | topic payload ์กฐํšŒ | +| `trace(topic, period=None)` | dict \| None | ์„ ํƒ source provenance ์กฐํšŒ | +| `fsSummary(period)` | AnalysisResult | ์š”์•ฝ์žฌ๋ฌด์ •๋ณด | +| `getTimeseries(period, fsDivPref)` | (series, periods) | ์ปค์Šคํ…€ ์‹œ๊ณ„์—ด | +| `getRatios(fsDivPref)` | RatioResult | ์ปค์Šคํ…€ ๋น„์œจ | + +`index`๋Š” ํšŒ์‚ฌ ์ „์ฒด ๊ตฌ์กฐ๋ฅผ ๋จผ์ € ๋ณด์—ฌ์ฃผ๊ณ , `show(topic)`๊ฐ€ ์‹ค์ œ ๋ฐ์ดํ„ฐ๋ฅผ ์—ฐ๋‹ค. +`trace(topic)`๋Š” ๊ฐ™์€ topic์—์„œ docs / finance / report ์ค‘ ์–ด๋–ค source๊ฐ€ ์ฑ„ํƒ๋๋Š”์ง€ ์„ค๋ช…ํ•œ๋‹ค. +docs๊ฐ€ ์—†๋Š” ํšŒ์‚ฌ๋Š” `docsStatus` ์•ˆ๋‚ด row์™€ `ํ˜„์žฌ ์‚ฌ์—…๋ณด๊ณ ์„œ ๋ถ€์žฌ` notice๊ฐ€ ํ‘œ์‹œ๋œ๋‹ค. + +report/disclosure property๋Š” registry์—์„œ ์ž๋™ ๋””์ŠคํŒจ์น˜๋œ๋‹ค (`_MODULE_REGISTRY`). +๋“ฑ๋ก๋œ ๋ชจ๋“  property๋Š” ์•„๋ž˜ "๋ฐ์ดํ„ฐ ๋ ˆ์ง€์ŠคํŠธ๋ฆฌ" ์„น์…˜ ์ฐธ์กฐ. + +## EDGAR Company + +```python +import dartlab + +us = dartlab.Company("AAPL") +us.ticker # "AAPL" +us.cik # "0000320193" +``` + +### property + +| property | ๋ฐ˜ํ™˜ | ์„ค๋ช… | +|----------|------|------| +| `timeseries` | (series, periods) | ๋ถ„๊ธฐ๋ณ„ standalone ์‹œ๊ณ„์—ด | +| `annual` | (series, years) | ์—ฐ๋„๋ณ„ ์‹œ๊ณ„์—ด | +| `ratios` | RatioResult | ์žฌ๋ฌด๋น„์œจ | +| `insights` | AnalysisResult | 7์˜์—ญ ์ธ์‚ฌ์ดํŠธ ๋“ฑ๊ธ‰ | +| `market` | str | `"US"` | + +--- + +## ๋ฐ์ดํ„ฐ ๋ ˆ์ง€์ŠคํŠธ๋ฆฌ + +`core/registry.py`์— ๋“ฑ๋ก๋œ ์ „์ฒด ๋ฐ์ดํ„ฐ ์†Œ์Šค ๋ชฉ๋ก. + +๋ชจ๋“ˆ ์ถ”๊ฐ€ = registry์— DataEntry ํ•œ ์ค„ ์ถ”๊ฐ€ โ†’ Company, Excel, LLM, Server, Skills ์ „๋ถ€ ์ž๋™ ๋ฐ˜์˜. + +### ์‹œ๊ณ„์—ด ์žฌ๋ฌด์ œํ‘œ (finance) + +| name | label | dataType | description | +|------|-------|----------|-------------| +| `annual.IS` | ์†์ต๊ณ„์‚ฐ์„œ(์—ฐ๋„๋ณ„) | `timeseries` | ์—ฐ๋„๋ณ„ ์†์ต๊ณ„์‚ฐ์„œ ์‹œ๊ณ„์—ด. ๋งค์ถœ์•ก, ์˜์—…์ด์ต, ์ˆœ์ด์ต ๋“ฑ ์ „์ฒด ๊ณ„์ •. | +| `annual.BS` | ์žฌ๋ฌด์ƒํƒœํ‘œ(์—ฐ๋„๋ณ„) | `timeseries` | ์—ฐ๋„๋ณ„ ์žฌ๋ฌด์ƒํƒœํ‘œ ์‹œ๊ณ„์—ด. ์ž์‚ฐ, ๋ถ€์ฑ„, ์ž๋ณธ ์ „์ฒด ๊ณ„์ •. | +| `annual.CF` | ํ˜„๊ธˆํ๋ฆ„ํ‘œ(์—ฐ๋„๋ณ„) | `timeseries` | ์—ฐ๋„๋ณ„ ํ˜„๊ธˆํ๋ฆ„ํ‘œ ์‹œ๊ณ„์—ด. ์˜์—…/ํˆฌ์ž/์žฌ๋ฌดํ™œ๋™ ํ˜„๊ธˆํ๋ฆ„. | +| `timeseries.IS` | ์†์ต๊ณ„์‚ฐ์„œ(๋ถ„๊ธฐ๋ณ„) | `timeseries` | ๋ถ„๊ธฐ๋ณ„ ์†์ต๊ณ„์‚ฐ์„œ standalone ์‹œ๊ณ„์—ด. | +| `timeseries.BS` | ์žฌ๋ฌด์ƒํƒœํ‘œ(๋ถ„๊ธฐ๋ณ„) | `timeseries` | ๋ถ„๊ธฐ๋ณ„ ์žฌ๋ฌด์ƒํƒœํ‘œ ์‹œ์ ์ž”์•ก ์‹œ๊ณ„์—ด. | +| `timeseries.CF` | ํ˜„๊ธˆํ๋ฆ„ํ‘œ(๋ถ„๊ธฐ๋ณ„) | `timeseries` | ๋ถ„๊ธฐ๋ณ„ ํ˜„๊ธˆํ๋ฆ„ํ‘œ standalone ์‹œ๊ณ„์—ด. | + +### ๊ณต์‹œ ํŒŒ์‹ฑ ๋ชจ๋“ˆ (report) + +| name | label | dataType | description | +|------|-------|----------|-------------| +| `BS` | ์žฌ๋ฌด์ƒํƒœํ‘œ | `dataframe` | K-IFRS ์—ฐ๊ฒฐ ์žฌ๋ฌด์ƒํƒœํ‘œ. finance XBRL ์ •๊ทœํ™”(snakeId) ๊ธฐ๋ฐ˜, ํšŒ์‚ฌ๊ฐ„ ๋น„๊ต ๊ฐ€๋Šฅ. finance ์—†์œผ๋ฉด docs fallback. | +| `IS` | ์†์ต๊ณ„์‚ฐ์„œ | `dataframe` | K-IFRS ์—ฐ๊ฒฐ ์†์ต๊ณ„์‚ฐ์„œ. finance XBRL ์ •๊ทœํ™” ๊ธฐ๋ฐ˜. ๋งค์ถœ์•ก, ์˜์—…์ด์ต, ์ˆœ์ด์ต ๋“ฑ ์ „์ฒด ๊ณ„์ • ํฌํ•จ. | +| `CF` | ํ˜„๊ธˆํ๋ฆ„ํ‘œ | `dataframe` | K-IFRS ์—ฐ๊ฒฐ ํ˜„๊ธˆํ๋ฆ„ํ‘œ. finance XBRL ์ •๊ทœํ™” ๊ธฐ๋ฐ˜. ์˜์—…/ํˆฌ์ž/์žฌ๋ฌดํ™œ๋™ ํ˜„๊ธˆํ๋ฆ„. | +| `fsSummary` | ์š”์•ฝ์žฌ๋ฌด์ •๋ณด | `dataframe` | DART ๊ณต์‹œ ์š”์•ฝ์žฌ๋ฌด์ •๋ณด. ๋‹ค๋…„๊ฐ„ ์ฃผ์š” ์žฌ๋ฌด์ง€ํ‘œ ๋น„๊ต. | +| `segments` | ๋ถ€๋ฌธ์ •๋ณด | `dataframe` | ์‚ฌ์—…๋ถ€๋ฌธ๋ณ„ ๋งค์ถœยท์ด์ต ๋ฐ์ดํ„ฐ. ๋ถ€๋ฌธ๊ฐ„ ์ˆ˜์ต์„ฑ ๋น„๊ต ๊ฐ€๋Šฅ. | +| `tangibleAsset` | ์œ ํ˜•์ž์‚ฐ | `dataframe` | ์œ ํ˜•์ž์‚ฐ ๋ณ€๋™ํ‘œ. ์ทจ๋“/์ฒ˜๋ถ„/๊ฐ๊ฐ€์ƒ๊ฐ ๋‚ด์—ญ. | +| `costByNature` | ๋น„์šฉ์„ฑ๊ฒฉ๋ณ„๋ถ„๋ฅ˜ | `dataframe` | ๋น„์šฉ์„ ์„ฑ๊ฒฉ๋ณ„๋กœ ๋ถ„๋ฅ˜ํ•œ ์‹œ๊ณ„์—ด. ์›์žฌ๋ฃŒ๋น„, ์ธ๊ฑด๋น„, ๊ฐ๊ฐ€์ƒ๊ฐ๋น„ ๋“ฑ. | +| `dividend` | ๋ฐฐ๋‹น | `dataframe` | ๋ฐฐ๋‹น ์‹œ๊ณ„์—ด. ์—ฐ๋„๋ณ„ DPS, ๋ฐฐ๋‹น์ด์•ก, ๋ฐฐ๋‹น์„ฑํ–ฅ, ๋ฐฐ๋‹น์ˆ˜์ต๋ฅ . | +| `majorHolder` | ์ตœ๋Œ€์ฃผ์ฃผ | `dataframe` | ์ตœ๋Œ€์ฃผ์ฃผ ์ง€๋ถ„์œจ ์‹œ๊ณ„์—ด. ์ง€๋ถ„ ๋ณ€๋™์€ ๊ฒฝ์˜๊ถŒ ์•ˆ์ •์„ฑ์˜ ํ•ต์‹ฌ ์ง€ํ‘œ. | +| `employee` | ์ง์›ํ˜„ํ™ฉ | `dataframe` | ์ง์› ์ˆ˜, ํ‰๊ท  ๊ทผ์†์—ฐ์ˆ˜, ํ‰๊ท  ์—ฐ๋ด‰ ์‹œ๊ณ„์—ด. | +| `subsidiary` | ์žํšŒ์‚ฌํˆฌ์ž | `dataframe` | ์ข…์†ํšŒ์‚ฌ ํˆฌ์ž ์‹œ๊ณ„์—ด. ์ง€๋ถ„์œจ, ์žฅ๋ถ€๊ฐ€์•ก ๋ณ€๋™. | +| `bond` | ์ฑ„๋ฌด์ฆ๊ถŒ | `dataframe` | ์‚ฌ์ฑ„, CP ๋“ฑ ์ฑ„๋ฌด์ฆ๊ถŒ ๋ฐœํ–‰ยท์ƒํ™˜ ์‹œ๊ณ„์—ด. | +| `shareCapital` | ์ฃผ์‹ํ˜„ํ™ฉ | `dataframe` | ๋ฐœํ–‰์ฃผ์‹์ˆ˜, ์ž๊ธฐ์ฃผ์‹, ์œ ํ†ต์ฃผ์‹์ˆ˜ ์‹œ๊ณ„์—ด. | +| `executive` | ์ž„์›ํ˜„ํ™ฉ | `dataframe` | ๋“ฑ๊ธฐ์ž„์› ๊ตฌ์„ฑ ์‹œ๊ณ„์—ด. ์‚ฌ๋‚ด์ด์‚ฌ/์‚ฌ์™ธ์ด์‚ฌ/๋น„์ƒ๋ฌด์ด์‚ฌ ๊ตฌ๋ถ„. | +| `executivePay` | ์ž„์›๋ณด์ˆ˜ | `dataframe` | ์ž„์› ์œ ํ˜•๋ณ„ ๋ณด์ˆ˜ ์‹œ๊ณ„์—ด. ๋“ฑ๊ธฐ์ด์‚ฌ/์‚ฌ์™ธ์ด์‚ฌ/๊ฐ์‚ฌ ๊ตฌ๋ถ„. | +| `audit` | ๊ฐ์‚ฌ์˜๊ฒฌ | `dataframe` | ์™ธ๋ถ€๊ฐ์‚ฌ์ธ์˜ ๊ฐ์‚ฌ์˜๊ฒฌ๊ณผ ๊ฐ์‚ฌ๋ณด์ˆ˜ ์‹œ๊ณ„์—ด. ์ ์ • ์™ธ ์˜๊ฒฌ์€ ์ค‘๋Œ€ ์œ„ํ—˜ ์‹ ํ˜ธ. | +| `boardOfDirectors` | ์ด์‚ฌํšŒ | `dataframe` | ์ด์‚ฌํšŒ ๊ตฌ์„ฑ ๋ฐ ํ™œ๋™ ์‹œ๊ณ„์—ด. ๊ฐœ์ตœํšŸ์ˆ˜, ์ถœ์„๋ฅ  ํฌํ•จ. | +| `capitalChange` | ์ž๋ณธ๋ณ€๋™ | `dataframe` | ์ž๋ณธ๊ธˆ ๋ณ€๋™ ์‹œ๊ณ„์—ด. ๋ณดํ†ต์ฃผ/์šฐ์„ ์ฃผ ์ฃผ์‹์ˆ˜ยท์•ก๋ฉด ๋ณ€๋™. | +| `contingentLiability` | ์šฐ๋ฐœ๋ถ€์ฑ„ | `dataframe` | ์ฑ„๋ฌด๋ณด์ฆ, ์†Œ์†ก ํ˜„ํ™ฉ. ์ž ์žฌ์  ์žฌ๋ฌด ๋ฆฌ์Šคํฌ ์ง€ํ‘œ. | +| `internalControl` | ๋‚ด๋ถ€ํ†ต์ œ | `dataframe` | ๋‚ด๋ถ€ํšŒ๊ณ„๊ด€๋ฆฌ์ œ๋„ ๊ฐ์‚ฌ์˜๊ฒฌ ์‹œ๊ณ„์—ด. | +| `relatedPartyTx` | ๊ด€๊ณ„์ž๊ฑฐ๋ž˜ | `dataframe` | ๋Œ€์ฃผ์ฃผ ๋“ฑ๊ณผ์˜ ๋งค์ถœยท๋งค์ž… ๊ฑฐ๋ž˜ ์‹œ๊ณ„์—ด. ์ด์ „๊ฐ€๊ฒฉ ๋ฆฌ์Šคํฌ ํ™•์ธ. | +| `rnd` | R&D | `dataframe` | ์—ฐ๊ตฌ๊ฐœ๋ฐœ๋น„์šฉ ์‹œ๊ณ„์—ด. ๊ธฐ์ˆ  ํˆฌ์ž ๊ฐ•๋„ ํŒ๋‹จ. | +| `sanction` | ์ œ์žฌํ˜„ํ™ฉ | `dataframe` | ํ–‰์ •์ œ์žฌ, ๊ณผ์ง•๊ธˆ, ์˜์—…์ •์ง€ ๋“ฑ ๊ทœ์ œ ์กฐ์น˜ ์ด๋ ฅ. | +| `affiliateGroup` | ๊ณ„์—ด์‚ฌ | `dataframe` | ๊ธฐ์—…์ง‘๋‹จ ์†Œ์† ๊ณ„์—ดํšŒ์‚ฌ ํ˜„ํ™ฉ. ์ƒ์žฅ/๋น„์ƒ์žฅ ๊ตฌ๋ถ„. | +| `fundraising` | ์ฆ์ž๊ฐ์ž | `dataframe` | ์œ ์ƒ์ฆ์ž, ๋ฌด์ƒ์ฆ์ž, ๊ฐ์ž ์ด๋ ฅ. | +| `productService` | ์ฃผ์š”์ œํ’ˆ | `dataframe` | ์ฃผ์š” ์ œํ’ˆ/์„œ๋น„์Šค๋ณ„ ๋งค์ถœ์•ก๊ณผ ๋น„์ค‘. | +| `salesOrder` | ๋งค์ถœ์ˆ˜์ฃผ | `dataframe` | ๋งค์ถœ์‹ค์  ๋ฐ ์ˆ˜์ฃผ ํ˜„ํ™ฉ. | +| `riskDerivative` | ์œ„ํ—˜๊ด€๋ฆฌ | `dataframe` | ํ™˜์œจยท์ด์ž์œจยท์ƒํ’ˆ๊ฐ€๊ฒฉ ๋ฆฌ์Šคํฌ ๊ด€๋ฆฌ. ํŒŒ์ƒ์ƒํ’ˆ ๋ณด์œ  ํ˜„ํ™ฉ. | +| `articlesOfIncorporation` | ์ •๊ด€ | `dataframe` | ์ •๊ด€ ๋ณ€๊ฒฝ ์ด๋ ฅ. ์‚ฌ์—…๋ชฉ์  ์ถ”๊ฐ€ยท๋ณ€๊ฒฝ์œผ๋กœ ์‹ ์‚ฌ์—… ์ง„์ถœ ํŒŒ์•…. | +| `otherFinance` | ๊ธฐํƒ€์žฌ๋ฌด | `dataframe` | ๋Œ€์†์ถฉ๋‹น๊ธˆ, ์žฌ๊ณ ์ž์‚ฐ ๊ด€๋ จ ๊ธฐํƒ€ ์žฌ๋ฌด ๋ฐ์ดํ„ฐ. | +| `companyHistory` | ์—ฐํ˜ | `dataframe` | ํšŒ์‚ฌ ์ฃผ์š” ์—ฐํ˜ ์ด๋ฒคํŠธ ๋ชฉ๋ก. | +| `shareholderMeeting` | ์ฃผ์ฃผ์ดํšŒ | `dataframe` | ์ฃผ์ฃผ์ดํšŒ ์•ˆ๊ฑด ๋ฐ ์˜๊ฒฐ ๊ฒฐ๊ณผ. | +| `auditSystem` | ๊ฐ์‚ฌ์ œ๋„ | `dataframe` | ๊ฐ์‚ฌ์œ„์›ํšŒ ๊ตฌ์„ฑ ๋ฐ ํ™œ๋™ ํ˜„ํ™ฉ. | +| `affiliate` | ๊ด€๊ณ„๊ธฐ์—…ํˆฌ์ž | `dataframe` | ๊ด€๊ณ„๊ธฐ์—…/๊ณต๋™๊ธฐ์—… ํˆฌ์ž ๋ณ€๋™ ์‹œ๊ณ„์—ด. ์ง€๋ถ„๋ฒ•์†์ต, ๊ธฐ์ดˆ/๊ธฐ๋ง ์žฅ๋ถ€๊ฐ€ ํฌํ•จ. | +| `investmentInOther` | ํƒ€๋ฒ•์ธ์ถœ์ž | `dataframe` | ํƒ€๋ฒ•์ธ ์ถœ์ž ํ˜„ํ™ฉ. ํˆฌ์ž๋ชฉ์ , ์ง€๋ถ„์œจ, ์žฅ๋ถ€๊ฐ€ ๋“ฑ. | +| `companyOverviewDetail` | ํšŒ์‚ฌ๊ฐœ์š” | `dict` | ์„ค๋ฆฝ์ผ, ์ƒ์žฅ์ผ, ๋Œ€ํ‘œ์ด์‚ฌ, ์ฃผ์†Œ, ์ฃผ์š”์‚ฌ์—… ๋“ฑ ๊ธฐ๋ณธ ์ •๋ณด. | +| `holderOverview` | ์ฃผ์ฃผํ˜„ํ™ฉ | `custom` | 5% ์ด์ƒ ์ฃผ์ฃผ, ์†Œ์•ก์ฃผ์ฃผ ํ˜„ํ™ฉ, ์˜๊ฒฐ๊ถŒ ํ˜„ํ™ฉ. majorHolder๋ณด๋‹ค ์ƒ์„ธํ•œ ์ฃผ์ฃผ ๊ตฌ์„ฑ. | + +### ์„œ์ˆ ํ˜• ๊ณต์‹œ (disclosure) + +| name | label | dataType | description | +|------|-------|----------|-------------| +| `business` | ์‚ฌ์—…์˜๋‚ด์šฉ | `text` | ์‚ฌ์—…๋ณด๊ณ ์„œ '์‚ฌ์—…์˜ ๋‚ด์šฉ' ์„œ์ˆ . ์‚ฌ์—… ๊ตฌ์กฐ์™€ ํ˜„ํ™ฉ ํŒŒ์•…. | +| `companyOverview` | ํšŒ์‚ฌ๊ฐœ์š”์ •๋Ÿ‰ | `dict` | ๊ณต์‹œ ๊ธฐ๋ฐ˜ ํšŒ์‚ฌ ์ •๋Ÿ‰ ๊ฐœ์š” ๋ฐ์ดํ„ฐ. | +| `mdna` | MD&A | `text` | ์ด์‚ฌ์˜ ๊ฒฝ์˜์ง„๋‹จ ๋ฐ ๋ถ„์„์˜๊ฒฌ. ๊ฒฝ์˜์ง„ ์‹œ๊ฐ์˜ ์‹ค์  ํ‰๊ฐ€์™€ ์ „๋ง. | +| `rawMaterial` | ์›์žฌ๋ฃŒ์„ค๋น„ | `dict` | ์›์žฌ๋ฃŒ ๋งค์ž…, ์œ ํ˜•์ž์‚ฐ ํ˜„ํ™ฉ, ์‹œ์„คํˆฌ์ž ๋ฐ์ดํ„ฐ. | +| `sections` | ์‚ฌ์—…๋ณด๊ณ ์„œ์„น์…˜ | `dataframe` | ์‚ฌ์—…๋ณด๊ณ ์„œ ์ „์ฒด ์„น์…˜ ํ…์ŠคํŠธ๋ฅผ topic(ํ–‰) ร— period(์—ด) DataFrame์œผ๋กœ ๊ตฌ์กฐํ™”. leaf title ๊ธฐ์ค€ ์ˆ˜ํ‰ ๋น„๊ต ๊ฐ€๋Šฅ. ์—ฐ๊ฐ„+๋ถ„๊ธฐ+๋ฐ˜๊ธฐ ์ „ ๊ธฐ๊ฐ„ ํฌํ•จ. | + +### K-IFRS ์ฃผ์„ (notes) + +| name | label | dataType | description | +|------|-------|----------|-------------| +| `notes.receivables` | ๋งค์ถœ์ฑ„๊ถŒ | `dataframe` | K-IFRS ๋งค์ถœ์ฑ„๊ถŒ ์ฃผ์„. ์ฑ„๊ถŒ ์ž”์•ก ๋ฐ ๋Œ€์†์ถฉ๋‹น๊ธˆ ๋‚ด์—ญ. | +| `notes.inventory` | ์žฌ๊ณ ์ž์‚ฐ | `dataframe` | K-IFRS ์žฌ๊ณ ์ž์‚ฐ ์ฃผ์„. ์›์žฌ๋ฃŒ/์žฌ๊ณตํ’ˆ/์ œํ’ˆ ๋‚ด์—ญ๋ณ„ ๊ธˆ์•ก. | +| `notes.tangibleAsset` | ์œ ํ˜•์ž์‚ฐ(์ฃผ์„) | `dataframe` | K-IFRS ์œ ํ˜•์ž์‚ฐ ๋ณ€๋™ ์ฃผ์„. ํ† ์ง€, ๊ฑด๋ฌผ, ๊ธฐ๊ณ„ ๋“ฑ ํ•ญ๋ชฉ๋ณ„ ๋ณ€๋™. | +| `notes.intangibleAsset` | ๋ฌดํ˜•์ž์‚ฐ | `dataframe` | K-IFRS ๋ฌดํ˜•์ž์‚ฐ ์ฃผ์„. ์˜์—…๊ถŒ, ๊ฐœ๋ฐœ๋น„ ๋“ฑ ํ•ญ๋ชฉ๋ณ„ ๋ณ€๋™. | +| `notes.investmentProperty` | ํˆฌ์ž๋ถ€๋™์‚ฐ | `dataframe` | K-IFRS ํˆฌ์ž๋ถ€๋™์‚ฐ ์ฃผ์„. ๊ณต์ •๊ฐ€์น˜ ๋ฐ ๋ณ€๋™ ๋‚ด์—ญ. | +| `notes.affiliates` | ๊ด€๊ณ„๊ธฐ์—…(์ฃผ์„) | `dataframe` | K-IFRS ๊ด€๊ณ„๊ธฐ์—… ํˆฌ์ž ์ฃผ์„. ์ง€๋ถ„๋ฒ• ์ ์šฉ ๋‚ด์—ญ. | +| `notes.borrowings` | ์ฐจ์ž…๊ธˆ | `dataframe` | K-IFRS ์ฐจ์ž…๊ธˆ ์ฃผ์„. ๋‹จ๊ธฐ/์žฅ๊ธฐ ์ฐจ์ž… ์ž”์•ก ๋ฐ ์ด์ž์œจ. | +| `notes.provisions` | ์ถฉ๋‹น๋ถ€์ฑ„ | `dataframe` | K-IFRS ์ถฉ๋‹น๋ถ€์ฑ„ ์ฃผ์„. ํŒ๋งค๋ณด์ฆ, ์†Œ์†ก, ๋ณต๊ตฌ ๋“ฑ. | +| `notes.eps` | ์ฃผ๋‹น์ด์ต | `dataframe` | K-IFRS ์ฃผ๋‹น์ด์ต ์ฃผ์„. ๊ธฐ๋ณธ/ํฌ์„ EPS ๊ณ„์‚ฐ ๋‚ด์—ญ. | +| `notes.lease` | ๋ฆฌ์Šค | `dataframe` | K-IFRS ๋ฆฌ์Šค ์ฃผ์„. ์‚ฌ์šฉ๊ถŒ์ž์‚ฐ, ๋ฆฌ์Šค๋ถ€์ฑ„ ๋‚ด์—ญ. | +| `notes.segments` | ๋ถ€๋ฌธ์ •๋ณด(์ฃผ์„) | `dataframe` | K-IFRS ๋ถ€๋ฌธ์ •๋ณด ์ฃผ์„. ์‚ฌ์—…๋ถ€๋ฌธ๋ณ„ ์ƒ์„ธ ๋ฐ์ดํ„ฐ. | +| `notes.costByNature` | ๋น„์šฉ์˜์„ฑ๊ฒฉ๋ณ„๋ถ„๋ฅ˜(์ฃผ์„) | `dataframe` | K-IFRS ๋น„์šฉ์˜ ์„ฑ๊ฒฉ๋ณ„ ๋ถ„๋ฅ˜ ์ฃผ์„. | + +### ์›๋ณธ ๋ฐ์ดํ„ฐ (raw) + +| name | label | dataType | description | +|------|-------|----------|-------------| +| `rawDocs` | ๊ณต์‹œ ์›๋ณธ | `dataframe` | ๊ณต์‹œ ๋ฌธ์„œ ์›๋ณธ parquet. ๊ฐ€๊ณต ์ „ ์ „์ฒด ํ…Œ์ด๋ธ”๊ณผ ํ…์ŠคํŠธ. | +| `rawFinance` | XBRL ์›๋ณธ | `dataframe` | XBRL ์žฌ๋ฌด์ œํ‘œ ์›๋ณธ parquet. ๋งคํ•‘/์ •๊ทœํ™” ์ „ ์›๋ณธ ๋ฐ์ดํ„ฐ. | +| `rawReport` | ๋ณด๊ณ ์„œ ์›๋ณธ | `dataframe` | ์ •๊ธฐ๋ณด๊ณ ์„œ API ์›๋ณธ parquet. ํŒŒ์‹ฑ ์ „ ์›๋ณธ ๋ฐ์ดํ„ฐ. | + +### ๋ถ„์„ ์—”์ง„ (analysis) + +| name | label | dataType | description | +|------|-------|----------|-------------| +| `ratios` | ์žฌ๋ฌด๋น„์œจ | `ratios` | financeEngine์ด ์ž๋™๊ณ„์‚ฐํ•œ ์ˆ˜์ต์„ฑยท์•ˆ์ •์„ฑยท๋ฐธ๋ฅ˜์—์ด์…˜ ๋น„์œจ. | +| `insight` | ์ธ์‚ฌ์ดํŠธ | `custom` | 7์˜์—ญ A~F ๋“ฑ๊ธ‰ ๋ถ„์„ (์‹ค์ , ์ˆ˜์ต์„ฑ, ๊ฑด์ „์„ฑ, ํ˜„๊ธˆํ๋ฆ„, ์ง€๋ฐฐ๊ตฌ์กฐ, ๋ฆฌ์Šคํฌ, ๊ธฐํšŒ). | +| `sector` | ์„นํ„ฐ๋ถ„๋ฅ˜ | `custom` | WICS 11๋Œ€ ์„นํ„ฐ ๋ถ„๋ฅ˜. ๋Œ€๋ถ„๋ฅ˜/์ค‘๋ถ„๋ฅ˜ + ์„นํ„ฐ๋ณ„ ํŒŒ๋ผ๋ฏธํ„ฐ. | +| `rank` | ์‹œ์žฅ์ˆœ์œ„ | `custom` | ์ „์ฒด ์‹œ์žฅ ๋ฐ ์„นํ„ฐ ๋‚ด ๋งค์ถœ/์ž์‚ฐ/์„ฑ์žฅ๋ฅ  ์ˆœ์œ„. | +| `keywordTrend` | ํ‚ค์›Œ๋“œ ํŠธ๋ Œ๋“œ | `dataframe` | ๊ณต์‹œ ํ…์ŠคํŠธ ํ‚ค์›Œ๋“œ ๋นˆ๋„ ์ถ”์ด (topic ร— period ร— keyword). 54๊ฐœ ๋‚ด์žฅ ํ‚ค์›Œ๋“œ ๋˜๋Š” ์‚ฌ์šฉ์ž ์ง€์ •. | +| `news` | ๋‰ด์Šค | `dataframe` | ์ตœ๊ทผ ๋‰ด์Šค ์ˆ˜์ง‘ (KR: Google News ํ•œ๊ตญ์–ด, US: Google News ์˜์–ด). ๋‚ ์งœ/์ œ๋ชฉ/์ถœ์ฒ˜/URL. | +| `crossBorderPeers` | ๊ธ€๋กœ๋ฒŒ ํ”ผ์–ด | `custom` | WICSโ†’GICS ์„นํ„ฐ ๋งคํ•‘ ๊ธฐ๋ฐ˜ ๊ธ€๋กœ๋ฒŒ ํ”ผ์–ด ์ถ”์ฒœ. ํ•œ๊ตญ ์ข…๋ชฉ์˜ ๋ฏธ๊ตญ ๋™์ข… ๊ธฐ์—… ๋ฆฌ์ŠคํŠธ. | + +--- + +## ์ฃผ์š” ๋ฐ์ดํ„ฐ ํƒ€์ž… + +### RatioResult + +๋น„์œจ ๊ณ„์‚ฐ ๊ฒฐ๊ณผ (์ตœ์‹  ๋‹จ์ผ ์‹œ์ ). + +| ํ•„๋“œ | ํƒ€์ž… | ๊ธฐ๋ณธ๊ฐ’ | +|------|------|--------| +| `revenueTTM` | `float | None` | None | +| `operatingIncomeTTM` | `float | None` | None | +| `netIncomeTTM` | `float | None` | None | +| `operatingCashflowTTM` | `float | None` | None | +| `investingCashflowTTM` | `float | None` | None | +| `totalAssets` | `float | None` | None | +| `totalEquity` | `float | None` | None | +| `ownersEquity` | `float | None` | None | +| `totalLiabilities` | `float | None` | None | +| `currentAssets` | `float | None` | None | +| `currentLiabilities` | `float | None` | None | +| `cash` | `float | None` | None | +| `shortTermBorrowings` | `float | None` | None | +| `longTermBorrowings` | `float | None` | None | +| `bonds` | `float | None` | None | +| `grossProfit` | `float | None` | None | +| `costOfSales` | `float | None` | None | +| `sga` | `float | None` | None | +| `inventories` | `float | None` | None | +| `receivables` | `float | None` | None | +| `payables` | `float | None` | None | +| `tangibleAssets` | `float | None` | None | +| `intangibleAssets` | `float | None` | None | +| `retainedEarnings` | `float | None` | None | +| `profitBeforeTax` | `float | None` | None | +| `incomeTaxExpense` | `float | None` | None | +| `financeIncome` | `float | None` | None | +| `financeCosts` | `float | None` | None | +| `capex` | `float | None` | None | +| `dividendsPaid` | `float | None` | None | +| `depreciationExpense` | `float | None` | None | +| `noncurrentAssets` | `float | None` | None | +| `noncurrentLiabilities` | `float | None` | None | +| `roe` | `float | None` | None | +| `roa` | `float | None` | None | +| `roce` | `float | None` | None | +| `operatingMargin` | `float | None` | None | +| `netMargin` | `float | None` | None | +| `preTaxMargin` | `float | None` | None | +| `grossMargin` | `float | None` | None | +| `ebitdaMargin` | `float | None` | None | +| `costOfSalesRatio` | `float | None` | None | +| `sgaRatio` | `float | None` | None | +| `effectiveTaxRate` | `float | None` | None | +| `incomeQualityRatio` | `float | None` | None | +| `debtRatio` | `float | None` | None | +| `currentRatio` | `float | None` | None | +| `quickRatio` | `float | None` | None | +| `cashRatio` | `float | None` | None | +| `equityRatio` | `float | None` | None | +| `interestCoverage` | `float | None` | None | +| `netDebt` | `float | None` | None | +| `netDebtRatio` | `float | None` | None | +| `noncurrentRatio` | `float | None` | None | +| `workingCapital` | `float | None` | None | +| `revenueGrowth` | `float | None` | None | +| `operatingProfitGrowth` | `float | None` | None | +| `netProfitGrowth` | `float | None` | None | +| `assetGrowth` | `float | None` | None | +| `equityGrowthRate` | `float | None` | None | +| `revenueGrowth3Y` | `float | None` | None | +| `totalAssetTurnover` | `float | None` | None | +| `fixedAssetTurnover` | `float | None` | None | +| `inventoryTurnover` | `float | None` | None | +| `receivablesTurnover` | `float | None` | None | +| `payablesTurnover` | `float | None` | None | +| `operatingCycle` | `float | None` | None | +| `fcf` | `float | None` | None | +| `operatingCfMargin` | `float | None` | None | +| `operatingCfToNetIncome` | `float | None` | None | +| `operatingCfToCurrentLiab` | `float | None` | None | +| `capexRatio` | `float | None` | None | +| `dividendPayoutRatio` | `float | None` | None | +| `fcfToOcfRatio` | `float | None` | None | +| `roic` | `float | None` | None | +| `dupontMargin` | `float | None` | None | +| `dupontTurnover` | `float | None` | None | +| `dupontLeverage` | `float | None` | None | +| `debtToEbitda` | `float | None` | None | +| `ccc` | `float | None` | None | +| `dso` | `float | None` | None | +| `dio` | `float | None` | None | +| `dpo` | `float | None` | None | +| `piotroskiFScore` | `int | None` | None | +| `piotroskiMaxScore` | `int` | 9 | +| `altmanZScore` | `float | None` | None | +| `beneishMScore` | `float | None` | None | +| `sloanAccrualRatio` | `float | None` | None | +| `ohlsonOScore` | `float | None` | None | +| `ohlsonProbability` | `float | None` | None | +| `altmanZppScore` | `float | None` | None | +| `springateSScore` | `float | None` | None | +| `zmijewskiXScore` | `float | None` | None | +| `eps` | `float | None` | None | +| `bps` | `float | None` | None | +| `dps` | `float | None` | None | +| `per` | `float | None` | None | +| `pbr` | `float | None` | None | +| `psr` | `float | None` | None | +| `evEbitda` | `float | None` | None | +| `marketCap` | `float | None` | None | +| `sharesOutstanding` | `int | None` | None | +| `ebitdaEstimated` | `bool` | True | +| `currency` | `str` | KRW | +| `warnings` | `list` | [] | + +### InsightResult + +๋‹จ์ผ ์˜์—ญ ๋ถ„์„ ๊ฒฐ๊ณผ. + +| ํ•„๋“œ | ํƒ€์ž… | ๊ธฐ๋ณธ๊ฐ’ | +|------|------|--------| +| `grade` | `str` | | +| `summary` | `str` | | +| `details` | `list` | [] | +| `risks` | `list` | [] | +| `opportunities` | `list` | [] | + +### Anomaly + +์ด์ƒ์น˜ ํƒ์ง€ ๊ฒฐ๊ณผ. + +| ํ•„๋“œ | ํƒ€์ž… | ๊ธฐ๋ณธ๊ฐ’ | +|------|------|--------| +| `severity` | `str` | | +| `category` | `str` | | +| `text` | `str` | | +| `value` | `Optional` | None | + +### Flag + +๋ฆฌ์Šคํฌ/๊ธฐํšŒ ํ”Œ๋ž˜๊ทธ. + +| ํ•„๋“œ | ํƒ€์ž… | ๊ธฐ๋ณธ๊ฐ’ | +|------|------|--------| +| `level` | `str` | | +| `category` | `str` | | +| `text` | `str` | | + +### AnalysisResult + +์ข…ํ•ฉ ๋ถ„์„ ๊ฒฐ๊ณผ. + +| ํ•„๋“œ | ํƒ€์ž… | ๊ธฐ๋ณธ๊ฐ’ | +|------|------|--------| +| `corpName` | `str` | | +| `stockCode` | `str` | | +| `isFinancial` | `bool` | | +| `performance` | `InsightResult` | | +| `profitability` | `InsightResult` | | +| `health` | `InsightResult` | | +| `cashflow` | `InsightResult` | | +| `governance` | `InsightResult` | | +| `risk` | `InsightResult` | | +| `opportunity` | `InsightResult` | | +| `predictability` | `Optional` | None | +| `uncertainty` | `Optional` | None | +| `coreEarnings` | `Optional` | None | +| `anomalies` | `list` | [] | +| `distress` | `Optional` | None | +| `summary` | `str` | | +| `profile` | `str` | | + +### SectorInfo + +์„นํ„ฐ ๋ถ„๋ฅ˜ ๊ฒฐ๊ณผ. + +| ํ•„๋“œ | ํƒ€์ž… | ๊ธฐ๋ณธ๊ฐ’ | +|------|------|--------| +| `sector` | `Sector` | | +| `industryGroup` | `IndustryGroup` | | +| `confidence` | `float` | | +| `source` | `str` | | + +### SectorParams + +์„นํ„ฐ๋ณ„ ๋ฐธ๋ฅ˜์—์ด์…˜ ํŒŒ๋ผ๋ฏธํ„ฐ. + +| ํ•„๋“œ | ํƒ€์ž… | ๊ธฐ๋ณธ๊ฐ’ | +|------|------|--------| +| `discountRate` | `float` | | +| `growthRate` | `float` | | +| `perMultiple` | `float` | | +| `pbrMultiple` | `float` | | +| `evEbitdaMultiple` | `float` | | +| `label` | `str` | | +| `description` | `str` | | + +### RankInfo + +๋‹จ์ผ ์ข…๋ชฉ์˜ ๋žญํฌ ์ •๋ณด. + +| ํ•„๋“œ | ํƒ€์ž… | ๊ธฐ๋ณธ๊ฐ’ | +|------|------|--------| +| `stockCode` | `str` | | +| `corpName` | `str` | | +| `sector` | `str` | | +| `industryGroup` | `str` | | +| `revenue` | `Optional` | None | +| `totalAssets` | `Optional` | None | +| `revenueGrowth3Y` | `Optional` | None | +| `revenueRank` | `Optional` | None | +| `revenueTotal` | `int` | 0 | +| `revenueRankInSector` | `Optional` | None | +| `revenueSectorTotal` | `int` | 0 | +| `assetRank` | `Optional` | None | +| `assetTotal` | `int` | 0 | +| `assetRankInSector` | `Optional` | None | +| `assetSectorTotal` | `int` | 0 | +| `growthRank` | `Optional` | None | +| `growthTotal` | `int` | 0 | +| `growthRankInSector` | `Optional` | None | +| `growthSectorTotal` | `int` | 0 | +| `sizeClass` | `str` | | diff --git a/src/dartlab/STATUS.md b/src/dartlab/STATUS.md new file mode 100644 index 0000000000000000000000000000000000000000..d11e1e048e7af4df57c7833b73d10e76d4ee843d --- /dev/null +++ b/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 ์„ค์ • diff --git a/src/dartlab/__init__.py b/src/dartlab/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..f38d0485a19eacff79437cbad88b027560bb3b8e --- /dev/null +++ b/src/dartlab/__init__.py @@ -0,0 +1,1008 @@ +"""DART ๊ณต์‹œ ๋ฐ์ดํ„ฐ ํ™œ์šฉ ๋ผ์ด๋ธŒ๋Ÿฌ๋ฆฌ.""" + +import sys +from importlib.metadata import PackageNotFoundError +from importlib.metadata import version as _pkg_version + +from dartlab import ai as llm +from dartlab import config, core +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, searchName +from dartlab.providers.dart.company import Company as _DartEngineCompany +from dartlab.providers.dart.openapi.dart import Dart, 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(keyword: str): + """์ข…๋ชฉ ๊ฒ€์ƒ‰ (KR + US ํ†ตํ•ฉ). + + Example:: + + import dartlab + dartlab.search("์‚ผ์„ฑ์ „์ž") + dartlab.search("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 listing(market: str | None = None): + """์ „์ฒด ์ƒ์žฅ๋ฒ•์ธ ๋ชฉ๋ก. + + Args: + market: "KR" ๋˜๋Š” "US". None์ด๋ฉด KR ๊ธฐ๋ณธ. + + Example:: + + import dartlab + dartlab.listing() # KR ์ „์ฒด + dartlab.listing("US") # US ์ „์ฒด (ํ–ฅํ›„) + """ + if market and market.upper() == "US": + try: + from dartlab.providers.edgar.company import Company as _US + + return _US.listing() + except (ImportError, AttributeError, NotImplementedError): + raise NotImplementedError("US listing์€ ์•„์ง ์ง€์›๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค") + return _DartEngineCompany.listing() + + +def collect( + *codes: str, + categories: list[str] | None = None, + incremental: bool = True, +) -> dict[str, dict[str, int]]: + """์ง€์ • ์ข…๋ชฉ DART ๋ฐ์ดํ„ฐ ์ˆ˜์ง‘ (OpenAPI). ๋ฉ€ํ‹ฐํ‚ค ์‹œ ๋ณ‘๋ ฌ. + + 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 ๋ฐ์ดํ„ฐ ์ˆ˜์ง‘. DART_API_KEY(S) ํ•„์š”. ๋ฉ€ํ‹ฐํ‚ค ์‹œ ๋ณ‘๋ ฌ. + + 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์—์„œ ์ „์ฒด ์‹œ์žฅ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค์šด๋กœ๋“œ. pip install dartlab[hf] ํ•„์š”. + + scanAccount, screen, digest ๋“ฑ ์ „์‚ฌ(ๅ…จ็คพ) ๋ถ„์„ ๊ธฐ๋Šฅ์€ ๋กœ์ปฌ์— ์ „์ฒด ๋ฐ์ดํ„ฐ๊ฐ€ ์žˆ์–ด์•ผ ๋™์ž‘ํ•ฉ๋‹ˆ๋‹ค. + ์ด ํ•จ์ˆ˜๋กœ ์นดํ…Œ๊ณ ๋ฆฌ๋ณ„ ์ „์ฒด ๋ฐ์ดํ„ฐ๋ฅผ ์‚ฌ์ „ ๋‹ค์šด๋กœ๋“œํ•˜์„ธ์š”. + + Args: + category: "finance" (์žฌ๋ฌด ~600MB), "docs" (๊ณต์‹œ ~8GB), "report" (๋ณด๊ณ ์„œ ~320MB). + forceUpdate: True๋ฉด ์ด๋ฏธ ์žˆ๋Š” ํŒŒ์ผ๋„ ์ตœ์‹ ์œผ๋กœ ๊ฐฑ์‹ . + + Examples:: + + import dartlab + dartlab.downloadAll("finance") # ์žฌ๋ฌด ์ „์ฒด โ€” scanAccount/screen/benchmark ๋“ฑ์— ํ•„์š” + dartlab.downloadAll("report") # ๋ณด๊ณ ์„œ ์ „์ฒด โ€” governance/workforce/capital/debt์— ํ•„์š” + dartlab.downloadAll("docs") # ๊ณต์‹œ ์ „์ฒด โ€” digest/signal์— ํ•„์š” (๋Œ€์šฉ๋Ÿ‰ ~8GB) + """ + from dartlab.core.dataLoader import downloadAll as _downloadAll + + _downloadAll(category, forceUpdate=forceUpdate) + + +def checkFreshness(stockCode: str, *, forceCheck: bool = False): + """์ข…๋ชฉ์˜ ๋กœ์ปฌ ๋ฐ์ดํ„ฐ๊ฐ€ ์ตœ์‹ ์ธ์ง€ DART API๋กœ ํ™•์ธ. + + 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 network(): + """ํ•œ๊ตญ ์ƒ์žฅ์‚ฌ ์ „์ฒด ๊ด€๊ณ„ ์ง€๋„. + + Example:: + + import dartlab + dartlab.network().show() # ๋ธŒ๋ผ์šฐ์ €์—์„œ ์ „์ฒด ๋„คํŠธ์›Œํฌ + """ + from dartlab.market.network import build_graph, export_full + from dartlab.tools.network import render_network + + data = build_graph() + full = export_full(data) + return render_network( + full["nodes"], + full["edges"], + "ํ•œ๊ตญ ์ƒ์žฅ์‚ฌ ๊ด€๊ณ„ ๋„คํŠธ์›Œํฌ", + ) + + +def governance(): + """ํ•œ๊ตญ ์ƒ์žฅ์‚ฌ ์ „์ฒด ์ง€๋ฐฐ๊ตฌ์กฐ ์Šค์บ”. + + Example:: + + import dartlab + df = dartlab.governance() + """ + from dartlab.market.governance import scan_governance + + return scan_governance() + + +def workforce(): + """ํ•œ๊ตญ ์ƒ์žฅ์‚ฌ ์ „์ฒด ์ธ๋ ฅ/๊ธ‰์—ฌ ์Šค์บ”. + + Example:: + + import dartlab + df = dartlab.workforce() + """ + from dartlab.market.workforce import scan_workforce + + return scan_workforce() + + +def capital(): + """ํ•œ๊ตญ ์ƒ์žฅ์‚ฌ ์ „์ฒด ์ฃผ์ฃผํ™˜์› ์Šค์บ”. + + Example:: + + import dartlab + df = dartlab.capital() + """ + from dartlab.market.capital import scan_capital + + return scan_capital() + + +def debt(): + """ํ•œ๊ตญ ์ƒ์žฅ์‚ฌ ์ „์ฒด ๋ถ€์ฑ„ ๊ตฌ์กฐ ์Šค์บ”. + + Example:: + + import dartlab + df = dartlab.debt() + """ + from dartlab.market.debt import scan_debt + + return scan_debt() + + +def screen(preset: str = "๊ฐ€์น˜์ฃผ"): + """์‹œ์žฅ ์Šคํฌ๋ฆฌ๋‹ โ€” ํ”„๋ฆฌ์…‹ ๊ธฐ๋ฐ˜ ์ข…๋ชฉ ํ•„ํ„ฐ. + + Args: + preset: ํ”„๋ฆฌ์…‹ ์ด๋ฆ„ ("๊ฐ€์น˜์ฃผ", "์„ฑ์žฅ์ฃผ", "ํ„ด์–ด๋ผ์šด๋“œ", "ํ˜„๊ธˆ๋ถ€์ž", + "๊ณ ์œ„ํ—˜", "์ž๋ณธ์ž ์‹", "์†Œํ˜•๊ณ ์ˆ˜์ต", "๋Œ€ํ˜•์•ˆ์ •"). + + Example:: + + import dartlab + df = dartlab.screen("๊ฐ€์น˜์ฃผ") # ROEโ‰ฅ10, ๋ถ€์ฑ„โ‰ค100 ๋“ฑ + df = dartlab.screen("๊ณ ์œ„ํ—˜") # ๋ถ€์ฑ„โ‰ฅ200, ICR<3 + """ + from dartlab.analysis.comparative.rank.screen import screen as _screen + + return _screen(preset) + + +def benchmark(): + """์„นํ„ฐ๋ณ„ ํ•ต์‹ฌ ๋น„์œจ ๋ฒค์น˜๋งˆํฌ (P10, median, P90). + + Example:: + + import dartlab + bm = dartlab.benchmark() # ์„นํ„ฐ ร— ๋น„์œจ ์ •์ƒ ๋ฒ”์œ„ + """ + from dartlab.analysis.comparative.rank.screen import benchmark as _benchmark + + return _benchmark() + + +def signal(keyword: str | None = None): + """์„œ์ˆ ํ˜• ๊ณต์‹œ ์‹œ์žฅ ์‹œ๊ทธ๋„ โ€” ํ‚ค์›Œ๋“œ ํŠธ๋ Œ๋“œ ํƒ์ง€. + + Args: + keyword: ํŠน์ • ํ‚ค์›Œ๋“œ๋งŒ ํ•„ํ„ฐ. None์ด๋ฉด ์ „์ฒด 48๊ฐœ ํ‚ค์›Œ๋“œ. + + Example:: + + import dartlab + df = dartlab.signal() # ์ „์ฒด ํ‚ค์›Œ๋“œ ํŠธ๋ Œ๋“œ + df = dartlab.signal("AI") # AI ํ‚ค์›Œ๋“œ ์—ฐ๋„๋ณ„ ์ถ”์ด + """ + from dartlab.market.signal import scan_signal + + return scan_signal(keyword) + + +def news(query: str, *, market: str = "KR", days: int = 30): + """๊ธฐ์—… ๋‰ด์Šค ์ˆ˜์ง‘. + + Args: + query: ๊ธฐ์—…๋ช… ๋˜๋Š” ํ‹ฐ์ปค. + market: "KR" ๋˜๋Š” "US". + days: ์ตœ๊ทผ N์ผ. + + Example:: + + import dartlab + dartlab.news("์‚ผ์„ฑ์ „์ž") + dartlab.news("AAPL", market="US") + """ + from dartlab.gather import getDefaultGather + + return getDefaultGather().news(query, market=market, days=days) + + +def price( + stockCode: str, *, market: str = "KR", start: str | None = None, end: str | None = None, snapshot: bool = False +): + """์ฃผ๊ฐ€ ์‹œ๊ณ„์—ด (๊ธฐ๋ณธ 1๋…„ OHLCV) ๋˜๋Š” ์Šค๋ƒ…์ƒท. + + Example:: + + import dartlab + dartlab.price("005930") # 1๋…„ OHLCV ์‹œ๊ณ„์—ด + dartlab.price("005930", start="2020-01-01") # ๊ธฐ๊ฐ„ ์ง€์ • + dartlab.price("005930", snapshot=True) # ํ˜„์žฌ๊ฐ€ ์Šค๋ƒ…์ƒท + """ + from dartlab.gather import getDefaultGather + + return getDefaultGather().price(stockCode, market=market, start=start, end=end, snapshot=snapshot) + + +def consensus(stockCode: str, *, market: str = "KR"): + """์ปจ์„ผ์„œ์Šค โ€” ๋ชฉํ‘œ๊ฐ€, ํˆฌ์ž์˜๊ฒฌ. + + Example:: + + import dartlab + dartlab.consensus("005930") + dartlab.consensus("AAPL", market="US") + """ + from dartlab.gather import getDefaultGather + + return getDefaultGather().consensus(stockCode, market=market) + + +def flow(stockCode: str, *, market: str = "KR"): + """์ˆ˜๊ธ‰ ์‹œ๊ณ„์—ด โ€” ์™ธ๊ตญ์ธ/๊ธฐ๊ด€ ๋งค๋งค ๋™ํ–ฅ (KR ์ „์šฉ). + + Example:: + + import dartlab + dartlab.flow("005930") + # [{"date": "20260325", "foreignNet": -6165053, "institutionNet": 2908773, ...}, ...] + """ + from dartlab.gather import getDefaultGather + + return getDefaultGather().flow(stockCode, market=market) + + +def macro(market: str = "KR", indicator: str | None = None, *, start: str | None = None, end: str | None = None): + """๊ฑฐ์‹œ ์ง€ํ‘œ ์‹œ๊ณ„์—ด โ€” ECOS(KR) / FRED(US). + + ์ธ์ž ์—†์œผ๋ฉด ์นดํƒˆ๋กœ๊ทธ ์ „์ฒด ์ง€ํ‘œ๋ฅผ wide DataFrame์œผ๋กœ ๋ฐ˜ํ™˜. + + Example:: + + import dartlab + dartlab.macro() # KR ์ „์ฒด ์ง€ํ‘œ wide DF (22๊ฐœ) + dartlab.macro("US") # US ์ „์ฒด ์ง€ํ‘œ wide DF (50๊ฐœ) + dartlab.macro("CPI") # CPI (์ž๋™ KR ๊ฐ์ง€) + dartlab.macro("FEDFUNDS") # ์—ฐ๋ฐฉ๊ธฐ๊ธˆ๊ธˆ๋ฆฌ (์ž๋™ US ๊ฐ์ง€) + dartlab.macro("KR", "CPI") # ๋ช…์‹œ์  KR + CPI + dartlab.macro("US", "SP500") # ๋ช…์‹œ์  US + S&P500 + """ + from dartlab.gather import getDefaultGather + + return getDefaultGather().macro(market, indicator, start=start, end=end) + + +def crossBorderPeers(stockCode: str, *, topK: int = 5): + """ํ•œ๊ตญ ์ข…๋ชฉ์˜ ๊ธ€๋กœ๋ฒŒ ํ”ผ์–ด ์ถ”์ฒœ (WICSโ†’GICS ๋งคํ•‘). + + Args: + stockCode: ํ•œ๊ตญ ์ข…๋ชฉ์ฝ”๋“œ. + topK: ๋ฐ˜ํ™˜ํ•  ํ”ผ์–ด ์ˆ˜. + + Example:: + + import dartlab + dartlab.crossBorderPeers("005930") # โ†’ ["AAPL", "MSFT", ...] + """ + from dartlab.analysis.comparative.peer.discover import crossBorderPeers as _cb + + return _cb(stockCode, topK=topK) + + +def setup(provider: str | None = None): + """AI provider ์„ค์ • ์•ˆ๋‚ด + ์ธํ„ฐ๋ž™ํ‹ฐ๋ธŒ ์„ค์ •. + + Args: + provider: ํŠน์ • provider ์„ค์ •. 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 ( + provider_guide, + providers_status, + resolve_alias, + ) + + if provider is None: + print(providers_status()) + return + + provider = resolve_alias(provider) + + if provider == "oauth-codex": + _setup_oauth_interactive() + elif provider == "openai": + _setup_openai_interactive() + else: + print(provider_guide(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_openai_interactive(): + """๋…ธํŠธ๋ถ์—์„œ OpenAI API ํ‚ค ์ธ๋ผ์ธ ์„ค์ •.""" + import os + + from dartlab.core.ai.guide import provider_guide + + existing_key = os.environ.get("OPENAI_API_KEY") + if existing_key: + print(f"\n โœ“ OPENAI_API_KEY ํ™˜๊ฒฝ๋ณ€์ˆ˜๊ฐ€ ์„ค์ •๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. (sk-...{existing_key[-4:]})\n") + return + + print(provider_guide("openai")) + print() + + try: + from getpass import getpass + + key = getpass(" API ํ‚ค ์ž…๋ ฅ (Enter๋กœ ๊ฑด๋„ˆ๋›ฐ๊ธฐ): ").strip() + if key: + llm.configure(provider="openai", api_key=key) + print("\n โœ“ OpenAI API ํ‚ค๊ฐ€ ์„ค์ •๋˜์—ˆ์Šต๋‹ˆ๋‹ค.\n") + else: + print("\n ๊ฑด๋„ˆ๋›ฐ์—ˆ์Šต๋‹ˆ๋‹ค.\n") + except (EOFError, KeyboardInterrupt): + print("\n ๊ฑด๋„ˆ๋›ฐ์—ˆ์Šต๋‹ˆ๋‹ค.\n") + + +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, + **kwargs, +): + """LLM์—๊ฒŒ ๊ธฐ์—…์— ๋Œ€ํ•ด ์งˆ๋ฌธ. + + 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: ์ „์ฒด ๋‹ต๋ณ€ ํ…์ŠคํŠธ. (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 + + msg = no_provider_message() + print(msg) + raise RuntimeError("AI provider๊ฐ€ ์„ค์ •๋˜์ง€ ์•Š์•˜์Šต๋‹ˆ๋‹ค. dartlab.setup()์„ ์‹คํ–‰ํ•˜์„ธ์š”.") + provider = detected + + 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: + raise ValueError( + f"์ข…๋ชฉ์„ ์ฐพ์„ ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค: '{args[0]}'\n" + "์ข…๋ชฉ๋ช… ๋˜๋Š” ์ข…๋ชฉ์ฝ”๋“œ๋ฅผ ํฌํ•จํ•ด ์ฃผ์„ธ์š”.\n" + "์˜ˆ: dartlab.ask('์‚ผ์„ฑ์ „์ž ์žฌ๋ฌด๊ฑด์ „์„ฑ ๋ถ„์„ํ•ด์ค˜')" + ) + elif len(args) == 0: + raise TypeError("์งˆ๋ฌธ์„ ์ž…๋ ฅํ•ด ์ฃผ์„ธ์š”. ์˜ˆ: dartlab.ask('์‚ผ์„ฑ์ „์ž ๋ถ„์„ํ•ด์ค˜')") + else: + raise TypeError(f"์ธ์ž๋Š” 1~2๊ฐœ๋งŒ ํ—ˆ์šฉ๋ฉ๋‹ˆ๋‹ค (๋ฐ›์€ ์ˆ˜: {len(args)})") + + if raw: + return _ask( + company, + question, + include=include, + exclude=exclude, + provider=provider, + model=model, + stream=stream, + reflect=reflect, + pattern=pattern, + **kwargs, + ) + + if not stream: + return _ask( + company, + question, + include=include, + exclude=exclude, + provider=provider, + model=model, + stream=False, + reflect=reflect, + pattern=pattern, + **kwargs, + ) + + gen = _ask( + company, + question, + include=include, + exclude=exclude, + provider=provider, + model=model, + stream=True, + reflect=reflect, + pattern=pattern, + **kwargs, + ) + return _auto_stream(gen) + + +def chat( + codeOrName: str, + question: str, + *, + provider: str | None = None, + model: str | None = None, + max_turns: int = 5, + on_tool_call=None, + on_tool_result=None, + **kwargs, +) -> str: + """์—์ด์ „ํŠธ ๋ชจ๋“œ: LLM์ด ๋„๊ตฌ๋ฅผ ์„ ํƒํ•˜์—ฌ ์‹ฌํ™” ๋ถ„์„. + + Args: + codeOrName: ์ข…๋ชฉ์ฝ”๋“œ, ํšŒ์‚ฌ๋ช…, ๋˜๋Š” US ticker. + question: ์งˆ๋ฌธ ํ…์ŠคํŠธ. + provider: LLM provider. + model: ๋ชจ๋ธ override. + max_turns: ์ตœ๋Œ€ ๋„๊ตฌ ํ˜ธ์ถœ ๋ฐ˜๋ณต ํšŸ์ˆ˜. + + Example:: + + import dartlab + dartlab.chat("005930", "๋ฐฐ๋‹น ์ถ”์„ธ๋ฅผ ๋ถ„์„ํ•˜๊ณ  ์ด์ƒ ์ง•ํ›„๋ฅผ ์ฐพ์•„์ค˜") + """ + from dartlab.ai.runtime.standalone import chat as _chat + + company = Company(codeOrName) + 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(): + """๋กœ๋“œ๋œ ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ชฉ๋ก ๋ฐ˜ํ™˜. + + 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 ํ›„ ์žฌ์‹œ์ž‘ ์—†์ด ์ฆ‰์‹œ ์ธ์‹. + + 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() + + +def audit(codeOrName: str): + """๊ฐ์‚ฌ Red Flag ๋ถ„์„. + + Example:: + + import dartlab + dartlab.audit("005930") + """ + c = Company(codeOrName) + from dartlab.analysis.financial.insight.pipeline import analyzeAudit + + return analyzeAudit(c) + + +def forecast(codeOrName: str, *, horizon: int = 3): + """๋งค์ถœ ์•™์ƒ๋ธ” ์˜ˆ์ธก. + + Example:: + + import dartlab + dartlab.forecast("005930") + """ + c = Company(codeOrName) + from dartlab.analysis.forecast.revenueForecast import forecastRevenue + + ts = c.finance.timeseries + if ts is None: + return None + series = ts[0] if isinstance(ts, tuple) else ts + currency = getattr(c, "currency", "KRW") + return forecastRevenue( + series, + stockCode=getattr(c, "stockCode", None), + sectorKey=getattr(c, "sectorKey", None), + market=getattr(c, "market", "KR"), + horizon=horizon, + currency=currency, + ) + + +def valuation(codeOrName: str, *, shares: int | None = None): + """์ข…ํ•ฉ ๋ฐธ๋ฅ˜์—์ด์…˜ (DCF + DDM + ์ƒ๋Œ€๊ฐ€์น˜). + + Example:: + + import dartlab + dartlab.valuation("005930") + """ + c = Company(codeOrName) + from dartlab.analysis.valuation.valuation import fullValuation + + ts = c.finance.timeseries + if ts is None: + return None + series = ts[0] if isinstance(ts, tuple) else ts + currency = getattr(c, "currency", "KRW") + if shares is None: + profile = getattr(c, "profile", None) + if profile: + shares = getattr(profile, "sharesOutstanding", None) + if shares: + shares = int(shares) + return fullValuation(series, shares=shares, currency=currency) + + +def insights(codeOrName: str): + """7์˜์—ญ ๋“ฑ๊ธ‰ ๋ถ„์„. + + Example:: + + import dartlab + dartlab.insights("005930") + """ + c = Company(codeOrName) + from dartlab.analysis.financial.insight import analyze + + return analyze(c.stockCode, company=c) + + +def simulation(codeOrName: str, *, scenarios: list[str] | None = None): + """๊ฒฝ์ œ ์‹œ๋‚˜๋ฆฌ์˜ค ์‹œ๋ฎฌ๋ ˆ์ด์…˜. + + Example:: + + import dartlab + dartlab.simulation("005930") + """ + c = Company(codeOrName) + from dartlab.analysis.forecast.simulation import simulateAllScenarios + + ts = c.finance.timeseries + if ts is None: + return None + series = ts[0] if isinstance(ts, tuple) else ts + return simulateAllScenarios( + series, + sectorKey=getattr(c, "sectorKey", None), + scenarios=scenarios, + ) + + +def research(codeOrName: str, *, sections: list[str] | None = None, includeMarket: bool = True): + """์ข…ํ•ฉ ๊ธฐ์—…๋ถ„์„ ๋ฆฌํฌํŠธ. + + Example:: + + import dartlab + dartlab.research("005930") + """ + c = Company(codeOrName) + from dartlab.analysis.financial.research import generateResearch + + return generateResearch(c, sections=sections, includeMarket=includeMarket) + + +def groupHealth(): + """๊ทธ๋ฃน์‚ฌ ๊ฑด์ „์„ฑ ๋ถ„์„ โ€” ๋„คํŠธ์›Œํฌ ร— ์žฌ๋ฌด๋น„์œจ ๊ต์ฐจ. + + Returns: + (summary, weakLinks) ํŠœํ”Œ. + + Example:: + + import dartlab + summary, weakLinks = dartlab.groupHealth() + """ + from dartlab.market.network.health import groupHealth as _groupHealth + + return _groupHealth() + + +def scanAccount( + snakeId: str, + *, + market: str = "dart", + sjDiv: str | None = None, + fsPref: str = "CFS", + annual: bool = False, +): + """์ „์ข…๋ชฉ ๋‹จ์ผ ๊ณ„์ • ์‹œ๊ณ„์—ด. + + Args: + snakeId: ๊ณ„์ • ์‹๋ณ„์ž. ์˜๋ฌธ("sales") ๋˜๋Š” ํ•œ๊ธ€("๋งค์ถœ์•ก") ๋ชจ๋‘ ๊ฐ€๋Šฅ. + market: "dart" (ํ•œ๊ตญ, ๊ธฐ๋ณธ) ๋˜๋Š” "edgar" (๋ฏธ๊ตญ). + sjDiv: ์žฌ๋ฌด์ œํ‘œ ๊ตฌ๋ถ„ ("IS", "BS", "CF"). None์ด๋ฉด ์ž๋™ ๊ฒฐ์ •. (dart๋งŒ) + fsPref: ์—ฐ๊ฒฐ/๋ณ„๋„ ์šฐ์„ ์ˆœ์œ„ ("CFS"=์—ฐ๊ฒฐ ์šฐ์„ , "OFS"=๋ณ„๋„ ์šฐ์„ ). (dart๋งŒ) + annual: True๋ฉด ์—ฐ๊ฐ„ (๊ธฐ๋ณธ False=๋ถ„๊ธฐ๋ณ„ standalone). + + Example:: + + import dartlab + dartlab.scanAccount("๋งค์ถœ์•ก") # DART ๋ถ„๊ธฐ๋ณ„ + dartlab.scanAccount("๋งค์ถœ์•ก", annual=True) # DART ์—ฐ๊ฐ„ + dartlab.scanAccount("sales", market="edgar") # EDGAR ๋ถ„๊ธฐ๋ณ„ + dartlab.scanAccount("total_assets", market="edgar", annual=True) + """ + if market == "edgar": + from dartlab.providers.edgar.finance.scanAccount import scanAccount as _edgarScan + + return _edgarScan(snakeId, annual=annual) + + from dartlab.providers.dart.finance.scanAccount import scanAccount as _scan + + return _scan(snakeId, sjDiv=sjDiv, fsPref=fsPref, annual=annual) + + +def scanRatio( + ratioName: str, + *, + market: str = "dart", + fsPref: str = "CFS", + annual: bool = False, +): + """์ „์ข…๋ชฉ ๋‹จ์ผ ์žฌ๋ฌด๋น„์œจ ์‹œ๊ณ„์—ด. + + Args: + ratioName: ๋น„์œจ ์‹๋ณ„์ž ("roe", "operatingMargin", "debtRatio" ๋“ฑ). + market: "dart" (ํ•œ๊ตญ, ๊ธฐ๋ณธ) ๋˜๋Š” "edgar" (๋ฏธ๊ตญ). + fsPref: ์—ฐ๊ฒฐ/๋ณ„๋„ ์šฐ์„ ์ˆœ์œ„. (dart๋งŒ) + annual: True๋ฉด ์—ฐ๊ฐ„ (๊ธฐ๋ณธ False=๋ถ„๊ธฐ๋ณ„). + + Example:: + + import dartlab + dartlab.scanRatio("roe") # DART ๋ถ„๊ธฐ๋ณ„ + dartlab.scanRatio("operatingMargin", annual=True) # DART ์—ฐ๊ฐ„ + dartlab.scanRatio("roe", market="edgar", annual=True) # EDGAR ์—ฐ๊ฐ„ + """ + if market == "edgar": + from dartlab.providers.edgar.finance.scanAccount import scanRatio as _edgarRatio + + return _edgarRatio(ratioName, annual=annual) + + from dartlab.providers.dart.finance.scanAccount import scanRatio as _ratio + + return _ratio(ratioName, fsPref=fsPref, annual=annual) + + +def scanRatioList(): + """์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ๋น„์œจ ๋ชฉ๋ก. + + Example:: + + import dartlab + dartlab.scanRatioList() + """ + from dartlab.providers.dart.finance.scanAccount import scanRatioList as _list + + return _list() + + +def digest( + *, + sector: str | None = None, + top_n: int = 20, + format: str = "dataframe", + stock_codes: list[str] | None = None, + verbose: bool = False, +): + """์‹œ์žฅ ์ „์ฒด ๊ณต์‹œ ๋ณ€ํ™” ๋‹ค์ด์ œ์ŠคํŠธ. + + ๋กœ์ปฌ์— ๋‹ค์šด๋กœ๋“œ๋œ docs ๋ฐ์ดํ„ฐ๋ฅผ ์ˆœํšŒํ•˜๋ฉฐ ์ค‘์š”๋„ ๋†’์€ ๋ณ€ํ™”๋ฅผ ์ง‘๊ณ„ํ•œ๋‹ค. + + Args: + sector: ์„นํ„ฐ ํ•„ํ„ฐ (์˜ˆ: "๋ฐ˜๋„์ฒด"). None์ด๋ฉด ์ „์ฒด. + top_n: ์ƒ์œ„ N๊ฐœ. + format: "dataframe", "markdown", "json". + stock_codes: ์ง์ ‘ ์ข…๋ชฉ์ฝ”๋“œ ๋ชฉ๋ก ์ง€์ •. + verbose: ์ง„ํ–‰ ์ƒํ™ฉ ์ถœ๋ ฅ. + + Example:: + + import dartlab + dartlab.digest() # ์ „์ฒด ์‹œ์žฅ + dartlab.digest(sector="๋ฐ˜๋„์ฒด") # ์„นํ„ฐ๋ณ„ + dartlab.digest(format="markdown") # ๋งˆํฌ๋‹ค์šด ์ถœ๋ ฅ + """ + from dartlab.analysis.accounting.watch.digest import build_digest + from dartlab.analysis.accounting.watch.scanner import scan_market + + scan_df = scan_market( + sector=sector, + top_n=top_n, + stock_codes=stock_codes, + verbose=verbose, + ) + + if format == "dataframe": + return scan_df + + title = f"{sector} ์„นํ„ฐ ๋ณ€ํ™” ๋‹ค์ด์ œ์ŠคํŠธ" if sector else None + return build_digest(scan_df, format=format, title=title, top_n=top_n) + + +class _Module(sys.modules[__name__].__class__): + """dartlab.verbose / dartlab.dataDir / dartlab.chart|table|text ํ”„๋ก์‹œ.""" + + @property + def verbose(self): + return config.verbose + + @verbose.setter + def verbose(self, value): + config.verbose = value + + @property + def dataDir(self): + return config.dataDir + + @dataDir.setter + def dataDir(self, value): + config.dataDir = str(value) + + def __getattr__(self, name): + if name in ("chart", "table", "text"): + import importlib + + mod = importlib.import_module(f"dartlab.tools.{name}") + setattr(self, name, mod) + return mod + raise AttributeError(f"module 'dartlab' has no attribute {name!r}") + + +sys.modules[__name__].__class__ = _Module + + +__all__ = [ + "Company", + "Dart", + "Fred", + "OpenDart", + "OpenEdgar", + "config", + "core", + "engines", + "llm", + "ask", + "chat", + "setup", + "search", + "listing", + "collect", + "collectAll", + "downloadAll", + "network", + "screen", + "benchmark", + "signal", + "news", + "crossBorderPeers", + "audit", + "forecast", + "valuation", + "insights", + "simulation", + "governance", + "workforce", + "capital", + "debt", + "groupHealth", + "research", + "digest", + "scanAccount", + "scanRatio", + "scanRatioList", + "plugins", + "reload_plugins", + "verbose", + "dataDir", + "getKindList", + "codeToName", + "nameToCode", + "searchName", + "fuzzySearch", + "chart", + "table", + "text", + "Review", + "SelectResult", + "ChartResult", +] diff --git a/src/dartlab/ai/DEV.md b/src/dartlab/ai/DEV.md new file mode 100644 index 0000000000000000000000000000000000000000..50aa3452cd55234d9f87cae2ed46d189686b5f4a --- /dev/null +++ b/src/dartlab/ai/DEV.md @@ -0,0 +1,224 @@ +# AI Engine Development Guide + +## Source Of Truth + +- ๋ฐ์ดํ„ฐ source-of-truth: `src/dartlab/core/registry.py` +- AI capability source-of-truth: `src/dartlab/core/capabilities.py` + +## ํ˜„์žฌ ๊ตฌ์กฐ ์›์น™ + +- `core.analyze()`๊ฐ€ AI ์˜ค์ผ€์ŠคํŠธ๋ ˆ์ด์…˜์˜ ๋‹จ์ผ ์ง„์ž…์ ์ด๋‹ค. +- `tools/registry.py`๋Š” capability ์ •์˜๋ฅผ runtime์— ๋ฐ”์ธ๋”ฉํ•˜๋Š” ๋ ˆ์ด์–ด๋‹ค. +- `server/streaming.py`, `mcp/__init__.py`, UI SSE client๋Š” capability ๊ฒฐ๊ณผ๋ฅผ ์†Œ๋น„ํ•˜๋Š” adapter๋‹ค. +- Svelte UI๋Š” source-of-truth๊ฐ€ ์•„๋‹ˆ๋ผ render sink๋‹ค. +- OpenDART ์ตœ๊ทผ ๊ณต์‹œ๋ชฉ๋ก retrieval๋„ `core.analyze()`์—์„œ company ์œ ๋ฌด์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ ๊ฐ™์€ ๊ฒฝ๋กœ๋กœ ํ•ฉ๋ฅ˜ํ•œ๋‹ค. + +## ํŒจํ‚ค์ง€ ๊ตฌ์กฐ + +- `runtime/` + - `core.py`: ์˜ค์ผ€์ŠคํŠธ๋ ˆ์ดํ„ฐ + - `events.py`: canonical/legacy ์ด๋ฒคํŠธ ๊ณ„์•ฝ + - `pipeline.py`: pre-compute pipeline + - `post_processing.py`: navigate/validation/auto-artifact ํ›„์ฒ˜๋ฆฌ + - `standalone.py`: public ask/chat bridge + - `validation.py`: ์ˆซ์ž ๊ฒ€์ฆ +- `conversation/` + - `dialogue.py`, `history.py`, `intent.py`, `focus.py`, `prompts.py` + - `suggestions.py`: ํšŒ์‚ฌ ์ƒํƒœ ๊ธฐ๋ฐ˜ ์ถ”์ฒœ ์งˆ๋ฌธ ์ƒ์„ฑ + - `data_ready.py`: docs/finance/report ๊ฐ€์šฉ์„ฑ ์š”์•ฝ +- `context/` + - `builder.py`: structured context build + - `snapshot.py`: headline snapshot + - `company_adapter.py`: facade mismatch adapter + - `dartOpenapi.py`: OpenDART filing intent ํŒŒ์‹ฑ + recent filing context +- `tools/` + - `registry.py`: tool/capability binding (`useSuperTools` ํ”Œ๋ž˜๊ทธ๋กœ ๋ชจ๋“œ ์ „ํ™˜) + - `runtime.py`: tool execution runtime + - `selector.py`: capability ๊ธฐ๋ฐ˜ ๋„๊ตฌ ์„ ํƒ + Super Tool ์ „์šฉ prompt ๋ถ„๊ธฐ + - `plugin.py`: external tool plugin bridge + - `coding.py`: coding runtime bridge + - `recipes.py`: ์งˆ๋ฌธ ์œ ํ˜•๋ณ„ ์„ ํ–‰ ๋ถ„์„ ๋ ˆ์‹œํ”ผ + - `routeHint.py`: ํ‚ค์›Œ๋“œโ†’๋„๊ตฌ ๋งคํ•‘ (Super Tool ๋ชจ๋“œ์—์„œ deprecated) + - `superTools/`: **7๊ฐœ Super Tool dispatcher** (explore/finance/analyze/market/openapi/system/chart) + - `defaults/`: ๊ธฐ์กด 101๊ฐœ ๋„๊ตฌ ๋“ฑ๋ก (๋ ˆ๊ฑฐ์‹œ ๋ชจ๋“œ์—์„œ ์‚ฌ์šฉ) +- `providers/support/` + - `codex_cli.py`, `cli_setup.py`, `ollama_setup.py`, `oauth_token.py` + - provider ๊ตฌํ˜„์ด ์ง์ ‘ ์“ฐ๋Š” CLI/OAuth ๋ณด์กฐ ๊ณ„์ธต + +๋ฃจํŠธ shim ๋ชจ๋“ˆ(`core.py`, `tools_registry.py`, `dialogue.py` ๋“ฑ)์€ ์ œ๊ฑฐ๋˜์—ˆ๋‹ค. ์ƒˆ ์ฝ”๋“œ๋Š” ๋ฐ˜๋“œ์‹œ ํ•˜์œ„ ํŒจํ‚ค์ง€ ๊ฒฝ๋กœ(`runtime/`, `conversation/`, `context/`, `tools/`, `providers/support/`)๋ฅผ ์ง์ ‘ importํ•œ๋‹ค. + +## Super Tool ์•„ํ‚คํ…์ฒ˜ (2026-03-25) + +101๊ฐœ ๋„๊ตฌ๋ฅผ 7๊ฐœ Super Tool dispatcher๋กœ ํ†ตํ•ฉ. ollama(์†Œํ˜• ๋ชจ๋ธ)์—์„œ ์ž๋™ ํ™œ์„ฑํ™”. + +### ๋ชจ๋ธ ์š”๊ตฌ์‚ฌํ•ญ +- **์ตœ์†Œ**: tool calling ์ง€์› + 14B ํŒŒ๋ผ๋ฏธํ„ฐ ์ด์ƒ (์˜ˆ: qwen3:14b, llama3.1:8b-instruct) +- **๊ถŒ์žฅ**: GPT-4o, Claude Sonnet ์ด์ƒ โ€” tool calling + ํ•œ๊ตญ์–ด + ๋ณตํ•ฉ ํŒŒ๋ผ๋ฏธํ„ฐ ๋™์‹œ ์ฒ˜๋ฆฌ +- **๋ถ€์ ํ•ฉ**: 8B ์ดํ•˜ ์†Œํ˜• ๋ชจ๋ธ (qwen3:4b/8b) โ€” action dispatch ํŒจํ„ด์„ ์ดํ•ดํ•˜์ง€ ๋ชปํ•จ, hallucination ๋‹ค๋ฐœ +- ์‹คํ—˜ 009 ๊ฒ€์ฆ ๊ฒฐ๊ณผ: qwen3:4b tool ์ •ํ™•๋„ 33%, qwen3:8b 0%. ์†Œํ˜• ๋ชจ๋ธ์€ tool calling AI ๋ถ„์„์— ์‚ฌ์šฉ ๋ถˆ๊ฐ€. + +### ํ™œ์„ฑํ™” ์กฐ๊ฑด +- **๋ชจ๋“  provider์—์„œ Super Tool ๊ธฐ๋ณธ ํ™œ์„ฑํ™”** (`_useSuperTools = True`) +- `build_tool_runtime(company, useSuperTools=False)`๋กœ ๋ ˆ๊ฑฐ์‹œ ๋ชจ๋“œ ์ˆ˜๋™ ์ „ํ™˜ ๊ฐ€๋Šฅ +- Route Hint(`routeHint.py`)๋Š” deprecated โ€” Super Tool enum description์ด ๋Œ€์ฒด + +### 7๊ฐœ Super Tool +| Tool | ํ†ตํ•ฉ ๋Œ€์ƒ | action enum | +|------|----------|-------------| +| `explore` | show_topic, list_topics, trace, diff, info, filings, search | 7 | +| `finance` | get_data, list_modules, ratios, growth, yoy, anomalies, report, search | 8 | +| `analyze` | insight, sector, rank, esg, valuation, changes, audit | 7 | +| `market` | price, consensus, history, screen | 4 | +| `openapi` | dartCall, searchFilings, capabilities | 3 | +| `system` | spec, features, searchCompany, dataStatus, suggest | 5 | +| `chart` | navigate, chart | 2 | + +### ๋™์  enum +- `explore.target`: company.topics์—์„œ ์ถ”์ถœ (์‚ผ์„ฑ์ „์ž ๊ธฐ์ค€ 53๊ฐœ) + ํ•œ๊ตญ์–ด ๋ผ๋ฒจ +- `finance.module`: scan_available_modules์—์„œ ์ถ”์ถœ (9๊ฐœ) + ํ•œ๊ตญ์–ด ๋ผ๋ฒจ +- `finance.apiType`: company.report.availableApiTypes์—์„œ ์ถ”์ถœ (24๊ฐœ) + ํ•œ๊ตญ์–ด ๋ผ๋ฒจ +- enum description์— `topicLabels.py`์˜ ํ•œ๊ตญ์–ด ๋ผ๋ฒจ๊ณผ aliases ํฌํ•จ + +### ํ•œ๊ตญ์–ด ๋ผ๋ฒจ source of truth +- `core/topicLabels.py`: 70๊ฐœ topic ร— ํ•œ๊ตญ์–ด ๋ผ๋ฒจ + ๊ฒ€์ƒ‰ aliases +- UI์˜ `topicLabels.js`์™€ ๋™์ผ ๋งคํ•‘ + AI์šฉ aliases ์ถ”๊ฐ€ + +## UI Action ๊ณ„์•ฝ + +- canonical payload๋Š” `UiAction`์ด๋‹ค. +- render payload๋Š” `ViewSpec` + `WidgetSpec` schema๋ฅผ ๊ธฐ์ค€์œผ๋กœ ํ•œ๋‹ค. +- widget id(`chart`, `comparison`, `insight_dashboard`, `table`)๋Š” UI widget registry์— ๋“ฑ๋ก๋œ ๊ฒƒ๋งŒ ์‚ฌ์šฉํ•œ๋‹ค. +- ํ—ˆ์šฉ action: + - `navigate` + - `render` + - `update` + - `toast` +- canonical SSE UI ์ด๋ฒคํŠธ๋Š” `ui_action` ํ•˜๋‚˜๋งŒ ์œ ์ง€ํ•œ๋‹ค. +- auto artifact๋„ ๋ณ„๋„ chart ์ด๋ฒคํŠธ๊ฐ€ ์•„๋‹ˆ๋ผ canonical `render` UI action์œผ๋กœ ์ฃผ์ž…ํ•œ๋‹ค. +- Svelte ์ธก AI bridge/helper๋Š” `src/dartlab/ui/src/lib/ai/`์— ๋‘”๋‹ค. `App.svelte`๋Š” provider/profile ๋™๊ธฐํ™”์™€ stream wiring๋งŒ ์—ฐ๊ฒฐํ•˜๋Š” shell๋กœ ์œ ์ง€ํ•œ๋‹ค. + +## Provider Surface + +- ๊ณต์‹ GPT ๊ตฌ๋… ๊ณ„์ • ๊ฒฝ๋กœ๋Š” ๋‘ ๊ฐœ๋‹ค. + - `codex`: Codex CLI ๋กœ๊ทธ์ธ ๊ธฐ๋ฐ˜ + - `oauth-codex`: ChatGPT OAuth ์ง์ ‘ ์—ฐ๊ฒฐ ๊ธฐ๋ฐ˜ +- ๊ณต๊ฐœ provider surface๋Š” `codex`, `oauth-codex`, `openai`, `ollama`, `custom`๋งŒ ์œ ์ง€ํ•œ๋‹ค. +- `claude` provider๋Š” public surface์—์„œ ์ œ๊ฑฐ๋˜์—ˆ๋‹ค. ๋‚จ์€ Claude ๊ด€๋ จ ์ฝ”๋“œ๋Š” legacy/internal ์šฉ๋„๋กœ๋งŒ ์ทจ๊ธ‰ํ•œ๋‹ค. +- provider alias(`chatgpt`, `chatgpt-oauth`)๋Š” ๋” ์ด์ƒ ๊ณต๊ฐœ/ํ˜ธํ™˜ surface์— ๋‘์ง€ ์•Š๋Š”๋‹ค. +- ask/CLI/server/UI๋Š” ๊ฐ™์€ provider ๋ฌธ์ž์—ด์„ ๊ณต์œ ํ•ด์•ผ ํ•˜๋ฉฐ, ์ƒˆ GPT ๊ฒฝ๋กœ๋ฅผ ์ถ”๊ฐ€ํ•  ๋•Œ๋Š” ์ด ๋ฌธ์„œ์™€ `core/ai/providers.py`, `server/api/ai.py`, `ui/src/App.svelte`, `cli/context.py`๋ฅผ ๊ฐ™์ด ๊ฐฑ์‹ ํ•œ๋‹ค. + +## Shared Profile + +- AI ์„ค์ • source-of-truth๋Š” `~/.dartlab/ai_profile.json`๊ณผ ๊ณตํ†ต secret store๋‹ค. +- `dartlab.llm.configure()`๋Š” ๋ฉ”๋ชจ๋ฆฌ ์ „์šฉ setter๊ฐ€ ์•„๋‹ˆ๋ผ shared profile writer๋‹ค. +- profile schema๋Š” `defaultProvider + roles(analysis, summary, coding, ui_control)` ๊ตฌ์กฐ๋‹ค. +- UI๋Š” provider/model์„ localStorage์— ์ €์žฅํ•˜์ง€ ์•Š๊ณ  `/api/ai/profile`๊ณผ `/api/ai/profile/events`๋ฅผ ํ†ตํ•ด ๋™๊ธฐํ™”ํ•œ๋‹ค. +- API key๋Š” profile JSON์— ์ €์žฅํ•˜์ง€ ์•Š๊ณ  secret store์—๋งŒ ์ €์žฅํ•œ๋‹ค. +- OAuth ํ† ํฐ๋„ legacy `oauth_token.json` ๋Œ€์‹  ๊ณตํ†ต secret store๋กœ ์ด๋™ํ•œ๋‹ค. +- Ollama preload/probe๋Š” ์„ ํƒ provider๊ฐ€ `ollama`์ผ ๋•Œ๋งŒ ์ ๊ทน์ ์œผ๋กœ ์ˆ˜ํ–‰ํ•œ๋‹ค. ๋‹ค๋ฅธ provider๊ฐ€ ์„ ํƒ๋œ ์ƒํƒœ์—์„œ๋Š” ์ƒํƒœ ์กฐํšŒ๋„ lazy probe๊ฐ€ ๊ธฐ๋ณธ์ด๋‹ค. +- OpenDART ํ‚ค๋Š” provider secret store๋กœ ํก์ˆ˜ํ•˜์ง€ ์•Š๊ณ  ํ”„๋กœ์ ํŠธ `.env`๋ฅผ source-of-truth๋กœ ์œ ์ง€ํ•œ๋‹ค. + +## Company Adapter ์›์น™ + +- AI ๋ ˆ์ด์–ด๋Š” `company.ratios` ๊ฐ™์€ facade surface๋ฅผ ์ง์ ‘ ์‹ ๋ขฐํ•˜์ง€ ์•Š๋Š”๋‹ค. +- headline ratio / ratio series๋Š” `src/dartlab/ai/context/company_adapter.py`๋กœ๋งŒ ์ ‘๊ทผํ•œ๋‹ค. +- facade์™€ ์—”์ง„ surface mismatch๋ฅผ ๋ฐœ๊ฒฌํ•˜๋ฉด AI ์ฝ”๋“œ ๊ณณ๊ณณ์—์„œ ๋ถ„๊ธฐํ•˜์ง€ ๋ง๊ณ  adapter์— ํก์ˆ˜ํ•œ๋‹ค. + +## Ask Context ์ •์ฑ… + +- ๊ธฐ๋ณธ `ask`๋Š” cheap-first๋‹ค. ์งˆ๋ฌธ์— ๋งž๋Š” ์ตœ์†Œ source๋งŒ ์ฝ๊ณ , `docs/finance/report` ์ „์ฒด ์„ ๋กœ๋”ฉ์„ ๊ธˆ์ง€ํ•œ๋‹ค. +- ์ผ๋ฐ˜ `ask`์˜ ๊ธฐ๋ณธ context tier๋Š” `focused`๋‹ค. `full` tier๋Š” `report_mode=True`์ผ ๋•Œ๋งŒ ํ—ˆ์šฉํ•œ๋‹ค. +- tool-capable provider(`openai`, `ollama`, `custom`)๋งŒ `use_tools=True`์ผ ๋•Œ `skeleton` tier๋ฅผ ์‚ฌ์šฉํ•œ๋‹ค. +- `oauth-codex` ๊ธฐ๋ณธ ask๋Š” ๋” ์ด์ƒ `full`๋กœ ๋–จ์–ด์ง€์ง€ ์•Š๋Š”๋‹ค. +- `auto diff`๋Š” `full` tier์—์„œ๋งŒ ์ž๋™ ๊ณ„์‚ฐํ•œ๋‹ค. ๊ธฐ๋ณธ ask์—์„œ๋Š” `company.diff()`๋ฅผ ์„ ํ–‰ ํ˜ธ์ถœํ•˜์ง€ ์•Š๋Š”๋‹ค. +- ์งˆ๋ฌธ ํ•ด์„์€ route-first๊ฐ€ ์•„๋‹ˆ๋ผ **candidate-module-first**๋‹ค. ๋จผ์ € `sections / notes / report / finance` ํ›„๋ณด๋ฅผ ๋™์‹œ์— ๋ชจ์œผ๊ณ , ์‹ค์ œ ์กด์žฌํ•˜๋Š” ๋ชจ๋“ˆ๋งŒ ์ปจํ…์ŠคํŠธ์— ์‹ฃ๋Š”๋‹ค. +- `costByNature`, `rnd`, `segments`์ฒ˜๋Ÿผ sections topic์ด ์•„๋‹ˆ์–ด๋„ direct/notes ๊ฒฝ๋กœ๋กœ ์กด์žฌํ•˜๋ฉด `ask`๊ฐ€ ์šฐ์„  ํšŒ์ˆ˜ํ•œ๋‹ค. +- ์ผ๋ฐ˜ `ask`์—์„œ ํฌํ•จ๋œ ๋ชจ๋“ˆ์ด ์žˆ์œผ๋ฉด `"๋ฐ์ดํ„ฐ ์—†์Œ"`์ด๋ผ๊ณ  ๋‹ตํ•˜๋ฉด ์‹คํŒจ๋กœ ๋ณธ๋‹ค. false-unavailable ๋ฐฉ์ง€๊ฐ€ ๊ธฐ๋ณธ ๊ณ„์•ฝ์ด๋‹ค. +- tool calling์ด ๋น„ํ™œ์„ฑํ™”๋œ ask์—์„œ๋Š” `show_topic()` ๊ฐ™์€ ํ˜ธ์ถœ ๊ณ„ํš์„ ๋ฌธ์žฅ์œผ๋กœ ์ถœ๋ ฅํ•˜์ง€ ์•Š๋Š”๋‹ค. ์ด๋ฏธ ์ œ๊ณต๋œ ์ปจํ…์ŠคํŠธ๋งŒ์œผ๋กœ ๋ฐ”๋กœ ๋‹ตํ•˜๊ณ , ๋ชจํ˜ธํ•  ๋•Œ๋งŒ ํ•œ ๋ฌธ์žฅ ํ™•์ธ ์งˆ๋ฌธ์„ ํ•œ๋‹ค. +- **๋ถ„๊ธฐ ์งˆ๋ฌธ ์ •์ฑ…**: "๋ถ„๊ธฐ", "๋ถ„๊ธฐ๋ณ„", "quarterly", "QoQ", "์ „๋ถ„๊ธฐ" ๋“ฑ ๋ถ„๊ธฐ ํ‚ค์›Œ๋“œ๊ฐ€ ๊ฐ์ง€๋˜๋ฉด: + - route๋ฅผ `hybrid`๋กœ ์ „ํ™˜ํ•˜์—ฌ sections + finance ์–‘์ชฝ ๋ชจ๋‘ ํฌํ•จํ•œ๋‹ค. + - `company.timeseries`์—์„œ IS/CF ๋ถ„๊ธฐ๋ณ„ standalone ๋ฐ์ดํ„ฐ๋ฅผ ์ตœ๊ทผ 8๋ถ„๊ธฐ๋งŒ ์ถ”์ถœํ•˜์—ฌ context์— ์ฃผ์ž…ํ•œ๋‹ค. + - `fsSummary`๋ฅผ sections exclude ๋ชฉ๋ก์—์„œ ์ผ์‹œ ํ•ด์ œํ•˜์—ฌ ๋ถ„๊ธฐ ์š”์•ฝ๋„ ํฌํ•จํ•œ๋‹ค. + - response_contract์— ๋ถ„๊ธฐ ๋ฐ์ดํ„ฐ ํ™œ์šฉ ์ง€์‹œ๋ฅผ ์ถ”๊ฐ€ํ•œ๋‹ค. +- **finance route sections ๋ณด์กฐ ์ •์ฑ…**: route=finance์ผ ๋•Œ๋„ `businessStatus`, `businessOverview` ์ค‘ ์กด์žฌํ•˜๋Š” topic 1๊ฐœ๋ฅผ ๊ฒฝ๋Ÿ‰ outline์œผ๋กœ ์ฃผ์ž…ํ•œ๋‹ค. "์™œ ์ด์ต๋ฅ ์ด ๋ณ€ํ–ˆ๋Š”์ง€" ๊ฐ™์€ ๋งฅ๋ฝ์„ LLM์ด ์„ค๋ช…ํ•  ์ˆ˜ ์žˆ๊ฒŒ ํ•œ๋‹ค. +- **context budget**: focused=10000, full=16000. ๋ถ„๊ธฐ ๋ฐ์ดํ„ฐ + sections ๋ณด์กฐ๋ฅผ ์ˆ˜์šฉํ•  ์ˆ˜ ์žˆ๋Š” ํฌ๊ธฐ. + +## Persona Eval ๋ฃจํ”„ + +- ask ์žฅ๊ธฐ ๊ฐœ์„ ์˜ ๊ธฐ๋ณธ ๋‹จ์œ„๋Š” **์‹ค์‚ฌ์šฉ ๋กœ๊ทธ๊ฐ€ ์•„๋‹ˆ๋ผ curated ์งˆ๋ฌธ ์„ธํŠธ replay**๋‹ค. +- source-of-truth๋Š” `src/dartlab/ai/eval/personaCases.json`์ด๋‹ค. +- ์‚ฌ๋žŒ ๊ฒ€์ˆ˜ ์ด๋ ฅ source-of-truth๋Š” `src/dartlab/ai/eval/reviewLog/.jsonl`์ด๋‹ค. +- persona ์ถ•์€ ์ตœ์†Œ `assistant`, `data_manager`, `operator`, `installer`, `research_gather`, `accountant`, `business_owner`, `investor`, `analyst`๋ฅผ ์œ ์ง€ํ•œ๋‹ค. +- ๊ฐ case๋Š” ์งˆ๋ฌธ๋งŒ ์ €์žฅํ•˜์ง€ ์•Š๋Š”๋‹ค. + - `expectedRoute` + - `expectedModules` + - `mustInclude` + - `mustNotSay` + - `forbiddenUiTerms` + - `allowedClarification` + - `expectedFollowups` + - `groundTruthFacts` +- ์ƒˆ ask ์‹คํŒจ๋Š” ๋ฐ”๋กœ ํ”„๋กฌํ”„ํŠธ hotfix๋กœ ๋ฎ์ง€ ์•Š๊ณ  ๋จผ์ € ์•„๋ž˜๋กœ ๋ถ„๋ฅ˜ํ•œ๋‹ค. + - `routing_failure` + - `retrieval_failure` + - `false_unavailable` + - `generation_failure` + - `ui_wording_failure` + - `data_gap` + - `runtime_error` +- replay runner source-of-truth๋Š” `src/dartlab/ai/eval/replayRunner.py`๋‹ค. +- ์‹ค์ œ replay๋ฅผ ๊ฒ€ํ† ํ•  ๋•Œ๋Š” ๊ฒฐ๊ณผ๋งŒ ๋‚จ๊ธฐ์ง€ ์•Š๊ณ  ๋ฐ˜๋“œ์‹œ `reviewedAt / effectiveness / improvementActions / notes`๋ฅผ ๊ฐ™์ด ๋‚จ๊ธด๋‹ค. +- review log๋Š” persona๋ณ„๋กœ ๋ถ„๋ฆฌํ•œ๋‹ค. + - `reviewLog/accountant.jsonl` + - `reviewLog/investor.jsonl` + - `reviewLog/analyst.jsonl` +- ๋‹ค์Œ ํšŒ์ฐจ replay๋Š” ๊ฐ™์€ persona ํŒŒ์ผ์„ ์ด์–ด์„œ ๋ณด๊ณ , `ํšจ๊ณผ์ ์ด์—ˆ๋Š”์ง€`์™€ `์ด๋ฒˆ ๊ฐœ์„ ์œผ๋กœ ์ค„์—ฌ์•ผ ํ•  failure type`์„ ๊ฐ™์ด ์ ๋Š”๋‹ค. +- ๊ฐœ์„  ๋ฃจํ”„๋Š” ํ•ญ์ƒ `์งˆ๋ฌธ ์„ธํŠธ ์ถ”๊ฐ€ โ†’ replay โ†’ failure taxonomy ํ™•์ธ โ†’ AI fix vs DartLab core fix ๋ถ„๋ฆฌ โ†’ ํšŒ๊ท€ ์žฌ์‹คํ–‰` ์ˆœ์„œ๋กœ ๊ฐ„๋‹ค. +- "์žฅ๊ธฐ ํ•™์Šต"์€ ๋ชจ๋ธ ํ•™์Šต์ด ์•„๋‹ˆ๋ผ ์ด replay/backlog ๋ฃจํ”„๋ฅผ ๋œปํ•œ๋‹ค. +- replay์—์„œ ๋ฐ˜๋ณต ์‹คํŒจํ•œ ์งˆ๋ฌธ ๋ฌถ์Œ์€ generic ambiguity๋กœ ๋‚จ๊ธฐ์ง€ ๋ง๊ณ  ๊ฐ•์ œ ๊ทœ์น™์œผ๋กœ ์Šน๊ฒฉํ•œ๋‹ค. + - `๋ถ€์‹ค ์ง•ํ›„`๋ฅ˜ ์งˆ๋ฌธ โ†’ `finance` route ๊ณ ์ • + - `์˜์—…์ด์ต๋ฅ  + ๋น„์šฉ ๊ตฌ์กฐ + ์‚ฌ์—… ๋ณ€ํ™”` โ†’ `IS + costByNature + businessOverview/productService` ๊ฐ•์ œ hybrid, clarification ๊ธˆ์ง€ + - `์ตœ๊ทผ ๊ณต์‹œ + ์‚ฌ์—… ๊ตฌ์กฐ ๋ณ€ํ™”` โ†’ `disclosureChanges`์— `businessOverview/productService`๋ฅผ ๊ฐ™์ด ํšŒ์ˆ˜ +- **groundTruthFacts๋Š” ์ˆ˜๋™ ํ•˜๋“œ์ฝ”๋”ฉ์ด ์•„๋‹ˆ๋ผ `truthHarvester`๋กœ ์ž๋™ ์ƒ์„ฑํ•œ๋‹ค.** + - `scripts/harvestEvalTruth.py`๋กœ ๋ฐฐ์น˜ ์‹คํ–‰, `--severity critical,high`๋ถ€ํ„ฐ ์šฐ์„  ์ฑ„์›€ + - finance ์—”์ง„์—์„œ IS/BS/CF ํ•ต์‹ฌ ๊ณ„์ • + ratios๋ฅผ ์ž๋™ ์ถ”์ถœ + - `truthAsOf` ๋‚ ์งœ๋กœ ๋ฐ์ดํ„ฐ ์‹œ์ ์„ ๊ธฐ๋ก +- **๊ฒฐ์ •๋ก ์  ๊ฒ€์ฆ(๋ผ์šฐํŒ…/๋ชจ๋“ˆ)์€ LLM ํ˜ธ์ถœ ์—†์ด CI์—์„œ ๋งค ์ปค๋ฐ‹ ๊ฒ€์ฆํ•œ๋‹ค.** + - `tests/test_eval_deterministic.py` โ€” personaCases.json์˜ expectedRoute/๋ชจ๋“ˆ/๊ตฌ์กฐ ๋ฌด๊ฒฐ์„ฑ ๊ฒ€์ฆ + - personaCases์— ์ผ€์ด์Šค๋ฅผ ์ถ”๊ฐ€ํ•˜๋ฉด ์ž๋™์œผ๋กœ ๊ฒฐ์ •๋ก ์  ํ…Œ์ŠคํŠธ๋„ ์‹คํ–‰๋จ + - `@pytest.mark.unit` โ†’ `test-lock.sh` 1๋‹จ๊ณ„์—์„œ ์‹คํ–‰ +- **๋ฐฐ์น˜ replay๋Š” `scripts/runEvalBatch.py`๋กœ ์ž๋™ํ™”ํ•œ๋‹ค.** + - `--provider`, `--model`, `--severity`, `--persona`, `--compare latest` ํ•„ํ„ฐ + - ๊ฒฐ๊ณผ๋Š” `eval/batchResults/` JSONL๋กœ ์ €์žฅ, ์ด์ „ ๋ฐฐ์น˜์™€ ํšŒ๊ท€ ๋น„๊ต ์ง€์› +- **replaySuite()๋Š” Company ์บ์‹œ 3๊ฐœ ์ œํ•œ์œผ๋กœ OOM์„ ๋ฐฉ์ง€ํ•œ๋‹ค.** + - 4๋ฒˆ์งธ Company ๋กœ๋“œ ์‹œ ๊ฐ€์žฅ ์˜ค๋ž˜๋œ ์บ์‹œ ์ œ๊ฑฐ + `gc.collect()` + +## User Language ์›์น™ + +- UI ๊ธฐ๋ณธ surface์—์„œ๋Š” internal module/method ์ด๋ฆ„์„ ์ง์ ‘ ๋…ธ์ถœํ•˜์ง€ ์•Š๋Š”๋‹ค. +- ask ๋‚ด๋ถ€ debug/meta์™€ eval/log์—์„œ๋Š” raw module ์ด๋ฆ„์„ ์œ ์ง€ํ•ด๋„ ๋œ๋‹ค. +- runtime `meta` / `done`์—๋Š” raw `includedModules`์™€ ํ•จ๊ป˜ ์‚ฌ์šฉ์ž์šฉ `includedEvidence` label์„ ๊ฐ™์ด ์‹ค์–ด ๋ณด๋‚ธ๋‹ค. +- UI evidence panel, transparency badges, modal title์€ ์‚ฌ์šฉ์ž์šฉ evidence label์„ ์šฐ์„  ์‚ฌ์šฉํ•œ๋‹ค. +- tool ์ด๋ฆ„๋„ UI์—์„œ๋Š” ์‚ฌ์šฉ์ž ํ–‰๋™ ๊ธฐ์ค€ ๋ฌธ๊ตฌ๋กœ ๋ณด์—ฌ์ค€๋‹ค. + - ์˜ˆ: `list_live_filings` โ†’ `์‹ค์‹œ๊ฐ„ ๊ณต์‹œ ๋ชฉ๋ก ์กฐํšŒ` + - ์˜ˆ: `get_data` โ†’ `์žฌ๋ฌดยท๊ณต์‹œ ๋ฐ์ดํ„ฐ ์กฐํšŒ` +- ask ๋ณธ๋ฌธ๋„ ๊ธฐ๋ณธ์ ์œผ๋กœ ์‚ฌ์šฉ์ž ์–ธ์–ด๋ฅผ ์“ด๋‹ค. + - `IS/BS/CF/ratios/TTM` โ†’ `์†์ต๊ณ„์‚ฐ์„œ/์žฌ๋ฌด์ƒํƒœํ‘œ/ํ˜„๊ธˆํ๋ฆ„ํ‘œ/์žฌ๋ฌด๋น„์œจ/์ตœ๊ทผ 4๋ถ„๊ธฐ ํ•ฉ์‚ฐ` + - `costByNature/businessOverview/productService` โ†’ `์„ฑ๊ฒฉ๋ณ„ ๋น„์šฉ ๋ถ„๋ฅ˜/์‚ฌ์—…์˜ ๊ฐœ์š”/์ œํ’ˆยท์„œ๋น„์Šค` + - `topic/period/source` โ†’ `ํ•ญ๋ชฉ/์‹œ์ /์ถœ์ฒ˜` + +## Sections First Retrieval + +- `sections`๋Š” ๊ธฐ๋ณธ์ ์œผ๋กœ โ€œ๋ณธ๋ฌธ ๋ฉ์–ด๋ฆฌโ€๊ฐ€ ์•„๋‹ˆ๋ผ โ€œretrieval indexโ€๋กœ ์“ด๋‹ค. +- sections ๊ณ„์—ด ์งˆ๋ฌธ์€ `topics() -> outline(topic) -> contextSlices -> raw docs sections block` ์ˆœ์„œ๋กœ ์ขํžŒ๋‹ค. +- `contextSlices`๊ฐ€ ask์˜ ๊ธฐ๋ณธ evidence layer๋‹ค. `outline(topic)`๋Š” ์ธ๋ฑ์Šค/์ปค๋ฒ„๋ฆฌ์ง€ ํ™•์ธ์šฉ์ด๊ณ , ์‹ค์ œ ๊ทผ๊ฑฐ ๋ฌธ์žฅ์€ `contextSlices`์—์„œ ๋จผ์ € ํšŒ์ˆ˜ํ•œ๋‹ค. +- `retrievalBlocks/raw sections`๋Š” `contextSlices`๋งŒ์œผ๋กœ ๊ทผ๊ฑฐ๊ฐ€ ๋ถ€์กฑํ•  ๋•Œ๋งŒ ์ถ”๊ฐ€๋กœ ์—ฐ๋‹ค. +- ์ผ๋ฐ˜ ์žฌ๋ฌด ์งˆ๋ฌธ์—์„œ๋Š” `sections`, `report`, `insights`, `change summary`๋ฅผ ์ž๋™์œผ๋กœ ๋ถ™์ด์ง€ ์•Š๋Š”๋‹ค. +- ๋ฐฐ๋‹น/์ง์›/์ตœ๋Œ€์ฃผ์ฃผ/๊ฐ์‚ฌ์ฒ˜๋Ÿผ ๋ช…์‹œ์ ์ธ report ์งˆ๋ฌธ์—์„œ๋งŒ report pivot/context๋ฅผ ์˜ฌ๋ฆฐ๋‹ค. + +## Follow-up Continuity + +- ํ›„์† ํ„ด์ด `์ตœ๊ทผ 5๊ฐœ๋…„`, `๊ทธ๋Ÿผ`, `์ด์–ด์„œ`์ฒ˜๋Ÿผ ์งง์€ ๊ธฐ๊ฐ„/์—ฐ์† ์งˆ๋ฌธ์ด๋ฉด ์ง์ „ assistant `includedModules`๋ฅผ ์ด์–ด๋ฐ›์•„ ๊ฐ™์€ ๋ถ„์„ ์ถ•์„ ์œ ์ง€ํ•œ๋‹ค. +- ์ด ์ƒ์†์€ ์•„๋ฌด ์งˆ๋ฌธ์—๋‚˜ ์ ์šฉํ•˜์ง€ ์•Š๊ณ  `follow_up` ๋ชจ๋“œ + ๊ธฐ๊ฐ„/์—ฐ์† ํžŒํŠธ๊ฐ€ ์žˆ์„ ๋•Œ๋งŒ ์ ์šฉํ•œ๋‹ค. +- ๊ฐ•ํ•œ direct intent ์งˆ๋ฌธ(`์„ฑ๊ฒฉ๋ณ„ ๋น„์šฉ`, `์ธ๊ฑด๋น„`, `๊ฐ๊ฐ€์ƒ๊ฐ`, `๋ฌผ๋ฅ˜๋น„`)์€ clarification ์—†์ด ๋ฐ”๋กœ `costByNature`๋ฅผ ํšŒ์ˆ˜ํ•œ๋‹ค. +- `costByNature` ๊ฐ™์€ ๋‹ค๊ธฐ๊ฐ„ direct module์ด ํฌํ•จ๋˜๋ฉด ๊ธฐ๊ฐ„์ด ๋น„์–ด ์žˆ์–ด๋„ ์ตœ์‹  ์‹œ์ ๊ณผ ์ตœ๊ทผ ์ถ”์„ธ๋ฅผ ๋จผ์ € ๋‹ตํ•œ๋‹ค. ์—ฐ๋„ ๊ธฐ์ค€์„ ๋จผ์ € ๋‹ค์‹œ ๋ฌป์ง€ ์•Š๋Š”๋‹ค. diff --git a/src/dartlab/ai/STATUS.md b/src/dartlab/ai/STATUS.md new file mode 100644 index 0000000000000000000000000000000000000000..b0d7785f851cb9f3778de3b8f328ed1e53963e6a --- /dev/null +++ b/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 ํ™˜๊ฒฝ์ด์Šˆ) diff --git a/src/dartlab/ai/__init__.py b/src/dartlab/ai/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..d1c099e2c02b5bcc7ef15cba8ab3b0b506fe6485 --- /dev/null +++ b/src/dartlab/ai/__init__.py @@ -0,0 +1,119 @@ +"""LLM ๊ธฐ๋ฐ˜ ๊ธฐ์—…๋ถ„์„ ์—”์ง„.""" + +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 import aiParser as ai +from dartlab.ai.tools.plugin import get_plugin_registry, tool + +__all__ = ["configure", "get_config", "status", "LLMConfig", "LLMResponse", "ai", "tool", "get_plugin_registry"] diff --git a/src/dartlab/ai/agent.py b/src/dartlab/ai/agent.py new file mode 100644 index 0000000000000000000000000000000000000000..3b86faf41dc8683ac5e2fc5b309f74142c37e704 --- /dev/null +++ b/src/dartlab/ai/agent.py @@ -0,0 +1,30 @@ +"""ํ˜ธํ™˜ shim โ€” ์‹ค์ œ ๊ตฌํ˜„์€ runtime/agent.py๋กœ ์ด๋™๋จ. + +๊ธฐ์กด import ๊ฒฝ๋กœ๋ฅผ ์œ ์ง€ํ•˜๊ธฐ ์œ„ํ•œ re-export. +""" + +from dartlab.ai.runtime.agent import ( # noqa: F401 + AGENT_SYSTEM_ADDITION, + PLANNING_PROMPT, + _reflect_on_answer, + agent_loop, + agent_loop_planning, + agent_loop_stream, + build_agent_system_addition, +) +from dartlab.ai.tools.selector import selectTools # noqa: F401 + +# ํ•˜์œ„ํ˜ธํ™˜: _select_tools โ†’ selectTools ๋ž˜ํผ +_select_tools = selectTools + +__all__ = [ + "AGENT_SYSTEM_ADDITION", + "PLANNING_PROMPT", + "_reflect_on_answer", + "_select_tools", + "agent_loop", + "agent_loop_planning", + "agent_loop_stream", + "build_agent_system_addition", + "selectTools", +] diff --git a/src/dartlab/ai/aiParser.py b/src/dartlab/ai/aiParser.py new file mode 100644 index 0000000000000000000000000000000000000000..41afc7400d3e5f97c711d33b0ba859faee63ca1a --- /dev/null +++ b/src/dartlab/ai/aiParser.py @@ -0,0 +1,500 @@ +"""AI ๋ณด์กฐ ํŒŒ์‹ฑ โ€” ๊ธฐ์กด ํŒŒ์„œ ์ถœ๋ ฅ์„ AI๊ฐ€ ํ›„์ฒ˜๋ฆฌํ•˜์—ฌ ๊ฐ•ํ™”. + +๊ธฐ์กด ํŒŒ์„œ๋ฅผ ๊ต์ฒดํ•˜์ง€ ์•Š๋Š”๋‹ค. ํŒŒ์„œ๊ฐ€ ์ƒ์‚ฐํ•œ DataFrame/ํ…์ŠคํŠธ๋ฅผ +LLM์ด ํ•ด์„ยท์š”์•ฝยท๊ฒ€์ฆํ•˜๋Š” ํ›„์ฒ˜๋ฆฌ ๋ ˆ์ด์–ด. + +๊ธฐ์กด LLM provider ์‹œ์Šคํ…œ ์žฌ์‚ฌ์šฉ: dartlab.llm.configure() ์„ค์ •์„ ๊ทธ๋Œ€๋กœ ํ™œ์šฉ. + +์‚ฌ์šฉ๋ฒ•:: + + import dartlab + dartlab.llm.configure(provider="ollama", model="llama3.2") + + c = dartlab.Company("005930") + + # ์š”์•ฝ + dartlab.llm.ai.summarize(c.IS) + + # ๊ณ„์ • ํ•ด์„ + dartlab.llm.ai.interpret_accounts(c.BS) + + # ์ด์ƒ์น˜ ํƒ์ง€ + dartlab.llm.ai.detect_anomalies(c.dividend) + + # ํ…์ŠคํŠธ ๋ถ„๋ฅ˜ + dartlab.llm.ai.classify_text(c.mdna) +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import Any + +import polars as pl + +from dartlab.ai.metadata import get_meta + +_AI_PARSER_ERRORS = (ImportError, OSError, RuntimeError, TypeError, ValueError) + +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• +# ๋‚ด๋ถ€ LLM ํ˜ธ์ถœ +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• + + +def _llm_call(prompt: str, system: str = "") -> str: + """๋‚ด๋ถ€ LLM ํ˜ธ์ถœ. ๊ธ€๋กœ๋ฒŒ ์„ค์ •๋œ provider ์‚ฌ์šฉ.""" + from dartlab.ai import get_config + from dartlab.ai.providers import create_provider + + config = get_config() + provider = create_provider(config) + + messages = [] + if system: + messages.append({"role": "system", "content": system}) + messages.append({"role": "user", "content": prompt}) + + response = provider.complete(messages) + return response.answer + + +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• +# ์š”์•ฝ +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• + + +def summarize( + data: pl.DataFrame | str | list, + *, + module_name: str | None = None, + lang: str = "ko", +) -> str: + """DataFrame, ํ…์ŠคํŠธ, ๋˜๋Š” ๋ฆฌ์ŠคํŠธ๋ฅผ 2~5๋ฌธ์žฅ์œผ๋กœ ์š”์•ฝ. + + Args: + data: DataFrame (๋งˆํฌ๋‹ค์šด ๋ณ€ํ™˜ ํ›„ ์š”์•ฝ), str (์ง์ ‘ ์š”์•ฝ), list (๊ฒฐํ•ฉ ํ›„ ์š”์•ฝ) + module_name: ๋ฉ”ํƒ€๋ฐ์ดํ„ฐ ํ™œ์šฉ์„ ์œ„ํ•œ ๋ชจ๋“ˆ๋ช… + lang: "ko" ๋˜๋Š” "en" + + Returns: + ์š”์•ฝ ํ…์ŠคํŠธ (2~5๋ฌธ์žฅ) + """ + from dartlab.ai.context.builder import df_to_markdown + + # ๋ฐ์ดํ„ฐ โ†’ ํ…์ŠคํŠธ + if isinstance(data, pl.DataFrame): + meta = get_meta(module_name) if module_name else None + text = df_to_markdown(data, meta=meta) + elif isinstance(data, list): + parts = [] + for item in data[:10]: + if hasattr(item, "title") and hasattr(item, "text"): + parts.append(f"[{item.title}]\n{item.text[:500]}") + else: + parts.append(str(item)[:500]) + text = "\n\n".join(parts) + else: + text = str(data)[:3000] + + # ๋ฉ”ํƒ€๋ฐ์ดํ„ฐ ์ปจํ…์ŠคํŠธ + context = "" + if module_name: + meta = get_meta(module_name) + if meta: + context = f"์ด ๋ฐ์ดํ„ฐ๋Š” '{meta.label}'์ž…๋‹ˆ๋‹ค. {meta.description}\n\n" + + system = "ํ•œ๊ตญ์–ด๋กœ ๋‹ต๋ณ€ํ•˜์„ธ์š”." if lang == "ko" else "Answer in English." + + prompt = ( + f"{context}" + f"๋‹ค์Œ ๋ฐ์ดํ„ฐ๋ฅผ 2~5๋ฌธ์žฅ์œผ๋กœ ํ•ต์‹ฌ๋งŒ ์š”์•ฝํ•˜์„ธ์š”.\n" + f"์ˆ˜์น˜๋ฅผ ๊ตฌ์ฒด์ ์œผ๋กœ ์ธ์šฉํ•˜๊ณ , ์ฃผ์š” ์ถ”์„ธ์™€ ํŠน์ด์‚ฌํ•ญ์„ ํฌํ•จํ•˜์„ธ์š”.\n\n" + f"{text}" + ) + + return _llm_call(prompt, system=system) + + +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• +# ๊ณ„์ • ํ•ด์„ +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• + + +def interpret_accounts( + df: pl.DataFrame, + *, + account_col: str = "๊ณ„์ •๋ช…", + module_name: str | None = None, +) -> pl.DataFrame: + """์žฌ๋ฌด์ œํ‘œ์— '์„ค๋ช…' ์ปฌ๋Ÿผ ์ถ”๊ฐ€. ๊ฐ ๊ณ„์ •๋ช…์˜ ์˜๋ฏธ๋ฅผ LLM์ด ํ•ด์„. + + LLM 1ํšŒ ํ˜ธ์ถœ๋กœ ์ „์ฒด ๊ณ„์ • ์ผ๊ด„ ํ•ด์„ (๊ฐœ๋ณ„ ํ˜ธ์ถœ ์•„๋‹˜). + + Args: + df: ๊ณ„์ •๋ช… ์ปฌ๋Ÿผ์ด ์žˆ๋Š” ์žฌ๋ฌด์ œํ‘œ DataFrame + account_col: ๊ณ„์ •๋ช… ์ปฌ๋Ÿผ๋ช… + module_name: "BS", "IS", "CF" ๋“ฑ + + Returns: + ์›๋ณธ + '์„ค๋ช…' ์ปฌ๋Ÿผ์ด ์ถ”๊ฐ€๋œ DataFrame + """ + if account_col not in df.columns: + return df + + accounts = df[account_col].to_list() + if not accounts: + return df + + # ์œ ์ผํ•œ ๊ณ„์ •๋ช…๋งŒ ์ถ”์ถœ + unique_accounts = list(dict.fromkeys(accounts)) + + module_hint = "" + if module_name: + meta = get_meta(module_name) + if meta: + module_hint = f"์ด ๋ฐ์ดํ„ฐ๋Š” '{meta.label}'({meta.description})์ž…๋‹ˆ๋‹ค.\n" + + prompt = ( + f"{module_hint}" + f"๋‹ค์Œ K-IFRS ๊ณ„์ •๋ช… ๊ฐ๊ฐ์— ๋Œ€ํ•ด ํ•œ ์ค„(20์ž ์ด๋‚ด)๋กœ ์„ค๋ช…ํ•˜์„ธ์š”.\n" + f"ํ˜•์‹: ๊ณ„์ •๋ช…: ์„ค๋ช…\n\n" + "\n".join(unique_accounts) + ) + + answer = _llm_call(prompt, system="ํ•œ๊ตญ์–ด๋กœ ๋‹ต๋ณ€ํ•˜์„ธ์š”. ๊ฐ ๊ณ„์ •์— ๋Œ€ํ•ด ๊ฐ„๊ฒฐํ•˜๊ฒŒ ์„ค๋ช…๋งŒ ํ•˜์„ธ์š”.") + + # ์‘๋‹ต ํŒŒ์‹ฑ: "๊ณ„์ •๋ช…: ์„ค๋ช…" ํ˜•ํƒœ + desc_map: dict[str, str] = {} + for line in answer.strip().split("\n"): + line = line.strip().lstrip("- ").lstrip("ยท ") + if ":" in line: + parts = line.split(":", 1) + key = parts[0].strip() + val = parts[1].strip() + desc_map[key] = val + + # ๋งคํ•‘ + descriptions = [] + for acct in accounts: + desc = desc_map.get(acct, "") + if not desc: + # ๋ถ€๋ถ„ ๋งค์นญ ์‹œ๋„ + for k, v in desc_map.items(): + if k in acct or acct in k: + desc = v + break + descriptions.append(desc) + + return df.with_columns(pl.Series("์„ค๋ช…", descriptions)) + + +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• +# ์ด์ƒ์น˜ ํƒ์ง€ +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• + + +@dataclass +class Anomaly: + """ํƒ์ง€๋œ ์ด์ƒ์น˜.""" + + column: str + year: str + value: Any + prev_value: Any + change_pct: float | None + anomaly_type: str # "spike", "sign_reversal", "outlier", "missing" + severity: str = "medium" # "high", "medium", "low" + description: str = "" + + +def _statistical_prescreen( + df: pl.DataFrame, + *, + year_col: str = "year", + threshold_pct: float = 50.0, +) -> list[Anomaly]: + """์ˆœ์ˆ˜ ํ†ต๊ณ„ ๊ธฐ๋ฐ˜ ์ด์ƒ์น˜ ์‚ฌ์ „ ํƒ์ง€ (LLM ์—†์ด ๋™์ž‘). + + ํƒ์ง€ ๊ธฐ์ค€: + - YoY ๋ณ€๋™ threshold_pct% ์ดˆ๊ณผ + - ๋ถ€ํ˜ธ ๋ฐ˜์ „ (์–‘โ†’์Œ, ์Œโ†’์–‘) + - 2ฯƒ ์ดํƒˆ + """ + if year_col not in df.columns: + return [] + + df_sorted = df.sort(year_col) + numeric_cols = [ + c for c in df.columns if c != year_col and df[c].dtype in (pl.Float64, pl.Float32, pl.Int64, pl.Int32) + ] + + anomalies = [] + years = df_sorted[year_col].to_list() + + for col in numeric_cols: + values = df_sorted[col].to_list() + non_null = [v for v in values if v is not None] + + if len(non_null) < 2: + continue + + mean_val = sum(non_null) / len(non_null) + if len(non_null) > 1: + variance = sum((v - mean_val) ** 2 for v in non_null) / (len(non_null) - 1) + std_val = variance**0.5 + else: + std_val = 0 + + for i in range(1, len(values)): + cur = values[i] + prev = values[i - 1] + + if cur is None or prev is None: + continue + + # YoY ๋ณ€๋™ + if prev != 0: + change = (cur - prev) / abs(prev) * 100 + if abs(change) > threshold_pct: + severity = "high" if abs(change) > 100 else "medium" + anomalies.append( + Anomaly( + column=col, + year=str(years[i]), + value=cur, + prev_value=prev, + change_pct=round(change, 1), + anomaly_type="spike", + severity=severity, + ) + ) + + # ๋ถ€ํ˜ธ ๋ฐ˜์ „ + if (prev > 0 and cur < 0) or (prev < 0 and cur > 0): + anomalies.append( + Anomaly( + column=col, + year=str(years[i]), + value=cur, + prev_value=prev, + change_pct=None, + anomaly_type="sign_reversal", + severity="high", + ) + ) + + # 2ฯƒ ์ดํƒˆ + if std_val > 0 and abs(cur - mean_val) > 2 * std_val: + anomalies.append( + Anomaly( + column=col, + year=str(years[i]), + value=cur, + prev_value=None, + change_pct=None, + anomaly_type="outlier", + severity="medium", + ) + ) + + # ์ค‘๋ณต ์ œ๊ฑฐ (๊ฐ™์€ year+column) + seen = set() + unique = [] + for a in anomalies: + key = (a.column, a.year, a.anomaly_type) + if key not in seen: + seen.add(key) + unique.append(a) + + return unique + + +def detect_anomalies( + df: pl.DataFrame, + *, + module_name: str | None = None, + year_col: str = "year", + threshold_pct: float = 50.0, + use_llm: bool = True, +) -> list[Anomaly]: + """2๋‹จ๊ณ„ ์ด์ƒ์น˜ ํƒ์ง€. + + Stage 1: ํ†ต๊ณ„ ์‚ฌ์ „์Šคํฌ๋ฆฌ๋‹ (LLM ์—†์ด ํ•ญ์ƒ ๋™์ž‘) + Stage 2: LLM ํ•ด์„ (use_llm=True์ด๊ณ  LLM ์„ค์ • ์‹œ) + + Args: + df: ์‹œ๊ณ„์—ด DataFrame + module_name: ๋ชจ๋“ˆ๋ช… (๋ฉ”ํƒ€๋ฐ์ดํ„ฐ ํ™œ์šฉ) + threshold_pct: YoY ๋ณ€๋™ ์ž„๊ณ„๊ฐ’ (%) + use_llm: True๋ฉด LLM์œผ๋กœ ํ•ด์„ ์ถ”๊ฐ€ + + Returns: + Anomaly ๋ฆฌ์ŠคํŠธ (severity ๋‚ด๋ฆผ์ฐจ์ˆœ) + """ + anomalies = _statistical_prescreen(df, year_col=year_col, threshold_pct=threshold_pct) + + if not anomalies: + return [] + + # Stage 2: LLM ํ•ด์„ + if use_llm and anomalies: + try: + meta_ctx = "" + if module_name: + meta = get_meta(module_name) + if meta: + meta_ctx = f"๋ฐ์ดํ„ฐ: {meta.label} ({meta.description})\n" + + lines = [] + for a in anomalies[:10]: # ์ตœ๋Œ€ 10๊ฐœ๋งŒ + if a.anomaly_type == "spike": + lines.append( + f"- {a.column} {a.year}๋…„: {a.prev_value:,.0f} โ†’ {a.value:,.0f} (YoY {a.change_pct:+.1f}%)" + ) + elif a.anomaly_type == "sign_reversal": + lines.append(f"- {a.column} {a.year}๋…„: ๋ถ€ํ˜ธ ๋ฐ˜์ „ {a.prev_value:,.0f} โ†’ {a.value:,.0f}") + elif a.anomaly_type == "outlier": + lines.append(f"- {a.column} {a.year}๋…„: ์ด์ƒ์น˜ {a.value:,.0f}") + + prompt = ( + f"{meta_ctx}" + f"๋‹ค์Œ ์žฌ๋ฌด ๋ฐ์ดํ„ฐ ์ด์ƒ์น˜๋“ค์— ๋Œ€ํ•ด ๊ฐ๊ฐ ํ•œ ์ค„๋กœ ๊ฐ€๋Šฅํ•œ ์›์ธ์„ ์„ค๋ช…ํ•˜์„ธ์š”.\n\n" + "\n".join(lines) + ) + + answer = _llm_call(prompt, system="ํ•œ๊ตญ์–ด๋กœ ๊ฐ„๊ฒฐํ•˜๊ฒŒ ๋‹ต๋ณ€ํ•˜์„ธ์š”.") + + # ์‘๋‹ต์—์„œ ์„ค๋ช… ์ถ”์ถœํ•˜์—ฌ anomalies์— ๋งคํ•‘ + desc_lines = [l.strip().lstrip("- ").lstrip("ยท ") for l in answer.strip().split("\n") if l.strip()] + for i, a in enumerate(anomalies[:10]): + if i < len(desc_lines): + a.description = desc_lines[i] + + except _AI_PARSER_ERRORS: + # LLM ์‹คํŒจ ์‹œ ํ†ต๊ณ„ ๊ฒฐ๊ณผ๋งŒ ๋ฐ˜ํ™˜ + pass + + # severity ์ •๋ ฌ + severity_order = {"high": 0, "medium": 1, "low": 2} + anomalies.sort(key=lambda a: severity_order.get(a.severity, 1)) + + return anomalies + + +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• +# ํ…์ŠคํŠธ ๋ถ„๋ฅ˜ +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• + + +def classify_text(text: str) -> dict: + """๊ณต์‹œ ํ…์ŠคํŠธ์—์„œ ๊ฐ์„ฑ, ํ•ต์‹ฌํ† ํ”ฝ, ๋ฆฌ์Šคํฌ, ๊ธฐํšŒ ์ถ”์ถœ. + + MD&A, ์‚ฌ์—…์˜ ๋‚ด์šฉ ๋“ฑ ์„œ์ˆ ํ˜• ํ…์ŠคํŠธ๋ฅผ ๊ตฌ์กฐํ™”๋œ ๋ถ„์„ ๊ฒฐ๊ณผ๋กœ ๋ณ€ํ™˜. + + Returns: + { + "sentiment": "๊ธ์ •" | "๋ถ€์ •" | "์ค‘๋ฆฝ", + "key_topics": list[str], + "risks": list[str], + "opportunities": list[str], + "summary": str, + } + """ + if not text: + return { + "sentiment": "์ค‘๋ฆฝ", + "key_topics": [], + "risks": [], + "opportunities": [], + "summary": "", + } + + # ํ…์ŠคํŠธ ๊ธธ์ด ์ œํ•œ + truncated = text[:3000] if len(text) > 3000 else text + + prompt = ( + "๋‹ค์Œ ๊ณต์‹œ ํ…์ŠคํŠธ๋ฅผ ๋ถ„์„ํ•˜์—ฌ ์•„๋ž˜ ํ˜•์‹์œผ๋กœ ๋‹ต๋ณ€ํ•˜์„ธ์š”.\n\n" + "๊ฐ์„ฑ: (๊ธ์ •/๋ถ€์ •/์ค‘๋ฆฝ)\n" + "ํ•ต์‹ฌํ† ํ”ฝ: (์‰ผํ‘œ๋กœ ๊ตฌ๋ถ„, 3~5๊ฐœ)\n" + "๋ฆฌ์Šคํฌ: (์‰ผํ‘œ๋กœ ๊ตฌ๋ถ„)\n" + "๊ธฐํšŒ: (์‰ผํ‘œ๋กœ ๊ตฌ๋ถ„)\n" + "์š”์•ฝ: (2~3๋ฌธ์žฅ)\n\n" + f"ํ…์ŠคํŠธ:\n{truncated}" + ) + + answer = _llm_call(prompt, system="ํ•œ๊ตญ์–ด๋กœ ๋‹ต๋ณ€ํ•˜์„ธ์š”. ์ฃผ์–ด์ง„ ํ˜•์‹์„ ์ •ํ™•ํžˆ ๋”ฐ๋ฅด์„ธ์š”.") + + # ์‘๋‹ต ํŒŒ์‹ฑ + result = { + "sentiment": "์ค‘๋ฆฝ", + "key_topics": [], + "risks": [], + "opportunities": [], + "summary": "", + } + + for line in answer.strip().split("\n"): + line = line.strip() + if line.startswith("๊ฐ์„ฑ:"): + val = line.split(":", 1)[1].strip() + if "๊ธ์ •" in val: + result["sentiment"] = "๊ธ์ •" + elif "๋ถ€์ •" in val: + result["sentiment"] = "๋ถ€์ •" + else: + result["sentiment"] = "์ค‘๋ฆฝ" + elif line.startswith("ํ•ต์‹ฌํ† ํ”ฝ:"): + val = line.split(":", 1)[1].strip() + result["key_topics"] = [t.strip() for t in val.split(",") if t.strip()] + elif line.startswith("๋ฆฌ์Šคํฌ:"): + val = line.split(":", 1)[1].strip() + result["risks"] = [t.strip() for t in val.split(",") if t.strip()] + elif line.startswith("๊ธฐํšŒ:"): + val = line.split(":", 1)[1].strip() + result["opportunities"] = [t.strip() for t in val.split(",") if t.strip()] + elif line.startswith("์š”์•ฝ:"): + result["summary"] = line.split(":", 1)[1].strip() + + return result + + +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• +# ํ†ตํ•ฉ ๋ถ„์„ +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• + + +def analyze_module( + company: Any, + module_name: str, +) -> dict: + """๋‹จ์ผ ๋ชจ๋“ˆ ์ „์ฒด AI ๋ถ„์„. + + summarize + detect_anomalies + (interpret_accounts if applicable) ์ผ๊ด„ ์‹คํ–‰. + + Returns: + { + "summary": str, + "anomalies": list[Anomaly], + "interpreted_df": pl.DataFrame | None, + } + """ + data = getattr(company, module_name, None) + if data is None: + return {"summary": "๋ฐ์ดํ„ฐ ์—†์Œ", "anomalies": [], "interpreted_df": None} + + result: dict[str, Any] = {} + + # ์š”์•ฝ + result["summary"] = summarize(data, module_name=module_name) + + # ์ด์ƒ์น˜ ํƒ์ง€ (DataFrame์ธ ๊ฒฝ์šฐ๋งŒ) + if isinstance(data, pl.DataFrame): + result["anomalies"] = detect_anomalies(data, module_name=module_name) + else: + result["anomalies"] = [] + + # ๊ณ„์ • ํ•ด์„ (BS/IS/CF๋งŒ) + if module_name in ("BS", "IS", "CF") and isinstance(data, pl.DataFrame) and "๊ณ„์ •๋ช…" in data.columns: + result["interpreted_df"] = interpret_accounts(data, module_name=module_name) + else: + result["interpreted_df"] = None + + return result diff --git a/src/dartlab/ai/context/__init__.py b/src/dartlab/ai/context/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..0beaca641776ece7592e6173862356f0fcc22d54 --- /dev/null +++ b/src/dartlab/ai/context/__init__.py @@ -0,0 +1,9 @@ +"""AI context package.""" + +from . import builder as _builder +from . import company_adapter as _company_adapter +from . import dartOpenapi as _dart_openapi +from . import snapshot as _snapshot + +for _module in (_builder, _snapshot, _company_adapter, _dart_openapi): + globals().update({name: getattr(_module, name) for name in dir(_module) if not name.startswith("__")}) diff --git a/src/dartlab/ai/context/builder.py b/src/dartlab/ai/context/builder.py new file mode 100644 index 0000000000000000000000000000000000000000..6014efcca835d839990ff2bc9d803f1998e3a4d8 --- /dev/null +++ b/src/dartlab/ai/context/builder.py @@ -0,0 +1,1960 @@ +"""Company ๋ฐ์ดํ„ฐ๋ฅผ LLM context๋กœ ๋ณ€ํ™˜. + +๋ฉ”ํƒ€๋ฐ์ดํ„ฐ ๊ธฐ๋ฐ˜ ์ปฌ๋Ÿผ ์„ค๋ช…, ํŒŒ์ƒ ์ง€ํ‘œ ์ž๋™๊ณ„์‚ฐ, ๋ถ„์„ ํžŒํŠธ๋ฅผ ํฌํ•จํ•˜์—ฌ +LLM์ด ์ •ํ™•ํ•˜๊ฒŒ ๋ถ„์„ํ•  ์ˆ˜ ์žˆ๋Š” ๊ตฌ์กฐํ™”๋œ ๋งˆํฌ๋‹ค์šด ์ปจํ…์ŠคํŠธ๋ฅผ ์ƒ์„ฑํ•œ๋‹ค. + +๋ถ„ํ•  ๋ชจ๋“ˆ: +- formatting.py: DataFrame ๋งˆํฌ๋‹ค์šด ๋ณ€ํ™˜, ํฌ๋งทํŒ…, ํŒŒ์ƒ ์ง€ํ‘œ ๊ณ„์‚ฐ +- finance_context.py: ์žฌ๋ฌด/๊ณต์‹œ ๋ฐ์ดํ„ฐ โ†’ LLM ์ปจํ…์ŠคํŠธ ๋งˆํฌ๋‹ค์šด ์ƒ์„ฑ +""" + +from __future__ import annotations + +import re +from typing import Any + +import polars as pl + +from dartlab.ai.context.company_adapter import get_headline_ratios +from dartlab.ai.context.finance_context import ( + _QUESTION_ACCOUNT_FILTER, + _QUESTION_MODULES, # noqa: F401 โ€” re-export for tests + _build_finance_engine_section, + _build_ratios_section, + _build_report_sections, + _buildQuarterlySection, + _detect_year_hint, + _get_quarter_counts, + _resolve_module_data, + _topic_name_set, + detect_year_range, + scan_available_modules, +) +from dartlab.ai.context.formatting import ( + _compute_derived_metrics, + _filter_key_accounts, + _format_usd, + _format_won, + _get_sector, # noqa: F401 โ€” re-export for runtime/core.py + df_to_markdown, +) +from dartlab.ai.metadata import MODULE_META + +_CONTEXT_ERRORS = (AttributeError, KeyError, OSError, RuntimeError, TypeError, ValueError) + +_ROUTE_FINANCE_TYPES = frozenset({"๊ฑด์ „์„ฑ", "์ˆ˜์ต์„ฑ", "์„ฑ์žฅ์„ฑ", "์ž๋ณธ"}) +_ROUTE_SECTIONS_TYPES = frozenset({"์‚ฌ์—…", "๋ฆฌ์Šคํฌ", "๊ณต์‹œ"}) +_ROUTE_REPORT_KEYWORDS: dict[str, str] = { + "๋ฐฐ๋‹น": "dividend", + "์ง์›": "employee", + "์ž„์›": "executive", + "์ตœ๋Œ€์ฃผ์ฃผ": "majorHolder", + "์ฃผ์ฃผ": "majorHolder", + "๊ฐ์‚ฌ": "audit", + "์ž๊ธฐ์ฃผ์‹": "treasuryStock", +} +_ROUTE_SECTIONS_KEYWORDS = frozenset( + { + "๊ณต์‹œ", + "์‚ฌ์—…", + "๋ฆฌ์Šคํฌ", + "๊ด€๊ณ„์‚ฌ", + "์ง€๋ฐฐ๊ตฌ์กฐ", + "๊ทผ๊ฑฐ", + "๋ณ€ํ™”", + "์ตœ๊ทผ ๊ณต์‹œ", + "๋ฌด์Šจ ์‚ฌ์—…", + "๋ญํ•˜๋Š”", + "์–ด๋–ค ํšŒ์‚ฌ", + "ESG", + "ํ™˜๊ฒฝ", + "์‚ฌํšŒ์  ์ฑ…์ž„", + "ํƒ„์†Œ", + "๊ธฐํ›„", + "๊ณต๊ธ‰๋ง", + "๊ณต๊ธ‰์‚ฌ", + "๊ณ ๊ฐ ์ง‘์ค‘", + "๋ณ€ํ™” ๊ฐ์ง€", + "๋ฌด์—‡์ด ๋‹ฌ๋ผ", + "๊ณต์‹œ ๋ณ€๊ฒฝ", + } +) +_ROUTE_HYBRID_KEYWORDS = frozenset({"์ข…ํ•ฉ", "์ „๋ฐ˜", "์ „์ฒด", "๋น„๊ต", "๋ฐธ๋ฅ˜์—์ด์…˜", "์ ์ • ์ฃผ๊ฐ€", "๋ชฉํ‘œ๊ฐ€", "DCF"}) +_ROUTE_FINANCE_KEYWORDS = frozenset( + { + "์žฌ๋ฌด", + "์˜์—…์ด์ต", + "์˜์—…์ด์ต๋ฅ ", + "๋งค์ถœ", + "์ˆœ์ด์ต", + "์‹ค์ ", + "ํ˜„๊ธˆํ๋ฆ„", + "๋ถ€์ฑ„", + "์ž์‚ฐ", + "์ˆ˜์ต์„ฑ", + "๊ฑด์ „์„ฑ", + "์„ฑ์žฅ์„ฑ", + "์ด์ต๋ฅ ", + "๋งˆ์ง„", + "revenue", + "profit", + "margin", + "cash flow", + "cashflow", + "debt", + "asset", + } +) +_ROUTE_REPORT_FINANCE_HINTS = frozenset( + { + "์ง€์† ๊ฐ€๋Šฅ", + "์ง€์†๊ฐ€๋Šฅ", + "์ง€์†์„ฑ", + "ํ˜„๊ธˆํ๋ฆ„", + "ํ˜„๊ธˆ", + "์‹ค์ ", + "์˜์—…์ด์ต", + "์ˆœ์ด์ต", + "์ปค๋ฒ„", + "ํŒ๋‹จ", + "ํ‰๊ฐ€", + "๊ฐ€๋Šฅํ•œ์ง€", + } +) +_ROUTE_DISTRESS_KEYWORDS = frozenset( + { + "๋ถ€์‹ค", + "๋ถ€์‹ค ์ง•ํ›„", + "์œ„๊ธฐ ์ง•ํ›„", + "์žฌ๋ฌด ์œ„๊ธฐ", + "์œ ๋™์„ฑ ์œ„๊ธฐ", + "์ž๊ธˆ ์••๋ฐ•", + "์ƒํ™˜ ๋ถ€๋‹ด", + "์ด์ž๋ณด์ƒ", + "์กด์† ๊ฐ€๋Šฅ", + "going concern", + "distress", + } +) +_SUMMARY_REQUEST_KEYWORDS = frozenset({"์ข…ํ•ฉ", "์ „๋ฐ˜", "์ „์ฒด", "์š”์•ฝ", "๊ฐœ๊ด„", "ํ•œ๋ˆˆ์—"}) +_QUARTERLY_HINTS = frozenset( + { + "๋ถ„๊ธฐ", + "๋ถ„๊ธฐ๋ณ„", + "quarterly", + "quarter", + "Q1", + "Q2", + "Q3", + "Q4", + "1๋ถ„๊ธฐ", + "2๋ถ„๊ธฐ", + "3๋ถ„๊ธฐ", + "4๋ถ„๊ธฐ", + "๋ฐ˜๊ธฐ", + "๋ฐ˜๊ธฐ๋ณ„", + "QoQ", + "์ „๋ถ„๊ธฐ", + } +) + + +def _detectGranularity(question: str) -> str: + """์งˆ๋ฌธ์—์„œ ์‹œ๊ฐ„ ๋‹จ์œ„ ๊ฐ์ง€: 'quarterly' | 'annual'.""" + if any(k in question for k in _QUARTERLY_HINTS): + return "quarterly" + return "annual" + + +_SECTIONS_TYPE_DEFAULTS: dict[str, list[str]] = { + "์‚ฌ์—…": ["businessOverview", "productService", "salesOrder"], + "๋ฆฌ์Šคํฌ": ["riskDerivative", "contingentLiability", "internalControl"], + "๊ณต์‹œ": ["disclosureChanges", "subsequentEvents", "otherReference"], + "์ง€๋ฐฐ๊ตฌ์กฐ": ["governanceOverview", "boardOfDirectors", "holderOverview"], +} +_SECTIONS_KEYWORD_TOPICS: dict[str, list[str]] = { + "๊ด€๊ณ„์‚ฌ": ["affiliateGroupDetail", "subsidiaryDetail", "investedCompany"], + "์ง€๋ฐฐ๊ตฌ์กฐ": ["governanceOverview", "boardOfDirectors", "holderOverview"], + "๋ฌด์Šจ ์‚ฌ์—…": ["businessOverview", "productService"], + "๋ญํ•˜๋Š”": ["businessOverview", "productService"], + "์–ด๋–ค ํšŒ์‚ฌ": ["businessOverview", "companyHistory"], + "์ตœ๊ทผ ๊ณต์‹œ": ["disclosureChanges", "subsequentEvents"], + "๋ณ€ํ™”": ["disclosureChanges", "businessStatus"], + "ESG": ["governanceOverview", "boardOfDirectors"], + "ํ™˜๊ฒฝ": ["businessOverview"], + "๊ณต๊ธ‰๋ง": ["segments", "rawMaterial"], + "๊ณต๊ธ‰์‚ฌ": ["segments", "rawMaterial"], + "๋ณ€ํ™” ๊ฐ์ง€": ["disclosureChanges", "businessStatus"], +} +_FINANCIAL_ONLY = {"BS", "IS", "CF", "fsSummary", "ratios"} +_SECTIONS_ROUTE_EXCLUDE_TOPICS = { + "fsSummary", + "financialStatements", + "financialNotes", + "consolidatedStatements", + "consolidatedNotes", + "dividend", + "employee", + "majorHolder", + "audit", +} +_FINANCE_STATEMENT_MODULES = frozenset({"BS", "IS", "CF", "CIS", "SCE"}) +_FINANCE_CONTEXT_MODULES = _FINANCE_STATEMENT_MODULES | {"ratios"} +_BALANCE_SHEET_HINTS = frozenset({"๋ถ€์ฑ„", "์ž์‚ฐ", "์œ ๋™", "์ฐจ์ž…", "์ž๋ณธ", "๋ ˆ๋ฒ„๋ฆฌ์ง€", "๊ฑด์ „์„ฑ", "์•ˆ์ „"}) +_CASHFLOW_HINTS = frozenset({"ํ˜„๊ธˆํ๋ฆ„", "ํ˜„๊ธˆ", "fcf", "์ž๊ธˆ", "์ปค๋ฒ„", "๋ฐฐ๋‹น์ง€๊ธ‰", "์ง€์† ๊ฐ€๋Šฅ", "์ง€์†๊ฐ€๋Šฅ"}) +_INCOME_STATEMENT_HINTS = frozenset( + {"๋งค์ถœ", "์˜์—…์ด์ต", "์ˆœ์ด์ต", "์ˆ˜์ต", "๋งˆ์ง„", "์ด์ต๋ฅ ", "์‹ค์ ", "์›๊ฐ€", "๋น„์šฉ", "ํŒ๊ด€๋น„"} +) +_RATIO_HINTS = frozenset({"๋น„์œจ", "๋งˆ์ง„", "์ด์ต๋ฅ ", "์ˆ˜์ต์„ฑ", "๊ฑด์ „์„ฑ", "์„ฑ์žฅ์„ฑ", "์•ˆ์ •์„ฑ", "์ง€์† ๊ฐ€๋Šฅ", "์ง€์†๊ฐ€๋Šฅ"}) +_DIRECT_HINT_MAP: dict[str, list[str]] = { + "์„ฑ๊ฒฉ๋ณ„ ๋น„์šฉ": ["costByNature"], + "๋น„์šฉ์˜ ์„ฑ๊ฒฉ": ["costByNature"], + "์ธ๊ฑด๋น„": ["costByNature"], + "๊ฐ๊ฐ€์ƒ๊ฐ": ["costByNature"], + "๊ด‘๊ณ ์„ ์ „๋น„": ["costByNature"], + "ํŒ๋งค์ด‰์ง„๋น„": ["costByNature"], + "์ง€๊ธ‰์ˆ˜์ˆ˜๋ฃŒ": ["costByNature"], + "์šด๋ฐ˜๋น„": ["costByNature"], + "๋ฌผ๋ฅ˜๋น„": ["costByNature"], + "์—ฐ๊ตฌ๊ฐœ๋ฐœ": ["rnd"], + "r&d": ["rnd"], + "์„ธ๊ทธ๋จผํŠธ": ["segments"], + "๋ถ€๋ฌธ์ •๋ณด": ["segments"], + "์‚ฌ์—…๋ถ€๋ฌธ": ["segments"], + "๋ถ€๋ฌธ๋ณ„": ["segments"], + "์ œํ’ˆ๋ณ„": ["productService"], + "์„œ๋น„์Šค๋ณ„": ["productService"], +} +_CANDIDATE_ALIASES = { + "segment": "segments", + "operationalAsset": "tangibleAsset", +} +_MARGIN_DRIVER_MARGIN_HINTS = frozenset({"์˜์—…์ด์ต๋ฅ ", "๋งˆ์ง„", "์ด์ต๋ฅ ", "margin"}) +_MARGIN_DRIVER_COST_HINTS = frozenset({"๋น„์šฉ ๊ตฌ์กฐ", "์›๊ฐ€ ๊ตฌ์กฐ", "๋น„์šฉ", "์›๊ฐ€", "ํŒ๊ด€๋น„", "๋งค์ถœ์›๊ฐ€"}) +_MARGIN_DRIVER_BUSINESS_HINTS = frozenset({"์‚ฌ์—… ๋ณ€ํ™”", "์‚ฌ์—…๋ณ€ํ™”", "์‚ฌ์—… ๊ตฌ์กฐ", "์‚ฌ์—…๊ตฌ์กฐ"}) +_RECENT_DISCLOSURE_BUSINESS_HINTS = frozenset({"์‚ฌ์—… ๋ณ€ํ™”", "์‚ฌ์—…๋ณ€ํ™”", "์‚ฌ์—… ๊ตฌ์กฐ", "์‚ฌ์—…๊ตฌ์กฐ"}) +_PERIOD_COLUMN_RE = re.compile(r"^\d{4}(?:Q[1-4])?$") + + +def _section_key_to_module_name(key: str) -> str: + if key.startswith("report_"): + return key.removeprefix("report_") + if key.startswith("module_"): + return key.removeprefix("module_") + if key.startswith("section_"): + return key.removeprefix("section_") + return key + + +def _module_name_to_section_keys(name: str) -> list[str]: + return [ + name, + f"report_{name}", + f"module_{name}", + f"section_{name}", + ] + + +def _build_module_section(name: str, data: Any, *, compact: bool, max_rows: int | None = None) -> str | None: + meta = MODULE_META.get(name) + label = meta.label if meta else name + max_rows_value = max_rows or (8 if compact else 15) + + if isinstance(data, pl.DataFrame): + if data.is_empty(): + return None + md = df_to_markdown(data, max_rows=max_rows_value, meta=meta, compact=True) + return f"\n## {label}\n{md}" + + if isinstance(data, dict): + items = list(data.items())[:max_rows_value] + lines = [f"\n## {label}"] + lines.extend(f"- {k}: {v}" for k, v in items) + return "\n".join(lines) + + if isinstance(data, list): + max_items = min(meta.maxRows if meta else 10, 5 if compact else 10) + lines = [f"\n## {label}"] + for item in data[:max_items]: + if hasattr(item, "title") and hasattr(item, "chars"): + lines.append(f"- **{item.title}** ({item.chars}์ž)") + else: + lines.append(f"- {item}") + if len(data) > max_items: + lines.append(f"(... ์ƒ์œ„ {max_items}๊ฑด, ์ „์ฒด {len(data)}๊ฑด)") + return "\n".join(lines) + + text = str(data).strip() + if not text: + return None + max_text = 500 if compact else 1000 + return f"\n## {label}\n{text[:max_text]}" + + +def _resolve_context_route( + question: str, + *, + include: list[str] | None, + q_types: list[str], +) -> str: + if include: + return "hybrid" + + if _detectGranularity(question) == "quarterly": + return "hybrid" + + if _has_margin_driver_pattern(question): + return "hybrid" + + if _has_distress_pattern(question): + return "finance" + + if _has_recent_disclosure_business_pattern(question): + return "sections" + + question_lower = question.lower() + q_set = set(q_types) + has_report = any(keyword in question for keyword in _ROUTE_REPORT_KEYWORDS) + has_sections = any(keyword in question for keyword in _ROUTE_SECTIONS_KEYWORDS) or bool( + q_set & _ROUTE_SECTIONS_TYPES + ) + has_finance_keyword = any(keyword in question_lower for keyword in _ROUTE_FINANCE_KEYWORDS) + has_finance = has_finance_keyword or bool(q_set & _ROUTE_FINANCE_TYPES) + has_report_finance_hint = any(keyword in question for keyword in _ROUTE_REPORT_FINANCE_HINTS) + + if has_report and (has_finance_keyword or has_sections or has_report_finance_hint): + return "hybrid" + + for keyword in _ROUTE_REPORT_KEYWORDS: + if keyword in question: + return "report" + + if has_sections: + return "sections" + + if q_set and q_set.issubset(_ROUTE_FINANCE_TYPES): + return "finance" + + if has_finance: + return "finance" + + if q_set and len(q_set) > 1: + return "hybrid" + + if q_set & {"์ข…ํ•ฉ"}: + return "hybrid" + + if any(keyword in question for keyword in _ROUTE_HYBRID_KEYWORDS): + return "hybrid" + + return "finance" if q_set else "hybrid" + + +def _append_unique(items: list[str], value: str | None) -> None: + if value and value not in items: + items.append(value) + + +def _normalize_candidate_module(name: str) -> str: + return _CANDIDATE_ALIASES.get(name, name) + + +def _question_has_any(question: str, keywords: set[str] | frozenset[str]) -> bool: + lowered = question.lower() + return any(keyword.lower() in lowered for keyword in keywords) + + +def _has_distress_pattern(question: str) -> bool: + return _question_has_any(question, _ROUTE_DISTRESS_KEYWORDS) + + +def _has_margin_driver_pattern(question: str) -> bool: + return ( + _question_has_any(question, _MARGIN_DRIVER_MARGIN_HINTS) + and _question_has_any(question, _MARGIN_DRIVER_COST_HINTS) + and _question_has_any(question, _MARGIN_DRIVER_BUSINESS_HINTS) + ) + + +def _has_recent_disclosure_business_pattern(question: str) -> bool: + lowered = question.lower() + return "์ตœ๊ทผ ๊ณต์‹œ" in lowered and _question_has_any(question, _RECENT_DISCLOSURE_BUSINESS_HINTS) + + +def _resolve_direct_hint_modules(question: str) -> list[str]: + selected: list[str] = [] + lowered = question.lower() + for keyword, modules in _DIRECT_HINT_MAP.items(): + if keyword.lower() in lowered: + for module_name in modules: + _append_unique(selected, _normalize_candidate_module(module_name)) + return selected + + +def _apply_question_specific_boosts(question: str, selected: list[str]) -> None: + if _has_distress_pattern(question): + for module_name in ("BS", "IS", "CF", "ratios"): + _append_unique(selected, module_name) + + if _has_margin_driver_pattern(question): + for module_name in ("IS", "costByNature", "businessOverview", "productService"): + _append_unique(selected, module_name) + + if _has_recent_disclosure_business_pattern(question): + for module_name in ("businessOverview", "productService"): + _append_unique(selected, module_name) + + +def _resolve_candidate_modules( + question: str, + *, + include: list[str] | None = None, + exclude: list[str] | None = None, +) -> list[str]: + selected: list[str] = [] + + if include: + for name in include: + _append_unique(selected, _normalize_candidate_module(name)) + else: + for module_name in _resolve_direct_hint_modules(question): + _append_unique(selected, module_name) + + for name in _resolve_tables(question, None, exclude): + _append_unique(selected, _normalize_candidate_module(name)) + + _apply_question_specific_boosts(question, selected) + + if exclude: + excluded = {_normalize_candidate_module(name) for name in exclude} + selected = [name for name in selected if name not in excluded] + + specific_modules = set(selected) - (_FINANCE_CONTEXT_MODULES | {"fsSummary"}) + if specific_modules and not _question_has_any(question, _SUMMARY_REQUEST_KEYWORDS): + selected = [name for name in selected if name != "fsSummary"] + + return selected + + +def _available_sections_topics(company: Any) -> set[str]: + docs = getattr(company, "docs", None) + sections = getattr(docs, "sections", None) + if sections is None: + return set() + + manifest = sections.outline() if hasattr(sections, "outline") else None + if isinstance(manifest, pl.DataFrame) and "topic" in manifest.columns: + return {topic for topic in manifest["topic"].drop_nulls().to_list() if isinstance(topic, str) and topic} + + if hasattr(sections, "topics"): + try: + return {topic for topic in sections.topics() if isinstance(topic, str) and topic} + except _CONTEXT_ERRORS: + return set() + return set() + + +def _available_report_modules(company: Any) -> set[str]: + report = getattr(company, "report", None) + if report is None: + return set() + + for attr_name in ("availableApiTypes", "apiTypes"): + try: + values = getattr(report, attr_name, None) + except _CONTEXT_ERRORS: + values = None + if isinstance(values, list): + return {str(value) for value in values if isinstance(value, str) and value} + return set() + + +def _available_notes_modules(company: Any) -> set[str]: + notes = getattr(company, "notes", None) + if notes is None: + docs = getattr(company, "docs", None) + notes = getattr(docs, "notes", None) if docs is not None else None + if notes is None or not hasattr(notes, "keys"): + return set() + + try: + return {str(value) for value in notes.keys() if isinstance(value, str) and value} + except _CONTEXT_ERRORS: + return set() + + +def _resolve_candidate_plan( + company: Any, + question: str, + *, + route: str, + include: list[str] | None = None, + exclude: list[str] | None = None, +) -> dict[str, list[str]]: + requested = _resolve_candidate_modules(question, include=include, exclude=exclude) + sections_set = _available_sections_topics(company) if route in {"sections", "hybrid"} else set() + report_set = _available_report_modules(company) if route in {"report", "hybrid"} else set() + notes_set = _available_notes_modules(company) if route == "hybrid" else set() + explicit_direct = set(_resolve_direct_hint_modules(question)) + boosted_direct: list[str] = [] + _apply_question_specific_boosts(question, boosted_direct) + explicit_direct.update(name for name in boosted_direct if name not in _FINANCE_CONTEXT_MODULES) + if include: + explicit_direct.update(_normalize_candidate_module(name) for name in include) + + sections: list[str] = [] + report: list[str] = [] + finance: list[str] = [] + direct: list[str] = [] + verified: list[str] = [] + + for name in requested: + normalized = _normalize_candidate_module(name) + if normalized in _FINANCE_CONTEXT_MODULES: + if route in {"finance", "hybrid"}: + _append_unique(finance, normalized) + _append_unique(verified, normalized) + continue + if normalized in sections_set and normalized not in _SECTIONS_ROUTE_EXCLUDE_TOPICS: + _append_unique(sections, normalized) + _append_unique(verified, normalized) + continue + if normalized in report_set: + _append_unique(report, normalized) + _append_unique(verified, normalized) + continue + if normalized in notes_set and normalized in explicit_direct: + _append_unique(direct, normalized) + _append_unique(verified, normalized) + continue + + if normalized in explicit_direct: + data = _resolve_module_data(company, normalized) + if data is not None: + _append_unique(direct, normalized) + _append_unique(verified, normalized) + + return { + "requested": requested, + "sections": sections, + "report": report, + "finance": finance, + "direct": direct, + "verified": verified, + } + + +def _resolve_finance_modules_for_question( + question: str, + *, + q_types: list[str], + route: str, + candidate_plan: dict[str, list[str]], +) -> list[str]: + selected: list[str] = [] + finance_candidates = [name for name in candidate_plan.get("finance", []) if name in _FINANCE_STATEMENT_MODULES] + + if _has_margin_driver_pattern(question): + _append_unique(selected, "IS") + + if route == "finance": + if _question_has_any(question, _INCOME_STATEMENT_HINTS): + _append_unique(selected, "IS") + if _question_has_any(question, _BALANCE_SHEET_HINTS): + _append_unique(selected, "BS") + if _question_has_any(question, _CASHFLOW_HINTS): + _append_unique(selected, "CF") + if not selected: + selected.extend(["IS", "BS", "CF"]) + elif route == "hybrid": + has_finance_signal = bool(finance_candidates) and ( + _question_has_any(question, _BALANCE_SHEET_HINTS | _CASHFLOW_HINTS | _RATIO_HINTS) + or bool(set(q_types) & _ROUTE_FINANCE_TYPES) + or any(name in candidate_plan.get("report", []) for name in ("dividend", "shareCapital")) + ) + if not has_finance_signal: + return [] + + for module_name in finance_candidates: + _append_unique(selected, module_name) + + if not selected: + if _question_has_any(question, _CASHFLOW_HINTS): + selected.extend(["IS", "CF"]) + elif _question_has_any(question, _BALANCE_SHEET_HINTS): + selected.extend(["IS", "BS"]) + else: + selected.append("IS") + + if route == "finance" or _question_has_any(question, _RATIO_HINTS) or bool(set(q_types) & _ROUTE_FINANCE_TYPES): + _append_unique(selected, "ratios") + elif route == "hybrid" and {"dividend", "shareCapital"} & set(candidate_plan.get("report", [])): + _append_unique(selected, "ratios") + + return selected + + +def _build_direct_module_context( + company: Any, + modules: list[str], + *, + compact: bool, + question: str, +) -> dict[str, str]: + result: dict[str, str] = {} + for name in modules: + try: + data = _resolve_module_data(company, name) + except _CONTEXT_ERRORS: + data = None + if data is None: + continue + if isinstance(data, pl.DataFrame): + data = _trim_period_columns(data, question, compact=compact) + section = _build_module_section(name, data, compact=compact) + if section: + result[name] = section + return result + + +def _trim_period_columns(data: pl.DataFrame, question: str, *, compact: bool) -> pl.DataFrame: + if data.is_empty(): + return data + + period_cols = [column for column in data.columns if isinstance(column, str) and _PERIOD_COLUMN_RE.fullmatch(column)] + if len(period_cols) <= 1: + return data + + def sort_key(value: str) -> tuple[int, int]: + if "Q" in value: + year, quarter = value.split("Q", 1) + return int(year), int(quarter) + return int(value), 9 + + ordered_periods = sorted(period_cols, key=sort_key) + keep_periods = _detect_year_hint(question) + if compact: + keep_periods = min(keep_periods, 5) + else: + keep_periods = min(keep_periods, 8) + if len(ordered_periods) <= keep_periods: + return data + + selected_periods = ordered_periods[-keep_periods:] + base_columns = [column for column in data.columns if column not in period_cols] + return data.select(base_columns + selected_periods) + + +def _build_response_contract( + question: str, + *, + included_modules: list[str], + route: str, +) -> str | None: + lines = ["## ์‘๋‹ต ๊ณ„์•ฝ", "- ์•„๋ž˜ ๋ชจ๋“ˆ์€ ์ด๋ฏธ ๋กœ์ปฌ dartlab ๋ฐ์ดํ„ฐ์—์„œ ํ™•์ธ๋˜์–ด ํฌํ•จ๋˜์—ˆ์Šต๋‹ˆ๋‹ค."] + lines.append(f"- ํฌํ•จ ๋ชจ๋“ˆ: {', '.join(included_modules)}") + lines.append("- ํฌํ•จ๋œ ๋ชจ๋“ˆ์„ ๋ณด๊ณ ๋„ '๋ฐ์ดํ„ฐ๊ฐ€ ์—†๋‹ค'๊ณ  ๋งํ•˜์ง€ ๋งˆ์„ธ์š”.") + lines.append("- ํ•ต์‹ฌ ๊ฒฐ๋ก  1~2๋ฌธ์žฅ์„ ๋จผ์ € ์ œ์‹œํ•˜๊ณ , ๋ฐ”๋กœ ๊ทผ๊ฑฐ ํ‘œ๋‚˜ ๊ทผ๊ฑฐ bullet์„ ๋ถ™์ด์„ธ์š”.") + lines.append( + "- `explore()` ๊ฐ™์€ ๋„๊ตฌ ํ˜ธ์ถœ ๊ณ„ํš์ด๋‚˜ ๋‚ด๋ถ€ ์ ˆ์ฐจ ์„ค๋ช…์„ ๋‹ต๋ณ€ ๋ณธ๋ฌธ์— ์“ฐ์ง€ ๋ง๊ณ  ๋ฐ”๋กœ ๋ถ„์„ ๊ฒฐ๊ณผ๋ฅผ ๋งํ•˜์„ธ์š”." + ) + lines.append( + "- ๋‹ต๋ณ€ ๋ณธ๋ฌธ์—์„œ๋Š” `IS/BS/CF/ratios/TTM/topic/period/source` ๊ฐ™์€ ๋‚ด๋ถ€ ์•ฝ์–ด๋‚˜ ํ•„๋“œ๋ช…์„ ๊ทธ๋Œ€๋กœ ์“ฐ์ง€ ๋ง๊ณ  " + "`์†์ต๊ณ„์‚ฐ์„œ/์žฌ๋ฌด์ƒํƒœํ‘œ/ํ˜„๊ธˆํ๋ฆ„ํ‘œ/์žฌ๋ฌด๋น„์œจ/์ตœ๊ทผ 4๋ถ„๊ธฐ ํ•ฉ์‚ฐ/ํ•ญ๋ชฉ/์‹œ์ /์ถœ์ฒ˜`์ฒ˜๋Ÿผ ์‚ฌ์šฉ์ž ์–ธ์–ด๋กœ ๋ฐ”๊พธ์„ธ์š”." + ) + lines.append( + "- `costByNature`, `businessOverview`, `productService` ๊ฐ™์€ ๋‚ด๋ถ€ ๋ชจ๋“ˆ๋ช…๋„ ๊ฐ๊ฐ " + "`์„ฑ๊ฒฉ๋ณ„ ๋น„์šฉ ๋ถ„๋ฅ˜`, `์‚ฌ์—…์˜ ๊ฐœ์š”`, `์ œํ’ˆยท์„œ๋น„์Šค`์ฒ˜๋Ÿผ ๋ฐ”๊ฟ” ์“ฐ์„ธ์š”." + ) + + module_set = set(included_modules) + if "costByNature" in module_set: + lines.append("- `costByNature`๊ฐ€ ์žˆ์œผ๋ฉด ์ƒ์œ„ ๋น„์šฉ ํ•ญ๋ชฉ 3~5๊ฐœ์™€ ์ตœ๊ทผ ๊ธฐ๊ฐ„ ๋ณ€ํ™” ๋ฐฉํ–ฅ์„ ๋จผ์ € ์š”์•ฝํ•˜์„ธ์š”.") + lines.append("- ๊ธฐ๊ฐ„์ด ๋ช…์‹œ๋˜์ง€ ์•Š์•„๋„ ์ตœ์‹  ์‹œ์ ๊ณผ ์ตœ๊ทผ ์ถ”์„ธ๋ฅผ ๋จผ์ € ๋‹ตํ•˜๊ณ , ์—ฐ๋„ ๊ธฐ์ค€์„ ๋‹ค์‹œ ๋ฌป์ง€ ๋งˆ์„ธ์š”.") + if "dividend" in module_set: + lines.append("- `dividend`๊ฐ€ ์žˆ์œผ๋ฉด DPSยท๋ฐฐ๋‹น์ˆ˜์ต๋ฅ ยท๋ฐฐ๋‹น์„ฑํ–ฅ์„ ๋จผ์ € ์š”์•ฝํ•˜์„ธ์š”.") + lines.append( + "- `dividend`๊ฐ€ ์žˆ๋Š”๋ฐ๋„ ๋ฐฐ๋‹น ๋ฐ์ดํ„ฐ๊ฐ€ ์—†๋‹ค๊ณ  ๋งํ•˜์ง€ ๋งˆ์„ธ์š”. ์ฒซ ๋ฌธ์žฅ์ด๋‚˜ ์ฒซ ํ‘œ์—์„œ DPS์™€ ๋ฐฐ๋‹น์ˆ˜์ต๋ฅ ์„ ์ง์ ‘ ์ธ์šฉํ•˜์„ธ์š”." + ) + if {"dividend", "IS", "CF"} <= module_set or {"dividend", "CF"} <= module_set: + lines.append("- `dividend`์™€ `IS/CF`๊ฐ€ ๊ฐ™์ด ์žˆ์œผ๋ฉด ๋ฐฐ๋‹น์˜ ์ด์ต/ํ˜„๊ธˆํ๋ฆ„ ์ปค๋ฒ„ ์—ฌ๋ถ€๋ฅผ ํ•œ ์ค„๋กœ ๋ช…์‹œํ•˜์„ธ์š”.") + if _has_distress_pattern(question): + lines.append( + "- `๋ถ€์‹ค ์ง•ํ›„` ์งˆ๋ฌธ์ด๋ฉด ๊ฑด์ „์„ฑ ๊ฒฐ๋ก ์„ ๋จผ์ € ๋งํ•˜๊ณ , ์ˆ˜์ต์„ฑยทํ˜„๊ธˆํ๋ฆ„ยท์ฐจ์ž… ๋ถ€๋‹ด ์ˆœ์œผ๋กœ ์งง๊ฒŒ ์ •๋ฆฌํ•˜์„ธ์š”." + ) + if route == "sections" or any(keyword in question for keyword in ("๊ทผ๊ฑฐ", "์™œ", "์ตœ๊ทผ ๊ณต์‹œ ๊ธฐ์ค€", "์ถœ์ฒ˜")): + lines.append("- ๊ทผ๊ฑฐ ์งˆ๋ฌธ์ด๋ฉด `topic`, `period`, `source`๋ฅผ ์ตœ์†Œ 2๊ฐœ ๋ช…์‹œํ•˜์„ธ์š”.") + lines.append( + "- `period`์™€ `source`๋Š” outline ํ‘œ์— ๋‚˜์˜จ ์‹ค์ œ ๊ฐ’์„ ์“ฐ์„ธ์š”. '์ตœ๊ทผ ๊ณต์‹œ ๊ธฐ์ค€' ๊ฐ™์€ ํฌ๊ด„ ํ‘œํ˜„์œผ๋กœ ๋ญ‰๊ฐœ์ง€ ๋งˆ์„ธ์š”." + ) + lines.append("- ๋ณธ๋ฌธ์—์„œ๋Š” `topic/period/source` ๋Œ€์‹  `ํ•ญ๋ชฉ/์‹œ์ /์ถœ์ฒ˜`์ฒ˜๋Ÿผ ์ž์—ฐ์–ด๋ฅผ ์“ฐ์„ธ์š”.") + hasQuarterly = any(m.endswith("_quarterly") for m in module_set) + if hasQuarterly: + lines.append("- **๋ถ„๊ธฐ๋ณ„ ๋ฐ์ดํ„ฐ๊ฐ€ ํฌํ•จ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. '๋ถ„๊ธฐ ๋ฐ์ดํ„ฐ๊ฐ€ ์—†๋‹ค'๊ณ  ์ ˆ๋Œ€ ๋งํ•˜์ง€ ๋งˆ์„ธ์š”.**") + lines.append("- ๋ถ„๊ธฐ๋ณ„ ์ถ”์ด๋ฅผ ํ…Œ์ด๋ธ”๋กœ ์ •๋ฆฌํ•˜๊ณ , ์ „๋ถ„๊ธฐ ๋Œ€๋น„(QoQ)์™€ ์ „๋…„๋™๊ธฐ ๋Œ€๋น„(YoY) ๋ณ€ํ™”๋ฅผ ํ•จ๊ป˜ ๋ณด์—ฌ์ฃผ์„ธ์š”.") + lines.append( + "- `IS_quarterly`, `CF_quarterly` ๊ฐ™์€ ๋‚ด๋ถ€๋ช… ๋Œ€์‹  `๋ถ„๊ธฐ๋ณ„ ์†์ต๊ณ„์‚ฐ์„œ`, `๋ถ„๊ธฐ๋ณ„ ํ˜„๊ธˆํ๋ฆ„ํ‘œ`๋กœ ์“ฐ์„ธ์š”." + ) + + # โ”€โ”€ ๋„๊ตฌ ์ถ”์ฒœ ํžŒํŠธ โ”€โ”€ + hasFinancial = {"IS", "BS"} <= module_set or {"IS", "CF"} <= module_set + if hasFinancial: + lines.append( + "- **์ถ”๊ฐ€ ๋ถ„์„ ์ถ”์ฒœ**: `finance(action='ratios')`๋กœ ์žฌ๋ฌด๋น„์œจ ํ™•์ธ, " + "`explore(action='search', keyword='...')`๋กœ ๋ณ€ํ™” ์›์ธ ํŒŒ์•…." + ) + elif not module_set & {"IS", "BS", "CF", "ratios"}: + lines.append( + "- **์žฌ๋ฌด ๋ฐ์ดํ„ฐ ๋ฏธํฌํ•จ**: `finance(action='modules')`๋กœ ์‚ฌ์šฉ ๊ฐ€๋Šฅ ๋ชจ๋“ˆ ํ™•์ธ, " + "`explore(action='topics')`๋กœ topic ๋ชฉ๋ก ํ™•์ธ ์ถ”์ฒœ." + ) + return "\n".join(lines) + + +def _build_clarification_context( + company: Any, + question: str, + *, + candidate_plan: dict[str, list[str]], +) -> str | None: + if _has_margin_driver_pattern(question): + return None + + lowered = question.lower() + module_set = set(candidate_plan.get("verified", [])) + has_cost_by_nature = "costByNature" in module_set + if not has_cost_by_nature and "costByNature" in set(candidate_plan.get("requested", [])): + try: + has_cost_by_nature = _resolve_module_data(company, "costByNature") is not None + except _CONTEXT_ERRORS: + has_cost_by_nature = False + has_is = "IS" in module_set or "IS" in set(candidate_plan.get("requested", [])) + if not has_cost_by_nature or not has_is: + return None + if "๋น„์šฉ" not in lowered: + return None + if any(keyword in lowered for keyword in ("์„ฑ๊ฒฉ", "์ธ๊ฑด๋น„", "๊ฐ๊ฐ€์ƒ๊ฐ", "๊ด‘๊ณ ์„ ์ „", "ํŒ๊ด€", "๋งค์ถœ์›๊ฐ€")): + return None + + return ( + "## Clarification Needed\n" + "- ํ˜„์žฌ ๋กœ์ปฌ์—์„œ ๋‘ ํ•ด์„์ด ๋ชจ๋‘ ๊ฐ€๋Šฅํ•ฉ๋‹ˆ๋‹ค.\n" + "- `costByNature`: ์ธ๊ฑด๋น„ยท๊ฐ๊ฐ€์ƒ๊ฐ๋น„ ๊ฐ™์€ ์„ฑ๊ฒฉ๋ณ„ ๋น„์šฉ ๋ถ„๋ฅ˜\n" + "- `IS`: ๋งค์ถœ์›๊ฐ€ยทํŒ๊ด€๋น„ ๊ฐ™์€ ๊ธฐ๋Šฅ๋ณ„ ๋น„์šฉ ์ด์•ก\n" + "- ์‚ฌ์šฉ์ž์˜ ์˜๋„๊ฐ€ ๋‘˜ ์ค‘ ์–ด๋Š ์ชฝ์ธ์ง€ ๊ฒฐ๋ก ์„ ๋ฐ”๊พธ๋ฏ€๋กœ, ๋จผ์ € ํ•œ ๋ฌธ์žฅ์œผ๋กœ ์–ด๋Š ๊ด€์ ์„ ์›ํ•˜๋Š”์ง€ ํ™•์ธํ•˜์„ธ์š”.\n" + "- ํ™•์ธ ์งˆ๋ฌธ์€ ํ•œ ๋ฌธ์žฅ๋งŒ ํ•˜์„ธ์š”. ๊ฐ™์€ ๋ฌธ์žฅ์„ ๋ฐ˜๋ณตํ•˜์ง€ ๋งˆ์„ธ์š”." + ) + + +def _resolve_report_modules_for_question( + question: str, + *, + include: list[str] | None = None, + exclude: list[str] | None = None, +) -> list[str]: + modules: list[str] = [] + + for keyword, name in _ROUTE_REPORT_KEYWORDS.items(): + if keyword in question and name not in modules: + modules.append(name) + + if include: + for name in include: + if ( + name in {"dividend", "employee", "majorHolder", "executive", "audit", "treasuryStock"} + and name not in modules + ): + modules.append(name) + + if exclude: + modules = [name for name in modules if name not in exclude] + + return modules + + +def _resolve_sections_topics( + company: Any, + question: str, + *, + q_types: list[str], + candidates: list[str] | None = None, + include: list[str] | None = None, + exclude: list[str] | None = None, + limit: int = 2, +) -> list[str]: + docs = getattr(company, "docs", None) + sections = getattr(docs, "sections", None) + if sections is None: + return [] + + manifest = sections.outline() if hasattr(sections, "outline") else None + available = ( + manifest["topic"].drop_nulls().to_list() + if isinstance(manifest, pl.DataFrame) and "topic" in manifest.columns + else sections.topics() + if hasattr(sections, "topics") + else [] + ) + availableTopics = [topic for topic in available if isinstance(topic, str) and topic] + availableSet = set(availableTopics) + if not availableSet: + return [] + + selected: list[str] = [] + isQuarterly = _detectGranularity(question) == "quarterly" + + def append(topic: str) -> None: + if topic in _SECTIONS_ROUTE_EXCLUDE_TOPICS: + if not (isQuarterly and topic == "fsSummary"): + return + if topic in availableSet and topic not in selected: + selected.append(topic) + + if isQuarterly: + append("fsSummary") + + if include: + for name in include: + append(name) + + if _has_recent_disclosure_business_pattern(question): + append("disclosureChanges") + append("businessOverview") + + candidate_source = _resolve_tables(question, None, exclude) if candidates is None else candidates + for name in candidate_source: + append(name) + + for q_type in q_types: + for topic in _SECTIONS_TYPE_DEFAULTS.get(q_type, []): + append(topic) + + for keyword, topics in _SECTIONS_KEYWORD_TOPICS.items(): + if keyword in question: + for topic in topics: + append(topic) + + if candidates is None and not selected and availableTopics: + selected.append(availableTopics[0]) + + return selected[:limit] + + +def _build_sections_context( + company: Any, + topics: list[str], + *, + compact: bool, +) -> dict[str, str]: + docs = getattr(company, "docs", None) + sections = getattr(docs, "sections", None) + if sections is None: + return {} + + try: + context_slices = getattr(docs, "contextSlices", None) if docs is not None else None + except _CONTEXT_ERRORS: + context_slices = None + + result: dict[str, str] = {} + for topic in topics: + outline = sections.outline(topic) if hasattr(sections, "outline") else None + if outline is None or not isinstance(outline, pl.DataFrame) or outline.is_empty(): + continue + + label_fn = getattr(company, "_topicLabel", None) + label = label_fn(topic) if callable(label_fn) else topic + lines = [f"\n## {label}"] + lines.append(df_to_markdown(outline.head(6 if compact else 10), max_rows=6 if compact else 10, compact=True)) + + topic_slices = _select_section_slices(context_slices, topic) + if isinstance(topic_slices, pl.DataFrame) and not topic_slices.is_empty(): + lines.append("\n### ํ•ต์‹ฌ ๊ทผ๊ฑฐ") + for row in topic_slices.head(2 if compact else 4).iter_rows(named=True): + period = row.get("period", "-") + source_topic = row.get("sourceTopic") or row.get("topic") or topic + block_type = "ํ‘œ" if row.get("isTable") or row.get("blockType") == "table" else "๋ฌธ์žฅ" + slice_text = _truncate_section_slice(str(row.get("sliceText") or ""), compact=compact) + if not slice_text: + continue + lines.append(f"#### ์‹œ์ : {period} | ์ถœ์ฒ˜: {source_topic} | ์œ ํ˜•: {block_type}") + lines.append(slice_text) + + if compact: + if ("preview" in outline.columns) and not ( + isinstance(topic_slices, pl.DataFrame) and not topic_slices.is_empty() + ): + preview_lines: list[str] = [] + for row in outline.head(2).iter_rows(named=True): + preview = row.get("preview") + if not isinstance(preview, str) or not preview.strip(): + continue + period = row.get("period", "-") + title = row.get("title", "-") + preview_lines.append( + f"- period: {period} | source: docs | title: {title} | preview: {preview.strip()}" + ) + if preview_lines: + lines.append("\n### ํ•ต์‹ฌ preview") + lines.extend(preview_lines) + result[f"section_{topic}"] = "\n".join(lines) + continue + + try: + raw_sections = sections.raw if hasattr(sections, "raw") else None + except _CONTEXT_ERRORS: + raw_sections = None + + topic_rows = ( + raw_sections.filter(pl.col("topic") == topic) + if isinstance(raw_sections, pl.DataFrame) and "topic" in raw_sections.columns + else None + ) + + block_builder = getattr(company, "_buildBlockIndex", None) + block_index = ( + block_builder(topic_rows) if callable(block_builder) and isinstance(topic_rows, pl.DataFrame) else None + ) + + if isinstance(block_index, pl.DataFrame) and not block_index.is_empty(): + lines.append("\n### block index") + lines.append( + df_to_markdown(block_index.head(4 if compact else 6), max_rows=4 if compact else 6, compact=True) + ) + + block_col = ( + "block" + if "block" in block_index.columns + else "blockOrder" + if "blockOrder" in block_index.columns + else None + ) + type_col = ( + "type" if "type" in block_index.columns else "blockType" if "blockType" in block_index.columns else None + ) + sample_block = None + if block_col: + for row in block_index.iter_rows(named=True): + block_no = row.get(block_col) + block_type = row.get(type_col) + if isinstance(block_no, int) and block_type in {"text", "table"}: + sample_block = block_no + break + if sample_block is not None: + show_section_block = getattr(company, "_showSectionBlock", None) + block_data = ( + show_section_block(topic_rows, block=sample_block) + if callable(show_section_block) and isinstance(topic_rows, pl.DataFrame) + else None + ) + section = _build_module_section(topic, block_data, compact=compact, max_rows=4 if compact else 6) + if section: + lines.append("\n### ๋Œ€ํ‘œ block") + lines.append(section.replace(f"\n## {label}", "", 1).strip()) + + result[f"section_{topic}"] = "\n".join(lines) + + return result + + +def _select_section_slices(context_slices: Any, topic: str) -> pl.DataFrame | None: + if not isinstance(context_slices, pl.DataFrame) or context_slices.is_empty(): + return None + + required_columns = {"topic", "periodOrder", "sliceText"} + if not required_columns <= set(context_slices.columns): + return None + + detail_col = pl.col("detailTopic") if "detailTopic" in context_slices.columns else pl.lit(None) + semantic_col = pl.col("semanticTopic") if "semanticTopic" in context_slices.columns else pl.lit(None) + block_priority_col = pl.col("blockPriority") if "blockPriority" in context_slices.columns else pl.lit(0) + slice_idx_col = pl.col("sliceIdx") if "sliceIdx" in context_slices.columns else pl.lit(0) + + matched = context_slices.filter((pl.col("topic") == topic) | (detail_col == topic) | (semantic_col == topic)) + if matched.is_empty(): + return None + + return matched.with_columns( + pl.when(detail_col == topic) + .then(3) + .when(semantic_col == topic) + .then(2) + .when(pl.col("topic") == topic) + .then(1) + .otherwise(0) + .alias("matchPriority") + ).sort( + ["periodOrder", "matchPriority", "blockPriority", "sliceIdx"], + descending=[True, True, True, False], + ) + + +def _truncate_section_slice(text: str, *, compact: bool) -> str: + stripped = text.strip() + if not stripped: + return "" + max_chars = 500 if compact else 1200 + if len(stripped) <= max_chars: + return stripped + return stripped[:max_chars].rstrip() + " ..." + + +def build_context_by_module( + company: Any, + question: str, + include: list[str] | None = None, + exclude: list[str] | None = None, + compact: bool = False, +) -> tuple[dict[str, str], list[str], str]: + """financeEngine ์šฐ์„  compact ์ปจํ…์ŠคํŠธ ๋นŒ๋” (๋ชจ๋“ˆ๋ณ„ ๋ถ„๋ฆฌ). + + 1์ฐจ: financeEngine annual + ratios (๋น ๋ฅด๊ณ  ์ •๊ทœํ™”๋œ ์ˆ˜์น˜) + 2์ฐจ: docsParser ์ •์„ฑ ๋ฐ์ดํ„ฐ (๋ฐฐ๋‹น, ๊ฐ์‚ฌ, ์ž„์› ๋“ฑ โ€” ์งˆ๋ฌธ์— ๋งž๋Š” ๊ฒƒ๋งŒ) + + Args: + compact: True๋ฉด ์†Œํ˜• ๋ชจ๋ธ์šฉ์œผ๋กœ ์—ฐ๋„/ํ–‰์ˆ˜ ์ œํ•œ (Ollama). + + Returns: + (modules_dict, included_list, header_text) + - modules_dict: {"IS": "## ์†์ต๊ณ„์‚ฐ์„œ\n...", "BS": "...", ...} + - included_list: ["IS", "BS", "CF", "ratios", ...] + - header_text: ๊ธฐ์—…๋ช… + ๋ฐ์ดํ„ฐ ๊ธฐ์ค€ ๋ผ์ธ + """ + from dartlab import config + + orig_verbose = config.verbose + config.verbose = False + try: + return _build_compact_context_modules_inner(company, question, include, exclude, compact, orig_verbose) + finally: + config.verbose = orig_verbose + + +def _build_compact_context_modules_inner( + company: Any, + question: str, + include: list[str] | None, + exclude: list[str] | None, + compact: bool, + orig_verbose: bool, +) -> tuple[dict[str, str], list[str], str]: + n_years = _detect_year_hint(question) + if compact: + n_years = min(n_years, 4) + modules_dict: dict[str, str] = {} + included: list[str] = [] + + header_parts = [f"# {company.corpName} ({company.stockCode})"] + + try: + detail = getattr(company, "companyOverviewDetail", None) + if detail and isinstance(detail, dict): + info_parts = [] + if detail.get("ceo"): + info_parts.append(f"๋Œ€ํ‘œ: {detail['ceo']}") + if detail.get("mainBusiness"): + info_parts.append(f"์ฃผ์š”์‚ฌ์—…: {detail['mainBusiness']}") + if info_parts: + header_parts.append("> " + " | ".join(info_parts)) + except _CONTEXT_ERRORS: + pass + + from dartlab.ai.conversation.prompts import _classify_question_multi + + q_types = _classify_question_multi(question, max_types=2) + route = _resolve_context_route(question, include=include, q_types=q_types) + report_modules = _resolve_report_modules_for_question(question, include=include, exclude=exclude) + candidate_plan = _resolve_candidate_plan(company, question, route=route, include=include, exclude=exclude) + selected_finance_modules = _resolve_finance_modules_for_question( + question, + q_types=q_types, + route=route, + candidate_plan=candidate_plan, + ) + + acct_filters: dict[str, set[str]] = {} + if compact: + for qt in q_types: + for sj, ids in _QUESTION_ACCOUNT_FILTER.get(qt, {}).items(): + acct_filters.setdefault(sj, set()).update(ids) + + statement_modules = [name for name in selected_finance_modules if name in _FINANCE_STATEMENT_MODULES] + if statement_modules: + annual = getattr(company, "annual", None) + if annual is not None: + series, years = annual + quarter_counts = _get_quarter_counts(company) + if years: + yr_min = years[max(0, len(years) - n_years)] + yr_max = years[-1] + header = f"\n**๋ฐ์ดํ„ฐ ๊ธฐ์ค€: {yr_min}~{yr_max}๋…„** (๊ฐ€์žฅ ์ตœ๊ทผ: {yr_max}๋…„, ๊ธˆ์•ก: ์–ต/์กฐ์›)\n" + + partial = [y for y in years[-n_years:] if quarter_counts.get(y, 4) < 4] + if partial: + notes = ", ".join(f"{y}๋…„=Q1~Q{quarter_counts[y]}" for y in partial) + header += ( + f"โš ๏ธ **๋ถ€๋ถ„ ์—ฐ๋„ ์ฃผ์˜**: {notes} (ํ•ด๋‹น ์—ฐ๋„๋Š” ๋ถ„๊ธฐ ๋ˆ„์ ์ด๋ฏ€๋กœ ์ „๋…„ ์—ฐ๊ฐ„๊ณผ ์ง์ ‘ ๋น„๊ต ๋ถˆ๊ฐ€)\n" + ) + + header_parts.append(header) + + for sj in statement_modules: + af = acct_filters.get(sj) if acct_filters and sj in {"IS", "BS", "CF"} else None + section = _build_finance_engine_section( + series, + years, + sj, + n_years, + af, + quarter_counts=quarter_counts, + ) + if section: + modules_dict[sj] = section + included.append(sj) + + if _detectGranularity(question) == "quarterly" and statement_modules: + ts = getattr(company, "timeseries", None) + if ts is not None: + tsSeries, tsPeriods = ts + for sj in statement_modules: + if sj in {"IS", "CF"}: + af = acct_filters.get(sj) if acct_filters else None + qSection = _buildQuarterlySection( + tsSeries, + tsPeriods, + sj, + nQuarters=8, + accountFilter=af, + ) + if qSection: + qKey = f"{sj}_quarterly" + modules_dict[qKey] = qSection + included.append(qKey) + + if "ratios" in selected_finance_modules: + ratios_section = _build_ratios_section(company, compact=compact, q_types=q_types or None) + if ratios_section: + modules_dict["ratios"] = ratios_section + if "ratios" not in included: + included.append("ratios") + + requested_report_modules = report_modules or candidate_plan.get("report", []) + if route == "report": + requested_report_modules = requested_report_modules or [ + "dividend", + "employee", + "majorHolder", + "executive", + "audit", + ] + report_sections = _build_report_sections( + company, + compact=compact, + q_types=q_types, + tier="focused" if compact else "full", + report_names=requested_report_modules, + ) + for key, section in report_sections.items(): + modules_dict[key] = section + included_name = _section_key_to_module_name(key) + if included_name not in included: + included.append(included_name) + + if route == "hybrid" and requested_report_modules: + report_sections = _build_report_sections( + company, + compact=compact, + q_types=q_types, + tier="focused" if compact else "full", + report_names=requested_report_modules, + ) + for key, section in report_sections.items(): + modules_dict[key] = section + included_name = _section_key_to_module_name(key) + if included_name not in included: + included.append(included_name) + + if route in {"sections", "hybrid"}: + topics = _resolve_sections_topics( + company, + question, + q_types=q_types, + candidates=candidate_plan.get("sections"), + include=include, + exclude=exclude, + limit=1 if route == "hybrid" else 2, + ) + sections_context = _build_sections_context(company, topics, compact=compact) + for key, section in sections_context.items(): + modules_dict[key] = section + included_name = _section_key_to_module_name(key) + if included_name not in included: + included.append(included_name) + + if route == "finance": + _financeSectionsTopics = ["businessStatus", "businessOverview"] + availableTopicSet = _topic_name_set(company) + lightTopics = [t for t in _financeSectionsTopics if t in availableTopicSet] + if lightTopics: + lightContext = _build_sections_context(company, lightTopics[:1], compact=True) + for key, section in lightContext.items(): + modules_dict[key] = section + included_name = _section_key_to_module_name(key) + if included_name not in included: + included.append(included_name) + + direct_sections = _build_direct_module_context( + company, + candidate_plan.get("direct", []), + compact=compact, + question=question, + ) + for key, section in direct_sections.items(): + modules_dict[key] = section + if key not in included: + included.append(key) + + response_contract = _build_response_contract(question, included_modules=included, route=route) + if response_contract: + modules_dict["_response_contract"] = response_contract + + clarification_context = _build_clarification_context(company, question, candidate_plan=candidate_plan) + if clarification_context: + modules_dict["_clarify"] = clarification_context + + if not modules_dict: + text, inc = build_context(company, question, include, exclude, compact=True) + return {"_full": text}, inc, "" + + deduped_included: list[str] = [] + for name in included: + if name not in deduped_included: + deduped_included.append(name) + + return modules_dict, deduped_included, "\n".join(header_parts) + + +def build_compact_context( + company: Any, + question: str, + include: list[str] | None = None, + exclude: list[str] | None = None, +) -> tuple[str, list[str]]: + """financeEngine ์šฐ์„  compact ์ปจํ…์ŠคํŠธ ๋นŒ๋” (ํ•˜์œ„ํ˜ธํ™˜). + + build_context_by_module ๊ฒฐ๊ณผ๋ฅผ ๋‹จ์ผ ๋ฌธ์ž์—ด๋กœ ํ•ฉ์ณ ๋ฐ˜ํ™˜ํ•œ๋‹ค. + """ + modules_dict, included, header = build_context_by_module( + company, + question, + include, + exclude, + compact=True, + ) + if "_full" in modules_dict: + return modules_dict["_full"], included + + parts = [header] if header else [] + for name in included: + for key in _module_name_to_section_keys(name): + if key in modules_dict: + parts.append(modules_dict[key]) + break + return "\n".join(parts), included + + +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• +# ์งˆ๋ฌธ ํ‚ค์›Œ๋“œ โ†’ ์ž๋™ ํฌํ•จ ๋ฐ์ดํ„ฐ ๋งคํ•‘ +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• + +from dartlab.core.registry import buildKeywordMap + +# registry aiKeywords ์ž๋™ ์—ญ์ธ๋ฑ์Šค (~55 ๋ชจ๋“ˆ ํ‚ค์›Œ๋“œ) +_KEYWORD_MAP = buildKeywordMap() + +# ์žฌ๋ฌด์ œํ‘œ ์ง์ ‘ ๋งคํ•‘ (registry ๋ฒ”์œ„ ๋ฐ– โ€” BS/IS/CF ๋“ฑ ์žฌ๋ฌด ์ฝ”๋“œ) +_FINANCIAL_MAP: dict[str, list[str]] = { + "์žฌ๋ฌด": ["BS", "IS", "CF", "fsSummary", "costByNature"], + "๊ฑด์ „์„ฑ": ["BS", "audit", "contingentLiability", "internalControl", "bond"], + "์ˆ˜์ต": ["IS", "segments", "productService", "costByNature"], + "์‹ค์ ": ["IS", "segments", "fsSummary", "productService", "salesOrder"], + "๋งค์ถœ": ["IS", "segments", "productService", "salesOrder"], + "์˜์—…์ด์ต": ["IS", "fsSummary", "segments"], + "์ˆœ์ด์ต": ["IS", "fsSummary"], + "ํ˜„๊ธˆ": ["CF", "BS"], + "์ž์‚ฐ": ["BS", "tangibleAsset", "investmentInOther"], + "์„ฑ์žฅ": ["IS", "CF", "productService", "salesOrder", "rnd"], + "์›๊ฐ€": ["costByNature", "IS"], + "๋น„์šฉ": ["costByNature", "IS"], + "๋ฐฐ๋‹น": ["dividend", "IS", "shareCapital"], + "์ž๋ณธ": ["BS", "capitalChange", "shareCapital", "fundraising"], + "ํˆฌ์ž": ["CF", "rnd", "subsidiary", "investmentInOther", "tangibleAsset"], + "๋ถ€์ฑ„": ["BS", "bond", "contingentLiability", "capitalChange"], + "๋ฆฌ์Šคํฌ": ["contingentLiability", "sanction", "riskDerivative", "audit", "internalControl"], + "์ง€๋ฐฐ": ["majorHolder", "executive", "boardOfDirectors", "holderOverview"], +} + +# ๋ณตํ•ฉ ๋ถ„์„ (์—ฌ๋Ÿฌ ์žฌ๋ฌด์ œํ‘œ ์กฐํ•ฉ) +_COMPOSITE_MAP: dict[str, list[str]] = { + "ROE": ["IS", "BS", "fsSummary"], + "ROA": ["IS", "BS", "fsSummary"], + "PER": ["IS", "fsSummary", "dividend"], + "PBR": ["BS", "fsSummary"], + "EPS": ["IS", "fsSummary", "dividend"], + "EBITDA": ["IS", "CF", "fsSummary"], + "ESG": ["employee", "boardOfDirectors", "sanction", "internalControl"], + "๊ฑฐ๋ฒ„๋„Œ์Šค": ["majorHolder", "executive", "boardOfDirectors", "audit"], + "์ง€๋ฐฐ๊ตฌ์กฐ": ["majorHolder", "executive", "boardOfDirectors", "audit"], + "์ธ๋ ฅํ˜„ํ™ฉ": ["employee", "executivePay"], + "์ฃผ์ฃผํ™˜์›": ["dividend", "shareCapital", "capitalChange"], + "๋ถ€์ฑ„์œ„ํ—˜": ["BS", "bond", "contingentLiability"], + "๋ถ€์ฑ„๊ตฌ์กฐ": ["BS", "bond", "contingentLiability"], + "์ข…ํ•ฉ์ง„๋‹จ": ["BS", "IS", "CF", "fsSummary", "dividend", "majorHolder", "audit", "employee"], + "์Šค์บ”": ["BS", "IS", "dividend", "majorHolder", "audit", "employee"], + "์ „๋ฐ˜": ["BS", "IS", "CF", "fsSummary", "audit", "majorHolder"], + "์ข…ํ•ฉ": ["BS", "IS", "CF", "fsSummary", "audit", "majorHolder"], + # ์˜๋ฌธ + "revenue": ["IS", "segments", "productService"], + "profit": ["IS", "fsSummary"], + "debt": ["BS", "bond", "contingentLiability"], + "cash flow": ["CF"], + "cashflow": ["CF"], + "dividend": ["dividend", "IS", "shareCapital"], + "growth": ["IS", "CF", "productService", "rnd"], + "risk": ["contingentLiability", "sanction", "riskDerivative", "audit"], + "audit": ["audit", "auditSystem", "internalControl"], + "governance": ["majorHolder", "executive", "boardOfDirectors"], + "employee": ["employee", "executivePay"], + "subsidiary": ["subsidiary", "affiliateGroup", "investmentInOther"], + "capex": ["CF", "tangibleAsset"], + "operating": ["IS", "fsSummary", "segments"], +} + +# ์ž์—ฐ์–ด ์งˆ๋ฌธ ํŒจํ„ด +_NATURAL_LANG_MAP: dict[str, list[str]] = { + "๋ˆ": ["BS", "CF"], + "๋ฒŒ": ["IS", "fsSummary"], + "์ž˜": ["IS", "fsSummary", "segments"], + "์œ„ํ—˜": ["contingentLiability", "sanction", "riskDerivative", "audit", "internalControl"], + "์•ˆ์ „": ["BS", "audit", "contingentLiability", "internalControl"], + "๊ฑด๊ฐ•": ["BS", "IS", "CF", "audit"], + "์ „๋ง": ["IS", "CF", "rnd", "segments", "mdna"], + "๋น„๊ต": ["IS", "BS", "CF", "fsSummary"], + "์ถ”์„ธ": ["IS", "BS", "CF", "fsSummary"], + "ํŠธ๋ Œ๋“œ": ["IS", "BS", "CF", "fsSummary"], + "๋ถ„์„": ["BS", "IS", "CF", "fsSummary"], + "์–ด๋–ค ํšŒ์‚ฌ": ["companyOverviewDetail", "companyOverview", "business", "companyHistory"], + "๋ฌด์Šจ ์‚ฌ์—…": ["business", "productService", "segments", "companyOverviewDetail"], + "๋ญํ•˜๋Š”": ["business", "productService", "segments", "companyOverviewDetail"], + "์–ด๋–ค ์‚ฌ์—…": ["business", "productService", "segments", "companyOverviewDetail"], +} + +# ๋ณ‘ํ•ฉ: registry ํ‚ค์›Œ๋“œ โ†’ ์žฌ๋ฌด์ œํ‘œ โ†’ ๋ณตํ•ฉ โ†’ ์ž์—ฐ์–ด (ํ›„์ˆœ์œ„๊ฐ€ ์˜ค๋ฒ„๋ผ์ด๋“œ) +_TOPIC_MAP: dict[str, list[str]] = {**_KEYWORD_MAP, **_FINANCIAL_MAP, **_COMPOSITE_MAP, **_NATURAL_LANG_MAP} + +# ํ•ญ์ƒ ํฌํ•จ๋˜๋Š” ๊ธฐ๋ณธ ์ปจํ…์ŠคํŠธ +_BASE_CONTEXT = ["fsSummary"] + + +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• +# ํ† ํ”ฝ ๋งคํ•‘ +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• + + +def _resolve_tables(question: str, include: list[str] | None, exclude: list[str] | None) -> list[str]: + """์งˆ๋ฌธ๊ณผ include/exclude๋กœ ํฌํ•จํ•  ํ…Œ์ด๋ธ” ๋ชฉ๋ก ๊ฒฐ์ •. + + ๊ฐœ์„ : ๋Œ€์†Œ๋ฌธ์ž ๋ฌด์‹œ, ๋ถ€๋ถ„๋งค์นญ, ๋ณตํ•ฉ ํ‚ค์›Œ๋“œ ์ง€์›. + """ + tables: list[str] = list(_BASE_CONTEXT) + + if include: + tables.extend(include) + else: + q_lower = question.lower() + matched_count = 0 + + for keyword, table_names in _TOPIC_MAP.items(): + # ๋Œ€์†Œ๋ฌธ์ž ๋ฌด์‹œ ๋งค์นญ + if keyword.lower() in q_lower: + matched_count += 1 + for t in table_names: + if t not in tables: + tables.append(t) + + # ๋งคํ•‘ ์•ˆ ๋์œผ๋ฉด ๊ธฐ๋ณธ ์žฌ๋ฌด์ œํ‘œ ํฌํ•จ + if matched_count == 0: + tables.extend(["BS", "IS", "CF"]) + + # ๋„ˆ๋ฌด ๋งŽ์€ ๋ชจ๋“ˆ์ด ๋งค์นญ๋˜๋ฉด ์ƒ์œ„ ์šฐ์„ ์ˆœ์œ„๋งŒ (ํ† ํฐ ์ ˆ์•ฝ) + # ํ•ต์‹ฌ ๋ชจ๋“ˆ(BS/IS/CF/fsSummary)์€ ํ•ญ์ƒ ์œ ์ง€ + _CORE = {"fsSummary", "BS", "IS", "CF"} + if len(tables) > 12: + core = [t for t in tables if t in _CORE] + non_core = [t for t in tables if t not in _CORE] + tables = core + non_core[:8] + + if exclude: + tables = [t for t in tables if t not in exclude] + + return tables + + +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• +# ์ปจํ…์ŠคํŠธ ์กฐ๋ฆฝ +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• + + +def build_context( + company: Any, + question: str, + include: list[str] | None = None, + exclude: list[str] | None = None, + max_rows: int = 30, + compact: bool = False, +) -> tuple[str, list[str]]: + """์งˆ๋ฌธ๊ณผ Company ์ธ์Šคํ„ด์Šค๋กœ๋ถ€ํ„ฐ LLM context ํ…์ŠคํŠธ ์กฐ๋ฆฝ. + + Args: + compact: True๋ฉด ํ•ต์‹ฌ ๊ณ„์ •๋งŒ, ์–ต/์กฐ ๋‹จ์œ„, ๊ฐ„๊ฒฐ ํฌ๋งท (์†Œํ˜• ๋ชจ๋ธ์šฉ). + + Returns: + (context_text, included_table_names) + """ + from dartlab.ai.context.formatting import _KEY_ACCOUNTS_MAP + + tables_to_include = _resolve_tables(question, include, exclude) + + # fsSummary ์ค‘๋ณต ์ œ๊ฑฐ: BS+IS ๋‘˜ ๋‹ค ์žˆ์œผ๋ฉด fsSummary ์Šคํ‚ต + if compact and "fsSummary" in tables_to_include: + has_bs = "BS" in tables_to_include + has_is = "IS" in tables_to_include + if has_bs and has_is: + tables_to_include = [t for t in tables_to_include if t != "fsSummary"] + + from dartlab import config + + orig_verbose = config.verbose + config.verbose = False + + sections = [] + included = [] + + sections.append(f"# {company.corpName} ({company.stockCode})") + + try: + detail = getattr(company, "companyOverviewDetail", None) + if detail and isinstance(detail, dict): + info_parts = [] + if detail.get("ceo"): + info_parts.append(f"๋Œ€ํ‘œ: {detail['ceo']}") + if detail.get("mainBusiness"): + info_parts.append(f"์ฃผ์š”์‚ฌ์—…: {detail['mainBusiness']}") + if detail.get("foundedDate"): + info_parts.append(f"์„ค๋ฆฝ: {detail['foundedDate']}") + if info_parts: + sections.append("> " + " | ".join(info_parts)) + except _CONTEXT_ERRORS: + pass + + year_range = detect_year_range(company, tables_to_include) + if year_range: + sections.append( + f"\n**๋ฐ์ดํ„ฐ ๊ธฐ์ค€: {year_range['min_year']}~{year_range['max_year']}๋…„** (๊ฐ€์žฅ ์ตœ๊ทผ: {year_range['max_year']}๋…„)" + ) + if not compact: + sections.append("์ดํ›„ ๋ฐ์ดํ„ฐ๋Š” ํฌํ•จ๋˜์–ด ์žˆ์ง€ ์•Š์Šต๋‹ˆ๋‹ค.\n") + + if compact: + sections.append("\n๊ธˆ์•ก: ์–ต/์กฐ์› ํ‘œ์‹œ (์›๋ณธ ๋ฐฑ๋งŒ์›)\n") + else: + sections.append("") + sections.append("๋ชจ๋“  ๊ธˆ์•ก์€ ๋ณ„๋„ ํ‘œ๊ธฐ ์—†์œผ๋ฉด ๋ฐฑ๋งŒ์›(millions KRW) ๋‹จ์œ„์ž…๋‹ˆ๋‹ค.") + sections.append("") + + for name in tables_to_include: + try: + data = getattr(company, name, None) + if data is None: + continue + + if callable(data) and not isinstance(data, type): + try: + result = data() + if hasattr(result, "FS") and isinstance(getattr(result, "FS", None), pl.DataFrame): + data = result.FS + elif isinstance(result, pl.DataFrame): + data = result + else: + data = result + except _CONTEXT_ERRORS: + continue + + meta = MODULE_META.get(name) + label = meta.label if meta else name + desc = meta.description if meta else "" + + section_parts = [f"\n## {label}"] + if not compact and desc: + section_parts.append(desc) + + if isinstance(data, pl.DataFrame): + display_df = data + if compact and name in _KEY_ACCOUNTS_MAP: + display_df = _filter_key_accounts(data, name) + + md = df_to_markdown(display_df, max_rows=max_rows, meta=meta, compact=compact) + section_parts.append(md) + + derived = _compute_derived_metrics(name, data, company) + if derived: + section_parts.append(derived) + + elif isinstance(data, dict): + dict_lines = [] + for k, v in data.items(): + dict_lines.append(f"- {k}: {v}") + section_parts.append("\n".join(dict_lines)) + + elif isinstance(data, list): + effective_max = meta.maxRows if meta else 20 + if compact: + effective_max = min(effective_max, 10) + list_lines = [] + for item in data[:effective_max]: + if hasattr(item, "title") and hasattr(item, "chars"): + list_lines.append(f"- **{item.title}** ({item.chars}์ž)") + else: + list_lines.append(f"- {item}") + if len(data) > effective_max: + list_lines.append(f"(... ์ƒ์œ„ {effective_max}๊ฑด, ์ „์ฒด {len(data)}๊ฑด)") + section_parts.append("\n".join(list_lines)) + + else: + max_text = 1000 if compact else 2000 + section_parts.append(str(data)[:max_text]) + + if not compact and meta and meta.analysisHints: + hints = " | ".join(meta.analysisHints) + section_parts.append(f"> ๋ถ„์„ ํฌ์ธํŠธ: {hints}") + + sections.append("\n".join(section_parts)) + included.append(name) + + except _CONTEXT_ERRORS: + continue + + from dartlab.ai.conversation.prompts import _classify_question_multi + + _q_types = _classify_question_multi(question, max_types=2) if question else [] + report_sections = _build_report_sections(company, q_types=_q_types) + for key, section in report_sections.items(): + sections.append(section) + included.append(key) + + if not compact: + available_modules = scan_available_modules(company) + available_names = {m["name"] for m in available_modules} + not_included = available_names - set(included) + if not_included: + available_list = [] + for m in available_modules: + if m["name"] in not_included: + info = f"`{m['name']}` ({m['label']}" + if m.get("rows"): + info += f", {m['rows']}ํ–‰" + info += ")" + available_list.append(info) + if available_list: + sections.append( + "\n---\n### ์ถ”๊ฐ€ ์กฐํšŒ ๊ฐ€๋Šฅํ•œ ๋ฐ์ดํ„ฐ\n" + "์•„๋ž˜ ๋ฐ์ดํ„ฐ๋Š” ํ˜„์žฌ ํฌํ•จ๋˜์ง€ ์•Š์•˜์ง€๋งŒ `finance(action='data', module=...)` ๋„๊ตฌ๋กœ ์กฐํšŒํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค:\n" + + ", ".join(available_list[:15]) + ) + + # โ”€โ”€ ์ •๋ณด ๋ฐฐ์น˜ ์ตœ์ ํ™”: ํ•ต์‹ฌ ์ˆ˜์น˜๋ฅผ context ๋์— ๋ฐ˜๋ณต (Lost-in-the-Middle ๋Œ€์‘) โ”€โ”€ + key_facts = _build_key_facts_recap(company, included) + if key_facts: + sections.append(key_facts) + + config.verbose = orig_verbose + + return "\n".join(sections), included + + +def _build_key_facts_recap(company: Any, included: list[str]) -> str | None: + """context ๋์— ํ•ต์‹ฌ ์ˆ˜์น˜๋ฅผ ๊ฐ„๊ฒฐํ•˜๊ฒŒ ๋ฐ˜๋ณต โ€” Lost-in-the-Middle ๋ฌธ์ œ ๋Œ€์‘.""" + lines: list[str] = [] + + ratios = get_headline_ratios(company) + if ratios is not None and hasattr(ratios, "roe"): + facts = [] + if ratios.roe is not None: + facts.append(f"ROE {ratios.roe:.1f}%") + if ratios.operatingMargin is not None: + facts.append(f"์˜์—…์ด์ต๋ฅ  {ratios.operatingMargin:.1f}%") + if ratios.debtRatio is not None: + facts.append(f"๋ถ€์ฑ„๋น„์œจ {ratios.debtRatio:.1f}%") + if ratios.currentRatio is not None: + facts.append(f"์œ ๋™๋น„์œจ {ratios.currentRatio:.1f}%") + if ratios.fcf is not None: + facts.append(f"FCF {_format_won(ratios.fcf)}") + if facts: + lines.append("---") + lines.append(f"**[ํ•ต์‹ฌ ์ง€ํ‘œ ์š”์•ฝ] {' | '.join(facts)}**") + + # insight ๋“ฑ๊ธ‰ ์š”์•ฝ (์žˆ์œผ๋ฉด) + try: + from dartlab.analysis.financial.insight import analyze + + stockCode = getattr(company, "stockCode", None) + if stockCode: + result = analyze(stockCode, company=company) + if result is not None: + grades = result.grades() + grade_parts = [f"{k}={v}" for k, v in grades.items() if v != "N"] + if grade_parts: + lines.append(f"**[์ธ์‚ฌ์ดํŠธ ๋“ฑ๊ธ‰] {result.profile} โ€” {', '.join(grade_parts[:5])}**") + except (ImportError, AttributeError, KeyError, OSError, RuntimeError, TypeError, ValueError): + pass + + if not lines: + return None + return "\n".join(lines) + + +def _build_change_summary(company: Any, max_topics: int = 5) -> str | None: + """๊ธฐ๊ฐ„๊ฐ„ ๋ณ€ํ™”๊ฐ€ ํฐ topic top-N์„ ์ž๋™ ์š”์•ฝํ•˜์—ฌ AI ์ปจํ…์ŠคํŠธ์— ์ œ๊ณต.""" + try: + diff_df = company.diff() + except _CONTEXT_ERRORS: + return None + + if diff_df is None or (isinstance(diff_df, pl.DataFrame) and diff_df.is_empty()): + return None + + if not isinstance(diff_df, pl.DataFrame): + return None + + # changeRate > 0 ์ธ topic๋งŒ ํ•„ํ„ฐ, ์ƒ์œ„ N๊ฐœ + if "changeRate" not in diff_df.columns or "topic" not in diff_df.columns: + return None + + changed = diff_df.filter(pl.col("changeRate") > 0).sort("changeRate", descending=True) + if changed.is_empty(): + return None + + top = changed.head(max_topics) + lines = [ + "\n## ์ฃผ์š” ๋ณ€ํ™” (์ตœ๊ทผ ๊ณต์‹œ vs ์ง์ „)", + "| topic | ๋ณ€ํ™”์œจ | ๊ธฐ๊ฐ„์ˆ˜ |", + "| --- | --- | --- |", + ] + for row in top.iter_rows(named=True): + rate_pct = round(row["changeRate"] * 100, 1) + periods = row.get("periods", "") + lines.append(f"| `{row['topic']}` | {rate_pct}% | {periods} |") + + lines.append("") + lines.append( + "๊นŠ์ด ๋ถ„์„์ด ํ•„์š”ํ•˜๋ฉด `explore(action='show', topic=topic)`์œผ๋กœ ์›๋ฌธ์„, `explore(action='diff', topic=topic)`์œผ๋กœ ์ƒ์„ธ ๋ณ€ํ™”๋ฅผ ํ™•์ธํ•˜์„ธ์š”." + ) + return "\n".join(lines) + + +def _build_topics_section(company: Any, compact: bool = False) -> str | None: + """Company์˜ topics ๋ชฉ๋ก์„ LLM์ด ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋Š” ๋งˆํฌ๋‹ค์šด์œผ๋กœ ๋ณ€ํ™˜. + + dartlab์— topic์ด ์ถ”๊ฐ€๋˜๋ฉด ์ž๋™์œผ๋กœ LLM ์ปจํ…์ŠคํŠธ์— ํฌํ•จ๋œ๋‹ค. + + Args: + compact: True๋ฉด ์ƒ์œ„ 10๊ฐœ + ์ด ๊ฐœ์ˆ˜ ์š”์•ฝ (93% ํ† ํฐ ์ ˆ๊ฐ) + """ + topics = getattr(company, "topics", None) + if topics is None: + return None + if isinstance(topics, pl.DataFrame): + if "topic" not in topics.columns: + return None + topic_list = [topic for topic in topics["topic"].drop_nulls().to_list() if isinstance(topic, str) and topic] + elif isinstance(topics, pl.Series): + topic_list = [topic for topic in topics.drop_nulls().to_list() if isinstance(topic, str) and topic] + elif isinstance(topics, list): + topic_list = [topic for topic in topics if isinstance(topic, str) and topic] + else: + try: + topic_list = [topic for topic in list(topics) if isinstance(topic, str) and topic] + except TypeError: + return None + if not topic_list: + return None + + if compact: + top10 = topic_list[:10] + return ( + f"\n## ๊ณต์‹œ topic ({len(topic_list)}๊ฐœ)\n" + f"์ฃผ์š”: {', '.join(top10)}\n" + f"์ „์ฒด ๋ชฉ๋ก์€ `explore(action='topics')` ๋„๊ตฌ๋กœ ์กฐํšŒํ•˜์„ธ์š”." + ) + + lines = [ + "\n## ์กฐํšŒ ๊ฐ€๋Šฅํ•œ ๊ณต์‹œ topic ๋ชฉ๋ก", + "`explore(action='show', topic=...)` ๋„๊ตฌ์— ์•„๋ž˜ topic์„ ๋„ฃ์œผ๋ฉด ์ƒ์„ธ ๋ฐ์ดํ„ฐ๋ฅผ ์กฐํšŒํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค.", + "", + ] + + # index๊ฐ€ ์žˆ์œผ๋ฉด label ์ •๋ณด ํฌํ•จ + index_df = getattr(company, "index", None) + if isinstance(index_df, pl.DataFrame) and index_df.height > 0: + label_col = "label" if "label" in index_df.columns else None + source_col = "source" if "source" in index_df.columns else None + for row in index_df.head(60).iter_rows(named=True): + topic = row.get("topic", "") + label = row.get(label_col, topic) if label_col else topic + source = row.get(source_col, "") if source_col else "" + lines.append(f"- `{topic}` ({label}) [{source}]") + else: + for t in topic_list[:60]: + lines.append(f"- `{t}`") + + return "\n".join(lines) + + +def _build_insights_section(company: Any) -> str | None: + """Company์˜ 7์˜์—ญ ์ธ์‚ฌ์ดํŠธ ๋“ฑ๊ธ‰์„ ์ปจํ…์ŠคํŠธ์— ์ž๋™ ํฌํ•จ.""" + stockCode = getattr(company, "stockCode", None) + if not stockCode: + return None + + try: + from dartlab.analysis.financial.insight.pipeline import analyze + + result = analyze(stockCode, company=company) + except (ImportError, AttributeError, FileNotFoundError, OSError, RuntimeError, TypeError, ValueError): + return None + if result is None: + return None + + area_labels = { + "performance": "์‹ค์ ", + "profitability": "์ˆ˜์ต์„ฑ", + "health": "๊ฑด์ „์„ฑ", + "cashflow": "ํ˜„๊ธˆํ๋ฆ„", + "governance": "์ง€๋ฐฐ๊ตฌ์กฐ", + "risk": "๋ฆฌ์Šคํฌ", + "opportunity": "๊ธฐํšŒ", + } + + lines = [ + "\n## ์ธ์‚ฌ์ดํŠธ ๋“ฑ๊ธ‰ (์ž๋™ ๋ถ„์„)", + f"ํ”„๋กœํŒŒ์ผ: **{result.profile}**", + "", + "| ์˜์—ญ | ๋“ฑ๊ธ‰ | ์š”์•ฝ |", + "| --- | --- | --- |", + ] + for key, label in area_labels.items(): + ir = getattr(result, key, None) + grade = result.grades().get(key, "N") + summary = ir.summary if ir else "-" + lines.append(f"| {label} | {grade} | {summary} |") + + if result.anomalies: + lines.append("") + lines.append("### ์ด์ƒ์น˜ ๊ฒฝ๊ณ ") + for a in result.anomalies[:5]: + lines.append(f"- [{a.severity}] {a.text}") + + if result.summary: + lines.append(f"\n{result.summary}") + + return "\n".join(lines) + + +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• +# Tiered Context Pipeline +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• + +# skeleton tier์—์„œ ์‚ฌ์šฉํ•  ํ•ต์‹ฌ ratios ํ‚ค +_SKELETON_RATIO_KEYS = ("roe", "debtRatio", "currentRatio", "operatingMargin", "fcf", "revenueGrowth3Y") + +# skeleton tier์—์„œ ์‚ฌ์šฉํ•  ํ•ต์‹ฌ ๊ณ„์ • (๋งค์ถœ/์˜์—…์ด์ต/์ด์ž์‚ฐ) +_SKELETON_ACCOUNTS_KR: dict[str, list[tuple[str, str]]] = { + "IS": [("sales", "๋งค์ถœ์•ก"), ("operating_profit", "์˜์—…์ด์ต")], + "BS": [("total_assets", "์ž์‚ฐ์ด๊ณ„")], +} +_SKELETON_ACCOUNTS_EN: dict[str, list[tuple[str, str]]] = { + "IS": [("sales", "Revenue"), ("operating_profit", "Operating Income")], + "BS": [("total_assets", "Total Assets")], +} + + +def build_context_skeleton(company: Any) -> tuple[str, list[str]]: + """skeleton tier: ~500 ํ† ํฐ. tool calling provider์šฉ ์ตœ์†Œ ์ปจํ…์ŠคํŠธ. + + ํ•ต์‹ฌ ๋น„์œจ 6๊ฐœ + ๋งค์ถœ/์˜์—…์ด์ต/์ด์ž์‚ฐ 3๊ณ„์ • + insight ๋“ฑ๊ธ‰ 1์ค„. + ์ƒ์„ธ ๋ฐ์ดํ„ฐ๋Š” ๋„๊ตฌ๋กœ ์กฐํšŒํ•˜๋„๋ก ์•ˆ๋‚ด. + EDGAR(US) / DART(KR) ์ž๋™ ๊ฐ์ง€. + """ + market = getattr(company, "market", "KR") + is_us = market == "US" + fmt_val = _format_usd if is_us else _format_won + skel_accounts = _SKELETON_ACCOUNTS_EN if is_us else _SKELETON_ACCOUNTS_KR + unit_label = "USD" if is_us else "์–ต/์กฐ์›" + + parts = [f"# {company.corpName} ({company.stockCode})"] + if is_us: + parts[0] += " | Market: US (SEC EDGAR) | Currency: USD" + parts.append("โš ๏ธ ์•„๋ž˜๋Š” ์ฐธ๊ณ ์šฉ ์š”์•ฝ์ž…๋‹ˆ๋‹ค. ์งˆ๋ฌธ์— ๋‹ตํ•˜๋ ค๋ฉด ๋ฐ˜๋“œ์‹œ ๋„๊ตฌ(explore/finance)๋กœ ์ƒ์„ธ ๋ฐ์ดํ„ฐ๋ฅผ ์กฐํšŒํ•˜์„ธ์š”.") + included = [] + + # ํ•ต์‹ฌ ๊ณ„์ • 3๊ฐœ (์ตœ๊ทผ 3๋…„) + annual = getattr(company, "annual", None) + if annual is not None: + series, years = annual + quarter_counts = _get_quarter_counts(company) + if years: + display_years = years[-3:] + display_labeled = [] + for y in display_years: + qc = quarter_counts.get(y, 4) + if qc < 4: + display_labeled.append(f"{y}(~Q{qc})") + else: + display_labeled.append(y) + display_reversed = list(reversed(display_labeled)) + year_offset = len(years) - 3 + + col_header = "Account" if is_us else "๊ณ„์ •" + header = f"| {col_header} | " + " | ".join(display_reversed) + " |" + sep = "| --- | " + " | ".join(["---"] * len(display_reversed)) + " |" + rows = [] + for sj, accts in skel_accounts.items(): + sj_data = series.get(sj, {}) + for snake_id, label in accts: + vals = sj_data.get(snake_id) + if not vals: + continue + sliced = vals[max(0, year_offset) :] + cells = [fmt_val(v) if v is not None else "-" for v in reversed(sliced)] + rows.append(f"| {label} | " + " | ".join(cells) + " |") + + if rows: + partial = [y for y in display_years if quarter_counts.get(y, 4) < 4] + partial_note = "" + if partial: + notes = ", ".join(f"{y}=Q1~Q{quarter_counts[y]}" for y in partial) + partial_note = f"\nโš ๏ธ {'Partial year' if is_us else '๋ถ€๋ถ„ ์—ฐ๋„'}: {notes}" + section_title = f"Key Financials ({unit_label})" if is_us else f"ํ•ต์‹ฌ ์ˆ˜์น˜ ({unit_label})" + parts.extend(["", f"## {section_title}{partial_note}", header, sep, *rows]) + included.extend(["IS", "BS"]) + + # ํ•ต์‹ฌ ๋น„์œจ 6๊ฐœ + ratios = get_headline_ratios(company) + if ratios is not None and hasattr(ratios, "roe"): + ratio_lines = [] + for key in _SKELETON_RATIO_KEYS: + val = getattr(ratios, key, None) + if val is None: + continue + label_map_kr = { + "roe": "ROE", + "debtRatio": "๋ถ€์ฑ„๋น„์œจ", + "currentRatio": "์œ ๋™๋น„์œจ", + "operatingMargin": "์˜์—…์ด์ต๋ฅ ", + "fcf": "FCF", + "revenueGrowth3Y": "๋งค์ถœ3Y CAGR", + } + label_map_en = { + "roe": "ROE", + "debtRatio": "Debt Ratio", + "currentRatio": "Current Ratio", + "operatingMargin": "Op. Margin", + "fcf": "FCF", + "revenueGrowth3Y": "Rev. 3Y CAGR", + } + label = (label_map_en if is_us else label_map_kr).get(key, key) + if key == "fcf": + ratio_lines.append(f"- {label}: {fmt_val(val)}") + else: + ratio_lines.append(f"- {label}: {val:.1f}%") + if ratio_lines: + section_title = "Key Ratios" if is_us else "ํ•ต์‹ฌ ๋น„์œจ" + parts.extend(["", f"## {section_title}", *ratio_lines]) + included.append("ratios") + + # ๋ถ„์„ ๊ฐ€์ด๋“œ + if is_us: + parts.extend( + [ + "", + "## DartLab Analysis Guide", + "All filing data is structured as **sections** (topic ร— period horizontalization).", + "- `explore(action='topics')` โ†’ full topic list | `explore(action='show', topic=...)` โ†’ block index โ†’ data", + "- `explore(action='search', keyword=...)` โ†’ original filing text for citations", + "- `explore(action='diff', topic=...)` โ†’ period-over-period changes | `explore(action='trace', topic=...)` โ†’ source provenance", + "- `finance(action='data', module='BS/IS/CF')` โ†’ financials | `finance(action='ratios')` โ†’ ratios", + "- `analyze(action='insight')` โ†’ 7-area grades | `explore(action='coverage')` โ†’ data availability", + "", + "**Note**: This is a US company (SEC EDGAR). No `report` namespace โ€” all narrative data via sections.", + "**Procedure**: Understand question โ†’ explore topics โ†’ retrieve data โ†’ cross-verify โ†’ synthesize answer", + ] + ) + else: + parts.extend( + [ + "", + "## DartLab ๋ถ„์„ ๊ฐ€์ด๋“œ", + "์ด ๊ธฐ์—…์˜ ๋ชจ๋“  ๊ณต์‹œ ๋ฐ์ดํ„ฐ๋Š” **sections** (topic ร— ๊ธฐ๊ฐ„ ์ˆ˜ํ‰ํ™”)์œผ๋กœ ๊ตฌ์กฐํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค.", + "- `explore(action='topics')` โ†’ ์ „์ฒด topic ๋ชฉ๋ก (ํ‰๊ท  120+๊ฐœ)", + "- `explore(action='show', topic=...)` โ†’ ๋ธ”๋ก ๋ชฉ์ฐจ โ†’ ์‹ค์ œ ๋ฐ์ดํ„ฐ", + "- `explore(action='search', keyword=...)` โ†’ ์›๋ฌธ ์ฆ๊ฑฐ ๊ฒ€์ƒ‰ (์ธ์šฉ์šฉ)", + "- `explore(action='diff', topic=...)` โ†’ ๊ธฐ๊ฐ„๊ฐ„ ๋ณ€ํ™” | `explore(action='trace', topic=...)` โ†’ ์ถœ์ฒ˜ ์ถ”์ ", + "- `finance(action='data', module='BS/IS/CF')` โ†’ ์žฌ๋ฌด์ œํ‘œ | `finance(action='ratios')` โ†’ ์žฌ๋ฌด๋น„์œจ", + "- `analyze(action='insight')` โ†’ 7์˜์—ญ ์ข…ํ•ฉ ๋“ฑ๊ธ‰ | `explore(action='report', apiType=...)` โ†’ ์ •๊ธฐ๋ณด๊ณ ์„œ", + "", + "**๋ถ„์„ ์ ˆ์ฐจ**: ์งˆ๋ฌธ ์ดํ•ด โ†’ ๊ด€๋ จ topic ํƒ์ƒ‰ โ†’ ์›๋ฌธ ๋ฐ์ดํ„ฐ ์กฐํšŒ โ†’ ๊ต์ฐจ ๊ฒ€์ฆ โ†’ ์ข…ํ•ฉ ๋‹ต๋ณ€", + "**ํ•ต์‹ฌ**: '๋ฐ์ดํ„ฐ ์—†์Œ'์œผ๋กœ ๋‹ตํ•˜๊ธฐ ์ „์— ๋ฐ˜๋“œ์‹œ ๋„๊ตฌ๋กœ ํ™•์ธ. sections์— ๊ฑฐ์˜ ๋ชจ๋“  ๊ณต์‹œ ๋ฐ์ดํ„ฐ๊ฐ€ ์žˆ์Šต๋‹ˆ๋‹ค.", + ] + ) + + return "\n".join(parts), included + + +def build_context_focused( + company: Any, + question: str, + include: list[str] | None = None, + exclude: list[str] | None = None, +) -> tuple[dict[str, str], list[str], str]: + """focused tier: ~2,000 ํ† ํฐ. tool calling ๋ฏธ์ง€์› provider์šฉ. + + skeleton + ์งˆ๋ฌธ ์œ ํ˜•๋ณ„ ๊ด€๋ จ ๋ชจ๋“ˆ๋งŒ ํฌํ•จ (compact ํ˜•์‹). + """ + return build_context_by_module(company, question, include, exclude, compact=True) + + +ContextTier = str # "skeleton" | "focused" | "full" + + +def build_context_tiered( + company: Any, + question: str, + tier: ContextTier, + include: list[str] | None = None, + exclude: list[str] | None = None, +) -> tuple[dict[str, str], list[str], str]: + """tier๋ณ„ context ๋นŒ๋”. streaming.py์—์„œ ํ˜ธ์ถœ. + + Args: + tier: "skeleton" | "focused" | "full" + + Returns: + (modules_dict, included_list, header_text) + """ + if tier == "skeleton": + text, included = build_context_skeleton(company) + return {"_skeleton": text}, included, "" + elif tier == "focused": + return build_context_focused(company, question, include, exclude) + else: + return build_context_by_module(company, question, include, exclude, compact=False) diff --git a/src/dartlab/ai/context/company_adapter.py b/src/dartlab/ai/context/company_adapter.py new file mode 100644 index 0000000000000000000000000000000000000000..fae2a11d881fe14d4819435aa4279c711eda6dd2 --- /dev/null +++ b/src/dartlab/ai/context/company_adapter.py @@ -0,0 +1,86 @@ +"""Facade adapter helpers for AI runtime. + +AI layer๋Š” `dartlab.Company` facade์™€ ์—”์ง„ ๋‚ด๋ถ€ ๊ตฌํ˜„ ์ฐจ์ด๋ฅผ ์ง์ ‘ ์•Œ์ง€ ์•Š๋Š”๋‹ค. +์ด ๋ชจ๋“ˆ์—์„œ headline ratios / ratio series ๊ฐ™์€ surface ์ฐจ์ด๋ฅผ ํก์ˆ˜ํ•œ๋‹ค. +""" + +from __future__ import annotations + +from types import SimpleNamespace +from typing import Any + +_ADAPTER_ERRORS = ( + AttributeError, + KeyError, + OSError, + RuntimeError, + TypeError, + ValueError, +) + + +class _RatioProxy: + """๋ˆ„๋ฝ ์†์„ฑ์€ None์œผ๋กœ ํก์ˆ˜ํ•˜๋Š” lightweight ratio adapter.""" + + def __init__(self, inner: Any): + self._inner = inner + + def __getattr__(self, name: str) -> Any: + return getattr(self._inner, name, None) + + +def get_headline_ratios(company: Any) -> Any | None: + """Return RatioResult-like object regardless of facade surface.""" + # ๋‚ด๋ถ€์šฉ _getRatiosInternal ์šฐ์„  (deprecation warning ์—†์Œ) + internal = getattr(company, "_getRatiosInternal", None) + getter = internal if callable(internal) else getattr(company, "getRatios", None) + if callable(getter): + try: + result = getter() + if result is not None and hasattr(result, "roe"): + return _RatioProxy(result) + except _ADAPTER_ERRORS: + pass + + finance = getattr(company, "finance", None) + finance_getter = getattr(finance, "getRatios", None) + if callable(finance_getter): + try: + result = finance_getter() + if result is not None and hasattr(result, "roe"): + return _RatioProxy(result) + except _ADAPTER_ERRORS: + pass + + for candidate in ( + getattr(company, "ratios", None), + getattr(finance, "ratios", None), + ): + if candidate is not None and hasattr(candidate, "roe"): + return _RatioProxy(candidate) + + return None + + +def get_ratio_series(company: Any) -> Any | None: + """Return attribute-style ratio series regardless of tuple/object surface.""" + for candidate in ( + getattr(company, "ratioSeries", None), + getattr(getattr(company, "finance", None), "ratioSeries", None), + ): + if candidate is None: + continue + if hasattr(candidate, "roe"): + return candidate + if isinstance(candidate, tuple) and len(candidate) == 2: + series, periods = candidate + if not isinstance(series, dict): + continue + ratio_series = series.get("RATIO", {}) + if not isinstance(ratio_series, dict) or not ratio_series: + continue + adapted = SimpleNamespace(periods=periods) + for key, values in ratio_series.items(): + setattr(adapted, key, values) + return adapted + return None diff --git a/src/dartlab/ai/context/dartOpenapi.py b/src/dartlab/ai/context/dartOpenapi.py new file mode 100644 index 0000000000000000000000000000000000000000..3d8dd4b137c565f3e9cd837826d871d060ead6f7 --- /dev/null +++ b/src/dartlab/ai/context/dartOpenapi.py @@ -0,0 +1,485 @@ +"""OpenDART ๊ณต์‹œ๋ชฉ๋ก retrieval helper. + +ํšŒ์‚ฌ ๋ฏธ์„ ํƒ ์งˆ๋ฌธ์—์„œ๋„ ์ตœ๊ทผ ๊ณต์‹œ๋ชฉ๋ก/์ˆ˜์ฃผ๊ณต์‹œ/๊ณ„์•ฝ๊ณต์‹œ๋ฅผ +deterministic prefetch๋กœ ํšŒ์ˆ˜ํ•ด AI ์ปจํ…์ŠคํŠธ๋กœ ์ฃผ์ž…ํ•œ๋‹ค. +""" + +from __future__ import annotations + +import re +from dataclasses import dataclass +from datetime import date, timedelta +from html import unescape +from typing import Any + +import polars as pl + +from dartlab.ai.context.formatting import df_to_markdown +from dartlab.core.capabilities import UiAction +from dartlab.providers.dart.openapi.dartKey import hasDartApiKey + +_FILING_TERMS = ( + "๊ณต์‹œ", + "์ „์ž๊ณต์‹œ", + "๊ณต์‹œ๋ชฉ๋ก", + "๊ณต์‹œ ๋ฆฌ์ŠคํŠธ", + "์ˆ˜์ฃผ๊ณต์‹œ", + "๊ณ„์•ฝ๊ณต์‹œ", + "๋‹จ์ผํŒ๋งค๊ณต๊ธ‰๊ณ„์•ฝ", + "๊ณต๊ธ‰๊ณ„์•ฝ", + "ํŒ๋งค๊ณต๊ธ‰๊ณ„์•ฝ", + "์ˆ˜์ฃผ", +) +_REQUEST_TERMS = ( + "์•Œ๋ ค", + "๋ณด์—ฌ", + "์ฐพ์•„", + "์ •๋ฆฌ", + "์š”์•ฝ", + "๋ถ„์„", + "๊ณจ๋ผ", + "์ถ”์ฒœ", + "๋ฌด์Šจ", + "๋ญ ์žˆ์—ˆ", + "๋ฆฌ์ŠคํŠธ", + "๋ชฉ๋ก", +) +_DETAIL_TERMS = ( + "์š”์•ฝ", + "๋ถ„์„", + "ํ•ต์‹ฌ", + "์ค‘์š”", + "์ฝ์„", + "๋ฆฌ์Šคํฌ", + "๋‚ด์šฉ", + "๋ฌด์Šจ ๋‚ด์šฉ", + "๊ผญ", +) +_READ_TERMS = ( + "์ฝ์–ด", + "๋ณธ๋ฌธ", + "์›๋ฌธ", + "์ „๋ฌธ", + "์ž์„ธํžˆ ๋ณด์—ฌ", + "๋‚ด์šฉ ๋ณด์—ฌ", +) +_ANALYSIS_ONLY_TERMS = ( + "๊ทผ๊ฑฐ", + "์™œ", + "์ง€์† ๊ฐ€๋Šฅ", + "์ง€์†๊ฐ€๋Šฅ", + "ํŒ๋‹จ", + "ํ‰๊ฐ€", + "ํ•ด์„", + "์‚ฌ์—…๊ตฌ์กฐ", + "๊ตฌ์กฐ", + "์˜ํ–ฅ", + "๋ณ€ํ™”", +) +_ORDER_KEYWORDS = ( + "๋‹จ์ผํŒ๋งค๊ณต๊ธ‰๊ณ„์•ฝ", + "ํŒ๋งค๊ณต๊ธ‰๊ณ„์•ฝ", + "๊ณต๊ธ‰๊ณ„์•ฝ", + "์ˆ˜์ฃผ", +) +_DISCLOSURE_TYPE_HINTS = { + "์ •๊ธฐ๊ณต์‹œ": "A", + "์ฃผ์š”์‚ฌํ•ญ": "B", + "์ฃผ์š”์‚ฌํ•ญ๋ณด๊ณ ": "B", + "๋ฐœํ–‰๊ณต์‹œ": "C", + "์ง€๋ถ„๊ณต์‹œ": "D", + "๊ธฐํƒ€๊ณต์‹œ": "E", + "์™ธ๋ถ€๊ฐ์‚ฌ": "F", + "ํŽ€๋“œ๊ณต์‹œ": "G", + "์ž์‚ฐ์œ ๋™ํ™”": "H", + "๊ฑฐ๋ž˜์†Œ๊ณต์‹œ": "I", + "๊ณต์ •์œ„๊ณต์‹œ": "J", +} +_MARKET_HINTS = { + "์ฝ”์Šคํ”ผ": "Y", + "์œ ๊ฐ€์ฆ๊ถŒ": "Y", + "์ฝ”์Šค๋‹ฅ": "K", + "์ฝ”๋„ฅ์Šค": "N", +} +_DEFAULT_LIMIT = 20 +_DEFAULT_DAYS = 7 + + +@dataclass(frozen=True) +class DartFilingIntent: + matched: bool = False + corp: str | None = None + start: str = "" + end: str = "" + disclosureType: str | None = None + market: str | None = None + finalOnly: bool = False + limit: int = _DEFAULT_LIMIT + titleKeywords: tuple[str, ...] = () + includeText: bool = False + textLimit: int = 0 + + +@dataclass(frozen=True) +class DartFilingPrefetch: + matched: bool + needsKey: bool = False + message: str = "" + contextText: str = "" + uiAction: dict[str, Any] | None = None + filings: pl.DataFrame | None = None + intent: DartFilingIntent | None = None + + +def buildMissingDartKeyMessage() -> str: + return ( + "OpenDART API ํ‚ค๊ฐ€ ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค.\n" + "- ์ด ์งˆ๋ฌธ์€ ์‹ค์‹œ๊ฐ„ ๊ณต์‹œ๋ชฉ๋ก ์กฐํšŒ๊ฐ€ ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค.\n" + "- ์„ค์ •์—์„œ `OpenDART API ํ‚ค`๋ฅผ ์ €์žฅํ•˜๋ฉด ์ตœ๊ทผ ๊ณต์‹œ, ์ˆ˜์ฃผ๊ณต์‹œ, ๊ณ„์•ฝ๊ณต์‹œ๋ฅผ ๋ฐ”๋กœ ๊ฒ€์ƒ‰ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค.\n" + "- ํ‚ค๋Š” ํ”„๋กœ์ ํŠธ ๋ฃจํŠธ `.env`์˜ `DART_API_KEY`๋กœ ์ €์žฅ๋ฉ๋‹ˆ๋‹ค." + ) + + +def buildMissingDartKeyUiAction() -> dict[str, Any]: + return UiAction.update( + "settings", + { + "open": True, + "section": "openDart", + "message": "OpenDART API ํ‚ค๋ฅผ ์„ค์ •ํ•˜๋ฉด ์ตœ๊ทผ ๊ณต์‹œ๋ชฉ๋ก์„ ๋ฐ”๋กœ ๊ฒ€์ƒ‰ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค.", + }, + ).to_payload() + + +def isDartFilingQuestion(question: str) -> bool: + q = (question or "").strip() + if not q: + return False + normalized = q.replace(" ", "") + if any(term in normalized for term in ("openapi", "opendart", "dartapi")) and not any( + term in q for term in _FILING_TERMS + ): + return False + has_filing_term = any(term in q for term in _FILING_TERMS) + has_request_term = any(term in q for term in _REQUEST_TERMS) + has_time_term = any(term in q for term in ("์ตœ๊ทผ", "์˜ค๋Š˜", "์–ด์ œ", "์ด๋ฒˆ ์ฃผ", "์ง€๋‚œ ์ฃผ", "์ด๋ฒˆ ๋‹ฌ", "๋ฉฐ์น ", "๋ช‡์ผ")) + has_read_term = any(term in q for term in _READ_TERMS) + has_analysis_only_term = any(term in q for term in _ANALYSIS_ONLY_TERMS) + + if ( + has_analysis_only_term + and not has_read_term + and not any(term in q for term in ("๋ชฉ๋ก", "๋ฆฌ์ŠคํŠธ", "๋ญ ์žˆ์—ˆ", "๋ฌด์Šจ ๊ณต์‹œ")) + ): + return False + + return has_filing_term and (has_request_term or has_time_term or has_read_term or "?" not in q) + + +def detectDartFilingIntent(question: str, company: Any | None = None) -> DartFilingIntent: + if not isDartFilingQuestion(question): + return DartFilingIntent() + + today = date.today() + start_date, end_date = _resolve_date_window(question, today) + title_keywords = _resolve_title_keywords(question) + include_text = any(term in question for term in _DETAIL_TERMS) or any(term in question for term in _READ_TERMS) + limit = _resolve_limit(question) + corp = None + if company is not None: + corp = getattr(company, "stockCode", None) or getattr(company, "corpName", None) + + disclosure_type = None + for hint, code in _DISCLOSURE_TYPE_HINTS.items(): + if hint in question: + disclosure_type = code + break + + market = None + for hint, code in _MARKET_HINTS.items(): + if hint in question: + market = code + break + + final_only = any(term in question for term in ("์ตœ์ข…", "์ •์ • ์ œ์™ธ", "์ •์ •์—†๋Š”", "์ •์ • ์—†๋Š”")) + text_limit = 3 if include_text and limit <= 5 else (2 if include_text else 0) + + return DartFilingIntent( + matched=True, + corp=corp, + start=start_date.strftime("%Y%m%d"), + end=end_date.strftime("%Y%m%d"), + disclosureType=disclosure_type, + market=market, + finalOnly=final_only, + limit=limit, + titleKeywords=title_keywords, + includeText=include_text, + textLimit=text_limit, + ) + + +def searchDartFilings( + *, + corp: str | None = None, + start: str | None = None, + end: str | None = None, + days: int | None = None, + weeks: int | None = None, + disclosureType: str | None = None, + market: str | None = None, + finalOnly: bool = False, + titleKeywords: list[str] | tuple[str, ...] | None = None, + limit: int = _DEFAULT_LIMIT, +) -> pl.DataFrame: + from dartlab import OpenDart + + if not hasDartApiKey(): + raise ValueError(buildMissingDartKeyMessage()) + + resolved_start, resolved_end = _coerce_search_window(start, end, days=days, weeks=weeks) + dart = OpenDart() + filings = dart.filings( + corp=corp, + start=resolved_start, + end=resolved_end, + type=disclosureType, + final=finalOnly, + market=market, + ) + if filings is None or filings.height == 0: + return pl.DataFrame() + + df = filings + if titleKeywords and "report_nm" in df.columns: + mask = pl.lit(False) + for keyword in titleKeywords: + mask = mask | pl.col("report_nm").str.contains(keyword, literal=True) + df = df.filter(mask) + + if df.height == 0: + return pl.DataFrame() + + sort_cols = [col for col in ("rcept_dt", "rcept_no") if col in df.columns] + if sort_cols: + descending = [True] * len(sort_cols) + df = df.sort(sort_cols, descending=descending) + + return df.head(max(1, min(limit, 100))) + + +def getDartFilingText(rceptNo: str, maxChars: int = 4000) -> str: + from dartlab import OpenDart + + if not rceptNo: + raise ValueError("rcept_no๊ฐ€ ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค.") + if not hasDartApiKey(): + raise ValueError(buildMissingDartKeyMessage()) + + raw_text = OpenDart().documentText(rceptNo) + return cleanDartFilingText(raw_text, maxChars=maxChars) + + +def buildDartFilingPrefetch(question: str, company: Any | None = None) -> DartFilingPrefetch: + intent = detectDartFilingIntent(question, company=company) + if not intent.matched: + return DartFilingPrefetch(matched=False) + if not hasDartApiKey(): + return DartFilingPrefetch( + matched=True, + needsKey=True, + message=buildMissingDartKeyMessage(), + uiAction=buildMissingDartKeyUiAction(), + intent=intent, + ) + + filings = searchDartFilings( + corp=intent.corp, + start=intent.start, + end=intent.end, + disclosureType=intent.disclosureType, + market=intent.market, + finalOnly=intent.finalOnly, + titleKeywords=intent.titleKeywords, + limit=intent.limit, + ) + context_text = formatDartFilingContext(filings, intent, question=question) + if intent.includeText and filings.height > 0 and "rcept_no" in filings.columns: + detail_blocks = [] + for rcept_no in filings["rcept_no"].head(intent.textLimit).to_list(): + try: + excerpt = getDartFilingText(str(rcept_no), maxChars=1800) + except (OSError, RuntimeError, ValueError): + continue + detail_blocks.append(f"### ์ ‘์ˆ˜๋ฒˆํ˜ธ {rcept_no} ์›๋ฌธ ๋ฐœ์ทŒ\n{excerpt}") + if detail_blocks: + context_text = "\n\n".join([context_text, *detail_blocks]) if context_text else "\n\n".join(detail_blocks) + + return DartFilingPrefetch( + matched=True, + needsKey=False, + contextText=context_text, + filings=filings, + intent=intent, + ) + + +def formatDartFilingContext( + filings: pl.DataFrame, + intent: DartFilingIntent, + *, + question: str = "", +) -> str: + if intent.start or intent.end: + window_label = f"{_format_date(intent.start or intent.end)} ~ {_format_date(intent.end or intent.start)}" + else: + window_label = "์ž๋™ ๊ธฐ๋ณธ ๋ฒ”์œ„" + lines = ["## OpenDART ๊ณต์‹œ๋ชฉ๋ก ๊ฒ€์ƒ‰ ๊ฒฐ๊ณผ", f"- ๊ธฐ๊ฐ„: {window_label}"] + if intent.corp: + lines.append(f"- ํšŒ์‚ฌ ํ•„ํ„ฐ: {intent.corp}") + else: + lines.append("- ํšŒ์‚ฌ ํ•„ํ„ฐ: ์ „์ฒด ์‹œ์žฅ") + if intent.market: + lines.append(f"- ์‹œ์žฅ ํ•„ํ„ฐ: {intent.market}") + if intent.disclosureType: + lines.append(f"- ๊ณต์‹œ์œ ํ˜•: {intent.disclosureType}") + if intent.finalOnly: + lines.append("- ์ตœ์ข…๋ณด๊ณ ์„œ๋งŒ ํฌํ•จ") + if intent.titleKeywords: + lines.append(f"- ์ œ๋ชฉ ํ‚ค์›Œ๋“œ: {', '.join(intent.titleKeywords)}") + if question: + lines.append(f"- ์‚ฌ์šฉ์ž ์งˆ๋ฌธ: {question}") + + if filings is None or filings.height == 0: + lines.append("") + lines.append("ํ•ด๋‹น ์กฐ๊ฑด์— ๋งž๋Š” ๊ณต์‹œ๊ฐ€ ์—†์Šต๋‹ˆ๋‹ค.") + return "\n".join(lines) + + display_df = _build_display_df(filings) + lines.extend(["", df_to_markdown(display_df, max_rows=min(intent.limit, 20), compact=False)]) + return "\n".join(lines) + + +def cleanDartFilingText(text: str, *, maxChars: int = 4000) -> str: + normalized = unescape(text or "") + normalized = re.sub(r"<[^>]+>", " ", normalized) + normalized = re.sub(r"\s+", " ", normalized).strip() + if len(normalized) <= maxChars: + return normalized + return normalized[:maxChars].rstrip() + " ... (truncated)" + + +def _build_display_df(df: pl.DataFrame) -> pl.DataFrame: + display = df + if "rcept_dt" in display.columns: + display = display.with_columns( + pl.col("rcept_dt").cast(pl.Utf8).map_elements(_format_date, return_dtype=pl.Utf8).alias("rcept_dt") + ) + + preferred_cols = [ + col + for col in ("rcept_dt", "corp_name", "stock_code", "corp_cls", "report_nm", "rcept_no") + if col in display.columns + ] + if preferred_cols: + display = display.select(preferred_cols) + + rename_map = { + "rcept_dt": "์ ‘์ˆ˜์ผ", + "corp_name": "ํšŒ์‚ฌ", + "stock_code": "์ข…๋ชฉ์ฝ”๋“œ", + "corp_cls": "์‹œ์žฅ", + "report_nm": "๊ณต์‹œ๋ช…", + "rcept_no": "์ ‘์ˆ˜๋ฒˆํ˜ธ", + } + actual_map = {src: dst for src, dst in rename_map.items() if src in display.columns} + return display.rename(actual_map) + + +def _resolve_title_keywords(question: str) -> tuple[str, ...]: + if any(term in question for term in _ORDER_KEYWORDS) or "๊ณ„์•ฝ๊ณต์‹œ" in question: + return _ORDER_KEYWORDS + explicit = [] + for phrase in ("๊ฐ์‚ฌ๋ณด๊ณ ์„œ", "ํ•ฉ๋ณ‘", "์œ ์ƒ์ฆ์ž", "๋ฌด์ƒ์ฆ์ž", "๋ฐฐ๋‹น", "์ž๊ธฐ์ฃผ์‹", "์ตœ๋Œ€์ฃผ์ฃผ"): + if phrase in question: + explicit.append(phrase) + return tuple(explicit) + + +def _resolve_limit(question: str) -> int: + match = re.search(r"(\d+)\s*๊ฑด", question) + if match: + return max(1, min(int(match.group(1)), 50)) + if "์ซ™" in question or "์ „๋ถ€" in question or "์ „์ฒด" in question: + return 30 + return _DEFAULT_LIMIT + + +def _resolve_date_window(question: str, today: date) -> tuple[date, date]: + q = question.replace(" ", "") + if "์˜ค๋Š˜" in question: + return today, today + if "์–ด์ œ" in question: + target = today - timedelta(days=1) + return target, target + if "์ด๋ฒˆ์ฃผ" in q: + start = today - timedelta(days=today.weekday()) + return start, today + if "์ง€๋‚œ์ฃผ" in q: + end = today - timedelta(days=today.weekday() + 1) + start = end - timedelta(days=6) + return start, end + if "์ด๋ฒˆ๋‹ฌ" in q: + start = today.replace(day=1) + return start, today + + recent_match = re.search(r"์ตœ๊ทผ\s*(\d+)\s*(์ผ|์ฃผ|๊ฐœ์›”|๋‹ฌ)", question) + if recent_match: + amount = int(recent_match.group(1)) + unit = recent_match.group(2) + if unit == "์ผ": + return today - timedelta(days=max(amount - 1, 0)), today + if unit == "์ฃผ": + return today - timedelta(days=max(amount * 7 - 1, 0)), today + if unit in {"๊ฐœ์›”", "๋‹ฌ"}: + return today - timedelta(days=max(amount * 30 - 1, 0)), today + + if "์ตœ๊ทผ ๋ช‡์ผ" in q or "์ตœ๊ทผ๋ช‡์ผ" in q or "์ตœ๊ทผ ๋ฉฐ์น " in question or "์ตœ๊ทผ๋ฉฐ์น " in q: + return today - timedelta(days=_DEFAULT_DAYS - 1), today + if "์ตœ๊ทผ ๋ช‡์ฃผ" in q or "์ตœ๊ทผ๋ช‡์ฃผ" in q: + return today - timedelta(days=13), today + + return today - timedelta(days=_DEFAULT_DAYS - 1), today + + +def _coerce_search_window( + start: str | None, + end: str | None, + *, + days: int | None, + weeks: int | None, +) -> tuple[str, str]: + today = date.today() + if start or end: + resolved_start = _strip_date_sep(start or (end or today.strftime("%Y%m%d"))) + resolved_end = _strip_date_sep(end or today.strftime("%Y%m%d")) + return resolved_start, resolved_end + if days: + begin = today - timedelta(days=max(days - 1, 0)) + return begin.strftime("%Y%m%d"), today.strftime("%Y%m%d") + if weeks: + begin = today - timedelta(days=max(weeks * 7 - 1, 0)) + return begin.strftime("%Y%m%d"), today.strftime("%Y%m%d") + begin = today - timedelta(days=_DEFAULT_DAYS - 1) + return begin.strftime("%Y%m%d"), today.strftime("%Y%m%d") + + +def _strip_date_sep(value: str) -> str: + return (value or "").replace("-", "").replace(".", "").replace("/", "") + + +def _format_date(value: str) -> str: + digits = _strip_date_sep(str(value)) + if len(digits) == 8 and digits.isdigit(): + return f"{digits[:4]}-{digits[4:6]}-{digits[6:]}" + return str(value) diff --git a/src/dartlab/ai/context/finance_context.py b/src/dartlab/ai/context/finance_context.py new file mode 100644 index 0000000000000000000000000000000000000000..2a3b596c3d5d13d2c28c4f07f2a02b1327362f37 --- /dev/null +++ b/src/dartlab/ai/context/finance_context.py @@ -0,0 +1,945 @@ +"""Finance/report ๋ฐ์ดํ„ฐ๋ฅผ LLM context ๋งˆํฌ๋‹ค์šด์œผ๋กœ ๋ณ€ํ™˜ํ•˜๋Š” ํ•จ์ˆ˜๋“ค.""" + +from __future__ import annotations + +import re +from typing import Any + +import polars as pl + +from dartlab.ai.context.company_adapter import get_headline_ratios, get_ratio_series +from dartlab.ai.context.formatting import _format_won, df_to_markdown +from dartlab.ai.metadata import MODULE_META + +_CONTEXT_ERRORS = (AttributeError, KeyError, OSError, RuntimeError, TypeError, ValueError) + +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• +# ์งˆ๋ฌธ ์œ ํ˜•๋ณ„ ๋ชจ๋“ˆ ๋งคํ•‘ (registry ์ž๋™ ์ƒ์„ฑ + override) +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• + +from dartlab.core.registry import buildQuestionModules + +# registry์— ์—†๋Š” ๋ชจ๋“ˆ(sections topic ์ „์šฉ ๋“ฑ)์€ override๋กœ ์ถ”๊ฐ€ +_QUESTION_MODULES_OVERRIDE: dict[str, list[str]] = { + "๊ณต์‹œ": [], + "๋ฐฐ๋‹น": ["treasuryStock"], + "์ž๋ณธ": ["treasuryStock"], + "์‚ฌ์—…": ["businessOverview"], + "ESG": ["governanceOverview", "boardOfDirectors"], + "๊ณต๊ธ‰๋ง": ["segments", "rawMaterial"], + "๋ณ€ํ™”": ["disclosureChanges", "businessStatus"], + "๋ฐธ๋ฅ˜์—์ด์…˜": ["IS", "BS"], +} + +_QUESTION_MODULES: dict[str, list[str]] = {} +for _qt, _mods in buildQuestionModules().items(): + _QUESTION_MODULES[_qt] = list(_mods) +for _qt, _extra in _QUESTION_MODULES_OVERRIDE.items(): + _QUESTION_MODULES.setdefault(_qt, []).extend(m for m in _extra if m not in _QUESTION_MODULES.get(_qt, [])) + +_ALWAYS_INCLUDE_MODULES = {"employee"} + +_CONTEXT_MODULE_BUDGET = 10000 # ์ด ๋ชจ๋“ˆ context ๊ธ€์ž ์ˆ˜ ์ƒํ•œ (focused tier ๊ธฐ๋ณธ๊ฐ’) + + +def _resolve_context_budget(tier: str = "focused") -> int: + """์ปจํ…์ŠคํŠธ tier๋ณ„ ๋ชจ๋“ˆ ์˜ˆ์‚ฐ.""" + return { + "skeleton": 2000, # tool-capable: ์ตœ์†Œ ๋งฅ๋ฝ, ๋„๊ตฌ๋กœ ๋ณด์ถฉ + "focused": 10000, # ๋ถ„๊ธฐ ๋ฐ์ดํ„ฐ ์ˆ˜์šฉ + "full": 16000, # non-tool ๋ชจ๋ธ: ์ตœ๋Œ€ํ•œ ํฌํ•จ + }.get(tier, 10000) + + +def _topic_name_set(company: Any) -> set[str]: + """Company.topics์—์„œ ์‹ค์ œ topic ์ด๋ฆ„๋งŒ ์•ˆ์ „ํ•˜๊ฒŒ ์ถ”์ถœ.""" + try: + topics = getattr(company, "topics", None) + except _CONTEXT_ERRORS: + return set() + + if topics is None: + return set() + + if isinstance(topics, pl.DataFrame): + if "topic" not in topics.columns: + return set() + return {t for t in topics["topic"].drop_nulls().to_list() if isinstance(t, str) and t} + + if isinstance(topics, pl.Series): + return {t for t in topics.drop_nulls().to_list() if isinstance(t, str) and t} + + try: + return {str(t) for t in topics if isinstance(t, str) and t} + except TypeError: + return set() + + +def _resolve_module_data(company: Any, module_name: str) -> Any: + """AI context์šฉ ๋ชจ๋“ˆ ํ•ด์„. + + 1. Company property/direct attr + 2. registry ๊ธฐ๋ฐ˜ lazy parser (_get_primary) + 3. ์‹ค์ œ ์กด์žฌํ•˜๋Š” topic์— ํ•œํ•ด show() + """ + data = getattr(company, module_name, None) + if data is not None: + return data + + get_primary = getattr(company, "_get_primary", None) + if callable(get_primary): + try: + data = get_primary(module_name) + except _CONTEXT_ERRORS: + data = None + except (FileNotFoundError, ImportError, IndexError): + data = None + if data is not None: + return data + + if hasattr(company, "show") and module_name in _topic_name_set(company): + try: + return company.show(module_name) + except _CONTEXT_ERRORS: + return None + + return None + + +def _extract_module_context(company: Any, module_name: str, max_rows: int = 10) -> str | None: + """registry ๋ชจ๋“ˆ โ†’ ๋งˆํฌ๋‹ค์šด ์š”์•ฝ. DataFrame/dict/list/text ๋ชจ๋‘ ์ฒ˜๋ฆฌ.""" + try: + data = _resolve_module_data(company, module_name) + if data is None: + return None + + if callable(data) and not isinstance(data, type): + try: + data = data() + except (AttributeError, KeyError, OSError, RuntimeError, TypeError, ValueError): + return None + + meta = MODULE_META.get(module_name) + label = meta.label if meta else module_name + + if isinstance(data, pl.DataFrame): + if data.is_empty(): + return None + md = df_to_markdown(data, max_rows=max_rows, meta=meta, compact=True) + return f"## {label}\n{md}" + + if isinstance(data, dict): + items = list(data.items())[:max_rows] + lines = [f"## {label}"] + for k, v in items: + lines.append(f"- {k}: {v}") + return "\n".join(lines) + + if isinstance(data, list): + if not data: + return None + lines = [f"## {label}"] + for item in data[:max_rows]: + if hasattr(item, "title") and hasattr(item, "chars"): + lines.append(f"- **{item.title}** ({item.chars}์ž)") + else: + lines.append(f"- {item}") + if len(data) > max_rows: + lines.append(f"(... ์ƒ์œ„ {max_rows}๊ฑด, ์ „์ฒด {len(data)}๊ฑด)") + return "\n".join(lines) + + text = str(data) + if len(text) > 300: + text = ( + text[:300] + + f"... (์ „์ฒด {len(str(data))}์ž, explore(action='show', topic='{module_name}')์œผ๋กœ ์ „๋ฌธ ํ™•์ธ)" + ) + return f"## {label}\n{text}" if text.strip() else None + + except (AttributeError, KeyError, OSError, RuntimeError, TypeError, ValueError): + return None + + +def _build_report_sections( + company: Any, + compact: bool = False, + q_types: list[str] | None = None, + tier: str = "focused", + report_names: list[str] | None = None, +) -> dict[str, str]: + """reportEngine pivot ๊ฒฐ๊ณผ + ์งˆ๋ฌธ ์œ ํ˜•๋ณ„ ๋ชจ๋“ˆ ์ž๋™ ์ฃผ์ž… โ†’ LLM context ์„น์…˜ dict.""" + report = getattr(company, "report", None) + sections: dict[str, str] = {} + budget = _resolve_context_budget(tier) + requested_reports = set(report_names or ["dividend", "employee", "majorHolder", "executive", "audit"]) + + # ์งˆ๋ฌธ ์œ ํ˜•๋ณ„ ์ถ”๊ฐ€ ๋ชจ๋“ˆ ์ฃผ์ž… + extra_modules: set[str] = set() if report_names is not None else set(_ALWAYS_INCLUDE_MODULES) + if q_types and report_names is None: + for qt in q_types: + for mod in _QUESTION_MODULES.get(qt, []): + extra_modules.add(mod) + + # ํ•˜๋“œ์ฝ”๋”ฉ๋œ ๊ธฐ์กด report ๋ชจ๋“ˆ๋“ค์˜ ์ด๋ฆ„ (์ค‘๋ณต ๋ฐฉ์ง€์šฉ) + _HARDCODED_REPORT = {"dividend", "employee", "majorHolder", "executive", "audit"} + if report_names: + for mod in report_names: + if mod not in _HARDCODED_REPORT: + extra_modules.add(mod) + + # ๋™์  ๋ชจ๋“ˆ ์ฃผ์ž… (ํ•˜๋“œ์ฝ”๋”ฉ์— ์—†๋Š” ๊ฒƒ๋งŒ) + budget_used = 0 + for mod in sorted(extra_modules - _HARDCODED_REPORT): + if budget_used >= budget: + break + content = _extract_module_context(company, mod, max_rows=8 if compact else 12) + if content: + budget_used += len(content) + sections[f"module_{mod}"] = content + + if report is None: + return sections + + max_years = 3 if compact else 99 + + div = getattr(report, "dividend", None) if "dividend" in requested_reports else None + if div is not None and div.years: + display_years = div.years[-max_years:] + offset = len(div.years) - len(display_years) + lines = ["## ๋ฐฐ๋‹น ์‹œ๊ณ„์—ด (์ •๊ธฐ๋ณด๊ณ ์„œ)"] + header = "| ์—ฐ๋„ | " + " | ".join(str(y) for y in display_years) + " |" + sep = "| --- | " + " | ".join(["---"] * len(display_years)) + " |" + lines.append(header) + lines.append(sep) + + def _fmtList(vals): + return [str(round(v)) if v is not None else "-" for v in vals] + + lines.append("| DPS(์›) | " + " | ".join(_fmtList(div.dps[offset:])) + " |") + lines.append( + "| ๋ฐฐ๋‹น์ˆ˜์ต๋ฅ (%) | " + + " | ".join([f"{v:.2f}" if v is not None else "-" for v in div.dividendYield[offset:]]) + + " |" + ) + latest_dps = div.dps[-1] if div.dps else None + latest_yield = div.dividendYield[-1] if div.dividendYield else None + if latest_dps is not None or latest_yield is not None: + lines.append("") + lines.append("### ๋ฐฐ๋‹น ํ•ต์‹ฌ ์š”์•ฝ") + if latest_dps is not None: + lines.append(f"- ์ตœ๊ทผ ์—ฐ๋„ DPS: {int(round(latest_dps))}์›") + if latest_yield is not None: + lines.append(f"- ์ตœ๊ทผ ์—ฐ๋„ ๋ฐฐ๋‹น์ˆ˜์ต๋ฅ : {latest_yield:.2f}%") + if len(display_years) >= 3: + recent_dps = [ + f"{year}:{int(round(value)) if value is not None else '-'}์›" + for year, value in zip(display_years[-3:], div.dps[offset:][-3:], strict=False) + ] + lines.append("- ์ตœ๊ทผ 3๊ฐœ๋…„ DPS ์ถ”์ด: " + " โ†’ ".join(recent_dps)) + sections["report_dividend"] = "\n".join(lines) + + emp = getattr(report, "employee", None) if "employee" in requested_reports else None + if emp is not None and emp.years: + display_years = emp.years[-max_years:] + offset = len(emp.years) - len(display_years) + lines = ["## ์ง์›ํ˜„ํ™ฉ (์ •๊ธฐ๋ณด๊ณ ์„œ)"] + header = "| ์—ฐ๋„ | " + " | ".join(str(y) for y in display_years) + " |" + sep = "| --- | " + " | ".join(["---"] * len(display_years)) + " |" + lines.append(header) + lines.append(sep) + + def _fmtEmp(vals): + return [f"{int(v):,}" if v is not None else "-" for v in vals] + + def _fmtSalary(vals): + return [f"{int(v):,}" if v is not None else "-" for v in vals] + + lines.append("| ์ด ์ง์›์ˆ˜(๋ช…) | " + " | ".join(_fmtEmp(emp.totalEmployee[offset:])) + " |") + lines.append("| ํ‰๊ท ์›”๊ธ‰(์ฒœ์›) | " + " | ".join(_fmtSalary(emp.avgMonthlySalary[offset:])) + " |") + sections["report_employee"] = "\n".join(lines) + + mh = getattr(report, "majorHolder", None) if "majorHolder" in requested_reports else None + if mh is not None and mh.years: + lines = ["## ์ตœ๋Œ€์ฃผ์ฃผ (์ •๊ธฐ๋ณด๊ณ ์„œ)"] + if compact: + latest_ratio = mh.totalShareRatio[-1] if mh.totalShareRatio else None + ratio_str = f"{latest_ratio:.2f}%" if latest_ratio is not None else "-" + lines.append(f"- {mh.years[-1]}๋…„ ํ•ฉ์‚ฐ ์ง€๋ถ„์œจ: {ratio_str}") + else: + header = "| ์—ฐ๋„ | " + " | ".join(str(y) for y in mh.years) + " |" + sep = "| --- | " + " | ".join(["---"] * len(mh.years)) + " |" + lines.append(header) + lines.append(sep) + lines.append( + "| ํ•ฉ์‚ฐ ์ง€๋ถ„์œจ(%) | " + + " | ".join([f"{v:.2f}" if v is not None else "-" for v in mh.totalShareRatio]) + + " |" + ) + + if mh.latestHolders: + holder_limit = 3 if compact else 5 + if not compact: + lines.append("") + lines.append(f"### ์ตœ๊ทผ ์ฃผ์š”์ฃผ์ฃผ ({mh.years[-1]}๋…„)") + for h in mh.latestHolders[:holder_limit]: + ratio = f"{h['ratio']:.2f}%" if h.get("ratio") is not None else "-" + relate = f" ({h['relate']})" if h.get("relate") else "" + lines.append(f"- {h['name']}{relate}: {ratio}") + sections["report_majorHolder"] = "\n".join(lines) + + exe = getattr(report, "executive", None) if "executive" in requested_reports else None + if exe is not None and exe.totalCount > 0: + lines = [ + "## ์ž„์›ํ˜„ํ™ฉ (์ •๊ธฐ๋ณด๊ณ ์„œ)", + f"- ์ด ์ž„์›์ˆ˜: {exe.totalCount}๋ช…", + f"- ์‚ฌ๋‚ด์ด์‚ฌ: {exe.registeredCount}๋ช…", + f"- ์‚ฌ์™ธ์ด์‚ฌ: {exe.outsideCount}๋ช…", + ] + sections["report_executive"] = "\n".join(lines) + + aud = getattr(report, "audit", None) if "audit" in requested_reports else None + if aud is not None and aud.years: + lines = ["## ๊ฐ์‚ฌ์˜๊ฒฌ (์ •๊ธฐ๋ณด๊ณ ์„œ)"] + display_aud = list(zip(aud.years, aud.opinions, aud.auditors)) + if compact: + display_aud = display_aud[-2:] + for y, opinion, auditor in display_aud: + opinion = opinion or "-" + auditor = auditor or "-" + lines.append(f"- {y}๋…„: {opinion} ({auditor})") + sections["report_audit"] = "\n".join(lines) + + return sections + + +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• +# financeEngine ๊ธฐ๋ฐ˜ ์ปจํ…์ŠคํŠธ (1์ฐจ ๋ฐ์ดํ„ฐ ์†Œ์Šค) +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• + +_YEAR_HINT_KEYWORDS: dict[str, int] = { + "์ตœ๊ทผ": 3, + "์˜ฌํ•ด": 3, + "์ž‘๋…„": 3, + "์ „๋…„": 3, + "์ถ”์ด": 5, + "ํŠธ๋ Œ๋“œ": 5, + "์ถ”์„ธ": 5, + "๋ณ€ํ™”": 5, + "์„ฑ์žฅ": 5, + "ํ๋ฆ„": 5, + "์ „์ฒด": 15, + "์—ญ์‚ฌ": 15, + "์žฅ๊ธฐ": 10, +} + + +def _detect_year_hint(question: str) -> int: + """์งˆ๋ฌธ์—์„œ ํ•„์š”ํ•œ ์—ฐ๋„ ๋ฒ”์œ„ ์ถ”์ถœ.""" + range_match = re.search(r"(\d+)\s*(?:๊ฐœ๋…„|๋…„)", question) + if range_match: + value = int(range_match.group(1)) + if 1 <= value <= 15: + return value + + year_match = re.search(r"(20\d{2})", question) + if year_match: + return 3 + + for keyword, n in _YEAR_HINT_KEYWORDS.items(): + if keyword in question: + return n + + return 5 + + +_FE_DISPLAY_ACCOUNTS = { + "BS": [ + ("total_assets", "์ž์‚ฐ์ด๊ณ„"), + ("current_assets", "์œ ๋™์ž์‚ฐ"), + ("noncurrent_assets", "๋น„์œ ๋™์ž์‚ฐ"), + ("total_liabilities", "๋ถ€์ฑ„์ด๊ณ„"), + ("current_liabilities", "์œ ๋™๋ถ€์ฑ„"), + ("noncurrent_liabilities", "๋น„์œ ๋™๋ถ€์ฑ„"), + ("owners_of_parent_equity", "์ž๋ณธ์ด๊ณ„"), + ("cash_and_cash_equivalents", "ํ˜„๊ธˆ์„ฑ์ž์‚ฐ"), + ("trade_and_other_receivables", "๋งค์ถœ์ฑ„๊ถŒ"), + ("inventories", "์žฌ๊ณ ์ž์‚ฐ"), + ("tangible_assets", "์œ ํ˜•์ž์‚ฐ"), + ("intangible_assets", "๋ฌดํ˜•์ž์‚ฐ"), + ("shortterm_borrowings", "๋‹จ๊ธฐ์ฐจ์ž…๊ธˆ"), + ("longterm_borrowings", "์žฅ๊ธฐ์ฐจ์ž…๊ธˆ"), + ], + "IS": [ + ("sales", "๋งค์ถœ์•ก"), + ("cost_of_sales", "๋งค์ถœ์›๊ฐ€"), + ("gross_profit", "๋งค์ถœ์ด์ด์ต"), + ("selling_and_administrative_expenses", "ํŒ๊ด€๋น„"), + ("operating_profit", "์˜์—…์ด์ต"), + ("finance_income", "๊ธˆ์œต์ˆ˜์ต"), + ("finance_costs", "๊ธˆ์œต๋น„์šฉ"), + ("profit_before_tax", "๋ฒ•์ธ์„ธ์ฐจ๊ฐ์ „์ด์ต"), + ("income_taxes", "๋ฒ•์ธ์„ธ๋น„์šฉ"), + ("net_profit", "๋‹น๊ธฐ์ˆœ์ด์ต"), + ], + "CF": [ + ("operating_cashflow", "์˜์—…ํ™œ๋™CF"), + ("investing_cashflow", "ํˆฌ์žํ™œ๋™CF"), + ("cash_flows_from_financing_activities", "์žฌ๋ฌดํ™œ๋™CF"), + ("cash_and_cash_equivalents_end", "๊ธฐ๋งํ˜„๊ธˆ"), + ], +} + + +# ํ•œ๊ธ€ ๋ผ๋ฒจ โ†’ snakeId ์—ญ๋งคํ•‘ (Phase 5 validation์šฉ) +ACCOUNT_LABEL_TO_SNAKE: dict[str, str] = {} +for _sj_accounts in _FE_DISPLAY_ACCOUNTS.values(): + for _snake_id, _label in _sj_accounts: + ACCOUNT_LABEL_TO_SNAKE[_label] = _snake_id + +_QUESTION_ACCOUNT_FILTER: dict[str, dict[str, set[str]]] = { + "๊ฑด์ „์„ฑ": { + "BS": { + "total_assets", + "total_liabilities", + "owners_of_parent_equity", + "current_assets", + "current_liabilities", + "cash_and_cash_equivalents", + "shortterm_borrowings", + "longterm_borrowings", + }, + "IS": {"operating_profit", "finance_costs", "net_profit"}, + "CF": {"operating_cashflow", "investing_cashflow"}, + }, + "์ˆ˜์ต์„ฑ": { + "IS": { + "sales", + "cost_of_sales", + "gross_profit", + "selling_and_administrative_expenses", + "operating_profit", + "net_profit", + }, + "BS": {"owners_of_parent_equity", "total_assets"}, + }, + "์„ฑ์žฅ์„ฑ": { + "IS": {"sales", "operating_profit", "net_profit"}, + "CF": {"operating_cashflow"}, + }, + "๋ฐฐ๋‹น": { + "IS": {"net_profit"}, + "BS": {"owners_of_parent_equity"}, + }, + "ํ˜„๊ธˆ": { + "CF": { + "operating_cashflow", + "investing_cashflow", + "cash_flows_from_financing_activities", + "cash_and_cash_equivalents_end", + }, + "BS": {"cash_and_cash_equivalents"}, + }, +} + + +def _get_quarter_counts(company: Any) -> dict[str, int]: + """company.timeseries periods์—์„œ ์—ฐ๋„๋ณ„ ๋ถ„๊ธฐ ์ˆ˜ ๊ณ„์‚ฐ.""" + ts = getattr(company, "timeseries", None) + if ts is None: + return {} + _, periods = ts + counts: dict[str, int] = {} + for p in periods: + year = p.split("-")[0] if "-" in p else p[:4] + counts[year] = counts.get(year, 0) + 1 + return counts + + +def _build_finance_engine_section( + series: dict, + years: list[str], + sj_div: str, + n_years: int, + account_filter: set[str] | None = None, + quarter_counts: dict[str, int] | None = None, +) -> str | None: + """financeEngine annual series โ†’ compact ๋งˆํฌ๋‹ค์šด ํ…Œ์ด๋ธ”. + + Args: + account_filter: ์ด set์— ์†ํ•œ snake_id๋งŒ ํ‘œ์‹œ. None์ด๋ฉด ์ „์ฒด. + """ + accounts = _FE_DISPLAY_ACCOUNTS.get(sj_div, []) + if account_filter: + accounts = [(sid, label) for sid, label in accounts if sid in account_filter] + if not accounts: + return None + + display_years = years[-n_years:] + + # ๋ถ€๋ถ„ ์—ฐ๋„ ํ‘œ์‹œ: IS/CF๋Š” 4๋ถ„๊ธฐ ๋ฏธ๋งŒ์ด๋ฉด "(~Q3)" ๋“ฑ ํ‘œ์‹œ, BS๋Š” ์‹œ์ ์ž”์•ก์ด๋ฏ€๋กœ ๋ถˆํ•„์š” + display_years_labeled = [] + for y in display_years: + qc = (quarter_counts or {}).get(y, 4) + if sj_div != "BS" and qc < 4: + display_years_labeled.append(f"{y}(~Q{qc})") + else: + display_years_labeled.append(y) + display_years_reversed = list(reversed(display_years_labeled)) + + # ์ตœ์‹  ์—ฐ๋„๊ฐ€ ๋ถ€๋ถ„์ด๋ฉด YoY ๋น„๊ต ๋ฌด์˜๋ฏธ + latest_year = display_years[-1] + latest_partial = sj_div != "BS" and (quarter_counts or {}).get(latest_year, 4) < 4 + + sj_data = series.get(sj_div, {}) + if not sj_data: + return None + + rows_data = [] + for snake_id, label in accounts: + vals = sj_data.get(snake_id) + if not vals: + continue + year_offset = len(years) - n_years + sliced = vals[year_offset:] if year_offset >= 0 else vals + has_data = any(v is not None for v in sliced) + if has_data: + rows_data.append((label, list(reversed(sliced)))) + + if not rows_data: + return None + + sj_labels = {"BS": "์žฌ๋ฌด์ƒํƒœํ‘œ", "IS": "์†์ต๊ณ„์‚ฐ์„œ", "CF": "ํ˜„๊ธˆํ๋ฆ„ํ‘œ"} + header = "| ๊ณ„์ • | " + " | ".join(display_years_reversed) + " | YoY |" + sep = "| --- | " + " | ".join(["---"] * len(display_years_reversed)) + " | --- |" + + # ๊ธฐ๊ฐ„ ๋ฉ”ํƒ€๋ฐ์ดํ„ฐ ๋ช…์‹œ + sj_meta = {"BS": "์‹œ์  ์ž”์•ก", "IS": "๊ธฐ๊ฐ„ flow (standalone)", "CF": "๊ธฐ๊ฐ„ flow (standalone)"} + meta_line = f"(๋‹จ์œ„: ์–ต/์กฐ์› | {sj_meta.get(sj_div, 'standalone')})" + if latest_partial: + meta_line += f" โš ๏ธ {display_years_labeled[-1]}์€ ๋ถ€๋ถ„์—ฐ๋„ โ€” ์—ฐ๊ฐ„ ์ง์ ‘ ๋น„๊ต ๋ถˆ๊ฐ€" + + lines = [f"## {sj_labels.get(sj_div, sj_div)}", meta_line, header, sep] + for label, vals in rows_data: + cells = [] + for v in vals: + cells.append(_format_won(v) if v is not None else "-") + # YoY: ๋ถ€๋ถ„ ์—ฐ๋„๋ฉด ๋น„๊ต ๋ถˆ๊ฐ€ + if latest_partial: + yoy_str = "-" + else: + yoy_str = _calc_yoy(vals[0], vals[1] if len(vals) > 1 else None) + lines.append(f"| {label} | " + " | ".join(cells) + f" | {yoy_str} |") + + return "\n".join(lines) + + +def _buildQuarterlySection( + series: dict, + periods: list[str], + sjDiv: str, + nQuarters: int = 8, + accountFilter: set[str] | None = None, +) -> str | None: + """timeseries ๋ถ„๊ธฐ๋ณ„ standalone โ†’ compact ๋งˆํฌ๋‹ค์šด ํ…Œ์ด๋ธ”. + + ์ตœ๊ทผ nQuarters ๋ถ„๊ธฐ๋งŒ ํ‘œ์‹œ. QoQ/YoY ์ปฌ๋Ÿผ ํฌํ•จ. + """ + accounts = _FE_DISPLAY_ACCOUNTS.get(sjDiv, []) + if accountFilter: + accounts = [(sid, label) for sid, label in accounts if sid in accountFilter] + if not accounts: + return None + + sjData = series.get(sjDiv, {}) + if not sjData: + return None + + displayPeriods = periods[-nQuarters:] + displayPeriodsReversed = list(reversed(displayPeriods)) + + rowsData = [] + for snakeId, label in accounts: + vals = sjData.get(snakeId) + if not vals: + continue + offset = len(periods) - nQuarters + sliced = vals[offset:] if offset >= 0 else vals + hasData = any(v is not None for v in sliced) + if hasData: + rowsData.append((label, list(reversed(sliced)))) + + if not rowsData: + return None + + sjLabels = {"BS": "์žฌ๋ฌด์ƒํƒœํ‘œ(๋ถ„๊ธฐ)", "IS": "์†์ต๊ณ„์‚ฐ์„œ(๋ถ„๊ธฐ)", "CF": "ํ˜„๊ธˆํ๋ฆ„ํ‘œ(๋ถ„๊ธฐ)"} + sjMeta = {"BS": "์‹œ์  ์ž”์•ก", "IS": "๋ถ„๊ธฐ standalone", "CF": "๋ถ„๊ธฐ standalone"} + + header = "| ๊ณ„์ • | " + " | ".join(displayPeriodsReversed) + " | QoQ | YoY |" + sep = "| --- | " + " | ".join(["---"] * len(displayPeriodsReversed)) + " | --- | --- |" + metaLine = f"(๋‹จ์œ„: ์–ต/์กฐ์› | {sjMeta.get(sjDiv, 'standalone')})" + + lines = [f"## {sjLabels.get(sjDiv, sjDiv)}", metaLine, header, sep] + for label, vals in rowsData: + cells = [_format_won(v) if v is not None else "-" for v in vals] + qoq = _calc_yoy(vals[0], vals[1] if len(vals) > 1 else None) + yoyIdx = 4 if len(vals) > 4 else None + yoy = _calc_yoy(vals[0], vals[yoyIdx] if yoyIdx is not None else None) + lines.append(f"| {label} | " + " | ".join(cells) + f" | {qoq} | {yoy} |") + + return "\n".join(lines) + + +def _calc_yoy(current: float | None, previous: float | None) -> str: + """YoY ์ฆ๊ฐ๋ฅ  ๊ณ„์‚ฐ. ๋ถ€ํ˜ธ ์ „ํ™˜ ์‹œ '-', |๋ณ€๋™๋ฅ |>50%๋ฉด ** ๊ฐ•์กฐ.""" + from dartlab.core.finance.ratios import yoy_pct + + pct = yoy_pct(current, previous) + if pct is None: + return "-" + sign = "+" if pct >= 0 else "" + marker = "**" if abs(pct) > 50 else "" + return f"{marker}{sign}{pct:.1f}%{marker}" + + +def _build_ratios_section( + company: Any, + compact: bool = False, + q_types: list[str] | None = None, +) -> str | None: + """financeEngine RatioResult โ†’ ๋งˆํฌ๋‹ค์šด (์งˆ๋ฌธ ์œ ํ˜•๋ณ„ ํ•„ํ„ฐ๋ง). + + q_types๊ฐ€ ์ฃผ์–ด์ง€๋ฉด ๊ด€๋ จ ๋น„์œจ ๊ทธ๋ฃน๋งŒ ๋…ธ์ถœํ•˜์—ฌ ํ† ํฐ ์ ˆ์•ฝ. + None์ด๋ฉด ์ „์ฒด ๋…ธ์ถœ. + """ + ratios = get_headline_ratios(company) + if ratios is None: + return None + if not hasattr(ratios, "roe"): + return None + + isFinancial = False + sectorInfo = getattr(company, "sector", None) + if sectorInfo is not None: + try: + from dartlab.analysis.comparative.sector.types import Sector + + isFinancial = sectorInfo.sector == Sector.FINANCIALS + except (ImportError, AttributeError): + isFinancial = False + + # โ”€โ”€ ํŒ๋‹จ ํ—ฌํผ โ”€โ”€ + def _judge(val: float | None, good: float, caution: float) -> str: + if val is None: + return "-" + return "์–‘ํ˜ธ" if val >= good else ("์ฃผ์˜" if val >= caution else "์œ„ํ—˜") + + def _judge_inv(val: float | None, good: float, caution: float) -> str: + if val is None: + return "-" + return "์–‘ํ˜ธ" if val <= good else ("์ฃผ์˜" if val <= caution else "์œ„ํ—˜") + + # โ”€โ”€ ์งˆ๋ฌธ ์œ ํ˜• โ†’ ๋…ธ์ถœ ๊ทธ๋ฃน ๋งคํ•‘ โ”€โ”€ + _Q_TYPE_TO_GROUPS: dict[str, list[str]] = { + "๊ฑด์ „์„ฑ": ["์ˆ˜์ต์„ฑ_core", "์•ˆ์ •์„ฑ", "ํ˜„๊ธˆํ๋ฆ„", "๋ณตํ•ฉ"], + "์ˆ˜์ต์„ฑ": ["์ˆ˜์ต์„ฑ", "ํšจ์œจ์„ฑ", "๋ณตํ•ฉ"], + "์„ฑ์žฅ์„ฑ": ["์ˆ˜์ต์„ฑ_core", "์„ฑ์žฅ"], + "๋ฐฐ๋‹น": ["์ˆ˜์ต์„ฑ_core", "ํ˜„๊ธˆํ๋ฆ„"], + "๋ฆฌ์Šคํฌ": ["์•ˆ์ •์„ฑ", "ํ˜„๊ธˆํ๋ฆ„", "๋ณตํ•ฉ"], + "ํˆฌ์ž": ["์ˆ˜์ต์„ฑ_core", "์„ฑ์žฅ", "ํ˜„๊ธˆํ๋ฆ„"], + "์ข…ํ•ฉ": ["์ˆ˜์ต์„ฑ", "์•ˆ์ •์„ฑ", "์„ฑ์žฅ", "ํšจ์œจ์„ฑ", "ํ˜„๊ธˆํ๋ฆ„", "๋ณตํ•ฉ"], + } + + active_groups: set[str] = set() + if q_types: + for qt in q_types: + active_groups.update(_Q_TYPE_TO_GROUPS.get(qt, [])) + if not active_groups: + active_groups = {"์ˆ˜์ต์„ฑ", "์•ˆ์ •์„ฑ", "์„ฑ์žฅ", "ํšจ์œจ์„ฑ", "ํ˜„๊ธˆํ๋ฆ„", "๋ณตํ•ฉ"} + + # "์ˆ˜์ต์„ฑ_core"๋Š” ์ˆ˜์ต์„ฑ์˜ ํ•ต์‹ฌ๋งŒ (ROE, ROA, ์˜์—…์ด์ต๋ฅ , ์ˆœ์ด์ต๋ฅ ) + show_profitability_full = "์ˆ˜์ต์„ฑ" in active_groups + show_profitability_core = show_profitability_full or "์ˆ˜์ต์„ฑ_core" in active_groups + + roeGood, roeCaution = (8, 5) if isFinancial else (10, 5) + roaGood, roaCaution = (0.5, 0.2) if isFinancial else (5, 2) + + lines = ["## ํ•ต์‹ฌ ์žฌ๋ฌด๋น„์œจ (์ž๋™๊ณ„์‚ฐ)"] + + # โ”€โ”€ ์ˆ˜์ต์„ฑ โ”€โ”€ + if show_profitability_core: + prof_rows: list[str] = [] + if ratios.roe is not None: + prof_rows.append(f"| ROE | {ratios.roe:.1f}% | {_judge(ratios.roe, roeGood, roeCaution)} |") + if ratios.roa is not None: + prof_rows.append(f"| ROA | {ratios.roa:.1f}% | {_judge(ratios.roa, roaGood, roaCaution)} |") + if ratios.operatingMargin is not None: + prof_rows.append(f"| ์˜์—…์ด์ต๋ฅ  | {ratios.operatingMargin:.1f}% | - |") + if not compact and ratios.netMargin is not None: + prof_rows.append(f"| ์ˆœ์ด์ต๋ฅ  | {ratios.netMargin:.1f}% | - |") + if show_profitability_full: + if ratios.grossMargin is not None: + prof_rows.append(f"| ๋งค์ถœ์ด์ด์ต๋ฅ  | {ratios.grossMargin:.1f}% | - |") + if ratios.ebitdaMargin is not None: + prof_rows.append(f"| EBITDA๋งˆ์ง„ | {ratios.ebitdaMargin:.1f}% | - |") + if not compact and ratios.roic is not None: + prof_rows.append(f"| ROIC | {ratios.roic:.1f}% | {_judge(ratios.roic, 15, 8)} |") + if prof_rows: + lines.append("\n### ์ˆ˜์ต์„ฑ") + lines.append("| ์ง€ํ‘œ | ๊ฐ’ | ํŒ๋‹จ |") + lines.append("| --- | --- | --- |") + lines.extend(prof_rows) + + # โ”€โ”€ ์•ˆ์ •์„ฑ โ”€โ”€ + if "์•ˆ์ •์„ฑ" in active_groups: + stab_rows: list[str] = [] + if ratios.debtRatio is not None: + stab_rows.append(f"| ๋ถ€์ฑ„๋น„์œจ | {ratios.debtRatio:.1f}% | {_judge_inv(ratios.debtRatio, 100, 200)} |") + if ratios.currentRatio is not None: + stab_rows.append(f"| ์œ ๋™๋น„์œจ | {ratios.currentRatio:.1f}% | {_judge(ratios.currentRatio, 150, 100)} |") + if not compact and ratios.quickRatio is not None: + stab_rows.append(f"| ๋‹น์ขŒ๋น„์œจ | {ratios.quickRatio:.1f}% | {_judge(ratios.quickRatio, 100, 50)} |") + if not compact and ratios.equityRatio is not None: + stab_rows.append(f"| ์ž๊ธฐ์ž๋ณธ๋น„์œจ | {ratios.equityRatio:.1f}% | {_judge(ratios.equityRatio, 50, 30)} |") + if ratios.interestCoverage is not None: + stab_rows.append( + f"| ์ด์ž๋ณด์ƒ๋ฐฐ์œจ | {ratios.interestCoverage:.1f}x | {_judge(ratios.interestCoverage, 5, 1)} |" + ) + if not compact and ratios.debtToEbitda is not None: + stab_rows.append(f"| Debt/EBITDA | {ratios.debtToEbitda:.1f}x | {_judge_inv(ratios.debtToEbitda, 3, 5)} |") + if not compact and ratios.netDebt is not None: + stab_rows.append( + f"| ์ˆœ์ฐจ์ž…๊ธˆ | {_format_won(ratios.netDebt)} | {'์–‘ํ˜ธ' if ratios.netDebt <= 0 else '์ฃผ์˜'} |" + ) + if not compact and ratios.netDebtRatio is not None: + stab_rows.append( + f"| ์ˆœ์ฐจ์ž…๊ธˆ๋น„์œจ | {ratios.netDebtRatio:.1f}% | {_judge_inv(ratios.netDebtRatio, 30, 80)} |" + ) + if stab_rows: + lines.append("\n### ์•ˆ์ •์„ฑ") + lines.append("| ์ง€ํ‘œ | ๊ฐ’ | ํŒ๋‹จ |") + lines.append("| --- | --- | --- |") + lines.extend(stab_rows) + + # โ”€โ”€ ์„ฑ์žฅ์„ฑ โ”€โ”€ + if "์„ฑ์žฅ" in active_groups: + grow_rows: list[str] = [] + if ratios.revenueGrowth is not None: + grow_rows.append(f"| ๋งค์ถœ์„ฑ์žฅ๋ฅ (YoY) | {ratios.revenueGrowth:.1f}% | - |") + if ratios.operatingProfitGrowth is not None: + grow_rows.append(f"| ์˜์—…์ด์ต์„ฑ์žฅ๋ฅ  | {ratios.operatingProfitGrowth:.1f}% | - |") + if ratios.netProfitGrowth is not None: + grow_rows.append(f"| ์ˆœ์ด์ต์„ฑ์žฅ๋ฅ  | {ratios.netProfitGrowth:.1f}% | - |") + if ratios.revenueGrowth3Y is not None: + grow_rows.append(f"| ๋งค์ถœ 3Y CAGR | {ratios.revenueGrowth3Y:.1f}% | - |") + if not compact and ratios.assetGrowth is not None: + grow_rows.append(f"| ์ž์‚ฐ์„ฑ์žฅ๋ฅ  | {ratios.assetGrowth:.1f}% | - |") + if grow_rows: + lines.append("\n### ์„ฑ์žฅ์„ฑ") + lines.append("| ์ง€ํ‘œ | ๊ฐ’ | ํŒ๋‹จ |") + lines.append("| --- | --- | --- |") + lines.extend(grow_rows) + + # โ”€โ”€ ํšจ์œจ์„ฑ โ”€โ”€ + if "ํšจ์œจ์„ฑ" in active_groups and not compact: + eff_rows: list[str] = [] + if ratios.totalAssetTurnover is not None: + eff_rows.append(f"| ์ด์ž์‚ฐํšŒ์ „์œจ | {ratios.totalAssetTurnover:.2f}x | - |") + if ratios.inventoryTurnover is not None: + eff_rows.append(f"| ์žฌ๊ณ ์ž์‚ฐํšŒ์ „์œจ | {ratios.inventoryTurnover:.1f}x | - |") + if ratios.receivablesTurnover is not None: + eff_rows.append(f"| ๋งค์ถœ์ฑ„๊ถŒํšŒ์ „์œจ | {ratios.receivablesTurnover:.1f}x | - |") + if eff_rows: + lines.append("\n### ํšจ์œจ์„ฑ") + lines.append("| ์ง€ํ‘œ | ๊ฐ’ | ํŒ๋‹จ |") + lines.append("| --- | --- | --- |") + lines.extend(eff_rows) + + # โ”€โ”€ ํ˜„๊ธˆํ๋ฆ„ โ”€โ”€ + if "ํ˜„๊ธˆํ๋ฆ„" in active_groups: + cf_rows: list[str] = [] + if ratios.fcf is not None: + cf_rows.append(f"| FCF | {_format_won(ratios.fcf)} | {'์–‘ํ˜ธ' if ratios.fcf > 0 else '์ฃผ์˜'} |") + if ratios.operatingCfToNetIncome is not None: + quality = _judge(ratios.operatingCfToNetIncome, 100, 50) + cf_rows.append(f"| ์˜์—…CF/์ˆœ์ด์ต | {ratios.operatingCfToNetIncome:.0f}% | {quality} |") + if not compact and ratios.capexRatio is not None: + cf_rows.append(f"| CAPEX๋น„์œจ | {ratios.capexRatio:.1f}% | - |") + if not compact and ratios.dividendPayoutRatio is not None: + cf_rows.append(f"| ๋ฐฐ๋‹น์„ฑํ–ฅ | {ratios.dividendPayoutRatio:.1f}% | - |") + if cf_rows: + lines.append("\n### ํ˜„๊ธˆํ๋ฆ„") + lines.append("| ์ง€ํ‘œ | ๊ฐ’ | ํŒ๋‹จ |") + lines.append("| --- | --- | --- |") + lines.extend(cf_rows) + + # โ”€โ”€ ๋ณตํ•ฉ ์ง€ํ‘œ โ”€โ”€ + if "๋ณตํ•ฉ" in active_groups and not compact: + comp_lines: list[str] = [] + + # DuPont ๋ถ„ํ•ด + dm = getattr(ratios, "dupontMargin", None) + dt = getattr(ratios, "dupontTurnover", None) + dl = getattr(ratios, "dupontLeverage", None) + if dm is not None and dt is not None and dl is not None and ratios.roe is not None: + # ์ฃผ์š” ๋™์ธ ํŒ๋ณ„ + if dm >= dt and dm >= dl: + driver = "์ˆ˜์ต์„ฑ ์ฃผ๋„ํ˜•" + elif dt >= dm and dt >= dl: + driver = "ํšจ์œจ์„ฑ ์ฃผ๋„ํ˜•" + else: + driver = "๋ ˆ๋ฒ„๋ฆฌ์ง€ ์ฃผ๋„ํ˜•" + comp_lines.append("\n### DuPont ๋ถ„ํ•ด") + comp_lines.append( + f"ROE {ratios.roe:.1f}% = ์ˆœ์ด์ต๋ฅ ({dm:.1f}%) ร— ์ž์‚ฐํšŒ์ „์œจ({dt:.2f}x) ร— ๋ ˆ๋ฒ„๋ฆฌ์ง€({dl:.2f}x)" + ) + comp_lines.append(f"โ†’ **{driver}**") + + # Piotroski F-Score + pf = getattr(ratios, "piotroskiFScore", None) + if pf is not None: + pf_label = "์šฐ์ˆ˜" if pf >= 7 else ("๋ณดํ†ต" if pf >= 4 else "์ทจ์•ฝ") + comp_lines.append("\n### ๋ณตํ•ฉ ์žฌ๋ฌด ์ง€ํ‘œ") + comp_lines.append(f"- **Piotroski F-Score**: {pf}/9 ({pf_label}) โ€” โ‰ฅ7 ์šฐ์ˆ˜, 4-6 ๋ณดํ†ต, <4 ์ทจ์•ฝ") + + # Altman Z-Score + az = getattr(ratios, "altmanZScore", None) + if az is not None: + az_label = "์•ˆ์ „" if az > 2.99 else ("ํšŒ์ƒ‰" if az >= 1.81 else "๋ถ€์‹ค์œ„ํ—˜") + if pf is None: + comp_lines.append("\n### ๋ณตํ•ฉ ์žฌ๋ฌด ์ง€ํ‘œ") + comp_lines.append(f"- **Altman Z-Score**: {az:.2f} ({az_label}) โ€” >2.99 ์•ˆ์ „, 1.81-2.99 ํšŒ์ƒ‰, <1.81 ๋ถ€์‹ค") + + # ROIC + if ratios.roic is not None: + roic_label = "์šฐ์ˆ˜" if ratios.roic >= 15 else ("์ ์ •" if ratios.roic >= 8 else "๋ฏธํก") + comp_lines.append(f"- **ROIC**: {ratios.roic:.1f}% ({roic_label})") + + # ์ด์ต์˜ ์งˆ โ€” CCC + ccc = getattr(ratios, "ccc", None) + dso = getattr(ratios, "dso", None) + dio = getattr(ratios, "dio", None) + dpo = getattr(ratios, "dpo", None) + cfni = ratios.operatingCfToNetIncome + has_quality = ccc is not None or cfni is not None + if has_quality: + comp_lines.append("\n### ์ด์ต์˜ ์งˆ") + if cfni is not None: + q = "์–‘ํ˜ธ" if cfni >= 100 else ("๋ณดํ†ต" if cfni >= 50 else "์ฃผ์˜") + comp_lines.append(f"- ์˜์—…CF/์ˆœ์ด์ต: {cfni:.0f}% ({q}) โ€” โ‰ฅ100% ์–‘ํ˜ธ") + if ccc is not None: + ccc_parts = [] + if dso is not None: + ccc_parts.append(f"DSO:{dso:.0f}") + if dio is not None: + ccc_parts.append(f"DIO:{dio:.0f}") + if dpo is not None: + ccc_parts.append(f"DPO:{dpo:.0f}") + detail = f" ({' + '.join(ccc_parts)})" if ccc_parts else "" + comp_lines.append(f"- CCC(ํ˜„๊ธˆ์ „ํ™˜์ฃผ๊ธฐ): {ccc:.0f}์ผ{detail}") + + if comp_lines: + lines.extend(comp_lines) + + # โ”€โ”€ ratioSeries 3๋…„ ์ถ”์„ธ โ”€โ”€ + ratio_series = get_ratio_series(company) + if ratio_series is not None and hasattr(ratio_series, "roe") and ratio_series.roe: + trend_keys = [("roe", "ROE"), ("operatingMargin", "์˜์—…์ด์ต๋ฅ "), ("debtRatio", "๋ถ€์ฑ„๋น„์œจ")] + if not compact and "์„ฑ์žฅ" in active_groups: + trend_keys.append(("revenueGrowth", "๋งค์ถœ์„ฑ์žฅ๋ฅ ")) + trend_lines: list[str] = [] + for key, label in trend_keys: + series_vals = getattr(ratio_series, key, None) + if series_vals and len(series_vals) >= 2: + recent = [f"{v:.1f}%" for v in series_vals[-3:] if v is not None] + if recent: + arrow = ( + "โ†—" if series_vals[-1] > series_vals[-2] else "โ†˜" if series_vals[-1] < series_vals[-2] else "โ†’" + ) + trend_lines.append(f"- {label}: {' โ†’ '.join(recent)} {arrow}") + if trend_lines: + lines.append("") + lines.append("### ์ถ”์„ธ (์ตœ๊ทผ 3๋…„)") + lines.extend(trend_lines) + + # โ”€โ”€ TTM โ”€โ”€ + ttm_lines: list[str] = [] + if ratios.revenueTTM is not None: + ttm_lines.append(f"- TTM ๋งค์ถœ: {_format_won(ratios.revenueTTM)}") + if ratios.operatingIncomeTTM is not None: + ttm_lines.append(f"- TTM ์˜์—…์ด์ต: {_format_won(ratios.operatingIncomeTTM)}") + if ratios.netIncomeTTM is not None: + ttm_lines.append(f"- TTM ์ˆœ์ด์ต: {_format_won(ratios.netIncomeTTM)}") + if ttm_lines: + lines.append("") + lines.append("### TTM (์ตœ๊ทผ 4๋ถ„๊ธฐ ํ•ฉ์‚ฐ)") + lines.extend(ttm_lines) + + # โ”€โ”€ ๊ฒฝ๊ณ  โ”€โ”€ + if ratios.warnings: + lines.append("") + lines.append("### ๊ฒฝ๊ณ ") + max_warnings = 2 if compact else len(ratios.warnings) + for w in ratios.warnings[:max_warnings]: + lines.append(f"- โš ๏ธ {w}") + + return "\n".join(lines) + + +def detect_year_range(company: Any, tables: list[str]) -> dict | None: + """ํฌํ•จ๋  ๋ฐ์ดํ„ฐ์˜ ์—ฐ๋„ ๋ฒ”์œ„ ๊ฐ์ง€.""" + all_years: set[int] = set() + for name in tables: + try: + data = getattr(company, name, None) + if data is None: + continue + if isinstance(data, pl.DataFrame): + if "year" in data.columns: + years = data["year"].unique().to_list() + all_years.update(int(y) for y in years if y) + else: + year_cols = [c for c in data.columns if c.isdigit() and len(c) == 4] + all_years.update(int(c) for c in year_cols) + except _CONTEXT_ERRORS: + continue + if not all_years: + return None + sorted_years = sorted(all_years) + return {"min_year": sorted_years[0], "max_year": sorted_years[-1]} + + +def scan_available_modules(company: Any) -> list[dict[str, str]]: + """Company ์ธ์Šคํ„ด์Šค์—์„œ ์‹ค์ œ ๋ฐ์ดํ„ฐ๊ฐ€ ์žˆ๋Š” ๋ชจ๋“ˆ ๋ชฉ๋ก์„ ๋ฐ˜ํ™˜. + + Returns: + [{"name": "BS", "label": "์žฌ๋ฌด์ƒํƒœํ‘œ", "type": "DataFrame", "rows": 25}, ...] + """ + available = [] + for name, meta in MODULE_META.items(): + try: + data = getattr(company, name, None) + if data is None: + continue + # method์ธ ๊ฒฝ์šฐ ๊ฑด๋„ˆ๋œ€ (fsSummary ๋“ฑ์€ ํ˜ธ์ถœ ๋น„์šฉ์ด ํผ) + if callable(data) and not isinstance(data, type): + info: dict[str, Any] = {"name": name, "label": meta.label, "type": "method"} + available.append(info) + continue + if isinstance(data, pl.DataFrame): + info = { + "name": name, + "label": meta.label, + "type": "table", + "rows": data.height, + "cols": len(data.columns), + } + elif isinstance(data, dict): + info = {"name": name, "label": meta.label, "type": "dict", "rows": len(data)} + elif isinstance(data, list): + info = {"name": name, "label": meta.label, "type": "list", "rows": len(data)} + else: + info = {"name": name, "label": meta.label, "type": "text"} + available.append(info) + except _CONTEXT_ERRORS: + continue + return available diff --git a/src/dartlab/ai/context/formatting.py b/src/dartlab/ai/context/formatting.py new file mode 100644 index 0000000000000000000000000000000000000000..d0a63412d4aebd700d70ad37b760351ba87f99e8 --- /dev/null +++ b/src/dartlab/ai/context/formatting.py @@ -0,0 +1,439 @@ +"""ํฌ๋งทํŒ…ยท์œ ํ‹ธ๋ฆฌํ‹ฐ ํ•จ์ˆ˜ โ€” builder.py์—์„œ ๋ถ„๋ฆฌ. + +์› ๋‹จ์œ„ ๋ณ€ํ™˜, DataFrameโ†’๋งˆํฌ๋‹ค์šด, ํŒŒ์ƒ ์ง€ํ‘œ ์ž๋™๊ณ„์‚ฐ ๋“ฑ +builder / finance_context ์–‘์ชฝ์—์„œ ์žฌ์‚ฌ์šฉํ•˜๋Š” ์ˆœ์ˆ˜ ํ•จ์ˆ˜ ๋ชจ์Œ. +""" + +from __future__ import annotations + +from typing import Any + +import polars as pl + +from dartlab.ai.metadata import ModuleMeta + +_CONTEXT_ERRORS = (AttributeError, KeyError, OSError, RuntimeError, TypeError, ValueError) + +# โ”€โ”€ ํ•ต์‹ฌ ๊ณ„์ • ํ•„ํ„ฐ์šฉ ์ƒ์ˆ˜ โ”€โ”€ + +_KEY_ACCOUNTS_BS = { + "์ž์‚ฐ์ด๊ณ„", + "์œ ๋™์ž์‚ฐ", + "๋น„์œ ๋™์ž์‚ฐ", + "๋ถ€์ฑ„์ด๊ณ„", + "์œ ๋™๋ถ€์ฑ„", + "๋น„์œ ๋™๋ถ€์ฑ„", + "์ž๋ณธ์ด๊ณ„", + "์ง€๋ฐฐ๊ธฐ์—…์†Œ์œ ์ฃผ์ง€๋ถ„", + "ํ˜„๊ธˆ๋ฐํ˜„๊ธˆ์„ฑ์ž์‚ฐ", + "๋งค์ถœ์ฑ„๊ถŒ", + "์žฌ๊ณ ์ž์‚ฐ", + "์œ ํ˜•์ž์‚ฐ", + "๋ฌดํ˜•์ž์‚ฐ", + "ํˆฌ์ž๋ถ€๋™์‚ฐ", + "๋‹จ๊ธฐ์ฐจ์ž…๊ธˆ", + "์žฅ๊ธฐ์ฐจ์ž…๊ธˆ", + "์‚ฌ์ฑ„", +} + +_KEY_ACCOUNTS_IS = { + "๋งค์ถœ์•ก", + "๋งค์ถœ์›๊ฐ€", + "๋งค์ถœ์ด์ด์ต", + "ํŒ๋งค๋น„์™€๊ด€๋ฆฌ๋น„", + "์˜์—…์ด์ต", + "์˜์—…์†์‹ค", + "๊ธˆ์œต์ˆ˜์ต", + "๊ธˆ์œต๋น„์šฉ", + "์ด์ž๋น„์šฉ", + "์ด์ž์ˆ˜์ต", + "๋ฒ•์ธ์„ธ๋น„์šฉ์ฐจ๊ฐ์ „์ˆœ์ด์ต", + "๋ฒ•์ธ์„ธ๋น„์šฉ", + "๋‹น๊ธฐ์ˆœ์ด์ต", + "๋‹น๊ธฐ์ˆœ์†์‹ค", + "์ง€๋ฐฐ๊ธฐ์—…์†Œ์œ ์ฃผ์ง€๋ถ„์ˆœ์ด์ต", +} + +_KEY_ACCOUNTS_CF = { + "์˜์—…ํ™œ๋™ํ˜„๊ธˆํ๋ฆ„", + "์˜์—…ํ™œ๋™์œผ๋กœ์ธํ•œํ˜„๊ธˆํ๋ฆ„", + "ํˆฌ์žํ™œ๋™ํ˜„๊ธˆํ๋ฆ„", + "ํˆฌ์žํ™œ๋™์œผ๋กœ์ธํ•œํ˜„๊ธˆํ๋ฆ„", + "์žฌ๋ฌดํ™œ๋™ํ˜„๊ธˆํ๋ฆ„", + "์žฌ๋ฌดํ™œ๋™์œผ๋กœ์ธํ•œํ˜„๊ธˆํ๋ฆ„", + "ํ˜„๊ธˆ๋ฐํ˜„๊ธˆ์„ฑ์ž์‚ฐ์˜์ˆœ์ฆ๊ฐ€", + "ํ˜„๊ธˆ๋ฐํ˜„๊ธˆ์„ฑ์ž์‚ฐ์˜์ฆ๊ฐ", + "๊ธฐ์ดˆํ˜„๊ธˆ๋ฐํ˜„๊ธˆ์„ฑ์ž์‚ฐ", + "๊ธฐ๋งํ˜„๊ธˆ๋ฐํ˜„๊ธˆ์„ฑ์ž์‚ฐ", +} + +_KEY_ACCOUNTS_MAP = { + "BS": _KEY_ACCOUNTS_BS, + "IS": _KEY_ACCOUNTS_IS, + "CF": _KEY_ACCOUNTS_CF, +} + + +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• +# ์ˆซ์ž ํฌ๋งทํŒ… +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• + + +def _format_won(val: float) -> str: + """์› ๋‹จ์œ„ ์ˆซ์ž๋ฅผ ์ฝ๊ธฐ ์ข‹์€ ํ•œ๊ตญ์–ด ๋‹จ์œ„๋กœ ๋ณ€ํ™˜.""" + abs_val = abs(val) + sign = "-" if val < 0 else "" + if abs_val >= 1e12: + return f"{sign}{abs_val / 1e12:,.1f}์กฐ" + if abs_val >= 1e8: + return f"{sign}{abs_val / 1e8:,.0f}์–ต" + if abs_val >= 1e4: + return f"{sign}{abs_val / 1e4:,.0f}๋งŒ" + if abs_val >= 1: + return f"{sign}{abs_val:,.0f}" + return "0" + + +def _format_krw(val: float) -> str: + """๋ฐฑ๋งŒ์› ๋‹จ์œ„ ์ˆซ์ž๋ฅผ ์ฝ๊ธฐ ์ข‹์€ ํ•œ๊ตญ์–ด ๋‹จ์œ„๋กœ ๋ณ€ํ™˜.""" + abs_val = abs(val) + sign = "-" if val < 0 else "" + if abs_val >= 1_000_000: + return f"{sign}{abs_val / 1_000_000:,.1f}์กฐ" + if abs_val >= 10_000: + return f"{sign}{abs_val / 10_000:,.0f}์–ต" + if abs_val >= 1: + return f"{sign}{abs_val:,.0f}" + if abs_val > 0: + return f"{sign}{abs_val:.4f}" + return "0" + + +def _format_usd(val: float) -> str: + """USD ์ˆซ์ž๋ฅผ ์ฝ๊ธฐ ์ข‹์€ ์˜๋ฌธ ๋‹จ์œ„๋กœ ๋ณ€ํ™˜.""" + abs_val = abs(val) + sign = "-" if val < 0 else "" + if abs_val >= 1e12: + return f"{sign}${abs_val / 1e12:,.1f}T" + if abs_val >= 1e9: + return f"{sign}${abs_val / 1e9:,.1f}B" + if abs_val >= 1e6: + return f"{sign}${abs_val / 1e6:,.0f}M" + if abs_val >= 1e3: + return f"{sign}${abs_val / 1e3:,.0f}K" + if abs_val >= 1: + return f"{sign}${abs_val:,.0f}" + return "$0" + + +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• +# ๊ณ„์ • ํ•„ํ„ฐ +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• + + +def _filter_key_accounts(df: pl.DataFrame, module_name: str) -> pl.DataFrame: + """์žฌ๋ฌด์ œํ‘œ์—์„œ ํ•ต์‹ฌ ๊ณ„์ •๋งŒ ํ•„ํ„ฐ๋ง.""" + if "๊ณ„์ •๋ช…" not in df.columns or module_name not in _KEY_ACCOUNTS_MAP: + return df + + key_set = _KEY_ACCOUNTS_MAP[module_name] + mask = pl.lit(False) + for keyword in key_set: + mask = mask | pl.col("๊ณ„์ •๋ช…").str.contains(keyword) + + filtered = df.filter(mask) + if filtered.height < 5: + return df + return filtered + + +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• +# ์—…์ข…๋ช… ์ถ”์ถœ +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• + + +def _get_sector(company: Any) -> str | None: + """Company์—์„œ ์—…์ข…๋ช… ์ถ”์ถœ.""" + try: + overview = getattr(company, "companyOverview", None) + if isinstance(overview, dict): + sector = overview.get("indutyName") or overview.get("sector") + if sector: + return sector + + detail = getattr(company, "companyOverviewDetail", None) + if isinstance(detail, dict): + sector = detail.get("sector") or detail.get("indutyName") + if sector: + return sector + except _CONTEXT_ERRORS: + pass + + return None + + +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• +# DataFrame โ†’ ๋งˆํฌ๋‹ค์šด ๋ณ€ํ™˜ +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• + + +def df_to_markdown( + df: pl.DataFrame, + max_rows: int = 30, + meta: ModuleMeta | None = None, + compact: bool = False, + market: str = "KR", +) -> str: + """Polars DataFrame โ†’ ๋ฉ”ํƒ€๋ฐ์ดํ„ฐ ์ฃผ์„ ํฌํ•จ Markdown ํ…Œ์ด๋ธ”. + + Args: + compact: True๋ฉด ์ˆซ์ž๋ฅผ ์–ต/์กฐ ๋‹จ์œ„๋กœ ๋ณ€ํ™˜ (LLM ์ปจํ…์ŠคํŠธ์šฉ). + market: "KR"์ด๋ฉด ํ•œ๊ธ€ ๋ผ๋ฒจ, "US"๋ฉด ์˜๋ฌธ ๋ผ๋ฒจ. + """ + if df is None or df.height == 0: + return "(๋ฐ์ดํ„ฐ ์—†์Œ)" + + # account ์ปฌ๋Ÿผ์˜ snakeId โ†’ ํ•œ๊ธ€/์˜๋ฌธ ๋ผ๋ฒจ ์ž๋™ ๋ณ€ํ™˜ + if "account" in df.columns: + try: + from dartlab.core.finance.labels import get_account_labels + + locale = "kr" if market == "KR" else "en" + _labels = get_account_labels(locale) + df = df.with_columns(pl.col("account").replace(_labels).alias("account")) + except ImportError: + pass + + effective_max = meta.maxRows if meta else max_rows + if compact: + effective_max = min(effective_max, 20) + + if "year" in df.columns: + df = df.sort("year", descending=True) + + if df.height > effective_max: + display_df = df.head(effective_max) + truncated = True + else: + display_df = df + truncated = False + + parts = [] + + is_krw = not meta or meta.unit in ("๋ฐฑ๋งŒ์›", "") + if meta and meta.unit and meta.unit != "๋ฐฑ๋งŒ์›": + parts.append(f"(๋‹จ์œ„: {meta.unit})") + elif compact and is_krw: + parts.append("(๋‹จ์œ„: ์–ต/์กฐ์›, ์›๋ณธ ๋ฐฑ๋งŒ์›)") + + if not compact and meta and meta.columns: + col_map = {c.name: c for c in meta.columns} + described = [] + for col in display_df.columns: + if col in col_map: + c = col_map[col] + desc = f"`{col}`: {c.description}" + if c.unit: + desc += f" ({c.unit})" + described.append(desc) + if described: + parts.append(" | ".join(described)) + + cols = display_df.columns + if not compact and meta and meta.columns: + col_map = {c.name: c for c in meta.columns} + header_cells = [] + for col in cols: + if col in col_map: + header_cells.append(f"{col} ({col_map[col].description})") + else: + header_cells.append(col) + header = "| " + " | ".join(header_cells) + " |" + else: + header = "| " + " | ".join(cols) + " |" + + sep = "| " + " | ".join(["---"] * len(cols)) + " |" + + rows = [] + for row in display_df.iter_rows(): + cells = [] + for i, val in enumerate(row): + if val is None: + cells.append("-") + elif isinstance(val, (int, float)): + col_name = cols[i] + if compact and is_krw and col_name.isdigit() and len(col_name) == 4: + cells.append(_format_krw(float(val))) + elif isinstance(val, float): + if abs(val) >= 1: + cells.append(f"{val:,.0f}") + else: + cells.append(f"{val:.4f}") + elif col_name == "year" or (isinstance(val, int) and 1900 <= val <= 2100): + cells.append(str(val)) + else: + cells.append(f"{val:,}") + else: + cells.append(str(val)) + rows.append("| " + " | ".join(cells) + " |") + + parts.append("\n".join([header, sep] + rows)) + + if truncated: + parts.append(f"(์ƒ์œ„ {effective_max}ํ–‰ ํ‘œ์‹œ, ์ „์ฒด {df.height}ํ–‰)") + + return "\n".join(parts) + + +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• +# ํŒŒ์ƒ ์ง€ํ‘œ ์ž๋™๊ณ„์‚ฐ +# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• + + +def _find_account_value(df: pl.DataFrame, keyword: str, year_col: str) -> float | None: + """๊ณ„์ •๋ช…์—์„œ ํ‚ค์›Œ๋“œ๋ฅผ ํฌํ•จํ•˜๋Š” ํ–‰์˜ ๊ฐ’ ์ถ”์ถœ.""" + if "๊ณ„์ •๋ช…" not in df.columns or year_col not in df.columns: + return None + matched = df.filter(pl.col("๊ณ„์ •๋ช…").str.contains(keyword)) + if matched.height == 0: + return None + val = matched.row(0, named=True).get(year_col) + return val if isinstance(val, (int, float)) else None + + +def _compute_derived_metrics(name: str, df: pl.DataFrame, company: Any = None) -> str | None: + """ํ•ต์‹ฌ ์žฌ๋ฌด์ œํ‘œ์—์„œ YoY ์„ฑ์žฅ๋ฅ /๋น„์œจ ์ž๋™๊ณ„์‚ฐ. + + ๊ฐœ์„ : ROE, ์ด์ž๋ณด์ƒ๋ฐฐ์œจ, FCF, EBITDA ๋“ฑ ์ถ”๊ฐ€. + """ + if name not in ("BS", "IS", "CF") or df is None or df.height == 0: + return None + + year_cols = sorted( + [c for c in df.columns if c.isdigit() and len(c) == 4], + reverse=True, + ) + if len(year_cols) < 2: + return None + + lines = [] + + if name == "IS": + targets = { + "๋งค์ถœ์•ก": "๋งค์ถœ ์„ฑ์žฅ๋ฅ ", + "์˜์—…์ด์ต": "์˜์—…์ด์ต ์„ฑ์žฅ๋ฅ ", + "๋‹น๊ธฐ์ˆœ์ด์ต": "์ˆœ์ด์ต ์„ฑ์žฅ๋ฅ ", + } + for acct, label in targets.items(): + metrics = [] + for i in range(min(len(year_cols) - 1, 3)): + cur = _find_account_value(df, acct, year_cols[i]) + prev = _find_account_value(df, acct, year_cols[i + 1]) + if cur is not None and prev is not None and prev != 0: + yoy = (cur - prev) / abs(prev) * 100 + metrics.append(f"{year_cols[i]}/{year_cols[i + 1]}: {yoy:+.1f}%") + if metrics: + lines.append(f"- {label}: {', '.join(metrics)}") + + # ์˜์—…์ด์ต๋ฅ , ์ˆœ์ด์ต๋ฅ  + latest = year_cols[0] + rev = _find_account_value(df, "๋งค์ถœ์•ก", latest) + oi = _find_account_value(df, "์˜์—…์ด์ต", latest) + ni = _find_account_value(df, "๋‹น๊ธฐ์ˆœ์ด์ต", latest) + if rev and rev != 0: + if oi is not None: + lines.append(f"- {latest} ์˜์—…์ด์ต๋ฅ : {oi / rev * 100:.1f}%") + if ni is not None: + lines.append(f"- {latest} ์ˆœ์ด์ต๋ฅ : {ni / rev * 100:.1f}%") + + # ์ด์ž๋ณด์ƒ๋ฐฐ์œจ (์˜์—…์ด์ต / ์ด์ž๋น„์šฉ) + interest = _find_account_value(df, "์ด์ž๋น„์šฉ", latest) + if interest is None: + interest = _find_account_value(df, "๊ธˆ์œต๋น„์šฉ", latest) + if oi is not None and interest is not None and interest != 0: + icr = oi / abs(interest) + lines.append(f"- {latest} ์ด์ž๋ณด์ƒ๋ฐฐ์œจ: {icr:.1f}x") + + # ROE (์ˆœ์ด์ต / ์ž๋ณธ์ด๊ณ„) โ€” BS๊ฐ€ ์žˆ์„ ๋•Œ + if company and ni is not None: + try: + bs = getattr(company, "BS", None) + if isinstance(bs, pl.DataFrame) and latest in bs.columns: + equity = _find_account_value(bs, "์ž๋ณธ์ด๊ณ„", latest) + if equity and equity != 0: + roe = ni / equity * 100 + lines.append(f"- {latest} ROE: {roe:.1f}%") + total_asset = _find_account_value(bs, "์ž์‚ฐ์ด๊ณ„", latest) + if total_asset and total_asset != 0: + roa = ni / total_asset * 100 + lines.append(f"- {latest} ROA: {roa:.1f}%") + except _CONTEXT_ERRORS: + pass + + elif name == "BS": + latest = year_cols[0] + debt = _find_account_value(df, "๋ถ€์ฑ„์ด๊ณ„", latest) + equity = _find_account_value(df, "์ž๋ณธ์ด๊ณ„", latest) + ca = _find_account_value(df, "์œ ๋™์ž์‚ฐ", latest) + cl = _find_account_value(df, "์œ ๋™๋ถ€์ฑ„", latest) + ta = _find_account_value(df, "์ž์‚ฐ์ด๊ณ„", latest) + + if debt is not None and equity is not None and equity != 0: + lines.append(f"- {latest} ๋ถ€์ฑ„๋น„์œจ: {debt / equity * 100:.1f}%") + if ca is not None and cl is not None and cl != 0: + lines.append(f"- {latest} ์œ ๋™๋น„์œจ: {ca / cl * 100:.1f}%") + if debt is not None and ta is not None and ta != 0: + lines.append(f"- {latest} ๋ถ€์ฑ„์ด๊ณ„/์ž์‚ฐ์ด๊ณ„: {debt / ta * 100:.1f}%") + + # ์ด์ž์‚ฐ ์ฆ๊ฐ€์œจ + for i in range(min(len(year_cols) - 1, 2)): + cur = _find_account_value(df, "์ž์‚ฐ์ด๊ณ„", year_cols[i]) + prev = _find_account_value(df, "์ž์‚ฐ์ด๊ณ„", year_cols[i + 1]) + if cur is not None and prev is not None and prev != 0: + yoy = (cur - prev) / abs(prev) * 100 + lines.append(f"- ์ด์ž์‚ฐ ์ฆ๊ฐ€์œจ {year_cols[i]}/{year_cols[i + 1]}: {yoy:+.1f}%") + + elif name == "CF": + latest = year_cols[0] + op_cf = _find_account_value(df, "์˜์—…ํ™œ๋™", latest) + inv_cf = _find_account_value(df, "ํˆฌ์žํ™œ๋™", latest) + fin_cf = _find_account_value(df, "์žฌ๋ฌดํ™œ๋™", latest) + + if op_cf is not None and inv_cf is not None: + fcf = op_cf + inv_cf + lines.append(f"- {latest} FCF(์˜์—…CF+ํˆฌ์žCF): {_format_krw(fcf)}") + + # CF ํŒจํ„ด ํ•ด์„ + if op_cf is not None and inv_cf is not None and fin_cf is not None: + pattern = f"{'+' if op_cf >= 0 else '-'}/{'+' if inv_cf >= 0 else '-'}/{'+' if fin_cf >= 0 else '-'}" + pattern_desc = _interpret_cf_pattern(op_cf >= 0, inv_cf >= 0, fin_cf >= 0) + lines.append(f"- {latest} CF ํŒจํ„ด(์˜์—…/ํˆฌ์ž/์žฌ๋ฌด): {pattern} โ†’ {pattern_desc}") + + for i in range(min(len(year_cols) - 1, 2)): + cur = _find_account_value(df, "์˜์—…ํ™œ๋™", year_cols[i]) + prev = _find_account_value(df, "์˜์—…ํ™œ๋™", year_cols[i + 1]) + if cur is not None and prev is not None and prev != 0: + yoy = (cur - prev) / abs(prev) * 100 + lines.append(f"- ์˜์—…ํ™œ๋™CF ๋ณ€๋™ {year_cols[i]}/{year_cols[i + 1]}: {yoy:+.1f}%") + + if not lines: + return None + + return "### ์ฃผ์š” ์ง€ํ‘œ (์ž๋™๊ณ„์‚ฐ)\n" + "\n".join(lines) + + +def _interpret_cf_pattern(op_pos: bool, inv_pos: bool, fin_pos: bool) -> str: + """ํ˜„๊ธˆํ๋ฆ„ ํŒจํ„ด ํ•ด์„.""" + if op_pos and not inv_pos and not fin_pos: + return "์šฐ๋Ÿ‰ ๊ธฐ์—…ํ˜• (์˜์—…์ด์ต์œผ๋กœ ํˆฌ์ž+์ƒํ™˜)" + if op_pos and not inv_pos and fin_pos: + return "์„ฑ์žฅ ํˆฌ์žํ˜• (์˜์—…+์ฐจ์ž…์œผ๋กœ ์ ๊ทน ํˆฌ์ž)" + if op_pos and inv_pos and not fin_pos: + return "๊ตฌ์กฐ์กฐ์ •ํ˜• (์ž์‚ฐ ๋งค๊ฐ+๋ถ€์ฑ„ ์ƒํ™˜)" + if not op_pos and not inv_pos and fin_pos: + return "์œ„ํ—˜ ์‹ ํ˜ธ (์˜์—…์ ์ž์ธ๋ฐ ์ฐจ์ž…์œผ๋กœ ํˆฌ์ž)" + if not op_pos and inv_pos and fin_pos: + return "์œ„๊ธฐ ๊ด€๋ฆฌํ˜• (์ž์‚ฐ ๋งค๊ฐ+์ฐจ์ž…์œผ๋กœ ์˜์—… ๋ณด์ „)" + if not op_pos and inv_pos and not fin_pos: + return "์ถ•์†Œํ˜• (์ž์‚ฐ ๋งค๊ฐ์œผ๋กœ ๋ถ€์ฑ„ ์ƒํ™˜)" + return "๊ธฐํƒ€ ํŒจํ„ด" diff --git a/src/dartlab/ai/context/snapshot.py b/src/dartlab/ai/context/snapshot.py new file mode 100644 index 0000000000000000000000000000000000000000..b05d64673f3e5ef1cb85d14833cc297fff18f40b --- /dev/null +++ b/src/dartlab/ai/context/snapshot.py @@ -0,0 +1,198 @@ +"""ํ•ต์‹ฌ ์ˆ˜์น˜ ์Šค๋ƒ…์ƒท ๋นŒ๋“œ โ€” server ์˜์กด์„ฑ ์—†๋Š” ์ˆœ์ˆ˜ ๋กœ์ง. + +server/chat.py์˜ build_snapshot()์—์„œ ์ถ”์ถœ. +""" + +from __future__ import annotations + +from typing import Any + +from dartlab.ai.context.company_adapter import get_headline_ratios + + +def _fmt(val: float | int | None, suffix: str = "") -> str | None: + if val is None: + return None + abs_v = abs(val) + sign = "-" if val < 0 else "" + if abs_v >= 1e12: + return f"{sign}{abs_v / 1e12:,.1f}์กฐ{suffix}" + if abs_v >= 1e8: + return f"{sign}{abs_v / 1e8:,.0f}์–ต{suffix}" + if abs_v >= 1e4: + return f"{sign}{abs_v / 1e4:,.0f}๋งŒ{suffix}" + if abs_v >= 1: + return f"{sign}{abs_v:,.0f}{suffix}" + return f"0{suffix}" + + +def _pct(val: float | None) -> str | None: + return f"{val:.1f}%" if val is not None else None + + +def _judge_pct(val: float | None, good: float, caution: float) -> str | None: + if val is None: + return None + if val >= good: + return "good" + if val >= caution: + return "caution" + return "danger" + + +def _judge_pct_inv(val: float | None, good: float, caution: float) -> str | None: + if val is None: + return None + if val <= good: + return "good" + if val <= caution: + return "caution" + return "danger" + + +def build_snapshot(company: Any, *, includeInsights: bool = True) -> dict | None: + """ratios + ํ•ต์‹ฌ ์‹œ๊ณ„์—ด์—์„œ ์ฆ‰์‹œ ํ‘œ์‹œํ•  ์Šค๋ƒ…์ƒท ๋ฐ์ดํ„ฐ ์ถ”์ถœ.""" + ratios = get_headline_ratios(company) + if ratios is None: + return None + if not hasattr(ratios, "revenueTTM"): + return None + + isFinancial = False + sectorInfo = getattr(company, "sector", None) + if sectorInfo is not None: + try: + from dartlab.analysis.comparative.sector.types import Sector + + isFinancial = sectorInfo.sector == Sector.FINANCIALS + except (ImportError, AttributeError): + isFinancial = False + + items: list[dict[str, Any]] = [] + roeGood, roeCaution = (8, 5) if isFinancial else (10, 5) + roaGood, roaCaution = (0.5, 0.2) if isFinancial else (5, 2) + + if ratios.revenueTTM is not None: + items.append({"label": "๋งค์ถœ(TTM)", "value": _fmt(ratios.revenueTTM), "status": None}) + if ratios.operatingIncomeTTM is not None: + items.append( + { + "label": "์˜์—…์ด์ต(TTM)", + "value": _fmt(ratios.operatingIncomeTTM), + "status": "good" if ratios.operatingIncomeTTM > 0 else "danger", + } + ) + if ratios.netIncomeTTM is not None: + items.append( + { + "label": "์ˆœ์ด์ต(TTM)", + "value": _fmt(ratios.netIncomeTTM), + "status": "good" if ratios.netIncomeTTM > 0 else "danger", + } + ) + if ratios.operatingMargin is not None: + items.append( + { + "label": "์˜์—…์ด์ต๋ฅ ", + "value": _pct(ratios.operatingMargin), + "status": _judge_pct(ratios.operatingMargin, 10, 5), + } + ) + if ratios.roe is not None: + items.append({"label": "ROE", "value": _pct(ratios.roe), "status": _judge_pct(ratios.roe, roeGood, roeCaution)}) + if ratios.roa is not None: + items.append({"label": "ROA", "value": _pct(ratios.roa), "status": _judge_pct(ratios.roa, roaGood, roaCaution)}) + if ratios.debtRatio is not None: + items.append( + { + "label": "๋ถ€์ฑ„๋น„์œจ", + "value": _pct(ratios.debtRatio), + "status": _judge_pct_inv(ratios.debtRatio, 100, 200), + } + ) + if ratios.currentRatio is not None: + items.append( + { + "label": "์œ ๋™๋น„์œจ", + "value": _pct(ratios.currentRatio), + "status": _judge_pct(ratios.currentRatio, 150, 100), + } + ) + if ratios.fcf is not None: + items.append({"label": "FCF", "value": _fmt(ratios.fcf), "status": "good" if ratios.fcf > 0 else "danger"}) + if ratios.revenueGrowth3Y is not None: + items.append( + { + "label": "๋งค์ถœ 3Y CAGR", + "value": _pct(ratios.revenueGrowth3Y), + "status": _judge_pct(ratios.revenueGrowth3Y, 5, 0), + } + ) + if ratios.roic is not None: + items.append( + { + "label": "ROIC", + "value": _pct(ratios.roic), + "status": _judge_pct(ratios.roic, 15, 8), + } + ) + if ratios.interestCoverage is not None: + items.append( + { + "label": "์ด์ž๋ณด์ƒ๋ฐฐ์œจ", + "value": f"{ratios.interestCoverage:.1f}x", + "status": _judge_pct(ratios.interestCoverage, 5, 1), + } + ) + pf = getattr(ratios, "piotroskiFScore", None) + if pf is not None: + items.append( + { + "label": "Piotroski F", + "value": f"{pf}/9", + "status": "good" if pf >= 7 else ("caution" if pf >= 4 else "danger"), + } + ) + az = getattr(ratios, "altmanZScore", None) + if az is not None: + items.append( + { + "label": "Altman Z", + "value": f"{az:.2f}", + "status": "good" if az > 2.99 else ("caution" if az >= 1.81 else "danger"), + } + ) + + annual = getattr(company, "annual", None) + trend = None + if annual is not None: + series, years = annual + if years and len(years) >= 2: + rev_list = series.get("IS", {}).get("sales") + if rev_list: + n = min(5, len(rev_list)) + recent_years = years[-n:] + recent_vals = rev_list[-n:] + trend = {"years": recent_years, "values": list(recent_vals)} + + if not items: + return None + + snapshot: dict[str, Any] = {"items": items} + if trend: + snapshot["trend"] = trend + if ratios.warnings: + snapshot["warnings"] = ratios.warnings[:3] + + if includeInsights: + try: + from dartlab.analysis.financial.insight.pipeline import analyze as insight_analyze + + insight_result = insight_analyze(company.stockCode, company=company) + if insight_result is not None: + snapshot["grades"] = insight_result.grades() + snapshot["anomalyCount"] = len(insight_result.anomalies) + except (ImportError, AttributeError, FileNotFoundError, OSError, RuntimeError, TypeError, ValueError): + pass + + return snapshot diff --git a/src/dartlab/ai/conversation/__init__.py b/src/dartlab/ai/conversation/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..56a6f02838efb48cafcff773fe811bedf8fa6f2c --- /dev/null +++ b/src/dartlab/ai/conversation/__init__.py @@ -0,0 +1 @@ +"""AI conversation package.""" diff --git a/src/dartlab/ai/conversation/data_ready.py b/src/dartlab/ai/conversation/data_ready.py new file mode 100644 index 0000000000000000000000000000000000000000..a6462c227d34c7e518bb076aca580814cc1a0a0b --- /dev/null +++ b/src/dartlab/ai/conversation/data_ready.py @@ -0,0 +1,71 @@ +"""AI ๋ถ„์„ ์ „ ๋ฐ์ดํ„ฐ ์ค€๋น„ ์ƒํƒœ๋ฅผ ์š”์•ฝํ•˜๋Š” ํ—ฌํผ.""" + +from __future__ import annotations + +from datetime import datetime +from typing import Any + +_DATA_CATEGORIES = ("docs", "finance", "report") + + +def getDataReadyStatus(stockCode: str) -> dict[str, Any]: + """์ข…๋ชฉ์˜ docs/finance/report ๋กœ์ปฌ ์ค€๋น„ ์ƒํƒœ๋ฅผ ๋ฐ˜ํ™˜ํ•œ๋‹ค.""" + from dartlab.core.dataLoader import _dataDir + + categories: dict[str, dict[str, Any]] = {} + available: list[str] = [] + missing: list[str] = [] + + for category in _DATA_CATEGORIES: + filePath = _dataDir(category) / f"{stockCode}.parquet" + ready = filePath.exists() + updatedAt = None + if ready: + updatedAt = datetime.fromtimestamp(filePath.stat().st_mtime).strftime("%Y-%m-%d %H:%M") + available.append(category) + else: + missing.append(category) + + categories[category] = { + "ready": ready, + "updatedAt": updatedAt, + } + + return { + "stockCode": stockCode, + "allReady": not missing, + "available": available, + "missing": missing, + "categories": categories, + } + + +def formatDataReadyStatus(stockCode: str, *, detailed: bool = False) -> str: + """๋ฐ์ดํ„ฐ ์ค€๋น„ ์ƒํƒœ๋ฅผ LLM/UI์šฉ ํ…์ŠคํŠธ๋กœ ๋ Œ๋”๋งํ•œ๋‹ค.""" + status = getDataReadyStatus(stockCode) + + if not detailed: + readyText = ", ".join(status["available"]) if status["available"] else "์—†์Œ" + missingText = ", ".join(status["missing"]) if status["missing"] else "์—†์Œ" + if status["allReady"]: + return "- ๋ฐ์ดํ„ฐ ์ƒํƒœ: docs, finance, report๊ฐ€ ๋ชจ๋‘ ์ค€๋น„๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค." + return ( + f"- ๋ฐ์ดํ„ฐ ์ƒํƒœ: ์ค€๋น„๋จ={readyText}; ๋ˆ„๋ฝ={missingText}. " + "๋ˆ„๋ฝ๋œ ๋ฐ์ดํ„ฐ๊ฐ€ ์žˆ์œผ๋ฉด ๋‹ต๋ณ€ ๋ฒ”์œ„๊ฐ€ ์ œํ•œ๋  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค." + ) + + lines = [f"## {stockCode} ๋ฐ์ดํ„ฐ ์ƒํƒœ", ""] + for category in _DATA_CATEGORIES: + info = status["categories"][category] + if info["ready"]: + lines.append(f"- **{category}**: โœ… ์žˆ์Œ (์ตœ์ข… ๊ฐฑ์‹ : {info['updatedAt']})") + else: + lines.append(f"- **{category}**: โŒ ์—†์Œ") + + if status["allReady"]: + lines.append("\n๋ชจ๋“  ๋ฐ์ดํ„ฐ๊ฐ€ ์ค€๋น„๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. ๋ฐ”๋กœ ๋ถ„์„์„ ์ง„ํ–‰ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค.") + else: + lines.append( + "\n์ผ๋ถ€ ๋ฐ์ดํ„ฐ๊ฐ€ ์—†์Šต๋‹ˆ๋‹ค. `download_data` ๋„๊ตฌ๋กœ ๋‹ค์šด๋กœ๋“œํ•˜๊ฑฐ๋‚˜, ์‚ฌ์šฉ์ž์—๊ฒŒ ๋‹ค์šด๋กœ๋“œ ์—ฌ๋ถ€๋ฅผ ๋ฌผ์–ด๋ณด์„ธ์š”." + ) + return "\n".join(lines) diff --git a/src/dartlab/ai/conversation/dialogue.py b/src/dartlab/ai/conversation/dialogue.py new file mode 100644 index 0000000000000000000000000000000000000000..b2e7f65a033be90cf893efdd83290b83585da3f3 --- /dev/null +++ b/src/dartlab/ai/conversation/dialogue.py @@ -0,0 +1,476 @@ +"""๋Œ€ํ™” ์ƒํƒœ/๋ชจ๋“œ ๋ถ„๋ฅ˜ โ€” server ์˜์กด์„ฑ ์—†๋Š” ์ˆœ์ˆ˜ ๋กœ์ง. + +server/dialogue.py์—์„œ ์ถ”์ถœ. ๊ฒฝ๋Ÿ‰ ํƒ€์ž…(types.py) ๊ธฐ๋ฐ˜. +""" + +from __future__ import annotations + +import re +from dataclasses import dataclass +from typing import Any + +from ..types import HistoryItem, ViewContextInfo +from .intent import has_analysis_intent, is_meta_question + +_LEGACY_VIEWER_RE = re.compile( + r"\[์‚ฌ์šฉ์ž๊ฐ€ ํ˜„์žฌ\s+(?P.+?)\((?P[A-Za-z0-9]+)\)\s+๊ณต์‹œ๋ฅผ ๋ณด๊ณ  ์žˆ์Šต๋‹ˆ๋‹ค" + r"(?:\s+โ€”\s+ํ˜„์žฌ ์„น์…˜:\s+(?P