Python API Reference
This reference is generated from the installed package. Run python scripts/gen_api_md.py to regenerate.
Classes
Section titled “Classes”AggregateOp
Section titled “AggregateOp”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).
AggregateScope
Section titled “AggregateScope”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.
BioDirection
Section titled “BioDirection”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.
ClaimKind
Section titled “ClaimKind”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.
Client
Section titled “Client”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 = '')
Methods
Section titled “Methods”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.
Client.available_method_collections()
Section titled “Client.available_method_collections()”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.
Client.default_method_collection()
Section titled “Client.default_method_collection()”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).
Client.download_units(name: str) -> bytes
Section titled “Client.download_units(name: str) -> bytes”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.
Client.formula_language()
Section titled “Client.formula_language()”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.
Client.get_stats()
Section titled “Client.get_stats()”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).
Client.get_tree(process_id: str) -> dict
Section titled “Client.get_tree(process_id: str) -> dict”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.
Client.get_version()
Section titled “Client.get_version()”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.
Client.licences()
Section titled “Client.licences()”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.
Client.list_classifications()
Section titled “Client.list_classifications()”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.
Client.list_databases()
Section titled “Client.list_databases()”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.
Client.list_method_collections()
Section titled “Client.list_method_collections()”List every method collection the engine knows (loaded or staged).
Each entry carries name, displayName, status,
methodCount and format.
Client.list_methods()
Section titled “Client.list_methods()”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.
Client.list_presets()
Section titled “Client.list_presets()”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.
Client.refresh_stubs()
Section titled “Client.refresh_stubs()”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"}).
Client.relink_from_file(dep_db: str, mapping_path: str, db_name: str | None = None) -> dict
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.
Client.usage(after: int = 0) -> dict
Section titled “Client.usage(after: int = 0) -> dict”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.
Client.use(db_name: str) -> 'Client'
Section titled “Client.use(db_name: str) -> 'Client'”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).
DatabaseStatus
Section titled “DatabaseStatus”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.
MatchMode
Section titled “MatchMode”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".
Server
Section titled “Server”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)
Properties
Section titled “Properties”base_url
Section titled “base_url”http://localhost:<port>, pass to Client(base_url=…).
Always loopback: the managed server only listens locally.
Methods
Section titled “Methods”Server.is_alive()
Section titled “Server.is_alive()”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.
Server.stop()
Section titled “Server.stop()”Stop the server via shutdown endpoint, then terminate process.
TechRole
Section titled “TechRole”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.
WasteRole
Section titled “WasteRole”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.
Exceptions
Section titled “Exceptions”DownloadError
Section titled “DownloadError”Raised when the download or verification fails.
VoLCAError
Section titled “VoLCAError”Error from the VoLCA API.
Constructor: VoLCAError(message: str, status_code: int | None = None, body: str = '')
Data types
Section titled “Data types”Activity
Section titled “Activity”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.
| Field | Type | Default |
|---|---|---|
process_id | str | required |
activity_name | str | required |
location | str | required |
product_name | str | required |
product_amount | float | required |
product_unit | str | required |
allocation_percent | float | None | None |
allocation_formula | str | None | None |
mass_allocation_percent | float | None | None |
block | str | None | None |
block_products | int | None | None |
ActivityComparison
Section titled “ActivityComparison”Two activities side by side, as Client.compare_activities returns them.
| Field | Type | Default |
|---|---|---|
base | Activity | required |
other | Activity | required |
summary | list[SummaryChange] | required |
exchanges | list[ExchangeChange] | required |
uncompared | list[UncomparedLine] | required |
Properties
Section titled “Properties”identical
Section titled “identical”True when nothing differs and every line could be judged.
ActivityContribution
Section titled “ActivityContribution”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).
| Field | Type | Default |
|---|---|---|
process_id | str | required |
activity_name | str | required |
product_name | str | required |
location | str | required |
contribution | float | required |
share_pct | float | required |
ActivityDetail
Section titled “ActivityDetail”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).
| Field | Type | Default |
|---|---|---|
process_id | str | required |
activity_name | str | required |
location | str | required |
unit | str | required |
description | list[str] | required |
classifications | dict[str, str] | required |
product_name | str | None | required |
product_amount | float | None | required |
product_unit | str | None | required |
all_products | list[Activity] | required |
exchanges | list[Union[TechnosphereExchange, BiosphereExchange, WasteExchange]] | required |
native_id | str | None | None |
dates | DatasetDates | DatasetDates() |
withheld | WithheldExchanges | None | None |
parameters | list[Parameter] | list() |
database_parameters | list[Parameter] | list() |
Properties
Section titled “Properties”allocation_percent
Section titled “allocation_percent”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.
inputs
Section titled “inputs”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.
is_allocated
Section titled “is_allocated”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.
outputs
Section titled “outputs”Every output exchange: products and biosphere emissions.
Includes the reference product, coproducts (in allocated activities), and all biosphere emissions.
technosphere_inputs
Section titled “technosphere_inputs”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?”.
ExchangeName
Section titled “ExchangeName”An exchange named without its amount, as a database whose licence keeps its amounts lets it be read.
| Field | Type | Default |
|---|---|---|
flow_name | str | required |
unit_name | str | required |
kind | str | required |
is_input | bool | required |
compartment | Compartment | None | None |
target_activity_name | str | None | None |
target_location | str | None | None |
target_process_id | str | None | None |
WithheldExchanges
Section titled “WithheldExchanges”The exchanges of an activity whose licence keeps their amounts, and why.
| Field | Type | Default |
|---|---|---|
reason | str | required |
lines | list[ExchangeName] | required |
WithheldInput
Section titled “WithheldInput”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).
| Field | Type | Default |
|---|---|---|
consumer | str | required |
database | str | required |
WithheldProcesses
Section titled “WithheldProcesses”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).
| Field | Type | Default |
|---|---|---|
database | str | required |
processes | int | required |
reason | str | required |
WithheldShare
Section titled “WithheldShare”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).
| Field | Type | Default |
|---|---|---|
database | str | required |
contribution | float | required |
share_pct | float | required |
reason | str | required |
CutoffInput
Section titled “CutoffInput”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).
| Field | Type | Default |
|---|---|---|
database | str | required |
product | str | required |
supplier | str | None | required |
location | str | required |
unit | str | required |
amount | float | required |
consumers | int | required |
reasons | list[dict] | required |
WithheldCutoffs
Section titled “WithheldCutoffs”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).
| Field | Type | Default |
|---|---|---|
database | str | required |
count | int | required |
DatasetDates
Section titled “DatasetDates”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.
| Field | Type | Default |
|---|---|---|
created | datetime.date | None | None |
last_revised | datetime.date | None | None |
stated | datetime.date | None | None |
ExchangeContribution
Section titled “ExchangeContribution”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.
| Field | Type | Default |
|---|---|---|
position | int | required |
contribution | float | required |
share_pct | float | required |
ProbableMiss
Section titled “ProbableMiss”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.
| Field | Type | Default |
|---|---|---|
flow_id | str | required |
flow_name | str | required |
category | str | required |
compartment | str | None | required |
quantity | float | required |
unit | str | required |
written_at | list[str] | required |
factor | float | required |
up_to | float | required |
up_to_share_pct | float | required |
ProbableMisses
Section titled “ProbableMisses”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.
| Field | Type | Default |
|---|---|---|
shown | list[ProbableMiss] | list() |
more | int | 0 |
withheld | list[str] | list() |
ScoreBasis
Section titled “ScoreBasis”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.
| Field | Type | Default |
|---|---|---|
engine | str | required |
databases | list[BasisDatabase] | required |
methods | BasisMethods | required |
substitutions | list['Substitution'] | list() |
parameter_sets | list[list['ParameterValue']] | list() |
BasisDatabase
Section titled “BasisDatabase”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.
| Field | Type | Default |
|---|---|---|
name | str | required |
release | dict | None | required |
reads_files_of | str | None | required |
edited | bool | required |
reallocated | bool | required |
patched | bool | required |
BasisMethods
Section titled “BasisMethods”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.
| Field | Type | Default |
|---|---|---|
collection | str | required |
copy_of | str | None | required |
modified | bool | required |
ExchangeFormula
Section titled “ExchangeFormula”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).
| Field | Type | Default |
|---|---|---|
text | str | required |
name | str | None | None |
PairedActivities
Section titled “PairedActivities”Two activities the cascade paired, one from each database, and the rung that paired them.
matched_on reads as in ChangedActivity.
| Field | Type | Default |
|---|---|---|
matched_on | str | required |
base | Activity | required |
other | Activity | required |
Parameter
Section titled “Parameter”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).
| Field | Type | Default |
|---|---|---|
name | str | required |
value | float | None | required |
formula | str | None | None |
unit | str | None | None |
description | str | ” |
uncertainty | Uncertainty | None | None |
Uncertainty
Section titled “Uncertainty”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.
| Field | Type | Default |
|---|---|---|
distribution | str | required |
geometric_mean | float | None | None |
geometric_sd | float | None | None |
mean | float | None | None |
sd | float | None | None |
minimum | float | None | None |
mode | float | None | None |
maximum | float | None | None |
ActivityDiff
Section titled “ActivityDiff”Result of compare_activities.
| Field | Type | Default |
|---|---|---|
scope | str | required |
group_by | str | required |
matched | list[ActivityDiffRow] | list() |
left_only | list[ActivityDiffRow] | list() |
right_only | list[ActivityDiffRow] | list() |
ActivityInput
Section titled “ActivityInput”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.
| Field | Type | Default |
|---|---|---|
name | str | required |
location | str | required |
product_name | str | required |
product_amount | float | required |
product_unit | str | required |
description | list[str] | list() |
inputs | list[TechInput] | list() |
biosphere | list[BioExchange] | list() |
waste_outputs | list[WasteOutput] | list() |
ActivityDiffRow
Section titled “ActivityDiffRow”One matched or unmatched flow in an activity comparison.
| Field | Type | Default |
|---|---|---|
key | str | required |
left | float | None | required |
right | float | None | required |
unit | str | None | required |
Properties
Section titled “Properties”right - left (0 if one side is missing).
AggregateGroup
Section titled “AggregateGroup”One bucket inside an AggregateResult.
| Field | Type | Default |
|---|---|---|
key | str | required |
quantity | float | required |
count | int | required |
unit | str | None | None |
share | float | None | None |
AggregateResult
Section titled “AggregateResult”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.
| Field | Type | Default |
|---|---|---|
scope | AggregateScope | required |
filtered_total | float | required |
filtered_unit | str | None | required |
filtered_count | int | required |
groups | list[AggregateGroup] | list() |
withheld_databases | list[WithheldProcesses] | list() |
cutoff_inputs | list[CutoffInput] | list() |
withheld_cutoffs | list[WithheldCutoffs] | list() |
AmbiguousActivities
Section titled “AmbiguousActivities”Activities one key of a rung names on either side, too many to pair.
| Field | Type | Default |
|---|---|---|
matched_on | str | required |
base | list[Activity] | required |
other | list[Activity] | required |
BatchScores
Section titled “BatchScores”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.
| Field | Type | Default |
|---|---|---|
results | list[ScoredActivity] | required |
not_found | list[str] | required |
invalid | list[str] | required |
unscorable | list[str] | required |
unsolvable | list[UnsolvableActivity] | list() |
basis | ScoreBasis | None | None |
reading_notice | str | None | None |
UnsolvableActivity
Section titled “UnsolvableActivity”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.
| Field | Type | Default |
|---|---|---|
process_id | str | required |
reason | str | required |
parameter_set | int | None | None |
BioExchange
Section titled “BioExchange”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.
| Field | Type | Default |
|---|---|---|
direction | BioDirection | required |
amount | float | required |
flow | str | None | None |
name | str | None | None |
compartment | str | None | None |
sub_compartment | str | None | None |
unit | str | None | None |
comment | str | None | None |
Methods
Section titled “Methods”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.
BiosphereExchange
Section titled “BiosphereExchange”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.
| Field | Type | Default |
|---|---|---|
flow_name | str | required |
compartment | Compartment | None | required |
amount | float | required |
unit | str | required |
direction | BioDirection | required |
flow_id | str | required |
comment | str | None | None |
formula | ExchangeFormula | None | None |
position | int | None | None |
selector | ExchangeSelector | None | None |
is_biosphere | bool | True |
is_waste | bool | False |
Properties
Section titled “Properties”is_input
Section titled “is_input”True for resource extractions (direction is RESOURCE).
Biosphere inputs are resource extractions; outputs are emissions to the environment.
is_reference
Section titled “is_reference”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).
ChangedActivity
Section titled “ChangedActivity”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).
| Field | Type | Default |
|---|---|---|
matched_on | str | required |
comparison | ActivityComparison | required |
CharacterizationFactor
Section titled “CharacterizationFactor”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").
| Field | Type | Default |
|---|---|---|
method_flow_name | str | required |
cf_value | float | required |
cf_unit | str | required |
direction | str | required |
db_flow_name | str | required |
flow_id | str | required |
flow_unit | str | required |
category | str | required |
match_strategy | str | required |
compartment | str | None | None |
CharacterizationResult
Section titled “CharacterizationResult”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.
| Field | Type | Default |
|---|---|---|
method | str | required |
unit | str | required |
matches | int | required |
shown | int | required |
factors | list[CharacterizationFactor] | list() |
Properties
Section titled “Properties”has_more
Section titled “has_more”True when the server truncated below matches.
ClassificationFilter
Section titled “ClassificationFilter”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.
| Field | Type | Default |
|---|---|---|
system | str | required |
value | str | required |
mode | MatchMode | <MatchMode.CONTAINS: ‘contains’> |
ClassificationSystem
Section titled “ClassificationSystem”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).
| Field | Type | Default |
|---|---|---|
name | str | required |
values | list[str] | list() |
activity_count | int | 0 |
Compartment
Section titled “Compartment”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.
| Field | Type | Default |
|---|---|---|
name | str | required |
sub | str | None | None |
UnitDefinition
Section titled “UnitDefinition”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.
| Field | Type | Default |
|---|---|---|
dimension | str | required |
factor | float | required |
ConsumerResult
Section titled “ConsumerResult”Activity that consumes a given supplier, with BFS depth.
| Field | Type | Default |
|---|---|---|
process_id | str | required |
activity_name | str | required |
location | str | required |
product_name | str | required |
product_amount | float | required |
product_unit | str | required |
depth | int | required |
classifications | dict[str, str] | dict() |
ConsumersResponse
Section titled “ConsumersResponse”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.
| Field | Type | Default |
|---|---|---|
consumers | SearchResults[ConsumerResult] | required |
edges | list[SupplyChainEdge] | list() |
Methods
Section titled “Methods”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).
ContributingActivities
Section titled “ContributingActivities”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.
| Field | Type | Default |
|---|---|---|
method | str | required |
unit | str | required |
total_score | float | required |
activities | list[ActivityContribution] | list() |
withheld_databases | list[WithheldShare] | list() |
cutoff_inputs | list[CutoffInput] | list() |
withheld_cutoffs | list[WithheldCutoffs] | list() |
basis | ScoreBasis | None | None |
ContributingFlows
Section titled “ContributingFlows”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.
| Field | Type | Default |
|---|---|---|
method | str | required |
unit | str | required |
total_score | float | required |
top_flows | list[FlowContribution] | list() |
withheld_databases | list[WithheldShare] | list() |
cutoff_inputs | list[CutoffInput] | list() |
withheld_cutoffs | list[WithheldCutoffs] | list() |
basis | ScoreBasis | None | None |
DatabaseComparison
Section titled “DatabaseComparison”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.
| Field | Type | Default |
|---|---|---|
added_count | int | required |
removed_count | int | required |
changed_count | int | required |
redated_count | int | required |
ambiguous_count | int | required |
unchanged_count | int | required |
added | list[Activity] | required |
removed | list[Activity] | required |
changed | list[ChangedActivity] | required |
redated | list[ChangedActivity] | required |
ambiguous | list[AmbiguousActivities] | required |
unchanged | list[PairedActivities] | None | required |
Methods
Section titled “Methods”DatabaseComparison.pairs()
Section titled “DatabaseComparison.pairs()”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.
DatabaseInfo
Section titled “DatabaseInfo”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.
| Field | Type | Default |
|---|---|---|
name | str | required |
display_name | str | required |
status | DatabaseStatus | required |
path | str | required |
load_at_startup | bool | False |
is_uploaded | bool | False |
activity_count | int | 0 |
description | str | None | None |
format | str | None | None |
depends_on | list[str] | list() |
allocation | str | None | None |
source | str | None | None |
licence | dict | None | None |
release | dict | None | None |
modification | dict | None | None |
added | str | None | None |
Properties
Section titled “Properties”modified
Section titled “modified”Whether its data differ from the files it reads.
ExchangeChange
Section titled “ExchangeChange”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.
| Field | Type | Default |
|---|---|---|
flow_id | str | required |
flow_name | str | required |
compartment | Compartment | None | required |
kind | str | required |
role | str | required |
change | str | required |
before | Quantity | None | required |
after | Quantity | None | required |
matched_on | str | None | None |
supplier_before | Supplier | None | None |
supplier_after | Supplier | None | None |
ExchangeSelector
Section titled “ExchangeSelector”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.
| Field | Type | Default |
|---|---|---|
kind | str | required |
provider | str | None | None |
flow | str | None | None |
location | str | None | None |
Properties
Section titled “Properties”by_flow
Section titled “by_flow”True for an input or a waste output named by its flow (wire revision 76).
Methods
Section titled “Methods”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.
ExplainCFResult
Section titled “ExplainCFResult”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.
| Field | Type | Default |
|---|---|---|
method | str | required |
method_unit | str | required |
flow | ExplainedFlow | required |
outcome | str | required |
explanation | list[str] | list() |
match | ExplainedMatch | None | None |
steps_tried | list[ExplainedStep] | list() |
regional_factor_count | int | 0 |
method_id | str | None | None |
CollectionFactors
Section titled “CollectionFactors”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.
| Field | Type | Default |
|---|---|---|
collection | str | required |
factors | list[ExplainCFResult] | list() |
no_factor | list[Method] | list() |
FlowFactors
Section titled “FlowFactors”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.
| Field | Type | Default |
|---|---|---|
flow | ExplainedFlow | required |
collections | list[CollectionFactors] | list() |
FactorMatch
Section titled “FactorMatch”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.
| Field | Type | Default |
|---|---|---|
category | str | None | None |
flow_name | str | None | None |
flow_name_prefix | str | None | None |
cas | str | None | None |
subcompartment_contains | str | None | None |
ExplainedFlow
Section titled “ExplainedFlow”The flow an explanation is about, as the cascade sees it.
| Field | Type | Default |
|---|---|---|
id | str | required |
name | str | required |
unit | str | required |
category | str | required |
compartment | str | None | None |
cas | str | None | None |
ExplainedMatch
Section titled “ExplainedMatch”The factor that was served, and where it came from.
| Field | Type | Default |
|---|---|---|
rung | str | required |
cf_value | float | required |
cf_unit | str | required |
method_flow_name | str | required |
match_strategy | str | required |
method_cas | str | None | None |
unit_conversion | str | None | None |
refusal | str | None | None |
ExplainedStep
Section titled “ExplainedStep”One rung of the factor-matching cascade, and what it made of the flow.
| Field | Type | Default |
|---|---|---|
rung | str | required |
result | str | required |
veto | str | None | None |
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.
| Field | Type | Default |
|---|---|---|
id | str | required |
name | str | required |
category | str | required |
unit_name | str | required |
kind | str | None | None |
compartment | str | None | None |
synonyms | dict[str, list[str]] | dict() |
producer_count | int | None | None |
FlowContribution
Section titled “FlowContribution”Top contributing elementary flow for an impact category.
Emitted inside LCIAResult.top_contributors.
| Field | Type | Default |
|---|---|---|
flow_name | str | required |
contribution | float | required |
share_pct | float | required |
flow_id | str | required |
category | str | required |
cf_value | float | 0.0 |
compartment | str | None | None |
match_kind | str | None | None |
FlowDetail
Section titled “FlowDetail”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.
| Field | Type | Default |
|---|---|---|
flow | dict | required |
unit_name | str | required |
usage_count | int | required |
FlowMapping
Section titled “FlowMapping”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.
| Field | Type | Default |
|---|---|---|
method_name | str | required |
method_unit | str | required |
total_flows | int | required |
matched_flows | int | required |
flows | list[FlowMappingEntry] | list() |
Properties
Section titled “Properties”coverage_pct
Section titled “coverage_pct”Matched fraction expressed as 0..100. Returns 0 when total is 0.
FlowMappingEntry
Section titled “FlowMappingEntry”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").
| Field | Type | Default |
|---|---|---|
flow_id | str | required |
flow_name | str | required |
flow_category | str | required |
cf_value | float | None | None |
cf_flow_name | str | None | None |
match_strategy | str | None | None |
Installed
Section titled “Installed”Result of download.
| Field | Type | Default |
|---|---|---|
binary | Path | required |
data_dir | Path | required |
version | str | required |
data_version | str | required |
InventoryFlow
Section titled “InventoryFlow”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.
| Field | Type | Default |
|---|---|---|
flow_id | str | required |
flow_name | str | required |
quantity | float | required |
unit_name | str | required |
is_emission | bool | required |
category | str | required |
compartment | str | None | None |
InventoryResult
Section titled “InventoryResult”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.
| Field | Type | Default |
|---|---|---|
root | Activity | required |
total_flows | int | required |
emission_flows | int | required |
resource_flows | int | required |
flows | list[InventoryFlow] | required |
statistics | InventoryStatistics | required |
matched_flows | int | 0 |
cutoff_inputs | list[CutoffInput] | list() |
withheld_cutoffs | list[WithheldCutoffs] | list() |
InventoryStatistics
Section titled “InventoryStatistics”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.
| Field | Type | Default |
|---|---|---|
total_quantity | float | required |
emission_quantity | float | required |
resource_quantity | float | required |
top_categories | list[tuple[str, int]] | list() |
LCIABatchResult
Section titled “LCIABatchResult”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.
| Field | Type | Default |
|---|---|---|
results | list[LCIAResult] | required |
single_score | float | None | None |
single_score_unit | str | None | None |
norm_weight_set_name | str | None | None |
available_nw_sets | list[str] | list() |
scoring_results | dict[str, dict[str, float]] | dict() |
scoring_units | dict[str, str] | dict() |
scoring_indicators | dict[str, dict[str, ScoringIndicator]] | dict() |
scoring_rows | dict[str, dict[str, ScoringIndicator]] | dict() |
withheld | list[str] | list() |
cutoff_inputs | list[CutoffInput] | list() |
withheld_cutoffs | list[WithheldCutoffs] | list() |
basis | ScoreBasis | None | None |
LCIAResult
Section titled “LCIAResult”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.
| Field | Type | Default |
|---|---|---|
method_id | str | required |
method_name | str | required |
category | str | required |
damage_category | str | required |
score | float | required |
unit | str | required |
mapped_flows | int | required |
functional_unit | str | required |
normalized_score | float | None | None |
weighted_score | float | None | None |
top_contributors | list[FlowContribution] | list() |
withheld | str | None | None |
withheld_databases | list[WithheldShare] | list() |
cutoff_inputs | list[CutoffInput] | list() |
withheld_cutoffs | list[WithheldCutoffs] | list() |
exchange_contributions | list[ExchangeContribution] | list() |
probable_misses | ProbableMisses | None | None |
basis | ScoreBasis | None | None |
MappingStatus
Section titled “MappingStatus”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.
| Field | Type | Default |
|---|---|---|
method_id | str | required |
method_name | str | required |
total_factors | int | required |
mapped_by_uuid | int | required |
mapped_by_cas | int | required |
mapped_by_name | int | required |
mapped_by_synonym | int | required |
unmapped | int | required |
coverage | float | required |
db_biosphere_count | int | required |
unique_db_flows_matched | int | required |
unmapped_flows | list[UnmappedFlow] | required |
Method
Section titled “Method”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.
| Field | Type | Default |
|---|---|---|
id | str | required |
name | str | required |
category | str | required |
unit | str | required |
factor_count | int | required |
collection | str | required |
MethodDetail
Section titled “MethodDetail”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.
| Field | Type | Default |
|---|---|---|
id | str | required |
name | str | required |
unit | str | required |
category | str | required |
factor_count | int | required |
description | str | None | None |
methodology | str | None | None |
FactorReading
Section titled “FactorReading”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.
| Field | Type | Default |
|---|---|---|
medium | str | None | None |
location | ReadLocation | None | None |
MethodFactor
Section titled “MethodFactor”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.
| Field | Type | Default |
|---|---|---|
flow_ref | str | required |
flow_name | str | required |
direction | str | required |
value | float | required |
unit | str | None | None |
compartment | str | None | None |
location | str | None | None |
reading | FactorReading | None | None |
NewMethodFactor
Section titled “NewMethodFactor”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.
| Field | Type | Default |
|---|---|---|
flow_id | str | required |
name | str | required |
direction | str | required |
value | float | required |
unit | str | required |
compartment | tuple[str, str, str] | None | None |
cas | str | None | None |
location | str | None | None |
ScoringRow
Section titled “ScoringRow”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.
| Field | Type | Default |
|---|---|---|
label | str | required |
terms | dict[str, float] | required |
normalization | float | None | None |
weight | float | None | None |
unit | str | None | None |
ReadLocation
Section titled “ReadLocation”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).
| Field | Type | Default |
|---|---|---|
code | str | required |
from_ | str | required |
PathResult
Section titled “PathResult”Shortest upstream path from a root process to a matching activity.
| Field | Type | Default |
|---|---|---|
path | list[PathStep] | required |
path_length | int | required |
total_ratio | float | required |
PathStep
Section titled “PathStep”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.
| Field | Type | Default |
|---|---|---|
process_id | str | required |
activity_name | str | required |
location | str | required |
unit | str | required |
cumulative_quantity | float | required |
scaling_factor | float | required |
local_step_ratio | float | None | None |
PerturbedResult
Section titled “PerturbedResult”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.
| Field | Type | Default |
|---|---|---|
perturbation | dict | required |
impact | LCIAResult | None | required |
delta_impact | float | None | required |
error | str | None | required |
Preset
Section titled “Preset”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).
| Field | Type | Default |
|---|---|---|
name | str | required |
label | str | required |
description | str | None | required |
filters | list[PresetFilter] | list() |
PresetFilter
Section titled “PresetFilter”One filter triple inside a Preset.
| Field | Type | Default |
|---|---|---|
system | str | required |
value | str | required |
mode | MatchMode | <MatchMode.CONTAINS: ‘contains’> |
Quantity
Section titled “Quantity”The lines of one flow in one unit, as one side writes them, summed.
| Field | Type | Default |
|---|---|---|
amount | float | required |
unit | str | required |
Supplier
Section titled “Supplier”The activity an input comes from, or a waste goes to, by name and location.
| Field | Type | Default |
|---|---|---|
activity_name | str | required |
location | str | required |
ScoredActivity
Section titled “ScoredActivity”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.
| Field | Type | Default |
|---|---|---|
process_id | str | required |
activity_name | str | required |
impacts | LCIABatchResult | required |
parameter_set | int | None | None |
product_amount | float | None | None |
product_unit | str | None | None |
ScoringIndicator
Section titled “ScoringIndicator”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.
| Field | Type | Default |
|---|---|---|
category | str | required |
value | float | required |
SearchCounts
Section titled “SearchCounts”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.
| Field | Type | Default |
|---|---|---|
processes | int | required |
products | int | required |
flows | int | required |
SearchResults
Section titled “SearchResults”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.
| Field | Type | Default |
|---|---|---|
results | list[~T] | required |
total | int | required |
offset | int | required |
limit | int | required |
has_more | bool | required |
search_time_ms | float | required |
_fetch | Optional[Callable[[int, int | None], dict]] | None |
_parse | Optional[Callable[[dict], ~T]] | None |
_fetched | list[~T] | list() |
_exhausted | bool | False |
Properties
Section titled “Properties”page_size
Section titled “page_size”Server-applied limit (page size for further fetches).
Methods
Section titled “Methods”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.
SensitivityResult
Section titled “SensitivityResult”Sensitivity analysis: baseline impact plus one entry per perturbation.
Returned by Client.compute_sensitivity. perturbed preserves
the order of the requested perturbations.
| Field | Type | Default |
|---|---|---|
baseline | LCIAResult | required |
perturbed | list[PerturbedResult] | required |
cutoff_inputs | list[CutoffInput] | list() |
withheld_cutoffs | list[WithheldCutoffs] | list() |
ServerVersion
Section titled “ServerVersion”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.
| Field | Type | Default |
|---|---|---|
version | str | required |
git_hash | str | required |
git_tag | str | None | required |
build_target | str | required |
wire_version | int | None | None |
data_version | str | None | None |
FreeParameter
Section titled “FreeParameter”A parameter of a ReducedModel: its parameter.value is the default.
| Field | Type | Default |
|---|---|---|
parameter | Parameter | required |
process | str | None | None |
ModelScores
Section titled “ModelScores”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.
| Field | Type | Default |
|---|---|---|
scores | Any | required |
scoring_sets | dict[str, dict[str, Any]] | required |
ParameterName
Section titled “ParameterName”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.
| Field | Type | Default |
|---|---|---|
name | str | required |
process | str | None | None |
FormulaCheck
Section titled “FormulaCheck”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.
| Field | Type | Default |
|---|---|---|
value | float | None | required |
reads | list[str] | required |
warnings | list[str] | required |
problem | str | None | required |
Scenario
Section titled “Scenario”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.
| Field | Type | Default |
|---|---|---|
name | str | required |
parameters | list[ParameterValue] | required |
problem | str | None | None |
shipped | bool | False |
FormulaFunction
Section titled “FormulaFunction”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.
| Field | Type | Default |
|---|---|---|
name | str | required |
form | str | required |
usage | str | required |
meaning | str | required |
example | str | required |
value | float | required |
FormulaLanguage
Section titled “FormulaLanguage”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.
| Field | Type | Default |
|---|---|---|
functions | list[FormulaFunction] | required |
operators | list[list[str]] | required |
rules | list[str] | required |
ParameterValue
Section titled “ParameterValue”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.
| Field | Type | Default |
|---|---|---|
name | str | required |
value | float | required |
process | str | None | None |
Methods
Section titled “Methods”ParameterValue.to_wire()
Section titled “ParameterValue.to_wire()”Serialise to the wire shape consumed by SubstitutionRequest.
ReducedModel
Section titled “ReducedModel”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.
| Field | Type | Default |
|---|---|---|
process_id | str | required |
methods | list[dict] | required |
exclude_long_term | bool | required |
baseline | list[float] | required |
parameters | list[FreeParameter] | required |
processes | list[dict] | required |
suppliers | list[dict] | required |
scoring_sets | list[dict] | required |
Methods
Section titled “Methods”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.
SetAmount
Section titled “SetAmount”The lines to restate, and what to restate them to.
| Field | Type | Default |
|---|---|---|
select | ExchangeSelector | required |
amount | float | required |
SetFormula
Section titled “SetFormula”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.
| Field | Type | Default |
|---|---|---|
select | ExchangeSelector | required |
formula | str | None | required |
SetDryMass
Section titled “SetDryMass”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.
| Field | Type | Default |
|---|---|---|
product | str | required |
amount | float | None | required |
unit | str | ’kg’ |
SetSupplier
Section titled “SetSupplier”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.
| Field | Type | Default |
|---|---|---|
select | ExchangeSelector | required |
provider | str | required |
SetWetMass
Section titled “SetWetMass”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.
| Field | Type | Default |
|---|---|---|
product | str | required |
amount | float | None | required |
unit | str | ’kg’ |
ActivityEdit
Section titled “ActivityEdit”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.
| Field | Type | Default |
|---|---|---|
process_id | str | required |
remove | collections.abc.Sequence[ExchangeSelector] | () |
set_amounts | collections.abc.Sequence[SetAmount] | () |
add_inputs | collections.abc.Sequence[TechInput] | () |
add_biosphere | collections.abc.Sequence[BioExchange] | () |
add_waste_outputs | collections.abc.Sequence[WasteOutput] | () |
name | str | None | None |
location | str | None | None |
description | list[str] | None | None |
set_parameters | collections.abc.Sequence[SetParameter] | () |
set_formulas | collections.abc.Sequence[SetFormula] | () |
set_prices | collections.abc.Sequence[SetPrice] | () |
set_dry_masses | collections.abc.Sequence[SetDryMass] | () |
set_wet_masses | collections.abc.Sequence[SetWetMass] | () |
set_suppliers | collections.abc.Sequence[SetSupplier] | () |
remove_parameters | collections.abc.Sequence[str] | () |
Methods
Section titled “Methods”ActivityEdit.fields()
Section titled “ActivityEdit.fields()”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.
SetPrice
Section titled “SetPrice”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.
| Field | Type | Default |
|---|---|---|
product | str | required |
amount | float | None | required |
currency | str | ” |
SetParameter
Section titled “SetParameter”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.
| Field | Type | Default |
|---|---|---|
name | str | required |
value | float | None | None |
formula | str | None | None |
unit | str | None | None |
description | str | None | None |
uncertainty | Uncertainty | None | None |
Substitution
Section titled “Substitution”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.
| Field | Type | Default |
|---|---|---|
from_pid | str | required |
to_pid | str | required |
consumer | str | None | None |
Methods
Section titled “Methods”Substitution.to_wire()
Section titled “Substitution.to_wire()”Serialise to the wire shape consumed by SubstitutionRequest.
SummaryChange
Section titled “SummaryChange”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.
| Field | Type | Default |
|---|---|---|
field | str | required |
before | str | float | DatasetDates | list[str] | None | required |
after | str | float | DatasetDates | list[str] | None | required |
SupplierClaim
Section titled “SupplierClaim”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.
| Field | Type | Default |
|---|---|---|
kind | ClaimKind | required |
value | str | int | None | None |
SupplyChain
Section titled “SupplyChain”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.
| Field | Type | Default |
|---|---|---|
root | Activity | required |
total_activities | int | required |
filtered_activities | int | required |
entries | list[SupplyChainEntry] | list() |
edges | list[SupplyChainEdge] | list() |
withheld_databases | list[WithheldProcesses] | list() |
withheld_inputs | list[WithheldInput] | list() |
cutoff_inputs | list[CutoffInput] | list() |
withheld_cutoffs | list[WithheldCutoffs] | list() |
Properties
Section titled “Properties”has_more
Section titled “has_more”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.
SupplyChainEdge
Section titled “SupplyChainEdge”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).
| Field | Type | Default |
|---|---|---|
from_id | str | required |
from_db | str | required |
to_id | str | required |
to_db | str | required |
amount | float | required |
SupplyChainEntry
Section titled “SupplyChainEntry”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).
| Field | Type | Default |
|---|---|---|
process_id | str | required |
database_name | str | required |
activity_name | str | required |
location | str | required |
quantity | float | required |
unit | str | required |
scaling_factor | float | required |
depth | int | required |
upstream_count | int | required |
classifications | dict[str, str] | dict() |
TechInput
Section titled “TechInput”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.
| Field | Type | Default |
|---|---|---|
provider | str | required |
amount | float | required |
unit | str | None | None |
comment | str | None | None |
TechnosphereExchange
Section titled “TechnosphereExchange”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).
| Field | Type | Default |
|---|---|---|
flow_name | str | required |
amount | float | required |
unit | str | required |
role | TechRole | required |
target_activity_name | str | None | required |
target_location | str | None | required |
target_process_id | str | None | required |
comment | str | None | None |
supplier_claim | SupplierClaim | None | None |
formula | ExchangeFormula | None | None |
position | int | None | None |
selector | ExchangeSelector | None | None |
is_biosphere | bool | False |
is_waste | bool | False |
Properties
Section titled “Properties”is_input
Section titled “is_input”True for technosphere inputs (role is INPUT or REFERENCE_INPUT).
Lets callers split exchanges into inputs vs. outputs without knowing the four-role taxonomy.
is_reference
Section titled “is_reference”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.
UncomparedLine
Section titled “UncomparedLine”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).
| Field | Type | Default |
|---|---|---|
flow_name | str | required |
compartment | Compartment | None | required |
kind | str | required |
role | str | required |
reason | str | required |
base_units | list[str] | list() |
other_units | list[str] | list() |
base_flows | list[str] | list() |
other_flows | list[str] | list() |
UnmappedFlow
Section titled “UnmappedFlow”A method factor with no matching database flow (in MappingStatus).
| Field | Type | Default |
|---|---|---|
flow_ref | str | required |
flow_name | str | required |
direction | str | required |
compartment | str | None | None |
WasteExchange
Section titled “WasteExchange”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.
| Field | Type | Default |
|---|---|---|
flow_name | str | required |
amount | float | required |
unit | str | required |
is_input | bool | required |
target_activity_name | str | None | required |
target_location | str | None | required |
target_process_id | str | None | required |
comment | str | None | None |
role | WasteRole | None | None |
supplier_claim | SupplierClaim | None | None |
formula | ExchangeFormula | None | None |
position | int | None | None |
selector | ExchangeSelector | None | None |
is_biosphere | bool | False |
is_waste | bool | True |
Properties
Section titled “Properties”is_reference
Section titled “is_reference”Always False: waste flows never define an activity’s functional unit.
Treatment activities have a ReferenceInput instead, exposed
via TechnosphereExchange.
WasteOutput
Section titled “WasteOutput”One residue an activity hands to a treatment process.
provider names that treatment process, exactly as a TechInput
names its producer.
| Field | Type | Default |
|---|---|---|
provider | str | required |
amount | float | required |
unit | str | None | None |
comment | str | None | None |
Functions
Section titled “Functions”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 aliases
Section titled “Type aliases”Exchange
Section titled “Exchange”Type alias: Union[TechnosphereExchange, BiosphereExchange, WasteExchange].
RefDataKind
Section titled “RefDataKind”Type alias: Literal['flow-synonyms', 'compartment-mappings', 'units'].