Metadata-Version: 2.4
Name: migrate2vespa
Version: 0.1.0
Summary: Workload-aware schema migration planner for Vespa
Author: Searchplex
Maintainer: Searchplex
License-Expression: Apache-2.0
Project-URL: Homepage, https://www.searchplex.net/
Project-URL: Source, https://github.com/searchplexai/migrate2vespa
Project-URL: Documentation, https://github.com/searchplexai/migrate2vespa#readme
Project-URL: Issues, https://github.com/searchplexai/migrate2vespa/issues
Project-URL: Changelog, https://github.com/searchplexai/migrate2vespa/blob/main/CHANGELOG.md
Keywords: elasticsearch,migration,opensearch,search,vespa
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Requires-Dist: pyvespa==1.2.4
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.12; extra == "dev"
Dynamic: license-file

# migrate2vespa

A workload-aware schema migration planner for Vespa, currently supporting
Elasticsearch and OpenSearch.

> Don't translate field types. Infer field requirements.

Reads local source artifacts, accounts for every supplied field, document and
representative query, and writes a reviewable migration manifest. When safe, it
also generates a Vespa application package with PyVespa.

Source-specific interpretation is isolated from the migration manifest, Vespa
planner and package generator. Additional source engines can therefore be added
without duplicating the Vespa planning pipeline.

Offline and deterministic. No cluster connections, no LLM, no behavioral-parity
claim. Built by [Searchplex](https://www.searchplex.net/).

## Quickstart

Requires Python 3.11–3.13.

```bash
python3 -m pip install migrate2vespa
migrate2vespa ./es-app
```

Results go to `./es-app/out/` by default. Try the fixture:

```bash
git clone https://github.com/searchplexai/migrate2vespa.git
cd migrate2vespa
python3 -m pip install -e .
migrate2vespa fixtures/quickstart
```

Next step printed on success: `vespa deploy --wait 600 out/vespa-app`.

## Input

```text
es-app/
├── mapping.json          # required
├── settings.json         # optional analysis settings
├── documents.jsonl       # optional representative documents
└── queries/              # optional _search request bodies
```

Canonical names preferred; a single unambiguous `*mapping*.json` /
`*setting*.json` is accepted. Documents may use `_id`/`_source` or an `id`
field. Queries supply usage evidence; they are not compiled to YQL. One source
index per run. `migrate2vespa ./mapping.json` is mapping-only.

## Output

```text
es-app/out/
├── migration-manifest.yaml
└── vespa-app/            # absent when generation is blocked or skipped
    ├── services.xml
    ├── schemas/<schema>.sd
    └── feed/documents.jsonl
```

The manifest records source semantics, evidence, capabilities, proposed Vespa
fields, decisions, risks and rule IDs, plus a coverage ledger. Generation is
`READY`, `PARTIAL` (omissions recorded; containers omitted with their children),
or `BLOCKED`. See [docs/overview.md](docs/overview.md).

## Recognized surface

| Surface | Behavior |
|---|---|
| Fields | `text`, `keyword`, `boolean`, `integer`, `long`, `float`, `double`, recognized `date`, dimensioned float `dense_vector` |
| Adaptations | Multi-fields, observed arrays, lowercase normalizers, dates → epoch seconds, vectors → tensors |
| Query evidence | `match`, `match_phrase`, `term`, `terms`, `range`, sort, basic aggregations, `knn`; custom scoring → redesign |

Unrecognized constructs are recorded, not guessed.

## CLI

```text
migrate2vespa ./es-app --analyze-only
migrate2vespa ./es-app --output ./migration-work
migrate2vespa generate ./es-app/out/migration-manifest.yaml
```

Exit codes: `0` success, `2` invalid input, `3` blocked generation, `1` other
failure. Status vocabulary: `READY`, `READY WITH CAVEATS`, `DECISION REQUIRED`,
`REDESIGN REQUIRED`.

## Trust boundary

Reads only paths you supply. Writes under the chosen output directory. No
credentials, telemetry or network clients at runtime. Review and validate the
generated package before production use — [SECURITY.md](SECURITY.md).

## Development

```bash
python3 -m pip install -e '.[dev]'
python3 -m pytest -q
scripts/validate-with-vespa-docker.sh   # needs Docker + Vespa CLI
```

See [CONTRIBUTING.md](CONTRIBUTING.md).

Copyright © 2026 Searchplex. Licensed under the Apache License 2.0.
