Metadata-Version: 2.4
Name: trail-lang
Version: 0.1.0
Summary: A declarative expression language for financial indicators, scoring, and screening over security panels
Project-URL: Homepage, https://github.com/trail-language
Project-URL: Repository, https://github.com/trail-language/trail-py
Project-URL: Specification, https://github.com/trail-language/spec
Project-URL: Issues, https://github.com/trail-language/trail-py/issues
Author-email: Usman Shahid <u.manshahid@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: expression-language,factor,finance,indicators,polars,quant,screening
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: lark>=1.2
Requires-Dist: polars>=1.20
Requires-Dist: pyyaml>=6
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/trail-language/spec/main/brand/icon-color-240.png" alt="Trail" width="120">
</p>

# trail-py

The reference implementation of **Trail** - a small, total, declarative language for computing
financial indicators, scores, and screening strategies over panels of securities. Trail
expressions compile to vectorized [Polars](https://pola.rs) operations.

The language specification (grammar, reference, standard library) lives in
[**trail-language/spec**](https://github.com/trail-language/spec).

```trail
model quality on us_main period annual {
    operating_margin = income.operating_income / income.revenue
    score om_score weight 7 {
        2 if operating_margin > 0.12
        1 if operating_margin > 0.05
        else 0
    }
    export composite = weighted_score()
}
```

## Install

```bash
pip install trail-lang        # or: uv add trail-lang
```

## CLI

```bash
trail validate models/quality.trail                 # parse, kind-check, dry-run
trail run models/quality.trail --model quality      # evaluate a model
trail run models/quality.trail --model quality --config trail.yaml
trail catalog                                       # discover fields, functions, sources
trail catalog income                                # fields in a namespace
trail catalog cagr                                  # describe a function
```

The standard library is loaded implicitly; pass `--no-stdlib` to opt out.

## Library

```python
from trail.pipeline import prepare
from trail.compiler import compile_model
from trail.fixtures import load_panel  # a bundled demo panel

program = prepare("model m { export margin = income.operating_income / income.revenue }")
model = next(d for d in program.decls if type(d).__name__ == "ModelDecl")
result = compile_model(model, {}).run(load_panel())
```

## Architecture

Parser (Lark LALR) → typed AST → macro expansion (`def` inlining) → kind-checked validation →
Polars compiler. The engine carries only irreducible **primitives**; the large **derived**
function library is written in Trail itself and shipped as `trail/stdlib/*.trail` (canonical
copy in the [spec](https://github.com/trail-language/spec)).

## Development

```bash
uv sync
uv run pytest -q
uv run ruff check .
```

## License

[MIT](LICENSE).
