Metadata-Version: 2.5
Name: cortexhub
Version: 3.0.0
Summary: CortexHub platform SDK: point your agent at the governed LLM router + MCP gateway.
Project-URL: Homepage, https://cortexhub.ai
Project-URL: Documentation, https://docs.cortexhub.ai
Author-email: CortexHub <hello@cortexhub.ai>
License: MIT
License-File: LICENSE
Keywords: agents,ai,governance,mcp,programmatic
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Provides-Extra: ai
Requires-Dist: openai>=1.40; extra == 'ai'
Provides-Extra: all
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: openai>=1.40; extra == 'all'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# cortexhub

The **CortexHub platform SDK**. One API key points your existing agent at two
governed planes:

- the **LLM router** (inference) - OpenAI-compatible, so any framework works,
  with routing, caching, compression, governance, and per-agent metering; and
- the **MCP gateway** (tools + brain + files) - governed, consent-gated,
  injection-defended.

You don't rewrite your agent. You change a base URL and drop in one key.

[Documentation](https://docs.cortexhub.ai/docs/sdks/overview)

## Install

```bash
pip install cortexhub          # zero-dependency core (URLs + headers)
pip install 'cortexhub[ai]'    # + a ready OpenAI-compatible client via cx.llm
pip install 'cortexhub[mcp]'   # + the official MCP client for cx.mcp() sessions
```

## The key

Onboard an external AI employee in the CortexHub dashboard, grant it
capabilities, and mint an API key **bound to that agent** (Settings ->
API keys, or the agent's page). The `cxh_key_...` *is* that agent's identity -
every call is attributed, governed, and metered to it. No agent argument needed.

```python
from cortexhub import Cortexhub
cx = Cortexhub(api_key="cxh_key_...")   # or set CORTEXHUB_API_KEY
```

## Inference

`cx.ai` gives you everything any OpenAI-compatible client needs; `cx.llm` is a
ready client (extra: `cortexhub[ai]`). Pick the model with the `model` argument:
`cortexhub/auto` to let CortexHub route per turn, or any model enabled on the
platform.

```python
cx.llm.chat.completions.create(model="cortexhub/auto", messages=[{"role": "user", "content": "hi"}])
cx.llm.responses.create(model="cortexhub/auto", input="hi")
cx.llm.models.list()

cx.ai.base_url   # e.g. https://api.cortexhub.ai/v1  (override with CORTEXHUB_ROUTER_URL)
cx.ai.api_key    # your cxh_key_...
```

## Use your existing framework

The router speaks the OpenAI wire protocol, so every framework integrates the
same way: point its OpenAI-compatible provider at `cx.ai.base_url`, pass
`cx.ai.api_key`, and choose a `model`.

```python
base, key = cx.ai.base_url, cx.ai.api_key

# OpenAI SDK / plain
from openai import OpenAI
OpenAI(base_url=base, api_key=key).chat.completions.create(model="cortexhub/auto", messages=[...])

# LangChain / LangGraph
from langchain_openai import ChatOpenAI
ChatOpenAI(base_url=base, api_key=key, model="cortexhub/auto")

# CrewAI (LiteLLM under the hood)
from crewai import LLM
LLM(model="openai/cortexhub/auto", base_url=base, api_key=key)

# AutoGen
from autogen_ext.models.openai import OpenAIChatCompletionClient
OpenAIChatCompletionClient(model="cortexhub/auto", base_url=base, api_key=key)

# Pydantic AI
from pydantic_ai.models.openai import OpenAIModel
from pydantic_ai.providers.openai import OpenAIProvider
OpenAIModel("cortexhub/auto", provider=OpenAIProvider(base_url=base, api_key=key))
```

**Anthropic SDK:** the router is OpenAI-compatible, not Anthropic-Messages, so
point the *OpenAI* client at CortexHub with a `claude-*` model (we route to
Claude) rather than the Anthropic SDK.

## Tools, brain, and files (MCP gateway)

`cx.mcp(agent=...)` returns the MCP connection your agent's loop drives. Any
MCP-capable framework can register it as a server; the `cortexhub_*` tools
(governed toolkit calls, brain recall/learn, files search) then appear
automatically.

```python
conn = cx.mcp(agent="invoice-bot", end_user_subject="user_42")
conn.url       # https://mcp.cortexhub.ai/v1/mcp
conn.headers   # ready to wire into your MCP transport
```

## Authentication modes

- **API key** (`api_key=cxh_key_...`, or `CORTEXHUB_API_KEY`) - backends whose
  end users do not have CortexHub accounts. Attest the end user per call with
  `end_user_subject`. Required for `cx.ai` / `cx.llm`.
- **MCP OAuth client** (`client_id=` / `client_secret=`) - for interactive
  CortexHub users, MCP gateway only.

The MCP gateway also accepts MCP OAuth from third-party clients (Claude, Cursor)
independently of this SDK.
