Metadata-Version: 2.4
Name: algorhino-anemone
Version: 0.3.1
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.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: valanga==0.3.0
Requires-Dist: rich
Requires-Dist: sortedcollections>=2.1.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: orjson
Requires-Dist: zstandard
Provides-Extra: debug
Requires-Dist: graphviz; extra == "debug"
Provides-Extra: test
Requires-Dist: pytest==9.1.1; extra == "test"
Requires-Dist: coverage==7.17.0; extra == "test"
Requires-Dist: pytest-cov==7.1.0; extra == "test"
Requires-Dist: atomheart==0.3.0; extra == "test"
Requires-Dist: parsley-coco==0.2.0; extra == "test"
Provides-Extra: lint
Requires-Dist: ruff==0.17.3; extra == "lint"
Requires-Dist: pylint==4.1.3; extra == "lint"
Provides-Extra: typecheck
Requires-Dist: mypy==2.4.0; extra == "typecheck"
Requires-Dist: pyright[nodejs]==1.1.414; extra == "typecheck"
Requires-Dist: types-PyYAML==6.0.12.20260906; extra == "typecheck"
Provides-Extra: dev
Requires-Dist: tox==4.67.2; extra == "dev"
Requires-Dist: black==26.10.1; extra == "dev"
Requires-Dist: build==1.6.1; extra == "dev"
Requires-Dist: twine==7.0.0; extra == "dev"
Requires-Dist: sphinx==9.2.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme==3.1.0; extra == "dev"
Requires-Dist: sphinx-autodoc-typehints==3.17.3; extra == "dev"
Requires-Dist: pre-commit==4.7.0; extra == "dev"
Provides-Extra: nn
Requires-Dist: algorhino-coral<0.3.0,>=0.2.0; extra == "nn"
Requires-Dist: torch>=2.14.1; extra == "nn"
Provides-Extra: profiling-viz
Requires-Dist: streamlit>=1.44.0; extra == "profiling-viz"
Requires-Dist: snakeviz; extra == "profiling-viz"
Requires-Dist: gprof2dot; extra == "profiling-viz"
Provides-Extra: docs
Requires-Dist: sphinx==9.2.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme==3.1.0; extra == "docs"
Requires-Dist: myst-parser==5.1.0; extra == "docs"
Dynamic: license-file

# anemone

`anemone` is a Python library for tree search over `valanga` game states. It
separates structural tree storage, runtime search state, node evaluation,
exploration indices, and selector/opening logic so different search policies can
share one coherent runtime.

## Overview

The main architectural split is:

- structure: `TreeNode` and `ITreeNode`
- runtime: `AlgorithmNode` and `TreeExploration`
- evaluation: direct evaluation plus backed-up tree evaluation
- exploration: per-node exploration-index payloads and tree-wide recomputation
- selection: selectors and opening instructions that decide what to expand next

## Installation

Release 0.3.0 requires Python **3.14 or higher**. CPU release validation uses
standard CPython **3.14.10** (GIL enabled, `PYTHON_JIT=0`). Runtime dependencies
use the published `valanga==0.3.0`; test extras use `atomheart==0.3.0` and
`parsley-coco==0.2.0`. The neural extra requires Coral 0.2.x.

Run `tox --workdir /path/to/private/anemone-tox` for complete validation.
`requirements/validation-py314.txt` selects verified public foundation wheels
by URL and SHA-256 for both local tox and CI.

Published distribution names:

```bash
pip install algorhino-anemone
```

Optional extras:

```bash
pip install algorhino-anemone[nn]
pip install algorhino-anemone[debug]
```

Debug snapshot export and the debug browser's SVG rendering also require the
system Graphviz executable (`dot`).

## Getting started

The canonical public entry point is `anemone.factory.create_search`.

- Use `anemone.factory` to build a runnable search runtime.
- Treat `anemone._runtime_assembly` and `anemone.search_factory` as internal
  wiring layers behind that API.
- Use `TreeAndValueBranchSelector` only when you want the higher-level
  one-shot recommendation wrapper instead of driving the runtime directly.

```python
from random import Random

from anemone.factory import SearchArgs, create_search

# Domain-specific collaborators omitted for brevity:
# - YourStateType
# - your_dynamics
# - starting_state
# - your_evaluator
# - your_selector_args
# - your_opening_type
# - your_stopping_criterion
# - your_recommender_rule
args = SearchArgs(
    node_selector=your_selector_args,
    opening_type=your_opening_type,
    stopping_criterion=your_stopping_criterion,
    recommender_rule=your_recommender_rule,
)

runtime = create_search(
    state_type=YourStateType,
    dynamics=your_dynamics,
    starting_state=starting_state,
    args=args,
    random_generator=Random(0),
    master_state_value_evaluator=your_evaluator,
    state_representation_factory=None,
)

result = runtime.explore(Random(0))
print(result.branch_recommendation.recommended_name)
```

## Core concepts

- `TreeNode`: the concrete structural node storing state, depth, and links.
- `AlgorithmNode`: the runtime wrapper that adds tree evaluation and
  exploration-index payloads.
- `direct_value`: the immediate evaluator output for one node.
- `backed_up_value`: the subtree-derived value propagated from children.
- exploration index: optional per-node search-priority data recomputed across
  the tree by a configured strategy.

## How it works

- `create_search(...)` assembles the runtime, direct evaluator, selector
  factory, tree-evaluation factory, and tree manager.
- The initial tree is created with a directly evaluated root node.
- A selector chooses which node or branch to open next.
- The tree manager expands the structure and creates any new runtime nodes.
- Direct evaluation fills `direct_value` on newly created nodes.
- Upward propagation recomputes `backed_up_value`, branch ordering, and
  principal variation.
- Exploration-index payloads are refreshed for the next iteration.

## Documentation

- [Search iteration architecture](docs/source/search_iteration_architecture.rst)
- [Node evaluation README](src/anemone/node_evaluation/README.md)
- [Exploration indices README](src/anemone/indices/README.md)
- [Node selector README](src/anemone/node_selector/README.md)
- [Nodes README](src/anemone/nodes/README.md)
- [Search factory README](src/anemone/search_factory/README.md)
