### Install DartLab

Source: https://context7.com/eddmpython/dartlab/llms.txt

Install DartLab using uv or pip. This is the initial setup step for using the library.

```bash
uv add dartlab
# 또는
pip install dartlab
```

--------------------------------

### DartLab Installation and Basic Usage

Source: https://github.com/eddmpython/dartlab/blob/master/README.md

Instructions for installing DartLab using micropip and a basic Python example demonstrating its usage.

```APIDOC
## Installation (xlwings Lite · One line)

```python
import micropip
await micropip.install(["diff-match-patch", "openpyxl"])
await micropip.install(
    "https://huggingface.co/eddmpython/dartlab-data/resolve/main/pyodide/dartlab-latest-py3-none-any.whl",
    deps=False,
)

import dartlab
c = dartlab.Company("005930")
c.show("IS")
```

Alternatively, add `dartlab` to the `requirements.txt` in the xlwings Lite sidebar — that's all. **0 lines of local Python, 0 lines of uv, 0 lines of venv.**
```

--------------------------------

### Install Dartlab CLI

Source: https://github.com/eddmpython/dartlab/blob/master/README.md

Installs the dartlab command-line interface. This is a one-time setup step.

```bash
uv tool install dartlab        # 또는: pipx install dartlab
```

--------------------------------

### Install DartLab with Micropip

Source: https://github.com/eddmpython/dartlab/blob/master/README.md

Install dartlab and its dependencies using micropip for browser environments. This method avoids local Python setup.

```python
import micropip
await micropip.install(["diff-match-patch", "openpyxl"])
await micropip.install(
    "https://huggingface.co/eddmpython/dartlab-data/resolve/main/pyodide/dartlab-latest-py3-none-any.whl",
    deps=False,
)

import dartlab
c = dartlab.Company("005930")
c.show("IS")
```

--------------------------------

### Start External Channel Adapter

Source: https://github.com/eddmpython/dartlab/blob/master/CAPABILITIES.md

Starts an external channel adapter for a specified platform.

```APIDOC
## POST /api/channels/{platform}/start

### Description
Starts an external channel adapter.

### Method
POST

### Endpoint
/api/channels/{platform}/start

### Parameters
#### Path Parameters
- **platform** (string) - Required - The platform for the channel adapter.
```

--------------------------------

### Install dartlab

Source: https://github.com/eddmpython/dartlab/blob/master/notebooks/colab/05_analysis.ipynb

Install the dartlab library using pip. This is a prerequisite for using the library's functionalities.

```python
%pip install -q dartlab
```

--------------------------------

### Get Credit Rating Guide

Source: https://github.com/eddmpython/dartlab/blob/master/src/dartlab/skills/specs/engines/credit/SKILL.md

Retrieves a guide listing the seven axes used for credit assessment, including their labels, descriptions, examples, and groups. This is called when no stock code is specified.

```python
import dartlab

# 1. 가이드 (7 축 목록)
guide = dartlab.credit()
```

--------------------------------

### DartLab Engine Guide and Example Call

Source: https://github.com/eddmpython/dartlab/blob/master/notebooks/colab/README.md

Use this pattern to interact with DartLab engines. Call the engine without arguments to list available axes, then call it with a specific axis to get data. Refer to the ops documentation for detailed usage of each engine.

```python
import dartlab
dartlab.엔진()        # 가이드 — 어떤 축이 있는지 출력
dartlab.엔진("축")    # 단일 예시
```

--------------------------------

### Install and Run Marimo Notebook

Source: https://github.com/eddmpython/dartlab/blob/master/notebooks/marimo/README.md

Install the necessary packages and launch a Marimo notebook for editing. Alternatively, open notebooks directly via marimo.app.

```bash
pip install marimo dartlab
marimo edit notebooks/marimo/05_analysis.py
```

--------------------------------

### Initialize DartLab Engine

Source: https://github.com/eddmpython/dartlab/blob/master/README.md

Use `dartlab.engine()` to access the guide and `dartlab.engine("축")` to execute specific functions. This is the primary entry point for interacting with DartLab's core functionalities.

```python
dartlab.엔진()
```

```python
dartlab.엔진("축")
```

--------------------------------

### Financial Analysis Setup

Source: https://github.com/eddmpython/dartlab/blob/master/blog/05-company-reports/52-189300-intellian/index.md

Initializes financial analysis by calling the 'financial' analysis function and retrieving cost structure data. It includes a comment with projected cost breakdowns for 2025.

```python
prof = c.analysis("financial", "비용구조")
# 2025: 원재료 1,628억, 인건비 744억, 감가상각 166억
```

--------------------------------

### Get Scan Engine Guide

Source: https://github.com/eddmpython/dartlab/blob/master/src/dartlab/skills/specs/engines/scan/SKILL.md

