ecosemantic-view 0.1.8__py3-none-any.whl

ecosemantic/view/__init__.py

@@ -0,0 +1 @@
+"""The browser view the server serves: its API, its event stream, its page and its panels."""

ecosemantic/view/activity.py

@@ -0,0 +1,99 @@
+"""The activity routes: the agents, their calls, the trail of a log entry, an agent's open
+trail, a call run again, and a system's calculations."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from datetime import datetime
+
+from fastmcp import FastMCP
+from pydantic import BaseModel
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+from starlette.routing import Route
+
+from ecosemantic.errors import Invalid
+from ecosemantic.mcp.context import ServerContext
+from ecosemantic.mcp.envelopes import as_uuid
+from ecosemantic.mcp.recording import current_hash
+from ecosemantic.ports.types import open_trail, trail
+from ecosemantic.view.api import IMPACT_TOOL, structured
+from ecosemantic.view.handling import answering
+
+
+def _listed(items: Sequence[BaseModel]) -> JSONResponse:
+    return JSONResponse({"value": [item.model_dump(mode="json") for item in items]})
+
+
+def _time(text: str | None) -> datetime | None:
+    if text is None:
+        return None
+    try:
+        return datetime.fromisoformat(text)
+    except ValueError as error:
+        raise Invalid(f"after={text!r} is not an ISO 8601 time") from error
+
+
+def routes(server: FastMCP, context: ServerContext) -> list[Route]:
+    """The six activity routes."""
+
+    @answering
+    async def agents(request: Request) -> Response:
+        return _listed(await context.activity.list_agents())
+
+    @answering
+    async def calls(request: Request) -> Response:
+        query = request.query_params
+        named = query.get("product_system_id")
+        return _listed(
+            await context.activity.list_calls(
+                agent=query.get("agent"),
+                product_system_id=as_uuid(named) if named is not None else None,
+                after=_time(query.get("after")),
+            )
+        )
+
+    @answering
+    async def entry_trail(request: Request) -> Response:
+        system_id = as_uuid(request.path_params["id"])
+        await context.storage.get_product_system(system_id)
+        recorded = await context.activity.list_calls()
+        return _listed(trail(recorded, system_id, request.path_params["seq"]))
+
+    @answering
+    async def calculations(request: Request) -> Response:
+        system_id = as_uuid(request.path_params["id"])
+        await context.storage.get_product_system(system_id)
+        recorded = await context.activity.list_calls(product_system_id=system_id)
+        return _listed([call for call in reversed(recorded) if call.tool == IMPACT_TOOL])
+
+    @answering
+    async def agent_trail(request: Request) -> Response:
+        recorded = await context.activity.list_calls()
+        named = request.query_params.get("product_system_id")
+        system_id = as_uuid(named) if named is not None else None
+        return _listed(open_trail(recorded, request.path_params["agent"], system_id))
+
+    @answering
+    async def rerun(request: Request) -> Response:
+        call = await context.activity.get_call(as_uuid(request.path_params["call_id"]))
+        if call.effect in ("write", "delete"):
+            raise Invalid(f"{call.tool} changes a model; the page reruns reads and calculations")
+        result = await structured(server, call.tool, call.arguments, started=True)
+        hash_now = (
+            await current_hash(context.storage, call.product_system_id)
+            if call.product_system_id is not None
+            else None
+        )
+        return JSONResponse(
+            {"value": {"result": result, "at_hash": call.at_hash, "hash_now": hash_now}}
+        )
+
+    return [
+        Route("/api/agents", agents),
+        Route("/api/agents/{agent}/trail", agent_trail),
+        Route("/api/activity", calls),
+        Route("/api/activity/{call_id}/rerun", rerun, methods=["POST"]),
+        Route("/api/product-systems/{id}/log/{seq:int}/trail", entry_trail),
+        Route("/api/product-systems/{id}/calculations", calculations),
+    ]

ecosemantic/view/api.py

@@ -0,0 +1,303 @@
+"""The routes over the tools: each calls the tool the agent calls, through the in-process client."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping
+from importlib import metadata
+
+from fastmcp import Client, FastMCP
+from fastmcp.exceptions import ToolError
+from mcp.shared.exceptions import MCPError
+from mcp.types import INVALID_PARAMS, Implementation
+from pydantic import JsonValue, ValidationError
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+from starlette.routing import Route
+
+from ecosemantic.errors import Invalid
+from ecosemantic.mcp.context import ServerContext
+from ecosemantic.mcp.envelopes import Answer, Listing, as_uuid, envelope_of
+from ecosemantic.mcp.recording import STARTED, VIEW
+from ecosemantic.model.validation import anchors
+from ecosemantic.ports.types import Layout, LogEntry, RequestDraft
+from ecosemantic.view.handling import (
+    ToolRefused,
+    answering,
+    created,
+    envelope_response,
+    error_response,
+)
+
+GATE_PARAMETER = "token"
+IMPACT_TOOL = "calculate_impact"
+STARTED_PARAMETER = "started"
+
+
+async def structured(
+    server: FastMCP, name: str, arguments: Mapping[str, JsonValue], started: bool = False
+) -> dict[str, JsonValue]:
+    """A tool's structured content, or ToolRefused carrying its error as the envelope. A call the
+    server refuses as invalid parameters carries the invalid envelope. A call a person started is
+    marked so, and the recorder keeps such a calculation."""
+    try:
+        async with Client(
+            server,
+            client_info=Implementation(name=VIEW, version=metadata.version("ecosemantic-view")),
+        ) as client:
+            result = await client.call_tool(
+                name, dict(arguments), meta={STARTED: True} if started else None
+            )
+    except MCPError as error:
+        if error.code != INVALID_PARAMS:
+            raise
+        raise ToolRefused(error_response(Invalid(f"{name}: {error.message}"))) from error
+    except ToolError as error:
+        raise ToolRefused(envelope_response(envelope_of(error))) from error
+    return result.structured_content
+
+
+async def call_tool(
+    server: FastMCP, name: str, arguments: Mapping[str, JsonValue], started: bool = False
+) -> Response:
+    """One tool call rendered as an HTTP response: its structured content, or its error."""
+    try:
+        return JSONResponse(await structured(server, name, arguments, started))
+    except ToolRefused as refused:
+        return refused.response
+
+
+async def json_object(request: Request) -> dict[str, JsonValue]:
+    """The request body as a JSON object; Invalid when it is not one."""
+    try:
+        body = await request.json()
+    except ValueError as error:
+        raise Invalid("the body is not JSON") from error
+    if not isinstance(body, dict):
+        raise Invalid("the body is not a JSON object")
+    return body
+
+
+def arguments(query: Mapping[str, str]) -> dict[str, JsonValue]:
+    """Query parameters as tool arguments; the token stays out, the tool's schema types the rest."""
+    return {key: value for key, value in query.items() if key != GATE_PARAMETER}
+
+
+def routes(server: FastMCP, context: ServerContext) -> list[Route]:
+    """Every JSON route under /api, in the order the spec lists them."""
+
+    async def databases(request: Request) -> Response:
+        return await call_tool(server, "list_databases", {})
+
+    async def vocabulary(request: Request) -> Response:
+        params = request.path_params
+        return await call_tool(
+            server, "list_vocabulary", {"database": params["name"], "kind": params["kind"]}
+        )
+
+    async def processes(request: Request) -> Response:
+        args = arguments(request.query_params)
+        return await call_tool(
+            server, "search_processes", {"database": request.path_params["name"], **args}
+        )
+
+    async def elementary_flows(request: Request) -> Response:
+        args = arguments(request.query_params)
+        return await call_tool(
+            server, "search_elementary_flows", {"database": request.path_params["name"], **args}
+        )
+
+    async def methods(request: Request) -> Response:
+        args = arguments(request.query_params)
+        return await call_tool(
+            server, "search_methods", {"database": request.path_params["name"], **args}
+        )
+
+    async def process(request: Request) -> Response:
+        params = request.path_params
+        return await call_tool(
+            server,
+            "get_background_process",
+            {"database": params["name"], "process_id": params["ref"], "exchanges": True},
+        )
+
+    async def elementary_flow(request: Request) -> Response:
+        params = request.path_params
+        return await call_tool(
+            server, "get_elementary_flow", {"database": params["name"], "flow_id": params["ref"]}
+        )
+
+    async def systems(request: Request) -> Response:
+        return await call_tool(server, "list_product_systems", {})
+
+    async def system(request: Request) -> Response:
+        args = arguments(request.query_params)
+        return await call_tool(
+            server,
+            "get_product_system",
+            {"product_system_id": request.path_params["id"], "variant": args.get("variant")},
+        )
+
+    async def parameters(request: Request) -> Response:
+        args = arguments(request.query_params)
+        content_hash = args.pop("hash", None)
+        return await call_tool(
+            server,
+            "get_parameters",
+            {"product_system_id": request.path_params["id"], "content_hash": content_hash},
+        )
+
+    @answering
+    async def log(request: Request) -> Response:
+        entries: list[LogEntry] = []
+        cursor: str | None = None
+        while True:
+            page = Listing[LogEntry].model_validate(
+                await structured(
+                    server,
+                    "get_product_system_log",
+                    {"product_system_id": request.path_params["id"], "cursor": cursor},
+                )
+            )
+            entries.extend(page.items)
+            cursor = page.next_cursor
+            if cursor is None:
+                return JSONResponse(Answer[list[LogEntry]](value=entries).model_dump(mode="json"))
+
+    @answering
+    async def version(request: Request) -> Response:
+        params = request.path_params
+        stored = await context.storage.get_version(as_uuid(params["id"]), params["hash"])
+        return JSONResponse(stored.model_dump(mode="json"))
+
+    @answering
+    async def system_anchors(request: Request) -> Response:
+        stored = await context.storage.get_product_system(as_uuid(request.path_params["id"]))
+        return JSONResponse(Answer[list[str]](value=anchors(stored)).model_dump(mode="json"))
+
+    async def validation(request: Request) -> Response:
+        args = arguments(request.query_params)
+        return await call_tool(
+            server,
+            "validate_product_system",
+            {"product_system_id": request.path_params["id"], **args},
+        )
+
+    async def server_details(request: Request) -> Response:
+        """The client that introduced itself, this package's version and the two directories."""
+        return JSONResponse(
+            {
+                "client": context.client or None,
+                "version": metadata.version("ecosemantic"),
+                "data_dir": str(context.data_dir),
+                "systems_dir": str(context.systems_dir),
+            }
+        )
+
+    def calculation(tool: str) -> Callable[[Request], Awaitable[Response]]:
+        @answering
+        async def handler(request: Request) -> Response:
+            body = await json_object(request)
+            return await call_tool(
+                server,
+                tool,
+                {"product_system_id": request.path_params["id"], **body},
+                started=request.query_params.get(STARTED_PARAMETER) == "true",
+            )
+
+        return handler
+
+    async def runs_listed(request: Request) -> Response:
+        return await call_tool(
+            server, "list_runs", {"product_system_id": request.path_params["id"]}
+        )
+
+    async def run_read(request: Request) -> Response:
+        return await call_tool(server, "get_run", {"run_id": request.path_params["run_id"]})
+
+    async def run_cancelled(request: Request) -> Response:
+        return await call_tool(server, "cancel_run", {"run_id": request.path_params["run_id"]})
+
+    async def requests_listed(request: Request) -> Response:
+        args = arguments(request.query_params)
+        return await call_tool(
+            server,
+            "list_requests",
+            {"product_system_id": request.path_params["id"], "open_only": False, **args},
+        )
+
+    @answering
+    async def request_posted(request: Request) -> Response:
+        body = await json_object(request)
+        system_id = as_uuid(request.path_params["id"])
+        try:
+            draft = RequestDraft.model_validate(
+                {
+                    "actor": {"kind": "person", "name": str(body.get("actor", ""))},
+                    "kind": body.get("kind"),
+                    "at_hash": body.get("at_hash", ""),
+                    "message": body.get("message", ""),
+                    "entity": body.get("entity"),
+                    "entity_id": body.get("entity_id"),
+                }
+            )
+        except ValidationError as exc:
+            raise Invalid(str(exc)) from exc
+        posted = await context.storage.post_request(system_id, draft)
+        return created(posted)
+
+    async def layout(request: Request) -> Response:
+        args = arguments(request.query_params)
+        return await call_tool(
+            server,
+            "graph_layout",
+            {"product_system_id": request.path_params["id"], "variant": args.get("variant")},
+        )
+
+    @answering
+    async def place(request: Request) -> Response:
+        body = await json_object(request)
+        return await call_tool(
+            server, "arrange_graph", {"product_system_id": request.path_params["id"], **body}
+        )
+
+    @answering
+    async def release(request: Request) -> Response:
+        system_id = as_uuid(request.path_params["id"])
+        await context.storage.put_layout(system_id, Layout())
+        args = arguments(request.query_params)
+        return await call_tool(
+            server,
+            "graph_layout",
+            {"product_system_id": str(system_id), "variant": args.get("variant")},
+        )
+
+    base = "/api/product-systems/{id}"
+    return [
+        Route("/api/server", server_details),
+        Route("/api/databases", databases),
+        Route("/api/databases/{name}/vocabulary/{kind}", vocabulary),
+        Route("/api/databases/{name}/processes", processes),
+        Route("/api/databases/{name}/elementary-flows", elementary_flows),
+        Route("/api/databases/{name}/elementary-flows/{ref}", elementary_flow),
+        Route("/api/databases/{name}/methods", methods),
+        Route("/api/databases/{name}/processes/{ref}", process),
+        Route("/api/product-systems", systems),
+        Route(base, system),
+        Route(f"{base}/parameters", parameters),
+        Route(f"{base}/log", log),
+        Route(f"{base}/versions/{{hash}}", version),
+        Route(f"{base}/validation", validation),
+        Route(f"{base}/anchors", system_anchors),
+        Route(f"{base}/impact", calculation(IMPACT_TOOL), methods=["POST"]),
+        Route(f"{base}/contributions", calculation("contribution_analysis"), methods=["POST"]),
+        Route(f"{base}/inventory", calculation("calculate_inventory"), methods=["POST"]),
+        Route(f"{base}/runs", runs_listed),
+        Route(f"{base}/runs", calculation("start_monte_carlo"), methods=["POST"]),
+        Route("/api/runs/{run_id}", run_read),
+        Route("/api/runs/{run_id}/cancel", run_cancelled, methods=["POST"]),
+        Route(f"{base}/requests", requests_listed),
+        Route(f"{base}/requests", request_posted, methods=["POST"]),
+        Route(f"{base}/layout", layout),
+        Route(f"{base}/layout", place, methods=["POST"]),
+        Route(f"{base}/layout", release, methods=["DELETE"]),
+    ]

