pyvolca 0.1.0__py3-none-any.whl

pyvolca-0.1.0.dist-info/METADATA

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: pyvolca
+Version: 0.1.0
+Summary: Python client for VoLCA — Life Cycle Assessment engine
+Author-email: Christophe Combelles <ccomb@free.fr>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/ccomb/volca/tree/main/pyvolca
+Classifier: Development Status :: 3 - Alpha
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# pyvolca
+
+Python client for [VoLCA](https://github.com/ccomb/volca), a Life Cycle Assessment engine.
+
+## Install
+
+```bash
+pip install pyvolca
+```
+
+## Quick start
+
+```python
+from volca import Client
+
+c = Client(db="agribalyse-3.2", password="1234")
+
+# Search activities
+plants = c.search_activities(name="at plant")
+
+# Supply chain
+chain = c.get_supply_chain(plants[0].process_id, name="at farm")
+
+# LCIA with substitutions (Sherman-Morrison rank-1 updates)
+subs = [{"from": old_pid, "to": new_pid, "consumer": consumer_pid}]
+result = c.get_lcia(pid, method_id, substitutions=subs)
+```
+
+## License
+
+MIT

pyvolca-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pyvolca-0.1.0.dist-info/licenses/LICENSE,sha256=WeMtBxEZUylxEcqik6gaWgAdsGripQ-c_cXTwiqDjeU,1082
+volca/__init__.py,sha256=yDMJFF7TmK7V6UGogNFYkYyjBIkoqyS_ECXV9VFE9Rs,147
+volca/analysis.py,sha256=H9TStxiaS62gGivDcWidjbBdiia16LN1xTZFbc--S7k,8423
+volca/classify.py,sha256=KKhw-4P-NhTGeVmGiAv0hbBcMmNCbKzJ6phPcWGLWLs,2605
+volca/client.py,sha256=QTTZXgFAOSWFACl3BzQNwxHjjWV2S_Tb9qzkxT14WPQ,7537
+volca/server.py,sha256=EHExCR6RvqCjJMKtfqmcJqDOIzMvYEu7VBRpGwovuZ8,3919
+volca/types.py,sha256=fstNKKPxh53k9_vWA0A9t3Y_ksxmLt6DJIgFq1NO-Aw,2136
+pyvolca-0.1.0.dist-info/METADATA,sha256=G4WTjA0Wg7CJ43LCc32CU2lC-z64g5oXoU2251Ulhy4,1154
+pyvolca-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pyvolca-0.1.0.dist-info/top_level.txt,sha256=apMTTyWRE0IWimyd2DvNqN3yLakBs82TPxSYCz5CGJI,6
+pyvolca-0.1.0.dist-info/RECORD,,

pyvolca-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyvolca-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Christophe Combelles
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyvolca-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+volca

volca/__init__.py

@@ -0,0 +1,6 @@
+"""VoLCA Python client — Life Cycle Assessment engine."""
+
+from .client import Client
+from .server import Server
+
+__all__ = ["Client", "Server"]

volca/analysis.py

@@ -0,0 +1,269 @@
+"""Supply chain analysis helpers.
+
+Provides both generic classification-based grouping (using structured data
+from the database) and legacy semantic matching for databases without
+classification metadata.
+"""
+
+from dataclasses import dataclass, field
+
+from .classify import SemanticClassifier
+from .client import Client
+from .types import SupplyChainEntry
+
+
+def group_supply_chain_by_classification(
+    client: Client, process_id: str, prefix: str | None = None, limit: int = 1000
+) -> dict[str, list[SupplyChainEntry]]:
+    """Group supply chain entries by their classification path.
+
+    If prefix given (e.g. 'Agricultural\\Animal feed'), only entries
+    matching that prefix are included.
+    """
+    chain = client.get_supply_chain(process_id, limit=limit)
+    groups: dict[str, list[SupplyChainEntry]] = {}
+    for entry in chain.entries:
+        cat = entry.classifications.get("Category", "")
+        if not cat:
+            cat = "(unclassified)"
+        if prefix and not cat.startswith(prefix):
+            continue
+        groups.setdefault(cat, []).append(entry)
+    return groups
+
+
+# -- Legacy semantic matching (for databases without classification data) --
+
+# Reference phrases for semantic matching
+ANIMAL_PHRASES = [
+    "live animal at farm gate",
+    "livestock for slaughter at farm",
+]
+
+FEED_PHRASES = [
+    "animal feed ingredient for livestock",
+]
+
+FEED_CATEGORIES = [
+    "grazed grass/pasture",
+    "hay/dried forage",
+    "silage maize",
+    "cereal grain",
+    "soybean meal",
+    "rapeseed meal",
+    "sunflower meal",
+    "compound feed/premix",
+    "milk for calf",
+    "amino acids/additives",
+    "DDGS/co-products",
+]
+
+
+# -- Exchange accessors (handle the nested API response structure) --
+
+def _exch_name(inp: dict) -> str:
+    return inp.get("edFlow", {}).get("flowName", "")
+
+
+def _exch_amount(inp: dict) -> float:
+    exch = inp.get("edExchange", {})
+    return abs(float(exch.get("techAmount", 0) or exch.get("bioAmount", 0)))
+
+
+def _exch_unit(inp: dict) -> str:
+    return inp.get("edExchangeUnitName", "")
+
+
+def _exch_linked_id(inp: dict) -> str:
+    target = inp.get("edTargetActivity")
+    return target.get("prsId", "") if target else ""
+
+
+@dataclass
+class AnimalCandidate:
+    process_id: str
+    name: str
+    location: str
+    score: float
+    quantity: float
+    unit: str
+
+
+@dataclass
+class FeedInput:
+    name: str
+    category: str
+    category_score: float
+    amount: float
+    unit: str
+
+
+@dataclass
+class SubAnimal:
+    process_id: str
+    name: str
+    amount: float
+    unit: str
+    feeds: list[FeedInput] = field(default_factory=list)
+
+
+def find_animal_candidates(
+    client: Client,
+    process_id: str,
+    classifier: SemanticClassifier,
+    top_k: int = 5,
+) -> list[AnimalCandidate]:
+    """Find live animal candidates in a product's supply chain.
+
+    Pre-filters to "at farm" entries (structural LCA marker), then ranks
+    by semantic similarity to animal reference phrases.
+    """
+    chain = client.get_supply_chain(process_id, limit=1000)
+    # Pre-filter: "at farm" processes, excluding feed/processing/slaughter
+    exclude = {"feed", "slaughter", "processing", "manure", "housing", "emission"}
+    farm_entries = [
+        e for e in chain.entries
+        if "at farm" in e.name.lower()
+        and not any(w in e.name.lower() for w in exclude)
+    ]
+    if not farm_entries:
+        farm_entries = chain.entries  # fallback to full chain
+    names = [e.name for e in farm_entries]
+    ranked = classifier.rank_by_similarity(names, ANIMAL_PHRASES, top_k=top_k)
+    return [
+        AnimalCandidate(
+            process_id=farm_entries[i].process_id,
+            name=name,
+            location=farm_entries[i].location,
+            score=score,
+            quantity=farm_entries[i].quantity,
+            unit=farm_entries[i].unit,
+        )
+        for i, name, score in ranked
+    ]
+
+
+def _is_sub_animal(name: str) -> bool:
+    """Check if an input name looks like a sub-animal process.
+
+    Sub-animals are "at farm gate" processes that are not feed or supplements.
+    We check the beginning of the name (before the first comma) to avoid
+    false exclusions on names like "Cull cow, ..., silage maize 30%, at farm".
+    """
+    low = name.lower()
+    if "at farm" not in low:
+        return False
+    # Check only the first part of the name (the main subject)
+    subject = low.split(",")[0].strip()
+    feed_terms = {"feed", "grain", "straw", "meal", "silage", "hay", "oil",
+                  "lysine", "methionine", "tryptophane", "ddgs", "seed",
+                  "reproductive", "alfalfa", "rapeseed", "soybean", "sunflower",
+                  "wheat", "maize", "barley"}
+    return not any(w in subject for w in feed_terms)
+
+
+def detect_aggregation(client: Client, animal_id: str) -> tuple[bool, list[dict]]:
+    """Detect if an animal process aggregates sub-animals or has direct feed.
+
+    Sub-animals are "at farm gate" kg-unit inputs that aren't feed.
+    Returns (is_aggregated, sub_animal_inputs).
+    """
+    inputs = client.get_inputs(animal_id)
+    linked = [inp for inp in inputs if _exch_linked_id(inp)]
+    if len(linked) <= 1:
+        return False, linked
+    sub_animals = [
+        inp for inp in linked
+        if _exch_unit(inp) == "kg" and _is_sub_animal(_exch_name(inp))
+    ]
+    return len(sub_animals) > 1, sub_animals
+
+
+def get_feed_inputs(
+    client: Client,
+    animal_id: str,
+    classifier: SemanticClassifier,
+    threshold: float = 0.4,
+) -> list[FeedInput]:
+    """Identify and categorize feed inputs for a single animal process."""
+    inputs = client.get_inputs(animal_id)
+    names = [_exch_name(inp) for inp in inputs]
+    if not names:
+        return []
+
+    # Filter to feed-like inputs
+    feed_matches = classifier.filter_by_similarity(names, FEED_PHRASES, threshold)
+    if not feed_matches:
+        return []
+
+    feed_indices = {i for i, _, _ in feed_matches}
+    feed_names = [names[i] for i in sorted(feed_indices)]
+    feed_inputs_raw = [inputs[i] for i in sorted(feed_indices)]
+
+    # Classify into categories
+    classified = classifier.classify(feed_names, FEED_CATEGORIES)
+    return [
+        FeedInput(
+            name=name,
+            category=cat,
+            category_score=score,
+            amount=_exch_amount(feed_inputs_raw[j]),
+            unit=_exch_unit(feed_inputs_raw[j]),
+        )
+        for j, (name, cat, score) in enumerate(classified)
+    ]
+
+
+def get_reference_amount(client: Client, process_id: str) -> float:
+    """Get the reference product amount for normalization."""
+    activity = client.get_activity(process_id)
+    products = activity.get("piActivity", {}).get("pfaAllProducts", [])
+    if products:
+        return float(products[0].get("prsProductAmount", 1.0))
+    return float(activity.get("prsProductAmount", 1.0))
+
+
+def analyze_animal_feed(
+    client: Client,
+    animal_id: str,
+    classifier: SemanticClassifier,
+    feed_threshold: float = 0.4,
+) -> tuple[list[SubAnimal], float]:
+    """Full feed analysis: detect aggregation, get feeds for each (sub-)animal.
+
+    Returns (sub_animals_with_feeds, reference_amount).
+    """
+    ref_amount = get_reference_amount(client, animal_id)
+    is_agg, sub_inputs = detect_aggregation(client, animal_id)
+
+    if is_agg:
+        sub_animals = []
+        for inp in sub_inputs:
+            sub_id = _exch_linked_id(inp)
+            sub_ref = get_reference_amount(client, sub_id)
+            feeds = get_feed_inputs(client, sub_id, classifier, feed_threshold)
+            # Normalize feed amounts: per kg of sub-animal output
+            for f in feeds:
+                f.amount = f.amount / sub_ref if sub_ref > 0 else f.amount
+            sub = SubAnimal(
+                process_id=sub_id,
+                name=_exch_name(inp),
+                amount=_exch_amount(inp),
+                unit=_exch_unit(inp),
+                feeds=feeds,
+            )
+            sub_animals.append(sub)
+        return sub_animals, ref_amount
+    else:
+        # Single animal — feeds are direct inputs, normalize per kg
+        feeds = get_feed_inputs(client, animal_id, classifier, feed_threshold)
+        for f in feeds:
+            f.amount = f.amount / ref_amount if ref_amount > 0 else f.amount
+        single = SubAnimal(
+            process_id=animal_id,
+            name="(direct)",
+            amount=ref_amount,
+            unit="kg",
+            feeds=feeds,
+        )
+        return [single], ref_amount

volca/classify.py

@@ -0,0 +1,65 @@
+"""Semantic classification using sentence-transformers embeddings."""
+
+import numpy as np
+from sentence_transformers import SentenceTransformer
+
+
+class SemanticClassifier:
+    """Classify and rank text strings by cosine similarity to reference phrases.
+
+    Uses all-mpnet-base-v2 (768 dims) for high-quality semantic matching.
+    Single model instance handles all classification tasks.
+    """
+
+    def __init__(self, model_name: str = "all-mpnet-base-v2"):
+        self._model = SentenceTransformer(model_name)
+
+    def _cosine_similarity(self, a: np.ndarray, b: np.ndarray) -> np.ndarray:
+        """Cosine similarity between row vectors of a and b."""
+        a_norm = a / np.linalg.norm(a, axis=1, keepdims=True)
+        b_norm = b / np.linalg.norm(b, axis=1, keepdims=True)
+        return a_norm @ b_norm.T
+
+    def rank_by_similarity(
+        self, names: list[str], reference_phrases: list[str], top_k: int = 5
+    ) -> list[tuple[int, str, float]]:
+        """Rank names by max similarity to any reference phrase.
+
+        Returns list of (original_index, name, score) sorted by score descending.
+        """
+        if not names:
+            return []
+        name_emb = self._model.encode(names)
+        ref_emb = self._model.encode(reference_phrases)
+        sims = self._cosine_similarity(name_emb, ref_emb)
+        max_scores = sims.max(axis=1)
+        ranked_indices = np.argsort(-max_scores)[:top_k]
+        return [(int(i), names[i], float(max_scores[i])) for i in ranked_indices]
+
+    def classify(
+        self, names: list[str], categories: list[str]
+    ) -> list[tuple[str, str, float]]:
+        """Assign each name to its closest category.
+
+        Returns list of (name, category, score) preserving input order.
+        """
+        if not names:
+            return []
+        name_emb = self._model.encode(names)
+        cat_emb = self._model.encode(categories)
+        sims = self._cosine_similarity(name_emb, cat_emb)
+        best_cat = sims.argmax(axis=1)
+        return [
+            (names[i], categories[best_cat[i]], float(sims[i, best_cat[i]]))
+            for i in range(len(names))
+        ]
+
+    def filter_by_similarity(
+        self, names: list[str], reference_phrases: list[str], threshold: float = 0.3
+    ) -> list[tuple[int, str, float]]:
+        """Return names above similarity threshold to any reference phrase.
+
+        Returns list of (original_index, name, score) sorted by score descending.
+        """
+        ranked = self.rank_by_similarity(names, reference_phrases, top_k=len(names))
+        return [(i, n, s) for i, n, s in ranked if s >= threshold]

volca/client.py

@@ -0,0 +1,219 @@
+"""HTTP client for all VoLCA API endpoints."""
+
+import requests
+
+from .types import Activity, SupplyChain
+
+
+def _substitution_body(substitutions: list[dict]) -> dict:
+    """Build request body for substitution endpoints."""
+    return {
+        "srSubstitutions": [
+            {"subFrom": s["from"], "subTo": s["to"], "subConsumer": s["consumer"]}
+            for s in substitutions
+        ]
+    }
+
+
+class Client:
+    """HTTP client for the VoLCA REST 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, get_lcia,
+    and get_lcia_batch to compute results with Sherman-Morrison rank-1 updates::
+
+        subs = [{"from": old_pid, "to": new_pid, "consumer": consumer_pid}]
+        result = c.get_lcia(pid, method_id, substitutions=subs)
+    """
+
+    def __init__(self, base_url: str = "http://localhost:8081", db: str = "", password: str = ""):
+        self.base_url = base_url.rstrip("/")
+        self.db = db
+        self._session = requests.Session()
+        if password:
+            self._session.headers["Authorization"] = f"Bearer {password}"
+
+    def _db_url(self, path: str) -> str:
+        return f"{self.base_url}/api/v1/db/{self.db}/{path}"
+
+    def _api_url(self, path: str) -> str:
+        return f"{self.base_url}/api/v1/{path}"
+
+    def use(self, db_name: str) -> "Client":
+        """Return a new client targeting a different database (shares session)."""
+        c = Client.__new__(Client)
+        c.base_url = self.base_url
+        c.db = db_name
+        c._session = self._session
+        return c
+
+    # -- Server info --
+
+    def get_version(self) -> dict:
+        """Return server version info (version, gitHash, gitTag, buildTarget)."""
+        r = self._session.get(self._api_url("version"))
+        r.raise_for_status()
+        return r.json()
+
+    # -- Database management --
+
+    def list_databases(self) -> list[dict]:
+        r = self._session.get(self._api_url("db"))
+        r.raise_for_status()
+        return r.json()["dlrDatabases"]
+
+    def load_database(self, db_name: str) -> dict:
+        r = self._session.post(self._api_url(f"db/{db_name}/load"))
+        r.raise_for_status()
+        return r.json()
+
+    def unload_database(self, db_name: str) -> dict:
+        r = self._session.post(self._api_url(f"db/{db_name}/unload"))
+        r.raise_for_status()
+        return r.json()
+
+    # -- Search --
+
+    def search_activities(
+        self,
+        name: str | None = None,
+        geo: str | None = None,
+        product: str | None = None,
+        classification: str | None = None,
+        classification_value: str | None = None,
+        limit: int | None = None,
+        offset: int = 0,
+    ) -> list[Activity]:
+        params: dict = {"offset": offset}
+        if limit is not None:
+            params["limit"] = limit
+        if name:
+            params["name"] = name
+        if geo:
+            params["geo"] = geo
+        if product:
+            params["product"] = product
+        if classification:
+            params["classification"] = classification
+        if classification_value:
+            params["classification-value"] = classification_value
+        r = self._session.get(self._db_url("activities"), params=params)
+        r.raise_for_status()
+        return [Activity.from_json(a) for a in r.json()["srResults"]]
+
+    def get_classifications(self) -> list[dict]:
+        """List all classification systems and their values for the current database."""
+        r = self._session.get(self._db_url("classifications"))
+        r.raise_for_status()
+        return r.json()
+
+    def search_flows(self, query: str | None = None, limit: int | None = None) -> list[dict]:
+        params: dict = {}
+        if limit is not None:
+            params["limit"] = limit
+        if query:
+            params["q"] = query
+        r = self._session.get(self._db_url("flows"), params=params)
+        r.raise_for_status()
+        return r.json()["srResults"]
+
+    # -- Activity details --
+
+    def get_activity(self, process_id: str) -> dict:
+        r = self._session.get(self._db_url(f"activity/{process_id}"))
+        r.raise_for_status()
+        return r.json()
+
+    def get_inputs(self, process_id: str) -> list[dict]:
+        r = self._session.get(self._db_url(f"activity/{process_id}/inputs"))
+        r.raise_for_status()
+        return r.json()
+
+    def get_outputs(self, process_id: str) -> list[dict]:
+        r = self._session.get(self._db_url(f"activity/{process_id}/outputs"))
+        r.raise_for_status()
+        return r.json()
+
+    # -- Supply chain (scaling vector based) --
+
+    def get_supply_chain(
+        self,
+        process_id: str,
+        name: str | None = None,
+        limit: int | None = None,
+        min_quantity: float = 0,
+        substitutions: list[dict] | None = None,
+    ) -> SupplyChain:
+        params: dict = {}
+        if limit is not None:
+            params["limit"] = limit
+        if name:
+            params["name"] = name
+        if min_quantity > 0:
+            params["min-quantity"] = min_quantity
+        url = self._db_url(f"activity/{process_id}/supply-chain")
+        if substitutions:
+            r = self._session.post(url, params=params, json=_substitution_body(substitutions))
+        else:
+            r = self._session.get(url, params=params)
+        r.raise_for_status()
+        return SupplyChain.from_json(r.json())
+
+    # -- Consumers (reverse supply chain) --
+
+    def get_consumers(
+        self,
+        process_id: str,
+        name: str | None = None,
+        limit: int | None = None,
+    ) -> list[Activity]:
+        """Find all activities that transitively depend on this supplier."""
+        params: dict = {}
+        if name:
+            params["name"] = name
+        if limit is not None:
+            params["limit"] = limit
+        r = self._session.get(self._db_url(f"activity/{process_id}/consumers"), params=params)
+        r.raise_for_status()
+        return [Activity.from_json(a) for a in r.json()]
+
+    # -- Tree --
+
+    def get_tree(self, process_id: str) -> dict:
+        r = self._session.get(self._db_url(f"activity/{process_id}/tree"))
+        r.raise_for_status()
+        return r.json()
+
+    # -- Inventory & LCIA --
+
+    def get_inventory(self, process_id: str, substitutions: list[dict] | None = None) -> dict:
+        url = self._db_url(f"activity/{process_id}/inventory")
+        if substitutions:
+            r = self._session.post(url, json=_substitution_body(substitutions))
+        else:
+            r = self._session.get(url)
+        r.raise_for_status()
+        return r.json()
+
+    def get_lcia(self, process_id: str, method_id: str, substitutions: list[dict] | None = None) -> dict:
+        url = self._db_url(f"activity/{process_id}/lcia/{method_id}")
+        if substitutions:
+            r = self._session.post(url, json=_substitution_body(substitutions))
+        else:
+            r = self._session.get(url)
+        r.raise_for_status()
+        return r.json()
+
+    def get_lcia_batch(self, process_id: str, collection: str, substitutions: list[dict] | None = None) -> dict:
+        url = self._db_url(f"activity/{process_id}/lcia-batch/{collection}")
+        if substitutions:
+            r = self._session.post(url, json=_substitution_body(substitutions))
+        else:
+            r = self._session.get(url)
+        r.raise_for_status()
+        return r.json()

volca/server.py

@@ -0,0 +1,132 @@
+"""Server lifecycle management for VoLCA."""
+
+import shutil
+import subprocess
+import time
+from pathlib import Path
+
+import requests
+
+try:
+    import tomllib  # Python 3.11+
+except ModuleNotFoundError:
+    import tomli as tomllib  # type: ignore[no-redef]
+
+
+class 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")
+    """
+
+    def __init__(self, config: str = "volca.toml", port: int = 0, binary: str = "volca"):
+        self.config = config
+        self.binary = binary
+        self._process: subprocess.Popen | None = None
+
+        # Read port and password from config
+        cfg = self._read_config()
+        server_cfg = cfg.get("server", {})
+        self.port = port or server_cfg.get("port", 8081)
+        self.password = server_cfg.get("password", "")
+
+    @property
+    def base_url(self) -> str:
+        return f"http://localhost:{self.port}"
+
+    def _read_config(self) -> dict:
+        """Read the TOML config file."""
+        try:
+            with open(self.config, "rb") as f:
+                return tomllib.load(f)
+        except FileNotFoundError:
+            return {}
+
+    def _auth_headers(self) -> dict:
+        if self.password:
+            return {"Authorization": f"Bearer {self.password}"}
+        return {}
+
+    def _find_binary(self) -> str:
+        """Find the volca binary: explicit path, package bin/, or PATH."""
+        if Path(self.binary).exists():
+            return self.binary
+        found = shutil.which(self.binary)
+        if found:
+            return found
+        # Try common locations
+        for candidate in ["./volca", "./dist/volca"]:
+            if Path(candidate).exists():
+                return candidate
+        raise FileNotFoundError(
+            f"Cannot find '{self.binary}' binary. "
+            "Set binary= parameter or add volca to PATH."
+        )
+
+    def is_alive(self) -> bool:
+        """Health check — GET /api/v1/db, return True if 200."""
+        try:
+            r = requests.get(
+                f"{self.base_url}/api/v1/db",
+                headers=self._auth_headers(),
+                timeout=2,
+            )
+            return r.status_code == 200
+        except requests.ConnectionError:
+            return False
+
+    def start(self, idle_timeout: int = 300, wait_timeout: int = 120) -> None:
+        """Start server if not running. Wait until ready."""
+        if self.is_alive():
+            return
+
+        binary = self._find_binary()
+        cmd = [
+            binary,
+            "--config", self.config,
+            "server",
+            "--port", str(self.port),
+            "--idle-timeout", str(idle_timeout),
+        ]
+        self._process = subprocess.Popen(
+            cmd,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+
+        # Poll until server is ready
+        deadline = time.monotonic() + wait_timeout
+        while time.monotonic() < deadline:
+            if self.is_alive():
+                return
+            time.sleep(0.5)
+
+        raise TimeoutError(
+            f"Server did not become ready within {wait_timeout}s"
+        )
+
+    def stop(self) -> None:
+        """Stop the server via shutdown endpoint, then terminate process."""
+        try:
+            requests.post(
+                f"{self.base_url}/api/v1/shutdown",
+                headers=self._auth_headers(),
+                timeout=5,
+            )
+        except requests.ConnectionError:
+            pass
+        if self._process:
+            self._process.terminate()
+            self._process.wait(timeout=10)
+            self._process = None
+
+    def __enter__(self) -> "Server":
+        self.start()
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.stop()

volca/types.py

@@ -0,0 +1,83 @@
+"""Data types for VoLCA API responses."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Activity:
+    process_id: str
+    name: str
+    location: str
+    product: str
+    product_amount: float
+    product_unit: str
+
+    @classmethod
+    def from_json(cls, d: dict) -> "Activity":
+        return cls(
+            process_id=d["prsId"],
+            name=d["prsName"],
+            location=d["prsLocation"],
+            product=d["prsProduct"],
+            product_amount=d["prsProductAmount"],
+            product_unit=d["prsProductUnit"],
+        )
+
+
+@dataclass
+class SupplyChainEntry:
+    process_id: str
+    name: str
+    location: str
+    quantity: float
+    unit: str
+    scaling_factor: float
+    classifications: dict[str, str] = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, d: dict) -> "SupplyChainEntry":
+        return cls(
+            process_id=d["sceProcessId"],
+            name=d["sceName"],
+            location=d["sceLocation"],
+            quantity=d["sceQuantity"],
+            unit=d["sceUnit"],
+            scaling_factor=d["sceScalingFactor"],
+            classifications=d.get("sceClassifications", {}),
+        )
+
+
+@dataclass
+class SupplyChainEdge:
+    from_id: str
+    to_id: str
+    amount: float
+
+    @classmethod
+    def from_json(cls, d: dict) -> "SupplyChainEdge":
+        return cls(
+            from_id=d["sceEdgeFrom"],
+            to_id=d["sceEdgeTo"],
+            amount=d["sceEdgeAmount"],
+        )
+
+
+@dataclass
+class SupplyChain:
+    root: Activity
+    total_activities: int
+    filtered_activities: int
+    entries: list[SupplyChainEntry] = field(default_factory=list)
+    edges: list[SupplyChainEdge] = field(default_factory=list)
+
+    @classmethod
+    def from_json(cls, d: dict) -> "SupplyChain":
+        return cls(
+            root=Activity.from_json(d["scrRoot"]),
+            total_activities=d["scrTotalActivities"],
+            filtered_activities=d["scrFilteredActivities"],
+            entries=[SupplyChainEntry.from_json(e) for e in d["scrSupplyChain"]],
+            edges=[SupplyChainEdge.from_json(e) for e in d.get("scrEdges", [])],
+        )
+
+