clio-kit 2.7.2__tar.gz → 2.9.0__tar.gz

{clio_kit-2.7.2 → clio_kit-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clio-kit
-Version: 2.7.2
+Version: 2.9.0
 Summary: CLIO Kit - MCP Servers, Clients, and Tools for AI Agents
 Project-URL: Homepage, https://github.com/iowarp/clio-kit
 Project-URL: Repository, https://github.com/iowarp/clio-kit
@@ -291,7 +291,7 @@ distinct `not_installed` semantic, while real Spack failures remain errors.
 | **`slurm`** | 3.0.0 | HPC | Job submission and management | `clio-kit mcp-server slurm` |
 | **`spack`** | 2.1.0 | Package Management | Structured package discovery, installation, and location | `clio-kit mcp-server spack` |
 | **`terrain`** | 2.2.3 | Geospatial | Analyze DEMs and terrain point clouds | `clio-kit mcp-server terrain` |
-| **`web`** | 1.0.0 | Web | Fetch a URL to Markdown and search the web | `clio-kit mcp-server web` |
+| **`web`** | 2.0.0 | Web | Provider-fixed web search plus unified URL, DOI, and document fetching | `clio-kit mcp-server web` |
 
 </div>
 

{clio_kit-2.7.2 → clio_kit-2.9.0}/README.md

@@ -265,7 +265,7 @@ distinct `not_installed` semantic, while real Spack failures remain errors.
 | **`slurm`** | 3.0.0 | HPC | Job submission and management | `clio-kit mcp-server slurm` |
 | **`spack`** | 2.1.0 | Package Management | Structured package discovery, installation, and location | `clio-kit mcp-server spack` |
 | **`terrain`** | 2.2.3 | Geospatial | Analyze DEMs and terrain point clouds | `clio-kit mcp-server terrain` |
-| **`web`** | 1.0.0 | Web | Fetch a URL to Markdown and search the web | `clio-kit mcp-server web` |
+| **`web`** | 2.0.0 | Web | Provider-fixed web search plus unified URL, DOI, and document fetching | `clio-kit mcp-server web` |
 
 </div>
 

{clio_kit-2.7.2 → clio_kit-2.9.0}/clio-kit-mcp-servers/adios/server.json

@@ -12,7 +12,7 @@
     {
       "registryType": "pypi",
       "identifier": "clio-kit",
-      "version": "2.7.2",
+      "version": "2.9.0",
       "transport": {
         "type": "stdio"
       },

{clio_kit-2.7.2 → clio_kit-2.9.0}/clio-kit-mcp-servers/arxiv/server.json

@@ -12,7 +12,7 @@
     {
       "registryType": "pypi",
       "identifier": "clio-kit",
-      "version": "2.7.2",
+      "version": "2.9.0",
       "transport": {
         "type": "stdio"
       },

{clio_kit-2.7.2 → clio_kit-2.9.0}/clio-kit-mcp-servers/arxiv/src/arxiv_mcp/capabilities/arxiv_base.py

@@ -2,13 +2,32 @@
 Base utilities for ArXiv search capabilities.
 """
 
+import asyncio
 import httpx
+import math
 import xml.etree.ElementTree as ET
 from typing import Dict, List, Any, Union, cast
 import logging
 
 logger = logging.getLogger(__name__)
 
+# ArXiv's public API rate-limits aggressively under concurrent load (HTTP 429).
+# A well-behaved client retries a 429 with backoff rather than failing the
+# caller's request outright -- this is standard practice for this API, not a
+# test-only accommodation. Bounded (a few seconds worst case) so a genuinely
+# sustained block still surfaces as a real failure instead of hanging.
+#
+# `Retry-After` is untrusted external input: a misconfigured or hostile server
+# response naming an enormous or non-finite value (86400, inf, nan) must never
+# make this hang -- _RATE_LIMIT_MAX_DELAY_SECONDS caps every individual sleep
+# regardless of source (server-supplied or our own exponential backoff), and
+# _RATE_LIMIT_TOTAL_BUDGET_SECONDS caps the SUM of all sleeps across the whole
+# retry loop as an independent, defense-in-depth ceiling.
+_RATE_LIMIT_MAX_ATTEMPTS = 4
+_RATE_LIMIT_BACKOFF_SECONDS = 1.0
+_RATE_LIMIT_MAX_DELAY_SECONDS = 10.0
+_RATE_LIMIT_TOTAL_BUDGET_SECONDS = 20.0
+
 
 def parse_arxiv_entry(
     entry: ET.Element,
@@ -95,10 +114,7 @@ async def execute_arxiv_query(
     base_url = "https://export.arxiv.org/api/query"
 
     try:
-        async with httpx.AsyncClient(timeout=30.0) as client:
-            logger.info(f"Executing ArXiv query with params: {params}")
-            response = await client.get(base_url, params=params)
-            response.raise_for_status()
+        response = await _get_with_rate_limit_retry(base_url, params)
 
         # Parse XML response
         root = ET.fromstring(response.content)
@@ -128,6 +144,81 @@ async def execute_arxiv_query(
         raise Exception(f"ArXiv query failed: {str(e)}")
 
 
+async def _get_with_rate_limit_retry(
+    base_url: str, params: Dict[str, Any]
+) -> httpx.Response:
+    """Issue the ArXiv API GET, retrying a 429 response with bounded backoff.
+
+    Every other outcome (success, timeout, a non-429 HTTP error, a connection
+    error) is returned or raised on the first attempt unchanged -- only a 429
+    is treated as transient and retried, honoring ``Retry-After`` when the API
+    sends one. Every sleep is clamped to ``_RATE_LIMIT_MAX_DELAY_SECONDS`` and
+    the loop stops early once ``_RATE_LIMIT_TOTAL_BUDGET_SECONDS`` of
+    cumulative sleep has been spent, so an oversized or non-finite
+    ``Retry-After`` (86400, inf, nan) can never make this hang.
+    """
+    last_error: httpx.HTTPStatusError | None = None
+    total_slept = 0.0
+    for attempt in range(_RATE_LIMIT_MAX_ATTEMPTS):
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            logger.info(f"Executing ArXiv query with params: {params}")
+            response = await client.get(base_url, params=params)
+            if response.status_code != 429:
+                response.raise_for_status()
+                return response
+            last_error = httpx.HTTPStatusError(
+                f"Client error '429 Too Many Requests' for url '{response.url}'",
+                request=response.request,
+                response=response,
+            )
+        if attempt + 1 >= _RATE_LIMIT_MAX_ATTEMPTS:
+            break
+        remaining_budget = _RATE_LIMIT_TOTAL_BUDGET_SECONDS - total_slept
+        if remaining_budget <= 0:
+            logger.warning(
+                "ArXiv API rate-limited (429); retry time budget "
+                f"({_RATE_LIMIT_TOTAL_BUDGET_SECONDS:.0f}s) exhausted, giving up"
+            )
+            break
+        retry_after = _parse_retry_after(response.headers.get("Retry-After"))
+        requested_delay = (
+            retry_after
+            if retry_after is not None
+            else (_RATE_LIMIT_BACKOFF_SECONDS * (2**attempt))
+        )
+        delay = max(
+            0.0, min(requested_delay, _RATE_LIMIT_MAX_DELAY_SECONDS, remaining_budget)
+        )
+        logger.warning(
+            f"ArXiv API rate-limited (429); retrying in {delay:.1f}s "
+            f"(attempt {attempt + 1}/{_RATE_LIMIT_MAX_ATTEMPTS})"
+        )
+        await asyncio.sleep(delay)
+        total_slept += delay
+    assert last_error is not None
+    raise last_error
+
+
+def _parse_retry_after(value: str | None) -> float | None:
+    """Parse a numeric ``Retry-After`` header value in seconds, if present.
+
+    ``Retry-After`` is untrusted external input. ``inf``/``nan`` parse
+    successfully as floats in Python but are rejected here explicitly --
+    callers still clamp the result to ``_RATE_LIMIT_MAX_DELAY_SECONDS``
+    regardless, but a non-finite value should never reach that clamp as a
+    seemingly legitimate number in the first place.
+    """
+    if value is None:
+        return None
+    try:
+        parsed = float(value)
+    except ValueError:
+        return None
+    if not math.isfinite(parsed):
+        return None
+    return max(0.0, parsed)
+
+
 def generate_bibtex(
     paper: Dict[str, Union[str, List[str], List[Dict[str, str]]]],
 ) -> str:

{clio_kit-2.7.2 → clio_kit-2.9.0}/clio-kit-mcp-servers/chronolog/server.json

@@ -12,7 +12,7 @@
     {
       "registryType": "pypi",
       "identifier": "clio-kit",
-      "version": "2.7.2",
+      "version": "2.9.0",
       "transport": {
         "type": "stdio"
       },

{clio_kit-2.7.2 → clio_kit-2.9.0}/clio-kit-mcp-servers/compression/server.json

@@ -12,7 +12,7 @@
     {
       "registryType": "pypi",
       "identifier": "clio-kit",
-      "version": "2.7.2",
+      "version": "2.9.0",
       "transport": {
         "type": "stdio"
       },

{clio_kit-2.7.2 → clio_kit-2.9.0}/clio-kit-mcp-servers/darshan/server.json

@@ -12,7 +12,7 @@
     {
       "registryType": "pypi",
       "identifier": "clio-kit",
-      "version": "2.7.2",
+      "version": "2.9.0",
       "transport": {
         "type": "stdio"
       },

{clio_kit-2.7.2 → clio_kit-2.9.0}/clio-kit-mcp-servers/geo/server.json

@@ -12,7 +12,7 @@
     {
       "registryType": "pypi",
       "identifier": "clio-kit",
-      "version": "2.7.2",
+      "version": "2.9.0",
       "transport": {
         "type": "stdio"
       },

{clio_kit-2.7.2 → clio_kit-2.9.0}/clio-kit-mcp-servers/geojson/server.json

@@ -12,7 +12,7 @@
     {
       "registryType": "pypi",
       "identifier": "clio-kit",
-      "version": "2.7.2",
+      "version": "2.9.0",
       "transport": {
         "type": "stdio"
       },

{clio_kit-2.7.2 → clio_kit-2.9.0}/clio-kit-mcp-servers/hdf5/server.json

@@ -12,7 +12,7 @@
     {
       "registryType": "pypi",
       "identifier": "clio-kit",
-      "version": "2.7.2",
+      "version": "2.9.0",
       "transport": {
         "type": "stdio"
       },

{clio_kit-2.7.2 → clio_kit-2.9.0}/clio-kit-mcp-servers/jarvis/server.json

@@ -12,7 +12,7 @@
     {
       "registryType": "pypi",
       "identifier": "clio-kit",
-      "version": "2.7.2",
+      "version": "2.9.0",
       "transport": {
         "type": "stdio"
       },

clio_kit-2.9.0/clio-kit-mcp-servers/jarvis/src/jarvis_mcp/models/__init__.py

@@ -0,0 +1,21 @@
+"""Wire-facing data models for the jarvis MCP server, grouped by concern.
+
+Split out of ``jarvis_mcp.server`` (clio-kit campaign #362, Slice 1) so the
+44 Pydantic/TypedDict/dataclass models that previously lived inline in the
+3109-line ``server.py`` have owner modules. Tool registration (the
+``@mcp.tool`` surface) stays thin in ``server.py``, importing from here.
+
+Submodules, by concern:
+
+- ``_base``: the shared ``_ClosedDocument`` base (``extra="forbid"``).
+- ``compat``: the JARVIS-CD manager compatibility adapter.
+- ``packages``: package inventory/description/deployment/settings documents.
+- ``describe``: the ``jarvis_describe`` discriminated result union.
+- ``execution``: execution handle/record/run-result documents, and the
+  ``ExecutionIntent`` request model with its validation/conversion helpers.
+- ``progress``: package progress event/snapshot documents.
+- ``artifact_documents``: artifact location/document/page documents and the
+  ``ExecutionArtifactQuery`` request filter.
+- ``datasets``: the JARVIS-owned dataset descriptor documents.
+- ``service_runtime``: execution-owned service-runtime documents.
+"""

clio_kit-2.9.0/clio-kit-mcp-servers/jarvis/src/jarvis_mcp/models/_base.py

@@ -0,0 +1,11 @@
+"""Shared base for every closed (``extra="forbid"``) agent-visible document."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class _ClosedDocument(BaseModel):
+    """Base for agent-visible documents with no undeclared fields."""
+
+    model_config = ConfigDict(extra="forbid")

clio_kit-2.9.0/clio-kit-mcp-servers/jarvis/src/jarvis_mcp/models/artifact_documents.py

@@ -0,0 +1,124 @@
+"""Artifact location/document/page documents and the artifact query filter."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from typing_extensions import NotRequired, TypedDict
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class JarvisArtifactLocationDocument(TypedDict):
+    """Transport-neutral location in a JARVIS artifact manifest."""
+
+    kind: Literal["execution_path", "cluster_path", "external_uri"]
+    value: str
+
+
+class JarvisArtifactDocument(TypedDict):
+    """Current JARVIS-owned lifecycle observation for one generated artifact."""
+
+    schema_version: Literal["jarvis.artifact.v1"]
+    package_name: str
+    package_id: str
+    execution_id: str
+    artifact_id: str
+    logical_name: str
+    kind: str
+    role: Literal[
+        "intermediate",
+        "output",
+        "log",
+        "checkpoint",
+        "provenance",
+        "validation",
+    ]
+    structure: Literal["file", "directory", "collection", "stream"]
+    ownership: Literal["execution", "external", "shared"]
+    state: Literal["producing", "available", "finalized", "incomplete", "failed"]
+    revision: int
+    sequence: int
+    observed_at_epoch: float
+    metadata: dict[str, Any]
+    location: NotRequired[JarvisArtifactLocationDocument]
+    media_type: NotRequired[str]
+    format: NotRequired[str]
+    size_bytes: NotRequired[int]
+    checksum: NotRequired[str]
+    message: NotRequired[str]
+
+
+class JarvisExecutionArtifactPageDocument(BaseModel):
+    """Bounded artifact page nested in a unified execution query."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    producer_schema_version: Literal["jarvis.execution.artifacts.v1"]
+    pipeline_id: str
+    execution_id: str
+    execution_state: Literal[
+        "preparing",
+        "scripted",
+        "submitting",
+        "submitted",
+        "running",
+        "completed",
+        "failed",
+        "canceled",
+        "unknown",
+    ]
+    terminal: bool
+    artifacts: list[JarvisArtifactDocument]
+    matching_artifact_count: int
+    returned_artifact_count: int
+    next_cursor: str | None
+
+
+class ExecutionArtifactQuery(BaseModel):
+    """Optional filters for one bounded page of execution artifacts."""
+
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    package_id: str | None = Field(
+        default=None,
+        description="Exact JARVIS package alias filter.",
+        max_length=256,
+    )
+    role: (
+        Literal[
+            "intermediate",
+            "output",
+            "log",
+            "checkpoint",
+            "provenance",
+            "validation",
+        ]
+        | None
+    ) = None
+    state: (
+        Literal[
+            "producing",
+            "available",
+            "finalized",
+            "incomplete",
+            "failed",
+        ]
+        | None
+    ) = None
+    artifact_id: str | None = Field(
+        default=None,
+        description="Exact opaque JARVIS artifact ID filter.",
+        max_length=90,
+    )
+    page_size: int = Field(
+        default=50,
+        description="Maximum artifacts to return in this page.",
+        ge=1,
+        le=100,
+    )
+    cursor: str | None = Field(
+        default=None,
+        description="Opaque next-page cursor.",
+        max_length=1024,
+    )

clio_kit-2.9.0/clio-kit-mcp-servers/jarvis/src/jarvis_mcp/models/compat.py

@@ -0,0 +1,143 @@
+"""Compatibility adapter over the current JARVIS-CD ``Jarvis`` singleton."""
+
+from __future__ import annotations
+
+import importlib
+from pathlib import Path
+from typing import Any, Optional
+
+
+class _CurrentJarvisManager:
+    """Compatibility adapter over the current JARVIS-CD Jarvis singleton."""
+
+    @classmethod
+    def get_instance(cls) -> "_CurrentJarvisManager":
+        jarvis_module = importlib.import_module("jarvis_cd.core.config")
+        return cls(jarvis_module.Jarvis.get_instance())
+
+    def __init__(self, jarvis: Any) -> None:
+        self.jarvis = jarvis
+
+    def create(
+        self, config_dir: str, private_dir: str, shared_dir: Optional[str] = None
+    ) -> "_CurrentJarvisManager":
+        self.jarvis.initialize(
+            config_dir=config_dir,
+            private_dir=private_dir,
+            shared_dir=shared_dir or private_dir,
+        )
+        return self
+
+    def load(self) -> "_CurrentJarvisManager":
+        _ = self.jarvis.config
+        return self
+
+    def save(self) -> "_CurrentJarvisManager":
+        if getattr(self.jarvis, "_config", None) is not None:
+            self.jarvis.save_config(self.jarvis.config)
+        if getattr(self.jarvis, "_repos", None) is not None:
+            self.jarvis.save_repos(self.jarvis.repos)
+        return self
+
+    def set_hostfile(self, path: str) -> "_CurrentJarvisManager":
+        self.jarvis.set_hostfile(path)
+        return self
+
+    def bootstrap_from(self, machine: str) -> "_CurrentJarvisManager":
+        raise NotImplementedError(
+            f"bootstrap templates are not exposed by current JARVIS-CD: {machine}"
+        )
+
+    def bootstrap_list(self) -> list[str]:
+        return []
+
+    def reset(self) -> "_CurrentJarvisManager":
+        raise NotImplementedError(
+            "reset is not exposed through the compatibility adapter"
+        )
+
+    def list_pipelines(self) -> list[str]:
+        pipelines_dir = self.jarvis.get_pipelines_dir()
+        if not pipelines_dir.exists():
+            return []
+        return sorted(path.name for path in pipelines_dir.iterdir() if path.is_dir())
+
+    def cd(self, pipeline_id: str) -> "_CurrentJarvisManager":
+        self.jarvis.set_current_pipeline(pipeline_id)
+        return self
+
+    def list_repos(self) -> list[str]:
+        return list(self.jarvis.repos.get("repos", []))
+
+    def add_repo(self, path: str, force: bool = False) -> "_CurrentJarvisManager":
+        self.jarvis.add_repo(path, force=force)
+        return self
+
+    def remove_repo(self, repo_name: str) -> "_CurrentJarvisManager":
+        repo_paths = list(self.jarvis.repos.get("repos", []))
+        matches = [
+            repo_path
+            for repo_path in repo_paths
+            if repo_path == repo_name or Path(repo_path).name == repo_name
+        ]
+        if not matches:
+            self.jarvis.remove_repo(repo_name)
+        for repo_path in matches:
+            self.jarvis.remove_repo(repo_path)
+        return self
+
+    def promote_repo(self, repo_name: str) -> "_CurrentJarvisManager":
+        repos = self.jarvis.repos.copy()
+        repo_paths = list(repos.get("repos", []))
+        matches = [
+            repo_path
+            for repo_path in repo_paths
+            if repo_path == repo_name or Path(repo_path).name == repo_name
+        ]
+        if not matches:
+            raise ValueError(f"repository not found: {repo_name}")
+        for repo_path in reversed(matches):
+            repo_paths.remove(repo_path)
+            repo_paths.insert(0, repo_path)
+        repos["repos"] = repo_paths
+        self.jarvis.save_repos(repos)
+        return self
+
+    def get_repo(self, repo_name: str) -> dict[str, Any] | None:
+        for index, repo_path in enumerate(self.jarvis.repos.get("repos", []), start=1):
+            if repo_path == repo_name or Path(repo_path).name == repo_name:
+                return {
+                    "index": index,
+                    "name": Path(repo_path).name,
+                    "path": repo_path,
+                    "exists": Path(repo_path).exists(),
+                }
+        return None
+
+    def construct_pkg(self, pkg_type: str) -> Any:
+        raise NotImplementedError(
+            f"package construction is not exposed by current JARVIS-CD: {pkg_type}"
+        )
+
+    def resource_graph_show(self) -> dict[str, Any]:
+        return self.jarvis.resource_graph
+
+    def resource_graph_build(self, net_sleep: float) -> dict[str, Any]:
+        _ = net_sleep
+        raise NotImplementedError(
+            "resource graph build is not exposed through the compatibility adapter"
+        )
+
+    def resource_graph_modify(self, net_sleep: float) -> dict[str, Any]:
+        _ = net_sleep
+        raise NotImplementedError(
+            "resource graph modify is not exposed through the compatibility adapter"
+        )
+
+
+def _load_jarvis_manager_class() -> Any:
+    try:
+        module = importlib.import_module("jarvis_cd.basic.jarvis_manager")
+        return module.JarvisManager
+    except ModuleNotFoundError:
+        return _CurrentJarvisManager