CE-RISE SEE Impacts Calculation Service

This site documents the CE-RISE SEE impacts calculation service. SEE stands for socio-economic and environmental impacts.

The CE-RISE Solution portal is the main entry point for human users exploring the wider solution and its components.

Available Service Functions

The service provides Brightway project compatibility checks and an HTTP service boundary:

GET /health reports the service identity and configuration;
GET /capabilities opens the configured Brightway project and reports databases and methods;
GET /openapi.json and GET /docs provide the machine-readable and interactive API;
see-impacts-compatibility runs the same Brightway project check from the command line;
the container image runs the same HTTP service with externally mounted background data.

Use the Service

Install and inspect the local project:

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/see-impacts-compatibility

Start the HTTP service with the virtual environment active:

./scripts/run-local.sh
curl -sS http://127.0.0.1:8080/health
curl -sS http://127.0.0.1:8080/capabilities

POST /compute is documented so consumers can inspect its JSON schema. It returns 501 CALCULATION_NOT_IMPLEMENTED; it does not provide a calculation operation.

Documentation Structure

Architecture: active service components and data handling
API Overview: available endpoints and compute request schema
API Reference: endpoint-level request, response, and error behavior
Deployment: container image, configuration, and background provisioning
Local Testing: probe, test, and local container workflows
HEX Core Status: available configuration and client boundary
Project Scope: available service scope and exclusions

Funded by the European Union under Grant Agreement No. 101092281 — CE-RISE.
Views and opinions expressed are those of the author(s) only and do not necessarily reflect those of the European Union or the granting authority (HADEA). Neither the European Union nor the granting authority can be held responsible for them.

© 2026 CE-RISE consortium.
Licensed under the European Union Public Licence v1.2 (EUPL-1.2).
Attribution: CE-RISE project (Grant Agreement No. 101092281) and the individual authors/partners as indicated.

Developed by NILU (Riccardo Boero - ribo@nilu.no), Leiden University (Mintjes, B.A. (Berend) - b.a.mintjes@cml.leidenuniv.nl), and Empa (Francesco Barilli - francesco.barilli@empa.ch; Roland Hischier - roland.hischier@empa.ch) within the CE-RISE project.

Architecture

Available Components

The service is a containerized Python HTTP application with these active components:

app.py exposes health, capability, OpenAPI, and API-documentation endpoints;
compatibility.py opens the supplied Brightway project and reports its databases and methods;
config.py reads HTTP, background-project, and Brightway-workspace settings;
hex_core.py provides a source-level client for the HEX Core validation endpoint.

The HTTP application does not expose Brightway database management. Background data remains an external deployment input.

Background Data and Brightway State

The current local project is cerise_bonsai, located by default at data/background/projects/cerise_bonsai.c4e8a461df1485d0b80d98d3e46a35b9. It is excluded from Git and is not included in the container image. Deployments must mount or otherwise provision an approved background dataset.

Brightway project state is mutable and process-global. The compatibility probe uses BRIGHTWAY_WORKSPACE_DIR for this writable state and keeps the mounted background project immutable. Do not use the background source directory as the Brightway workspace.

API Boundary

GET /capabilities is the operational endpoint for checking the mounted background project. POST /compute exposes a JSON schema with model-version fields for product-system, lci-dataset, and integrated-lca, but returns 501 CALCULATION_NOT_IMPLEMENTED. The Product System object and LCI Dataset object(s) are inputs; the Integrated LCA model is the result contract. It does not open a foreground project, call HEX Core, or produce an assessment result.

The semantic content of the input objects is the basis for building the internal Brightway calculation. Brightway state is internal to the service; no additional mapping model, API resource, or persisted record is part of the service boundary.

API Overview

Available Endpoints

Use these endpoints with the running HTTP service:

GET /health
GET /capabilities
GET /openapi.json
GET /docs

GET /health is a liveness check. GET /capabilities verifies that the configured Brightway project can be opened and reports the databases and methods that the service can inspect.

Compute Request Schema

