dchub 0.1.0__tar.gz

dchub-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,46 @@
+# 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/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-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/dchub.egg-info/PKG-INFO

@@ -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/dchub.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+dchub/__init__.py
+dchub/client.py
+dchub.egg-info/PKG-INFO
+dchub.egg-info/SOURCES.txt
+dchub.egg-info/dependency_links.txt
+dchub.egg-info/requires.txt
+dchub.egg-info/top_level.txt
+tests/test_client.py

dchub-0.1.0/dchub.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dchub-0.1.0/dchub.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[test]
+pytest>=7

dchub-0.1.0/dchub.egg-info/top_level.txt

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

dchub-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dchub"
+version = "0.1.0"
+description = "DC Hub Python SDK — live data-center, power & gas intelligence over MCP."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "DC Hub" }]
+keywords = ["data-center", "energy", "mcp", "grid", "infrastructure"]
+dependencies = []          # stdlib only (urllib) — zero runtime deps
+
+[project.urls]
+Homepage = "https://dchub.cloud"
+Repository = "https://github.com/azmartone67/dchub-mcp-server"
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[tool.setuptools]
+packages = ["dchub"]

dchub-0.1.0/setup.cfg

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

dchub-0.1.0/tests/test_client.py

@@ -0,0 +1,38 @@
+"""Live tests for the DC Hub Python SDK (free tier; gate-graceful)."""
+from dchub import DCHub
+
+
+def test_tools_list_is_38():
+    assert len(DCHub().tools()) == 38
+
+
+def test_market_returns_real_data():
+    d = DCHub().market("northern-virginia")
+    assert isinstance(d, dict)
+    # Free tier rotates between the full payload and a 1-result preview gate;
+    # accept either (gate-graceful), but when data is present it must be real.
+    if "market" in d:
+        assert "northern virginia" in d["market"]["name"].lower()
+        assert sum(d["by_status"].values()) > 0
+    else:
+        assert "text" in d  # gated preview wrapper, stripped to its text
+
+
+def test_search_returns_canonical_slug():
+    d = DCHub().search(state="VA", limit=3)
+    rows = d.get("data", [])
+    assert rows and all("slug" in r for r in rows)
+
+
+def test_clean_strips_upsell_wrapper():
+    # A text blob with an upsell-only object then the real payload.
+    blob = ('marketing...\n---\n{"agent_action":{"x":1}}\n---\n'
+            '{"stats":{"facility_count":739},"success":true}')
+    out = DCHub._clean(blob)
+    assert out == {"stats": {"facility_count": 739}, "success": True}
+
+
+def test_grid_call_does_not_raise():
+    # Free tier gates grid to a preview; SDK should still return cleanly.
+    g = DCHub().grid("ERCOT")
+    assert isinstance(g, dict)