Skip to content

Python API Reference

This reference is generated from the installed package. Run python scripts/gen_api_md.py to regenerate.

How values are reduced within a bucket.

SUM_QUANTITY: sum of quantities (default). COUNT: number of matching entries. SHARE: each bucket’s percentage of the filtered total (0..100).

What the /aggregate primitive groups over.

DIRECT: direct exchanges of the activity. SUPPLY_CHAIN: the upstream activities reachable via cumulative flow. BIOSPHERE: only biosphere flows in the supply chain. CONSUMPTION: every scaled technosphere edge (who consumes what, in scaled units); the scope that answers “total X consumed upstream” without double counting, via filter_consumer_not.

Direction of a biosphere exchange.

RESOURCE: extraction from the environment (input). EMISSION: release to the environment (output).

Lookup is case-insensitive (BioDirection("emission") works): the engine reads the wire value that way, so the client should not be stricter than the server it speaks for.

How a source file designates the supplier of an exchange.

PRODUCT: the product row itself, its flow and where it has one its location - SimaPro, ILCD, and a Brightway row naming no activity. ID: the supplier activity’s own identifier, as EcoSpold 2 writes it. NAME: the supplier activity by name, from a Brightway name column. NAME_ALONE: the supplier activity by name and no product, as a Brightway export writes a row bought from another database (wire revision 71). DATASET_NUMBER: the number the supplier dataset is published under, as EcoSpold 1 writes it.

HTTP client for the VoLCA HTTP API.

Usage::

c = Client(db="agribalyse-3.2", password="1234")
plants = c.search_activities(name="at plant")
chain = c.get_supply_chain(plants[0].process_id, name="at farm")

Substitutions can be passed to get_supply_chain, get_inventory, and get_impacts to compute results with a different upstream supplier, fast::

subs = [{"from": old_pid, "to": new_pid, "consumer": consumer_pid}]
result = c.get_impacts(pid, method_id=mid, substitutions=subs)

Constructor: Client(base_url: str = 'http://localhost:8080', db: str = '', password: str = '')

Client.accept_substitution(release: dict, database: str, db_name: str | None = None) -> dict
Section titled “Client.accept_substitution(release: dict, database: str, db_name: str | None = None) -> dict”

Accept database in place of a release a packaged database requires.

release is one of the releases the setup’s requiredReleases lists, as it lists it. Returns the setup as it now links (see get_setup). Raises VoLCAError on an HTTP error: a 404 for an unknown database or a release it does not require, a 409 for a database already loaded with the links it has. Needs wire revision 50.

Client.accept_terms(db_name: str | None = None) -> list[dict]
Section titled “Client.accept_terms(db_name: str | None = None) -> list[dict]”

Accept, for this client, the terms terms_to_accept returns.

Call it only once the person running the code has read those terms and agreed to them: accepting binds them, not the client. The acceptance lasts as long as the client. Returns the terms accepted::

for t in c.terms_to_accept():
print(t["text"])
if t["usage"]:
print("Computations are counted for the publisher:", t["usage"])
if input("Do you accept these terms? [y/N] ") == "y":
c.accept_terms()
Client.add_dependency(dep_name: str, db_name: str | None = None) -> dict
Section titled “Client.add_dependency(dep_name: str, db_name: str | None = None) -> dict”

Declare dep_name as a dependency of the target database.

Returns the engine’s DatabaseSetupInfo dict describing the updated dependency topology.

Client.add_method_category(collection: str, name: str, unit: str, *, impact_category: str | None = None, methodology: str | None = None) -> dict
Section titled “Client.add_method_category(collection: str, name: str, unit: str, *, impact_category: str | None = None, methodology: str | None = None) -> dict”

Add an impact category to a collection of your own.

It starts with no factor: add them with add_method_factor, naming the category by the methodId the answer gives. A name already in use is refused. impact_category is the name when not given.

Needs an engine speaking wire revision 43.

Client.add_method_factor(collection: str, method_id: str, factor: NewMethodFactor) -> dict
Section titled “Client.add_method_factor(collection: str, method_id: str, factor: NewMethodFactor) -> dict”

Add a characterization factor to a category of a collection of your own.

Refused when a factor is already written for that flow at that place: change its value with set_method_factor instead.

Client.add_scoring_row(collection: str, set_name: str, row: ScoringRow) -> dict
Section titled “Client.add_scoring_row(collection: str, set_name: str, row: ScoringRow) -> dict”

Add a row to a scoring set; with a weight, it joins the score that adds up the rows.

A score written otherwise is left as it is. A label already in use is refused.

Client.aggregate(process_id: str, scope: AggregateScope | str, *, is_input: bool | None = None, max_depth: int | None = None, filter_name: str | None = None, filter_name_not: list[str] | str | None = None, filter_unit: str | None = None, preset: str | None = None, filter_classification: list[ClassificationFilter] | None = None, filter_target_name: str | None = None, filter_consumer: str | None = None, filter_consumer_not: list[str] | str | None = None, filter_is_reference: bool | None = None, group_by: str | None = None, aggregate: AggregateOp | str | None = None) -> AggregateResult
Section titled “Client.aggregate(process_id: str, scope: AggregateScope | str, *, is_input: bool | None = None, max_depth: int | None = None, filter_name: str | None = None, filter_name_not: list[str] | str | None = None, filter_unit: str | None = None, preset: str | None = None, filter_classification: list[ClassificationFilter] | None = None, filter_target_name: str | None = None, filter_consumer: str | None = None, filter_consumer_not: list[str] | str | None = None, filter_is_reference: bool | None = None, group_by: str | None = None, aggregate: AggregateOp | str | None = None) -> AggregateResult”

SQL-group-by aggregation over direct exchanges, supply chain, or biosphere flows.

Args: scope: AggregateScope member (DIRECT / SUPPLY_CHAIN / BIOSPHERE / CONSUMPTION) or the equivalent wire string. Strings are accepted for one-liner ergonomics but bypass static checking. CONSUMPTION rows are scaled technosphere edges: use it for “total X consumed upstream” questions. Net electricity without grid double counting::

