cortexhub 3.0.0__tar.gz → 3.1.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- cortexhub-3.1.1/PKG-INFO +280 -0
- cortexhub-3.1.1/README.md +251 -0
- {cortexhub-3.0.0 → cortexhub-3.1.1}/pyproject.toml +1 -1
- {cortexhub-3.0.0 → cortexhub-3.1.1}/src/cortexhub/__init__.py +1 -1
- {cortexhub-3.0.0 → cortexhub-3.1.1}/src/cortexhub/client.py +14 -2
- {cortexhub-3.0.0 → cortexhub-3.1.1}/src/cortexhub/mcp_key.py +46 -0
- cortexhub-3.1.1/src/cortexhub/session.py +89 -0
- cortexhub-3.0.0/PKG-INFO +0 -137
- cortexhub-3.0.0/README.md +0 -108
- cortexhub-3.0.0/src/cortexhub/session.py +0 -13
- {cortexhub-3.0.0 → cortexhub-3.1.1}/.gitignore +0 -0
- {cortexhub-3.0.0 → cortexhub-3.1.1}/LICENSE +0 -0
- {cortexhub-3.0.0 → cortexhub-3.1.1}/src/cortexhub/_config.py +0 -0
- {cortexhub-3.0.0 → cortexhub-3.1.1}/src/cortexhub/ai.py +0 -0
- {cortexhub-3.0.0 → cortexhub-3.1.1}/src/cortexhub/errors.py +0 -0
- {cortexhub-3.0.0 → cortexhub-3.1.1}/src/cortexhub/mcp_oauth.py +0 -0
cortexhub-3.1.1/PKG-INFO
ADDED
|
@@ -0,0 +1,280 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: cortexhub
|
|
3
|
+
Version: 3.1.1
|
|
4
|
+
Summary: CortexHub platform SDK: point your agent at the governed LLM router + MCP gateway.
|
|
5
|
+
Project-URL: Homepage, https://cortexhub.ai
|
|
6
|
+
Project-URL: Documentation, https://docs.cortexhub.ai
|
|
7
|
+
Author-email: CortexHub <hello@cortexhub.ai>
|
|
8
|
+
License: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: agents,ai,governance,mcp,programmatic
|
|
11
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
20
|
+
Requires-Python: >=3.10
|
|
21
|
+
Provides-Extra: ai
|
|
22
|
+
Requires-Dist: openai>=1.40; extra == 'ai'
|
|
23
|
+
Provides-Extra: all
|
|
24
|
+
Requires-Dist: mcp>=1.0; extra == 'all'
|
|
25
|
+
Requires-Dist: openai>=1.40; extra == 'all'
|
|
26
|
+
Provides-Extra: mcp
|
|
27
|
+
Requires-Dist: mcp>=1.0; extra == 'mcp'
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
|
|
30
|
+
# cortexhub
|
|
31
|
+
|
|
32
|
+
The **CortexHub platform SDK**. One API key points your existing agent at two
|
|
33
|
+
governed planes:
|
|
34
|
+
|
|
35
|
+
- the **LLM router** (inference) - OpenAI-compatible, so any framework works,
|
|
36
|
+
with routing, caching, compression, governance, and per-agent metering; and
|
|
37
|
+
- the **MCP gateway** (tools + brain + files) - governed, consent-gated,
|
|
38
|
+
injection-defended.
|
|
39
|
+
|
|
40
|
+
You don't rewrite your agent. You change a base URL and drop in one key.
|
|
41
|
+
|
|
42
|
+
[Documentation](https://docs.cortexhub.ai/docs/sdks/overview)
|
|
43
|
+
|
|
44
|
+
## Install
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
pip install cortexhub # zero-dependency core (URLs + headers)
|
|
48
|
+
pip install 'cortexhub[ai]' # + a ready OpenAI-compatible client via cx.llm
|
|
49
|
+
pip install 'cortexhub[mcp]' # + the official MCP client for cx.mcp() sessions
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## The key
|
|
53
|
+
|
|
54
|
+
Onboard an external AI employee in the CortexHub dashboard, grant it
|
|
55
|
+
capabilities, and mint an API key **bound to that agent** (Settings ->
|
|
56
|
+
API keys, or the agent's page). The `cxh_key_...` *is* that agent's identity -
|
|
57
|
+
every call is attributed, governed, and metered to it. No agent argument needed.
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
from cortexhub import Cortexhub
|
|
61
|
+
cx = Cortexhub(api_key="cxh_key_...") # or set CORTEXHUB_API_KEY
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Run a session (recommended)
|
|
65
|
+
|
|
66
|
+
Your agent runs in your own runtime, but every run should show up in CortexHub
|
|
67
|
+
with the same visibility as a co-worker on CortexHub's runtime -- one **Session**
|
|
68
|
+
in the Sessions tab, with its Trace, Spans, cost, and user attribution.
|
|
69
|
+
|
|
70
|
+
Use one `cx.session(...)` handle for the whole run. Pass the identity only your
|
|
71
|
+
app knows: a stable **session id** (your id for the conversation or autonomous
|
|
72
|
+
run) and the **end user** it acts for. The handle's `.llm` (inference) and `.mcp`
|
|
73
|
+
(tools) both land in that one session.
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
s = cx.session(
|
|
77
|
+
agent="support-bot",
|
|
78
|
+
mcp_session_id="conv-42", # your stable id -> one CortexHub session
|
|
79
|
+
end_user_subject="user_42", # who it acts for (None for an autonomous run)
|
|
80
|
+
)
|
|
81
|
+
|
|
82
|
+
# Inference (OpenAI-compatible). model="cortexhub/auto" lets CortexHub route per
|
|
83
|
+
# turn; or pass any model enabled on the platform.
|
|
84
|
+
s.llm.chat.completions.create(model="cortexhub/auto", messages=[{"role": "user", "content": "hi"}])
|
|
85
|
+
|
|
86
|
+
# Tools + brain + files, in the SAME session:
|
|
87
|
+
s.mcp.url # https://mcp.cortexhub.ai/v1/mcp
|
|
88
|
+
s.mcp.headers # wire into your MCP transport (see "Tools" below)
|
|
89
|
+
|
|
90
|
+
s.session_id # "conv-42" -- log or forward it to correlate
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Reuse the same handle across the run's turns so they group. An autonomous agent
|
|
94
|
+
(e.g. a cron job) does the same with a per-run id and no `end_user_subject`
|
|
95
|
+
(extra for `.llm`: `cortexhub[ai]`).
|
|
96
|
+
|
|
97
|
+
## Inference without a session
|
|
98
|
+
|
|
99
|
+
For a quick, standalone call, `cx.llm` is a ready OpenAI-compatible client and
|
|
100
|
+
`cx.ai` gives the raw `base_url` + `api_key` any framework needs. These are NOT
|
|
101
|
+
grouped into a session (no Sessions row) -- prefer `cx.session(...)` above when
|
|
102
|
+
you want the run visible in CortexHub.
|
|
103
|
+
|
|
104
|
+
```python
|
|
105
|
+
cx.llm.chat.completions.create(model="cortexhub/auto", messages=[...])
|
|
106
|
+
cx.llm.responses.create(model="cortexhub/auto", input="hi")
|
|
107
|
+
cx.llm.models.list()
|
|
108
|
+
|
|
109
|
+
cx.ai.base_url # e.g. https://api.cortexhub.ai/v1 (override with CORTEXHUB_ROUTER_URL)
|
|
110
|
+
cx.ai.api_key # your cxh_key_...
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
## Use your existing framework
|
|
114
|
+
|
|
115
|
+
The router speaks the OpenAI wire protocol, so every framework integrates the
|
|
116
|
+
same way: point its OpenAI-compatible provider at `cx.ai.base_url`, pass
|
|
117
|
+
`cx.ai.api_key`, and choose a `model`.
|
|
118
|
+
|
|
119
|
+
```python
|
|
120
|
+
base, key = cx.ai.base_url, cx.ai.api_key
|
|
121
|
+
|
|
122
|
+
# OpenAI SDK / plain
|
|
123
|
+
from openai import OpenAI
|
|
124
|
+
OpenAI(base_url=base, api_key=key).chat.completions.create(model="cortexhub/auto", messages=[...])
|
|
125
|
+
|
|
126
|
+
# LangChain / LangGraph
|
|
127
|
+
from langchain_openai import ChatOpenAI
|
|
128
|
+
ChatOpenAI(base_url=base, api_key=key, model="cortexhub/auto")
|
|
129
|
+
|
|
130
|
+
# CrewAI (LiteLLM under the hood)
|
|
131
|
+
from crewai import LLM
|
|
132
|
+
LLM(model="openai/cortexhub/auto", base_url=base, api_key=key)
|
|
133
|
+
|
|
134
|
+
# AutoGen
|
|
135
|
+
from autogen_ext.models.openai import OpenAIChatCompletionClient
|
|
136
|
+
OpenAIChatCompletionClient(model="cortexhub/auto", base_url=base, api_key=key)
|
|
137
|
+
|
|
138
|
+
# Pydantic AI
|
|
139
|
+
from pydantic_ai.models.openai import OpenAIModel
|
|
140
|
+
from pydantic_ai.providers.openai import OpenAIProvider
|
|
141
|
+
OpenAIModel("cortexhub/auto", provider=OpenAIProvider(base_url=base, api_key=key))
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
**Anthropic SDK:** the router is OpenAI-compatible, not Anthropic-Messages, so
|
|
145
|
+
point the *OpenAI* client at CortexHub with a `claude-*` model (we route to
|
|
146
|
+
Claude) rather than the Anthropic SDK.
|
|
147
|
+
|
|
148
|
+
## Tools, brain, and files (MCP gateway)
|
|
149
|
+
|
|
150
|
+
`s.mcp` (the session handle above) is the MCP connection your agent's loop
|
|
151
|
+
drives. Any MCP-capable framework registers it as a server; the `cortexhub_*`
|
|
152
|
+
tools (governed toolkit calls, brain recall/learn, files search) then appear
|
|
153
|
+
automatically -- and, on the session handle, group with that run's LLM turns.
|
|
154
|
+
|
|
155
|
+
```python
|
|
156
|
+
conn = s.mcp # from cx.session(...) -> same session as .llm
|
|
157
|
+
conn.url # https://mcp.cortexhub.ai/v1/mcp
|
|
158
|
+
conn.headers # wire into your MCP transport
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
`cx.mcp(agent=..., end_user_subject=...)` is the standalone form when you only
|
|
162
|
+
need tools (no session grouping).
|
|
163
|
+
|
|
164
|
+
## A full turn: reason, act, and approvals
|
|
165
|
+
|
|
166
|
+
One session, end to end: the model reasons with `s.llm`, acts through the
|
|
167
|
+
governed `cortexhub_*` tools on `s.mcp`, and when a governed action needs the end
|
|
168
|
+
user's **approval** it comes back parked with a signed `consent_url` -- you show
|
|
169
|
+
that to the user and poll until they decide in CortexHub. Needs both extras:
|
|
170
|
+
`pip install 'cortexhub[ai,mcp]'`.
|
|
171
|
+
|
|
172
|
+
> **How consent reaches your user.** The gateway picks the consent surface from
|
|
173
|
+
> what your MCP client declares at initialize. A UI host that declares the
|
|
174
|
+
> MCP-UI / Tasks extension (e.g. claude.ai) gets consent rendered **inline**. A
|
|
175
|
+
> plain backend client like the one below declares neither, so the gateway hands
|
|
176
|
+
> it the **`consent_url` fallback** shown here -- a signed link you surface to
|
|
177
|
+
> your end user however your app does UI (a page, an email, a Slack DM), then
|
|
178
|
+
> poll `cortexhub_get_task` for the decision. This is the right pattern for a
|
|
179
|
+
> headless or autonomous agent (there is no host to render inline consent).
|
|
180
|
+
|
|
181
|
+
```python
|
|
182
|
+
import asyncio, json
|
|
183
|
+
from cortexhub import Cortexhub
|
|
184
|
+
from mcp import ClientSession
|
|
185
|
+
|
|
186
|
+
cx = Cortexhub(api_key="cxh_key_...")
|
|
187
|
+
|
|
188
|
+
async def run_turn(user_text: str) -> str:
|
|
189
|
+
# One session for this end user's conversation -> LLM + tools share it.
|
|
190
|
+
s = cx.session(agent="support-bot", mcp_session_id="conv-42", end_user_subject="user_42")
|
|
191
|
+
|
|
192
|
+
# s.mcp.open() opens the transport across mcp client versions.
|
|
193
|
+
async with s.mcp.open() as (read, write):
|
|
194
|
+
async with ClientSession(read, write) as mcp:
|
|
195
|
+
await mcp.initialize()
|
|
196
|
+
|
|
197
|
+
# Offer the governed cortexhub_* tools to the model.
|
|
198
|
+
listed = await mcp.list_tools()
|
|
199
|
+
tools = [{
|
|
200
|
+
"type": "function",
|
|
201
|
+
"function": {"name": t.name, "description": t.description or "",
|
|
202
|
+
"parameters": t.inputSchema or {"type": "object", "properties": {}}},
|
|
203
|
+
} for t in listed.tools]
|
|
204
|
+
|
|
205
|
+
messages = [{"role": "user", "content": user_text}]
|
|
206
|
+
for _ in range(8): # a few reason -> act rounds
|
|
207
|
+
msg = s.llm.chat.completions.create(
|
|
208
|
+
model="cortexhub/auto", messages=messages, tools=tools,
|
|
209
|
+
).choices[0].message
|
|
210
|
+
if not msg.tool_calls:
|
|
211
|
+
return msg.content or "" # final answer
|
|
212
|
+
|
|
213
|
+
messages.append(msg.model_dump())
|
|
214
|
+
for call in msg.tool_calls:
|
|
215
|
+
args = json.loads(call.function.arguments or "{}")
|
|
216
|
+
result = await mcp.call_tool(call.function.name, args)
|
|
217
|
+
text = _text(result)
|
|
218
|
+
|
|
219
|
+
task = _parked_task(result) # governed action -> needs approval?
|
|
220
|
+
if task:
|
|
221
|
+
print("Approve to continue:", task["consent_url"]) # show the end user
|
|
222
|
+
text = await _await_decision(mcp, task["task_id"]) # wait for the decision
|
|
223
|
+
|
|
224
|
+
messages.append({"role": "tool", "tool_call_id": call.id, "content": text})
|
|
225
|
+
return ""
|
|
226
|
+
|
|
227
|
+
# --- small helpers over the MCP result ---
|
|
228
|
+
def _text(result) -> str:
|
|
229
|
+
return "\n".join(b.text for b in result.content if getattr(b, "text", None)) or "{}"
|
|
230
|
+
|
|
231
|
+
def _payload(result):
|
|
232
|
+
sc = getattr(result, "structuredContent", None)
|
|
233
|
+
if sc:
|
|
234
|
+
return sc
|
|
235
|
+
try:
|
|
236
|
+
return json.loads(_text(result))
|
|
237
|
+
except json.JSONDecodeError:
|
|
238
|
+
return {}
|
|
239
|
+
|
|
240
|
+
def _parked_task(result):
|
|
241
|
+
# A parked approval comes back as an `mcp_task` carrying a signed consent_url.
|
|
242
|
+
def walk(node):
|
|
243
|
+
if isinstance(node, dict):
|
|
244
|
+
t = node.get("mcp_task")
|
|
245
|
+
if isinstance(t, dict) and t.get("consent_url"):
|
|
246
|
+
return t
|
|
247
|
+
for v in node.values():
|
|
248
|
+
if (found := walk(v)):
|
|
249
|
+
return found
|
|
250
|
+
elif isinstance(node, list):
|
|
251
|
+
for item in node:
|
|
252
|
+
if (found := walk(item)):
|
|
253
|
+
return found
|
|
254
|
+
return None
|
|
255
|
+
return walk(_payload(result))
|
|
256
|
+
|
|
257
|
+
async def _await_decision(mcp, task_id: str) -> str:
|
|
258
|
+
# Poll until the human decides in CortexHub; an approval runs the action.
|
|
259
|
+
for _ in range(600): # ~10 min at 1s waits
|
|
260
|
+
res = await mcp.call_tool("cortexhub_get_task", {"task_id": task_id, "wait_ms": 1000})
|
|
261
|
+
if _payload(res).get("terminal"):
|
|
262
|
+
return _text(res)
|
|
263
|
+
return "approval timed out"
|
|
264
|
+
|
|
265
|
+
print(asyncio.run(run_turn("Email the Q3 report to the finance team")))
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
The whole turn is one CortexHub session (`conv-42`): open its Sessions tab to see
|
|
269
|
+
the model step, each tool call, and the approval as a single trace.
|
|
270
|
+
|
|
271
|
+
## Authentication modes
|
|
272
|
+
|
|
273
|
+
- **API key** (`api_key=cxh_key_...`, or `CORTEXHUB_API_KEY`) - backends whose
|
|
274
|
+
end users do not have CortexHub accounts. Attest the end user per call with
|
|
275
|
+
`end_user_subject`. Required for `cx.ai` / `cx.llm`.
|
|
276
|
+
- **MCP OAuth client** (`client_id=` / `client_secret=`) - for interactive
|
|
277
|
+
CortexHub users, MCP gateway only.
|
|
278
|
+
|
|
279
|
+
The MCP gateway also accepts MCP OAuth from third-party clients (Claude, Cursor)
|
|
280
|
+
independently of this SDK.
|
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
# cortexhub
|
|
2
|
+
|
|
3
|
+
The **CortexHub platform SDK**. One API key points your existing agent at two
|
|
4
|
+
governed planes:
|
|
5
|
+
|
|
6
|
+
- the **LLM router** (inference) - OpenAI-compatible, so any framework works,
|
|
7
|
+
with routing, caching, compression, governance, and per-agent metering; and
|
|
8
|
+
- the **MCP gateway** (tools + brain + files) - governed, consent-gated,
|
|
9
|
+
injection-defended.
|
|
10
|
+
|
|
11
|
+
You don't rewrite your agent. You change a base URL and drop in one key.
|
|
12
|
+
|
|
13
|
+
[Documentation](https://docs.cortexhub.ai/docs/sdks/overview)
|
|
14
|
+
|
|
15
|
+
## Install
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
pip install cortexhub # zero-dependency core (URLs + headers)
|
|
19
|
+
pip install 'cortexhub[ai]' # + a ready OpenAI-compatible client via cx.llm
|
|
20
|
+
pip install 'cortexhub[mcp]' # + the official MCP client for cx.mcp() sessions
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## The key
|
|
24
|
+
|
|
25
|
+
Onboard an external AI employee in the CortexHub dashboard, grant it
|
|
26
|
+
capabilities, and mint an API key **bound to that agent** (Settings ->
|
|
27
|
+
API keys, or the agent's page). The `cxh_key_...` *is* that agent's identity -
|
|
28
|
+
every call is attributed, governed, and metered to it. No agent argument needed.
|
|
29
|
+
|
|
30
|
+
```python
|
|
31
|
+
from cortexhub import Cortexhub
|
|
32
|
+
cx = Cortexhub(api_key="cxh_key_...") # or set CORTEXHUB_API_KEY
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Run a session (recommended)
|
|
36
|
+
|
|
37
|
+
Your agent runs in your own runtime, but every run should show up in CortexHub
|
|
38
|
+
with the same visibility as a co-worker on CortexHub's runtime -- one **Session**
|
|
39
|
+
in the Sessions tab, with its Trace, Spans, cost, and user attribution.
|
|
40
|
+
|
|
41
|
+
Use one `cx.session(...)` handle for the whole run. Pass the identity only your
|
|
42
|
+
app knows: a stable **session id** (your id for the conversation or autonomous
|
|
43
|
+
run) and the **end user** it acts for. The handle's `.llm` (inference) and `.mcp`
|
|
44
|
+
(tools) both land in that one session.
|
|
45
|
+
|
|
46
|
+
```python
|
|
47
|
+
s = cx.session(
|
|
48
|
+
agent="support-bot",
|
|
49
|
+
mcp_session_id="conv-42", # your stable id -> one CortexHub session
|
|
50
|
+
end_user_subject="user_42", # who it acts for (None for an autonomous run)
|
|
51
|
+
)
|
|
52
|
+
|
|
53
|
+
# Inference (OpenAI-compatible). model="cortexhub/auto" lets CortexHub route per
|
|
54
|
+
# turn; or pass any model enabled on the platform.
|
|
55
|
+
s.llm.chat.completions.create(model="cortexhub/auto", messages=[{"role": "user", "content": "hi"}])
|
|
56
|
+
|
|
57
|
+
# Tools + brain + files, in the SAME session:
|
|
58
|
+
s.mcp.url # https://mcp.cortexhub.ai/v1/mcp
|
|
59
|
+
s.mcp.headers # wire into your MCP transport (see "Tools" below)
|
|
60
|
+
|
|
61
|
+
s.session_id # "conv-42" -- log or forward it to correlate
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Reuse the same handle across the run's turns so they group. An autonomous agent
|
|
65
|
+
(e.g. a cron job) does the same with a per-run id and no `end_user_subject`
|
|
66
|
+
(extra for `.llm`: `cortexhub[ai]`).
|
|
67
|
+
|
|
68
|
+
## Inference without a session
|
|
69
|
+
|
|
70
|
+
For a quick, standalone call, `cx.llm` is a ready OpenAI-compatible client and
|
|
71
|
+
`cx.ai` gives the raw `base_url` + `api_key` any framework needs. These are NOT
|
|
72
|
+
grouped into a session (no Sessions row) -- prefer `cx.session(...)` above when
|
|
73
|
+
you want the run visible in CortexHub.
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
cx.llm.chat.completions.create(model="cortexhub/auto", messages=[...])
|
|
77
|
+
cx.llm.responses.create(model="cortexhub/auto", input="hi")
|
|
78
|
+
cx.llm.models.list()
|
|
79
|
+
|
|
80
|
+
cx.ai.base_url # e.g. https://api.cortexhub.ai/v1 (override with CORTEXHUB_ROUTER_URL)
|
|
81
|
+
cx.ai.api_key # your cxh_key_...
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Use your existing framework
|
|
85
|
+
|
|
86
|
+
The router speaks the OpenAI wire protocol, so every framework integrates the
|
|
87
|
+
same way: point its OpenAI-compatible provider at `cx.ai.base_url`, pass
|
|
88
|
+
`cx.ai.api_key`, and choose a `model`.
|
|
89
|
+
|
|
90
|
+
```python
|
|
91
|
+
base, key = cx.ai.base_url, cx.ai.api_key
|
|
92
|
+
|
|
93
|
+
# OpenAI SDK / plain
|
|
94
|
+
from openai import OpenAI
|
|
95
|
+
OpenAI(base_url=base, api_key=key).chat.completions.create(model="cortexhub/auto", messages=[...])
|
|
96
|
+
|
|
97
|
+
# LangChain / LangGraph
|
|
98
|
+
from langchain_openai import ChatOpenAI
|
|
99
|
+
ChatOpenAI(base_url=base, api_key=key, model="cortexhub/auto")
|
|
100
|
+
|
|
101
|
+
# CrewAI (LiteLLM under the hood)
|
|
102
|
+
from crewai import LLM
|
|
103
|
+
LLM(model="openai/cortexhub/auto", base_url=base, api_key=key)
|
|
104
|
+
|
|
105
|
+
# AutoGen
|
|
106
|
+
from autogen_ext.models.openai import OpenAIChatCompletionClient
|
|
107
|
+
OpenAIChatCompletionClient(model="cortexhub/auto", base_url=base, api_key=key)
|
|
108
|
+
|
|
109
|
+
# Pydantic AI
|
|
110
|
+
from pydantic_ai.models.openai import OpenAIModel
|
|
111
|
+
from pydantic_ai.providers.openai import OpenAIProvider
|
|
112
|
+
OpenAIModel("cortexhub/auto", provider=OpenAIProvider(base_url=base, api_key=key))
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
**Anthropic SDK:** the router is OpenAI-compatible, not Anthropic-Messages, so
|
|
116
|
+
point the *OpenAI* client at CortexHub with a `claude-*` model (we route to
|
|
117
|
+
Claude) rather than the Anthropic SDK.
|
|
118
|
+
|
|
119
|
+
## Tools, brain, and files (MCP gateway)
|
|
120
|
+
|
|
121
|
+
`s.mcp` (the session handle above) is the MCP connection your agent's loop
|
|
122
|
+
drives. Any MCP-capable framework registers it as a server; the `cortexhub_*`
|
|
123
|
+
tools (governed toolkit calls, brain recall/learn, files search) then appear
|
|
124
|
+
automatically -- and, on the session handle, group with that run's LLM turns.
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
conn = s.mcp # from cx.session(...) -> same session as .llm
|
|
128
|
+
conn.url # https://mcp.cortexhub.ai/v1/mcp
|
|
129
|
+
conn.headers # wire into your MCP transport
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
`cx.mcp(agent=..., end_user_subject=...)` is the standalone form when you only
|
|
133
|
+
need tools (no session grouping).
|
|
134
|
+
|
|
135
|
+
## A full turn: reason, act, and approvals
|
|
136
|
+
|
|
137
|
+
One session, end to end: the model reasons with `s.llm`, acts through the
|
|
138
|
+
governed `cortexhub_*` tools on `s.mcp`, and when a governed action needs the end
|
|
139
|
+
user's **approval** it comes back parked with a signed `consent_url` -- you show
|
|
140
|
+
that to the user and poll until they decide in CortexHub. Needs both extras:
|
|
141
|
+
`pip install 'cortexhub[ai,mcp]'`.
|
|
142
|
+
|
|
143
|
+
> **How consent reaches your user.** The gateway picks the consent surface from
|
|
144
|
+
> what your MCP client declares at initialize. A UI host that declares the
|
|
145
|
+
> MCP-UI / Tasks extension (e.g. claude.ai) gets consent rendered **inline**. A
|
|
146
|
+
> plain backend client like the one below declares neither, so the gateway hands
|
|
147
|
+
> it the **`consent_url` fallback** shown here -- a signed link you surface to
|
|
148
|
+
> your end user however your app does UI (a page, an email, a Slack DM), then
|
|
149
|
+
> poll `cortexhub_get_task` for the decision. This is the right pattern for a
|
|
150
|
+
> headless or autonomous agent (there is no host to render inline consent).
|
|
151
|
+
|
|
152
|
+
```python
|
|
153
|
+
import asyncio, json
|
|
154
|
+
from cortexhub import Cortexhub
|
|
155
|
+
from mcp import ClientSession
|
|
156
|
+
|
|
157
|
+
cx = Cortexhub(api_key="cxh_key_...")
|
|
158
|
+
|
|
159
|
+
async def run_turn(user_text: str) -> str:
|
|
160
|
+
# One session for this end user's conversation -> LLM + tools share it.
|
|
161
|
+
s = cx.session(agent="support-bot", mcp_session_id="conv-42", end_user_subject="user_42")
|
|
162
|
+
|
|
163
|
+
# s.mcp.open() opens the transport across mcp client versions.
|
|
164
|
+
async with s.mcp.open() as (read, write):
|
|
165
|
+
async with ClientSession(read, write) as mcp:
|
|
166
|
+
await mcp.initialize()
|
|
167
|
+
|
|
168
|
+
# Offer the governed cortexhub_* tools to the model.
|
|
169
|
+
listed = await mcp.list_tools()
|
|
170
|
+
tools = [{
|
|
171
|
+
"type": "function",
|
|
172
|
+
"function": {"name": t.name, "description": t.description or "",
|
|
173
|
+
"parameters": t.inputSchema or {"type": "object", "properties": {}}},
|
|
174
|
+
} for t in listed.tools]
|
|
175
|
+
|
|
176
|
+
messages = [{"role": "user", "content": user_text}]
|
|
177
|
+
for _ in range(8): # a few reason -> act rounds
|
|
178
|
+
msg = s.llm.chat.completions.create(
|
|
179
|
+
model="cortexhub/auto", messages=messages, tools=tools,
|
|
180
|
+
).choices[0].message
|
|
181
|
+
if not msg.tool_calls:
|
|
182
|
+
return msg.content or "" # final answer
|
|
183
|
+
|
|
184
|
+
messages.append(msg.model_dump())
|
|
185
|
+
for call in msg.tool_calls:
|
|
186
|
+
args = json.loads(call.function.arguments or "{}")
|
|
187
|
+
result = await mcp.call_tool(call.function.name, args)
|
|
188
|
+
text = _text(result)
|
|
189
|
+
|
|
190
|
+
task = _parked_task(result) # governed action -> needs approval?
|
|
191
|
+
if task:
|
|
192
|
+
print("Approve to continue:", task["consent_url"]) # show the end user
|
|
193
|
+
text = await _await_decision(mcp, task["task_id"]) # wait for the decision
|
|
194
|
+
|
|
195
|
+
messages.append({"role": "tool", "tool_call_id": call.id, "content": text})
|
|
196
|
+
return ""
|
|
197
|
+
|
|
198
|
+
# --- small helpers over the MCP result ---
|
|
199
|
+
def _text(result) -> str:
|
|
200
|
+
return "\n".join(b.text for b in result.content if getattr(b, "text", None)) or "{}"
|
|
201
|
+
|
|
202
|
+
def _payload(result):
|
|
203
|
+
sc = getattr(result, "structuredContent", None)
|
|
204
|
+
if sc:
|
|
205
|
+
return sc
|
|
206
|
+
try:
|
|
207
|
+
return json.loads(_text(result))
|
|
208
|
+
except json.JSONDecodeError:
|
|
209
|
+
return {}
|
|
210
|
+
|
|
211
|
+
def _parked_task(result):
|
|
212
|
+
# A parked approval comes back as an `mcp_task` carrying a signed consent_url.
|
|
213
|
+
def walk(node):
|
|
214
|
+
if isinstance(node, dict):
|
|
215
|
+
t = node.get("mcp_task")
|
|
216
|
+
if isinstance(t, dict) and t.get("consent_url"):
|
|
217
|
+
return t
|
|
218
|
+
for v in node.values():
|
|
219
|
+
if (found := walk(v)):
|
|
220
|
+
return found
|
|
221
|
+
elif isinstance(node, list):
|
|
222
|
+
for item in node:
|
|
223
|
+
if (found := walk(item)):
|
|
224
|
+
return found
|
|
225
|
+
return None
|
|
226
|
+
return walk(_payload(result))
|
|
227
|
+
|
|
228
|
+
async def _await_decision(mcp, task_id: str) -> str:
|
|
229
|
+
# Poll until the human decides in CortexHub; an approval runs the action.
|
|
230
|
+
for _ in range(600): # ~10 min at 1s waits
|
|
231
|
+
res = await mcp.call_tool("cortexhub_get_task", {"task_id": task_id, "wait_ms": 1000})
|
|
232
|
+
if _payload(res).get("terminal"):
|
|
233
|
+
return _text(res)
|
|
234
|
+
return "approval timed out"
|
|
235
|
+
|
|
236
|
+
print(asyncio.run(run_turn("Email the Q3 report to the finance team")))
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
The whole turn is one CortexHub session (`conv-42`): open its Sessions tab to see
|
|
240
|
+
the model step, each tool call, and the approval as a single trace.
|
|
241
|
+
|
|
242
|
+
## Authentication modes
|
|
243
|
+
|
|
244
|
+
- **API key** (`api_key=cxh_key_...`, or `CORTEXHUB_API_KEY`) - backends whose
|
|
245
|
+
end users do not have CortexHub accounts. Attest the end user per call with
|
|
246
|
+
`end_user_subject`. Required for `cx.ai` / `cx.llm`.
|
|
247
|
+
- **MCP OAuth client** (`client_id=` / `client_secret=`) - for interactive
|
|
248
|
+
CortexHub users, MCP gateway only.
|
|
249
|
+
|
|
250
|
+
The MCP gateway also accepts MCP OAuth from third-party clients (Claude, Cursor)
|
|
251
|
+
independently of this SDK.
|
|
@@ -31,7 +31,7 @@ from .mcp_key import CortexhubKeyClient, McpKeySession
|
|
|
31
31
|
from .mcp_oauth import CortexhubMcpOAuthClient, McpOAuthSession, McpOAuthToken
|
|
32
32
|
from .session import SessionMcp
|
|
33
33
|
|
|
34
|
-
__version__ = "3.
|
|
34
|
+
__version__ = "3.1.1"
|
|
35
35
|
__all__ = [
|
|
36
36
|
"APIError",
|
|
37
37
|
"AiGateway",
|
|
@@ -112,9 +112,21 @@ class Cortexhub:
|
|
|
112
112
|
last_user_message: str | None = None,
|
|
113
113
|
refresh: bool = False,
|
|
114
114
|
) -> McpKeySession | McpOAuthSession:
|
|
115
|
-
"""Return
|
|
115
|
+
"""Return a session handle for ONE conversation or autonomous run.
|
|
116
116
|
|
|
117
|
-
|
|
117
|
+
The handle carries both planes so everything the run does lands in ONE
|
|
118
|
+
CortexHub session (Session -> Trace -> Span, with cost + user attribution,
|
|
119
|
+
exactly like a co-worker):
|
|
120
|
+
|
|
121
|
+
- ``.mcp`` -- ``.url`` + ``.headers`` for your MCP transport (tools).
|
|
122
|
+
- ``.llm`` -- a ready OpenAI-compatible client scoped to this session
|
|
123
|
+
(key mode; extra ``ai``). Its turns group under the same session.
|
|
124
|
+
- ``.session_id`` -- the id the run groups under (the ``mcp_session_id``).
|
|
125
|
+
|
|
126
|
+
Pass ``mcp_session_id`` = your stable id for the conversation/run and
|
|
127
|
+
``end_user_subject`` = the end user it acts for (``None`` for an
|
|
128
|
+
autonomous run); reuse the same handle across the run's turns so they
|
|
129
|
+
group. ``agent`` is required on every call.
|
|
118
130
|
|
|
119
131
|
**Org API key mode**: pass ``end_user_subject`` to attest
|
|
120
132
|
the end user the call is acting on behalf of. The gateway
|
|
@@ -13,6 +13,7 @@ For applications that sign in CortexHub users interactively, see
|
|
|
13
13
|
from __future__ import annotations
|
|
14
14
|
|
|
15
15
|
from dataclasses import dataclass, field
|
|
16
|
+
from typing import Any
|
|
16
17
|
|
|
17
18
|
from ._config import base_url
|
|
18
19
|
from .session import SessionMcp
|
|
@@ -22,6 +23,13 @@ _AGENT_HEADER = "X-CortexHub-Agent"
|
|
|
22
23
|
_END_USER_SUBJECT_HEADER = "X-CortexHub-End-User-Subject"
|
|
23
24
|
_END_USER_DISPLAY_HINT_HEADER = "X-CortexHub-End-User-Display-Hint"
|
|
24
25
|
|
|
26
|
+
# The LLM router groups a turn into a CortexHub session by these headers -- the
|
|
27
|
+
# same session the MCP tool calls (Mcp-Session-Id) land in -- so one handle's
|
|
28
|
+
# ``.llm`` and ``.mcp`` share one Session -> Trace -> Span with cost + user
|
|
29
|
+
# attribution. The router names them without the ``-Subject`` suffix.
|
|
30
|
+
_ROUTER_SESSION_HEADER = "X-CortexHub-Session-Id"
|
|
31
|
+
_ROUTER_END_USER_HEADER = "X-CortexHub-End-User"
|
|
32
|
+
|
|
25
33
|
_KEY_PREFIX = "cxh_key_"
|
|
26
34
|
|
|
27
35
|
|
|
@@ -53,6 +61,44 @@ class McpKeySession:
|
|
|
53
61
|
headers[_END_USER_DISPLAY_HINT_HEADER] = self.end_user_display_hint
|
|
54
62
|
self.mcp = SessionMcp(url=f"{base_url()}/v1/mcp", headers=headers)
|
|
55
63
|
|
|
64
|
+
@property
|
|
65
|
+
def session_id(self) -> str | None:
|
|
66
|
+
"""The CortexHub session this handle's turns group under.
|
|
67
|
+
|
|
68
|
+
It is the ``mcp_session_id`` you passed - your stable id for the
|
|
69
|
+
conversation OR autonomous run. Log or forward it to correlate; every
|
|
70
|
+
``.llm`` and ``.mcp`` call on this handle lands in this one session.
|
|
71
|
+
"""
|
|
72
|
+
return self.mcp_session_id
|
|
73
|
+
|
|
74
|
+
@property
|
|
75
|
+
def llm(self) -> Any:
|
|
76
|
+
"""A ready OpenAI-compatible client scoped to THIS session (extra: ``ai``).
|
|
77
|
+
|
|
78
|
+
Every call carries the session id + end user, so the LLM turns land in
|
|
79
|
+
the SAME CortexHub session as this handle's tool calls -- one Session ->
|
|
80
|
+
Trace -> Span, with cost and user attribution, exactly like a co-worker
|
|
81
|
+
on CortexHub's own runtime.
|
|
82
|
+
|
|
83
|
+
.. code-block:: python
|
|
84
|
+
|
|
85
|
+
s = cx.session(agent="support-bot",
|
|
86
|
+
mcp_session_id="conv-42", # your conversation id
|
|
87
|
+
end_user_subject="user_42") # who it acts for
|
|
88
|
+
s.llm.chat.completions.create(model="cortexhub/auto", messages=[...])
|
|
89
|
+
# ...and s.mcp for tools -- both in session "conv-42".
|
|
90
|
+
|
|
91
|
+
Requires the ``openai`` package (``pip install 'cortexhub[ai]'``).
|
|
92
|
+
"""
|
|
93
|
+
from .ai import build_ai_gateway
|
|
94
|
+
|
|
95
|
+
headers: dict[str, str] = {}
|
|
96
|
+
if self.mcp_session_id:
|
|
97
|
+
headers[_ROUTER_SESSION_HEADER] = self.mcp_session_id
|
|
98
|
+
if self.end_user_subject:
|
|
99
|
+
headers[_ROUTER_END_USER_HEADER] = self.end_user_subject
|
|
100
|
+
return build_ai_gateway(self.api_key).client(default_headers=headers)
|
|
101
|
+
|
|
56
102
|
|
|
57
103
|
class CortexhubKeyClient:
|
|
58
104
|
"""Send MCP gateway calls authenticated by an org API key."""
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
"""Session types for the MCP gateway connection."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import inspect
|
|
6
|
+
from collections.abc import AsyncIterator
|
|
7
|
+
from contextlib import asynccontextmanager
|
|
8
|
+
from dataclasses import dataclass, field
|
|
9
|
+
from typing import Any
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def _streamable_http_opener() -> Any:
|
|
13
|
+
"""A ``(url, headers) -> transport`` opener over the installed ``mcp`` client.
|
|
14
|
+
|
|
15
|
+
The official ``mcp`` client's streamable-HTTP entry point is not stable across
|
|
16
|
+
releases: 1.x exposes ``streamablehttp_client(url, headers=...)``; 2.x renamed
|
|
17
|
+
it to ``streamable_http_client(url, *, http_client=...)`` (headers must be
|
|
18
|
+
baked into an httpx client) and dropped the old name. This adapts to whichever
|
|
19
|
+
is installed so callers never depend on a specific mcp version.
|
|
20
|
+
"""
|
|
21
|
+
from mcp.client import streamable_http as module
|
|
22
|
+
|
|
23
|
+
legacy = getattr(module, "streamablehttp_client", None)
|
|
24
|
+
if legacy is not None and "headers" in inspect.signature(legacy).parameters:
|
|
25
|
+
|
|
26
|
+
def _open(url: str, headers: dict[str, str]) -> Any:
|
|
27
|
+
return legacy(url, headers=headers)
|
|
28
|
+
|
|
29
|
+
return _open
|
|
30
|
+
|
|
31
|
+
modern = getattr(module, "streamable_http_client", None)
|
|
32
|
+
if modern is not None:
|
|
33
|
+
params = inspect.signature(modern).parameters
|
|
34
|
+
if "headers" in params:
|
|
35
|
+
|
|
36
|
+
def _open(url: str, headers: dict[str, str]) -> Any:
|
|
37
|
+
return modern(url, headers=headers)
|
|
38
|
+
|
|
39
|
+
return _open
|
|
40
|
+
if "http_client" in params:
|
|
41
|
+
from mcp.client.streamable_http import ( # type: ignore[attr-defined]
|
|
42
|
+
create_mcp_http_client,
|
|
43
|
+
)
|
|
44
|
+
|
|
45
|
+
def _open(url: str, headers: dict[str, str]) -> Any:
|
|
46
|
+
return modern(url, http_client=create_mcp_http_client(headers=headers))
|
|
47
|
+
|
|
48
|
+
return _open
|
|
49
|
+
|
|
50
|
+
raise ImportError( # pragma: no cover - defensive across future renames
|
|
51
|
+
"The installed 'mcp' package has no usable streamable-HTTP client entry point. "
|
|
52
|
+
"Install a supported version with: pip install 'cortexhub[mcp]'"
|
|
53
|
+
)
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
@dataclass(frozen=True)
|
|
57
|
+
class SessionMcp:
|
|
58
|
+
"""MCP gateway connection: ``.url`` + ``.headers`` for your MCP transport.
|
|
59
|
+
|
|
60
|
+
Wire these into any MCP client, or use :meth:`open` to open the transport
|
|
61
|
+
directly without touching the mcp client's version-specific entry points.
|
|
62
|
+
"""
|
|
63
|
+
|
|
64
|
+
url: str
|
|
65
|
+
headers: dict[str, str] = field(default_factory=dict)
|
|
66
|
+
|
|
67
|
+
@asynccontextmanager
|
|
68
|
+
async def open(self) -> AsyncIterator[tuple[Any, Any]]:
|
|
69
|
+
"""Open the streamable-HTTP transport, yielding ``(read, write)`` for
|
|
70
|
+
``mcp.ClientSession`` -- across mcp client versions (the entry-point name,
|
|
71
|
+
the ``headers`` vs ``http_client`` argument, and the 2- vs 3-tuple yield
|
|
72
|
+
all differ between mcp 1.x and 2.x). Requires ``cortexhub[mcp]``.
|
|
73
|
+
|
|
74
|
+
.. code-block:: python
|
|
75
|
+
|
|
76
|
+
from mcp import ClientSession
|
|
77
|
+
|
|
78
|
+
async with s.mcp.open() as (read, write):
|
|
79
|
+
async with ClientSession(read, write) as mcp:
|
|
80
|
+
await mcp.initialize()
|
|
81
|
+
tools = await mcp.list_tools()
|
|
82
|
+
"""
|
|
83
|
+
opener = _streamable_http_opener()
|
|
84
|
+
async with opener(self.url, self.headers) as streams:
|
|
85
|
+
# 2.x yields (read, write); older releases add get_session_id.
|
|
86
|
+
yield streams[0], streams[1]
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
__all__ = ["SessionMcp"]
|
cortexhub-3.0.0/PKG-INFO
DELETED
|
@@ -1,137 +0,0 @@
|
|
|
1
|
-
Metadata-Version: 2.5
|
|
2
|
-
Name: cortexhub
|
|
3
|
-
Version: 3.0.0
|
|
4
|
-
Summary: CortexHub platform SDK: point your agent at the governed LLM router + MCP gateway.
|
|
5
|
-
Project-URL: Homepage, https://cortexhub.ai
|
|
6
|
-
Project-URL: Documentation, https://docs.cortexhub.ai
|
|
7
|
-
Author-email: CortexHub <hello@cortexhub.ai>
|
|
8
|
-
License: MIT
|
|
9
|
-
License-File: LICENSE
|
|
10
|
-
Keywords: agents,ai,governance,mcp,programmatic
|
|
11
|
-
Classifier: Development Status :: 5 - Production/Stable
|
|
12
|
-
Classifier: Intended Audience :: Developers
|
|
13
|
-
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
-
Classifier: Programming Language :: Python :: 3
|
|
15
|
-
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
-
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
-
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
-
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
-
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
20
|
-
Requires-Python: >=3.10
|
|
21
|
-
Provides-Extra: ai
|
|
22
|
-
Requires-Dist: openai>=1.40; extra == 'ai'
|
|
23
|
-
Provides-Extra: all
|
|
24
|
-
Requires-Dist: mcp>=1.0; extra == 'all'
|
|
25
|
-
Requires-Dist: openai>=1.40; extra == 'all'
|
|
26
|
-
Provides-Extra: mcp
|
|
27
|
-
Requires-Dist: mcp>=1.0; extra == 'mcp'
|
|
28
|
-
Description-Content-Type: text/markdown
|
|
29
|
-
|
|
30
|
-
# cortexhub
|
|
31
|
-
|
|
32
|
-
The **CortexHub platform SDK**. One API key points your existing agent at two
|
|
33
|
-
governed planes:
|
|
34
|
-
|
|
35
|
-
- the **LLM router** (inference) - OpenAI-compatible, so any framework works,
|
|
36
|
-
with routing, caching, compression, governance, and per-agent metering; and
|
|
37
|
-
- the **MCP gateway** (tools + brain + files) - governed, consent-gated,
|
|
38
|
-
injection-defended.
|
|
39
|
-
|
|
40
|
-
You don't rewrite your agent. You change a base URL and drop in one key.
|
|
41
|
-
|
|
42
|
-
[Documentation](https://docs.cortexhub.ai/docs/sdks/overview)
|
|
43
|
-
|
|
44
|
-
## Install
|
|
45
|
-
|
|
46
|
-
```bash
|
|
47
|
-
pip install cortexhub # zero-dependency core (URLs + headers)
|
|
48
|
-
pip install 'cortexhub[ai]' # + a ready OpenAI-compatible client via cx.llm
|
|
49
|
-
pip install 'cortexhub[mcp]' # + the official MCP client for cx.mcp() sessions
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
## The key
|
|
53
|
-
|
|
54
|
-
Onboard an external AI employee in the CortexHub dashboard, grant it
|
|
55
|
-
capabilities, and mint an API key **bound to that agent** (Settings ->
|
|
56
|
-
API keys, or the agent's page). The `cxh_key_...` *is* that agent's identity -
|
|
57
|
-
every call is attributed, governed, and metered to it. No agent argument needed.
|
|
58
|
-
|
|
59
|
-
```python
|
|
60
|
-
from cortexhub import Cortexhub
|
|
61
|
-
cx = Cortexhub(api_key="cxh_key_...") # or set CORTEXHUB_API_KEY
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
## Inference
|
|
65
|
-
|
|
66
|
-
`cx.ai` gives you everything any OpenAI-compatible client needs; `cx.llm` is a
|
|
67
|
-
ready client (extra: `cortexhub[ai]`). Pick the model with the `model` argument:
|
|
68
|
-
`cortexhub/auto` to let CortexHub route per turn, or any model enabled on the
|
|
69
|
-
platform.
|
|
70
|
-
|
|
71
|
-
```python
|
|
72
|
-
cx.llm.chat.completions.create(model="cortexhub/auto", messages=[{"role": "user", "content": "hi"}])
|
|
73
|
-
cx.llm.responses.create(model="cortexhub/auto", input="hi")
|
|
74
|
-
cx.llm.models.list()
|
|
75
|
-
|
|
76
|
-
cx.ai.base_url # e.g. https://api.cortexhub.ai/v1 (override with CORTEXHUB_ROUTER_URL)
|
|
77
|
-
cx.ai.api_key # your cxh_key_...
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
## Use your existing framework
|
|
81
|
-
|
|
82
|
-
The router speaks the OpenAI wire protocol, so every framework integrates the
|
|
83
|
-
same way: point its OpenAI-compatible provider at `cx.ai.base_url`, pass
|
|
84
|
-
`cx.ai.api_key`, and choose a `model`.
|
|
85
|
-
|
|
86
|
-
```python
|
|
87
|
-
base, key = cx.ai.base_url, cx.ai.api_key
|
|
88
|
-
|
|
89
|
-
# OpenAI SDK / plain
|
|
90
|
-
from openai import OpenAI
|
|
91
|
-
OpenAI(base_url=base, api_key=key).chat.completions.create(model="cortexhub/auto", messages=[...])
|
|
92
|
-
|
|
93
|
-
# LangChain / LangGraph
|
|
94
|
-
from langchain_openai import ChatOpenAI
|
|
95
|
-
ChatOpenAI(base_url=base, api_key=key, model="cortexhub/auto")
|
|
96
|
-
|
|
97
|
-
# CrewAI (LiteLLM under the hood)
|
|
98
|
-
from crewai import LLM
|
|
99
|
-
LLM(model="openai/cortexhub/auto", base_url=base, api_key=key)
|
|
100
|
-
|
|
101
|
-
# AutoGen
|
|
102
|
-
from autogen_ext.models.openai import OpenAIChatCompletionClient
|
|
103
|
-
OpenAIChatCompletionClient(model="cortexhub/auto", base_url=base, api_key=key)
|
|
104
|
-
|
|
105
|
-
# Pydantic AI
|
|
106
|
-
from pydantic_ai.models.openai import OpenAIModel
|
|
107
|
-
from pydantic_ai.providers.openai import OpenAIProvider
|
|
108
|
-
OpenAIModel("cortexhub/auto", provider=OpenAIProvider(base_url=base, api_key=key))
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
**Anthropic SDK:** the router is OpenAI-compatible, not Anthropic-Messages, so
|
|
112
|
-
point the *OpenAI* client at CortexHub with a `claude-*` model (we route to
|
|
113
|
-
Claude) rather than the Anthropic SDK.
|
|
114
|
-
|
|
115
|
-
## Tools, brain, and files (MCP gateway)
|
|
116
|
-
|
|
117
|
-
`cx.mcp(agent=...)` returns the MCP connection your agent's loop drives. Any
|
|
118
|
-
MCP-capable framework can register it as a server; the `cortexhub_*` tools
|
|
119
|
-
(governed toolkit calls, brain recall/learn, files search) then appear
|
|
120
|
-
automatically.
|
|
121
|
-
|
|
122
|
-
```python
|
|
123
|
-
conn = cx.mcp(agent="invoice-bot", end_user_subject="user_42")
|
|
124
|
-
conn.url # https://mcp.cortexhub.ai/v1/mcp
|
|
125
|
-
conn.headers # ready to wire into your MCP transport
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
## Authentication modes
|
|
129
|
-
|
|
130
|
-
- **API key** (`api_key=cxh_key_...`, or `CORTEXHUB_API_KEY`) - backends whose
|
|
131
|
-
end users do not have CortexHub accounts. Attest the end user per call with
|
|
132
|
-
`end_user_subject`. Required for `cx.ai` / `cx.llm`.
|
|
133
|
-
- **MCP OAuth client** (`client_id=` / `client_secret=`) - for interactive
|
|
134
|
-
CortexHub users, MCP gateway only.
|
|
135
|
-
|
|
136
|
-
The MCP gateway also accepts MCP OAuth from third-party clients (Claude, Cursor)
|
|
137
|
-
independently of this SDK.
|
cortexhub-3.0.0/README.md
DELETED
|
@@ -1,108 +0,0 @@
|
|
|
1
|
-
# cortexhub
|
|
2
|
-
|
|
3
|
-
The **CortexHub platform SDK**. One API key points your existing agent at two
|
|
4
|
-
governed planes:
|
|
5
|
-
|
|
6
|
-
- the **LLM router** (inference) - OpenAI-compatible, so any framework works,
|
|
7
|
-
with routing, caching, compression, governance, and per-agent metering; and
|
|
8
|
-
- the **MCP gateway** (tools + brain + files) - governed, consent-gated,
|
|
9
|
-
injection-defended.
|
|
10
|
-
|
|
11
|
-
You don't rewrite your agent. You change a base URL and drop in one key.
|
|
12
|
-
|
|
13
|
-
[Documentation](https://docs.cortexhub.ai/docs/sdks/overview)
|
|
14
|
-
|
|
15
|
-
## Install
|
|
16
|
-
|
|
17
|
-
```bash
|
|
18
|
-
pip install cortexhub # zero-dependency core (URLs + headers)
|
|
19
|
-
pip install 'cortexhub[ai]' # + a ready OpenAI-compatible client via cx.llm
|
|
20
|
-
pip install 'cortexhub[mcp]' # + the official MCP client for cx.mcp() sessions
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
## The key
|
|
24
|
-
|
|
25
|
-
Onboard an external AI employee in the CortexHub dashboard, grant it
|
|
26
|
-
capabilities, and mint an API key **bound to that agent** (Settings ->
|
|
27
|
-
API keys, or the agent's page). The `cxh_key_...` *is* that agent's identity -
|
|
28
|
-
every call is attributed, governed, and metered to it. No agent argument needed.
|
|
29
|
-
|
|
30
|
-
```python
|
|
31
|
-
from cortexhub import Cortexhub
|
|
32
|
-
cx = Cortexhub(api_key="cxh_key_...") # or set CORTEXHUB_API_KEY
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
## Inference
|
|
36
|
-
|
|
37
|
-
`cx.ai` gives you everything any OpenAI-compatible client needs; `cx.llm` is a
|
|
38
|
-
ready client (extra: `cortexhub[ai]`). Pick the model with the `model` argument:
|
|
39
|
-
`cortexhub/auto` to let CortexHub route per turn, or any model enabled on the
|
|
40
|
-
platform.
|
|
41
|
-
|
|
42
|
-
```python
|
|
43
|
-
cx.llm.chat.completions.create(model="cortexhub/auto", messages=[{"role": "user", "content": "hi"}])
|
|
44
|
-
cx.llm.responses.create(model="cortexhub/auto", input="hi")
|
|
45
|
-
cx.llm.models.list()
|
|
46
|
-
|
|
47
|
-
cx.ai.base_url # e.g. https://api.cortexhub.ai/v1 (override with CORTEXHUB_ROUTER_URL)
|
|
48
|
-
cx.ai.api_key # your cxh_key_...
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
## Use your existing framework
|
|
52
|
-
|
|
53
|
-
The router speaks the OpenAI wire protocol, so every framework integrates the
|
|
54
|
-
same way: point its OpenAI-compatible provider at `cx.ai.base_url`, pass
|
|
55
|
-
`cx.ai.api_key`, and choose a `model`.
|
|
56
|
-
|
|
57
|
-
```python
|
|
58
|
-
base, key = cx.ai.base_url, cx.ai.api_key
|
|
59
|
-
|
|
60
|
-
# OpenAI SDK / plain
|
|
61
|
-
from openai import OpenAI
|
|
62
|
-
OpenAI(base_url=base, api_key=key).chat.completions.create(model="cortexhub/auto", messages=[...])
|
|
63
|
-
|
|
64
|
-
# LangChain / LangGraph
|
|
65
|
-
from langchain_openai import ChatOpenAI
|
|
66
|
-
ChatOpenAI(base_url=base, api_key=key, model="cortexhub/auto")
|
|
67
|
-
|
|
68
|
-
# CrewAI (LiteLLM under the hood)
|
|
69
|
-
from crewai import LLM
|
|
70
|
-
LLM(model="openai/cortexhub/auto", base_url=base, api_key=key)
|
|
71
|
-
|
|
72
|
-
# AutoGen
|
|
73
|
-
from autogen_ext.models.openai import OpenAIChatCompletionClient
|
|
74
|
-
OpenAIChatCompletionClient(model="cortexhub/auto", base_url=base, api_key=key)
|
|
75
|
-
|
|
76
|
-
# Pydantic AI
|
|
77
|
-
from pydantic_ai.models.openai import OpenAIModel
|
|
78
|
-
from pydantic_ai.providers.openai import OpenAIProvider
|
|
79
|
-
OpenAIModel("cortexhub/auto", provider=OpenAIProvider(base_url=base, api_key=key))
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
**Anthropic SDK:** the router is OpenAI-compatible, not Anthropic-Messages, so
|
|
83
|
-
point the *OpenAI* client at CortexHub with a `claude-*` model (we route to
|
|
84
|
-
Claude) rather than the Anthropic SDK.
|
|
85
|
-
|
|
86
|
-
## Tools, brain, and files (MCP gateway)
|
|
87
|
-
|
|
88
|
-
`cx.mcp(agent=...)` returns the MCP connection your agent's loop drives. Any
|
|
89
|
-
MCP-capable framework can register it as a server; the `cortexhub_*` tools
|
|
90
|
-
(governed toolkit calls, brain recall/learn, files search) then appear
|
|
91
|
-
automatically.
|
|
92
|
-
|
|
93
|
-
```python
|
|
94
|
-
conn = cx.mcp(agent="invoice-bot", end_user_subject="user_42")
|
|
95
|
-
conn.url # https://mcp.cortexhub.ai/v1/mcp
|
|
96
|
-
conn.headers # ready to wire into your MCP transport
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
## Authentication modes
|
|
100
|
-
|
|
101
|
-
- **API key** (`api_key=cxh_key_...`, or `CORTEXHUB_API_KEY`) - backends whose
|
|
102
|
-
end users do not have CortexHub accounts. Attest the end user per call with
|
|
103
|
-
`end_user_subject`. Required for `cx.ai` / `cx.llm`.
|
|
104
|
-
- **MCP OAuth client** (`client_id=` / `client_secret=`) - for interactive
|
|
105
|
-
CortexHub users, MCP gateway only.
|
|
106
|
-
|
|
107
|
-
The MCP gateway also accepts MCP OAuth from third-party clients (Claude, Cursor)
|
|
108
|
-
independently of this SDK.
|
|
@@ -1,13 +0,0 @@
|
|
|
1
|
-
"""Session types for MCP programmatic OAuth."""
|
|
2
|
-
|
|
3
|
-
from __future__ import annotations
|
|
4
|
-
|
|
5
|
-
from dataclasses import dataclass, field
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
@dataclass(frozen=True)
|
|
9
|
-
class SessionMcp:
|
|
10
|
-
"""MCP streamable-HTTP connection details for your framework."""
|
|
11
|
-
|
|
12
|
-
url: str
|
|
13
|
-
headers: dict[str, str] = field(default_factory=dict)
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|