Metadata-Version: 2.4
Name: folioframe
Version: 0.1.0
Summary: Simple, offline portfolio analytics and bilingual self-contained HTML reports
Author: xystudio-ai
License-Expression: CC-BY-NC-4.0
Project-URL: Homepage, https://github.com/xystudio-ai/folioframe
Project-URL: Repository, https://github.com/xystudio-ai/folioframe
Project-URL: Issues, https://github.com/xystudio-ai/folioframe/issues
Project-URL: Changelog, https://github.com/xystudio-ai/folioframe/blob/main/CHANGELOG.md
Keywords: quant,portfolio,performance,risk,report
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
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.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=1.24
Requires-Dist: pandas<3,>=2.0
Requires-Dist: plotly<7,>=6
Provides-Extra: dev
Requires-Dist: build<2,>=1; extra == "dev"
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: ruff<1,>=0.12; extra == "dev"
Provides-Extra: browser
Requires-Dist: playwright<2,>=1.49; extra == "browser"
Provides-Extra: release
Requires-Dist: twine<7,>=5; extra == "release"
Dynamic: license-file

<div align="right"><strong>English</strong> · <a href="https://github.com/xystudio-ai/folioframe/blob/main/README.zh-CN.md">简体中文</a></div>

# Folioframe

[![CI](https://github.com/xystudio-ai/folioframe/actions/workflows/ci.yml/badge.svg)](https://github.com/xystudio-ai/folioframe/actions/workflows/ci.yml)
[![Python 3.10–3.13](https://img.shields.io/badge/python-3.10–3.13-2563eb)](https://www.python.org/)
[![License: CC BY-NC 4.0](https://img.shields.io/badge/license-CC%20BY--NC%204.0-0f766e)](https://github.com/xystudio-ai/folioframe/blob/main/LICENSE)

Folioframe turns user-provided Pandas return or equity series into structured portfolio analytics
and a modern, interactive, self-contained HTML report. It supports English and Simplified Chinese,
one or many strategies, and zero, one or many benchmarks.

[Open the interactive English demo](https://xystudio-ai.github.io/folioframe/demo/folioframe-demo-en.html)
· [Open the Simplified Chinese demo](https://xystudio-ai.github.io/folioframe/demo/folioframe-demo-zh-cn.html)
· [Browse the demo source](https://github.com/xystudio-ai/folioframe/blob/main/examples/generate_reports.py)

[![Folioframe report overview](https://raw.githubusercontent.com/xystudio-ai/folioframe/main/docs/assets/report-overview-en.png)](https://xystudio-ai.github.io/folioframe/demo/folioframe-demo-en.html)

[![Interactive equity comparison](https://raw.githubusercontent.com/xystudio-ai/folioframe/main/docs/assets/report-equity-en.png)](https://xystudio-ai.github.io/folioframe/demo/folioframe-demo-en.html)

## What you get

- Performance, risk, drawdown, distribution, tail-risk and data-quality metrics for every series.
- Strategy-versus-benchmark metrics for every pair, with a selector when multiple benchmarks exist.
- Interactive equity, drawdown and weekly/monthly/quarterly/yearly return comparisons.
- Consistent comparison tables: series in rows, metrics in columns, best values emphasized.
- Optional IC/RankIC, sample, model, recorded-cost and turnover diagnostics.
- Offline Plotly charts, light/dark themes and a single portable HTML file.
- Strict inputs: no downloads, silent filling, implicit alignment or inferred return/equity type.

## Install

Install the latest release from PyPI:

```bash
python -m pip install folioframe
```

To test the current unreleased `main` branch instead:

```bash
python -m pip install "folioframe @ git+https://github.com/xystudio-ai/folioframe.git"
```

For local development:

```bash
git clone https://github.com/xystudio-ai/folioframe.git
cd folioframe
python -m pip install -e ".[dev]"
```

## Quick start

```python
import pandas as pd

from folioframe import report

strategies = pd.DataFrame(
    {"My strategy": strategy_returns},
    index=pd.DatetimeIndex(dates),
)
benchmarks = pd.DataFrame(
    {"Market benchmark": benchmark_returns},
    index=strategies.index,
)

analysis = report(
    strategies,
    benchmarks,
    input_kind="returns",
    periods_per_year=252,
    risk_free_rate=0.02,
    primary_benchmark="Market benchmark",
    output="report.html",
    language="en",  # or "zh-CN"
)

print(analysis.metrics)
```

DataFrame column names are the report labels. Use `input_kind="returns"` for simple period returns
or `input_kind="equity"` for positive equity/NAV levels. All series must share the same increasing,
unique `DatetimeIndex`; Folioframe fails clearly instead of repairing inputs silently.

`periods_per_year` and `risk_free_rate` default to `None`. Metrics that need a missing assumption
are marked unavailable instead of assuming 252 observations or a zero risk-free rate. See the
[metric definitions](https://github.com/xystudio-ai/folioframe/blob/main/docs/metrics.md).

## Three public workflows

| API | Use it when |
| --- | --- |
| `report(...)` | You want analysis and an HTML file in one call. |
| `analyze(...)` | You want structured metrics and time-series results in Python. |
| `render_html(...)` | You already have an `Analysis` and want to render it separately. |

`MachineLearningDiagnostics` and `TradingDiagnostics` are independent optional inputs. If an
object or field is omitted, its report section is omitted too. They display supplied research
facts without training a model or rerunning a backtest. See
[optional diagnostics](https://github.com/xystudio-ai/folioframe/blob/main/docs/diagnostics.md).

## Reproduce the demo

The repository includes an authorized, anonymized research sample with two strategy views, two
benchmarks, a 2% risk-free assumption, IC/RankIC, recorded cost, turnover and sample diagnostics.
Names and machine-specific identifiers have been removed.

```bash
python examples/generate_reports.py
```

This writes both languages to `examples/output/`. The two canonical reports are also versioned in
[`docs/demo`](https://github.com/xystudio-ai/folioframe/tree/main/docs/demo), so visitors can
inspect the result before installing anything.

## Project structure

```text
src/folioframe/
  _core.py          input validation and portfolio calculations
  _diagnostics.py   optional research and trading diagnostics
  _render.py        the single HTML/Plotly renderer
examples/
  data/              anonymous demo inputs
  generate_reports.py
docs/
  demo/              canonical bilingual HTML reports
tests/               numerical, rendering and real-browser checks
```

The library owns generic formulas and rendering. Calling frameworks only translate their own
verified evidence into Pandas objects; no caller-specific report logic belongs in Folioframe.

## Development

```bash
python -m pip install -e ".[dev,browser,release]"
python -m playwright install chromium
ruff check .
python -m pytest
python -m build
python -m twine check dist/*
```

Tests are offline and deterministic. Contributions that change a public formula must include a
numerical regression test, metric-documentation update and changelog entry. See
[CONTRIBUTING.md](https://github.com/xystudio-ai/folioframe/blob/main/CONTRIBUTING.md).

## License

Folioframe is source-available under
[CC BY-NC 4.0](https://github.com/xystudio-ai/folioframe/blob/main/LICENSE). Sharing and adaptation
are allowed with attribution; commercial use requires separate permission. This non-commercial
license is not an OSI-approved open-source license.