POST /compute publishes this JSON request schema:

{
  "model_versions": {
    "product_system": "<version>",
    "lci_dataset": "<version>",
    "integrated_lca": "<version>"
  },
  "product_system": {},
  "lci_datasets": [],
  "assessment_context": {}
}

The fields have these roles:

model_versions.product_system and model_versions.lci_dataset: versions of the input model contracts;
model_versions.integrated_lca: version of the result model contract;
product_system: input object conforming to the selected Product System version;
lci_datasets: input object(s) conforming to the selected LCI Dataset version;
assessment_context: additional assessment information.

The result belongs in an object conforming to the selected Integrated LCA version. Brightway activities, databases, methods, and project state are internal calculation details. The semantic content of the CE-RISE input objects is used to construct that internal calculation; no additional mapping object, request field, or API resource is required from callers.

The endpoint returns 501 CALCULATION_NOT_IMPLEMENTED. It has no calculation or validation side effects. Use GET /capabilities to inspect an available Brightway project.

API Reference

Base URL

http://<host>:8080/

Interactive OpenAPI documentation is available at GET /docs. The machine-readable OpenAPI document is available at GET /openapi.json.

`GET /health`

Returns service identity and the configured HEX Core and background-project locations. It does not open the Brightway project, so it can be used as a lightweight liveness check.

Example response:

{
  "status": "ok",
  "service": "see-impacts-calculation-service",
  "version": "0.1.0",
  "hex_core_base_url": "http://127.0.0.1:8080",
  "background_project_dir": "/app/data/background/projects/cerise_bonsai.c4e8a461df1485d0b80d98d3e46a35b9"
}

`GET /capabilities`

Opens the configured Brightway background project and reports the databases and impact methods that are available to the service. Use this endpoint as a readiness check after provisioning or updating background data.

Example response shape:

{
  "calculation_status": "not_available",
  "background": {
    "project_name": "cerise_bonsai",
    "databases": [
      {
        "name": "bonsai",
        "backend": "sqlite",
        "format": null,
        "activity_count": 42088
      }
    ],
    "method_count": 668,
    "method_examples": []
  },
  "brightway": {
    "bw2data_version": "3.6.6",
    "bw2calc_version": "1.8.2"
  }
}

The database names, counts, and method examples are determined by the mounted project. The example values reflect the approved local project used for this service and are not a fixed API guarantee.

If the project cannot be opened, the endpoint returns 503:

{
  "detail": {
    "code": "BRIGHTWAY_PROJECT_UNAVAILABLE",
    "message": "Brightway project directory does not exist: /configured/path"
  }
}

`POST /compute`

This endpoint exposes the CE-RISE-oriented request schema below. It does not provide an impact calculation operation.

Request Schema

model_versions
- type: object
- required: yes
- product_system: version of the Product System input model
- lci_dataset: version of the LCI Dataset input model
- integrated_lca: version of the Integrated LCA result model
product_system
- type: object
- required: yes
- meaning: Product System input object following the selected model version
lci_datasets
- type: array of objects
- required: no
- default: []
- meaning: LCI Dataset input objects following the selected model version
assessment_context
- type: object
- required: no
- default: {}
- meaning: additional assessment information

Request

{
  "model_versions": {
    "product_system": "<product-system-version>",
    "lci_dataset": "<lci-dataset-version>",
    "integrated_lca": "<integrated-lca-version>"
  },
  "product_system": {},
  "lci_datasets": [],
  "assessment_context": {}
}

Response

Every request that satisfies the top-level schema returns 501:

{
  "detail": {
    "code": "CALCULATION_NOT_IMPLEMENTED",
    "message": "Impact calculation is not available. Use GET /capabilities to verify the configured Brightway project."
  }
}

The endpoint has no calculation side effects. It does not call HEX Core, create foreground data, or modify the background project.

The schema has no Brightway-specific fields. Product System and LCI Dataset objects are the inputs; an Integrated LCA object is the calculation result contract. The semantic content of the input objects is used internally to build the Brightway calculation. There is no additional mapping object to submit or save.

