dchub 0.1.0__py3-none-any.whl

dchub/__init__.py

@@ -0,0 +1,5 @@
+"""DC Hub Python SDK — live data-center, power & gas intelligence over MCP."""
+from .client import DCHub
+
+__all__ = ["DCHub"]
+__version__ = "0.1.0"

dchub/client.py

@@ -0,0 +1,154 @@
+"""DC Hub Python SDK — hides the MCP JSON-RPC handshake.
+
+The MCP transport (initialize -> notifications/initialized -> tools/call, with
+SSE response parsing) is wrapped so you can just write:
+
+    from dchub import DCHub
+    dc = DCHub()                       # reads DCHUB_API_KEY from env if set
+    dc.market("northern-virginia")
+    dc.search(state="VA")
+    dc.grid(iso="ERCOT")
+    dc.call("get_market_intel", market="dallas")   # any of the 38 tools
+    dc.tools()                          # list tool names
+
+Set DCHUB_API_KEY for full-tier data (sent as the X-API-Key header).
+"""
+from __future__ import annotations
+
+import json
+import os
+import urllib.request
+
+__all__ = ["DCHub"]
+
+_DEFAULT_ENDPOINT = "https://dchub.cloud/mcp"
+
+
+class DCHub:
+    def __init__(self, api_key: str | None = None, endpoint: str | None = None,
+                 timeout: int = 60):
+        self.endpoint = endpoint or os.environ.get("DCHUB_ENDPOINT", _DEFAULT_ENDPOINT)
+        self.api_key = api_key if api_key is not None else os.environ.get("DCHUB_API_KEY")
+        self.timeout = timeout
+        self._session_id: str | None = None
+
+    # --- transport ---------------------------------------------------------
+    def _headers(self) -> dict:
+        h = {"Content-Type": "application/json",
+             "Accept": "application/json, text/event-stream"}
+        if self.api_key:
+            h["X-API-Key"] = self.api_key
+        if self._session_id:
+            h["Mcp-Session-Id"] = self._session_id
+        return h
+
+    @staticmethod
+    def _parse_body(raw: str):
+        raw = raw.strip()
+        if not raw:
+            return None
+        if raw.startswith("{"):
+            return json.loads(raw)
+        for line in raw.splitlines():            # SSE: 'data: {...}'
+            line = line.strip()
+            if line.startswith("data:"):
+                payload = line[len("data:"):].strip()
+                if payload.startswith("{"):
+                    return json.loads(payload)
+        raise ValueError(f"Could not parse MCP response body: {raw[:300]}")
+
+    def _post(self, payload: dict):
+        data = json.dumps(payload).encode()
+        req = urllib.request.Request(self.endpoint, data=data,
+                                     headers=self._headers(), method="POST")
+        with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+            sid = resp.headers.get("Mcp-Session-Id")
+            body = resp.read().decode()
+        if sid:
+            self._session_id = sid
+        return self._parse_body(body)
+
+    def _ensure_session(self):
+        if self._session_id:
+            return
+        self._post({"jsonrpc": "2.0", "id": 1, "method": "initialize",
+                    "params": {"protocolVersion": "2024-11-05", "capabilities": {},
+                               "clientInfo": {"name": "dchub-python-sdk", "version": "1.0"}}})
+        try:
+            self._post({"jsonrpc": "2.0", "method": "notifications/initialized"})
+        except Exception:
+            pass
+
+    # --- payload cleaning --------------------------------------------------
+    @staticmethod
+    def _clean(result):
+        """Return the real data payload, stripping any free-tier upsell wrapper.
+
+        `search_facilities` already returns a structured dict; the text tools
+        (`get_market_intel`, `get_grid_data`) embed the data as a JSON block
+        fenced by `---`. Upsell-only objects (agent_action/agent_claim) are
+        skipped.
+        """
+        if isinstance(result, dict):
+            return result
+        if isinstance(result, str):
+            for part in result.split("---"):
+                part = part.strip()
+                if part.startswith("{"):
+                    try:
+                        obj = json.loads(part)
+                    except Exception:
+                        continue
+                    if not ({"agent_action", "agent_claim"} & set(obj)):
+                        return obj
+            return {"text": result}
+        return result
+
+    # --- generic call ------------------------------------------------------
+    def call(self, tool: str, **arguments):
+        """Call any DC Hub MCP tool; returns the cleaned data payload."""
+        self._ensure_session()
+        resp = self._post({"jsonrpc": "2.0", "id": 3, "method": "tools/call",
+                           "params": {"name": tool, "arguments": arguments}})
+        if "error" in resp:
+            return resp["error"]
+        content = resp.get("result", {}).get("content", [])
+        parsed = []
+        for item in content:
+            if item.get("type") == "text":
+                txt = item["text"]
+                try:
+                    parsed.append(json.loads(txt))
+                except Exception:
+                    parsed.append(txt)
+            else:
+                parsed.append(item)
+        raw = parsed[0] if len(parsed) == 1 else parsed
+        return self._clean(raw)
+
+    def tools(self) -> list[str]:
+        """List all available tool names."""
+        self._ensure_session()
+        resp = self._post({"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}})
+        return [t["name"] for t in resp.get("result", {}).get("tools", [])]
+
+    # --- convenience methods ----------------------------------------------
+    def market(self, slug: str):
+        """Market intelligence for a market slug, e.g. 'northern-virginia'."""
+        return self.call("get_market_intel", market=slug)
+
+    def search(self, q: str | None = None, state: str | None = None,
+               country: str | None = None, limit: int = 5):
+        """Search facilities by free-text / state / country."""
+        args = {"limit": limit}
+        if q:
+            args["q"] = q
+        if state:
+            args["state"] = state
+        if country:
+            args["country"] = country
+        return self.call("search_facilities", **args)
+
+    def grid(self, iso: str):
+        """Live grid intelligence for an ISO, e.g. 'ERCOT', 'PJM'."""
+        return self.call("get_grid_data", iso=iso)

dchub-0.1.0.dist-info/METADATA

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: dchub
+Version: 0.1.0
+Summary: DC Hub Python SDK — live data-center, power & gas intelligence over MCP.
+Author: DC Hub
+License: MIT
+Project-URL: Homepage, https://dchub.cloud
+Project-URL: Repository, https://github.com/azmartone67/dchub-mcp-server
+Keywords: data-center,energy,mcp,grid,infrastructure
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+
+# dchub — Python SDK
+
+Live data-center, power & gas intelligence for AI agents. Hides the MCP JSON-RPC
+handshake (`initialize` → `notifications/initialized` → `tools/call`, SSE
+parsing) behind a thin client. **Zero runtime dependencies** (stdlib only).
+
+## Install
+```bash
+pip install dchub          # from this repo: pip install ./sdk/python
+```
+
+## Quickstart (5 lines)
+```python
+from dchub import DCHub
+dc = DCHub()                       # reads DCHUB_API_KEY from env if set
+print(dc.market("northern-virginia"))   # market intel
+print(dc.search(state="VA"))            # facility search (canonical slugs)
+print(dc.grid(iso="ERCOT"))             # live grid intel
+```
+
+## API
+| Method | Tool | Returns |
+|--------|------|---------|
+| `dc.market(slug)` | `get_market_intel` | by-status counts, operators, recent facilities |
+| `dc.search(q, state, country, limit)` | `search_facilities` | rows w/ canonical slug, provider, location |
+| `dc.grid(iso)` | `get_grid_data` | live demand / mix / headroom |
+| `dc.call(tool, **args)` | *any of 38* | cleaned data payload |
+| `dc.tools()` | `tools/list` | list of 38 tool names |
+
+## Auth & tiers
+Set `DCHUB_API_KEY` (sent as `X-API-Key`) for full data:
+```bash
+curl -X POST https://dchub.cloud/api/v1/keys/claim -d '{"client_name":"python-sdk"}'
+export DCHUB_API_KEY=dch_live_...
+```
+On the **free tier** some fields are masked and `grid` returns a gated preview;
+the SDK strips the upsell wrapper and returns the real embedded payload either
+way. Source/citation: https://dchub.cloud (CC-BY-4.0).
+
+## Tests
+```bash
+pip install -e ".[test]" && pytest        # 5 live, gate-graceful tests
+```
+
+> Packaging is configured but **not published** — the maintainer runs
+> `python -m build && twine upload` to ship to PyPI.

dchub-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+dchub/__init__.py,sha256=vxv_lrcBK-8z0JbLQH7x45oiXigfSSplt66Iq8sNINc,150
+dchub/client.py,sha256=VjsaVkVCOfLQ6Fj2quOsB9_IORxLPUk4GuPIs8NM85g,6028
+dchub-0.1.0.dist-info/METADATA,sha256=YDNPb-AGza2TYiPpMg6ykvNc93fzLd_hLerohNP_gCE,2228
+dchub-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+dchub-0.1.0.dist-info/top_level.txt,sha256=MleyxETg_be7Dvso8yPCSXbeyvW_FFoUazCaSEztOVY,6
+dchub-0.1.0.dist-info/RECORD,,

dchub-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
+

dchub-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dchub