Metadata-Version: 2.4
Name: evotoolkit
Version: 1.0.2
Summary: Core SDK for LLM-driven evolutionary search over executable or structured solutions.
Project-URL: Homepage, https://github.com/pgg3/evotoolkit
Project-URL: Repository, https://github.com/pgg3/evotoolkit
Project-URL: Documentation, https://evotoolkit.readthedocs.io/
Project-URL: Changelog, https://github.com/pgg3/evotoolkit/blob/main/CHANGELOG.md
Author-email: Ping Guo <pguo6680@gmail.com>
License: MIT
License-File: LICENSE
Keywords: LLM,evolutionary,optimization,toolkit
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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
Requires-Python: >=3.10
Requires-Dist: numpy
Requires-Dist: scipy
Description-Content-Type: text/markdown

# EvoToolkit Core

EvoToolkit is the core SDK for LLM-driven evolutionary search over executable or structured solutions.

The stable `1.0.2` package intentionally ships only reusable building blocks:

- built-in methods: `EoH`, `EvoEngineer`, `FunSearch`
- runtime lifecycle bases: `Method`, `IterativeMethod`, `PopulationMethod`
- checkpointing and readable artifacts through `RunStore`
- generic `PythonTask` and `StringTask` SDK layers
- generic Python and string interfaces for the built-in methods
- OpenAI-compatible HTTP client utilities in `evotoolkit.tools`

Concrete domain tasks, hardware-backed workflows, and application-specific examples should live in your own package or repository on top of this core.

## Install

```bash
pip install evotoolkit
```

## Quick Start

```python
from evotoolkit import EvoEngineer
from evotoolkit.core import EvaluationResult, TaskSpec
from evotoolkit.task.python_task import EvoEngineerPythonInterface, PythonTask
from evotoolkit.tools import HttpsApi


class SquareTask(PythonTask):
    def build_python_spec(self, data) -> TaskSpec:
        return TaskSpec(
            name="square",
            prompt="Write a Python function `f(x)` that returns a numeric value.",
            modality="python",
        )

    def _evaluate_code_impl(self, candidate_code: str) -> EvaluationResult:
        namespace = {}
        exec(candidate_code, namespace)  # noqa: S102
        if "f" not in namespace:
            return EvaluationResult(valid=False, score=float("-inf"), additional_info={"error": "Function `f` was not defined."})
        return EvaluationResult(valid=True, score=float(namespace["f"](3)), additional_info={})


task = SquareTask(data=None)
interface = EvoEngineerPythonInterface(task)
llm_api = HttpsApi(
    api_url="https://api.openai.com/v1/chat/completions",
    key="your-api-key",
    model="gpt-4o",
)
algo = EvoEngineer(
    interface=interface,
    output_path="./results",
    running_llm=llm_api,
    max_generations=5,
)
best_solution = algo.run()
```

## Documentation

The published documentation mirrors the `docs/` directory and keeps the core pages in English and Chinese:

- `index`
- `installation`
- `quickstart`
- `extensions`
- `migration`

## Development

```bash
uv sync --group dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mkdocs build
uv build --out-dir dist
```

The runnable repository example lives in `examples/custom_task/my_custom_task.py`.

## Runtime Artifacts

Each run writes:

- `checkpoint/state.pkl`
- `checkpoint/manifest.json`
- readable `history/*.json`
- readable `summary/*.json`

Checkpoint restore is explicit: recreate the algorithm object, call `load_checkpoint()`, then call `run()` again.