Validation Errors

FastAPI returns 422 Unprocessable Entity when a required top-level field is absent or has an incompatible JSON type.

Error Responses

Errors use the standard FastAPI detail envelope. The currently defined service error codes are:

BRIGHTWAY_PROJECT_UNAVAILABLE (503): the configured background project cannot be opened;
CALCULATION_NOT_IMPLEMENTED (501): a syntactically valid compute request was received, but impact calculation is not available.

Deployment

Service Form

This project is deployed as a containerized HTTP service. The repository includes a Dockerfile and .dockerignore; the background dataset is deliberately excluded from the build context and the resulting image.

Image Publication

Pushing a v*.*.* tag to the canonical Codeberg repository triggers the Forgejo release workflow. It builds and publishes:

$REGISTRY_HOST/$REGISTRY_NAMESPACE/see-impacts-calculation:<tag>
$REGISTRY_HOST/$REGISTRY_NAMESPACE/see-impacts-calculation:latest

The workflow needs these repository-level settings:

variables: REGISTRY_HOST, REGISTRY_NAMESPACE;
secrets: REGISTRY_USERNAME, REGISTRY_PASSWORD.

The existing CE-RISE registry convention resolves these to an image such as rg.fr-par.scw.cloud/ce-rise-software/see-impacts-calculation:<tag>. A release tag must never be pushed before the registry settings are configured.

Build Locally

podman build -t see-impacts-calculation-service:local .

The image listens on port 8080 and runs as an unprivileged application user.

Runtime Configuration

The service accepts the following environment variables:

BIND_ADDRESS: HTTP bind address; default 0.0.0.0;
PORT: HTTP port; default 8080;
HEX_CORE_BASE_URL: HEX Core base URL; default http://127.0.0.1:8080;
HTTP_TIMEOUT_SECS: delegated HTTP timeout; default 30;
BACKGROUND_PROJECT_DIR: approved Brightway project directory; default data/background/projects/cerise_bonsai.c4e8a461df1485d0b80d98d3e46a35b9;
BACKGROUND_PROJECT_NAME: expected project name from .project-name.json; default cerise_bonsai;
BRIGHTWAY_WORKSPACE_DIR: writable Brightway registry workspace; default runtime/brightway locally and /var/lib/see-impacts/brightway in the container image.

HEX_CORE_BASE_URL and HTTP_TIMEOUT_SECS are accepted runtime settings. The available HTTP endpoints do not make an outbound HEX Core request.

Background Data Provisioning

The image contains code and dependencies only. Background data must be provided separately and treated as immutable. The service creates Brightway registry state in BRIGHTWAY_WORKSPACE_DIR; this path must be writable and must not be the background source directory.

Each concurrently running worker should use its own writable Brightway workspace. This avoids concurrent mutation of Brightway’s process-global project registry.

Run Example

From a local checkout where the approved project is stored under the ignored data/background directory:

podman run --rm -p 8080:8080 \
  -e BACKGROUND_PROJECT_DIR=/data/projects/cerise_bonsai.c4e8a461df1485d0b80d98d3e46a35b9 \
  -e BACKGROUND_PROJECT_NAME=cerise_bonsai \
  -e BRIGHTWAY_WORKSPACE_DIR=/var/lib/see-impacts/brightway \
  -v "$PWD/data/background:/data:ro,Z" \
  see-impacts-calculation-service:local

The :Z suffix is appropriate for Podman on SELinux-enabled hosts. Use the equivalent read-only volume syntax required by the target container runtime.

After startup, verify both liveness and project readiness:

curl -sS http://127.0.0.1:8080/health
curl -sS http://127.0.0.1:8080/capabilities

Operational Readiness

Use GET /health for a lightweight liveness check. Use GET /capabilities as the readiness check because it confirms that the configured Brightway project can be opened. A healthy HTTP process is not sufficient to show that required background data has been provisioned.

Local Testing

