mwps-client 0.1.7__tar.gz

mwps_client-0.1.7/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: mwps-client
+Version: 0.1.7
+Summary: Official mwps client library: single entry point MwpsClient, one typed method per mwps command.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# mwps-client
+
+Official Python client for the `mwps` server. `MwpsClient` is the single
+entry point: it hides transport selection, TLS material, proxy routing,
+request correlation and error mapping behind one typed async method per
+`mwps` command (see `mwps_client/mwps_client/client.py`).
+
+## Installation
+
+```
+pip install mwps-client
+```
+
+## Usage
+
+```python
+import asyncio
+from mwps_client import MwpsClient
+
+async def main():
+    client = MwpsClient(base_url="https://<host>:8015", ca="/path/to/ca.crt")
+    result = await client.invoke_tool(tool_name="list_servers")
+    print(result)
+
+asyncio.run(main())
+```
+
+## Version lockstep
+
+`mwps-client` carries no version of its own: its published version is
+always identical to the `mwps` server version it was generated against
+(C-068, ClientServerVersionLockstep). Both packages read the same
+repository-root `VERSION` file — `mwps_client/VERSION` is a symlink to
+`../VERSION` — so a client published from a given deploy always matches
+the server it talks to. See `pipeline/README.md` for the release process
+that keeps the two in lockstep.

mwps_client-0.1.7/README.md

@@ -0,0 +1,36 @@
+# mwps-client
+
+Official Python client for the `mwps` server. `MwpsClient` is the single
+entry point: it hides transport selection, TLS material, proxy routing,
+request correlation and error mapping behind one typed async method per
+`mwps` command (see `mwps_client/mwps_client/client.py`).
+
+## Installation
+
+```
+pip install mwps-client
+```
+
+## Usage
+
+```python
+import asyncio
+from mwps_client import MwpsClient
+
+async def main():
+    client = MwpsClient(base_url="https://<host>:8015", ca="/path/to/ca.crt")
+    result = await client.invoke_tool(tool_name="list_servers")
+    print(result)
+
+asyncio.run(main())
+```
+
+## Version lockstep
+
+`mwps-client` carries no version of its own: its published version is
+always identical to the `mwps` server version it was generated against
+(C-068, ClientServerVersionLockstep). Both packages read the same
+repository-root `VERSION` file — `mwps_client/VERSION` is a symlink to
+`../VERSION` — so a client published from a given deploy always matches
+the server it talks to. See `pipeline/README.md` for the release process
+that keeps the two in lockstep.

mwps_client-0.1.7/VERSION

@@ -0,0 +1 @@
+0.1.7

mwps_client-0.1.7/mwps_client/__init__.py

@@ -0,0 +1,36 @@
+from pathlib import Path
+
+from .client import MwpsClient
+
+# Lockstep version (C-068, ClientServerVersionLockstep): must always equal
+# the mwps server's [project].version in the repo-root pyproject.toml. Both
+# read the same root VERSION file (mwps_client/pyproject.toml derives its
+# published version from it via
+# [tool.setuptools.dynamic] version = {file = "VERSION"}, and
+# mwps_client/VERSION is a symlink to ../VERSION).
+#
+# When installed (wheel/sdist), the version setuptools recorded at build
+# time is authoritative and is read via importlib.metadata -- no network,
+# no filesystem lookup outside the installed distribution's own metadata.
+# When running from a checkout without an installed distribution (e.g. a
+# fresh `python -c "import mwps_client"` before `pip install -e .`), fall
+# back to reading the VERSION file next to this package's pyproject.toml.
+
+
+def _read_version() -> str:
+    try:
+        from importlib.metadata import version
+
+        return version("mwps-client")
+    except Exception:
+        pass
+    try:
+        version_file = Path(__file__).resolve().parent.parent / "VERSION"
+        return version_file.read_text(encoding="utf-8").strip()
+    except OSError:
+        return "0.0.0"
+
+
+__version__ = _read_version()
+
+__all__ = ["MwpsClient", "__version__"]

mwps_client-0.1.7/mwps_client/client.py

