> For the complete documentation index, see [llms.txt](https://gilad-rubin.gitbook.io/hypster/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gilad-rubin.gitbook.io/hypster/migration/upgrade-0.7-to-0.8.md).

# Upgrade From 0.7 To 0.8

Hypster 0.8 removes an accidental integration namespace and renames one schema metadata key. Update those two surfaces before upgrading; ordinary config functions, `explore()`, `instantiate()`, rules, and replayable values keep their 0.7 shapes.

Install the target release and check the version:

```bash
uv add "hypster==0.8.*"
uv run python -c "import hypster; print(hypster.__version__)"
```

## Import HPO APIs From `hypster.hpo`

The removed `hypster.integrations` package used a wildcard export and exposed implementation details as if they were public. Import the HPO API from its owning package.

Before:

```python
from hypster.integrations import HpoInt, suggest_values
```

After:

```python
from hypster.hpo import HpoInt, TrialValueProvider, suggest_values

assert HpoInt(step=2).step == 2
assert callable(suggest_values)
assert TrialValueProvider.__name__ == "TrialValueProvider"
```

You can also import `suggest_values` from `hypster.hpo.optuna`. No compatibility alias remains at `hypster.integrations`.

## Read Schema Definitions From `schema_fields`

Metadata emitted by `hp.schema()` now uses `schema_fields`. The `field_specs` key remains the vocabulary for the conditions accepted by `hp.rules()`; the two concepts are intentionally distinct.

Before:

```python
fields = parameter["metadata"]["field_specs"]
```

After:

```python
from hypster import HP, SchemaField, explore


def extraction_config(hp: HP):
    return hp.schema(
        default=[SchemaField(key="invoice_number", value_type="text", required=True)],
        name="fields",
    )


schema = explore(extraction_config, return_schema=True)
metadata = schema.to_dict()["parameters"][0]["metadata"]

assert metadata["schema_fields"][0]["key"] == "invoice_number"
assert metadata["schema_fields"][0]["required"] is True
assert "field_specs" not in metadata
```

## Check HPO Behavior That Previously Failed

The 0.8 Optuna adapter validates trial suggestions through the same path as explicit values. Integer trials default to a step of `1`; log-scale integer trials enforce Optuna's step rule. Parameter kinds without an Optuna mapping, including `hp.bool`, `hp.text`, and `multi_*`, keep their validated defaults and are omitted from `suggest_values()`'s returned dictionary.

If a search relied on a raw Optuna error or on an unsupported kind appearing in returned suggestions, update the search space explicitly. See [Optuna HPO API](/hypster/reference/optuna-hpo.md) for the current mapping and error cases.

## Verify The Upgrade

Run your config tests and search for the two removed 0.7 forms:

```bash
rg -n "hypster\.integrations|\[\"field_specs\"\]" .
uv run pytest
```

An occurrence of `field_specs` can still be correct when it reads `hp.rules()` metadata.

For all user-visible 0.8 changes, see the [changelog](https://github.com/gilad-rubin/hypster/tree/master/CHANGELOG.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://gilad-rubin.gitbook.io/hypster/migration/upgrade-0.7-to-0.8.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.