Metadata-Version: 2.4
Name: finance-flow
Version: 0.1.0
Summary: Standard financial flow models
Project-URL: Repository, https://github.com/PrettyGoodCapital/finance-flow
Project-URL: Homepage, https://github.com/PrettyGoodCapital/finance-flow
Author-email: PrettyGoodCapital <prettygoodcapital@gmail.com>
License: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python
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: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Requires-Dist: ccflow>=0.6.10
Requires-Dist: finance-datagen
Requires-Dist: finance-etl
Requires-Dist: pydantic
Provides-Extra: develop
Requires-Dist: build; extra == 'develop'
Requires-Dist: bump-my-version; extra == 'develop'
Requires-Dist: check-dist; extra == 'develop'
Requires-Dist: codespell; extra == 'develop'
Requires-Dist: hatchling; extra == 'develop'
Requires-Dist: mdformat; extra == 'develop'
Requires-Dist: mdformat-tables>=1; extra == 'develop'
Requires-Dist: pytest; extra == 'develop'
Requires-Dist: pytest-cov; extra == 'develop'
Requires-Dist: ruff; extra == 'develop'
Requires-Dist: twine; extra == 'develop'
Requires-Dist: ty; extra == 'develop'
Requires-Dist: uv; extra == 'develop'
Requires-Dist: wheel; extra == 'develop'
Description-Content-Type: text/markdown

# finance flow

Standard financial flow models

[![Build Status](https://github.com/PrettyGoodCapital/finance-flow/actions/workflows/build.yaml/badge.svg?branch=main&event=push)](https://github.com/PrettyGoodCapital/finance-flow/actions/workflows/build.yaml)
[![codecov](https://codecov.io/gh/PrettyGoodCapital/finance-flow/branch/main/graph/badge.svg)](https://codecov.io/gh/PrettyGoodCapital/finance-flow)
[![License](https://img.shields.io/github/license/PrettyGoodCapital/finance-flow)](https://github.com/PrettyGoodCapital/finance-flow)
[![PyPI](https://img.shields.io/pypi/v/finance-flow.svg)](https://pypi.python.org/pypi/finance-flow)

## Overview

`finance-flow` provides reusable finance-specific callable models, schemas, and transformations. It owns provider-neutral research and portfolio workflow logic: normalize market data, validate finance structures, build universes, calculate signals, produce target positions, backtest, and generate reports.

It does not own extraction credentials, provider clients, storage destinations, or application orchestration. Those concerns belong in `finance-etl`, connector packages, or downstream applications.

## Quick Start

Normalize provider-shaped daily aggregate rows into typed daily bars:

```python
from finance_flow import normalize_massive_daily_bars

bars = normalize_massive_daily_bars(
    {
        "results": [
            {"T": "AAPL", "o": 184.22, "h": 185.88, "l": 183.43, "c": 184.95, "v": 58414500}
        ]
    },
    ticker="AAPL",
    session_date="2024-01-03",
)
```

Use the callable wrapper when composing the transform inside a `ccflow` graph:

```python
from finance_flow import MassiveDailyBarsNormalizeContext, MassiveDailyBarsNormalizeModel

result = MassiveDailyBarsNormalizeModel()(
    MassiveDailyBarsNormalizeContext(
        payload=[{"ticker": "AAPL", "open": 1, "high": 2, "low": 1, "close": 2, "volume": 100}],
        ticker="AAPL",
        session_date="2024-01-03",
    )
)
```

## Documentation

- [Schemas](docs/src/schemas.md)
- [Transforms](docs/src/transforms.md)
- [API](docs/src/api.md)
- [Task Payload Contracts](docs/src/task-payloads.md)
- [Development](docs/src/development.md)

## Dependency Contract

- Depends on `ccflow` for callable model integration and may depend on dataframe and validation libraries needed for finance transformations.
- May be consumed by `finance-etl` and application-specific packages.
- Must not depend on connector packages unless a transformation genuinely needs optional I/O support, and must not depend on application-specific packages.

## Test Convention

Default tests should use small synthetic finance datasets and run without external services or provider credentials.
