flamapy-rest 2.6.0.dev11__tar.gz → 2.9.0.dev0__tar.gz

{flamapy_rest-2.6.0.dev11 → flamapy_rest-2.9.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flamapy-rest
-Version: 2.6.0.dev11
+Version: 2.9.0.dev0
 Summary: Flamapy feature model is a distribution of the flama framework containing all plugins required to analyze feature models. It also offers a richer API and a complete command line interface and documentation.
 Author-email: Flamapy <flamapy@us.es>
 License-Expression: GPL-3.0-or-later
@@ -9,9 +9,7 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 Requires-Dist: Flask
 Requires-Dist: gunicorn
-Requires-Dist: flamapy~=2.6.0.dev11
-Requires-Dist: flask-swagger-ui
-Requires-Dist: flask-restplus
+Requires-Dist: flamapy~=2.9.0.dev0
 Requires-Dist: flask_cors
 Requires-Dist: flasgger
 Requires-Dist: Flask-Limiter
@@ -153,9 +151,14 @@ python -m flask run --host=0.0.0.0
 
 ## Usage
 
-Every public operation of FLAMAPY's `FLAMAFeatureModel` facade is exposed as a `POST` endpoint under
-`/api/v1/operations/<operation_name>`. Each call uploads a feature model file (e.g. UVL) as
-multipart form data; some operations also accept an optional `feature` or `configuration` parameter.
+The API mirrors FLAMAPY's Python facade (`FLAMAFeatureModel`): every one of its operations is a
+`POST` endpoint under `/api/v1/operations/<operation_name>`, with the same parameters as the Python
+method. Each call uploads a feature model file (e.g. UVL) as multipart form data; the other
+parameters are form fields named after the Python arguments (`configuration`, `feature`, `size`,
+`t`, …), files for the ones that take a path. Structured arguments (`objectives`,
+`configurations`) are sent as JSON text. The two operations that return a feature model
+(`generate_random_feature_model`, which needs no upload, and `generate_random_attribute`) answer
+with a JSON string that holds the model in UVL.
 
 ```bash
 # Example: count the number of valid configurations of a model
@@ -166,6 +169,58 @@ curl -X POST http://localhost:8000/api/v1/operations/configurations_number \
 The full, interactive list of endpoints — with parameters and "try it out" support — is available
 in the Swagger UI at <http://localhost:8000/docs/>.
 
+### Choosing the backend
+
+Operations that more than one solver implements take `backend`, exactly like the Python facade:
+a plugin name (`sat`, `bdd`, `z3`; `sdd`, `sharpsat`, `dnnf` when installed) or `auto`, which
+hands the choice to the query planner. `allow_approximate=true` lets `auto` also consider
+approximate implementations. Setting `FLAMAPY_BACKEND=auto` (and optionally
+`FLAMAPY_ALLOW_APPROXIMATE=1`) in the container's environment makes `auto` the default for
+every call.
+
+```bash
+curl -X POST http://localhost:8000/api/v1/operations/configurations_number \
+  -F "model=@resources/models/simple/valid_model.uvl" -F "backend=auto"
+```
+
+### Provenance
+
+The body of a response is the bare value the Python facade returns; the provenance the facade
+keeps in `last_result` travels in response headers:
+
+| Header | Meaning |
+|---|---|
+| `X-Flamapy-Plugin` / `X-Flamapy-Backend` | The plugin that produced the result and the model it ran on (`pysat`, `bdd`, `z3`, …) |
+| `X-Flamapy-Exact` | `false` when an approximate implementation produced the result |
+| `X-Flamapy-Planner` | Under `backend=auto`, the planner's choice and its reasons (estimated milliseconds, …) |
+| `X-Flamapy-Wall-Time` | Seconds spent in the operation (on a cached response, `X-Cache: HIT`, the time of the run that computed it) |
+| `X-Flamapy-Model-Hash` | Canonical hash of the uploaded model |
+| `X-Flamapy-Artifact-Cache` | `true` when the backend model was loaded from flamapy's artifact cache (`FLAMAPY_CACHE=1`) instead of being built |
+| `X-Cache` | `HIT` / `MISS` of the result cache |
+
+### Asking the planner without running anything
+
+`POST /api/v1/operations/<operation>/plan` (same `model` upload, optional `allow_approximate`)
+returns what `backend=auto` would do for that operation on that model — the facade's `plan()`:
+
+```bash
+curl -X POST http://localhost:8000/api/v1/operations/configurations_number/plan \
+  -F "model=@resources/models/simple/valid_model.uvl"
+# {"operation": "configurations_number", "plugin": "bdd_metamodel", "backend": "bdd",
+#  "transformation_chain": ["fm", "bdd"], "estimated_cost_ms": 12,
+#  "rationale": "bdd: estimated 12 ms (transformation 11, operation 1), historical default backend",
+#  "alternatives": ["sdd_metamodel", "pysat_metamodel", "z3_metamodel"]}
+```
+
+### Errors
+
+| Status | Meaning |
+|---|---|
+| `400` | Missing or invalid parameter, or a model that could not be parsed |
+| `404` | Unknown operation, or the operation could not run: an unknown backend, invalid inputs, or (under `backend=auto`) no installed plugin can handle this model. The body says why. This is the 2.6 status; 3.0 will answer these with `422` |
+| `413` / `429` / `504` | Upload too large / rate limit exceeded / operation killed after its time budget |
+| `500` | An unexpected error inside a plugin; the details go to the server log, not the response |
+
 <p align="right">(<a href="#top">back to top</a>)</p>
 
 ## Abuse controls & configuration
@@ -184,6 +239,8 @@ result cache, all configurable through environment variables (e.g. `docker run -
 | `FLAMAPY_CACHE_TTL` | `3600` | Seconds a result stays cached (same model + operation + arguments); `0` disables. Responses carry an `X-Cache: HIT|MISS` header |
 | `FLAMAPY_CACHE_MAXSIZE` | `128` | Max cached results per worker |
 | `FLAMAPY_TRUST_PROXY` | `false` | Set to `true` behind a reverse proxy so rate limits see the real client IP (`X-Forwarded-For`) |
+| `FLAMAPY_BACKEND` | unset | `auto` makes the query planner choose the backend of every call that does not name one |
+| `FLAMAPY_ALLOW_APPROXIMATE` | unset | `1` lets `auto` also pick approximate implementations |
 | `WEB_CONCURRENCY` | `2` | gunicorn worker count (Docker image) |
 | `GUNICORN_TIMEOUT` | `120` | gunicorn hard worker timeout; keep it above `FLAMAPY_OPERATION_TIMEOUT` |
 
@@ -216,3 +273,11 @@ pytest               # tests
 ```
 
 <p align="right">(<a href="#top">back to top</a>)</p>
+
+## Acknowledgements
+
+Special thanks to [José Antonio Zamudio Amaya](https://www.linkedin.com/in/joszamama/) for
+identifying the need for a REST API on top of Flamapy and for providing the first implementation of
+the idea, on which this project was built.
+
+<p align="right">(<a href="#top">back to top</a>)</p>

{flamapy_rest-2.6.0.dev11 → flamapy_rest-2.9.0.dev0}/README.md

@@ -128,9 +128,14 @@ python -m flask run --host=0.0.0.0
 
 ## Usage
 
-Every public operation of FLAMAPY's `FLAMAFeatureModel` facade is exposed as a `POST` endpoint under
-`/api/v1/operations/<operation_name>`. Each call uploads a feature model file (e.g. UVL) as
-multipart form data; some operations also accept an optional `feature` or `configuration` parameter.
+The API mirrors FLAMAPY's Python facade (`FLAMAFeatureModel`): every one of its operations is a
+`POST` endpoint under `/api/v1/operations/<operation_name>`, with the same parameters as the Python
+method. Each call uploads a feature model file (e.g. UVL) as multipart form data; the other
+parameters are form fields named after the Python arguments (`configuration`, `feature`, `size`,
+`t`, …), files for the ones that take a path. Structured arguments (`objectives`,
+`configurations`) are sent as JSON text. The two operations that return a feature model
+(`generate_random_feature_model`, which needs no upload, and `generate_random_attribute`) answer
+with a JSON string that holds the model in UVL.
 
 ```bash
 # Example: count the number of valid configurations of a model
@@ -141,6 +146,58 @@ curl -X POST http://localhost:8000/api/v1/operations/configurations_number \
 The full, interactive list of endpoints — with parameters and "try it out" support — is available
 in the Swagger UI at <http://localhost:8000/docs/>.
 
+### Choosing the backend
+
+Operations that more than one solver implements take `backend`, exactly like the Python facade:
+a plugin name (`sat`, `bdd`, `z3`; `sdd`, `sharpsat`, `dnnf` when installed) or `auto`, which
+hands the choice to the query planner. `allow_approximate=true` lets `auto` also consider
+approximate implementations. Setting `FLAMAPY_BACKEND=auto` (and optionally
+`FLAMAPY_ALLOW_APPROXIMATE=1`) in the container's environment makes `auto` the default for
+every call.
+
+```bash
+curl -X POST http://localhost:8000/api/v1/operations/configurations_number \
+  -F "model=@resources/models/simple/valid_model.uvl" -F "backend=auto"
+```
+
+### Provenance
+
+The body of a response is the bare value the Python facade returns; the provenance the facade
+keeps in `last_result` travels in response headers:
+
+| Header | Meaning |
+|---|---|
+| `X-Flamapy-Plugin` / `X-Flamapy-Backend` | The plugin that produced the result and the model it ran on (`pysat`, `bdd`, `z3`, …) |
+| `X-Flamapy-Exact` | `false` when an approximate implementation produced the result |
+| `X-Flamapy-Planner` | Under `backend=auto`, the planner's choice and its reasons (estimated milliseconds, …) |
+| `X-Flamapy-Wall-Time` | Seconds spent in the operation (on a cached response, `X-Cache: HIT`, the time of the run that computed it) |
+| `X-Flamapy-Model-Hash` | Canonical hash of the uploaded model |
+| `X-Flamapy-Artifact-Cache` | `true` when the backend model was loaded from flamapy's artifact cache (`FLAMAPY_CACHE=1`) instead of being built |
+| `X-Cache` | `HIT` / `MISS` of the result cache |
+
+### Asking the planner without running anything
+
+`POST /api/v1/operations/<operation>/plan` (same `model` upload, optional `allow_approximate`)
+returns what `backend=auto` would do for that operation on that model — the facade's `plan()`:
+
+```bash
+curl -X POST http://localhost:8000/api/v1/operations/configurations_number/plan \
+  -F "model=@resources/models/simple/valid_model.uvl"
+# {"operation": "configurations_number", "plugin": "bdd_metamodel", "backend": "bdd",
+#  "transformation_chain": ["fm", "bdd"], "estimated_cost_ms": 12,
+#  "rationale": "bdd: estimated 12 ms (transformation 11, operation 1), historical default backend",
+#  "alternatives": ["sdd_metamodel", "pysat_metamodel", "z3_metamodel"]}
+```
+
+### Errors
+
+| Status | Meaning |
+|---|---|
+| `400` | Missing or invalid parameter, or a model that could not be parsed |
+| `404` | Unknown operation, or the operation could not run: an unknown backend, invalid inputs, or (under `backend=auto`) no installed plugin can handle this model. The body says why. This is the 2.6 status; 3.0 will answer these with `422` |
+| `413` / `429` / `504` | Upload too large / rate limit exceeded / operation killed after its time budget |
+| `500` | An unexpected error inside a plugin; the details go to the server log, not the response |
+
 <p align="right">(<a href="#top">back to top</a>)</p>
 
 ## Abuse controls & configuration
@@ -159,6 +216,8 @@ result cache, all configurable through environment variables (e.g. `docker run -
 | `FLAMAPY_CACHE_TTL` | `3600` | Seconds a result stays cached (same model + operation + arguments); `0` disables. Responses carry an `X-Cache: HIT|MISS` header |
 | `FLAMAPY_CACHE_MAXSIZE` | `128` | Max cached results per worker |
 | `FLAMAPY_TRUST_PROXY` | `false` | Set to `true` behind a reverse proxy so rate limits see the real client IP (`X-Forwarded-For`) |
+| `FLAMAPY_BACKEND` | unset | `auto` makes the query planner choose the backend of every call that does not name one |
+| `FLAMAPY_ALLOW_APPROXIMATE` | unset | `1` lets `auto` also pick approximate implementations |
 | `WEB_CONCURRENCY` | `2` | gunicorn worker count (Docker image) |
 | `GUNICORN_TIMEOUT` | `120` | gunicorn hard worker timeout; keep it above `FLAMAPY_OPERATION_TIMEOUT` |
 
@@ -191,3 +250,11 @@ pytest               # tests
 ```
 
 <p align="right">(<a href="#top">back to top</a>)</p>
+
+## Acknowledgements
+
+Special thanks to [José Antonio Zamudio Amaya](https://www.linkedin.com/in/joszamama/) for
+identifying the need for a REST API on top of Flamapy and for providing the first implementation of
+the idea, on which this project was built.
+
+<p align="right">(<a href="#top">back to top</a>)</p>

{flamapy_rest-2.6.0.dev11 → flamapy_rest-2.9.0.dev0}/flamapy/interfaces/rest/operations_routes.py

@@ -5,13 +5,17 @@ import json
 import shutil
 import tempfile
 import typing
-from typing import Any, Callable
+from typing import Any, Callable, Optional
 
 from flask import Blueprint, Response, current_app, request, jsonify, abort
 from werkzeug.datastructures import FileStorage
 from werkzeug.utils import secure_filename
+from flamapy.core.exceptions import FlamaException
+from flamapy.core.models.language_level import LanguageLevel
 from flamapy.interfaces.python.flamapy_feature_model import FLAMAFeatureModel, Backend
 from flamapy.metamodels.configuration_metamodel.models import Configuration
+from flamapy.metamodels.fm_metamodel.models import FeatureModel
+from flamapy.metamodels.fm_metamodel.transformations import UVLWriter
 
 from flamapy.interfaces.rest.extensions import (
     limiter,
@@ -19,7 +23,12 @@ from flamapy.interfaces.rest.extensions import (
     default_operation_limit,
     expensive_operation_limit,
 )
-from flamapy.interfaces.rest.runner import ModelParseError, OperationTimeout, run_operation
+from flamapy.interfaces.rest.runner import (
+    ModelParseError,
+    OperationTimeout,
+    run_operation,
+    run_plan,
+)
 
 
 operations_bp = Blueprint('operations_bp', __name__, url_prefix='/api/v1/operations')
@@ -27,7 +36,12 @@ operations_bp = Blueprint('operations_bp', __name__, url_prefix='/api/v1/operati
 # Operations that enumerate or repeatedly invoke a solver; they get the stricter
 # rate-limit tier because a single call can monopolize a CPU for a long time.
 _EXPENSIVE_OPERATIONS = {
+    'attribute_optimization',
+    'commonality',
+    'generate_random_feature_model',
     'configurations',
+    'covering_array',
+    't_wise_sampling',
     'configurations_number',
     'configurations_with_n_features',
     'conflict',
@@ -56,14 +70,44 @@ _ENUM_VALUES = {
 
 _SWAGGER_TYPES = {int: 'integer', float: 'number', bool: 'boolean', str: 'string'}
 
+# The provenance of every result (the facade's ``last_result``: plugin, backend, exact,
+# planner rationale, wall time of the run that computed it, hash of the model, whether the
+# backend model came from the artifact cache) travels in response headers, so the body stays
+# the bare value the Python facade returns.
+PROVENANCE_HEADERS = (
+    ('X-Flamapy-Plugin', 'plugin'),
+    ('X-Flamapy-Backend', 'backend'),
+    ('X-Flamapy-Exact', 'exact'),
+    ('X-Flamapy-Planner', 'planner'),
+    ('X-Flamapy-Wall-Time', 'wall_time'),
+    ('X-Flamapy-Model-Hash', 'model_hash'),
+    ('X-Flamapy-Artifact-Cache', 'cache_hit'),
+)
+
 
 class CustomJSONEncoder(json.JSONEncoder):
+    """JSON for the facade's return types: configurations as their fields, feature models
+    (``generate_random_feature_model``, ``generate_random_attribute``) as UVL text, language
+    levels as their major/minor names."""
+
     def default(self, obj: Any) -> Any:
         if isinstance(obj, Configuration):
             return obj.__dict__
+        if isinstance(obj, FeatureModel):
+            return UVLWriter(path=None, source_model=obj).transform()
+        if isinstance(obj, LanguageLevel):
+            return {'major': obj.major.name, 'minors': sorted(m.name for m in obj.minors)}
+        if isinstance(obj, (set, frozenset)):
+            return sorted(obj, key=str)
         return super().default(obj)
 
 
+def _facade_kind(method: Any) -> str:
+    """'operation' (runs on an uploaded model), 'transformer' (returns the modified model)
+    or 'producer' (builds a model from parameters; no upload)."""
+    return str(getattr(method, '_facade_kind', 'operation'))
+
+
 def _operation_params(method: Any) -> list[inspect.Parameter]:
     """Call-relevant parameters of a facade method (excluding ``self``)."""
     return [p for p in inspect.signature(method).parameters.values() if p.name != 'self']
@@ -101,6 +145,19 @@ def _convert(raw: str, scalar_type: type) -> Any:
     return raw
 
 
+def _is_json_param(param: inspect.Parameter) -> bool:
+    """Untyped facade inputs take structured values (``objectives``: an attribute name or
+    {attribute: min|max}; ``configurations``: a list of {feature: bool}); over HTTP they
+    arrive as JSON text."""
+    return param.annotation is typing.Any
+
+
+def _convert_param(raw: str, param: inspect.Parameter) -> Any:
+    if _is_json_param(param) and raw.lstrip()[:1] in ('[', '{'):
+        return json.loads(raw)
+    return _convert(raw, _scalar_type(param.annotation))
+
+
 def _save_upload(uploaded: FileStorage, work_dir: str) -> str:
     """Save an uploaded file into ``work_dir`` under a sanitized name and return
     its path. ``secure_filename`` strips any directory components, so a client
@@ -133,7 +190,7 @@ def _resolve_kwargs(operation: Any, work_dir: str) -> dict[str, Any]:
                 if allowed is not None and raw not in allowed:
                     abort(400, f"Invalid value for '{field}'; choose from {allowed}")
                 try:
-                    kwargs[param.name] = _convert(raw, _scalar_type(param.annotation))
+                    kwargs[param.name] = _convert_param(raw, param)
                 except (TypeError, ValueError):
                     abort(400, f"Invalid value for '{field}'")
             elif required:
@@ -142,15 +199,16 @@ def _resolve_kwargs(operation: Any, work_dir: str) -> dict[str, Any]:
 
 
 def _cache_key(
-    operation_name: str, operation: Any, model_path: str, kwargs: dict[str, Any]
+    operation_name: str, operation: Any, model_path: Optional[str], kwargs: dict[str, Any]
 ) -> str:
     """Digest of everything that determines the result: the operation, the model
     contents and every argument (file arguments by content, not by temp path)."""
     file_params = {p.name for p in _operation_params(operation) if _is_file_param(p)}
     digest = hashlib.sha256()
     digest.update(operation_name.encode())
-    with open(model_path, 'rb') as model_file:
-        digest.update(model_file.read())
+    if model_path is not None:
+        with open(model_path, 'rb') as model_file:
+            digest.update(model_file.read())
     for name in sorted(kwargs):
         digest.update(b'\x00' + name.encode() + b'\x00')
         if name in file_params:
@@ -161,49 +219,100 @@ def _cache_key(
     return digest.hexdigest()
 
 
-def _api_call(operation_name: str) -> Any:
+def _header_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return 'true' if value else 'false'
+    return str(value)
+
+
+def _respond(entry: dict[str, Any], cache_status: str) -> Response:
+    """The response for a cached or fresh ``{'value': ..., 'provenance': ...}`` entry: the
+    bare value as the body, the provenance in the headers."""
+    provenance: dict[str, Any] = entry.get('provenance') or {}
+    response: Response = jsonify(entry['value'])
+    response.headers['X-Cache'] = cache_status
+    for header, field in PROVENANCE_HEADERS:
+        if provenance.get(field) is not None:
+            response.headers[header] = _header_value(provenance[field])
+    return response
+
+
+def _uploaded_model() -> FileStorage:
     uploaded_model = request.files.get('model')
     if uploaded_model is None or not uploaded_model.filename:
         abort(400, "Missing required file 'model'")
+    return uploaded_model
+
+
+def _api_call(operation_name: str) -> Any:
+    operation = getattr(FLAMAFeatureModel, operation_name)
+    # Producers build a model from their parameters: nothing to upload.
+    uploaded_model = None if _facade_kind(operation) == 'producer' else _uploaded_model()
 
     # Each request gets its own directory so concurrent requests cannot collide
     # on (or delete) each other's uploads; the whole tree is removed afterwards.
     work_dir = tempfile.mkdtemp(prefix='flamapy_')
     try:
-        model_path = _save_upload(uploaded_model, work_dir)
-        operation = getattr(FLAMAFeatureModel, operation_name)
+        model_path = _save_upload(uploaded_model, work_dir) if uploaded_model else None
         kwargs = _resolve_kwargs(operation, work_dir)
 
         key = _cache_key(operation_name, operation, model_path, kwargs)
-        payload = result_cache.get(key)
-        if payload is not None:
-            response: Response = jsonify(payload)
-            response.headers['X-Cache'] = 'HIT'
-            return response
+        cached = result_cache.get(key)
+        if cached is not None:
+            return _respond(cached, 'HIT')
 
         try:
-            result = run_operation(
+            value, provenance = run_operation(
                 model_path, operation_name, kwargs, current_app.config['OPERATION_TIMEOUT']
             )
         except ModelParseError:
             abort(400, "The uploaded model could not be parsed")
         except OperationTimeout as exc:
             abort(504, str(exc))
+        except FlamaException as exc:
+            # The operation could not run: an unknown backend, invalid inputs, or no
+            # installed plugin able to run it on this model (backend=auto). 404 as in 2.6,
+            # with the reason; 3.0 moves this to 422.
+            abort(404, str(exc))
     finally:
         shutil.rmtree(work_dir, ignore_errors=True)
 
-    if result is None:
+    if value is None:
         return jsonify(error='Not valid result'), 404
-    payload = json.loads(json.dumps(result, cls=CustomJSONEncoder))
-    result_cache.set(key, payload)
-    response = jsonify(payload)
-    response.headers['X-Cache'] = 'MISS'
-    return response
+    entry = {
+        'value': json.loads(json.dumps(value, cls=CustomJSONEncoder)),
+        'provenance': provenance,
+    }
+    result_cache.set(key, entry)
+    return _respond(entry, 'MISS')
+
+
+def _plan_call(operation_name: str) -> Any:
+    """Which backend ``backend=auto`` would pick for the operation on the uploaded model."""
+    uploaded_model = _uploaded_model()
+    raw = request.form.get('allow_approximate')
+    allow_approximate = _convert(raw, bool) if raw not in (None, '') else None
+    work_dir = tempfile.mkdtemp(prefix='flamapy_')
+    try:
+        model_path = _save_upload(uploaded_model, work_dir)
+        try:
+            chosen = run_plan(model_path, operation_name, allow_approximate,
+                              current_app.config['OPERATION_TIMEOUT'])
+        except ModelParseError:
+            abort(400, "The uploaded model could not be parsed")
+        except OperationTimeout as exc:
+            abort(504, str(exc))
+        except FlamaException as exc:
+            abort(404, str(exc))
+    finally:
+        shutil.rmtree(work_dir, ignore_errors=True)
+    return jsonify(chosen)
 
 
 def extract_docstring_with_swagger_info(method: Any) -> str:
     """Build the flasgger YAML spec for a facade method by introspecting its
-    signature: a required ``model`` file plus one field per parameter."""
+    signature: a required ``model`` file (except for producers) plus one field per
+    parameter."""
     lines = [
         "    ---",
         "    tags:",
@@ -211,11 +320,14 @@ def extract_docstring_with_swagger_info(method: Any) -> str:
         "    consumes:",
         "      - multipart/form-data",
         "    parameters:",
-        "      - name: model",
-        "        in: formData",
-        "        type: file",
-        "        required: true",
     ]
+    if _facade_kind(method) != 'producer':
+        lines += [
+            "      - name: model",
+            "        in: formData",
+            "        type: file",
+            "        required: true",
+        ]
     for param in _operation_params(method):
         ptype = 'file' if _is_file_param(param) else _SWAGGER_TYPES.get(
             _scalar_type(param.annotation), 'string'
@@ -227,18 +339,64 @@ def extract_docstring_with_swagger_info(method: Any) -> str:
             f"        type: {ptype}",
             f"        required: {str(required).lower()}",
         ]
+        if _is_json_param(param):
+            lines.append("        description: JSON (an object or a list) or a plain string")
+        if param.name == 'allow_approximate':
+            lines.append("        description: Only with backend=auto, let the planner choose"
+                         " approximate implementations")
         if param.name in _ENUM_VALUES:
             lines.append("        enum:")
             lines += [f"          - {value}" for value in _ENUM_VALUES[param.name]]
+    returns_model = _facade_kind(method) in ('producer', 'transformer')
     lines += [
         "    responses:",
         "      200:",
-        "        description: Result of the operation",
+        "        description: " + (
+            "A JSON string holding the resulting feature model in UVL" if returns_model
+            else "Result of the operation; its provenance travels in the X-Flamapy-* headers"),
+        "        headers:",
+    ]
+    for header, _ in PROVENANCE_HEADERS:
+        lines += [f"          {header}:", "            type: string"]
+    lines += [
+        "      404:",
+        "        description: The operation could not run (unknown backend, invalid input,"
+        " or no installed plugin can run it on this model); the body says why",
     ]
     docstring = (method.__doc__ or "").replace('\n', ' ').strip()
     return docstring + "\n" + "\n".join(lines) + "\n"
 
 
+def _plan_docstring(operation_name: str) -> str:
+    """The flasgger spec of an operation's ``/plan`` endpoint."""
+    lines = [
+        f"Which backend backend=auto would run {operation_name} on the uploaded model, and"
+        " why: the plugin, its model extension, the transformation chain, the estimated"
+        " cost in milliseconds, the rationale and the alternatives. Nothing is executed.",
+        "    ---",
+        "    tags:",
+        f"      - {operation_name}",
+        "    consumes:",
+        "      - multipart/form-data",
+        "    parameters:",
+        "      - name: model",
+        "        in: formData",
+        "        type: file",
+        "        required: true",
+        "      - name: allow_approximate",
+        "        in: formData",
+        "        type: boolean",
+        "        required: false",
+        "        description: Also consider approximate implementations",
+        "    responses:",
+        "      200:",
+        "        description: The planner's choice",
+        "      404:",
+        "        description: No installed plugin can run the operation on this model",
+    ]
+    return "\n".join(lines) + "\n"
+
+
 def create_route(operation_name: str, docstring: str) -> Callable[[], Any]:
     def route_function() -> Any:
         return _api_call(operation_name)
@@ -248,15 +406,30 @@ def create_route(operation_name: str, docstring: str) -> Callable[[], Any]:
     return route_function
 
 
+def create_plan_route(operation_name: str) -> Callable[[], Any]:
+    def route_function() -> Any:
+        return _plan_call(operation_name)
+
+    route_function.__name__ = f'{operation_name}_plan'
+    route_function.__doc__ = _plan_docstring(operation_name)
+    return route_function
+
+
+def _selects_backend(method: Any) -> bool:
+    return any(param.name == 'backend' for param in _operation_params(method))
+
+
 # Introspect FLAMAFeatureModel to expose every public method as a POST route,
 # generating its Swagger spec from the method signature. Limits are passed as
 # callables so they read the app config of whichever app the blueprint joins.
 for name, method in inspect.getmembers(FLAMAFeatureModel, predicate=inspect.isfunction):
-    if name.startswith('_'):
-        continue
-    if getattr(method, '_facade_kind', 'operation') != 'operation':
-        continue  # producers/transformers return models; Python-API only for now
+    if name.startswith('_') or getattr(method, '_facade_descriptor', None) is None:
+        continue  # plan/run_async/iter_configurations are Python-API helpers, not operations
     docstring = extract_docstring_with_swagger_info(method)
     limit = expensive_operation_limit if name in _EXPENSIVE_OPERATIONS else default_operation_limit
     route_view = limiter.limit(limit)(create_route(name, docstring))
     operations_bp.route(f'/{name}', methods=['POST'])(route_view)
+    if _selects_backend(method):
+        # Operations with more than one backend also answer which one the planner would pick.
+        plan_view = limiter.limit(default_operation_limit)(create_plan_route(name))
+        operations_bp.route(f'/{name}/plan', methods=['POST'])(plan_view)