codestr 0.1.0__tar.gz

codestr-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: ruff check
+        run: uvx ruff check src/
+      - name: ruff format check
+        run: uvx ruff format --check src/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install and test
+        run: |
+          uv sync --extra test
+          uv run pytest tests/ -v

codestr-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,41 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Build distributions
+        run: uv build
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/codestr
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

codestr-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+.venv/
+*.pyc
+.idea/
+.vscode/
+*.egg-info/
+dist/

codestr-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

codestr-0.1.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+- **Per-instance over-window config**: `partition_by` / `order_by` params on `CodeStr.__init__`
+  replacing the global `over` dict and `configure_over()`.
+- Multi-column support for `partition_by` and `order_by`.
+- Compiler auto-injects `partition_by`/`order_by` based on `UDFMeta.category`.
+- 163 tests covering parser, compiler, engine, syntax, registry, and all UDF operators.
+
+### Changed
+- `CodeStr.__init__` signature: `index` is now a 2-tuple `(time_col, entity_col)`.
+- TS/CS UDF functions accept `partition_by`/`order_by` keyword arguments (injected by compiler).
+- `udf/__init__.py` uses explicit module imports instead of `import *`.
+- Stricter ruff rules: added B, SIM, RUF, TCH.
+
+### Removed
+- **BREAKING**: Module-level `over` dict and `configure_over()` from `ts_udf` and `cs_udf`.
+
+### Fixed
+- `cs_midby`/`cs_meanby`: `[*over, *by]` was unpacking dict keys as column names —
+  now uses `partition_by + list(by)`.
+
+## [0.1.0] — Initial Release
+
+### Added
+- DSL parser (Lark LALR grammar): binary/unary/ternary operators, function calls, implicit multiplication
+- AST compiler that translates expressions to Polars expressions
+- `CodeStr` engine with two API modes: pure `compile()` and interactive `sql()`
+- Expression-level caching with hash-based deduplication (alias-independent)
+- Built-in UDF operators:
+  - **base_udf**: arithmetic, logical, trigonometric, and horizontal operations
+  - **cs_udf**: cross-section operators (rank, z-score, IC, quantile cut, etc.)
+  - **ts_udf**: time-series operators (rolling mean, sum, delay, delta, etc.)
+- UDF registry with `@udf` decorator for custom operators
+- CI workflow with lint and format checks (ruff)

codestr-0.1.0/CLAUDE.md