@@ -0,0 +1,390 @@
+"""
+mwps_client.client
+
+MwpsClient: the sole entry point of the mwps-client package. Hides all
+network interaction (transport selection, TLS material, proxy routing,
+request correlation, transport-level retry, error mapping) behind one
+async, typed method per mwps command.
+
+Version note (C-068, ClientServerVersionLockstep): this module carries no
+version string of its own. mwps-client's published version is always
+identical to the mwps server version it was generated against and is
+derived at build time; every server deployment obligatorily raises that
+version, and mwps-client is republished to PyPI at the same new version in
+the same delivery. Do not add a __version__ or literal version string here.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, List, Optional, cast
+from urllib.parse import urlparse
+
+
+class MwpsClientError(Exception):
+    """Transport-level error raised by MwpsClient; message is safe to display."""
+
+    def __init__(self, message: str, status: Optional[int] = None) -> None:
+        """Store error message and optional status code."""
+        super().__init__(message)
+        self.message = message
+        self.status = status
+
+
+class MwpsClient:
+    """
+    Single entry point for the mwps-client package.
+
+    Hides transport selection, TLS material, proxy routing, request
+    correlation, transport-level retry, and error mapping behind one typed
+    async method per mwps command. All commands are invoked as JSON-RPC
+    calls through mcp_proxy_adapter's JsonRpcClient, routed via mcp-proxy.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token_header: Optional[str] = None,
+        token: Optional[str] = None,
+        cert: Optional[str] = None,
+        key: Optional[str] = None,
+        ca: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        """
+        Initialize the client with mcp-proxy connection parameters.
+
+        Args:
+            base_url: mcp-proxy base URL (http, https, ws, or wss).
+            token_header: Optional HTTP header name carrying the auth token.
+            token: Optional auth token value.
+            cert: Optional path to client TLS certificate (mTLS). Only
+                takes effect together with `key`.
+            key: Optional path to client TLS private key (mTLS). Only
+                takes effect together with `cert`.
+            ca: Optional path to CA certificate for server verification.
+                Forwarded to the adapter whenever supplied, independently
+                of `cert`/`key` -- plain `https` with a self-signed or
+                private CA needs `ca` alone, with no client certificate.
+            timeout: Request timeout in seconds.
+        """
+        parsed = urlparse((base_url or "").rstrip("/"))
+        scheme = (parsed.scheme or "http").lower()
+        host = parsed.hostname or "localhost"
+        port = parsed.port
+        if port is None:
+            port = 443 if scheme in ("https", "wss") else 80
+        protocol = "https" if scheme in ("https", "wss") else "http"
+        self._adapter_params: Dict[str, Any] = {
+            "protocol": protocol,
+            "host": host,
+            "port": port,
+            "token_header": token_header,
+            "token": token,
+            "timeout": timeout,
+        }
+        if cert and key:
+            self._adapter_params["cert"] = cert
+            self._adapter_params["key"] = key
+        if ca:
+            self._adapter_params["ca"] = ca
+        self._client: Any = None
+        self._client_loop: Optional[asyncio.AbstractEventLoop] = None
+
+    async def _get_client(self) -> Any:
+        """Lazily create and cache the underlying JsonRpcClient for the running loop.
+
+        A cached adapter client holds an httpx.AsyncClient whose pooled
+        connections and internal async primitives are bound to the event
+        loop that was running when they were created. mwps-client is
+        typically driven by pipeline/runner.py, which invokes each check
+        through its own ``asyncio.run(...)`` call -- a fresh event loop
+        every time. Reusing the same adapter client across loops makes its
+        first request in a new loop fail with "Event loop is closed" (the
+        pooled connection tries to schedule I/O on the now-closed old
+        loop), even though the client itself is fine and later requests in
+        that same loop succeed once the stale connection is dropped.
+
+        To stay correct across any number of ``asyncio.run()`` calls, close
+        and drop the cached client whenever the running loop has changed
+        since it was created, then build a fresh one for the current loop.
+        """
+        running_loop = asyncio.get_running_loop()
+        if self._client is not None and self._client_loop is running_loop:
+            return self._client
+        if self._client is not None:
+            await self._close_adapter_client(self._client)
+        try:
+            from mcp_proxy_adapter.client.jsonrpc_client import JsonRpcClient
+        except ImportError as e:
+            raise MwpsClientError(
+                f"mcp_proxy_adapter client not available: {e}"
+            ) from e
+        self._client = JsonRpcClient(**self._adapter_params)
+        self._client_loop = running_loop
+        return self._client
+
+    @staticmethod
+    async def _close_adapter_client(client: Any) -> None:
+        """Best-effort close of a stale adapter client; never raises."""
+        close = getattr(client, "close", None)
+        if not callable(close):
+            return
+        try:
+            result = close()
+            if asyncio.iscoroutine(result):
+                await result
+        except Exception:  # noqa: BLE001 -- teardown failure must not mask real errors
+            pass
+
+    async def aclose(self) -> None:
+        """Close the underlying adapter client, if one was created.
+
+        Safe to call from any running loop, and safe to call more than
+        once. Intended for callers (such as pipeline/main.py) that want to
+        release the transport deterministically after use instead of
+        relying on lazy per-loop recreation in ``_get_client``.
+        """
+        if self._client is None:
+            return
+        await self._close_adapter_client(self._client)
+        self._client = None
+        self._client_loop = None
+
+    async def _call_command(self, command: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Invoke one mwps command via JSON-RPC and return its result.
+
+        Raises:
+            MwpsClientError: on any transport or protocol failure.
+        """
+        client = await self._get_client()
+        try:
+            response = await client.jsonrpc_call(command, params)
+            return cast(Dict[str, Any], client._extract_result(response))
+        except MwpsClientError:
+            raise
+        except Exception as e:  # noqa: BLE001
+            resp = getattr(e, "response", None)
+            status = (
+                getattr(e, "status_code", None)
+                or getattr(e, "status", None)
+                or (getattr(resp, "status_code", None) if resp is not None else None)
+            )
+            raise MwpsClientError(str(e), status=status) from e
+
+    async def session_init(
+        self,
+        model: Optional[str] = None,
+        allowed_commands: Optional[List[str]] = None,
+        forbidden_commands: Optional[List[str]] = None,
+        standards: Optional[List[str]] = None,
+        session_rules: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Create a new chat session and return its identifier.
+
+        Args:
+            model: Default MWPS model id to associate with the session.
+            allowed_commands: Allow-list of command names for the session.
+            forbidden_commands: Forbid-list of command names for the session.
+            standards: Canonical standards text blocks for session context.
+            session_rules: Session rules text blocks for session context.
+
+        Returns:
+            Object with session_id (string, UUID4).
+        """
+        params: Dict[str, Any] = {}
+        if model is not None:
+            params["model"] = model
+        if allowed_commands is not None:
+            params["allowed_commands"] = allowed_commands
+        if forbidden_commands is not None:
+            params["forbidden_commands"] = forbidden_commands
+        if standards is not None:
+            params["standards"] = standards
+        if session_rules is not None:
+            params["session_rules"] = session_rules
+        return await self._call_command("session_init", params)
+
+    async def session_update(
+        self,
+        session_id: str,
+        model: Optional[str] = None,
+        allowed_commands: Optional[List[str]] = None,
+        forbidden_commands: Optional[List[str]] = None,
+        standards: Optional[List[str]] = None,
+        session_rules: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Update an existing session in place (full replacement of supplied lists).
+
+        Args:
+            session_id: UUID4 of the session to update.
+            model: Sets the session's default MWPS model.
+            allowed_commands: Replaces the session's allow-list.
+            forbidden_commands: Replaces the session's forbid-list.
+            standards: Replaces the session's standards context blocks.
+            session_rules: Replaces the session's session-rules context blocks.
+
+        Returns:
+            Object with ok (boolean).
+        """
+        params: Dict[str, Any] = {"session_id": session_id}
+        if model is not None:
+            params["model"] = model
+        if allowed_commands is not None:
+            params["allowed_commands"] = allowed_commands
+        if forbidden_commands is not None:
+            params["forbidden_commands"] = forbidden_commands
+        if standards is not None:
+            params["standards"] = standards
+        if session_rules is not None:
+            params["session_rules"] = session_rules
+        return await self._call_command("session_update", params)
+
+    async def add_command_to_session(
+        self,
+        session_id: str,
+        command_id: str,
+    ) -> Dict[str, Any]:
+        """
+        Grant a session access to one additional command.
+
+        Args:
+            session_id: UUID4 of the session.
+            command_id: Name of the command to allow.
+
+        Returns:
+            Object with ok (boolean).
+        """
+        params: Dict[str, Any] = {"session_id": session_id, "command_id": command_id}
+        return await self._call_command("add_command_to_session", params)
+
+    async def remove_command_from_session(
+        self,
+        session_id: str,
+        command_id: str,
+    ) -> Dict[str, Any]:
+        """
+        Revoke a session's access to one command.
+
+        Args:
+            session_id: UUID4 of the session.
+            command_id: Name of the command to remove.
+
+        Returns:
+            Object with ok (boolean).
+        """
+        params: Dict[str, Any] = {"session_id": session_id, "command_id": command_id}
+        return await self._call_command("remove_command_from_session", params)
+
+    async def get_model_context(
+        self,
+        session_id: str,
+        content: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Return the exact final context that would be sent to the model.
+
+        Args:
+            session_id: UUID4 of the session.
+            content: User message to append as the final message.
+
+        Returns:
+            Object with final_context, representation_model, messages,
+            tool_names, tools, messages_count.
+        """
+        params: Dict[str, Any] = {"session_id": session_id}
+        if content is not None:
+            params["content"] = content
+        return await self._call_command("get_model_context", params)
+
+    async def invoke_tool(
+        self,
+        tool_name: str,
+        arguments: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Invoke one proxy-registered tool the way the model would invoke it.
+
+        Args:
+            tool_name: The tool's display name, or a proxy meta-command
+                (list_servers, call_server, help).
+            arguments: Arguments passed to the tool.
+
+        Returns:
+            Object with content (string).
+        """
+        params: Dict[str, Any] = {"tool_name": tool_name}
+        if arguments is not None:
+            params["arguments"] = arguments
+        return await self._call_command("invoke_tool", params)
+
+    async def info(
+        self,
+        section: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Return server documentation: overview + table of contents, or one section.
+
+        Args:
+            section: Documentation section name (e.g. "commands",
+                "configuration"); omit for the overview and table of
+                contents.
+
+        Returns:
+            Without section: object with description, server (name,
+            version), sections (array of name/title/summary). With
+            section: object with section, title, content.
+        """
+        params: Dict[str, Any] = {}
+        if section is not None:
+            params["section"] = section
+        return await self._call_command("info", params)
+
+    async def mwps_chat(
+        self,
+        messages: Optional[List[Dict[str, str]]] = None,
+        model: Optional[str] = None,
+        stream: Optional[bool] = None,
+        max_tool_rounds: Optional[int] = None,
+        config_path: Optional[str] = None,
+        session_id: Optional[str] = None,
+        content: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Run one chat turn against MWPS, in direct mode or session mode.
+
+        Direct mode: supply `messages`. Session mode: supply `session_id`
+        together with `content`. Exactly one mode must be used per call.
+
+        Args:
+            messages: Chat messages for direct mode; each item has role
+                and content.
+            model: MWPS model name overriding the session/config default.
+            stream: If True, the reply is streamed.
+            max_tool_rounds: Maximum number of tool-call rounds.
+            config_path: Path to the adapter/workstation configuration file.
+            session_id: UUID4 of the session, for session mode.
+            content: New user message text for session mode.
+
+        Returns:
+            Object with message (string) and history (array of object).
+        """
+        params: Dict[str, Any] = {}
+        if messages is not None:
+            params["messages"] = messages
+        if model is not None:
+            params["model"] = model
+        if stream is not None:
+            params["stream"] = stream
+        if max_tool_rounds is not None:
+            params["max_tool_rounds"] = max_tool_rounds
+        if config_path is not None:
+            params["config_path"] = config_path
+        if session_id is not None:
+            params["session_id"] = session_id
+        if content is not None:
+            params["content"] = content
+        return await self._call_command("mwps_chat", params)

mwps_client-0.1.7/mwps_client.egg-info/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: mwps-client
+Version: 0.1.7
+Summary: Official mwps client library: single entry point MwpsClient, one typed method per mwps command.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# mwps-client
+
+Official Python client for the `mwps` server. `MwpsClient` is the single
+entry point: it hides transport selection, TLS material, proxy routing,
+request correlation and error mapping behind one typed async method per
+`mwps` command (see `mwps_client/mwps_client/client.py`).
+
+## Installation
+
+```
+pip install mwps-client
+```
+
+## Usage
+
+```python
+import asyncio
+from mwps_client import MwpsClient
+
+async def main():
+    client = MwpsClient(base_url="https://<host>:8015", ca="/path/to/ca.crt")
+    result = await client.invoke_tool(tool_name="list_servers")
+    print(result)
+
+asyncio.run(main())
+```
+
+## Version lockstep
+
+`mwps-client` carries no version of its own: its published version is
+always identical to the `mwps` server version it was generated against
+(C-068, ClientServerVersionLockstep). Both packages read the same
+repository-root `VERSION` file — `mwps_client/VERSION` is a symlink to
+`../VERSION` — so a client published from a given deploy always matches
+the server it talks to. See `pipeline/README.md` for the release process
+that keeps the two in lockstep.

mwps_client-0.1.7/mwps_client.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+VERSION
+pyproject.toml
+mwps_client/__init__.py
+mwps_client/client.py
+mwps_client.egg-info/PKG-INFO
+mwps_client.egg-info/SOURCES.txt
+mwps_client.egg-info/dependency_links.txt
+mwps_client.egg-info/top_level.txt

mwps_client-0.1.7/mwps_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mwps_client-0.1.7/mwps_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+mwps_client

mwps_client-0.1.7/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mwps-client"
+# Per C-068 (ClientServerVersionLockstep), this client carries no static
+# version of its own. Its version is always identical to the mwps server
+# version and is derived and republished at every server deployment; it
+# must never be hardcoded here as a literal version string.
+dynamic = ["version"]
+description = "Official mwps client library: single entry point MwpsClient, one typed method per mwps command."
+readme = "README.md"
+requires-python = ">=3.10"
+
+[tool.setuptools]
+packages = ["mwps_client"]
+
+[tool.setuptools.dynamic]
+# Single source of truth is the repo-root VERSION file (mwps_client/VERSION
+# is a symlink to ../VERSION), the same file the mwps server's root
+# pyproject.toml reads (C-068, ClientServerVersionLockstep). See
+# pipeline/README.md for the build-time lockstep requirement.
+version = {file = "VERSION"}

mwps_client-0.1.7/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+