This page shows how to verify that the service can safely open an approved Brightway 2 background project, run its tests, and start the HTTP service.

Setup

Create a virtual environment and install the service with its test dependencies:

python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e '.[dev]'

The default background project location is data/background/projects/cerise_bonsai.c4e8a461df1485d0b80d98d3e46a35b9. Override it with BACKGROUND_PROJECT_DIR when an approved dataset is located elsewhere. The separate BRIGHTWAY_WORKSPACE_DIR holds Brightway’s writable project registry and defaults to runtime/brightway.

Brightway Compatibility Probe

Run the probe against the configured background project:

.venv/bin/see-impacts-compatibility

The probe activates the project and prints its registered databases and impact methods as JSON. It does not create foreground data or run an LCIA calculation.

To use a non-default location without changing the environment permanently:

BACKGROUND_PROJECT_DIR=/path/to/project \
BRIGHTWAY_WORKSPACE_DIR=/tmp/see-impacts-brightway \
.venv/bin/see-impacts-compatibility

Unit Tests

.venv/bin/python -m pytest

HTTP Service

Start the service from the activated virtual environment:

. .venv/bin/activate
./scripts/run-local.sh

In a second terminal, check the live service and background project:

curl -sS http://127.0.0.1:8080/health
curl -sS http://127.0.0.1:8080/capabilities
curl -sS http://127.0.0.1:8080/openapi.json

POST /compute validates the top-level request shape and returns 501 CALCULATION_NOT_IMPLEMENTED. Use GET /capabilities for the available Brightway project inspection operation.

Container Smoke Test

Build the image locally:

podman build -t see-impacts-calculation-service:local .

Run it with the approved local background directory mounted read-only:

podman run --rm -p 8080:8080 \
  -e BACKGROUND_PROJECT_DIR=/data/projects/cerise_bonsai.c4e8a461df1485d0b80d98d3e46a35b9 \
  -e BRIGHTWAY_WORKSPACE_DIR=/var/lib/see-impacts/brightway \
  -v "$PWD/data/background:/data:ro,Z" \
  see-impacts-calculation-service:local

Then call GET /capabilities. A successful response proves that the container can inspect the mounted background project without baking it into the image.

HEX Core Status

Available Configuration

The service accepts HEX_CORE_BASE_URL and HTTP_TIMEOUT_SECS as runtime configuration. GET /health reports the configured HEX Core base URL.

No available HTTP endpoint calls HEX Core. Configuring these values does not enable model validation through POST /compute; that endpoint returns 501 CALCULATION_NOT_IMPLEMENTED.

Source-Level Client

src/see_impacts_calculation_service/hex_core.py contains HexCoreClient, which constructs the standard validation URL:

POST /models/{model-family}/versions/{version}:validate

Its validate method accepts a payload and optional bearer token. It is not part of the exposed HTTP service behavior.

CE-RISE Data Boundary

The POST /compute JSON schema uses the following CE-RISE contracts:

Product System: input object
LCI Dataset: input object(s)
Integrated LCA: result object

Brightway remains inside the calculation service. It is not represented by an additional CE-RISE model or mapping API. The semantic content of the Product System and LCI Dataset input objects is used internally to build the Brightway calculation. The service does not validate these payloads or produce an Integrated LCA record through its available HTTP endpoints.

Project Scope

Available Scope

The repository provides a containerized Python HTTP service for inspecting an approved Brightway background project. The usable operations are the command-line compatibility probe, health endpoint, capability endpoint, OpenAPI document, and container release workflow.

Background source data remains local and read-only. Brightway registry state uses a separate writable workspace. The API and operating guidance are published through the repository’s Codeberg Pages site.

Not Provided

impact calculation through POST /compute;
Product System, LCI Dataset, or Integrated LCA payload validation;
HEX Core calls from the HTTP service;
a Brightway database-management API;
background datasets embedded in the source repository or container image;
a general-purpose LCA application, CLI, or notebook interface.

Keyboard shortcuts

CE-RISE SEE Impacts Calculation Service