ecosemantic/view/app.py

@@ -0,0 +1,159 @@
+"""The view application: the token gate, the routes and the page."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import hmac
+from collections.abc import AsyncIterator, Sequence
+from importlib import resources
+from pathlib import Path
+from urllib.parse import parse_qsl
+
+from fastmcp import FastMCP
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import FileResponse, HTMLResponse, Response
+from starlette.routing import BaseRoute, Mount, Route
+from starlette.staticfiles import StaticFiles
+from starlette.types import ASGIApp, Lifespan, Receive, Scope, Send
+
+from ecosemantic.errors import NotFound, Unauthorised, Unavailable
+from ecosemantic.events import pump_installs, pump_runs, pump_storage
+from ecosemantic.mcp.context import ServerContext
+from ecosemantic.view.activity import routes as activity_routes
+from ecosemantic.view.api import GATE_PARAMETER
+from ecosemantic.view.api import routes as api_routes
+from ecosemantic.view.credentials import routes as credential_routes
+from ecosemantic.view.handling import answering, error_response
+from ecosemantic.view.installs import routes as install_routes
+from ecosemantic.view.olca import routes as olca_routes
+from ecosemantic.view.stream import routes as stream_routes
+from ecosemantic.view.tables import routes as tables_routes
+
+UNBUILT = (
+    "<!doctype html><title>EcoSemantic</title>"
+    "<p>The page is not built in this installation. The API answers under /api.</p>"
+)
+
+
+class TokenGate:
+    """Refuse a call under /api, or under a prefix the caller gates, whose token query parameter
+    is not the process's."""
+
+    def __init__(self, app: ASGIApp, token: str, gated: tuple[str, ...] = ()) -> None:
+        self.app = app
+        self.token = token
+        self.prefixes = ("/api", *gated)
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] == "http" and scope["path"].startswith(self.prefixes):
+            query = dict(parse_qsl(scope.get("query_string", b"").decode()))
+            if not hmac.compare_digest(query.get(GATE_PARAMETER, ""), self.token):
+                refused = error_response(Unauthorised("the token in the link is required"))
+                await refused(scope, receive, send)
+                return
+        await self.app(scope, receive, send)
+
+
+def static_dir() -> Path:
+    """Where the built page lives inside the package."""
+    return Path(str(resources.files("ecosemantic.view") / "static"))
+
+
+def page_routes(static: Path) -> list[BaseRoute]:
+    """The built page with its assets, or the one line that says there is none."""
+    if (static / "index.html").is_file():
+
+        async def page(request: Request) -> Response:
+            return FileResponse(static / "index.html")
+
+        return [
+            Mount("/assets", app=StaticFiles(directory=static / "assets", check_dir=False)),
+            Route("/{path:path}", page),
+        ]
+
+    async def unbuilt(request: Request) -> Response:
+        return HTMLResponse(UNBUILT)
+
+    return [Route("/{path:path}", unbuilt)]
+
+
+@answering
+async def not_found(request: Request) -> Response:
+    """A JSON 404 for any `/api/...` path no route above this one matched."""
+    raise NotFound(f"no route /api/{request.path_params['path']}")
+
+
+def pumping(context: ServerContext, inner: Lifespan[Starlette] | None) -> Lifespan[Starlette]:
+    """The application's lifespan: publish what other processes write for as long as it serves."""
+
+    @contextlib.asynccontextmanager
+    async def lifespan(app: Starlette) -> AsyncIterator[None]:
+        storage_ready = asyncio.Event()
+        runs_ready = asyncio.Event()
+        installs_ready = asyncio.Event()
+        pumps = [
+            asyncio.create_task(pump_storage(context.storage, context.events, storage_ready)),
+            asyncio.create_task(pump_runs(context.runs, context.events, runs_ready)),
+            asyncio.create_task(pump_installs(context.installs, context.events, installs_ready)),
+        ]
+        try:
+            await _pumps_started(pumps, (storage_ready, runs_ready, installs_ready))
+            if inner is None:
+                yield
+            else:
+                async with inner(app):
+                    yield
+        finally:
+            for pump in pumps:
+                pump.cancel()
+            await asyncio.gather(*pumps, return_exceptions=True)
+
+    return lifespan
+
+
+async def _pumps_started(pumps: list[asyncio.Task[None]], ready: tuple[asyncio.Event, ...]) -> None:
+    """Wait until every pump is armed and has taken the stored state as published, or raise the
+    error of one that ended first: a write the application goes on to serve is one a ready pump
+    publishes."""
+    waiting = asyncio.gather(*(event.wait() for event in ready))
+    done, _ = await asyncio.wait([*pumps, waiting], return_when=asyncio.FIRST_COMPLETED)
+    if waiting in done:
+        return
+    ended = await asyncio.gather(*pumps, return_exceptions=True)
+    for outcome in ended:
+        if isinstance(outcome, BaseException) and not isinstance(outcome, asyncio.CancelledError):
+            raise outcome
+    raise Unavailable("a pump of the application ended before it was ready")
+
+
+def build_view(
+    context: ServerContext,
+    server: FastMCP,
+    token: str | None = None,
+    static: Path | None = None,
+    routes: Sequence[BaseRoute] = (),
+    gated: tuple[str, ...] = (),
+    inner: Lifespan[Starlette] | None = None,
+) -> ASGIApp:
+    """The page's API and the page. The caller's routes sit ahead of the page and its lifespan
+    runs inside the view's; the token gates /api and every prefix in gated."""
+    served: list[BaseRoute] = [
+        *api_routes(server, context),
+        *activity_routes(server, context),
+        *stream_routes(context),
+        *olca_routes(context),
+        *install_routes(server, context),
+        *credential_routes(context),
+        *tables_routes(server, context),
+        *routes,
+        Route(
+            "/api/{path:path}",
+            not_found,
+            methods=["GET", "POST", "PUT", "DELETE", "PATCH"],
+        ),
+        *page_routes(static if static is not None else static_dir()),
+    ]
+    app = Starlette(routes=served, lifespan=pumping(context, inner))
+    return TokenGate(app, token, gated) if token else app