Call dartlab.scan() without arguments to get a DataFrame of available scan axes and their representative calls. This is useful for understanding the engine's capabilities.

```python
import dartlab

# 전체 스캔 축 가이드
guide = dartlab.scan()
```

--------------------------------

### Initialize Project with uv

Source: https://github.com/eddmpython/dartlab/blob/master/blog/02-dartlab-news/01-dartlab-easy-start/index.md

Initializes the current directory as a Python project managed by uv. This sets up the necessary configuration for uv to manage dependencies and environments.

```bash
uv init
```

--------------------------------

### Instantiate and Select Company Data (Cosmax Example)

Source: https://github.com/eddmpython/dartlab/blob/master/blog/05-company-reports/86-161890-kolmar/index.md

Create a `Company` object with a specific ID and then use `select` to retrieve financial data. This example shows how to get revenue and operating profit for Cosmax.

```python
c192=Company("192820"); c192.select("IS",["매출액"])
```

```python
c192.select("IS",["금융비용"])
```

```python
c192.select("BS",["비지배지분"])
```

```python
c192.select("BS",["무형자산"])
```

```python
c192.select("IS",["당기순이익"])
```

```python
c192.select("IS",["매출액"])
```

```python
c192.select("IS",["영업이익"])
```

```python
c192.select("BS",["비지배지분"])
```

```python
c192.select("BS",["무형자산"])
```

--------------------------------

### Python Recipe Execution Example

Source: https://github.com/eddmpython/dartlab/blob/master/src/dartlab/skills/specs/recipes/credit/macroStress.md

Demonstrates how to execute the macro stress testing recipe using Python, including capturing results for further analysis. Ensure all required evidence parameters are correctly provided.

```python
from dartlab.skills.recipes.credit import macroStress

# Example of calling the recipe
result = macroStress.run(
    skillRef=macroStress.SKILL_REF,
    tableRef=macroStress.TABLE_REF,
    valueRef=macroStress.VALUE_REF,
    dateRef=macroStress.DATE_REF,
    capture=True
)
```

--------------------------------

### Analysis Engine - Public Call Methods

Source: https://github.com/eddmpython/dartlab/blob/master/src/dartlab/skills/specs/engines/analysis/SKILL.md

Demonstrates various ways to call the Analysis engine, from getting general guides to executing specific analyses.

```APIDOC
## Analysis Engine - Public Call Methods

### Description
This section details how to invoke the Analysis engine, covering scenarios from retrieving analysis guides to performing specific financial and valuation analyses.

### Method
`Company.analysis()` or `dartlab.analysis()`

### Endpoints
- `Company.analysis()`
- `dartlab.analysis()`

### Usage Examples

#### 1. Get All Analysis Axes Guide
```python
import dartlab

c = dartlab.Company("005930")
guide = c.analysis()
```

#### 2. Get Group Guide or Calculation Items within a Group
```python
financial_guide = c.analysis("financial")
```

#### 3. Execute Specific Analysis Axis
```python
profitability = c.analysis("financial", "수익성")
cashflow = c.analysis("financial", "현금흐름")
valuation = c.analysis("valuation", "가치평가")
forecast = c.analysis("forecast", "매출전망")
```

#### 4. Execute Using Axis Name Only
```python
profitability_by_axis = c.analysis("수익성")
```

#### 5. Module Function Call (Company object passed via keyword)
```python
profitability_module = dartlab.analysis("financial", "수익성", company=c)
valuation_module = dartlab.analysis("valuation", "가치평가", company=c)

# Or using stockCode directly
profitability_stockcode = dartlab.analysis("financial", "수익성", stockCode="005930")
```

### Notes
- When the `axis` is not provided, the engine returns a DataFrame of executable analysis axes, serving as a public menu for users.
- Providing only the `group` returns the guide for that group's axes or calculation items.
- When both `group` and `axis` are provided, or just the axis name, the engine executes the specified analysis.
- The engine reads data snapshots from `Company` and performs calculations. Insufficient data is handled by returning flags, assumptions, and null values instead of imputing zeros.
- The `analysis` engine does not import other L2 engines or L1.5/L3 combiners internally; it reads data directly from L1/core layers. Combinations are handled by `story`.
```

--------------------------------

### AI Comprehensive Opinion (Commented Out)

Source: https://github.com/eddmpython/dartlab/blob/master/notebooks/colab/08_story.ipynb

Example of how to use the `dartlab.ask()` function to get an AI-generated comprehensive opinion on a company, potentially from a specific analytical perspective. This code is commented out.

```python
# dartlab.ask("삼성전자 반도체 사이클 관점에서 평가해줘")
```

--------------------------------

### Initialize Company and Load Analysis Data

