Metadata-Version: 2.4
Name: PyDecisionGraph
Version: 0.3.1.post2
Summary: A rule-based decision tree implementation for Python
Home-page: https://github.com/BolunHan/PyDecisionGraph
Author: Han Bolun
Author-email: Han Bolun <Bolun.Han@outlook.com>
License-Expression: MPL-2.0
Project-URL: Homepage, https://github.com/BolunHan/PyDecisionGraph
Project-URL: Repository, https://github.com/BolunHan/PyDecisionGraph
Project-URL: Issues, https://github.com/BolunHan/PyDecisionGraph/issues
Keywords: decision tree,decision graph,rules,cython,HFT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: visualization
Requires-Dist: flask; extra == "visualization"
Requires-Dist: jinja2; extra == "visualization"
Provides-Extra: session-time-support
Requires-Dist: PyAlgoEngine; extra == "session-time-support"
Dynamic: license-file

# PyDecisionGraph

`PyDecisionGraph` is an easy-to-use library to create custom decision trees, primarily designed for trading and financial decision-making. This package helps you build rule-based decision processes and visualize them effectively.

## Installation

To install the package, run:

```bash
pip install PyDecisionGraph
```

# Requirements

- Python 3.12 or higher

# Documentation

For detailed documentation, visit https://pydecisiongraph.readthedocs.io/.

# Quick Start

Here is a quick demo on how to use `PyDecisionGraph` for building a decision tree based on various conditions:

```python
from decision_graph.decision_tree import LOGGER, LongAction, ShortAction, NoAction, RootLogicNode, LogicMapping

# Mapping of attribute names to their values
state = {
    "exposure": 0,  # Current exposure
    "working_order": 0,  # Current working order
    "up_prob": 0.8,  # Probability of price going up
    "down_prob": 0.2,  # Probability of price going down
    "volatility": 0.26,  # Current market volatility
    "ttl": 15.3  # Time to live (TTL) of the decision tree
}

# The store the conditions read from, entered for the scope the tree is built in
with LogicMapping(name='Root', data=state) as lg:
    # Root of the logic tree
    with RootLogicNode() as root:
        # Condition for zero exposure
        with lg.exposure == 0:
            with lg.volatility > 0.25:  # Check if volatility is high
                with lg.down_prob > 0.1:  # Action for down probability
                    LongAction()

                with lg.up_prob < -0.1:  # Action for up probability
                    ShortAction()

            # No action if there's a working order
            with lg.working_order != 0:
                NoAction()

# Visualize the decision tree
root.to_html('tree.html')

# Log the evaluation result
LOGGER.info(root())
```

## Explanation of the Script:

- LogicNode & LogicMapping:
    - LogicNode: Represents a node in the decision tree where conditions are evaluated. A node evaluates its condition and takes one of its two arms.
    - LogicMapping: The named store the conditions read from, holding the state used in decision-making. Feed it a new value and the next walk moves.

- State:
    - A dictionary containing the variables used for decision-making, such as exposure, working_order, up_prob, etc.

- RootLogicNode:
    - The entry point for the decision tree; its single child is the top of the tree.

- Decision Conditions:
    - Inside each with block, logical conditions are evaluated (e.g., lg.volatility > 0.25, lg.up_prob < -0.1) to determine which action to take.
    - Each with block nests one level deeper; the first block under a node is its true arm, the second its false arm.
    - Actions like LongAction() or ShortAction() are taken based on the conditions.

- Action Handling:
    - LongAction(), ShortAction(), and NoAction() represent different actions you can trigger in the decision tree based on the conditions.
    - An arm left empty is filled with a NoAction when the tree is evaluated.

- Logging:
    - The result of the tree evaluation is logged using the LOGGER object, which outputs to the console.

- Visualization:
    - root.to_html('tree.html') generates a standalone HTML page visualizing the decision tree. Drop the file name and the page is named after the root.

# Features

- Easily define custom decision rules.
- Actionable outcomes like LongAction, ShortAction, and NoAction.
- Log outputs for debugging and tracking.
- Visualize decision paths through HTML export.
- Bake a finished tree once (root.bake()) and let it decide in a hot loop.

---

# Contributing

Feel free to fork, submit issues, and create pull requests. Contributions are always welcome!

# License

This project is licensed under the Mozilla Public License 2.0 - see the LICENSE file for details.
