macore-client-dev 0.1.52__tar.gz

macore_client_dev-0.1.52/.gitignore

@@ -0,0 +1,49 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.hypothesis/
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+
+# Virtualenv
+.venv/
+venv/
+
+# Logs
+logs/
+*.log
+
+# macmgr state
+.mac/
+
+# Secrets / env
+.env
+.env.*
+!.env.example
+
+# Build
+dist/
+build/
+docker/dist/
+*.egg-info/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+.cst/
+.tree/
+projectid
+
+docker/dist/*.deb

macore_client_dev-0.1.52/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.5
+Name: macore-client-dev
+Version: 0.1.52
+Summary: Client for the Model Access Core (MAC) server
+Requires-Python: >=3.11
+Requires-Dist: mcp-proxy-adapter<9,>=8.11.11

macore_client_dev-0.1.52/macore_client/__about__.py

@@ -0,0 +1,3 @@
+"""The single release version shared by the client and server packages."""
+
+__version__ = "0.1.52"

macore_client_dev-0.1.52/macore_client/__init__.py

@@ -0,0 +1,9 @@
+# client/macore_client/__init__.py
+# Author: Vasiliy Zdanovskiy <vasilyvz@gmail.com>
+# Project: model_access_core (71b1e006-b777-4edb-854e-f0a47120f793)
+"""Client package for the Model Access Core (MAC) server."""
+
+from macore_client.client import MacClient
+from macore_client.__about__ import __version__
+
+__all__ = ["MacClient", "__version__"]

macore_client_dev-0.1.52/macore_client/cli.py

@@ -0,0 +1,77 @@
+# client/macore_client/cli.py
+# Author: Vasiliy Zdanovskiy <vasilyvz@gmail.com>
+# Project: model_access_core (71b1e006-b777-4edb-854e-f0a47120f793)
+"""``macore-client`` console script: one subcommand per MAC command."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+from typing import Any
+
+from macore_client.client import COMMANDS, MacClient
+
+
+def default_base_url() -> str:
+    """Resolve the server base URL from the environment."""
+    return os.environ.get("MAC_VERIFY_BASE_URL", "http://127.0.0.1:8010")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the CLI parser with one subcommand per client command method."""
+    parser = argparse.ArgumentParser(
+        prog="macore-client",
+        description="Call one Model Access Core server command over JSON-RPC.",
+    )
+    parser.add_argument(
+        "--base-url",
+        default=None,
+        help="Adapter base URL (default: env MAC_VERIFY_BASE_URL or http://127.0.0.1:8010)",
+    )
+    parser.add_argument("--timeout", type=float, default=None, help="HTTP timeout seconds")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    for command in COMMANDS:
+        sub = subparsers.add_parser(command.replace("_", "-"), help=f"Run {command}")
+        sub.add_argument(
+            "--params",
+            default="{}",
+            help="Command parameters as a JSON object string",
+        )
+    return parser
+
+
+async def _run(base_url: str, timeout: float | None, command: str, params: dict[str, Any]) -> Any:
+    client = MacClient(base_url, timeout=timeout)
+    try:
+        return await client.call(command, params)
+    finally:
+        await client.close()
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point of the ``macore-client`` command."""
+    args = build_parser().parse_args(argv)
+    command = str(args.command).replace("-", "_")
+    try:
+        params = json.loads(args.params)
+    except json.JSONDecodeError as exc:
+        print(f"macore-client: --params is not valid JSON: {exc}", file=sys.stderr)
+        return 2
+    if not isinstance(params, dict):
+        print("macore-client: --params must be a JSON object", file=sys.stderr)
+        return 2
+    base_url = args.base_url or default_base_url()
+    try:
+        result = asyncio.run(_run(base_url, args.timeout, command, params))
+    except Exception as exc:  # surface transport/command failure as text, not traceback
+        print(f"macore-client: {command} failed: {exc}", file=sys.stderr)
+        return 1
+    print(json.dumps(result, ensure_ascii=False, indent=2, default=str))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

macore_client_dev-0.1.52/macore_client/client.py

@@ -0,0 +1,201 @@
+# client/macore_client/client.py
+# Author: Vasiliy Zdanovskiy <vasilyvz@gmail.com>
+# Project: model_access_core (71b1e006-b777-4edb-854e-f0a47120f793)
+"""The MAC client: one method per public MAC command.
+
+Wraps the ``mcp_proxy_adapter`` framework JSON-RPC client. No method builds a
+URL, a JSON-RPC envelope or a raw transport payload; transport, protocol
+selection, serialization and queued-job handling all belong to the framework
+client. Every method mirrors a command the MAC server registers, with the same
+name, so client and server read against each other without a translation table.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import sys
+from typing import Any
+from urllib.parse import urlparse
+
+
+def _import_jsonrpc_client() -> Any:
+    """Import the framework client with its import-time banner kept off stdout."""
+    with contextlib.redirect_stdout(sys.stderr):
+        from mcp_proxy_adapter.client.jsonrpc_client.client import JsonRpcClient
+    return JsonRpcClient
+
+# Public MAC commands, one client method each. model_selftest is queued on the
+# server; the rest answer inline.
+COMMANDS: tuple[str, ...] = (
+    "info",
+    "list_vectorization_models",
+    "count_vectorization_tokens",
+    "vectorize",
+    "openai_models",
+    "health",
+    "model_health",
+    "model_providers",
+    "model_provider_status",
+    "model_vram_status",
+    "model_queue_status",
+    "model_session_create",
+    "model_session_get",
+    "model_session_delete",
+    "model_chat",
+    "model_count_tokens",
+    "model_estimate_request_capacity",
+    "model_request_status",
+    "model_request_cancel",
+    "model_cache_create",
+    "model_cache_set_active",
+    "model_cache_list",
+    "model_cache_delete",
+    "model_selftest",
+    "hardware_calibration",
+)
+
+_QUEUED_COMMANDS: frozenset[str] = frozenset({"model_selftest"})
+
+
+def command_methods() -> tuple[str, ...]:
+    """Return the client's public command-method names (for surface checks)."""
+    return COMMANDS
+
+
+def _unwrap(result: Any) -> Any:
+    """Unwrap the unified-execution envelope down to the command result."""
+    seen = 0
+    while isinstance(result, dict) and seen < 8:
+        seen += 1
+        if result.get("mode") in {"immediate", "queued"} and "result" in result:
+            result = result["result"]
+            continue
+        if "result" in result and set(result.keys()) <= {"result", "job_id", "status", "queued", "command", "raw_status", "mode"}:
+            result = result["result"]
+            continue
+        break
+    return result
+
+
+class MacClient:
+    """Full-surface client for one Model Access Core server.
+
+    Attributes:
+        transport: The framework JSON-RPC client carrying every request.
+    """
+
+    def __init__(
+        self,
+        base_url: str = "http://127.0.0.1:8010",
+        *,
+        token: str | None = None,
+        token_header: str | None = None,
+        cert: str | None = None,
+        key: str | None = None,
+        ca: str | None = None,
+        check_hostname: bool = False,
+        timeout: float | None = None,
+    ) -> None:
+        parsed = urlparse(base_url)
+        protocol = parsed.scheme or "http"
+        host = parsed.hostname or "127.0.0.1"
+        port = parsed.port or (443 if protocol == "https" else 80)
+        json_rpc_client = _import_jsonrpc_client()
+        self.transport = json_rpc_client(
+            protocol=protocol,
+            host=host,
+            port=port,
+            token=token,
+            token_header=token_header,
+            cert=cert,
+            key=key,
+            ca=ca,
+            check_hostname=check_hostname,
+            timeout=timeout,
+        )
+
+    async def call(self, command: str, params: dict[str, Any] | None = None) -> Any:
+        """Execute one MAC command and return its unwrapped result."""
+        if command in _QUEUED_COMMANDS:
+            raw = await self.transport.execute_command_unified(
+                command,
+                params or {},
+                auto_poll=True,
+            )
+        else:
+            raw = await self.transport.execute_command_unified(
+                command,
+                params or {},
+                expect_queue=False,
+            )
+        return _unwrap(raw)
+
+    async def close(self) -> None:
+        """Close the underlying transport."""
+        close = getattr(self.transport, "close", None)
+        if close is not None:
+            await close()
+
+    async def info(self, section: str, *, page: int = 1, page_size: int = 1000) -> Any:
+        """Return one bounded page of embedded MAC reference documentation."""
+        return await self.call("info", {"section": section, "page": page, "page_size": page_size})
+
+    async def list_vectorization_models(self) -> Any:
+        """Return the ordered vectorization model inventory."""
+        return await self.call("list_vectorization_models")
+
+    async def openai_models(self) -> Any:
+        """Return the raw OpenAI model list with the added capability marker (no parameters)."""
+        return await self.call("openai_models")
+
+    async def vectorize(
+        self,
+        text: str | list[str],
+        provider_id: str,
+        model_id: str,
+        dimension: int | None = None,
+    ) -> Any:
+        """Generate vectors through the selected provider and model."""
+        params: dict[str, Any] = {
+            "text": text,
+            "provider_id": provider_id,
+            "model_id": model_id,
+        }
+        if dimension is not None:
+            params["dimension"] = dimension
+        return await self.call("vectorize", params)
+
+    async def count_vectorization_tokens(
+        self,
+        text: str | list[str],
+        provider_id: str,
+        model_id: str,
+    ) -> Any:
+        """Count vectorization input tokens without generating embeddings."""
+        return await self.call("count_vectorization_tokens", {
+            "text": text,
+            "provider_id": provider_id,
+            "model_id": model_id,
+        })
+
+
+def _make_method(command: str) -> Any:
+    async def method(self: MacClient, params: dict[str, Any] | None = None) -> Any:
+        return await self.call(command, params)
+
+    method.__name__ = command
+    method.__qualname__ = f"MacClient.{command}"
+    method.__doc__ = f"Execute the MAC ``{command}`` command."
+    return method
+
+
+for _command in COMMANDS:
+    if _command in {
+    "info",
+    "list_vectorization_models",
+    "vectorize",
+    "count_vectorization_tokens",
+    "openai_models",
+}:
+        continue
+    setattr(MacClient, _command, _make_method(_command))

macore_client_dev-0.1.52/macore_client/live_check.py

@@ -0,0 +1,226 @@
+# client/macore_client/live_check.py
+# Author: Vasiliy Zdanovskiy <vasilyvz@gmail.com>
+# Project: model_access_core (71b1e006-b777-4edb-854e-f0a47120f793)
+"""Client-driven live acceptance helpers for a deployed MAC server."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Any
+
+from macore_client.client import MacClient
+
+
+def _base_url() -> str:
+    return os.environ.get("MAC_VERIFY_BASE_URL", "http://127.0.0.1:8010")
+
+
+def _timeout() -> float:
+    raw = os.environ.get("MAC_VERIFY_TIMEOUT", "300")
+    try:
+        return float(raw)
+    except ValueError:
+        return 300.0
+
+
+async def _with_client(coro: Any) -> int:
+    client = MacClient(
+        _base_url(),
+        ca=os.environ.get("MAC_VERIFY_CA"),
+        check_hostname=True,
+        timeout=_timeout(),
+    )
+    try:
+        return await coro(client)
+    finally:
+        await client.close()
+
+
+def select_catalog_chat_model(catalog: Any, provider_id: str) -> dict[str, int | str] | None:
+    """Return one catalog-backed chat identity for ``provider_id``.
+
+    The returned mapping is deliberately small and stable for pipeline callers:
+    ``provider_id``, ``model_id``, ``context_window``, and
+    ``max_output_tokens``.  It contains only positive integer limits and the
+    exact model ID advertised by MAC; it never translates provider aliases.
+    """
+
+    data = catalog.get("data") if isinstance(catalog, dict) else None
+    providers = data if isinstance(data, list) else None
+    if providers is None and isinstance(data, dict):
+        candidate = data.get("providers")
+        providers = candidate if isinstance(candidate, list) else None
+    if not isinstance(providers, list):
+        return None
+
+    provider = next(
+        (row for row in providers if isinstance(row, dict) and row.get("provider_id") == provider_id),
+        None,
+    )
+    summaries = provider.get("capability_summary") if isinstance(provider, dict) else None
+    if not isinstance(summaries, list):
+        return None
+
+    selections: list[dict[str, int | str]] = []
+    for summary in summaries:
+        if not isinstance(summary, dict):
+            continue
+        model_id = summary.get("model_id")
+        context_window = summary.get("context_window_tokens")
+        max_output_tokens = summary.get("max_output_tokens")
+        if (
+            not isinstance(model_id, str)
+            or not model_id
+            or not isinstance(context_window, int)
+            or isinstance(context_window, bool)
+            or context_window <= 0
+            or not isinstance(max_output_tokens, int)
+            or isinstance(max_output_tokens, bool)
+            or max_output_tokens <= 0
+        ):
+            continue
+        selections.append(
+            {
+                "provider_id": provider_id,
+                "model_id": model_id,
+                "context_window": context_window,
+                "max_output_tokens": max_output_tokens,
+            }
+        )
+
+    return min(selections, key=lambda selection: str(selection["model_id"])) if selections else None
+
+
+async def _run_catalog_chat_live(client: MacClient, provider_id: str) -> int:
+    catalog = await client.model_providers()
+    selection = select_catalog_chat_model(catalog, provider_id)
+    if selection is None:
+        print(f"FAIL {provider_id}-live: no chat model with positive limits in catalog")
+        return 1
+
+    result = await client.model_chat(
+        {
+            "provider_id": selection["provider_id"],
+            "provider_key_id": "noauth:default",
+            "model_id": selection["model_id"],
+            "messages": [
+                {"role": "user", "content": [{"type": "text", "text": "Reply OK."}]}
+            ],
+            "reserved_output_tokens": min(32, int(selection["max_output_tokens"])),
+            "stream": False,
+            "generation_options": {},
+        }
+    )
+    data = result.get("data") if isinstance(result, dict) else None
+    message = data.get("message") if isinstance(data, dict) else None
+    blocks = message.get("content") if isinstance(message, dict) else None
+    text_blocks = [
+        block.get("text")
+        for block in blocks
+        if isinstance(block, dict) and block.get("type") == "text"
+    ] if isinstance(blocks, list) else []
+    usage = data.get("usage") if isinstance(data, dict) else None
+    total_tokens = usage.get("total_tokens") if isinstance(usage, dict) else None
+    if (
+        not isinstance(result, dict)
+        or result.get("success") is not True
+        or not isinstance(data, dict)
+        or data.get("finish_reason") not in {"stop", "length"}
+        or not any(isinstance(text, str) and text.strip() for text in text_blocks)
+        or not isinstance(total_tokens, int)
+        or total_tokens <= 0
+    ):
+        print(f"FAIL {provider_id}-live: {selection}: {str(result)[:240]}")
+        return 1
+    print(f"PASS {provider_id}-live: {selection}: tokens={total_tokens}")
+    return 0
+
+
+def run_health_live() -> int:
+    """The deployed server answers health and model_health."""
+
+    async def check(client: MacClient) -> int:
+        health = await client.call("health")
+        model_health = await client.call("model_health")
+        data = model_health.get("data") if isinstance(model_health, dict) else None
+        adapter = (data or {}).get("adapter") if isinstance(data, dict) else None
+        registry = (data or {}).get("registry") if isinstance(data, dict) else None
+        providers = (registry or {}).get("providers") if isinstance(registry, dict) else None
+        if not isinstance(health, dict):
+            print("FAIL health-live: health returned no object")
+            return 1
+        if adapter != "ok" or not isinstance(providers, int) or providers < 1:
+            print(f"FAIL health-live: adapter={adapter!r} providers={providers!r}")
+            return 1
+        print(f"PASS health-live: adapter=ok providers={providers}")
+        return 0
+
+    return asyncio.run(_with_client(check))
+
+
+def run_providers_live() -> int:
+    """The deployed server lists at least one provider with models."""
+
+    async def check(client: MacClient) -> int:
+        result = await client.call("model_providers")
+        data = result.get("data") if isinstance(result, dict) else None
+        providers = data if isinstance(data, list) else None
+        if providers is None and isinstance(data, dict):
+            providers = data.get("providers") if isinstance(data.get("providers"), list) else None
+        if not isinstance(providers, list) or not providers:
+            print(f"FAIL providers-live: no providers in {str(result)[:200]}")
+            return 1
+        names = [p.get("provider_id") for p in providers if isinstance(p, dict)]
+        print(f"PASS providers-live: {len(providers)} providers: {', '.join(map(str, names))}")
+        return 0
+
+    return asyncio.run(_with_client(check))
+
+
+def run_openrouter_qwen_live() -> int:
+    """One current OpenRouter chat model answers using its catalog identity."""
+
+    async def check(client: MacClient) -> int:
+        return await _run_catalog_chat_live(client, "openrouter-qwen")
+
+    return asyncio.run(_with_client(check))
+
+
+def run_lmrs_live() -> int:
+    """One current LMRS chat model answers using its catalog identity."""
+
+    async def check(client: MacClient) -> int:
+        return await _run_catalog_chat_live(client, "lmrs")
+
+    return asyncio.run(_with_client(check))
+
+
+def run_selftest_live() -> int:
+    """Drive the server's own full live regression (model_selftest)."""
+
+    async def check(client: MacClient) -> int:
+        result = await client.call("model_selftest", {})
+        node: Any = result
+        for _ in range(6):
+            if isinstance(node, dict) and isinstance(node.get("data"), dict):
+                node = node["data"]
+                continue
+            break
+        if not isinstance(node, dict) or "exit_code" not in node:
+            print(f"FAIL selftest-live: unrecognized selftest result: {str(result)[:300]}")
+            return 1
+        ok = bool(node.get("ok"))
+        exit_code = int(node.get("exit_code") or 0)
+        passed = node.get("passed")
+        failed = node.get("failed")
+        n_pass = len(passed) if isinstance(passed, list) else 0
+        n_fail = len(failed) if isinstance(failed, list) else 0
+        line = f"selftest-live: ok={ok} exit_code={exit_code} passed={n_pass} failed={n_fail}"
+        if not ok or exit_code != 0 or n_pass == 0:
+            print(f"FAIL {line}")
+            return 1
+        print(f"PASS {line}")
+        return 0
+
+    return asyncio.run(_with_client(check))

macore_client_dev-0.1.52/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "macore-client-dev"
+dynamic = ["version"]
+description = "Client for the Model Access Core (MAC) server"
+requires-python = ">=3.11"
+dependencies = [
+    "mcp_proxy_adapter>=8.11.11,<9",
+]
+
+[project.scripts]
+macore-client = "macore_client.cli:main"
+
+[tool.hatch.version]
+path = "macore_client/__about__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["macore_client"]