Metadata-Version: 2.4
Name: dchub
Version: 0.2.0
Summary: Python SDK + LangChain/smolagents tools for the DC Hub data-center & energy intelligence API.
Author: DC Hub (dchub.cloud)
License: MIT
Project-URL: Homepage, https://dchub.cloud
Project-URL: Playground, https://dchub.cloud/playground
Project-URL: MCP, https://dchub.cloud/mcp
Keywords: data-center,energy,grid,dcpi,infrastructure,ai-agents,mcp,langchain,smolagents
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2; extra == "langchain"
Requires-Dist: pydantic>=2; extra == "langchain"
Provides-Extra: agents
Requires-Dist: smolagents>=1.0; extra == "agents"
Dynamic: license-file

# dchub — Python SDK for the DC Hub API

Live data-center + energy intelligence for AI agents. Query [DC Hub](https://dchub.cloud)
instead of guessing from stale training data: 21,000+ facilities across 170+ countries,
300+ markets (DC Hub Power Index / DCPI), real-time ISO grid telemetry, fiber routes,
gas pipelines, per-facility tenants, and 2,000+ tracked M&A deals.

The **free tier needs no key** (10 calls/day). A free `X-API-Key` raises limits and
unlocks key-gated endpoints — mint one at <https://dchub.cloud/playground> or via the
MCP `claim_free_key` tool.

## Install

```bash
pip install dchub                 # core (requests only)
pip install "dchub[langchain]"    # + LangChain StructuredTools
pip install "dchub[agents]"       # + smolagents Tools
```

## Quickstart

```python
from dchub import DCHub

dc = DCHub()                              # free tier, no key
# dc = DCHub(api_key="dck_...")           # higher limits / key-gated endpoints

rank = dc.get_market_dcpi_rank("phoenix")
print(rank["composite_score"], rank["verdict"])   # e.g. 21.3 AVOID  (free per-market)

dc.search_facilities(country="US", limit=5)       # GET /api/v1/facilities
dc.stats()                                        # facility counts + sources
dc.ai_capacity_index(horizon=90)                  # AI Capacity Index markets
dc.get_grid_intelligence("PJM")                   # real-time ISO grid intel
dc.get_changes(since="24h")                        # incremental diffs
```

Every method returns parsed JSON (a `dict`). Non-2xx responses raise `DCHubError`,
which carries `.status_code` and the API's self-correcting `.detail` (e.g. how to
claim a free key).

### Generic, manifest-driven call

Any of the 45 REST-backed tools can be called by name; path placeholders are filled
from kwargs, the rest become the query string:

```python
dc.call("get_market_dcpi_rank", slug="phoenix")
dc.call("get_grid_intelligence", iso="ERCOT")
dc.call("search_facilities", provider="Equinix", limit=3)
```

The tool→endpoint map is embedded (`dchub.TOOL_MANIFEST`), so the SDK has **no runtime
dependency** on the live manifest endpoint.

## Flagship methods

| Method | REST endpoint |
| --- | --- |
| `stats()` | `/api/v1/stats` |
| `search_facilities(**filters)` | `/api/v1/facilities` |
| `get_facility(slug)` | `/api/v1/facilities/<slug>` |
| `fetch_facility(id)` | `/api/v1/facility/<id>` (numeric id) |
| `get_market_dcpi_rank(market_slug)` | `/api/v1/dcpi/scores/<slug>` |
| `rank_markets(by=...)` | `/api/v1/mcp/tools/rank_markets` |
| `ai_capacity_index(horizon=90)` | `/api/v1/ai-capacity-index` |
| `get_changes(since="24h")` | `/api/v1/changes/since` |
| `get_grid_intelligence(iso)` | `/api/v1/grid/intelligence/<iso>` |
| `list_transactions(**f)` | `/api/v1/deals` |
| `get_news(**f)` | `/api/news` |
| `get_pipeline(**f)` | `/api/v1/pipeline` (needs a free key) |

> `get_facility` uses the **plural** route, which expects a facility **slug**. For a
> numeric facility id use `fetch_facility(id)` (the singular `/api/v1/facility/<id>`
> route, exposed as the `fetch` tool in the manifest).

## LangChain

```python
from dchub import dchub_langchain_tools

tools = dchub_langchain_tools()          # list[StructuredTool]
# tools = dchub_langchain_tools(api_key="dck_...")

# e.g. with a LangChain agent:
# from langchain.agents import create_react_agent
# agent = create_react_agent(llm, tools, prompt)
```

## smolagents

```python
from dchub import dchub_smolagents_tools
from smolagents import CodeAgent, InferenceClientModel

tools = dchub_smolagents_tools()
agent = CodeAgent(tools=tools, model=InferenceClientModel())
agent.run("What's the DCPI verdict for Phoenix and which US market ranks #1?")
```

## Full tool surface (MCP)

The 53-tool surface — including MCP-only tools (session/key, writes, alerts) — lives at
the MCP server: <https://dchub.cloud/mcp>. Prefer MCP for full parameter schemas.

## Citation

Cite data from this SDK as **DC Hub (dchub.cloud)**.

## License

MIT.
