Metadata-Version: 2.4
Name: algorhino-anemone
Version: 0.1.15
Summary: anemone searches trees
Author-email: Victor Gabillon <victorgabillon@gmail.com>
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://github.com/victorgabillon/anemone
Project-URL: Bug Tracker, https://github.com/victorgabillon/anemone/issues
Keywords: tree,search
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: valanga>=0.1.14
Requires-Dist: atomheart>=0.1.7
Requires-Dist: rich
Requires-Dist: sortedcollections>=2.1.0
Requires-Dist: graphviz
Provides-Extra: test
Requires-Dist: pytest>=9.0.2; extra == "test"
Requires-Dist: coverage; extra == "test"
Requires-Dist: pytest-cov>=6.0.0; extra == "test"
Provides-Extra: lint
Requires-Dist: ruff>=0.15.0; extra == "lint"
Requires-Dist: pylint>=4.0.4; extra == "lint"
Provides-Extra: typecheck
Requires-Dist: mypy>=1.18.2; extra == "typecheck"
Requires-Dist: pyright[nodejs]>=1.1.408; extra == "typecheck"
Requires-Dist: types-PyYAML>=6.0.12.12; extra == "typecheck"
Provides-Extra: dev
Requires-Dist: tox>=4.32.0; extra == "dev"
Requires-Dist: black>=25.1.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: sphinx; extra == "dev"
Requires-Dist: sphinx-rtd-theme; extra == "dev"
Requires-Dist: sphinx-autodoc-typehints; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Provides-Extra: nn
Requires-Dist: algorhino-coral; extra == "nn"
Requires-Dist: torch; extra == "nn"
Dynamic: license-file

# anemone

`anemone` is a Python library for tree search over `valanga` game states. It builds a
shared tree graph and layers algorithm-specific wrappers on top so you can plug in
node evaluation, exploration indices, and selection policies for "tree and value"
searches.

## Highlights

- Tree-and-value exploration pipeline driven by `TreeAndValueBranchSelector`.
- Modular factories for node evaluation, selection, index computation, and tree
  management.
- Pluggable stopping criteria and recommender rules for final branch selection.
- Optional torch-based evaluator for batched neural evaluations.

## Installation

```bash
pip install anemone
```

Optional torch integration:

```bash
pip install anemone[nn]
```

## Quick start

`anemone` exposes factory helpers to build a branch selector configured with your
node selector, evaluation, and stopping-criterion choices. At runtime you feed it a
`valanga` state and a seed to get back a branch recommendation.

```python
from random import Random

from anemone import TreeAndValuePlayerArgs, create_tree_and_value_branch_selector
from anemone.node_selector.factory import UniformArgs
from anemone.node_selector.node_selector_types import NodeSelectorType
from anemone.progress_monitor.progress_monitor import (
    StoppingCriterionTypes,
    TreeBranchLimitArgs,
)
from anemone.recommender_rule.recommender_rule import SoftmaxRule

# Populate the pieces specific to your game domain.
args = TreeAndValuePlayerArgs(
    node_selector=UniformArgs(type=NodeSelectorType.UNIFORM),
    opening_type=None,
    stopping_criterion=TreeBranchLimitArgs(
        type=StoppingCriterionTypes.TREE_BRANCH_LIMIT,
        tree_branch_limit=100,
    ),
    recommender_rule=SoftmaxRule(type="softmax", temperature=1.0),
)

selector = create_tree_and_value_branch_selector(
    state_type=YourStateType,
    args=args,
    random_generator=Random(0),
    master_state_evaluator=your_state_evaluator,
    state_representation_factory=None,
    queue_progress_player=None,
)

recommendation = selector.select_branch(state=current_state, selection_seed=0)
print(recommendation.branch_key)
```

## Design

This codebase follows a “core node + wrappers” pattern.

- **`TreeNode` (core)**
  - `TreeNode` is the canonical, shared data structure.
  - It stores the graph structure: `branches_children` and `parent_nodes`.
  - There is conceptually a single tree/graph of `TreeNode`s.

- **Wrappers implement `ITreeNode`**
  - Higher-level nodes (e.g. `AlgorithmNode`) wrap a `TreeNode` and add algorithm-specific state:
    evaluation, indices, representations, etc.
  - Wrappers expose navigation by delegating to the underlying `TreeNode`.

- **Homogeneity at the wrapper level**
  - Even though `TreeNode` is the core place where connections are stored, each wrapper is intended to be
    *closed under parent/child links*:
    - a wrapper’s `branches_children` and `parent_nodes` contain that same wrapper type.
    - today this is typically either “all `TreeNode`” or “all `AlgorithmNode`”.
    - in the future, another wrapper can exist (still implementing `ITreeNode`), and it should also be
      homogeneous within itself.

The practical motivation is:
- algorithms can be written against `ITreeNode` (for navigation) and against wrappers like `AlgorithmNode`
  (for algorithm-specific fields),
- while keeping a single shared underlying structure that can be accessed consistently from any wrapper.

## Repository layout

Each important package folder includes a local README with details. Start with:

- `src/anemone/` for the main search pipeline and public entry points.
- `src/anemone/node_selector/` for selection strategies (Uniform, RecurZipf, Sequool).
- `src/anemone/node_evaluation/` for direct evaluation and minmax tree evaluation.
- `src/anemone/tree_manager/`, `src/anemone/trees/`, and `src/anemone/updates/` for tree construction,
  expansion, and backpropagation.
- `src/anemone/indices/` for exploration index computation and updates.
- `tests/` for index and tree-building fixtures.