Source: https://github.com/eddmpython/dartlab/blob/master/src/dartlab/skills/specs/recipes/macro/scenarioAnalysis.md

Instantiate a Company object and load forecast, sensitivity, macro scenario, and regime data. This is the initial setup for performing scenario analysis.

```python
import dartlab

c = dartlab.Company("005930")

forecast = c.analysis("forecast", "매출전망")
sensitivity = c.analysis("financial", "macro민감도")
macro_scenario = dartlab.macro("scenario")
regime = c.quant("국면")
```

--------------------------------

### Scan Engine - Public Call Methods

Source: https://github.com/eddmpython/dartlab/blob/master/src/dartlab/skills/specs/engines/scan/SKILL.md

Demonstrates how to use the dartlab.scan() function for various scanning purposes, including getting guides, executing specific axes, and using primitive or screen-based scans.

```APIDOC
## Scan Engine - Public Call Methods

### Description
This section shows how to invoke the Scan engine's capabilities using the `dartlab.scan()` function. It covers obtaining a guide DataFrame for all scan axes, executing specific scan axes, and utilizing primitive or screen-based scanning functionalities.

### Method
`dartlab.scan()`

### Examples

#### Get All Scan Axis Guides
```python
import dartlab

# Get a guide DataFrame for all scan axes
guide = dartlab.scan()
```

#### Execute Specific Scan Axes
```python
# Execute specific axes like 'quality', 'valuation', or 'cashflow'
quality = dartlab.scan("quality")
valuation = dartlab.scan("valuation")
cashflow = dartlab.scan("cashflow")
```

#### Use Primitive Axes (Account and Ratio)
```python
# Access primitive axes for specific accounts or ratios
revenue = dartlab.scan("account", "매출액")
roe = dartlab.scan("ratio", "roe")
```

#### Conditional Screening
```python
# Use 'fields' to find fields for conditional screening
fields = dartlab.scan("fields", "roe")

# Perform screening using presets like 'value'
value = dartlab.scan("screen", "value")

# Perform custom screening using a spec
custom = dartlab.scan("screen", spec={"filters": []})
```

### Notes
- The `dartlab.scan()` function can be called with or without arguments.
- When called without arguments, it returns a guide DataFrame for all available scan axes.
- Specific axes like 'account' and 'ratio' can take additional arguments to specify the exact metric.
- The 'screen' axis allows for conditional screening based on presets or custom specifications.
```

--------------------------------

### Create Project Directory

Source: https://github.com/eddmpython/dartlab/blob/master/blog/02-dartlab-news/01-dartlab-easy-start/index.md

Creates a new directory named 'my-analysis' for your project. You can replace 'my-analysis' with any desired folder name.

```bash
mkdir my-analysis
```

--------------------------------

### Navigate to Project Directory

Source: https://github.com/eddmpython/dartlab/blob/master/blog/02-dartlab-news/01-dartlab-easy-start/index.md

Changes the current directory to the 'my-analysis' folder you just created. This is where your project files will reside.

```bash
cd my-analysis
```

--------------------------------

### Classify Companies by Cash Flow Patterns

Source: https://github.com/eddmpython/dartlab/blob/master/blog/02-dartlab-news/03-scan-market-finance/index.md

Categorize all listed companies into one of eight cash flow patterns. This example uses `dartlab.scan` to get cash flow data and `value_counts` to show the distribution of identified patterns.

```python
cf = dartlab.scan("cashflow")
print(cf["패턴"].value_counts())
```

--------------------------------

### Call Macro Engine for Market Analysis

Source: https://github.com/eddmpython/dartlab/blob/master/src/dartlab/skills/specs/engines/macro/SKILL.md

Use dartlab.macro() to get a guide DataFrame for all 12 axes. Specify an axis and market (e.g., 'KR' for Korea, 'US' for United States) to retrieve specific market data.

```python
import dartlab

guide = dartlab.macro()
cycle = dartlab.macro("cycle", market="KR")
rates = dartlab.macro("금리", market="US")
scenario = dartlab.macro("시나리오", "2008 금융위기")
summary = dartlab.macro("종합", market="KR")
```

--------------------------------

### Gather Engine - Module Callable (Recommended)

Source: https://github.com/eddmpython/dartlab/blob/master/src/dartlab/skills/specs/engines/gather/SKILL.md

Use dartlab.gather as the recommended entry point for the Gather engine. It dispatches based on the provided axis. Call dartlab.gather() without arguments to get a guide DataFrame of all available axes.