ecosemantic/view/credentials.py

@@ -0,0 +1,81 @@
+"""The page's own credential routes: which kinds this server holds, one entered and one cleared.
+They answer a peer on this machine only, since the page's token travels over plain HTTP."""
+
+from __future__ import annotations
+
+from typing import get_args
+
+from pydantic import TypeAdapter, ValidationError
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+from starlette.routing import Route
+
+from ecosemantic.errors import Invalid, Unauthorised
+from ecosemantic.mcp.context import ServerContext
+from ecosemantic.ports.types import Account, CredentialKind
+from ecosemantic.view.api import json_object
+from ecosemantic.view.handling import answering
+
+LOOPBACK_PEERS = frozenset({"127.0.0.1", "::1"})
+HINT = "run ecosemantic setup, or reach the page through an SSH tunnel"
+KIND = TypeAdapter(CredentialKind)
+KINDS: tuple[str, ...] = get_args(CredentialKind)
+
+
+def _peer(request: Request) -> None:
+    """Unauthorised unless the request comes from this machine."""
+    client = request.client
+    peer = "" if client is None else client.host
+    if peer not in LOOPBACK_PEERS:
+        raise Unauthorised("a credential is entered only from this machine", hint=HINT)
+
+
+def _kind(name: str) -> CredentialKind:
+    """The credential kind a path names, Invalid for a name that is none of them."""
+    try:
+        return KIND.validate_python(name)
+    except ValidationError as error:
+        raise Invalid(
+            f"{name!r} is no credential kind; the kinds are {', '.join(KINDS)}"
+        ) from error
+
+
+def routes(context: ServerContext) -> list[Route]:
+    """The kinds held, one kind entered and one cleared, from this machine only."""
+
+    @answering
+    async def held(request: Request) -> Response:
+        _peer(request)
+        return JSONResponse({"held": sorted(context.credentials)})
+
+    @answering
+    async def entered(request: Request) -> Response:
+        _peer(request)
+        kind = _kind(request.path_params["kind"])
+        body = await json_object(request)
+        try:
+            account = Account.model_validate(
+                {
+                    "username": body.get("username"),
+                    "password": body.get("password"),
+                    "token": body.get("token"),
+                }
+            )
+        except ValidationError as error:
+            raise Invalid(
+                "a credential is a username and a password as text, and a token as text or none"
+            ) from error
+        context.credentials[kind] = account
+        return Response(status_code=204)
+
+    @answering
+    async def cleared(request: Request) -> Response:
+        _peer(request)
+        context.credentials.pop(_kind(request.path_params["kind"]), None)
+        return Response(status_code=204)
+
+    return [
+        Route("/api/credentials", held),
+        Route("/api/credentials/{kind}", entered, methods=["PUT"]),
+        Route("/api/credentials/{kind}", cleared, methods=["DELETE"]),
+    ]