Metadata-Version: 2.4
Name: finkritq
Version: 0.2.0
Summary: Deterministic portfolio quant core: risk, performance, optimization, and tax.
Project-URL: Homepage, https://github.com/finkrit/finkrit
Project-URL: Repository, https://github.com/finkrit/finkrit
Project-URL: Changelog, https://github.com/finkrit/finkrit/blob/main/CHANGELOG.md
Author: Finkrit
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: finance,investing,optimization,portfolio,quant,risk,tax
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.11
Requires-Dist: numpy>=2.0
Requires-Dist: scipy>=1.13
Provides-Extra: data
Requires-Dist: loguru>=0.7; extra == 'data'
Requires-Dist: pandas>=2.2; extra == 'data'
Requires-Dist: yfinance>=1.0; extra == 'data'
Description-Content-Type: text/markdown

# finkritq

Deterministic portfolio quant core: risk, performance, optimization, and tax
analytics over holdings you supply. Pure numpy and scipy, no agent or web
dependency. This is the open core of the [finkrit](https://github.com/finkrit/finkrit)
stack, published on its own for use as a standalone library.

## Install

```bash
pip install finkritq              # core: numpy + scipy
pip install "finkritq[data]"      # adds the live yfinance market data provider
```

## What it does

- **Risk**: volatility, variance, semivariance, downside deviation, drawdown
  and maximum drawdown, value at risk and conditional value at risk, beta,
  marginal and component contribution to risk, forward return range.
- **Performance**: total and annualized return, Sharpe, Sortino, Calmar,
  information ratio, Jensen's alpha, contribution to return, net of fees,
  time and money weighted return, Brinson attribution.
- **Optimization**: mean variance weights (minimum variance, maximum Sharpe,
  target return), long only and box constrained, Ledoit-Wolf shrinkage,
  rebalancing to a target or a policy.
- **Tax**: tax lots, tax-loss harvest candidates, tax-aware rebalancing.

## Quickstart

```python
from datetime import date
from decimal import Decimal

from finkritq.asset import Stock
from finkritq.datatype import Currency, Exchange
from finkritq.portfolio import Portfolio, Position, TaxLot
from finkritq.anal.risk import portfolio_volatility

stock = Stock(ticker="AAPL", currency=Currency.USD, exchange=Exchange.NASDAQ, company_name="Apple Inc")
lot = TaxLot(id="lot-1", quantity=Decimal("100"), cost_per_share=Decimal("150"), acquired=date(2022, 1, 3))
portfolio = Portfolio(id="p1", name="Demo", positions=[Position(id="pos-1", asset=stock, lots=(lot,))])
```

Feed it your own price history, or install the `data` extra to pull live daily
closes through the bundled provider.

## Runnable demo

```bash
python -m finkritq              # seeded, offline synthetic market
python -m finkritq real NVDA KO PG --benchmark SPY --years 3    # needs [data]
```

## License

Apache-2.0. See [LICENSE](LICENSE).