aggregate(pid, "consumption", filter_name="electricity",
filter_consumer_not=["electricity"])
Grass eaten by cattle across the whole chain::
aggregate(pid, "consumption", filter_name="grass",
filter_consumer="cattle")
filter_consumer: substring match on the consuming activity's name
(``CONSUMPTION`` scope only).
filter_consumer_not: exclude edges whose consumer name contains
any of these substrings (list or comma-separated string).
Items always split on commas on the wire, so a name that
itself contains a comma ("electricity production, hard
coal") becomes two independent substrings; use a
comma-free fragment of the name instead.
group_by: omit for a single-bucket result (just the totals).
Supported keys: ``"name"``, ``"flow_id"``, ``"name_prefix"``,
``"unit"``, ``"location"``, ``"target_name"``,
``"consumer_name"`` (``CONSUMPTION`` scope),
``"classification.<system>"``.
aggregate: `AggregateOp` member or wire string
(``"sum_quantity"`` by default, ``"count"``, or ``"share"``).
Client.apply_changes(process_id: str, *, summary: list[dict] | None = None, exchanges: list[dict] | None = None, note: str | None = None, source: dict | None = None, db_name: str | None = None) -> dict
Section titled “Client.apply_changes(process_id: str, *, summary: list[dict] | None = None, exchanges: list[dict] | None = None, note: str | None = None, source: dict | None = None, db_name: str | None = None) -> dict”

Make an activity say each change it is given that it does not say yet.

summary and exchanges are changes as a comparison writes them, as for changes_present. A change applies only where the activity still says what it replaced. Returns {"summary": [...], "exchanges": [...]}, one outcome per change in the order given, each {"outcome": ...}: "applied", "present", "different", "line-gone", or "not-applicable" with the "reason" no edit can make it. Needs wire revision 60.

note says why, in a sentence: it is kept in the database’s history (database_history) and in the changes report its export carries. Needs wire revision 79.

source says where the figures come from, as {"document": ..., "page": 7, "passage": ...} (page and passage are optional): it is kept beside the reason. Needs wire revision 111.

The method collections the engine offers to download and load in one step (wire revision 103).

Each entry carries name, publisher, version, licence (an SPDX identifier, absent when the file states none), sourceUrl, size in bytes, description, and installed, true when the engine already knows a collection of that name.

Client.call(operation_id: str, **kwargs) -> Any
Section titled “Client.call(operation_id: str, **kwargs) -> Any”

Escape hatch: call any OpenAPI operation by operationId.

Returns the raw JSON (no dataclass wrapping). Use this for operations that don’t have an ergonomic wrapper yet, or for new endpoints added after the installed pyvolca was released.

Client.change_scoring_row(collection: str, set_name: str, variable: str, row: ScoringRow) -> dict
Section titled “Client.change_scoring_row(collection: str, set_name: str, variable: str, row: ScoringRow) -> dict”

Make the row of variable (from scoring_sets) the row given.

Client.changes_present(process_id: str, *, summary: list[dict] | None = None, exchanges: list[dict] | None = None, db_name: str | None = None) -> dict
Section titled “Client.changes_present(process_id: str, *, summary: list[dict] | None = None, exchanges: list[dict] | None = None, db_name: str | None = None) -> dict”

Whether an activity already holds each change it is given.

summary and exchanges are changes as a comparison writes them on the wire, such as the summary and exchanges of call("compare_activities", ...): a change made against one version of an activity, looked for in a later one. Returns {"summary": [...], "exchanges": [...]}, one answer per change in the order given: "present" (it says what the change made it say, or no longer holds a removed line), "absent" (it still says what the change replaced), "different" or "line-gone" (the line is not there to judge, or several answer to its name). Needs wire revision 57.

Client.check_formula(formula: str, *, process_id: str | None = None, exchange: int | None = None) -> FormulaCheck
Section titled “Client.check_formula(formula: str, *, process_id: str | None = None, exchange: int | None = None) -> FormulaCheck”

What formula gives where it would be written, at the database’s own values.

With process_id it reads the process’s parameters and named lines, and the database’s; without, the database’s parameters alone. exchange is the line it would be written on, by its position among the process’s exchanges: its formula is replaced, so a name that reads the line back is a cycle, and a parameter whose unit does not convert to the line’s is warned. A formula that gives nothing comes back with its problem; it is not an error.

Client.compare_activities(process_id: str, other_process_id: str, *, other_database: str | None = None) -> ActivityComparison
Section titled “Client.compare_activities(process_id: str, other_process_id: str, *, other_database: str | None = None) -> ActivityComparison”

Compare one activity with another, exchange by exchange.

other_database names the loaded database holding the other activity when it is not this one, which is how an adapted copy is held against the dataset it was adapted from. A result whose identical is True says the two activities say the same thing.

Client.compare_database_scores(other_database: str, *, collection: str | None = None, units: dict[str, UnitDefinition] | None = None, chunk: int = 100, workers: int = 8) -> DatabaseScoreComparison
Section titled “Client.compare_database_scores(other_database: str, *, collection: str | None = None, units: dict[str, UnitDefinition] | None = None, chunk: int = 100, workers: int = 8) -> DatabaseScoreComparison”

Score this database and another under one collection, activity by activity.

Only the database varies: the same data in two formats, say. Activities pair as compare_databases pairs them, and every pair is scored on both sides; the right score is brought to one unit of the left reference (units is the unit table, unit_table when not given: pass it on an engine whose configuration names its own). Each method’s points are (left score, right score), ready for volca.compare_plot.scatter_grid. A pair the engine did not score, or whose references measure different things, is counted in left_out, not drawn; what did not pair stays in activities. Refuses one database compared with itself.

Client.compare_databases(other_database: str, *, limit: int | None = None) -> DatabaseComparison
Section titled “Client.compare_databases(other_database: str, *, limit: int | None = None) -> DatabaseComparison”

Compare this database with another loaded one, usually its next version.

Activities pair in a cascade: the same process id, then the same names at the same location, then the same reference product at the same location from the same kind of activity. Each changed pair says which in matched_on, and a key several activities answer to is listed in ambiguous rather than paired. limit keeps the first entries of each list; the counts always cover them all.

Client.compare_method_collections(collection: str, other_collection: str, *, pairs: list[str] | None = None, category: str | None = None, limit: int | None = None) -> dict
Section titled “Client.compare_method_collections(collection: str, other_collection: str, *, pairs: list[str] | None = None, category: str | None = None, limit: int | None = None) -> dict”

Compare two loaded method collections, category by category.

Categories pair on their name, then on their impact category; pairs settles the others, each written "base=other". Within a pair, factors pair by flow identifier, name, synonym class, CAS number, then pattern prefix, at one direction, compartment and location. category compares only the pair whose base category has that name, much faster than comparing them all. limit keeps the first entries of each list of each category; the counts cover them all.

Client.compare_methods(left_collection: str, right_collection: str, process_ids: list[str], *, forced: dict[str, str] | None = None, chunk: int = 100, workers: int = 8) -> MethodComparison
Section titled “Client.compare_methods(left_collection: str, right_collection: str, process_ids: list[str], *, forced: dict[str, str] | None = None, chunk: int = 100, workers: int = 8) -> MethodComparison”

Score this database’s processes under two collections and pair their categories.

Only the method varies: the database, and so every activity and its reference, is the same on both sides. Categories pair as in volca.compare_scores.pair_categories, forced first; each pair’s points are (left score, right score) per activity, ready for volca.compare_plot.scatter_grid. chunk and workers are as in score_table. Refuses one collection compared with itself.

Client.compute_sensitivity(process_id: str, method_id: str, perturbations: list[dict], *, collection: str | None = None) -> SensitivityResult
Section titled “Client.compute_sensitivity(process_id: str, method_id: str, perturbations: list[dict], *, collection: str | None = None) -> SensitivityResult”

How much one impact score moves when technosphere links are perturbed.

Each perturbation is a dict {"consumer": pid, "supplier": pid, "delta": -0.05, "label"?: str}: delta is relative (the coefficient becomes a * (1 + delta), so -1.0 removes the link). Returns the baseline LCIAResult plus one PerturbedResult per perturbation, each carrying either the perturbed impact and its delta, or an error string when that perturbation could not be resolved. method_id takes a method name as well as a UUID, and collection is read off the resolved method unless you pin it.

Client.computed_quality_report(db_name: str | None = None, *, collection: str | None = None, limit: int | None = None) -> dict
Section titled “Client.computed_quality_report(db_name: str | None = None, *, collection: str | None = None, limit: int | None = None) -> dict”

The quality checks read from every activity’s scores under collection.

Client.computed_quality_report_csv(db_name: str | None = None, *, collection: str | None = None, limit: int | None = None) -> bytes
Section titled “Client.computed_quality_report_csv(db_name: str | None = None, *, collection: str | None = None, limit: int | None = None) -> bytes”

The computed quality report as the CSV file the web page offers.

Client.copy_database(new_name: str, db_name: str | None = None) -> dict
Section titled “Client.copy_database(new_name: str, db_name: str | None = None) -> dict”

Copy a loaded database in memory under a new name.

new_name is a path segment; the source defaults to self.db. Returns the engine’s ActivateResponse dict ({"success", "message", "database"?}). Raises VoLCAError if the engine refuses the copy.

Client.copy_method_collection(collection: str, new_name: str) -> dict
Section titled “Client.copy_method_collection(collection: str, new_name: str) -> dict”

Copy a method collection under a new name, in order to change it.

A collection the configuration declares, or one built into the engine, is never changed in place: copy it, then change the copy. The copy scores exactly as its source before any change and is loaded at once. It reads its source’s files, so the source cannot be deleted while the copy exists. The copy is known by the slug of new_name (lower case, words joined by dashes); a name another collection already has is refused. Returns the collection made, whose name is the one the next call takes.

Needs an engine speaking wire revision 42.

Client.count_search_matches(query: str) -> SearchCounts
Section titled “Client.count_search_matches(query: str) -> SearchCounts”

How many processes, products and flows a query matches.

One call rather than three searches, for a search box that labels its tabs with counts. The three are disjoint and together cover the database.

Args: query: The search term. Required: an empty box has nothing to count, and the engine refuses a blank one rather than answering three zeros, which would read as “this database has nothing”.

Client.create_activities(activities: list[ActivityInput] | ActivityInput, db_name: str | None = None, *, note: str | None = None, source: dict | None = None) -> dict
Section titled “Client.create_activities(activities: list[ActivityInput] | ActivityInput, db_name: str | None = None, *, note: str | None = None, source: dict | None = None) -> dict”

Write new activities into a database that can hold them.

Each activity’s process_id is minted by the engine from its name, its location, and its product name and unit (you do not choose it), and comes back in written. Writing the same activity twice is therefore a conflict, not a second row; use replace_activity to correct one that is already there.

Only a database of your own accepts writes: one you uploaded, or a copy. A database the engine reads from its configuration is background data the whole installation shares, and is refused.

A batch is judged as a whole. If anything is wrong the engine reports every complaint at once and writes nothing, so a ten-line inventory is fixed in one round trip.

Returns {"written": [process_id], "transient": bool, "warnings": [...]}. transient is true when the edit lives in memory only; warnings carries what the engine wants you to know but would not refuse over (a brand-new biosphere flow no method characterizes yet, for one).

Needs an engine speaking wire revision 5 (the routes do not exist before it, and an absent route is a 404 that reads exactly like a misspelled database name).

note says why, in a sentence: it is kept in the database’s history (database_history) and in the changes report its export carries. Needs wire revision 79.

source says where the figures come from, as {"document": ..., "page": 7, "passage": ...} (page and passage are optional): it is kept beside the reason. Needs wire revision 111.

Client.create_scoring_set(collection: str, name: str, rows: list[ScoringRow], *, unit: str | None = None) -> dict
Section titled “Client.create_scoring_set(collection: str, name: str, rows: list[ScoringRow], *, unit: str | None = None) -> dict”

Create a scoring set in a collection of your own, from its rows.

Its Single score adds up the rows that have a weight. unit is Pt when not given. Every change to a set is one journal line, undone whole with undo_method_edit.

Client.database_history(*, db_name: str | None = None) -> list[dict]
Section titled “Client.database_history(*, db_name: str | None = None) -> list[dict]”

Every change made to the database, oldest first::

{"at": "2026-10-21T09:12:03Z", "database": "my-farm", "by": "ana",
"note": "Measured on site",
"summary": "Edited \"wheat production\" (FR)",
"details": ["Flow \"Water\": amount from 2.0 set to 1.5"]}

by is the public name of the account that made it, None when the engine was not told, as on the desktop (wire revision 104). note is the reason its author gave, None when they gave none. via is the surface the change came through, "mcp" or "http" (a script an assistant drives comes through "http" too), and source where its figures come from, as its author cited them (wire revision 111; absent from an older engine). database is the database the change was made on: for a child, the changes of the parent it is divided from come first, since its data carry them (wire revision 100; absent from an older engine). A database the engine reads from its configuration has no changes of its own. Needs wire revision 79.

Client.database_parameters(*, db_name: str | None = None) -> list[Parameter]
Section titled “Client.database_parameters(*, db_name: str | None = None) -> list[Parameter]”

The database’s own parameters, which every process’s formulas read unless the process defines its own of the same name. A process’s own are in get_activity.

The method collection the configuration offers a reader first, by name; None when it names none, and against an engine older than wire revision 52.

Client.delete_activities(*, name: str = '', location: str = '', product: str = '', classifications: list[dict | tuple] | None = None, exact: bool = False, keep: list[str] | None = None, extra: list[str] | None = None, ids: list[str] | None = None, note: str | None = None, source: dict | None = None, db_name: str | None = None) -> dict
Section titled “Client.delete_activities(*, name: str = '', location: str = '', product: str = '', classifications: list[dict | tuple] | None = None, exact: bool = False, keep: list[str] | None = None, extra: list[str] | None = None, ids: list[str] | None = None, note: str | None = None, source: dict | None = None, db_name: str | None = None) -> dict”

Delete activities selected by filter, or exactly the ids list.

Builds a DeleteSelectionRequest: the filter fields select the whole matching set, keep spares matched process ids, and extra adds ones the filter missed. classifications is a list of {"system", "value", "exact"} dicts or (system, value, exact) tuples.

ids names the selection verbatim instead of filtering; the filter arguments (and exact) must then stay unset: the two modes are exclusive, mirroring the engine. Needs an engine speaking wire revision 3 (>= v0.9.3): an older one would silently drop the unknown ids key and read the request as an empty filter (“everything”), so pyvolca refuses to send it rather than let the engine guess.

Returns the DeleteSelectionResponse dict ({"success", "message", "deleted"}); raises VoLCAError on success=false.

note says why, in a sentence: it is kept in the database’s history (database_history) and in the changes report its export carries. Needs wire revision 79.

source says where the figures come from, as {"document": ..., "page": 7, "passage": ...} (page and passage are optional): it is kept beside the reason. Needs wire revision 111.

Client.delete_database(db_name: str | None = None) -> dict
Section titled “Client.delete_database(db_name: str | None = None) -> dict”

Delete a database entirely: unload it and remove its uploaded files.

Returns the ActivateResponse dict; raises VoLCAError if the engine refuses it.

Client.delete_method_collection(name: str) -> dict
Section titled “Client.delete_method_collection(name: str) -> dict”

Delete a method collection: unload it and remove its staged file.

Client.delete_reference_data(kind: RefDataKind, name: str) -> dict
Section titled “Client.delete_reference_data(kind: RefDataKind, name: str) -> dict”

Delete a reference-data set of kind and remove its staged file.

Client.derive_database(new_name: str, allocation: str | None = None, db_name: str | None = None, *, system_model: str | Path | None = None, parent: bool = False) -> dict
Section titled “Client.derive_database(new_name: str, allocation: str | None = None, db_name: str | None = None, *, system_model: str | Path | None = None, parent: bool = False) -> dict”

Make a parent or a child of a database, under new_name.

parent=True reads the database’s files again keeping every block of several products whole, each declared share turned into a price. system_model divides a parent into a child: the text of a system model’s TOML file, or the path of one, which names the property every block is divided by and the exceptions, each with its own property, its reason, and the processes it takes::

name = "Agribalyse, economic"
version = "1.0.0"
[allocation]
default = "price"
[[allocation.exceptions]]
key = "wet mass"
reason = "Dairies weigh their milk, not its price."
classification = { system = "Category", value = "Agricultural\\Food\\Cheese production" }

Give one of the two. allocation="none", the form before system models, still asks for a parent and warns; a property there is refused, since a database is no longer read from its files under one. The source is untouched and every database stays loadable side by side, so two divisions of one study can be compared.

This is a full load, not a copy: seconds to minutes on a large database. Refused when a parent is asked of a database that is not read from its files, a child of a database that is not a parent, when the model does not read, or when an exception takes or divides nothing; a refusal names what went wrong.

Returns the engine’s LoadDatabaseResponse dict, as load_database does: "database" describes the new database and "deps" how each of its dependencies loaded.

Client.document_file(path: str, db_name: str | None = None) -> bytes
Section titled “Client.document_file(path: str, db_name: str | None = None) -> bytes”

The bytes of a file a database ships with a literature entry.

path is one of the files a literature entry of the database’s setup documentation lists, such as external_docs/report.pdf; only an ILCD package ships any. Raises VoLCAError on an HTTP error, a 404 when the documentation lists no such file or the package does not hold it, a 403 when the database’s licence refuses downloads.

Client.download_flow_synonyms(name: str) -> bytes
Section titled “Client.download_flow_synonyms(name: str) -> bytes”

Download a flow-synonyms set as its raw CSV bytes.

Raises VoLCAError on an HTTP error (e.g. the set does not exist).

Download a unit table as its raw CSV bytes.

Raises VoLCAError on an HTTP error (e.g. the table does not exist).

Client.drop_scenario(name: str, *, db_name: str | None = None) -> list[Scenario]
Section titled “Client.drop_scenario(name: str, *, db_name: str | None = None) -> list[Scenario]”

Drop a saved scenario, and return the scenarios left. Refused for a scenario the database ships, which comes back at every load.

Client.edit_activities(edits: Sequence[ActivityEdit], *, note: str | None = None, source: dict | None = None, db_name: str | None = None) -> dict
Section titled “Client.edit_activities(edits: Sequence[ActivityEdit], *, note: str | None = None, source: dict | None = None, db_name: str | None = None) -> dict”

Edit several activities as one change: what edit_exchanges does for one, for each ActivityEdit.

Every edit is judged before anything is written, and one refused edit refuses them all. The database is then rebuilt, relinked and saved once rather than once per activity, which on a large database is most of what an edit costs. An activity is named once per call, two products of one activity included::

client.edit_activities(
[
ActivityEdit("a_b", set_amounts=[SetAmount(ExchangeSelector.biosphere_flow("f-1"), 0.2)]),
ActivityEdit("c_d", remove=[ExchangeSelector.input_from("e_f")]),
],
note="Measured on site",
)

The answer lists each activity’s report, as edit_exchanges gives it, in the order of edits, then transient and the warnings of the change once::

{"edited": [{"removed": [], "amountsSet": [1], ...}, ...],
"transient": False, "warnings": []}

note says why, for every activity edited. Needs wire revision 107.

source says where the figures come from, as {"document": ..., "page": 7, "passage": ...} (page and passage are optional): it is kept beside the reason. Needs wire revision 111.

Client.edit_database_parameters(*, set_parameters: Sequence[SetParameter] = (), remove_parameters: Sequence[str] = (), note: str | None = None, source: dict | None = None, db_name: str | None = None) -> dict
Section titled “Client.edit_database_parameters(*, set_parameters: Sequence[SetParameter] = (), remove_parameters: Sequence[str] = (), note: str | None = None, source: dict | None = None, db_name: str | None = None) -> dict”

Set or remove the database’s own parameters, then restate every process that reads them: each line whose formula no longer gives its amount takes the formula’s value. The answer names the parameters set and removed, and restatedProcesses the process ids that moved::

{"parametersSet": ["distance"], "parametersRemoved": [],
"restatedProcesses": ["a_b"], "transient": False, "warnings": []}

Removals come after the parameters set, and are refused while a formula still reads the name. Only a database of your own accepts edits: copy a configured one first.

note says why, in a sentence: it is kept in the database’s history (database_history) and in the changes report its export carries. Needs wire revision 79.

source says where the figures come from, as {"document": ..., "page": 7, "passage": ...} (page and passage are optional): it is kept beside the reason. Needs wire revision 111.

Client.edit_exchanges(process_id: str, *, remove: Sequence[ExchangeSelector] = (), set_amounts: Sequence[SetAmount] = (), add_inputs: Sequence[TechInput] = (), add_biosphere: Sequence[BioExchange] = (), add_waste_outputs: Sequence[WasteOutput] = (), name: str | None = None, location: str | None = None, description: list[str] | None = None, set_parameters: Sequence[SetParameter] = (), set_formulas: Sequence[SetFormula] = (), set_prices: Sequence[SetPrice] = (), set_dry_masses: Sequence[SetDryMass] = (), set_wet_masses: Sequence[SetWetMass] = (), set_suppliers: Sequence[SetSupplier] = (), remove_parameters: Sequence[str] = (), note: str | None = None, source: dict | None = None, db_name: str | None = None) -> dict
Section titled “Client.edit_exchanges(process_id: str, *, remove: Sequence[ExchangeSelector] = (), set_amounts: Sequence[SetAmount] = (), add_inputs: Sequence[TechInput] = (), add_biosphere: Sequence[BioExchange] = (), add_waste_outputs: Sequence[WasteOutput] = (), name: str | None = None, location: str | None = None, description: list[str] | None = None, set_parameters: Sequence[SetParameter] = (), set_formulas: Sequence[SetFormula] = (), set_prices: Sequence[SetPrice] = (), set_dry_masses: Sequence[SetDryMass] = (), set_wet_masses: Sequence[SetWetMass] = (), set_suppliers: Sequence[SetSupplier] = (), remove_parameters: Sequence[str] = (), note: str | None = None, source: dict | None = None, db_name: str | None = None) -> dict”

Change what one activity consumes and emits, its texts or its parameters, keeping the activity.

This reaches what replace_activity cannot: an activity that came in from a database file. Its identity was minted by whichever parser read it, so no description addresses it, and a description could not carry back its classification, synonyms, parameters, pedigree or coproducts anyway. Here you name only the lines that change, and everything else stays as it was.

Only the inventory side is addressable. The reference product and any coproduct carry the activity’s identity and its allocation, so no selector reaches them. Their price alone can change: set_prices names each product by its flow id, and pricesSet counts the products priced. A price is what the "price" allocation key of derive_database divides a process of several products by. Needs wire revision 84. Their dry mass too: set_dry_masses states it per unit of each product, and dryMassesSet counts the products reached; it is what a "dry mass" exception of a system model divides by. Needs wire revision 87. Their wet mass too: set_wet_masses states it per unit of each product, which on a product in litres or cubic metres is its density, and wetMassesSet counts the products reached; the "wet mass" key weighs it before the line’s own amount. Needs wire revision 89.

A selector that names nothing is refused rather than treated as done. One that names several lines applies to all of them, and the counts come back per selector, in the order you stated them::

{"removed": [2], "amountsSet": [], "added": 1, "textsSet": [],
"transient": False, "warnings": [...]}

name, location and description (one string per paragraph, an empty list clears it) restate the activity’s texts under the process id it already has. An activity written with create_activities is refused a new name or location, which make its identity: rewrite it with replace_activity instead. textsSet names the texts rewritten.

set_parameters adds or replaces parameters of the activity, set_formulas gives lines a formula (see formula_language), and remove_parameters removes parameters once the formulas set here no longer read them. With every change in, each line whose formula no longer gives its amount takes the formula’s value; restated lists those lines by position, with the amount moved from and to.

set_suppliers moves inputs to another supplier, in this database or a dependency, and links an input that named none: each line keeps its amount, unit, formula, comment, pedigree and place, and suppliersSet counts the lines moved. Needs wire revision 108.

Each line of get_activity carries the selector that reaches it (selector), including a line no provider is named for, which is selected by its flow and location.

Only a database of your own accepts edits: copy a configured one first.

Needs an engine speaking wire revision 7, 56 for the texts, 73 for the parameters and formulas, and 76 for a selector by flow of an input or a waste output.

note says why, in a sentence: it is kept in the database’s history (database_history) and in the changes report its export carries. Needs wire revision 79.

source says where the figures come from, as {"document": ..., "page": 7, "passage": ...} (page and passage are optional): it is kept beside the reason. Needs wire revision 111.

Client.ensure_database(source: str | Path | bytes, name: str | None = None) -> str
Section titled “Client.ensure_database(source: str | Path | bytes, name: str | None = None) -> str”

Idempotently make the archive at source a loaded database.

The one-call form of the upload lifecycle: match by display name (default: the file’s stem), upload only when absent, finalize the staged copy, load if unloaded. Returns the slug every later call targets: run it at the top of a script and it converges on the same loaded database every time instead of re-uploading. A match that is already loaded, even partially linked, is left untouched.

A staged copy that is not ready to finalize raises VoLCAError naming the blocker (missing suppliers, no activities parsed); fix it with add_dependency or set_data_path, then finalize_database. The gate also holds on re-runs: an upload left staged by an earlier failed run goes through the same readiness check instead of being loaded half-linked.

Client.explain_cf(method_id: str, flow_id: str, *, collection: str | None = None) -> ExplainCFResult
Section titled “Client.explain_cf(method_id: str, flow_id: str, *, collection: str | None = None) -> ExplainCFResult”

Explain why one flow scores with the characterization factor it does.

result.explanation is a list of sentences written by the engine: show them as they are. The structured fields say the same thing in a form you can compare or filter on, and result.steps_tried lists the rungs the cascade walked before the one that answered. collection names the collection to read when several carry the method.

Client.export_database(fmt: str, db_name: str | None = None, *, package: str | None = None) -> bytes
Section titled “Client.export_database(fmt: str, db_name: str | None = None, *, package: str | None = None) -> bytes”

Export a loaded database, returning the serialized bytes.

fmt is one of simapro|ecospold1|ecospold2|ilcd|brightway|openlca, validated client-side; an unknown value raises VoLCAError before any request. Single-file formats carry their bytes directly; EcoSpold 2, ILCD and openLCA multi-file trees come back zipped. openlca needs wire revision 61.

package="ro-crate" returns instead a zip holding that export under payload/, beside an RO-Crate ro-crate-metadata.json describing the licence the database is served under, the digest of the export and the release of every database it links to, so a reader’s engine can tell whether it holds the same data. A dependency with no release declared (see set_release) refuses it with a 400 naming it. Needs wire revision 49.

A modified database (see DatabaseInfo.modified) is exported only as a package, which carries CHANGES.md, the report of every change and its reason, and LICENCE.txt: with package unset, pyvolca asks for ro-crate itself and warns that it did.

The engine streams the payload as raw bytes. Best-effort approximation warnings arrive in the X-Volca-Export-Warnings response header (percent-encoded, newline-joined) and are surfaced through warnings. Raises VoLCAError on an HTTP error, a 403 when the database’s licence refuses downloads.

Client.export_method_collection(name: str, fmt: str = 'simapro') -> bytes
Section titled “Client.export_method_collection(name: str, fmt: str = 'simapro') -> bytes”

Export a loaded method collection, returning the serialized bytes.

fmt names the target format: simapro (SimaPro method CSV), csv (columnar CSV, one column per impact category, the spreadsheet view), openlca (a zip of openLCA JSON-LD impact categories), or ilcd (a zip of an ILCD LCIA-method package, one method dataset per impact category plus its flow datasets). Projection warnings (anything the format cannot carry faithfully) arrive in the X-Volca-Export-Warnings response header and are surfaced through warnings. Raises VoLCAError on an HTTP error, including a collection that is not loaded.

Client.export_to_file(fmt: str, out_path: str, db_name: str | None = None, *, package: str | None = None) -> None
Section titled “Client.export_to_file(fmt: str, out_path: str, db_name: str | None = None, *, package: str | None = None) -> None”

Export a database (see export_database) and write it to a file.

Client.finalize_database(db_name: str | None = None) -> dict
Section titled “Client.finalize_database(db_name: str | None = None) -> dict”

Build matrices for a staged database and load it (ActivateResponse).

Call after dependencies resolve (get_setup reports isReady). Raises VoLCAError if the engine refuses it (e.g. unresolved suppliers).

Client.forget_usage(boot: str, through: int) -> None
Section titled “Client.forget_usage(boot: str, through: int) -> None”

Forget the usage lines collected, up to seq through.

boot is the one usage returned; a cursor from another start of the engine raises VoLCAError with a 409. Needs wire revision 53.

The formula language: every function and operator with its usage, meaning and an example, the operators by how tightly they bind, and the rules for numbers, names and arguments.

Client.get_activity(process_id: str) -> ActivityDetail
Section titled “Client.get_activity(process_id: str) -> ActivityDetail”

Fetch an activity’s full detail.

Returns a typed ActivityDetail. Use act.inputs / act.outputs / act.technosphere_inputs to filter exchanges instead of walking act.exchanges directly.

Client.get_characterization(method_id: str, *, flow: str | None = None, limit: int | None = None, collection: str | None = None) -> CharacterizationResult
Section titled “Client.get_characterization(method_id: str, *, flow: str | None = None, limit: int | None = None, collection: str | None = None) -> CharacterizationResult”

Look up characterization factors for a method matched to database flows.

Returns a CharacterizationResult carrying matches (total rows the filter selected) and shown (rows actually returned under limit). Check result.has_more to detect truncation. collection names the collection to read when several carry the method.

Client.get_collection_coverage(collection: str, db_name: str | None = None) -> CollectionCoverage
Section titled “Client.get_collection_coverage(collection: str, db_name: str | None = None) -> CollectionCoverage”

How much of a database a whole method collection characterizes.

Counts the distinct emission and resource flows at least one of the collection’s methods resolves a factor for, with the same lookup scoring uses. Distinct across methods: their factors overlap, so the per-method figures from get_mapping_status do not add up to this number.

Client.get_consumers(process_id: str, *, name: str | None = None, location: str | None = None, product: str | None = None, preset: str | None = None, classification_filters: list[ClassificationFilter] | None = None, page: int | None = None, page_size: int | None = None, limit: int | None = None, offset: int | None = None, max_depth: int | None = None, sort: str | None = None, order: str | None = None, include_edges: bool = False) -> ConsumersResponse
Section titled “Client.get_consumers(process_id: str, *, name: str | None = None, location: str | None = None, product: str | None = None, preset: str | None = None, classification_filters: list[ClassificationFilter] | None = None, page: int | None = None, page_size: int | None = None, limit: int | None = None, offset: int | None = None, max_depth: int | None = None, sort: str | None = None, order: str | None = None, include_edges: bool = False) -> ConsumersResponse”

Find all activities that transitively consume this supplier.

Args: max_depth: Max hops from supplier. 1 = direct consumers only. classification_filters: ClassificationFilter entries restricting the results. Multiple filters are AND-combined by the server. Mode is MatchMode.EXACT or MatchMode.CONTAINS. sort: Sort key: "name", "location", "product", "amount", or "unit". Default orders by depth. order: "desc" to reverse; ascending otherwise. include_edges: When True, the response carries every technosphere edge whose endpoints are both reachable from the supplier. Callers can walk these to reconstruct supplier→consumer paths without a second get_path_to round-trip.

Returns a ConsumersResponse whose consumers attribute is a SearchResults[ConsumerResult] (iterate it to walk every consumer across all pages) and whose edges attribute carries the traversal subgraph (empty by default).

Client.get_contributing_activities(process_id: str, method_id: str, *, collection: str | None = None, limit: int | None = None) -> ContributingActivities
Section titled “Client.get_contributing_activities(process_id: str, method_id: str, *, collection: str | None = None, limit: int | None = None) -> ContributingActivities”

Which upstream activities drive a given impact category.

Same engine-side limitation as get_contributing_flows: no total exposed, so has_more cannot be derived. Inspect share_pct totals to gauge coverage. method_id takes a method name as well as a UUID, and collection is read off the resolved method unless you pin it.

Client.get_contributing_flows(process_id: str, method_id: str, *, collection: str | None = None, limit: int | None = None) -> ContributingFlows
Section titled “Client.get_contributing_flows(process_id: str, method_id: str, *, collection: str | None = None, limit: int | None = None) -> ContributingFlows”

Which elementary flows drive a given impact category.

Returns a ContributingFlows. Caveat: the engine does not report the total flow count, so pyvolca cannot derive has_more from the response. Pass a generous limit if you need exhaustive coverage and inspect share_pct totals. method_id takes a method name as well as a UUID, and collection is read off the resolved method unless you pin it.

Client.get_flow(flow_id: str, db_name: str | None = None) -> FlowDetail
Section titled “Client.get_flow(flow_id: str, db_name: str | None = None) -> FlowDetail”

Detail of one flow: its record, unit, and how many exchanges use it.

Client.get_flow_activities(flow_id: str, db_name: str | None = None, *, role: str | None = None) -> list[Activity]
Section titled “Client.get_flow_activities(flow_id: str, db_name: str | None = None, *, role: str | None = None) -> list[Activity]”

Activities on one side of a flow, or both.

Args: flow_id: The flow to ask about. db_name: Database to ask; the current one by default. role: "producer" for the activities that make the flow, "consumer" for those that use it, "any" or omitted for both. Needs engine wire revision 16; an older engine would ignore the parameter and answer with both sides, so the request is refused rather than sent.

Note that both sides together are narrower than asking for both: an avoided product is an exchange on the flow that neither makes it for sale nor consumes it, and only the unfiltered call lists it.

Client.get_flow_factors(flow_id: str, *, collection: str | None = None, db_name: str | None = None) -> FlowFactors
Section titled “Client.get_flow_factors(flow_id: str, *, collection: str | None = None, db_name: str | None = None) -> FlowFactors”

Every factor the loaded method collections give one flow.

Each collection explains, as explain_cf does, the methods whose factors reach the flow, and names those that give it none. collection asks one collection alone. Needs wire revision 55.

Client.get_flow_mapping(method_id: str, *, collection: str | None = None) -> FlowMapping
Section titled “Client.get_flow_mapping(method_id: str, *, collection: str | None = None) -> FlowMapping”

Get the characterization-factor-to-database-flow mapping coverage.

FlowMapping.coverage_pct summarises how many of the DB’s biosphere flows the method has a CF for; flows is the per-flow breakdown including unmatched rows (cf_value=None). collection names the collection to read when several carry the method.

Client.get_impacts(process_id: str, method_id: str, *, collection: str | None = None, top_flows: int | None = None, substitutions: list[SubstitutionLike] | None = None, parameters: list[ParameterValue] | None = None) -> LCIAResult
Section titled “Client.get_impacts(process_id: str, method_id: str, *, collection: str | None = None, top_flows: int | None = None, substitutions: list[SubstitutionLike] | None = None, parameters: list[ParameterValue] | None = None) -> LCIAResult”

Compute the LCIA score for a single impact category on an activity.

Use get_impacts_batch to retrieve every category in a method collection at once (and any configured scoring sets).

Args: method_id: A method UUID, or the method’s name (“Water use”); a name is resolved against the engine’s loaded methods. collection: Method collection name. Left out, it is read off the resolved method, so the caller needs to know only the method. top_flows: Max top contributing flows to return (default 5). substitutions: Upstream supplier swaps; see get_supply_chain. parameters: Values for input parameters; see get_supply_chain.

Client.get_impacts_batch(process_id: str, *, collection: str | None = None, substitutions: list[SubstitutionLike] | None = None, exclude_long_term: bool | None = None, parameters: list[ParameterValue] | None = None, exchange_contributions: bool = False) -> LCIABatchResult
Section titled “Client.get_impacts_batch(process_id: str, *, collection: str | None = None, substitutions: list[SubstitutionLike] | None = None, exclude_long_term: bool | None = None, parameters: list[ParameterValue] | None = None, exchange_contributions: bool = False) -> LCIABatchResult”

Compute LCIA for every impact category in a collection, in one call.

The response carries the per-method LCIAResult list plus any formula-based scoring sets declared in the engine config (PEF, ECS…). scoring_indicators gives the per-variable breakdown of each scoring set, pre-multiplied by the set’s displayMultiplier. exclude_long_term drops long-term emissions before scoring, the same switch score_activities carries. parameters gives values for input parameters, as get_supply_chain takes them. exchange_contributions=True gives each result the LCIAResult.exchange_contributions of the activity’s own lines, which add up to its score, to group into stages; it is refused with substitutions, and scoring-set scores are not split by line.

Left without a collection, the call runs against the only loaded one, and refuses when several are loaded rather than picking one.

Uses a direct HTTP call: the batch endpoint has no operationId in the OpenAPI spec (the dispatcher primary is the single-method variant), so this wrapper bypasses _call and builds the URL itself.

Client.get_inputs(process_id: str) -> list[Exchange]
Section titled “Client.get_inputs(process_id: str) -> list[Exchange]”

Return the input exchanges of an activity (richer metadata than get_activity).

Uses a direct HTTP call because /inputs has no operationId (it’s a non-Resources auxiliary endpoint).

Client.get_inventory(process_id: str, *, flow: str | None = None, limit: int | None = None, substitutions: list[SubstitutionLike] | None = None, parameters: list[ParameterValue] | None = None) -> InventoryResult
Section titled “Client.get_inventory(process_id: str, *, flow: str | None = None, limit: int | None = None, substitutions: list[SubstitutionLike] | None = None, parameters: list[ParameterValue] | None = None) -> InventoryResult”

Compute the life-cycle inventory (cumulative biosphere flows) for an activity.

Returns an InventoryResult with the per-elementary-flow totals scaled to one functional unit of the activity’s reference product. Use get_impacts to apply a characterization method to the inventory; use aggregate with scope="biosphere" for grouped views.

Args: flow: Keep the flows whose name answers this query, read the way search_flows reads it, synonyms included. limit: Keep this many flows, largest in absolute quantity first. Without it, every flow is returned. The statistics cover the whole inventory either way. substitutions: Upstream supplier swaps; see get_supply_chain. parameters: Values for input parameters; see get_supply_chain.

Client.get_mapping_status(method_id: str, db_name: str | None = None, *, collection: str | None = None) -> MappingStatus
Section titled “Client.get_mapping_status(method_id: str, db_name: str | None = None, *, collection: str | None = None) -> MappingStatus”

How well a method’s factors map onto a database’s biosphere flows.

Reports the cascade breakdown (matched by UUID / CAS / name / synonym), the coverage fraction, and the unmapped_flows still without a CF. collection names the collection to read when several carry the method.

Client.get_method(method_id: str, *, collection: str | None = None) -> MethodDetail
Section titled “Client.get_method(method_id: str, *, collection: str | None = None) -> MethodDetail”

Detail of one LCIA method: unit, category, methodology, factor count.

collection names the collection to read when several carry the method.

Client.get_method_factors(method_id: str, *, collection: str | None = None) -> list[MethodFactor]
Section titled “Client.get_method_factors(method_id: str, *, collection: str | None = None) -> list[MethodFactor]”

The characterization factors of a method (flow, direction, value).

collection names the collection to read when several carry the method.

Client.get_outputs(process_id: str) -> list[Exchange]
Section titled “Client.get_outputs(process_id: str) -> list[Exchange]”

Return the output exchanges of an activity. See get_inputs for notes.

Client.get_path_to(process_id: str, target: str) -> PathResult
Section titled “Client.get_path_to(process_id: str, target: str) -> PathResult”

Find the shortest upstream path from process to first activity whose name matches target.

Returns a PathResult whose path is ordered root → target. Each step includes cumulative_quantity, scaling_factor, and (except the root) local_step_ratio.

Client.get_score_contributing_activities(process_id: str, collection: str, scoring_set: str, score: str, *, limit: int | None = None) -> ContributingActivities
Section titled “Client.get_score_contributing_activities(process_id: str, collection: str, scoring_set: str, score: str, *, limit: int | None = None) -> ContributingActivities”

Which upstream activities drive one score of a scoring set.

Same split as get_score_contributing_flows: an activity’s contribution is the weighted sum of its contributions to each indicator, and the contributions add up to the score.

Client.get_score_contributing_flows(process_id: str, collection: str, scoring_set: str, score: str, *, limit: int | None = None) -> ContributingFlows
Section titled “Client.get_score_contributing_flows(process_id: str, collection: str, scoring_set: str, score: str, *, limit: int | None = None) -> ContributingFlows”

Which elementary flows drive one score of a scoring set.

A flow’s contribution is the weighted sum of its contributions to each indicator, so the contributions add up to the score, in the set’s unit. A row’s factor is what one unit of the flow adds to the score, and its match_kind is None: a single score weighs several factors into one. A score that is not a weighted sum of its indicators has no such split, and the engine refuses it.

Client.get_setup(db_name: str | None = None) -> dict
Section titled “Client.get_setup(db_name: str | None = None) -> dict”

Setup status of a staged or loaded database (DatabaseSetupInfo).

Key fields: isReady (can it be finalized/loaded), missingSuppliers and unresolvedLinks (unmet cross-database links), dependencies (declared deps), dataPath / availablePaths (the selected data file and the alternatives, see set_data_path), completeness, and supplierAmbiguities: the inputs several activities of one dependency answered equally well, each naming the product asked for, the activity linked to and how many tied, so the supplier meant can be named rather than guessed (wire revision 23). documentation is what the database says about itself (wire revision 36): under export, the tool that wrote the file, its format version, the day, time and project it was exported from; under systems, each system description its datasets name, and under literature each literature reference it holds, both with a name, category, sections and files (the files it ships, which document_file reads). A SimaPro export says all of it; an EcoSpold 1 database lists under literature the sources its datasets cite, and an ILCD package the sources it holds; another format leaves export null and both lists empty. licence is what the database is served under (wire revision 41), the shape set_licence takes and returns. release is which published database it is, the shape set_release takes, and systemModels the system models its activities state, each once (wire revision 48). requiredReleases lists the releases a package was built on (wire revision 50), each with its state, satisfied, missing or substituted, and the databases that meet it, or for a missing one those of the same name at another version; accept_substitution names another.

Return the engine’s runtime statistics (memory use, loaded sizes).

Keys are already snake_case on the wire, so this returns the raw dict.

Client.get_supply_chain(process_id: str, *, name: str | None = None, location: str | None = None, limit: int | None = None, min_quantity: float | None = None, max_depth: int | None = None, preset: str | None = None, classification_filters: list[ClassificationFilter] | None = None, sort: str | None = None, order: str | None = None, substitutions: list[SubstitutionLike] | None = None, parameters: list[ParameterValue] | None = None, include_edges: bool | None = None) -> SupplyChain
Section titled “Client.get_supply_chain(process_id: str, *, name: str | None = None, location: str | None = None, limit: int | None = None, min_quantity: float | None = None, max_depth: int | None = None, preset: str | None = None, classification_filters: list[ClassificationFilter] | None = None, sort: str | None = None, order: str | None = None, substitutions: list[SubstitutionLike] | None = None, parameters: list[ParameterValue] | None = None, include_edges: bool | None = None) -> SupplyChain”

Get the flat supply chain of an activity.

Returns a SupplyChain. Check result.has_more to detect when limit truncated entries below filtered_activities: further downstream analysis on a truncated chain would be wrong without flagging the gap.

Each entry carries its own unit, and entries do not share one: it is the producing activity’s reference-product unit, which is not always the unit written on the exchange that consumes it. Read it off the entry rather than off the activity you started from.

Args: max_depth: Max hops from root. 1 = direct inputs only. classification_filters: Restrict entries to those matching any of the given ClassificationFilter triples. Multiple filters are AND-combined by the server. sort: Sort key: "name", "location", "unit", "depth", "consumers", or "amount". Default orders by descending absolute quantity. order: "desc" to reverse; ascending otherwise. substitutions: When provided, the call is upgraded to POST and the scaling vector is recomputed with the substituted suppliers. Accepts Substitution (preferred) or the legacy {"from", "to", "consumer"} dict form; consumer is optional: omit it for a global swap. parameters: Values for input parameters: the amounts whose formulas read them are computed again for this call, and the substitutions are made on the database at those values.

Client.get_synonym_groups(name: str) -> list[list[str]]
Section titled “Client.get_synonym_groups(name: str) -> list[list[str]]”

Return the synonym groups of a flow-synonyms set (lists of aliases).

Fetch the recursive activity tree used by the analysis SPA.

/tree has no operationId in the OpenAPI spec; it’s kept for the SPA’s lazy-expanding graph widget and intentionally not exposed as a Resource. Included here as a direct HTTP call for scripts that need the same shape.

Return server build metadata: version, git hash/tag, build target.

Uses a direct HTTP call: /api/v1/version has no operationId since it predates the Resources ADT.

Client.install_method_collection(name: str) -> dict
Section titled “Client.install_method_collection(name: str) -> dict”

Download a collection available_method_collections offers, check it is the file the engine expects, then store and load it under that name (wire revision 103).

Refused when the engine is read-only, when it already knows a collection of that name, when the file is larger than the plan’s upload limit, and when the file received differs from the one expected.

The standard licences a database can be published under.

Each carries its id (SPDX), name, url, the conditions its permissions cannot say, and permissions: one entry per permission, granted or not, and enforced when the engine itself holds it back.

List classification systems and their values for the current database.

ClassificationSystem.activity_count tells how widely each system is populated, useful for picking a filter dimension with enough signal.

List every database declared in the engine config.

The typed entries carry depends_on, so callers can derive cross-DB dependency sets from declared topology rather than hardcoding allowlists.

List every method collection the engine knows (loaded or staged).

Each entry carries name, displayName, status, methodCount and format.

List every LCIA method available in the engine.

Each Method carries id, name, category, unit, factor_count, and the parent collection. Every method_id argument takes either, so this list is for browsing, not for looking up an id before a call.

List classification presets configured in this instance.

Each Preset carries its filters (list of PresetFilter triples). Apply by passing preset=p.name to filtering endpoints.

Client.list_reference_data(kind: RefDataKind) -> list[dict]
Section titled “Client.list_reference_data(kind: RefDataKind) -> list[dict]”

List reference-data sets of one kind (loaded, staged, or built-in).

Each entry carries name, displayName, status, isAuto (a built-in bundled set) and entryCount.

Client.load_database(db_name: str) -> dict
Section titled “Client.load_database(db_name: str) -> dict”

Load a database into memory so it answers queries.

Declared dependencies are loaded first; has no effect if the database is already loaded.

Client.load_method_collection(name: str) -> dict
Section titled “Client.load_method_collection(name: str) -> dict”

Load a staged method collection so its methods become available.

Client.load_reference_data(kind: RefDataKind, name: str) -> dict
Section titled “Client.load_reference_data(kind: RefDataKind, name: str) -> dict”

Load a staged reference-data set of kind into memory.

Client.method_history(collection: str) -> list[dict]
Section titled “Client.method_history(collection: str) -> list[dict]”

The journal of a collection, one entry per line.

Each entry gives its line, when it was written (at), the public name of the account that wrote it (by, None when the engine was not told; wire revision 104), its kind (change, undo or configuration, for what a copy took from its source’s configuration), the line it undoes, whether it is inEffect, and the change it made. A collection the configuration declares has an empty history.

Client.profile_method_collection(collection: str) -> dict
Section titled “Client.profile_method_collection(collection: str) -> dict”

What each impact category of a loaded method collection holds.

For each category: the factors per medium, how many are written for one location (and how many carry it at the end of their name, as "Ammonia, FR"), how many locations, zero factors, pattern rows, and the duplicates, the factors one key answers to at one place. Compartments and locations are read as compare_method_collections reads them.

Client.quality_report(db_name: str | None = None, *, limit: int | None = None) -> dict
Section titled “Client.quality_report(db_name: str | None = None, *, limit: int | None = None) -> dict”

The database’s structural quality report, as the engine sends it.

limit caps the findings listed per check, worst first.

Client.quality_report_csv(db_name: str | None = None, *, limit: int | None = None) -> bytes
Section titled “Client.quality_report_csv(db_name: str | None = None, *, limit: int | None = None) -> bytes”

The structural quality report as the CSV file the web page offers.

Client.reduced_model(process_id: str, parameters: list[ParameterName], *, collection: str | None = None, exclude_long_term: bool | None = None) -> ReducedModel
Section titled “Client.reduced_model(process_id: str, parameters: list[ParameterName], *, collection: str | None = None, exclude_long_term: bool | None = None) -> ReducedModel”

The activity’s scores as a function of some of its input parameters.

Returns a ReducedModel whose ReducedModel.evaluate gives every score of the collection at thousands of sets of values (Monte Carlo, Sobol indices) on this side, equal to what score_activities with parameter_sets would answer. The other parameters stay at their values. The engine refuses a parameter that moves an allocation share, and a model too large to send.

Fetch the OpenAPI spec from the server and refresh the dispatch table.

Also regenerates the .pyi type stubs in the installed pyvolca package directory so IDE autocomplete reflects the current engine. Useful when the engine is upgraded without reinstalling pyvolca.

This is the explicit “the engine was upgraded” path, the likeliest place to meet a wire change, so it forgets the cached wire and re-runs the gate against the live engine before fetching a spec pyvolca can’t decode. Without the reset, a client that first met an older engine would keep refusing wire-gated capabilities after an in-place upgrade.

Client.relink(dep_db: str, mapping_csv: str, db_name: str | None = None) -> dict
Section titled “Client.relink(dep_db: str, mapping_csv: str, db_name: str | None = None) -> dict”

Re-link a database against a dependency using a mapping CSV.

mapping_csv is the CSV text, sent inline so the engine needs no filesystem access. Each row maps a source (source_product or source_id, with an optional source_location) to a target (target_product or target_id, with an optional target_location); a row with no target keeps its input unlinked, and columns the engine does not know are ignored. conversion, with source_unit and target_unit, says how many source units one target unit holds (a car of 1200 kg is 1 p: 1200, kg, p; urea counted “as N” is 2.17, kg, kg). It always applies; one that contradicts the unit table between two units of different sizes (0.2778 from MJ to kWh) refuses the file. direction is opposite when the target counts the demand the other way than the supplier the line was written for (a wastewater market of reference -1 m3 mapped to a treatment of reference +1 m3), same or blank otherwise. It changes nothing on a SimaPro, ILCD or EcoSpold 1 database, whose lines already take their supplier’s sign. Returns the RelinkResponse dict ({"dbName", "unresolvedBefore", "unresolvedAfter", "crossDBLinks", "dependsOn"}).

Section titled “Client.relink_from_file(dep_db: str, mapping_path: str, db_name: str | None = None) -> dict”

Read a mapping CSV file and call relink with its text.

Client.remove_dependency(dep_name: str, db_name: str | None = None) -> dict
Section titled “Client.remove_dependency(dep_name: str, db_name: str | None = None) -> dict”

Remove dep_name from the target database’s dependencies.

Returns the updated DatabaseSetupInfo dict.

Client.remove_method_category(collection: str, method_id: str) -> dict
Section titled “Client.remove_method_category(collection: str, method_id: str) -> dict”

Remove an impact category of a collection of your own, with its factors.

Refused while a scoring set weighs it, naming the set. Undone with undo_method_edit, which puts it back with its factors.

Client.remove_method_factor(collection: str, method_id: str, flow_id: str, *, location: str | None = None, value: float | None = None) -> dict
Section titled “Client.remove_method_factor(collection: str, method_id: str, flow_id: str, *, location: str | None = None, value: float | None = None) -> dict”

Remove one characterization factor of a collection of your own.

Named as in set_method_factor, and refused on the same grounds.

Client.remove_score(collection: str, set_name: str, score: str) -> dict
Section titled “Client.remove_score(collection: str, set_name: str, score: str) -> dict”

Remove a score of a scoring set.

Client.remove_scoring_row(collection: str, set_name: str, variable: str) -> dict
Section titled “Client.remove_scoring_row(collection: str, set_name: str, variable: str) -> dict”

Remove the row of variable, refused while a score reads it other than as a sum of rows.

Client.remove_scoring_set(collection: str, name: str) -> dict
Section titled “Client.remove_scoring_set(collection: str, name: str) -> dict”

Remove a scoring set of a collection of your own.

Client.rename_method_category(collection: str, method_id: str, name: str) -> dict
Section titled “Client.rename_method_category(collection: str, method_id: str, name: str) -> dict”

Rename an impact category of a collection of your own.

The scoring sets and the unregionalized categories naming it follow, so they keep scoring it. A name already in use is refused.

Client.rename_scoring_set(collection: str, name: str, new_name: str) -> dict
Section titled “Client.rename_scoring_set(collection: str, name: str, new_name: str) -> dict”

Rename a scoring set of a collection of your own.

Client.replace_activity(process_id: str, activity: ActivityInput, db_name: str | None = None, *, note: str | None = None, source: dict | None = None) -> dict
Section titled “Client.replace_activity(process_id: str, activity: ActivityInput, db_name: str | None = None, *, note: str | None = None, source: dict | None = None) -> dict”

Rewrite one activity the database already holds, keeping its identity.

process_id must be the identity activity mints to; that is, the name, the location, and the product name and unit must be the ones the row already has, spelling and case included. Change any of those and you are describing a different activity, which the engine refuses rather than writing to a second row; create that one and delete the old one instead.

Returns the same shape as create_activities.

note says why, in a sentence: it is kept in the database’s history (database_history) and in the changes report its export carries. Needs wire revision 79.

source says where the figures come from, as {"document": ..., "page": 7, "passage": ...} (page and passage are optional): it is kept beside the reason. Needs wire revision 111.

Client.resolve_activities(names: Iterable[str], *, by: Literal['name', 'product'] = 'name', geo: str | None = None, exact: bool = True, limit: int = 5, workers: int = 8) -> dict[str, list[Activity]]
Section titled “Client.resolve_activities(names: Iterable[str], *, by: Literal['name', 'product'] = 'name', geo: str | None = None, exact: bool = True, limit: int = 5, workers: int = 8) -> dict[str, list[Activity]]”

Resolve a batch of names to their matching activities, concurrently.

One search_activities call per unique name, fanned out over workers threads on the client’s HTTP session. This replaces the two patterns scripts keep hand-rolling: downloading the whole database to build a name→process_id dict, and per-name thread pools.

The result maps every input name to its matches: the mapping is total, so misses are visible, never silently dropped:

  • []: no match; the name does not resolve.
  • one Activity: unambiguous; matches[0].process_id.
  • several: ambiguous (same name across geographies or products); disambiguate with geo= or inspect the candidates.

With exact=False matches are relevance-ranked (best first), so matches[0] is the engine’s best fuzzy guess.

Args: names: Names to resolve. Duplicates are searched once. by: Match against activity "name" or reference "product". geo: Restrict every search to one geography code. exact: Exact (default) or substring/ranked matching. limit: Maximum candidates returned per name. workers: Concurrent searches.

Returns: {name: matches} for every input name, in input order.

Client.save_scenario(name: str, parameters: Sequence[ParameterValue], *, db_name: str | None = None) -> list[Scenario]
Section titled “Client.save_scenario(name: str, parameters: Sequence[ParameterValue], *, db_name: str | None = None) -> list[Scenario]”

Save parameter values under a name, replacing what that name held, and return the scenarios saved. Refused when a scoring request would refuse the values, under the name of a scenario the database ships, and on a database read from the engine’s configuration: copy it first.

Client.scale_method_factors(collection: str, match: FactorMatch, scale: float) -> dict
Section titled “Client.scale_method_factors(collection: str, match: FactorMatch, scale: float) -> dict”

Multiply by scale every factor match reaches.

A selector that reaches no factor is refused rather than passed off as done; touched in the answer says how many changed.

Client.scenarios(*, db_name: str | None = None) -> list[Scenario]
Section titled “Client.scenarios(*, db_name: str | None = None) -> list[Scenario]”

The scenarios of the database: those it ships, then those saved on it. Score one by passing its parameters to a scoring request::

high = next(s for s in client.scenarios() if s.name == "high salt")
client.get_impacts(pid, "EF 3.1", parameters=high.parameters)
Client.score_activities(process_ids: list[str], *, collection: str | None = None, top_flows: int | None = None, exclude_long_term: bool | None = None, parameter_sets: list[list[ParameterValue]] | None = None) -> BatchScores
Section titled “Client.score_activities(process_ids: list[str], *, collection: str | None = None, top_flows: int | None = None, exclude_long_term: bool | None = None, parameter_sets: list[list[ParameterValue]] | None = None) -> BatchScores”

Score many processes in one call (every category of a collection each).

Returns a BatchScores: results holds one ScoredActivity per process the engine could compute, while not_found / invalid list the ids it could not resolve and unsolvable those it has no answer for, each with why; inspect them, a partial result is not an error. top_flows caps the top contributors per category; exclude_long_term drops long-term emissions from the totals. Left without a collection, the call runs against the only loaded one, and refuses when several are loaded rather than picking one. parameter_sets scores every process once at each set of ParameterValue, set after set; each ScoredActivity then carries the position of its set in parameter_set.

Client.score_table(process_ids: list[str], *, collection: str | None = None, chunk: int = 100, workers: int = 8, exclude_long_term: bool | None = None) -> list[dict]
Section titled “Client.score_table(process_ids: list[str], *, collection: str | None = None, chunk: int = 100, workers: int = 8, exclude_long_term: bool | None = None) -> list[dict]”

Score many processes into one flat row each, in the order given.

A row holds process_id, activity_name, product_amount and product_unit (the reference each score is per one unit of), each method’s score under the method’s name (not its category, which several methods share: four climate change methods in EF 3.1), and each scoring set’s scores under the set’s then the score’s name: "ECS total" for a set declared with a total formula, "ECS Single score" for one built with create_scoring_set. The ids go in batches of chunk (a hosted engine caps a batch), workers at a time. exclude_long_term is as in score_activities. Raises VoLCAError naming every id the engine did not score.

Client.scoring_sets(collection: str) -> list[dict]
Section titled “Client.scoring_sets(collection: str) -> list[dict]”

The scoring sets of a loaded collection, each read as rows.

Each set gives its name, unit and displayMultiplier; its rows, each with the variable that names it, its label, its terms (RowGrouped with the categories it adds up, each with its methodId and coefficient, or RowWritten with a formula that is no such sum), its normalization (the string "Infinity" for a row a file counts as zero) and weight; its scores, each with its formula and whether it is the sumOfRows a new row joins; the variables a formula can read, each with the category it reads or the label of its row; and whether it weighs, a score taking a category otherwise than once or adding up normalized categories (wire revision 105).

Needs an engine speaking wire revision 45.

Client.search_activities(name: str | None = None, *, geo: str | None = None, product: str | None = None, preset: str | None = None, classification: str | None = None, classification_value: str | None = None, classification_match: MatchModeLike | None = None, page: int | None = None, page_size: int | None = None, limit: int | None = None, offset: int | None = None, sort: str | None = None, order: str | None = None, exact: bool = False) -> SearchResults[Activity]
Section titled “Client.search_activities(name: str | None = None, *, geo: str | None = None, product: str | None = None, preset: str | None = None, classification: str | None = None, classification_value: str | None = None, classification_match: MatchModeLike | None = None, page: int | None = None, page_size: int | None = None, limit: int | None = None, offset: int | None = None, sort: str | None = None, order: str | None = None, exact: bool = False) -> SearchResults[Activity]”

Search activities in the current database.

All filters are AND-combined and case-insensitive. name and product match by substring unless exact=True.

Returns a paginated SearchResults: iterate it to walk every match across all pages (subsequent pages fetched on demand), or use .page(n) for explicit page access. len(results) is the server-reported total across all pages.

Args: name: Substring (or exact match) on activity name. geo: Geography code ("FR", "GLO", "RoW"…). Matches that location, plus every location inside it ("US" also matches "US-WECC", "RER" matches "FR"). Which place sits inside which comes from the engine’s location table, never from how a code is spelled, so "GL" does not match "GLO"; exact=True narrows it to the location itself. product: Substring on the reference product name. preset: Apply a named classification preset configured in the engine. classification: System name ("ISIC rev.4 ecoinvent"). classification_value: Substring within that system’s value. classification_match: How classification_value is compared: MatchMode.CONTAINS (default, substring) or MatchMode.EXACT (case-insensitive equality). Ignored when classification is unset. page: 1-based page number. Must be paired with page_size: offset cannot be derived from page alone. page_size: Items per page (becomes the wire-level limit). Alone (no page) means “page 1 with this size”. limit: Wire-level cap on returned items. Prefer page_size. offset: Wire-level starting index. Prefer page + page_size. sort: Sort key: "name" or "location". When set, results are ordered lexicographically instead of by relevance. order: "desc" to reverse; ascending otherwise. exact: When True, name and product are matched exactly.

Returns: SearchResults[Activity], iterable across all pages.

Client.search_flows(query: str | None = None, *, kind: str | None = None, page: int | None = None, page_size: int | None = None, limit: int | None = None, offset: int | None = None, sort: str | None = None, order: str | None = None) -> SearchResults[Flow]
Section titled “Client.search_flows(query: str | None = None, *, kind: str | None = None, page: int | None = None, page_size: int | None = None, limit: int | None = None, offset: int | None = None, sort: str | None = None, order: str | None = None) -> SearchResults[Flow]”

Search flows in the current database.

Three kinds of flow answer, and Flow.kind says which each one is: a technosphere product one activity makes and another consumes, a biosphere substance exchanged with nature, or a waste.

Returns a paginated SearchResults[Flow]: iterate to walk every match across all pages, or use .page(n) for explicit access. See search_activities for the pagination contract.

Args: query: Words matched case-insensitively against flow names and synonyms. Every word must appear, in any order, and a word matches inside a longer one (chlor finds Trichloroethane). Punctuation separates words, so water fossil and water, fossil search alike. With no sort asked for, names carrying the query as typed come first. An empty query returns nothing. kind: Keep only these kinds: "technosphere", "biosphere" or "waste". Omit for all three. Name several separated by commas, as in "biosphere,waste", which is what is exchanged with nature or discarded and the bucket count_search_matches reports as flows. One kind needs engine wire revision 9: an older engine would drop the filter and answer with every kind. Several need revision 19, where an older engine reads the whole value as one name and refuses it. Either way the request is refused here first, with a message naming the revision, rather than sent. page / page_size: Web-style pagination; convert to wire-level offset / limit. limit / offset: Wire-level escape hatch. sort: Sort key: "name" (default), "category", or "unit". order: "desc" to reverse; ascending otherwise.

Client.search_method_flows(collection: str, q: str, *, limit: int | None = None) -> list[dict]
Section titled “Client.search_method_flows(collection: str, q: str, *, limit: int | None = None) -> list[dict]”

The flows a loaded collection characterizes whose name holds every word of q.

Once per direction and compartment, sorted by name, with the flow id and compartment a new factor for that flow is written with (50 at most unless limit says otherwise).

Client.set_data_path(path: str, db_name: str | None = None) -> dict
Section titled “Client.set_data_path(path: str, db_name: str | None = None) -> dict”

Choose which data file a staged multi-file archive should use.

path must be one of the availablePaths reported by get_setup, relative to the upload directory. Returns the updated DatabaseSetupInfo dict.

Client.set_description(description: str | None, db_name: str | None = None) -> str | None
Section titled “Client.set_description(description: str | None, db_name: str | None = None) -> str | None”

Describe an uploaded database, or clear its description with None or a blank text.

Returns the description kept, without the spaces around it, or None. Raises VoLCAError on an HTTP error: a 404 for an unknown database, a 409 for one the configuration file declares. Needs wire revision 94.

Client.set_display_name(name: str, db_name: str | None = None) -> str
Section titled “Client.set_display_name(name: str, db_name: str | None = None) -> str”

Rename an uploaded database: the name it is shown under, not the name it is addressed by, which its links and the databases depending on it keep.

Returns the name kept, without the spaces around it. Raises VoLCAError on an HTTP error: a 400 for a blank name, a 404 for an unknown database, a 409 for one the configuration file declares. Needs wire revision 92.

Client.set_licence(licence: dict, db_name: str | None = None) -> dict
Section titled “Client.set_licence(licence: dict, db_name: str | None = None) -> dict”

Set the licence an uploaded database is published under.

licence names one by its kind: {"kind": "standard", "id": "CC-BY-4.0"} for a standard licence (licences lists them), {"kind": "own", "text": ..., "refused": ["download", ...], "attribution": True, "accept": True, "usage": "anonymous"} for an own one, or {"kind": "unstated"}. usage counts the computations made on the database for its publisher, "anonymous" or with each reader’s "organizations"; it needs accept, since readers accept the clause with the text, and is left out to count nothing. A licence this returns can be sent back as it came. A database whose licence refuses download answers export_database and document_file with a 403, and so does every copy of it. Returns the licence now in force, with the permissions it settles. Raises VoLCAError on an HTTP error: a 409 for a database whose licence is written elsewhere, in the configuration file or on the source a copy reads.

Client.set_method_category_unit(collection: str, method_id: str, unit: str) -> dict
Section titled “Client.set_method_category_unit(collection: str, method_id: str, unit: str) -> dict”

Change the unit an impact category of a collection of your own is expressed in.

Client.set_method_factor(collection: str, method_id: str, flow_id: str, new_value: float, *, location: str | None = None, value: float | None = None) -> dict
Section titled “Client.set_method_factor(collection: str, method_id: str, flow_id: str, new_value: float, *, location: str | None = None, value: float | None = None) -> dict”

Change the value of one characterization factor of a collection of your own.

The factor is named by its category (method_id), its flow and its location (None for a factor written for no location). When several factors answer there, give value, the present value of the one to change; two identical factors cannot be changed one by one, only together through set_method_factors. A collection the configuration declares is refused: copy it with copy_method_collection first.

Returns {"line", "touched", "before", "after"}: the journal line recording the change, and the factor’s value before and after.

Client.set_method_factors(collection: str, match: FactorMatch, value: float) -> dict
Section titled “Client.set_method_factors(collection: str, match: FactorMatch, value: float) -> dict”

Set to value every factor match reaches, refused as scale_method_factors is.

Client.set_release(release: dict | None, db_name: str | None = None) -> dict | None
Section titled “Client.set_release(release: dict | None, db_name: str | None = None) -> dict | None”

Declare which published database an uploaded database is.

release is {"name": ..., "version": ..., "systemModel": ...}, the system model only when the publisher ships several (the setup’s systemModels lists those its activities state); None clears it. A package exported from a database that links to this one names it by this release. Returns the release now declared. Raises VoLCAError on an HTTP error: a 404 for an unknown database, a 409 for one the configuration file declares. Needs wire revision 48.

Client.set_score(collection: str, set_name: str, score: str, formula: str) -> dict
Section titled “Client.set_score(collection: str, set_name: str, score: str, formula: str) -> dict”

Add a score to a scoring set, or write its formula.

Client.set_scoring_formula(collection: str, set_name: str, variable: str, formula: str) -> dict
Section titled “Client.set_scoring_formula(collection: str, set_name: str, variable: str, formula: str) -> dict”

Write the formula of a computed variable, refused when it names nothing the set holds.

Client.set_scoring_set_multiplier(collection: str, name: str, multiplier: float | None) -> dict
Section titled “Client.set_scoring_set_multiplier(collection: str, name: str, multiplier: float | None) -> dict”

Set the multiplier a scoring set’s values are shown with, or drop it with None.

Client.set_scoring_set_unit(collection: str, name: str, unit: str) -> dict
Section titled “Client.set_scoring_set_unit(collection: str, name: str, unit: str) -> dict”

Change the unit a scoring set’s scores are expressed in.

Client.supply_missing_product(product: str, provider: str, *, supplier_activity: str | None = None, note: str | None = None, source: dict | None = None, db_name: str | None = None) -> dict
Section titled “Client.supply_missing_product(product: str, provider: str, *, supplier_activity: str | None = None, note: str | None = None, source: dict | None = None, db_name: str | None = None) -> dict”

Give a missing product a supplier wherever the database asks for it.

Every input that asks for product (naming supplier_activity, or no supplier activity when it is None) and that nothing answers moves to provider, keeping its amount, formula and comment: the SetSupplier edits edit_activities would make, one per activity, found by the engine. product and supplier_activity are the name and supplierActivity of a gap of get_gap_report::

client.supply_missing_product("barley", "a_b", note="Local mill")

One line the provider cannot supply refuses the whole change. Answers as edit_activities does. Needs wire revision 109.

source says where the figures come from, as {"document": ..., "page": 7, "passage": ...} (page and passage are optional): it is kept beside the reason. Needs wire revision 111.

Client.system_model(*, db_name: str | None = None) -> dict
Section titled “Client.system_model(*, db_name: str | None = None) -> dict”

The system model a child is divided by::

{"text": "name = ...",
"exceptions": [{"key": "wet mass", "reason": "...",
"processes": [{"activity": "...", "name": "..."}]}],
"substitutions": [{"coproduct": "...", "block": "...", "coproductName": "...",
"replaces": "...", "replacedProcess": "...",
"replacedProduct": "...", "ratio": 21.5, "reason": "..."}]}

text is the model’s file as written; each exception lists the processes of the parent it takes, read on the parent as now loaded. Each substitution names a coproduct the model does not divide, and the process of the parent it is credited against, ratio units of that process’s product per unit of the coproduct (wire revision 91; an older engine sends no substitutions). Refused on a database that is not a child, or whose parent is not loaded. Needs wire revision 85.

Client.terms_to_accept(db_name: str | None = None) -> list[dict]
Section titled “Client.terms_to_accept(db_name: str | None = None) -> list[dict]”

The terms of use to accept before reading a database.

Its own, and those of every database it depends on, when their publisher asks its readers to accept them: until then, the engine answers 403 to every request reading it. Each entry is {"database", "text", "fingerprint", "usage"}, once per text. usage is what the terms let the publisher see of the computations: None when nothing is counted, "anonymous" for counts alone, "organizations" for the counts with each reader’s organization and email domain. Empty when nothing is asked, and against an engine older than wire revision 78.

Client.undo_method_edit(collection: str, *, line: int | None = None) -> dict
Section titled “Client.undo_method_edit(collection: str, *, line: int | None = None) -> dict”

Undo a change, by writing its inverse as a new journal line.

Without line, undoes the latest change still in effect, so calling it again walks back one more, and never reaches what a copy took from its source’s configuration. With line, undoes that line whatever it is: naming an undo line redoes the change it undid. A selector is undone by restoring the values it replaced, which is refused, naming the factor, when a later line changed one of them.

Client.unit_table(name: str = 'Default units') -> dict[str, UnitDefinition]
Section titled “Client.unit_table(name: str = 'Default units') -> dict[str, UnitDefinition]”

A unit table read into a dict, keyed by each unit as the table writes it.

The columns are read by position (unit, measure, factor) after the header, as the engine reads them. The engine also reads a unit written in another case or spacing; this dict holds only the spellings the table lists. “Default units” is the built-in table, absent from an engine whose configuration names its own.

Client.unload_database(db_name: str) -> dict
Section titled “Client.unload_database(db_name: str) -> dict”

Unload a database from memory to free RAM. The disk copy is kept.

Refused if another loaded database still depends on it.

Client.unload_method_collection(name: str) -> dict
Section titled “Client.unload_method_collection(name: str) -> dict”

Unload a method collection from memory (the staged file is kept).

Client.unload_reference_data(kind: RefDataKind, name: str) -> dict
Section titled “Client.unload_reference_data(kind: RefDataKind, name: str) -> dict”

Unload a reference-data set of kind from memory.

Client.upload_database(source: str | Path | bytes, name: str, *, description: str | None = None) -> dict
Section titled “Client.upload_database(source: str | Path | bytes, name: str, *, description: str | None = None) -> dict”

Upload a database archive; stage it under a generated slug.

source is a path to a ZIP / CSV / XLSX archive (or its raw bytes); name is the display name. The engine auto-detects the format (EcoSpold 1/2, SimaPro CSV, ILCD, OpenLCA JSON-LD, Brightway Excel) and stages the database without loading it. A package (export_database with package="ro-crate") is read as one from wire revision 50: its export is checked against the digest it states and staged with its licence, and the releases it was built on become the requiredReleases of its setup.

Returns the UploadResponse dict ({"success", "message", "slug", "format"}); slug is the name every later call targets. Then inspect get_setup, wire missing dependencies with add_dependency, and call finalize_database to build matrices and load it.

Raises VoLCAError on any rejection (uploads disabled on the plan, size cap exceeded, unreadable archive).

Client.upload_method_collection(source: str | Path | bytes, name: str, *, description: str | None = None, flows_from: str | None = None) -> dict
Section titled “Client.upload_method_collection(source: str | Path | bytes, name: str, *, description: str | None = None, flows_from: str | None = None) -> dict”

Upload a method file as a staged method collection.

source is a path to the method archive (or its raw bytes). Same streamed-body + query-param shape as upload_database; returns the UploadResponse dict and raises VoLCAError on rejection.

A workbook of characterization factors, one per row (Method, Category, Indicator, Name, Compartment, Subcompartment, CF), becomes one collection per method family, listed under families; the factors left out are under dropped. Its flows take their units and CAS numbers from the EcoSpold 2 master data of an uploaded database: flows_from names it, and may be left out when only one database has master data (wire revision 101).

Client.upload_reference_data(kind: RefDataKind, source: str | Path | bytes, name: str, *, description: str | None = None) -> dict
Section titled “Client.upload_reference_data(kind: RefDataKind, source: str | Path | bytes, name: str, *, description: str | None = None) -> dict”

Upload a reference-data CSV of kind as a staged set.

source is a path to the CSV (or its raw bytes). Same streamed-body + query-param shape as upload_database.

The usage log after the cursor after, for whoever runs the engine.

An engine started with usage_log = true keeps one line per computation on a process of a database with a declared release. Returns {"boot", "lines", "more"}: each line carries seq, at, kind, database, process, heldAs (the activityName, productName and location the database gives the process, wire revision 54), reader and counted, the releases the computation is counted for, each with what its publisher sees; more says more lines wait after these. Raises VoLCAError with a 404 on an engine that keeps no log. Needs wire revision 53.

Return a new client targeting a different database.

Shares the underlying HTTP session, dispatch table, and any other Client-level state with the original; only db is overridden. New fields added to Client.__init__ propagate automatically (no manual mirror to keep in sync).

Lifecycle state of a database in the engine.

UNLOADED: declared in the engine config but not yet loaded. PARTIALLY_LINKED: loaded, but some cross-DB flow references could not be resolved against currently-loaded dependencies. LOADED: loaded and fully linked.

Inherits from str, so dataclasses.asdict(db)["status"] serialises as the bare wire string.

How a ClassificationFilter value is compared against the entry.

EXACT: case-insensitive equality. CONTAINS: case-insensitive substring. Inherits from str so json.dumps(MatchMode.EXACT) and dataclasses.asdict(filter)["mode"] both serialise as the bare string "exact" / "contains".

Manages the VoLCA server process.

Usage::

with Server(config="volca.toml") as srv:
client = Client(base_url=srv.base_url, db="agribalyse-3.2", password=srv.password)
activities = client.search_activities(name="at plant")

Or with no TOML of one’s own, the databases and methods named by path::

with Server(databases={"agb": "agribalyse.zip"}, methods={"EF 3.1": "ef31.zip"}) as srv:
client = Client(base_url=srv.base_url, db="agb")
client.load_database("agb")

Constructor: Server(config: str | None = 'volca.toml', port: Union[int, Literal['auto']] = 0, binary: str = 'volca', databases: collections.abc.Mapping[str, str | pathlib.Path] | None = None, methods: collections.abc.Mapping[str, str | pathlib.Path] | None = None)

http://localhost:<port>, pass to Client(base_url=…).

Always loopback: the managed server only listens locally.

Health check: GET /api/v1/db, return True if 200.

Server.start(idle_timeout: int = 1200, wait_timeout: int = 120) -> None
Section titled “Server.start(idle_timeout: int = 1200, wait_timeout: int = 120) -> None”

Spawn the engine process if it is not already serving, and wait until ready.

Args: idle_timeout: Seconds without use before the engine shuts itself down. Default 20 min: a script’s own work between two requests (reading a workbook, drawing its results) counts as idleness, and outlasted 5. An API request or a matrix solve counts as use; an MCP client merely staying connected does not. wait_timeout: How long to poll for the server to become healthy before raising TimeoutError.

No-op if a healthy server is already reachable on base_url.

Stop the server via shutdown endpoint, then terminate process.

Role a technosphere exchange plays within its host activity.

REFERENCE_PRODUCT: the activity’s reference output product. COPRODUCT: a product output the source left unallocated; an activity still carrying one is refused a score (see the unallocated check of the quality report). AVOIDED_PRODUCT: a substitution, the product the activity displaces; a credit on that product’s producer (wire revision 14). REFERENCE_INPUT: the reference input (in waste-treatment activities). INPUT: any other technosphere input.

What a waste line does within its activity.

TREATS_WASTE: an input, so this activity is the one treating it. SENT_TO_TREATMENT: an output whose treatment was found. FINAL_WASTE_FLOW: an output naming no treatment, so nothing treats it. TREATMENT_NOT_LOADED: an output naming a treatment no loaded database ships, so its burden is missing rather than accounted for.

The last two both arrive with no target, which is why the role is stated rather than worked out from the target fields.

Raised when the download or verification fails.

Error from the VoLCA API.

Constructor: VoLCAError(message: str, status_code: int | None = None, body: str = '')

One activity in a database: the row returned by /activities search.

process_id is the engine’s canonical address (activityUUID_productUUID) and is what you pass to every detail endpoint (Client.get_activity, Client.get_supply_chain, Client.get_impacts, …). activity_name is the activity name (e.g. "wheat flour, at plant"); product_name is the reference output product (e.g. "wheat flour"); product_amount and product_unit are what the source says this process produces (typically 1.0 of "kg" / "mj" / etc.; a database imported from SimaPro or Brightway Excel states it in the canonical unit of its dimension, so a 1 kWh reference product reads 3.6 of "mj", and a coproduct its block states at 0.0686462 kg reads that). It is not the basis a score or an inventory is reported against: those are always per one product_unit, whatever the amount here. location is the geography code ("FR", "GLO", "RoW"…). A process has no name of its own; compose a label from activity_name + product_name.

allocation_percent is this product’s share (0..100) of the parent activity’s exchanges in a multi-output (allocated) process, e.g. a cheese activity that also yields whey, cream and permeate gives each product its own share, summing to ~100. It is None for single-output processes. allocation_formula carries the raw symbolic formula when the source expressed the share as an expression rather than a number, else None.

mass_allocation_percent is the share the same product would carry if the key were its mass rather than what the source declared, so the two read side by side: the cheese above is declared 51.4 % of its block where its mass is 11.7 %, and a kilo of it therefore carries 4.4 times more under the declared key. It is None outside an activity’s own product list, when the block’s products are not all stated in a mass, and against an engine older than wire revision 15.

block names the source block the process came out of, as a value to compare and never to read: the coproducts of one block carry the same one and nothing else does, which is what lets a listing gather them. block_products is how many products that block holds, so a page showing fewer rows than that knows it is showing part of a block and not the whole of it. Both are None against an engine older than wire revision 21.

FieldTypeDefault
process_idstrrequired
activity_namestrrequired
locationstrrequired
product_namestrrequired
product_amountfloatrequired
product_unitstrrequired
allocation_percentfloat | NoneNone
allocation_formulastr | NoneNone
mass_allocation_percentfloat | NoneNone
blockstr | NoneNone
block_productsint | NoneNone

Two activities side by side, as Client.compare_activities returns them.

FieldTypeDefault
baseActivityrequired
otherActivityrequired
summarylist[SummaryChange]required
exchangeslist[ExchangeChange]required
uncomparedlist[UncomparedLine]required

True when nothing differs and every line could be judged.

One upstream activity’s contribution to an LCIA score.

Returned in ContributingActivities.activities. share_pct is the percentage of the total impact this activity contributes (0..100).

FieldTypeDefault
process_idstrrequired
activity_namestrrequired
product_namestrrequired
locationstrrequired
contributionfloatrequired
share_pctfloatrequired

Typed wrapper around the JSON returned by GET /activity/{pid}.

Use the .inputs / .outputs / .technosphere_inputs convenience properties instead of walking the raw exchanges list.

native_id is the identifier the source file gave the dataset block this process was read from - SimaPro’s Process identifier, the number an EcoSpold 1 dataset is published under - which is what a reader copies to find the dataset back in the file it came from. It is None where the format has none, where the format names a dataset by the UUID process_id already spells, and against an engine older than wire revision 22.

dates holds the days the dataset says it was created, last revised, or written without saying which (see DatasetDates).

parameters are the names its formulas read that the process defines itself, database_parameters those it reads from its database and does not define (wire revision 65; empty from an older engine, and when the licence keeps the amounts to itself).

FieldTypeDefault
process_idstrrequired
activity_namestrrequired
locationstrrequired
unitstrrequired
descriptionlist[str]required
classificationsdict[str, str]required
product_namestr | Nonerequired
product_amountfloat | Nonerequired
product_unitstr | Nonerequired
all_productslist[Activity]required
exchangeslist[Union[TechnosphereExchange, BiosphereExchange, WasteExchange]]required
native_idstr | NoneNone
datesDatasetDatesDatasetDates()
withheldWithheldExchanges | NoneNone
parameterslist[Parameter]list()
database_parameterslist[Parameter]list()

This process’s own allocation share (0..100), or None.

A multi-output process splits the parent activity’s burden across its co-products; every all_products entry carries its share. This returns the share of this process (the entry whose process_id matches), and None for single-output processes.

Every input exchange: technosphere inputs and biosphere resources.

Equivalent to filtering exchanges by e.is_input. Mixed kinds: callers needing only one variant should use technosphere_inputs or filter manually.

True iff the activity splits its burden across several co-products.

Reads the structured allocation_percent the engine sets on each all_products entry (authoritative), not the description text.

Every output exchange: products and biosphere emissions.

Includes the reference product, coproducts (in allocated activities), and all biosphere emissions.

Only the technosphere inputs (ingredients from other activities).

Excludes biosphere inputs (resource extractions) and waste outputs. The common case when answering “what does this activity consume from upstream?”.

An exchange named without its amount, as a database whose licence keeps its amounts lets it be read.

FieldTypeDefault
flow_namestrrequired
unit_namestrrequired
kindstrrequired
is_inputboolrequired
compartmentCompartment | NoneNone
target_activity_namestr | NoneNone
target_locationstr | NoneNone
target_process_idstr | NoneNone

The exchanges of an activity whose licence keeps their amounts, and why.

FieldTypeDefault
reasonstrrequired
lineslist[ExchangeName]required

A listed process of a supply chain that buys from a database whose licence keeps the amounts of its exchanges: its edges to that database are not listed, so part of its weight comes from there and not from the process itself (wire revision 47).

FieldTypeDefault
consumerstrrequired
databasestrrequired

A dependency whose licence keeps the amounts of its exchanges, in one line of a supply chain or an aggregation: how many of its processes are reached, and why they are not listed (wire revision 46).

FieldTypeDefault
databasestrrequired
processesintrequired
reasonstrrequired

A dependency whose licence keeps what weighs in its scores, in one line: its part of the score and why it is not detailed. The detailed rows and these lines add up to the score (wire revision 46).

FieldTypeDefault
databasestrrequired
contributionfloatrequired
share_pctfloatrequired
reasonstrrequired

A product input no loaded database supplies, which the result counted as zero: how much of it the chain asks per unit of the activity computed, and by how many of its processes (wire revision 58).

FieldTypeDefault
databasestrrequired
productstrrequired
supplierstr | Nonerequired
locationstrrequired
unitstrrequired
amountfloatrequired
consumersintrequired
reasonslist[dict]required

How many unsupplied inputs a result met inside a database whose licence keeps its detail to itself, the one asked included, counted without naming them (wire revision 58).

FieldTypeDefault
databasestrrequired
countintrequired

The days a dataset says it was written on, each under its format’s meaning.

created is when the dataset was first written (EcoSpold 1 and 2), last_revised when it was last changed (EcoSpold 2, ILCD). stated is a date the dataset gives without saying what it marks, which is what a SimaPro process’s Date is. Each is None where the dataset states none, and all three against an engine older than wire revision 35.

FieldTypeDefault
createddatetime.date | NoneNone
last_reviseddatetime.date | NoneNone
stateddatetime.date | NoneNone

What one line of an activity adds to one of its scores.

position is the line’s position among the activity’s exchanges, the position of the exchange Client.get_activity lists, so lines can be grouped into stages (ingredients, transport, packaging) by whatever the caller knows of them. share_pct is negative for a line that lowers the score.

FieldTypeDefault
positionintrequired
contributionfloatrequired
share_pctfloatrequired

A flow a score read no factor for, although its method writes the same substance elsewhere in the flow’s medium.

A flow reads the factor of its own subcompartment, of its whole medium, or of the one an if_absent row of the compartment table sends it to, and a resource then the line its name has at unspecified. Ammonia emitted indoors scores nothing under a method that writes ammonia only for urban and non-urban air, and that collection writes nothing for indoor air. up_to is what the flow would add to the score at the largest of the factors in written_at, in the score’s unit.

FieldTypeDefault
flow_idstrrequired
flow_namestrrequired
categorystrrequired
compartmentstr | Nonerequired
quantityfloatrequired
unitstrrequired
written_atlist[str]required
factorfloatrequired
up_tofloatrequired
up_to_share_pctfloatrequired

The flows a score probably missed: the ten biggest able to move it by a thousandth or more (all of them beside a zero score), and how many more. withheld says why none is shown, when a database the score reads keeps the amounts of its exchanges to itself.

FieldTypeDefault
shownlist[ProbableMiss]list()
moreint0
withheldlist[str]list()

What a score rests on (wire revision 99): the engine’s version and commit, each database read (the one asked first), the method collection, and the substitutions and parameter values the request sent. Two scores compare only on the same basis.

FieldTypeDefault
enginestrrequired
databaseslist[BasisDatabase]required
methodsBasisMethodsrequired
substitutionslist['Substitution']list()
parameter_setslist[list['ParameterValue']]list()

One database a score read, and how its data differ from its release.

release is the published database it is, its source’s for a copy, in the shape Client.set_release takes; None when none is declared. reads_files_of names the database whose files it reads, when that is another one. edited when its history holds a change, a child divided from an edited parent included; reallocated when its multi-output processes are divided otherwise than the original’s; patched when its configuration patches exchanges as it loads.

FieldTypeDefault
namestrrequired
releasedict | Nonerequired
reads_files_ofstr | Nonerequired
editedboolrequired
reallocatedboolrequired
patchedboolrequired

The method collection a score read: copy_of names the collection it was first copied from, and modified says whether its factors or categories differ from its files.

FieldTypeDefault
collectionstrrequired
copy_ofstr | Nonerequired
modifiedboolrequired

What makes an exchange’s amount follow the dataset’s parameters.

text is the formula in VoLCA’s language; name is the name other formulas read the amount by, when the source gives one (wire revision 64).

FieldTypeDefault
textstrrequired
namestr | NoneNone

Two activities the cascade paired, one from each database, and the rung that paired them.

matched_on reads as in ChangedActivity.

FieldTypeDefault
matched_onstrrequired
baseActivityrequired
otherActivityrequired

A name a dataset’s formulas read.

An input parameter has a value and, when the source gives one, an uncertainty; a calculated one has a formula in VoLCA’s language and the value it gives at the dataset’s defaults, None when it gives none. unit is as the source spells it (wire revision 65).

FieldTypeDefault
namestrrequired
valuefloat | Nonerequired
formulastr | NoneNone
unitstr | NoneNone
descriptionstr”
uncertaintyUncertainty | NoneNone

How an input parameter may vary: the distribution and its own numbers.

lognormal gives geometric_mean and geometric_sd (a draw is the geometric mean times the geometric standard deviation raised to a standard normal draw), normal gives mean and sd, triangular gives minimum, mode and maximum, uniform gives minimum and maximum. The numbers a distribution does not use are None.

FieldTypeDefault
distributionstrrequired
geometric_meanfloat | NoneNone
geometric_sdfloat | NoneNone
meanfloat | NoneNone
sdfloat | NoneNone
minimumfloat | NoneNone
modefloat | NoneNone
maximumfloat | NoneNone

Result of compare_activities.

FieldTypeDefault
scopestrrequired
group_bystrrequired
matchedlist[ActivityDiffRow]list()
left_onlylist[ActivityDiffRow]list()
right_onlylist[ActivityDiffRow]list()

An activity as you write it: the body of Client.create_activities.

The inventory is three lists rather than one, so a field that means something on a supplier link cannot be sent on an emission.

You do not choose the process_id. The engine mints it from the name, the location, and the product name and unit, which is what makes writing the same activity twice a correction of one row rather than two. One reference product per activity: coproducts and allocation are not supported yet, and this type does not pretend they are.

FieldTypeDefault
namestrrequired
locationstrrequired
product_namestrrequired
product_amountfloatrequired
product_unitstrrequired
descriptionlist[str]list()
inputslist[TechInput]list()
biospherelist[BioExchange]list()
waste_outputslist[WasteOutput]list()

One matched or unmatched flow in an activity comparison.

FieldTypeDefault
keystrrequired
leftfloat | Nonerequired
rightfloat | Nonerequired
unitstr | Nonerequired

right - left (0 if one side is missing).

One bucket inside an AggregateResult.

FieldTypeDefault
keystrrequired
quantityfloatrequired
countintrequired
unitstr | NoneNone
sharefloat | NoneNone

Result of a Client.aggregate() call.

filtered_total is the sum across all items matching the filters (the top-level number). groups is the per-bucket breakdown when group_by was set; empty otherwise.

FieldTypeDefault
scopeAggregateScoperequired
filtered_totalfloatrequired
filtered_unitstr | Nonerequired
filtered_countintrequired
groupslist[AggregateGroup]list()
withheld_databaseslist[WithheldProcesses]list()
cutoff_inputslist[CutoffInput]list()
withheld_cutoffslist[WithheldCutoffs]list()

Activities one key of a rung names on either side, too many to pair.

FieldTypeDefault
matched_onstrrequired
baselist[Activity]required
otherlist[Activity]required

Result of Client.score_activities scoring many processes at once.

results carries one ScoredActivity per process the engine computed; not_found and invalid list the process ids it could not resolve, and unscorable those that resolve but name an activity the engine refuses to score (its quality report’s unallocated check says why; wire revision 14, empty from an older engine). unsolvable lists those the solver has no answer for, each with why (wire revision 112, empty from an older engine, which refused the whole batch instead). A non-empty list is a partial result to inspect, not a failure.

FieldTypeDefault
resultslist[ScoredActivity]required
not_foundlist[str]required
invalidlist[str]required
unscorablelist[str]required
unsolvablelist[UnsolvableActivity]list()
basisScoreBasis | NoneNone
reading_noticestr | NoneNone

A process of a batch that resolves but has no answer, and why.

Its supply chain reaches a process the solver cannot answer for (for instance two processes that each take all of what the other makes), or its demand cannot be put to a database it reaches. parameter_set is the position of the set it has no answer at, when the batch gave sets: values change the matrix, so a process may have an answer at one set and none at another.

FieldTypeDefault
process_idstrrequired
reasonstrrequired
parameter_setint | NoneNone

One resource taken from the environment, or one emission released into it.

Name the flow one way or the other, never both: flow is the identifier of a flow the database already has, which Client.search_flows and BiosphereExchange.flow_id both return, while name with compartment and unit names one in words. Use the two constructors rather than the fields, from_id and from_name, which is why passing both or neither raises here instead of at the server.

A biosphere amount is never converted, so an exchange states its amount in the flow’s own unit.

FieldTypeDefault
directionBioDirectionrequired
amountfloatrequired
flowstr | NoneNone
namestr | NoneNone
compartmentstr | NoneNone
sub_compartmentstr | NoneNone
unitstr | NoneNone
commentstr | NoneNone
BioExchange.existing(flow: str, direction: BioDirection | str, amount: float, *, unit: str | None = None, comment: str | None = None) -> BioExchange
Section titled “BioExchange.existing(flow: str, direction: BioDirection | str, amount: float, *, unit: str | None = None, comment: str | None = None) -> BioExchange”

Retired name of from_id. Still works, and says so.

BioExchange.from_id(flow: str, direction: BioDirection | str, amount: float, *, unit: str | None = None, comment: str | None = None) -> BioExchange
Section titled “BioExchange.from_id(flow: str, direction: BioDirection | str, amount: float, *, unit: str | None = None, comment: str | None = None) -> BioExchange”

An exchange on a flow the database already declares, by its identifier.

Client.search_flows is where identifiers come from.

BioExchange.from_name(name: str, compartment: str, direction: BioDirection | str, amount: float, unit: str, *, sub_compartment: str | None = None, comment: str | None = None) -> BioExchange
Section titled “BioExchange.from_name(name: str, compartment: str, direction: BioDirection | str, amount: float, unit: str, *, sub_compartment: str | None = None, comment: str | None = None) -> BioExchange”

An exchange on the flow this name, compartment and unit address.

That is the flow the database already declares under them when it has one, which is what keeps an exchange written from an inventory pointing at the curated flow rather than at a twin of it. sub_compartment is part of the address, not a decoration: a flow recorded in water/river is reached with sub_compartment="river" and not by water alone.

A name nothing answers to brings a flow into the database, and since no characterization factor matches a brand-new flow by identity, the engine returns a warning alongside the write rather than refusing it. A name several flows answer to in the unit stated is refused, listing their identifiers, so the exchange can name the one it means; two flows of one name in two units are told apart by the unit itself.

BioExchange.introducing(name: str, compartment: str, direction: BioDirection | str, amount: float, unit: str, *, sub_compartment: str | None = None, comment: str | None = None) -> BioExchange
Section titled “BioExchange.introducing(name: str, compartment: str, direction: BioDirection | str, amount: float, unit: str, *, sub_compartment: str | None = None, comment: str | None = None) -> BioExchange”

Retired name of from_name. Still works, and says so.

It was named for what it did when a name reached nothing: bring the flow into the database. It now reaches the flow the database already declares under that name, and only introduces one when nothing does.

An exchange with the environment (resource extraction or emission).

flow_id is what a line writes back when its words cannot address the flow on their own: a name several flows answer to, or one whose source recorded no compartment. Everything else restates as BioExchange.from_name takes it.

FieldTypeDefault
flow_namestrrequired
compartmentCompartment | Nonerequired
amountfloatrequired
unitstrrequired
directionBioDirectionrequired
flow_idstrrequired
commentstr | NoneNone
formulaExchangeFormula | NoneNone
positionint | NoneNone
selectorExchangeSelector | NoneNone
is_biosphereboolTrue
is_wasteboolFalse

True for resource extractions (direction is RESOURCE).

Biosphere inputs are resource extractions; outputs are emissions to the environment.

Always False: biosphere exchanges cannot be reference flows.

The reference flow defines the functional unit and is always a technosphere product (see TechnosphereExchange.is_reference).

A pair of activities that differ, and the rung of the cascade that paired them.

matched_on is "SameProcessId", "SameNames" (the same activity and product names, case and a trailing geography aside, at the same location), "SameProduct" (the same reference product at the same location, from the same kind of activity) or "SameCutNames" (the same names cut at 80 characters with their geography, as SimaPro cuts them, for a name longer than that).

FieldTypeDefault
matched_onstrrequired
comparisonActivityComparisonrequired

One characterization factor matched against a database biosphere flow.

Returned in the factors list of CharacterizationResult. match_strategy records how the CF was matched to the DB flow ("uuid", "cas", "name", "pattern", "synonym", "proxy").

FieldTypeDefault
method_flow_namestrrequired
cf_valuefloatrequired
cf_unitstrrequired
directionstrrequired
db_flow_namestrrequired
flow_idstrrequired
flow_unitstrrequired
categorystrrequired
match_strategystrrequired
compartmentstr | NoneNone

Result of Client.get_characterization.

The engine truncates factors to shown rows (server-side limit). matches is the unfiltered total: use has_more to detect when the slice is incomplete.

FieldTypeDefault
methodstrrequired
unitstrrequired
matchesintrequired
shownintrequired
factorslist[CharacterizationFactor]list()

True when the server truncated below matches.

Filter a supply-chain/consumers query by a classification (system, value, mode).

Matches one classification system entry, e.g. ClassificationFilter("Category", "Agricultural\\Food", "exact") or ClassificationFilter("Category", "Agricultural\\Food", MatchMode.EXACT). Multiple filters are AND-combined by the server.

FieldTypeDefault
systemstrrequired
valuestrrequired
modeMatchMode<MatchMode.CONTAINS: ‘contains’>

One classification system declared by a database.

values are the distinct entries in this system; activity_count is how many activities carry at least one classification under this system (helps callers pick a worthwhile filter dimension).

FieldTypeDefault
namestrrequired
valueslist[str]list()
activity_countint0

Biosphere compartment (medium + optional subcompartment).

Frozen so it’s hashable and immutable, so callers can use it as a dict key when grouping flows by compartment, and accidental mutation is rejected.

FieldTypeDefault
namestrrequired
substr | NoneNone

A row of a unit table: the measure a unit belongs to, as the table spells it ("mass", "volume"), and how many of that measure’s base unit it holds (g is 0.001 of mass). The engine also reads a measure written as a product of base measures (volume is length^3), so two spellings can name one measure.

FieldTypeDefault
dimensionstrrequired
factorfloatrequired

Activity that consumes a given supplier, with BFS depth.

FieldTypeDefault
process_idstrrequired
activity_namestrrequired
locationstrrequired
product_namestrrequired
product_amountfloatrequired
product_unitstrrequired
depthintrequired
classificationsdict[str, str]dict()

Reverse supply chain (/consumers): paginated consumer list plus optional edge set. Mirrors SupplyChain so callers have a uniform {entries, edges} shape in both traversal directions.

consumers is a SearchResults[ConsumerResult]: iterate it to walk every consumer across all pages. edges is populated only when include_edges=True.

FieldTypeDefault
consumersSearchResults[ConsumerResult]required
edgeslist[SupplyChainEdge]list()
ConsumersResponse.from_json(d: dict, *, fetch: Optional[Callable[[int, int | None], dict]] = None) -> ConsumersResponse
Section titled “ConsumersResponse.from_json(d: dict, *, fetch: Optional[Callable[[int, int | None], dict]] = None) -> ConsumersResponse”

Parse the /consumers wire envelope.

fetch is a page fetcher returning the inner results envelope for (offset, limit), used by SearchResults for lazy iteration. The client wires this so users get pagination for free; callers building ConsumersResponse manually (e.g. tests) can omit it and the resulting SearchResults is “detached” (one page only).

Top upstream activities driving an LCIA score.

Same engine-side limitation as ContributingFlows: the server reports no total, so pyvolca cannot derive has_more. Pass a generous limit and inspect share_pct if exhaustive coverage matters.

FieldTypeDefault
methodstrrequired
unitstrrequired
total_scorefloatrequired
activitieslist[ActivityContribution]list()
withheld_databaseslist[WithheldShare]list()
cutoff_inputslist[CutoffInput]list()
withheld_cutoffslist[WithheldCutoffs]list()
basisScoreBasis | NoneNone

Top elementary flows driving an LCIA score.

Note: the engine does not report a total: top_flows is whatever the server returned under limit, but pyvolca cannot tell whether more flows were truncated. If you need exhaustive coverage, pass a generous limit and inspect share_pct totals.

FieldTypeDefault
methodstrrequired
unitstrrequired
total_scorefloatrequired
top_flowslist[FlowContribution]list()
withheld_databaseslist[WithheldShare]list()
cutoff_inputslist[CutoffInput]list()
withheld_cutoffslist[WithheldCutoffs]list()
basisScoreBasis | NoneNone

Two databases side by side, as Client.compare_databases returns them.

The *_count fields always cover the full lists, which a limit may have truncated. A pair whose only difference is the dates its datasets state is in redated, not changed; a pair that says the same thing on both sides is in unchanged, which is None against an engine older than wire revision 86.

FieldTypeDefault
added_countintrequired
removed_countintrequired
changed_countintrequired
redated_countintrequired
ambiguous_countintrequired
unchanged_countintrequired
addedlist[Activity]required
removedlist[Activity]required
changedlist[ChangedActivity]required
redatedlist[ChangedActivity]required
ambiguouslist[AmbiguousActivities]required
unchangedlist[PairedActivities] | Nonerequired

Every pair the cascade made, changed, redated or not.

Raises ValueError when a list is incomplete, so missing pairs never pass for the whole pairing: an engine older than wire revision 86, or a comparison asked for with a limit smaller than a list.

One entry of Client.list_databases.

depends_on names the databases this one links against for cross-DB flow resolution, mirroring the dependsOn list surfaced by the relink endpoint. Derived from the engine’s declared topology, not runtime state.

allocation is the key its multi-output blocks were divided by: "declared" for the shares the source itself states, otherwise the name of the property recomputed them ("dry mass", "wet mass", "price"), or "none" for blocks kept whole. A child divided by a system model reports its model’s default property; its exceptions are in Client.system_model. Without it a column of shares cannot say which of the two it is showing. source names the database this one was derived from, and is None for one read straight from its files. Both are None against an engine older than wire revision 20.

licence is what it is served under, its source’s for a copy, the shape Client.set_licence returns. None against an engine older than wire revision 41, which refused no download.

release is which published database it is, as its owner declared it: {"name", "version", "systemModel"}, the shape Client.set_release takes. None when none is declared, and against an engine older than wire revision 48.

modification says how its data differ from the files it reads: {"edited": bool, "reallocated": bool}, edited when its history (Client.database_history) holds a change, reallocated when its multi-output processes are divided otherwise than the original’s. None against an engine older than wire revision 79.

added is the moment the engine made it, in UTC to the second ("2026-10-28T13:30:59Z"), so that sorting the texts sorts by time. None for a database the configuration declares and for one made before the engine kept the moment, which is not guessed from the age of a file, and against an engine older than wire revision 90.

FieldTypeDefault
namestrrequired
display_namestrrequired
statusDatabaseStatusrequired
pathstrrequired
load_at_startupboolFalse
is_uploadedboolFalse
activity_countint0
descriptionstr | NoneNone
formatstr | NoneNone
depends_onlist[str]list()
allocationstr | NoneNone
sourcestr | NoneNone
licencedict | NoneNone
releasedict | NoneNone
modificationdict | NoneNone
addedstr | NoneNone

Whether its data differ from the files it reads.

One line two activities disagree on.

kind is "technosphere", "biosphere" or "waste", and role what the line does within it: a TechRole value, a BioDirection value, or "WasteInput" / "WasteOutput". The role is part of a line, so a flow moving from input to coproduct is one line removed and one added.

change is "added", "removed", "changed" or "supplier". before is None on an added line and after on a removed one. On "supplier" they are None, and supplier_before and supplier_after name the activity the one line of the flow comes from on each side. A flow drawn from several suppliers compares its total only. matched_on says how a changed line was found in the other activity: "SameFlow" (the same flow id) or "SameFlowName" (the same name, compartment and role under another id). The flow is named as the base activity has it, or as the other activity has it when the line was added.

FieldTypeDefault
flow_idstrrequired
flow_namestrrequired
compartmentCompartment | Nonerequired
kindstrrequired
rolestrrequired
changestrrequired
beforeQuantity | Nonerequired
afterQuantity | Nonerequired
matched_onstr | NoneNone
supplier_beforeSupplier | NoneNone
supplier_afterSupplier | NoneNone

Which lines of an inventory an edit is about.

kind is "input", "waste" or "biosphere". The first two name their provider by process id, or, for a line that names no provider, its flow and the location it states ("" for none; None reaches every location); the third names its flow by identity. There is no kind for the reference product or a coproduct: changing those changes what the activity is, which is not what an inventory edit does.

Each line of Client.get_activity carries the selector that reaches it as selector (wire revision 76), which is the one to send.

A selector may name several lines, and then it applies to all of them; Client.edit_exchanges reports how many. Naming none is refused by the engine rather than passed off as done.

FieldTypeDefault
kindstrrequired
providerstr | NoneNone
flowstr | NoneNone
locationstr | NoneNone

True for an input or a waste output named by its flow (wire revision 76).

ExchangeSelector.biosphere_flow(flow: str) -> ExchangeSelector
Section titled “ExchangeSelector.biosphere_flow(flow: str) -> ExchangeSelector”

A biosphere exchange, by flow id.

ExchangeSelector.input_from(provider: str) -> ExchangeSelector
Section titled “ExchangeSelector.input_from(provider: str) -> ExchangeSelector”

A technosphere input, by the process id of what supplies it.

ExchangeSelector.input_of_flow(flow: str, location: str | None = None) -> ExchangeSelector
Section titled “ExchangeSelector.input_of_flow(flow: str, location: str | None = None) -> ExchangeSelector”

A technosphere input naming no provider, by its flow and location.

ExchangeSelector.waste_of_flow(flow: str, location: str | None = None) -> ExchangeSelector
Section titled “ExchangeSelector.waste_of_flow(flow: str, location: str | None = None) -> ExchangeSelector”

A waste output naming no treatment, by its flow and location.

ExchangeSelector.waste_to(provider: str) -> ExchangeSelector
Section titled “ExchangeSelector.waste_to(provider: str) -> ExchangeSelector”

A waste output, by the process id of the treatment it goes to.

Result of Client.explain_cf.

explanation is written by the engine: show it as it is rather than rewording the codes. The structured fields are for comparing, filtering or linking. outcome is "characterized", "conversion_refused" (a factor was found but the flow’s unit cannot be converted to its basis, so the flow scores nothing) or "no_factor". method_id is the UUID to ask about this method again; None against an engine older than wire revision 55.

FieldTypeDefault
methodstrrequired
method_unitstrrequired
flowExplainedFlowrequired
outcomestrrequired
explanationlist[str]list()
matchExplainedMatch | NoneNone
steps_triedlist[ExplainedStep]list()
regional_factor_countint0
method_idstr | NoneNone

What one loaded method collection makes of one flow, in a FlowFactors.

factors explains, as Client.explain_cf does, each method whose factors reach the flow, applied or refused, or that charges it by the location of the emitting activity. no_factor only names the methods that give it no factor at all.

FieldTypeDefault
collectionstrrequired
factorslist[ExplainCFResult]list()
no_factorlist[Method]list()

Result of Client.get_flow_factors: every factor the loaded collections give one flow (wire revision 55). A large emission no method characterizes adds nothing to any score; this is where that shows.

FieldTypeDefault
flowExplainedFlowrequired
collectionslist[CollectionFactors]list()

The characterization factors a selector reaches, as a configuration’s [[methods.patches]] match writes them.

Every field given must hold: category and flow_name exactly, flow_name_prefix as a prefix, cas as a CAS number whichever way it is padded, subcompartment_contains as a substring of the subcompartment, case aside. A selector naming nothing would reach every factor, which is almost certainly a mistake, so it is refused.

FieldTypeDefault
categorystr | NoneNone
flow_namestr | NoneNone
flow_name_prefixstr | NoneNone
casstr | NoneNone
subcompartment_containsstr | NoneNone

The flow an explanation is about, as the cascade sees it.

FieldTypeDefault
idstrrequired
namestrrequired
unitstrrequired
categorystrrequired
compartmentstr | NoneNone
casstr | NoneNone

The factor that was served, and where it came from.

FieldTypeDefault
rungstrrequired
cf_valuefloatrequired
cf_unitstrrequired
method_flow_namestrrequired
match_strategystrrequired
method_casstr | NoneNone
unit_conversionstr | NoneNone
refusalstr | NoneNone

One rung of the factor-matching cascade, and what it made of the flow.

FieldTypeDefault
rungstrrequired
resultstrrequired
vetostr | NoneNone

One flow as returned by /flows.

Mirrors the server’s FlowSearchResult. kind says which of the three a flow is: "technosphere" for a product one activity makes and another consumes, "biosphere" for a substance exchanged with nature, "waste" for a waste. It is None against an engine older than wire revision 9, which did not report it.

category is the medium alone (“air”, “water”, “soil”, “natural resource”) and compartment the sub-compartment (“agricultural”), which is often all that tells two same-named flows apart. Only a biosphere flow has either: that is where “taken from nature” and “released to nature” are told apart. synonyms maps language code → list of synonym strings (empty when the database carries no synonym index).

producer_count is how many activities make this flow, which is the number of ways a database offers to produce it. It is None on a flow no activity can produce (biosphere, waste) and against an engine older than wire revision 16; a zero would be the different statement that nothing makes it.

FieldTypeDefault
idstrrequired
namestrrequired
categorystrrequired
unit_namestrrequired
kindstr | NoneNone
compartmentstr | NoneNone
synonymsdict[str, list[str]]dict()
producer_countint | NoneNone

Top contributing elementary flow for an impact category.

Emitted inside LCIAResult.top_contributors.

FieldTypeDefault
flow_namestrrequired
contributionfloatrequired
share_pctfloatrequired
flow_idstrrequired
categorystrrequired
cf_valuefloat0.0
compartmentstr | NoneNone
match_kindstr | NoneNone

Detail of one flow, returned by Client.get_flow.

flow is the raw flow record: a tagged union (technosphere product, biosphere flow, waste flow, or unresolved) whose shape depends on its kind, kept as a dict rather than forced into one dataclass. usage_count is how many exchanges reference it.

FieldTypeDefault
flowdictrequired
unit_namestrrequired
usage_countintrequired

CF-coverage report for one method against the current database.

matched_flows / total_flows is the coverage ratio: how many of the database’s biosphere flows have a CF in this method. Mirrors the engine response of Client.get_flow_mapping.

FieldTypeDefault
method_namestrrequired
method_unitstrrequired
total_flowsintrequired
matched_flowsintrequired
flowslist[FlowMappingEntry]list()

Matched fraction expressed as 0..100. Returns 0 when total is 0.

One DB biosphere flow and the CF (if any) assigned to it.

cf_value is None when this DB flow has no characterization factor in the method: that flow contributes 0 to the score for the method. match_strategy records how the mapping was resolved ("uuid", "cas", "name", "pattern", "synonym", "proxy").

FieldTypeDefault
flow_idstrrequired
flow_namestrrequired
flow_categorystrrequired
cf_valuefloat | NoneNone
cf_flow_namestr | NoneNone
match_strategystr | NoneNone

Result of download.

FieldTypeDefault
binaryPathrequired
data_dirPathrequired
versionstrrequired
data_versionstrrequired

One row of an inventory: a biosphere flow scaled to the functional unit.

is_emission distinguishes outputs (releases) from inputs (resource extraction). flow_id is the database UUID; compartment is the medium label (e.g. "air/urban air") when the source dataset declared one. category is the engine-normalised category used for grouping.

FieldTypeDefault
flow_idstrrequired
flow_namestrrequired
quantityfloatrequired
unit_namestrrequired
is_emissionboolrequired
categorystrrequired
compartmentstr | NoneNone

Life-cycle inventory of an activity: cumulative biosphere flows.

Returned by Client.get_inventory. flows is the full inventory, or the flows flow= and limit= kept when given. statistics carries the per-direction roll-ups and the most-populated categories, over the full inventory.

root is the activity the inventory was computed for. total_flows, emission_flows, resource_flows mirror the engine’s metadata block.

FieldTypeDefault
rootActivityrequired
total_flowsintrequired
emission_flowsintrequired
resource_flowsintrequired
flowslist[InventoryFlow]required
statisticsInventoryStatisticsrequired
matched_flowsint0
cutoff_inputslist[CutoffInput]list()
withheld_cutoffslist[WithheldCutoffs]list()

Roll-up totals of an inventory result.

emission_quantity and resource_quantity are sums by direction; total_quantity is the sum of absolute values. top_categories lists (category_name, flow_count) pairs ordered by frequency.

FieldTypeDefault
total_quantityfloatrequired
emission_quantityfloatrequired
resource_quantityfloatrequired
top_categorieslist[tuple[str, int]]list()

Batch LCIA: every impact category in a method collection, for one activity.

Returned by Client.get_impacts_batch. Carries the per-method impact results plus any formula-based scoring sets configured in the engine TOML (PEF, ECS, or any named set).

scoring_indicators gives the per-variable normalized-weighted breakdown of each scoring set, already multiplied by the set’s displayMultiplier and expressed in its display unit (see ScoringIndicator). Lets callers render per-indicator charts alongside the aggregate scoring_results. scoring_rows gives the same for every row of each set as Client.scoring_sets reads it, a row no score reads among them, its category the row’s label.

FieldTypeDefault
resultslist[LCIAResult]required
single_scorefloat | NoneNone
single_score_unitstr | NoneNone
norm_weight_set_namestr | NoneNone
available_nw_setslist[str]list()
scoring_resultsdict[str, dict[str, float]]dict()
scoring_unitsdict[str, str]dict()
scoring_indicatorsdict[str, dict[str, ScoringIndicator]]dict()
scoring_rowsdict[str, dict[str, ScoringIndicator]]dict()
withheldlist[str]list()
cutoff_inputslist[CutoffInput]list()
withheld_cutoffslist[WithheldCutoffs]list()
basisScoreBasis | NoneNone

LCIA score for one impact category on one activity.

Returned directly by Client.get_impacts, and nested inside LCIABatchResult.results (one entry per impact category).

functional_unit is the basis score is reported against, and it is always one unit of the reference product ("1.00 kg of cream") however much of it the source says the process produces.

FieldTypeDefault
method_idstrrequired
method_namestrrequired
categorystrrequired
damage_categorystrrequired
scorefloatrequired
unitstrrequired
mapped_flowsintrequired
functional_unitstrrequired
normalized_scorefloat | NoneNone
weighted_scorefloat | NoneNone
top_contributorslist[FlowContribution]list()
withheldstr | NoneNone
withheld_databaseslist[WithheldShare]list()
cutoff_inputslist[CutoffInput]list()
withheld_cutoffslist[WithheldCutoffs]list()
exchange_contributionslist[ExchangeContribution]list()
probable_missesProbableMisses | NoneNone
basisScoreBasis | NoneNone

How a method’s factors map onto a database’s biosphere flows.

Returned by Client.get_mapping_status. The mapped_by_* counts break the match cascade down by stage (UUID, then CAS, then name, then synonym); coverage is the matched percentage (0–100), and unmapped_flows lists the factors still without a database flow.

Parsed by hand rather than via the snake-case mixin because the acronym runs (mappedByUUID, mappedByCAS, dbBiosphereCount) do not survive the generic camelCase→snake_case conversion.

FieldTypeDefault
method_idstrrequired
method_namestrrequired
total_factorsintrequired
mapped_by_uuidintrequired
mapped_by_casintrequired
mapped_by_nameintrequired
mapped_by_synonymintrequired
unmappedintrequired
coveragefloatrequired
db_biosphere_countintrequired
unique_db_flows_matchedintrequired
unmapped_flowslist[UnmappedFlow]required

One LCIA method, returned by Client.list_methods.

Pass id (or name, which the client resolves against the loaded methods) wherever a method_id is asked for. collection is the parent method collection (e.g. "ef-31"); the client reads it off the resolved method, so it is worth passing to Client.get_impacts / Client.get_impacts_batch only to pin one of several loaded.

FieldTypeDefault
idstrrequired
namestrrequired
categorystrrequired
unitstrrequired
factor_countintrequired
collectionstrrequired

Detail of one LCIA method, returned by Client.get_method.

factor_count is the number of characterization factors; methodology and description are free-text metadata the source may or may not carry.

FieldTypeDefault
idstrrequired
namestrrequired
unitstrrequired
categorystrrequired
factor_countintrequired
descriptionstr | NoneNone
methodologystr | NoneNone

A factor’s medium after the compartment table, and its location, read the way Client.compare_method_collections and Client.profile_method_collection read them. Either is None when the factor states none.

FieldTypeDefault
mediumstr | NoneNone
locationReadLocation | NoneNone

One characterization factor of a method (Client.get_method_factors).

direction is the flow direction the factor applies to; value is the factor in the method’s unit per the flow’s unit. A method routinely holds several factors sharing one flow_name (the same substance emitted to air vs. water, or one regionalized factor per location), so compartment, location and unit are what tell them apart. Each is None when the source method does not carry that axis, or when the engine predates these fields.

FieldTypeDefault
flow_refstrrequired
flow_namestrrequired
directionstrrequired
valuefloatrequired
unitstr | NoneNone
compartmentstr | NoneNone
locationstr | NoneNone
readingFactorReading | NoneNone

A characterization factor written whole, to add to a category.

direction is "Input" (a resource) or "Output" (an emission); compartment is (medium, subcompartment, qualifier), empty strings for the parts a factor leaves open. Client.search_method_flows gives the flow id and compartment of a flow the collection already characterizes.

FieldTypeDefault
flow_idstrrequired
namestrrequired
directionstrrequired
valuefloatrequired
unitstrrequired
compartmenttuple[str, str, str] | NoneNone
casstr | NoneNone
locationstr | NoneNone

A row of a scoring set: the categories it groups, each by its method_id times a coefficient, under a label, with a normalization (a divisor) and a weight.

A row with a weight joins the score that adds up the rows. A row groups at least one category.

FieldTypeDefault
labelstrrequired
termsdict[str, float]required
normalizationfloat | NoneNone
weightfloat | NoneNone
unitstr | NoneNone

A factor’s location, and where it was read: "InField" when the file writes it in its location field, "InName" when at the end of the name (Ammonia, FR).

FieldTypeDefault
codestrrequired
from_strrequired

Shortest upstream path from a root process to a matching activity.

FieldTypeDefault
pathlist[PathStep]required
path_lengthintrequired
total_ratiofloatrequired

One step in the supply chain path returned by get_path_to.

Note: the /path endpoint is hand-built (aeson object [...]) but now emits camelCase keys (processId, activityName, cumulativeQuantity, …) like the rest of the API.

FieldTypeDefault
process_idstrrequired
activity_namestrrequired
locationstrrequired
unitstrrequired
cumulative_quantityfloatrequired
scaling_factorfloatrequired
local_step_ratiofloat | NoneNone

One perturbation outcome from Client.compute_sensitivity.

The engine flattens an Either on the wire: a success carries impact and delta_impact (with error None), a failure carries error (with the other two None). perturbation echoes the request entry (including its label if one was supplied), so results correlate without an out-of-band index.

FieldTypeDefault
perturbationdictrequired
impactLCIAResult | Nonerequired
delta_impactfloat | Nonerequired
errorstr | Nonerequired

A named classification preset declared in the engine config.

Apply by passing preset=preset.name to filtering endpoints (the engine expands it server-side into the filters triples).

FieldTypeDefault
namestrrequired
labelstrrequired
descriptionstr | Nonerequired
filterslist[PresetFilter]list()

One filter triple inside a Preset.

FieldTypeDefault
systemstrrequired
valuestrrequired
modeMatchMode<MatchMode.CONTAINS: ‘contains’>

The lines of one flow in one unit, as one side writes them, summed.

FieldTypeDefault
amountfloatrequired
unitstrrequired

The activity an input comes from, or a waste goes to, by name and location.

FieldTypeDefault
activity_namestrrequired
locationstrrequired

One process’s batch impacts inside a BatchScores.

impacts is the same LCIABatchResult that Client.get_impacts_batch returns for a single process. parameter_set is the position of the parameter set it was scored at, when Client.score_activities was given parameter_sets. product_amount is the amount the source declares for the activity’s reference product, negative for a treatment taking in waste, and product_unit its unit. The scores are per one product_unit whatever the amount, as for Activity.product_amount. Both are None for an activity without a reference product, and from an engine older than wire revision 80.

FieldTypeDefault
process_idstrrequired
activity_namestrrequired
impactsLCIABatchResultrequired
parameter_setint | NoneNone
product_amountfloat | NoneNone
product_unitstr | NoneNone

One per-variable entry inside LCIABatchResult.scoring_indicators.

value is pre-multiplied by the scoring set’s displayMultiplier (configured in the scoring TOML) and expressed in the set’s display unit. category is the indicator’s display name: the scoring set’s labels entry when one is configured (typically for computed variables), otherwise the impact category the variable was resolved from, or as a last resort the raw variable key.

FieldTypeDefault
categorystrrequired
valuefloatrequired

How many processes, products and flows one query matches.

The three are disjoint and together cover the database, so they partition what a query found. Use them to tell which of the three a term is really about before listing any of them: a term matching 2 processes and 300 flows is a substance name, not a product.

Needs engine wire revision 17.

FieldTypeDefault
processesintrequired
productsintrequired
flowsintrequired

Paginated wire envelope, mirrors Haskell SearchResults a.

Carries one page of results plus pagination metadata. Iterating walks every page lazily, fetching subsequent pages on demand via the _fetch callback. len() returns total: the server-reported count across all pages, not just the items currently held.

Wire fields (results, total, offset, limit, has_more, search_time_ms) mirror the server type exactly. Page-style helpers (page_size, page(n)) are client conveniences computed from them.

Pages fetched during iteration are cached on the instance, so re-iterating replays the cache without hitting the server. Wrap in list(...) to materialise eagerly if you prefer.

FieldTypeDefault
resultslist[~T]required
totalintrequired
offsetintrequired
limitintrequired
has_moreboolrequired
search_time_msfloatrequired
_fetchOptional[Callable[[int, int | None], dict]]None
_parseOptional[Callable[[dict], ~T]]None
_fetchedlist[~T]list()
_exhaustedboolFalse

Server-applied limit (page size for further fetches).

SearchResults.from_raw(raw: dict, *, parse: Callable[[dict], ~T], fetch: Optional[Callable[[int, int | None], dict]] = None) -> SearchResults[T]
Section titled “SearchResults.from_raw(raw: dict, *, parse: Callable[[dict], ~T], fetch: Optional[Callable[[int, int | None], dict]] = None) -> SearchResults[T]”

Build from the wire envelope.

Wire keys: results, total, offset, limit, hasMore, searchTimeMs. fetch is the callback used by iteration and page(n) to retrieve further pages. Omit only when the envelope is a single-page snapshot (hasMore=False); otherwise iteration would silently truncate and the constructor raises.

When fetch is provided (the production path), every wire key is required: missing fields would let pyvolca silently default to a truncated total or page size, which is the exact silent-undercount bug 0.5.0 set out to eliminate. When fetch is None (test fixtures), missing fields fall back to permissive defaults so callers can build small envelopes by hand.

SearchResults.page(n: int, *, page_size: int | None = None) -> SearchResults[T]
Section titled “SearchResults.page(n: int, *, page_size: int | None = None) -> SearchResults[T]”

Fetch a specific page (1-based). Returns a fresh SearchResults.

page_size overrides the current limit for the fetched page; the returned envelope’s limit reflects what the server actually applied.

Sensitivity analysis: baseline impact plus one entry per perturbation.

Returned by Client.compute_sensitivity. perturbed preserves the order of the requested perturbations.

FieldTypeDefault
baselineLCIAResultrequired
perturbedlist[PerturbedResult]required
cutoff_inputslist[CutoffInput]list()
withheld_cutoffslist[WithheldCutoffs]list()

Server build metadata returned by Client.get_version.

git_tag is None for untagged dev builds. build_target names the platform triple the binary was compiled for (e.g. "x86_64-linux"). wire_version is the engine’s advertised JSON wire-format revision, or None for engines that predate it (everything up to v0.7.x). data_version names the reference-data bundle the engine reads; None when it reads none, or for engines that predate the field. Two engines of one version giving two scores for one calculation differ here.

FieldTypeDefault
versionstrrequired
git_hashstrrequired
git_tagstr | Nonerequired
build_targetstrrequired
wire_versionint | NoneNone
data_versionstr | NoneNone

A parameter of a ReducedModel: its parameter.value is the default.

FieldTypeDefault
parameterParameterrequired
processstr | NoneNone

What a ReducedModel gives at N sets of parameter values.

scores is an array of N rows, one column per method of the model; scoring_sets gives, for each scoring set, each of its scores as an array of N values.

FieldTypeDefault
scoresAnyrequired
scoring_setsdict[str, dict[str, Any]]required

An input parameter a reduced model leaves free.

name and process as in ParameterValue: leave process out for one of the database’s database_parameters.

FieldTypeDefault
namestrrequired
processstr | NoneNone

What a formula gives at the database’s own values, or why it gives nothing.

problem is set exactly when value is not. reads lists the names the formula reads, in lower case; warnings what looks wrong without stopping it, such as a parameter whose unit does not convert to the line’s.

FieldTypeDefault
valuefloat | Nonerequired
readslist[str]required
warningslist[str]required
problemstr | Nonerequired

Parameter values of a database under a name.

To score one, pass its parameters as the parameters of a scoring request. problem says why its values no longer apply, when an edit of the database has since made them stale (a parameter removed, say). shipped marks one that comes with the database itself (an openLCA package’s parameter set), which can be neither replaced nor dropped.

FieldTypeDefault
namestrrequired
parameterslist[ParameterValue]required
problemstr | NoneNone
shippedboolFalse

A function or an operator of the formula language.

name is written as it is in a formula: a function’s name, or an operator’s symbol. form is "function", "operator" (between two arguments) or "prefix" (before one); value is what example gives.

FieldTypeDefault
namestrrequired
formstrrequired
usagestrrequired
meaningstrrequired
examplestrrequired
valuefloatrequired

The language parameter and exchange formulas are written in.

operators lists the operators by how tightly they bind, loosest first, each by its usage ("-x" apart from "a - b"); a function called by name binds tighter than all of them. rules says how numbers, names and arguments are written.

FieldTypeDefault
functionslist[FormulaFunction]required
operatorslist[list[str]]required
ruleslist[str]required

A value for one input parameter, for one request.

name is a parameter as Client.get_activity lists it. Leave process out for one of the database’s database_parameters; give the process_id for one of its own parameters. The amounts whose formulas read it are computed again for that request only: the loaded database does not change.

FieldTypeDefault
namestrrequired
valuefloatrequired
processstr | NoneNone

Serialise to the wire shape consumed by SubstitutionRequest.

An activity’s scores as a function of some of its parameters, from Client.reduced_model.

evaluate computes them for many sets of values without asking the engine again, loops among the processes the parameters move included. methods are the collection’s, in the order of every score; baseline the scores at the defaults. processes, suppliers and scoring_sets stay in the engine’s own shape, with formulas as trees, for a program that evaluates them its own way.

FieldTypeDefault
process_idstrrequired
methodslist[dict]required
exclude_long_termboolrequired
baselinelist[float]required
parameterslist[FreeParameter]required
processeslist[dict]required
supplierslist[dict]required
scoring_setslist[dict]required
ReducedModel.evaluate(values: Any) -> ModelScores
Section titled “ReducedModel.evaluate(values: Any) -> ModelScores”

The scores at each set of values: one row per set, one column per parameter in parameters’ order.

A flat array is one set, or, for a model of one parameter, one value per set.

Needs numpy (pip install 'pyvolca[model]'). A set that gives a line no finite amount, or turns the activity’s reference amount over, is refused with its position.

The lines to restate, and what to restate them to.

FieldTypeDefault
selectExchangeSelectorrequired
amountfloatrequired

The lines to give a formula in VoLCA’s language, or None to drop it and keep the amount; a named line keeps its name either way.

FieldTypeDefault
selectExchangeSelectorrequired
formulastr | Nonerequired

The dry mass of one unit of a product output, named by its flow id: amount in unit, a unit of mass (a kilogram of cheese at 59 % dry matter is SetDryMass(flow, 0.59)). An amount of None removes it.

FieldTypeDefault
productstrrequired
amountfloat | Nonerequired
unitstr’kg’

The inputs to move to another supplier, linked or naming none yet, and that supplier’s process id, in this database or a dependency. Each line keeps its amount, unit, formula, comment and pedigree.

FieldTypeDefault
selectExchangeSelectorrequired
providerstrrequired

The wet mass of one unit of a product output, named by its flow id: amount in unit, a unit of mass. On a product in litres or cubic metres it is the product’s density (a litre of wine at 0.92 is SetWetMass(flow, 0.92)), and the wet mass key weighs it before the line’s own amount. An amount of None removes it.

FieldTypeDefault
productstrrequired
amountfloat | Nonerequired
unitstr’kg’

One activity’s edit for Client.edit_activities: the process it applies to, and the changes Client.edit_exchanges takes, under the same names and with the same meaning. The note is given once, for the whole change, so it is not here.

FieldTypeDefault
process_idstrrequired
removecollections.abc.Sequence[ExchangeSelector]()
set_amountscollections.abc.Sequence[SetAmount]()
add_inputscollections.abc.Sequence[TechInput]()
add_biospherecollections.abc.Sequence[BioExchange]()
add_waste_outputscollections.abc.Sequence[WasteOutput]()
namestr | NoneNone
locationstr | NoneNone
descriptionlist[str] | NoneNone
set_parameterscollections.abc.Sequence[SetParameter]()
set_formulascollections.abc.Sequence[SetFormula]()
set_pricescollections.abc.Sequence[SetPrice]()
set_dry_massescollections.abc.Sequence[SetDryMass]()
set_wet_massescollections.abc.Sequence[SetWetMass]()
set_supplierscollections.abc.Sequence[SetSupplier]()
remove_parameterscollections.abc.Sequence[str]()

The body of Client.edit_exchanges for this edit. The five lists of lines always travel, so the body keeps one shape; the rest travel only when stated, since an empty description clears it and a null price removes it.

The price of a product output, named by its flow id: amount for one unit of the product, in currency as written ("EUR2005"). An amount of None removes the price.

FieldTypeDefault
productstrrequired
amountfloat | Nonerequired
currencystr”

A parameter to add, of an activity or of a database, or to replace whole under the same spelling: a value (with an uncertainty if it varies), or a formula in VoLCA’s language whose value the engine computes. A unit, description or uncertainty left out is dropped.

FieldTypeDefault
namestrrequired
valuefloat | NoneNone
formulastr | NoneNone
unitstr | NoneNone
descriptionstr | NoneNone
uncertaintyUncertainty | NoneNone

Replace one supplier with another in the upstream supply chain.

All fields are process_ids. consumer identifies which downstream consumer’s input to rewrite, scoping the swap to one edge: the same upstream supplier can be replaced by different alternatives in different parts of the tree. Omit it (leave None) to apply the swap globally, replacing the supplier on every consumer at once.

Frozen so callers can put it in a set / dict key and re-use the same substitution across multiple calls without aliasing risk.

FieldTypeDefault
from_pidstrrequired
to_pidstrrequired
consumerstr | NoneNone

Serialise to the wire shape consumed by SubstitutionRequest.

A field of two activities that differs.

field is "activity_name", "location", "product_name", "allocation_percent", "dates", whose before and after are DatasetDates, or "description", whose before and after are lists of paragraphs. The product’s amount and unit are not among them: the reference line reports those, among the exchanges.

FieldTypeDefault
fieldstrrequired
beforestr | float | DatasetDates | list[str] | Nonerequired
afterstr | float | DatasetDates | list[str] | Nonerequired

What the source said about an exchange’s supplier, before linking.

Every format designates a supplier differently, and linking overwrites what it resolved to; this is the claim itself, which linking never rewrites, so a reader can tell what the file asked for from what the engine found. value is the identifier, name or dataset number the claim carries, and is None for ClaimKind.PRODUCT, which names the supplier by the product row and carries nothing else.

Wire revision 23; None on a technosphere exchange from an older engine.

FieldTypeDefault
kindClaimKindrequired
valuestr | int | NoneNone

Flat supply chain of an activity.

total_activities is the unfiltered upstream count; filtered_activities is what remains after the server applies classification_filters / min_quantity / preset. entries is the slice the server actually returned; it may be shorter than filtered_activities when limit truncates. Use has_more to detect that case rather than comparing lengths by hand.

FieldTypeDefault
rootActivityrequired
total_activitiesintrequired
filtered_activitiesintrequired
entrieslist[SupplyChainEntry]list()
edgeslist[SupplyChainEdge]list()
withheld_databaseslist[WithheldProcesses]list()
withheld_inputslist[WithheldInput]list()
cutoff_inputslist[CutoffInput]list()
withheld_cutoffslist[WithheldCutoffs]list()

True when the server truncated entries below filtered_activities.

Surfacing this lets callers detect silent truncation: if you passed limit=100 and filtered_activities is 500, downstream LCA work would be wrong without flagging the gap.

A consumer→supplier link in the supply chain.

from/to are Python keywords, so the process ids are stored under from_id/to_id. from_db/to_db carry each endpoint’s database name, which is required to route edges across databases (the same process id can exist in more than one loaded DB).

FieldTypeDefault
from_idstrrequired
from_dbstrrequired
to_idstrrequired
to_dbstrrequired
amountfloatrequired

One activity in a SupplyChain.entries list.

quantity is the cumulative amount of this activity’s reference product consumed per functional unit of the root activity, in unit. unit is the producing activity’s reference-product unit, which for a database imported from SimaPro or Brightway Excel is the canonical unit of its dimension ("kg", "mj", "m3"), not the unit written on the exchange that consumes it. An input stated as 0.22 kWh therefore shows up here as its equivalent in mj: 1 kWh is 3.6 MJ. scaling_factor is the multiplier the solver applied to this activity to produce quantity, i.e. quantity = ref_output * scaling_factor. classifications mirrors the producing activity’s classifications (ISIC, CPC, Category, …) so callers can filter by taxonomy without a second Client.get_activity round trip. depth is the BFS shortest-path distance from the queried root (0 = the root itself), upstream_count the number of direct consumers of this activity inside the chain, and database_name the database the entry lives in (they differ across linked databases).

FieldTypeDefault
process_idstrrequired
database_namestrrequired
activity_namestrrequired
locationstrrequired
quantityfloatrequired
unitstrrequired
scaling_factorfloatrequired
depthintrequired
upstream_countintrequired
classificationsdict[str, str]dict()

One product an activity consumes, named by the process that supplies it.

provider is a process_id (activityUUID_productUUID, or a bare activity UUID when that activity has a single product), the same address every read endpoint hands out. The flow follows from the supplier, so it is never stated separately. unit defaults to the supplier’s own reference unit; another one is fine as long as it converts.

FieldTypeDefault
providerstrrequired
amountfloatrequired
unitstr | NoneNone
commentstr | NoneNone

An exchange with another activity. Carries no compartment: the producing activity’s classifications describe the product taxonomy.

supplier_claim is how the source designated the supplier, which is not the same question as which activity it resolved to: target_process_id is the answer, this is what was asked (wire revision 23).

FieldTypeDefault
flow_namestrrequired
amountfloatrequired
unitstrrequired
roleTechRolerequired
target_activity_namestr | Nonerequired
target_locationstr | Nonerequired
target_process_idstr | Nonerequired
commentstr | NoneNone
supplier_claimSupplierClaim | NoneNone
formulaExchangeFormula | NoneNone
positionint | NoneNone
selectorExchangeSelector | NoneNone
is_biosphereboolFalse
is_wasteboolFalse

True for technosphere inputs (role is INPUT or REFERENCE_INPUT).

Lets callers split exchanges into inputs vs. outputs without knowing the four-role taxonomy.

True for reference roles (REFERENCE_PRODUCT / REFERENCE_INPUT).

The reference exchange is the one that defines the activity’s functional unit, the basis the LCA result is normalised to.

A line the engine could not judge, and why.

reason is "mixed_units" when one side writes the flow in several units, which no sum reads (base_units and other_units list them, empty on the side that lacks the line), or "several_flows" when several distinct flows answer to one name on a side (base_flows and other_flows list their ids).

FieldTypeDefault
flow_namestrrequired
compartmentCompartment | Nonerequired
kindstrrequired
rolestrrequired
reasonstrrequired
base_unitslist[str]list()
other_unitslist[str]list()
base_flowslist[str]list()
other_flowslist[str]list()

A method factor with no matching database flow (in MappingStatus).

FieldTypeDefault
flow_refstrrequired
flow_namestrrequired
directionstrrequired
compartmentstr | NoneNone

An exchange of a waste flow with a treatment activity.

Shares the technosphere matrix with product flows but tracked as its own kind so callers can tell a “waste sent to landfill” output apart from a product input. A waste output no treatment is found for contributes zero impact, the same cut-off semantics as an orphan technosphere input; role says whether that is because nothing treats it or because the treatment it names was not loaded.

FieldTypeDefault
flow_namestrrequired
amountfloatrequired
unitstrrequired
is_inputboolrequired
target_activity_namestr | Nonerequired
target_locationstr | Nonerequired
target_process_idstr | Nonerequired
commentstr | NoneNone
roleWasteRole | NoneNone
supplier_claimSupplierClaim | NoneNone
formulaExchangeFormula | NoneNone
positionint | NoneNone
selectorExchangeSelector | NoneNone
is_biosphereboolFalse
is_wasteboolTrue

Always False: waste flows never define an activity’s functional unit.

Treatment activities have a ReferenceInput instead, exposed via TechnosphereExchange.

One residue an activity hands to a treatment process.

provider names that treatment process, exactly as a TechInput names its producer.

FieldTypeDefault
providerstrrequired
amountfloatrequired
unitstr | NoneNone
commentstr | NoneNone

compare_activities(client: Client, pid_left: str, pid_right: str, *, scope: str = 'direct', group_by: str = 'flow_id', is_input: bool | None = True, **aggregate_kwargs) -> ActivityDiff

Section titled “compare_activities(client: Client, pid_left: str, pid_right: str, *, scope: str = 'direct', group_by: str = 'flow_id', is_input: bool | None = True, **aggregate_kwargs) -> ActivityDiff”

Diff two activities by flow_id (default) at the requested scope.

Returns three lists:

  • matched: flows present in both activities (with left, right, delta).
  • left_only: flows present only in the left activity.
  • right_only: flows present only in the right activity.

Default is_input=True restricts the comparison to inputs, which is the common case for “what does this variant consume differently?”. Pass is_input=None to include outputs as well.

download(version: Optional[str] = None, repo: str = 'ccomb/volca', *, force: bool = False) -> Installed

Section titled “download(version: Optional[str] = None, repo: str = 'ccomb/volca', *, force: bool = False) -> Installed”

Download the volca binary + data bundle for the current platform.

Idempotent: if both artefacts are already extracted under the install root and force=False, returns immediately without network.

Args: version: GH Release tag (v0.7.0); None resolves the latest. repo: GitHub repo slug. Default ccomb/volca. force: Re-download even if the install root looks complete.

Returns: Installed with the resolved paths and versions.

Type alias: Union[TechnosphereExchange, BiosphereExchange, WasteExchange].

Type alias: Literal['flow-synonyms', 'compartment-mappings', 'units'].