@@ -0,0 +1,105 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 项目概述
+
+CodeStr 是一个专为量化因子挖掘设计的表达式计算引擎，基于 [Polars](https://pola.rs/) 构建，提供 DSL → Polars Expr 的高效转译与执行。
+
+## 开发命令
+
+```bash
+uv sync --extra dev               # 安装项目 + 开发依赖
+uv run pytest tests/ -v           # 运行所有测试
+uv run pytest tests/test_parser.py -v  # 运行单个测试文件
+
+# 代码质量（与 CI 一致）
+uvx ruff check src/ tests/        # lint 检查
+uvx ruff format --check src/      # 格式检查（CI 模式）
+uvx ruff format src/              # 自动格式化
+```
+
+项目使用 `hatchling` 构建，`ruff` 做 lint/格式化，`mypy` 做类型检查。CI 见 `.github/workflows/ci.yml`，在 push/PR 到 master 时运行 lint + format + test matrix (3.10/3.11/3.12)。
+
+## 项目结构
+
+```
+src/codestr/
+├── __init__.py          # 公开 API：CodeStr, ExprNode, Call, Column, Literal
+├── engine.py            # CodeStr 引擎：compile() 纯编译 + sql() 交互式有状态
+├── compiler.py          # AST → Polars Expr 编译器（纯函数，无副作用）
+├── parser.py            # DSL 解析器（Lark LALR grammar + Transformer → AST）
+├── syntax.py            # AST 定义：ExprNode, Column, Literal, Call + 分析辅助函数
+├── tokens.py            # Token/TokenType 定义（RPN 分析用）
+├── errors.py            # 异常：ParseError, CompileError, PolarsError, FailError
+└── udf/
+    ├── registry.py      # UDF 注册中心（单例 + @udf 装饰器）
+    ├── base_udf.py      # 基础算子：一元/二元/三元 + 算术/逻辑运算
+    ├── cs_udf.py         # 截面算子 (Cross-Section)，如 cs_rank, cs_zscore
+    └── ts_udf.py         # 时序算子 (Time-Series)，如 ts_mean, ts_delay
+```
+
+## 核心架构
+
+### 数据流
+
+```
+DSL 字符串 → parser.parse() → AST (ExprNode) → compiler.compile() → pl.Expr → Polars 执行
+```
+
+- **Parser** (`parser.py`): 用 Lark LALR 解析器将 DSL 字符串转为 AST。`_normalize()` 预处理：`if(` → `if_(`，`!` → `~`（但保留 `!=`），移除 `$` 和换行。`as` 关键字后的别名会被注入 AST 的 `_alias` 字段。
+- **Compiler** (`compiler.py`): 纯函数，AST → `pl.Expr`。`_resolve()` 对 Literal 返回 Python 标量，对 Column/Call 返回 `pl.Expr`。`_compile()` 总是返回 `pl.Expr`（Literal 包装为 `pl.lit()`）。函数从 UDFRegistry 查找。引擎上下文通过签名检查自动注入：`dims`、`partition_by`、`order_by`。
+- **Engine** (`engine.py`): `CodeStr` 类封装了上述流程，额外管理状态（数据对齐、表达式缓存、惰性计算图）。
+
+### 两种 API 模式
+
+| 模式 | API | 副作用 | 适用场景 |
+|------|-----|--------|---------|
+| 纯编译 | `compile(expr_str) -> pl.Expr` | 无 | 批量/RL 评估 |
+| 交互式 | `sql(expr_str, lazy=False) -> pl.DataFrame` | 有（更新内部状态） | 交互式研究/GP |
+
+- `sql(lazy=True)` 返回 `pl.LazyFrame`，不物化，不更新内部状态（rollback `_data_`）。
+- `sql(lazy=False)`（默认）collect 后物化，更新 `_expr_cache` 和 `data`。
+
+### 窗口配置
+
+CodeStr 通过 `partition_by` / `order_by` 参数配置算子窗口，**不再有全局 `over` 字典**：
+
+```python
+CodeStr(df,
+    index=("datetime", "asset"),               # 面板对齐 + 结果选择
+    partition_by=["asset", "industry"],        # 实体分组轴
+    order_by=["datetime", "tick"],             # 时间排序轴
+)
+```
+
+- **TS 算子**: `over(partition_by=partition_by, order_by=order_by)` — 按实体分组，沿时间排序
+- **CS 算子**: `over(partition_by=order_by, order_by=partition_by)` — 按时间分组，沿实体排序（交换）
+
+编译器在编译期根据 `UDFMeta.category` 自动注入对应的窗口配置。`category="math"` / `"user"` 不注入。
+
+### 表达式缓存策略
+
+两层缓存，都基于 `Call.__hash__`（只看 `fn_name + args`，**别名不参与**）：
+
+1. **`_expr_cache`** — 跨查询持久化缓存，只在 eager `sql()` 成功后合并入。
+2. **`_cur_expr_cache`** — 单次查询临时缓存，查询成功后才 merge 到 `_expr_cache`。
+
+缓存命中时直接 `pl.col(cached_alias).alias(new_alias)` 复用，避免重编译。`cover=True` 强制绕过缓存。
+
+### UDF 注册
+
+`UDFRegistry` 是单例。三种注册方式：
+1. `@udf(category="ts")` 装饰器（自动推断 arity）
+2. `CodeStr.register_udf(func, name="...")` 实例方法
+3. 直接 `UDFRegistry.get_instance().register(UDFMeta(...))`
+
+编译器通过 `inspect.signature` 检查函数签名，自动注入：
+- `dims` — 如果函数接受且引擎有 dims 信息
+- `partition_by` / `order_by` — 根据 category（ts → ts_over, cs → cs_over）
+
+### DSL 语法
+
+运算符优先级（从低到高）：三元 `?:` → 或 `|` → 与 `&` → 比较 `<>` `<=` `>=` `==` `!=` → 加减 `+` `-` → 乘除 `*` `/` `//` `%` → 幂 `**` → 一元 `-` `~` → 函数调用/属性访问
+
+支持隐式乘法：`5close` → `5 * close`。支持属性链：`df.close` → `Column("df.close")`。

codestr-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing to CodeStr
+
+CodeStr is an expression compute engine for quantitative factor mining — contributions are welcome.
+
+## Getting started
+
+```bash
+git clone https://github.com/huangbogeng/codestr.git
+cd codestr
+uv sync --extra dev
+```
+
+## Development workflow
+
+```bash
+# 1. Create a feature branch from master
+git checkout -b feature/my-change
+
+# 2. Make your changes
+
+# 3. Run checks locally (same as CI)
+uvx ruff check src/ tests/
+uvx ruff format --check src/ tests/
+uv run pytest tests/ -v
+
+# 4. Commit and push
+git commit -m "feat: describe your change"
+git push -u origin feature/my-change
+```
+
+## Code style
+
+- **Formatter**: [Ruff](https://docs.astral.sh/ruff/) — 100 char line length, double quotes
+- **Type checker**: [mypy](https://www.mypy-lang.org/) — Python 3.10 target
+- **Linter**: Ruff with E, F, I, N, W, UP, B, SIM, RUF, TCH rules
+- **Tests**: pytest in `tests/` directory
+- **Build**: [hatchling](https://hatch.pypa.io/)
+
+CI will fail if any check doesn't pass.
+
+## Testing
+
+- Test files mirror the source structure: `tests/test_engine.py` tests `src/codestr/engine.py`
+- Use `conftest.py` fixtures for shared test data
+- The `reset_registry` fixture (autouse) resets the UDF registry between tests — register new UDFs in test functions, not at module level
+
+```bash
+uv run pytest tests/                     # all tests
+uv run pytest tests/test_parser.py -v    # single file
+uv run pytest tests/ -k "test_ts" -v     # filter by name
+```
+
+## Project architecture
+
+See [CLAUDE.md](./CLAUDE.md) for a detailed walkthrough of the data flow, caching, and window configuration.
+
+## Reporting issues
+
+Please include:
+- A minimal reproducible example
+- Expected vs actual behavior
+- Python version (`python --version`) and package versions (`uv pip list | grep -E "polars|codestr|lark"`)

codestr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 huangbogeng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codestr-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: codestr
+Version: 0.1.0
+Summary: DSL → Polars Expr compile engine for quantitative factor mining
+Project-URL: Repository, https://github.com/huangbogeng/codestr
+Author: huangbogeng
+License: MIT
+License-File: LICENSE
+Keywords: dsl,expression-engine,factor-mining,polars,quantitative-finance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: lark<2.0,>=1.0
+Requires-Dist: loguru<1.0,>=0.7
+Requires-Dist: numpy<3.0,>=1.26
+Requires-Dist: polars<2.0,>=1.0
+Requires-Dist: toolz<2.0,>=1.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=5.0; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# CodeStr
+
+[![CI](https://github.com/huangbogeng/codestr/actions/workflows/ci.yml/badge.svg)](https://github.com/huangbogeng/codestr/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+CodeStr 是一个专为量化因子挖掘设计的 DSL → Polars Expr 表达式计算引擎，提供高效的表达式转译、缓存与执行。
+
+## 安装
+
+```bash
+git clone https://github.com/huangbogeng/codestr.git
+cd codestr
+uv sync --extra dev
+```
+
+## 快速开始
+
+```python
+import polars as pl
+from codestr import CodeStr
+
+# 标准面板数据 (time, entity)
+df = pl.DataFrame({
+    "datetime": ["2024-01-01", "2024-01-01", "2024-01-02", "2024-01-02"],
+    "asset":    ["A", "B", "A", "B"],
+    "close":    [100.0, 200.0, 101.0, 198.0],
+    "volume":   [1000.0, 2000.0, 1100.0, 1900.0],
+})
+
+cs = CodeStr(df, index=("datetime", "asset"))
+
+# 交互式查询 — 结果自动缓存
+result = cs.sql(
+    "ts_mean(close, 5) as ma5",
+    "cs_rank(close) as rank",
+    "close / ts_delay(close, 1) - 1 as ret",
+)
+print(result)
+```
+
+## 两种 API 模式
+
+| 模式 | API | 行为 |
+|------|-----|------|
+| **纯编译** | `cs.compile(expr) -> pl.Expr` | 无副作用，返回 Polars 表达式 |
+| **交互式** | `cs.sql(expr, lazy=False) -> pl.DataFrame` | 有状态，自动缓存与复用 |
+
+```python
+# 纯编译 — 表达式可被任意 DataFrame 消费
+expr = cs.compile("ts_mean(close, 5) as ma5")
+other_df.with_columns(expr)
+
+# 交互式 — 适合逐步构建因子
+cs.sql("close + volume as total")
+cs.sql("ts_mean(total, 5) as total_ma5")  # 复用上一步的 total
+```
+
+## 窗口配置
+
+CodeStr 使用 `partition_by`（实体分组轴）和 `order_by`（时间排序轴）控制窗口算子：
+
+```python
+# 默认配置
+cs = CodeStr(df)
+# index=("datetime", "asset")
+# → TS: over(partition_by=["asset"], order_by=["datetime"])
+# → CS: over(partition_by=["datetime"], order_by=["asset"])
+
+# 自定义列名
+cs = CodeStr(df, index=("trade_date", "stock_code"))
+
+# 多列窗口 — 按行业+股票分组，按日期+逐笔序号排序
+cs = CodeStr(df,
+    index=("trade_date", "stock_code"),
+    partition_by=["industry", "stock_code"],
+    order_by=["trade_date", "tick"],
+)
+```
+
+| 算子类别 | 窗口规则 |
+|---------|---------|
+| **TS (时序)** | `over(partition_by=partition_by, order_by=order_by)` |
+| **CS (截面)** | `over(partition_by=order_by, order_by=partition_by)` |
+
+## 自定义算子
+
+```python
+from codestr.udf.registry import udf
+import polars as pl
+
+@udf(category="ts")
+def ts_ewm(expr: pl.Expr, windows, partition_by=None, order_by=None):
+    """指数加权移动平均"""
+    return expr.ewm_mean(halflife=windows).over(
+        partition_by=partition_by, order_by=order_by
+    )
+
+cs.sql("ts_ewm(close, 10) as ewm10")
+```
+
+## 内置算子
+
+**基础算子** (`base_udf`)：`abs`, `log`, `sqrt`, `square`, `cube`, `sin`, `cos`, `tan`, `exp`, `sigmoid`, `sign`, `clip`, `trunc`, `between`, `cast`, `max`, `min`, `sum`, `mean`, `arg_max`, `arg_min`, `if_`, `fib` 等
+
+**截面算子** (`cs_udf`)：`cs_rank`, `cs_zscore`, `cs_demean`, `cs_mean`, `cs_std`, `cs_var`, `cs_skew`, `cs_ic`, `cs_corr`, `cs_slope`, `cs_resid`, `cs_qcut`, `cs_midby`, `cs_meanby` 等
+
+**时序算子** (`ts_udf`)：`ts_mean`, `ts_sum`, `ts_std`, `ts_var`, `ts_skew`, `ts_kurt`, `ts_max`, `ts_min`, `ts_mid`, `ts_delay`, `ts_delta`, `ts_mad` 等
+
+## 项目结构
+
+```
+src/codestr/
+├── engine.py            # CodeStr 引擎入口
+├── compiler.py          # AST → Polars Expr 编译器
+├── parser.py            # DSL 解析器 (Lark LALR grammar)
+├── syntax.py            # AST 节点定义
+├── tokens.py            # Token 定义
+├── errors.py            # 异常类型
+└── udf/
+    ├── registry.py      # UDF 注册中心 (@udf 装饰器)
+    ├── base_udf.py      # 基础算子
+    ├── cs_udf.py         # 截面算子 (Cross-Section)
+    └── ts_udf.py         # 时序算子 (Time-Series)
+```

codestr-0.1.0/README.md

@@ -0,0 +1,126 @@
+# CodeStr
+
+[![CI](https://github.com/huangbogeng/codestr/actions/workflows/ci.yml/badge.svg)](https://github.com/huangbogeng/codestr/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+CodeStr 是一个专为量化因子挖掘设计的 DSL → Polars Expr 表达式计算引擎，提供高效的表达式转译、缓存与执行。
+
+## 安装
+
+```bash
+git clone https://github.com/huangbogeng/codestr.git
+cd codestr
+uv sync --extra dev
+```
+
+## 快速开始
+
+```python
+import polars as pl
+from codestr import CodeStr
+
+# 标准面板数据 (time, entity)
+df = pl.DataFrame({
+    "datetime": ["2024-01-01", "2024-01-01", "2024-01-02", "2024-01-02"],
+    "asset":    ["A", "B", "A", "B"],
+    "close":    [100.0, 200.0, 101.0, 198.0],
+    "volume":   [1000.0, 2000.0, 1100.0, 1900.0],
+})
+
+cs = CodeStr(df, index=("datetime", "asset"))
+
+# 交互式查询 — 结果自动缓存
+result = cs.sql(
+    "ts_mean(close, 5) as ma5",
+    "cs_rank(close) as rank",
+    "close / ts_delay(close, 1) - 1 as ret",
+)
+print(result)
+```
+
+## 两种 API 模式
+
+| 模式 | API | 行为 |
+|------|-----|------|
+| **纯编译** | `cs.compile(expr) -> pl.Expr` | 无副作用，返回 Polars 表达式 |
+| **交互式** | `cs.sql(expr, lazy=False) -> pl.DataFrame` | 有状态，自动缓存与复用 |
+
+```python
+# 纯编译 — 表达式可被任意 DataFrame 消费
+expr = cs.compile("ts_mean(close, 5) as ma5")
+other_df.with_columns(expr)
+
+# 交互式 — 适合逐步构建因子
+cs.sql("close + volume as total")
+cs.sql("ts_mean(total, 5) as total_ma5")  # 复用上一步的 total
+```
+
+## 窗口配置
+
+CodeStr 使用 `partition_by`（实体分组轴）和 `order_by`（时间排序轴）控制窗口算子：
+
+```python
+# 默认配置
+cs = CodeStr(df)
+# index=("datetime", "asset")
+# → TS: over(partition_by=["asset"], order_by=["datetime"])
+# → CS: over(partition_by=["datetime"], order_by=["asset"])
+
+# 自定义列名
+cs = CodeStr(df, index=("trade_date", "stock_code"))
+
+# 多列窗口 — 按行业+股票分组，按日期+逐笔序号排序
+cs = CodeStr(df,
+    index=("trade_date", "stock_code"),
+    partition_by=["industry", "stock_code"],
+    order_by=["trade_date", "tick"],
+)
+```
+
+| 算子类别 | 窗口规则 |
+|---------|---------|
+| **TS (时序)** | `over(partition_by=partition_by, order_by=order_by)` |
+| **CS (截面)** | `over(partition_by=order_by, order_by=partition_by)` |
+
+## 自定义算子
+
+```python
+from codestr.udf.registry import udf
+import polars as pl
+
+@udf(category="ts")
+def ts_ewm(expr: pl.Expr, windows, partition_by=None, order_by=None):
+    """指数加权移动平均"""
+    return expr.ewm_mean(halflife=windows).over(
+        partition_by=partition_by, order_by=order_by
+    )
+
+cs.sql("ts_ewm(close, 10) as ewm10")
+```
+
+## 内置算子
+
+**基础算子** (`base_udf`)：`abs`, `log`, `sqrt`, `square`, `cube`, `sin`, `cos`, `tan`, `exp`, `sigmoid`, `sign`, `clip`, `trunc`, `between`, `cast`, `max`, `min`, `sum`, `mean`, `arg_max`, `arg_min`, `if_`, `fib` 等
+
+**截面算子** (`cs_udf`)：`cs_rank`, `cs_zscore`, `cs_demean`, `cs_mean`, `cs_std`, `cs_var`, `cs_skew`, `cs_ic`, `cs_corr`, `cs_slope`, `cs_resid`, `cs_qcut`, `cs_midby`, `cs_meanby` 等
+
+**时序算子** (`ts_udf`)：`ts_mean`, `ts_sum`, `ts_std`, `ts_var`, `ts_skew`, `ts_kurt`, `ts_max`, `ts_min`, `ts_mid`, `ts_delay`, `ts_delta`, `ts_mad` 等
+
+## 项目结构
+
+```
+src/codestr/
+├── engine.py            # CodeStr 引擎入口
+├── compiler.py          # AST → Polars Expr 编译器
+├── parser.py            # DSL 解析器 (Lark LALR grammar)
+├── syntax.py            # AST 节点定义
+├── tokens.py            # Token 定义
+├── errors.py            # 异常类型
+└── udf/
+    ├── registry.py      # UDF 注册中心 (@udf 装饰器)
+    ├── base_udf.py      # 基础算子
+    ├── cs_udf.py         # 截面算子 (Cross-Section)
+    └── ts_udf.py         # 时序算子 (Time-Series)
+```