```python
import dartlab

dartlab.gather()                              # 가이드 DataFrame (전체 axis 목록)
dartlab.gather("price", "005930")             # KR OHLCV
dartlab.gather("price", "AAPL", market="US")  # US OHLCV
dartlab.gather("flow", "005930")              # 수급
dartlab.gather("macro")                       # KR 거시지표 wide
dartlab.gather("macro", "FEDFUNDS")           # FRED 자동 감지
dartlab.gather("news", "삼성전자")             # Google News RSS
dartlab.gather("calendar", "005930")          # 정기공시 due (DART_API_KEY)
dartlab.gather("krxIndex", "close", market="KOSPI")  # 시장군 지수

c = dartlab.Company("005930")
c.gather("price")                             # 종목코드/market 자동 주입
```

--------------------------------

### Quant Beta Engine Usage

Source: https://github.com/eddmpython/dartlab/blob/master/src/dartlab/skills/specs/engines/quant/beta.md

Demonstrates how to invoke the Quant Beta engine using both string-based and accessor-based methods.

```APIDOC
## Quant Beta Engine

### Description

The Quant Beta engine calculates market/sector/style benchmark-selected beta, CAPM, Alpha, and R-squared for a given stock.

### Method

Direct function call or accessor method.

### Endpoint

N/A (SDK function)

### Parameters

- **ticker** (string): The stock ticker symbol or a list of ticker symbols.
- **period** (string, optional): The reference period for the calculation.
- **benchmark** (string, optional): The benchmark to use for beta calculation (e.g., KOSPI, S&P).

### Request Example

```python
import dartlab

# 1. String call
result = dartlab.quant("beta", "005930")

# 2. Accessor call (equivalent)
result = dartlab.quant.beta("005930")
```

### Response

- **dict or DataFrame**: Contains beta, CAPM, Alpha, R-squared, and other relevant metrics.
- **flags**: Indicates any issues or assumptions made during calculation.
- **assumptions**: Details any assumptions applied.

### Response Example

```json
{
  "stockCode": "005930",
  "corpName": "Samsung Electronics",
  "latestAsOf": "2023-10-27",
  "beta": 1.15,
  "alpha": 0.02,
  "rSquared": 0.85,
  "flags": [],
  "assumptions": []
}
```
```

--------------------------------

### Verify uv Installation

Source: https://github.com/eddmpython/dartlab/blob/master/blog/02-dartlab-news/01-dartlab-easy-start/index.md

After installing uv, run this command to verify the installation and check the installed version. Close and reopen your terminal before running this command.

```bash
uv --version
```

--------------------------------

### Initialize and Use Company Engine

Source: https://github.com/eddmpython/dartlab/blob/master/src/dartlab/skills/specs/engines/company/SKILL.md

Demonstrates how to initialize the Company engine with a stock code and access various data and analysis functions. Use this to fetch raw data, perform deep analysis, or gather supplementary information for a specific company.

```python
import dartlab

c = dartlab.Company("005930")

raw = c.show("BS")
selected = c.select("매출액")
trace = c.trace("영업이익")

analysis = c.analysis("financial", "수익성")
credit = c.credit()
price = c.gather("price")
quant = c.quant("모멘텀")
macro = c.macro("사이클") 
sensitivity = c.analysis("macro", "매크로민감도") 
story = c.story()
industry = c.industry()
```

--------------------------------

### Python Usage Example

Source: https://github.com/eddmpython/dartlab/blob/master/src/dartlab/skills/specs/engines/viz/priceChart.md

Demonstrates how to use the `specPriceChart` function to generate a price chart specification for a given stock.

```APIDOC
## Python Usage Example

### Description
This example shows how to fetch historical price data and generate a price chart specification using the `dartlab` library.

### Method
```python
import dartlab
from dartlab.gather import getDefaultGather
from dartlab.viz import emit_chart
from dartlab.viz.generators import specPriceChart

g = getDefaultGather()

# 1. Fetch OHLCV for a specific stock
price = g.history("005930", start="2025-01-01", end="2025-12-31", market="KR")

# 2. Fetch benchmark data (e.g., KOSPI)
kospi = dartlab.gather("krxIndex", "raw", market="KOSPI", start="2025-01-01", end="2025-12-31")

# Generate the price chart specification
spec = specPriceChart(
    price,
    stockCode="005930",
    corpName="삼성전자",
    market="KR",
    benchmarkRows=kospi,
    benchmarkName="KOSPI",
)

# Emit the chart if the spec is generated successfully
if spec is not None:
    emit_chart(spec)
```

### Notes
- The `specPriceChart` function can handle various input formats for `rows`, including Polars DataFrames, Pandas DataFrames, and lists of dictionaries.
- It automatically calculates moving averages (MA20, MA60 by default) and benchmark relative indices if benchmark data is provided.
```

--------------------------------

### Install Python with uv

Source: https://github.com/eddmpython/dartlab/blob/master/blog/02-dartlab-news/01-dartlab-easy-start/index.md

This command uses uv to automatically install Python version 3.12. If you already have Python installed, you can skip this step.

```bash
uv python install 3.12
```