cortexhub 3.1.1__tar.gz → 3.4.0__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 → cortexhub-3.4.0}/PKG-INFO +118 -40
- {cortexhub-3.1.1 → cortexhub-3.4.0}/README.md +111 -36
- {cortexhub-3.1.1 → cortexhub-3.4.0}/pyproject.toml +14 -4
- {cortexhub-3.1.1 → cortexhub-3.4.0}/src/cortexhub/__init__.py +17 -1
- cortexhub-3.4.0/src/cortexhub/cli.py +44 -0
- {cortexhub-3.1.1 → cortexhub-3.4.0}/src/cortexhub/mcp_key.py +106 -10
- cortexhub-3.4.0/src/cortexhub/verify.py +707 -0
- {cortexhub-3.1.1 → cortexhub-3.4.0}/.gitignore +0 -0
- {cortexhub-3.1.1 → cortexhub-3.4.0}/LICENSE +0 -0
- {cortexhub-3.1.1 → cortexhub-3.4.0}/src/cortexhub/_config.py +0 -0
- {cortexhub-3.1.1 → cortexhub-3.4.0}/src/cortexhub/ai.py +0 -0
- {cortexhub-3.1.1 → cortexhub-3.4.0}/src/cortexhub/client.py +0 -0
- {cortexhub-3.1.1 → cortexhub-3.4.0}/src/cortexhub/errors.py +0 -0
- {cortexhub-3.1.1 → cortexhub-3.4.0}/src/cortexhub/mcp_oauth.py +0 -0
- {cortexhub-3.1.1 → cortexhub-3.4.0}/src/cortexhub/session.py +0 -0
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: cortexhub
|
|
3
|
-
Version: 3.
|
|
3
|
+
Version: 3.4.0
|
|
4
4
|
Summary: CortexHub platform SDK: point your agent at the governed LLM router + MCP gateway.
|
|
5
5
|
Project-URL: Homepage, https://cortexhub.ai
|
|
6
6
|
Project-URL: Documentation, https://docs.cortexhub.ai
|
|
7
7
|
Author-email: CortexHub <hello@cortexhub.ai>
|
|
8
8
|
License: MIT
|
|
9
9
|
License-File: LICENSE
|
|
10
|
-
Keywords: agents,ai,governance,mcp,programmatic
|
|
10
|
+
Keywords: agents,ai,audit,governance,mcp,programmatic,verification
|
|
11
11
|
Classifier: Development Status :: 5 - Production/Stable
|
|
12
12
|
Classifier: Intended Audience :: Developers
|
|
13
13
|
Classifier: License :: OSI Approved :: MIT License
|
|
@@ -21,10 +21,13 @@ Requires-Python: >=3.10
|
|
|
21
21
|
Provides-Extra: ai
|
|
22
22
|
Requires-Dist: openai>=1.40; extra == 'ai'
|
|
23
23
|
Provides-Extra: all
|
|
24
|
-
Requires-Dist:
|
|
24
|
+
Requires-Dist: cryptography>=42; extra == 'all'
|
|
25
|
+
Requires-Dist: mcp<2,>=1.0; extra == 'all'
|
|
25
26
|
Requires-Dist: openai>=1.40; extra == 'all'
|
|
26
27
|
Provides-Extra: mcp
|
|
27
|
-
Requires-Dist: mcp
|
|
28
|
+
Requires-Dist: mcp<2,>=1.0; extra == 'mcp'
|
|
29
|
+
Provides-Extra: verify
|
|
30
|
+
Requires-Dist: cryptography>=42; extra == 'verify'
|
|
28
31
|
Description-Content-Type: text/markdown
|
|
29
32
|
|
|
30
33
|
# cortexhub
|
|
@@ -47,6 +50,7 @@ You don't rewrite your agent. You change a base URL and drop in one key.
|
|
|
47
50
|
pip install cortexhub # zero-dependency core (URLs + headers)
|
|
48
51
|
pip install 'cortexhub[ai]' # + a ready OpenAI-compatible client via cx.llm
|
|
49
52
|
pip install 'cortexhub[mcp]' # + the official MCP client for cx.mcp() sessions
|
|
53
|
+
pip install 'cortexhub[verify]' # + `cortexhub verify`: check receipts and evidence packs offline
|
|
50
54
|
```
|
|
51
55
|
|
|
52
56
|
## The key
|
|
@@ -57,8 +61,12 @@ API keys, or the agent's page). The `cxh_key_...` *is* that agent's identity -
|
|
|
57
61
|
every call is attributed, governed, and metered to it. No agent argument needed.
|
|
58
62
|
|
|
59
63
|
```python
|
|
64
|
+
import cortexhub
|
|
65
|
+
cx = cortexhub.init("cxh_key_...") # or set CORTEXHUB_API_KEY
|
|
66
|
+
|
|
67
|
+
# equivalently:
|
|
60
68
|
from cortexhub import Cortexhub
|
|
61
|
-
cx = Cortexhub(api_key="cxh_key_...")
|
|
69
|
+
cx = Cortexhub(api_key="cxh_key_...")
|
|
62
70
|
```
|
|
63
71
|
|
|
64
72
|
## Run a session (recommended)
|
|
@@ -88,6 +96,7 @@ s.mcp.url # https://mcp.cortexhub.ai/v1/mcp
|
|
|
88
96
|
s.mcp.headers # wire into your MCP transport (see "Tools" below)
|
|
89
97
|
|
|
90
98
|
s.session_id # "conv-42" -- log or forward it to correlate
|
|
99
|
+
s.ai_headers # router headers for your own OpenAI-compatible client (below)
|
|
91
100
|
```
|
|
92
101
|
|
|
93
102
|
Reuse the same handle across the run's turns so they group. An autonomous agent
|
|
@@ -96,49 +105,73 @@ Reuse the same handle across the run's turns so they group. An autonomous agent
|
|
|
96
105
|
|
|
97
106
|
## Inference without a session
|
|
98
107
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
108
|
+
`cx.ai` gives the raw `base_url` + `api_key` any client needs, and `cx.llm` is a
|
|
109
|
+
ready OpenAI-compatible client. The router requires every call to name the end
|
|
110
|
+
user it acts for (`X-CortexHub-End-User-Subject`, else HTTP 400), so in practice
|
|
111
|
+
build the client from a session handle (`s.llm`, or `s.ai_headers` below).
|
|
103
112
|
|
|
104
113
|
```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
114
|
cx.ai.base_url # e.g. https://api.cortexhub.ai/v1 (override with CORTEXHUB_ROUTER_URL)
|
|
110
115
|
cx.ai.api_key # your cxh_key_...
|
|
116
|
+
cx.llm.models.list()
|
|
111
117
|
```
|
|
112
118
|
|
|
113
119
|
## Use your existing framework
|
|
114
120
|
|
|
115
121
|
The router speaks the OpenAI wire protocol, so every framework integrates the
|
|
116
122
|
same way: point its OpenAI-compatible provider at `cx.ai.base_url`, pass
|
|
117
|
-
`cx.ai.api_key`,
|
|
123
|
+
`cx.ai.api_key`, choose a `model`, and send the session handle's **`ai_headers`**
|
|
124
|
+
as the client's default headers. They tell the router which run the call
|
|
125
|
+
belongs to and which end user it acts for (`X-CortexHub-End-User-Subject`,
|
|
126
|
+
`X-CortexHub-Session-Id`), so the framework's model calls land in the same
|
|
127
|
+
CortexHub session as the handle's tool calls.
|
|
118
128
|
|
|
119
129
|
```python
|
|
120
|
-
|
|
130
|
+
s = cx.session(agent="support-bot", mcp_session_id="conv-42", end_user_subject="user_42")
|
|
131
|
+
base, key, headers = cx.ai.base_url, cx.ai.api_key, s.ai_headers
|
|
121
132
|
|
|
122
133
|
# OpenAI SDK / plain
|
|
123
134
|
from openai import OpenAI
|
|
124
|
-
OpenAI(base_url=base, api_key=key
|
|
135
|
+
OpenAI(base_url=base, api_key=key, default_headers=headers)
|
|
125
136
|
|
|
126
137
|
# LangChain / LangGraph
|
|
127
138
|
from langchain_openai import ChatOpenAI
|
|
128
|
-
ChatOpenAI(base_url=base, api_key=key, model="cortexhub/auto")
|
|
139
|
+
ChatOpenAI(base_url=base, api_key=key, model="cortexhub/auto", default_headers=headers)
|
|
129
140
|
|
|
130
141
|
# CrewAI (LiteLLM under the hood)
|
|
131
142
|
from crewai import LLM
|
|
132
|
-
LLM(model="openai/cortexhub/auto", base_url=base, api_key=key)
|
|
143
|
+
LLM(model="openai/cortexhub/auto", base_url=base, api_key=key, extra_headers=headers)
|
|
133
144
|
|
|
134
145
|
# AutoGen
|
|
135
146
|
from autogen_ext.models.openai import OpenAIChatCompletionClient
|
|
136
|
-
OpenAIChatCompletionClient(model="cortexhub/auto", base_url=base, api_key=key
|
|
147
|
+
OpenAIChatCompletionClient(model="cortexhub/auto", base_url=base, api_key=key,
|
|
148
|
+
default_headers=headers)
|
|
137
149
|
|
|
138
150
|
# Pydantic AI
|
|
151
|
+
from openai import AsyncOpenAI
|
|
139
152
|
from pydantic_ai.models.openai import OpenAIModel
|
|
140
153
|
from pydantic_ai.providers.openai import OpenAIProvider
|
|
141
|
-
OpenAIModel("cortexhub/auto", provider=OpenAIProvider(
|
|
154
|
+
OpenAIModel("cortexhub/auto", provider=OpenAIProvider(
|
|
155
|
+
openai_client=AsyncOpenAI(base_url=base, api_key=key, default_headers=headers)))
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
A LangGraph agent with CortexHub's model AND its governed tools (the MCP
|
|
159
|
+
connection through `langchain-mcp-adapters`), in one session:
|
|
160
|
+
|
|
161
|
+
```python
|
|
162
|
+
from langchain_mcp_adapters.tools import load_mcp_tools
|
|
163
|
+
from langchain_openai import ChatOpenAI
|
|
164
|
+
from langgraph.prebuilt import create_react_agent
|
|
165
|
+
from mcp import ClientSession
|
|
166
|
+
|
|
167
|
+
run = cx.session(agent="lead-assistant", end_user_subject="northwind-ops",
|
|
168
|
+
mcp_session_id="lead-assistant-run-1")
|
|
169
|
+
llm = ChatOpenAI(model="cortexhub/auto", base_url=cx.ai.base_url,
|
|
170
|
+
api_key=cx.ai.api_key, default_headers=run.ai_headers)
|
|
171
|
+
async with run.mcp.open() as (read, write), ClientSession(read, write) as mcp:
|
|
172
|
+
await mcp.initialize()
|
|
173
|
+
agent = create_react_agent(llm, await load_mcp_tools(mcp))
|
|
174
|
+
state = await agent.ainvoke({"messages": [("user", "...")]})
|
|
142
175
|
```
|
|
143
176
|
|
|
144
177
|
**Anthropic SDK:** the router is OpenAI-compatible, not Anthropic-Messages, so
|
|
@@ -149,8 +182,10 @@ Claude) rather than the Anthropic SDK.
|
|
|
149
182
|
|
|
150
183
|
`s.mcp` (the session handle above) is the MCP connection your agent's loop
|
|
151
184
|
drives. Any MCP-capable framework registers it as a server; the `cortexhub_*`
|
|
152
|
-
tools (
|
|
153
|
-
|
|
185
|
+
meta-tools (search, schemas, invoke) and the built-in toolkits the agent's group
|
|
186
|
+
is granted (`brain_recall`, `brain_learn`, `files_search`, `skills_find`, ...)
|
|
187
|
+
then appear automatically -- and, on the session handle, group with that run's
|
|
188
|
+
LLM turns.
|
|
154
189
|
|
|
155
190
|
```python
|
|
156
191
|
conn = s.mcp # from cx.session(...) -> same session as .llm
|
|
@@ -165,18 +200,26 @@ need tools (no session grouping).
|
|
|
165
200
|
|
|
166
201
|
One session, end to end: the model reasons with `s.llm`, acts through the
|
|
167
202
|
governed `cortexhub_*` tools on `s.mcp`, and when a governed action needs the end
|
|
168
|
-
user's **approval** it comes back parked
|
|
169
|
-
|
|
170
|
-
`pip install 'cortexhub[ai,mcp]'`.
|
|
171
|
-
|
|
172
|
-
> **How consent reaches your user.**
|
|
173
|
-
>
|
|
174
|
-
>
|
|
175
|
-
>
|
|
176
|
-
>
|
|
177
|
-
>
|
|
178
|
-
>
|
|
179
|
-
>
|
|
203
|
+
user's **approval** it comes back parked, carrying an `approval_id` and the
|
|
204
|
+
`presentation` (headline / sections / summary) of what will happen. Needs both
|
|
205
|
+
extras: `pip install 'cortexhub[ai,mcp]'`.
|
|
206
|
+
|
|
207
|
+
> **How consent reaches your user.** Your agent is headless, so *you* own the
|
|
208
|
+
> consent UI. When a call parks, read the `approval_id` + `presentation` from the
|
|
209
|
+
> result, show it to your end user however your app does UI, and when they decide
|
|
210
|
+
> submit it through the SDK:
|
|
211
|
+
>
|
|
212
|
+
> ```python
|
|
213
|
+
> s.decide(approval_id, "approve", note="ok by me") # or "deny"
|
|
214
|
+
> ```
|
|
215
|
+
>
|
|
216
|
+
> `s.decide` records the decision as *that end user's* consent -- no CortexHub
|
|
217
|
+
> account for the end user is required -- bound to the same agent + `end_user_subject`
|
|
218
|
+
> this session runs as. Then poll `cortexhub_get_task` (below): an approved call
|
|
219
|
+
> runs server-side and its result comes back. If you'd rather not build any UI,
|
|
220
|
+
> the parked result also carries a signed **`consent_url`** you can hand the user
|
|
221
|
+
> to approve in a browser instead. (A UI host that declares the MCP-UI extension,
|
|
222
|
+
> e.g. claude.ai, gets consent rendered inline and never reaches this path.)
|
|
180
223
|
|
|
181
224
|
```python
|
|
182
225
|
import asyncio, json
|
|
@@ -218,8 +261,10 @@ async def run_turn(user_text: str) -> str:
|
|
|
218
261
|
|
|
219
262
|
task = _parked_task(result) # governed action -> needs approval?
|
|
220
263
|
if task:
|
|
221
|
-
|
|
222
|
-
|
|
264
|
+
# Show task["presentation"] in YOUR UI and get the user's
|
|
265
|
+
# decision. Here we auto-approve to keep the example runnable.
|
|
266
|
+
s.decide(task["approval_id"], "approve", note="demo auto-approve")
|
|
267
|
+
text = await _await_decision(mcp, task["task_id"]) # resume + read result
|
|
223
268
|
|
|
224
269
|
messages.append({"role": "tool", "tool_call_id": call.id, "content": text})
|
|
225
270
|
return ""
|
|
@@ -238,11 +283,15 @@ def _payload(result):
|
|
|
238
283
|
return {}
|
|
239
284
|
|
|
240
285
|
def _parked_task(result):
|
|
241
|
-
# A parked approval comes back as an `mcp_task` carrying
|
|
286
|
+
# A parked approval comes back as an `mcp_task` carrying an approval_id (and a
|
|
287
|
+
# signed consent_url fallback). The presentation you passed to the tool call
|
|
288
|
+
# rides alongside it, so you can render your own consent UI.
|
|
242
289
|
def walk(node):
|
|
243
290
|
if isinstance(node, dict):
|
|
244
291
|
t = node.get("mcp_task")
|
|
245
|
-
if isinstance(t, dict) and t.get("
|
|
292
|
+
if isinstance(t, dict) and t.get("approval_id"):
|
|
293
|
+
if "presentation" in node and "presentation" not in t:
|
|
294
|
+
t = {**t, "presentation": node["presentation"]}
|
|
246
295
|
return t
|
|
247
296
|
for v in node.values():
|
|
248
297
|
if (found := walk(v)):
|
|
@@ -257,9 +306,14 @@ def _parked_task(result):
|
|
|
257
306
|
async def _await_decision(mcp, task_id: str) -> str:
|
|
258
307
|
# Poll until the human decides in CortexHub; an approval runs the action.
|
|
259
308
|
for _ in range(600): # ~10 min at 1s waits
|
|
260
|
-
res = await mcp.call_tool("cortexhub_get_task", {"task_id": task_id, "
|
|
261
|
-
|
|
309
|
+
res = await mcp.call_tool("cortexhub_get_task", {"task_id": task_id, "wait_seconds": 1})
|
|
310
|
+
# structuredContent is {"ok", "status", "meta_tool", "result": {...}}.
|
|
311
|
+
task = _payload(res).get("result") or {}
|
|
312
|
+
if task.get("terminal"):
|
|
262
313
|
return _text(res)
|
|
314
|
+
# While it waits, task["approval"]["routed_to"] names who approves it
|
|
315
|
+
# (e.g. ["Priya Shah"]), the same on the held invoke result's
|
|
316
|
+
# details.approval.
|
|
263
317
|
return "approval timed out"
|
|
264
318
|
|
|
265
319
|
print(asyncio.run(run_turn("Email the Q3 report to the finance team")))
|
|
@@ -278,3 +332,27 @@ the model step, each tool call, and the approval as a single trace.
|
|
|
278
332
|
|
|
279
333
|
The MCP gateway also accepts MCP OAuth from third-party clients (Claude, Cursor)
|
|
280
334
|
independently of this SDK.
|
|
335
|
+
|
|
336
|
+
## Verify receipts and evidence packs without CortexHub
|
|
337
|
+
|
|
338
|
+
CortexHub signs every authorization record, receipt and enforcement decision
|
|
339
|
+
with the agent's Ed25519 key, and every evidence pack with a platform key. The
|
|
340
|
+
public keys are published at `https://api.cortexhub.ai/.well-known/cortexhub-signing-keys.json`
|
|
341
|
+
(platform) and `.../cortexhub-signing-keys/agents/<agent_id>.json` (per agent).
|
|
342
|
+
`cortexhub verify` checks a downloaded file against them; it never calls a
|
|
343
|
+
CortexHub API.
|
|
344
|
+
|
|
345
|
+
```bash
|
|
346
|
+
pip install 'cortexhub[verify]'
|
|
347
|
+
cortexhub verify receipt.json # a downloaded receipt or authorization record
|
|
348
|
+
cortexhub verify evidence-pack.zip # signed manifest, every file, every record, every chain
|
|
349
|
+
cortexhub verify evidence-pack.zip --pack-record pack.json # also the whole-archive signature
|
|
350
|
+
|
|
351
|
+
# air-gapped: save the key sets once, then
|
|
352
|
+
cortexhub verify evidence-pack.zip --offline --keys cortexhub-signing-keys.json
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
Exit code 0 means verified, 1 a check failed, 2 the file could not be read. The
|
|
356
|
+
verifier is one file (`src/cortexhub/verify.py`, standard library plus
|
|
357
|
+
`cryptography`) that also runs on its own: `python verify.py <file>`.
|
|
358
|
+
[How to verify](https://docs.cortexhub.ai/docs/architecture/verify-offline)
|
|
@@ -18,6 +18,7 @@ You don't rewrite your agent. You change a base URL and drop in one key.
|
|
|
18
18
|
pip install cortexhub # zero-dependency core (URLs + headers)
|
|
19
19
|
pip install 'cortexhub[ai]' # + a ready OpenAI-compatible client via cx.llm
|
|
20
20
|
pip install 'cortexhub[mcp]' # + the official MCP client for cx.mcp() sessions
|
|
21
|
+
pip install 'cortexhub[verify]' # + `cortexhub verify`: check receipts and evidence packs offline
|
|
21
22
|
```
|
|
22
23
|
|
|
23
24
|
## The key
|
|
@@ -28,8 +29,12 @@ API keys, or the agent's page). The `cxh_key_...` *is* that agent's identity -
|
|
|
28
29
|
every call is attributed, governed, and metered to it. No agent argument needed.
|
|
29
30
|
|
|
30
31
|
```python
|
|
32
|
+
import cortexhub
|
|
33
|
+
cx = cortexhub.init("cxh_key_...") # or set CORTEXHUB_API_KEY
|
|
34
|
+
|
|
35
|
+
# equivalently:
|
|
31
36
|
from cortexhub import Cortexhub
|
|
32
|
-
cx = Cortexhub(api_key="cxh_key_...")
|
|
37
|
+
cx = Cortexhub(api_key="cxh_key_...")
|
|
33
38
|
```
|
|
34
39
|
|
|
35
40
|
## Run a session (recommended)
|
|
@@ -59,6 +64,7 @@ s.mcp.url # https://mcp.cortexhub.ai/v1/mcp
|
|
|
59
64
|
s.mcp.headers # wire into your MCP transport (see "Tools" below)
|
|
60
65
|
|
|
61
66
|
s.session_id # "conv-42" -- log or forward it to correlate
|
|
67
|
+
s.ai_headers # router headers for your own OpenAI-compatible client (below)
|
|
62
68
|
```
|
|
63
69
|
|
|
64
70
|
Reuse the same handle across the run's turns so they group. An autonomous agent
|
|
@@ -67,49 +73,73 @@ Reuse the same handle across the run's turns so they group. An autonomous agent
|
|
|
67
73
|
|
|
68
74
|
## Inference without a session
|
|
69
75
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
76
|
+
`cx.ai` gives the raw `base_url` + `api_key` any client needs, and `cx.llm` is a
|
|
77
|
+
ready OpenAI-compatible client. The router requires every call to name the end
|
|
78
|
+
user it acts for (`X-CortexHub-End-User-Subject`, else HTTP 400), so in practice
|
|
79
|
+
build the client from a session handle (`s.llm`, or `s.ai_headers` below).
|
|
74
80
|
|
|
75
81
|
```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
82
|
cx.ai.base_url # e.g. https://api.cortexhub.ai/v1 (override with CORTEXHUB_ROUTER_URL)
|
|
81
83
|
cx.ai.api_key # your cxh_key_...
|
|
84
|
+
cx.llm.models.list()
|
|
82
85
|
```
|
|
83
86
|
|
|
84
87
|
## Use your existing framework
|
|
85
88
|
|
|
86
89
|
The router speaks the OpenAI wire protocol, so every framework integrates the
|
|
87
90
|
same way: point its OpenAI-compatible provider at `cx.ai.base_url`, pass
|
|
88
|
-
`cx.ai.api_key`,
|
|
91
|
+
`cx.ai.api_key`, choose a `model`, and send the session handle's **`ai_headers`**
|
|
92
|
+
as the client's default headers. They tell the router which run the call
|
|
93
|
+
belongs to and which end user it acts for (`X-CortexHub-End-User-Subject`,
|
|
94
|
+
`X-CortexHub-Session-Id`), so the framework's model calls land in the same
|
|
95
|
+
CortexHub session as the handle's tool calls.
|
|
89
96
|
|
|
90
97
|
```python
|
|
91
|
-
|
|
98
|
+
s = cx.session(agent="support-bot", mcp_session_id="conv-42", end_user_subject="user_42")
|
|
99
|
+
base, key, headers = cx.ai.base_url, cx.ai.api_key, s.ai_headers
|
|
92
100
|
|
|
93
101
|
# OpenAI SDK / plain
|
|
94
102
|
from openai import OpenAI
|
|
95
|
-
OpenAI(base_url=base, api_key=key
|
|
103
|
+
OpenAI(base_url=base, api_key=key, default_headers=headers)
|
|
96
104
|
|
|
97
105
|
# LangChain / LangGraph
|
|
98
106
|
from langchain_openai import ChatOpenAI
|
|
99
|
-
ChatOpenAI(base_url=base, api_key=key, model="cortexhub/auto")
|
|
107
|
+
ChatOpenAI(base_url=base, api_key=key, model="cortexhub/auto", default_headers=headers)
|
|
100
108
|
|
|
101
109
|
# CrewAI (LiteLLM under the hood)
|
|
102
110
|
from crewai import LLM
|
|
103
|
-
LLM(model="openai/cortexhub/auto", base_url=base, api_key=key)
|
|
111
|
+
LLM(model="openai/cortexhub/auto", base_url=base, api_key=key, extra_headers=headers)
|
|
104
112
|
|
|
105
113
|
# AutoGen
|
|
106
114
|
from autogen_ext.models.openai import OpenAIChatCompletionClient
|
|
107
|
-
OpenAIChatCompletionClient(model="cortexhub/auto", base_url=base, api_key=key
|
|
115
|
+
OpenAIChatCompletionClient(model="cortexhub/auto", base_url=base, api_key=key,
|
|
116
|
+
default_headers=headers)
|
|
108
117
|
|
|
109
118
|
# Pydantic AI
|
|
119
|
+
from openai import AsyncOpenAI
|
|
110
120
|
from pydantic_ai.models.openai import OpenAIModel
|
|
111
121
|
from pydantic_ai.providers.openai import OpenAIProvider
|
|
112
|
-
OpenAIModel("cortexhub/auto", provider=OpenAIProvider(
|
|
122
|
+
OpenAIModel("cortexhub/auto", provider=OpenAIProvider(
|
|
123
|
+
openai_client=AsyncOpenAI(base_url=base, api_key=key, default_headers=headers)))
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
A LangGraph agent with CortexHub's model AND its governed tools (the MCP
|
|
127
|
+
connection through `langchain-mcp-adapters`), in one session:
|
|
128
|
+
|
|
129
|
+
```python
|
|
130
|
+
from langchain_mcp_adapters.tools import load_mcp_tools
|
|
131
|
+
from langchain_openai import ChatOpenAI
|
|
132
|
+
from langgraph.prebuilt import create_react_agent
|
|
133
|
+
from mcp import ClientSession
|
|
134
|
+
|
|
135
|
+
run = cx.session(agent="lead-assistant", end_user_subject="northwind-ops",
|
|
136
|
+
mcp_session_id="lead-assistant-run-1")
|
|
137
|
+
llm = ChatOpenAI(model="cortexhub/auto", base_url=cx.ai.base_url,
|
|
138
|
+
api_key=cx.ai.api_key, default_headers=run.ai_headers)
|
|
139
|
+
async with run.mcp.open() as (read, write), ClientSession(read, write) as mcp:
|
|
140
|
+
await mcp.initialize()
|
|
141
|
+
agent = create_react_agent(llm, await load_mcp_tools(mcp))
|
|
142
|
+
state = await agent.ainvoke({"messages": [("user", "...")]})
|
|
113
143
|
```
|
|
114
144
|
|
|
115
145
|
**Anthropic SDK:** the router is OpenAI-compatible, not Anthropic-Messages, so
|
|
@@ -120,8 +150,10 @@ Claude) rather than the Anthropic SDK.
|
|
|
120
150
|
|
|
121
151
|
`s.mcp` (the session handle above) is the MCP connection your agent's loop
|
|
122
152
|
drives. Any MCP-capable framework registers it as a server; the `cortexhub_*`
|
|
123
|
-
tools (
|
|
124
|
-
|
|
153
|
+
meta-tools (search, schemas, invoke) and the built-in toolkits the agent's group
|
|
154
|
+
is granted (`brain_recall`, `brain_learn`, `files_search`, `skills_find`, ...)
|
|
155
|
+
then appear automatically -- and, on the session handle, group with that run's
|
|
156
|
+
LLM turns.
|
|
125
157
|
|
|
126
158
|
```python
|
|
127
159
|
conn = s.mcp # from cx.session(...) -> same session as .llm
|
|
@@ -136,18 +168,26 @@ need tools (no session grouping).
|
|
|
136
168
|
|
|
137
169
|
One session, end to end: the model reasons with `s.llm`, acts through the
|
|
138
170
|
governed `cortexhub_*` tools on `s.mcp`, and when a governed action needs the end
|
|
139
|
-
user's **approval** it comes back parked
|
|
140
|
-
|
|
141
|
-
`pip install 'cortexhub[ai,mcp]'`.
|
|
142
|
-
|
|
143
|
-
> **How consent reaches your user.**
|
|
144
|
-
>
|
|
145
|
-
>
|
|
146
|
-
>
|
|
147
|
-
>
|
|
148
|
-
>
|
|
149
|
-
>
|
|
150
|
-
>
|
|
171
|
+
user's **approval** it comes back parked, carrying an `approval_id` and the
|
|
172
|
+
`presentation` (headline / sections / summary) of what will happen. Needs both
|
|
173
|
+
extras: `pip install 'cortexhub[ai,mcp]'`.
|
|
174
|
+
|
|
175
|
+
> **How consent reaches your user.** Your agent is headless, so *you* own the
|
|
176
|
+
> consent UI. When a call parks, read the `approval_id` + `presentation` from the
|
|
177
|
+
> result, show it to your end user however your app does UI, and when they decide
|
|
178
|
+
> submit it through the SDK:
|
|
179
|
+
>
|
|
180
|
+
> ```python
|
|
181
|
+
> s.decide(approval_id, "approve", note="ok by me") # or "deny"
|
|
182
|
+
> ```
|
|
183
|
+
>
|
|
184
|
+
> `s.decide` records the decision as *that end user's* consent -- no CortexHub
|
|
185
|
+
> account for the end user is required -- bound to the same agent + `end_user_subject`
|
|
186
|
+
> this session runs as. Then poll `cortexhub_get_task` (below): an approved call
|
|
187
|
+
> runs server-side and its result comes back. If you'd rather not build any UI,
|
|
188
|
+
> the parked result also carries a signed **`consent_url`** you can hand the user
|
|
189
|
+
> to approve in a browser instead. (A UI host that declares the MCP-UI extension,
|
|
190
|
+
> e.g. claude.ai, gets consent rendered inline and never reaches this path.)
|
|
151
191
|
|
|
152
192
|
```python
|
|
153
193
|
import asyncio, json
|
|
@@ -189,8 +229,10 @@ async def run_turn(user_text: str) -> str:
|
|
|
189
229
|
|
|
190
230
|
task = _parked_task(result) # governed action -> needs approval?
|
|
191
231
|
if task:
|
|
192
|
-
|
|
193
|
-
|
|
232
|
+
# Show task["presentation"] in YOUR UI and get the user's
|
|
233
|
+
# decision. Here we auto-approve to keep the example runnable.
|
|
234
|
+
s.decide(task["approval_id"], "approve", note="demo auto-approve")
|
|
235
|
+
text = await _await_decision(mcp, task["task_id"]) # resume + read result
|
|
194
236
|
|
|
195
237
|
messages.append({"role": "tool", "tool_call_id": call.id, "content": text})
|
|
196
238
|
return ""
|
|
@@ -209,11 +251,15 @@ def _payload(result):
|
|
|
209
251
|
return {}
|
|
210
252
|
|
|
211
253
|
def _parked_task(result):
|
|
212
|
-
# A parked approval comes back as an `mcp_task` carrying
|
|
254
|
+
# A parked approval comes back as an `mcp_task` carrying an approval_id (and a
|
|
255
|
+
# signed consent_url fallback). The presentation you passed to the tool call
|
|
256
|
+
# rides alongside it, so you can render your own consent UI.
|
|
213
257
|
def walk(node):
|
|
214
258
|
if isinstance(node, dict):
|
|
215
259
|
t = node.get("mcp_task")
|
|
216
|
-
if isinstance(t, dict) and t.get("
|
|
260
|
+
if isinstance(t, dict) and t.get("approval_id"):
|
|
261
|
+
if "presentation" in node and "presentation" not in t:
|
|
262
|
+
t = {**t, "presentation": node["presentation"]}
|
|
217
263
|
return t
|
|
218
264
|
for v in node.values():
|
|
219
265
|
if (found := walk(v)):
|
|
@@ -228,9 +274,14 @@ def _parked_task(result):
|
|
|
228
274
|
async def _await_decision(mcp, task_id: str) -> str:
|
|
229
275
|
# Poll until the human decides in CortexHub; an approval runs the action.
|
|
230
276
|
for _ in range(600): # ~10 min at 1s waits
|
|
231
|
-
res = await mcp.call_tool("cortexhub_get_task", {"task_id": task_id, "
|
|
232
|
-
|
|
277
|
+
res = await mcp.call_tool("cortexhub_get_task", {"task_id": task_id, "wait_seconds": 1})
|
|
278
|
+
# structuredContent is {"ok", "status", "meta_tool", "result": {...}}.
|
|
279
|
+
task = _payload(res).get("result") or {}
|
|
280
|
+
if task.get("terminal"):
|
|
233
281
|
return _text(res)
|
|
282
|
+
# While it waits, task["approval"]["routed_to"] names who approves it
|
|
283
|
+
# (e.g. ["Priya Shah"]), the same on the held invoke result's
|
|
284
|
+
# details.approval.
|
|
234
285
|
return "approval timed out"
|
|
235
286
|
|
|
236
287
|
print(asyncio.run(run_turn("Email the Q3 report to the finance team")))
|
|
@@ -249,3 +300,27 @@ the model step, each tool call, and the approval as a single trace.
|
|
|
249
300
|
|
|
250
301
|
The MCP gateway also accepts MCP OAuth from third-party clients (Claude, Cursor)
|
|
251
302
|
independently of this SDK.
|
|
303
|
+
|
|
304
|
+
## Verify receipts and evidence packs without CortexHub
|
|
305
|
+
|
|
306
|
+
CortexHub signs every authorization record, receipt and enforcement decision
|
|
307
|
+
with the agent's Ed25519 key, and every evidence pack with a platform key. The
|
|
308
|
+
public keys are published at `https://api.cortexhub.ai/.well-known/cortexhub-signing-keys.json`
|
|
309
|
+
(platform) and `.../cortexhub-signing-keys/agents/<agent_id>.json` (per agent).
|
|
310
|
+
`cortexhub verify` checks a downloaded file against them; it never calls a
|
|
311
|
+
CortexHub API.
|
|
312
|
+
|
|
313
|
+
```bash
|
|
314
|
+
pip install 'cortexhub[verify]'
|
|
315
|
+
cortexhub verify receipt.json # a downloaded receipt or authorization record
|
|
316
|
+
cortexhub verify evidence-pack.zip # signed manifest, every file, every record, every chain
|
|
317
|
+
cortexhub verify evidence-pack.zip --pack-record pack.json # also the whole-archive signature
|
|
318
|
+
|
|
319
|
+
# air-gapped: save the key sets once, then
|
|
320
|
+
cortexhub verify evidence-pack.zip --offline --keys cortexhub-signing-keys.json
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
Exit code 0 means verified, 1 a check failed, 2 the file could not be read. The
|
|
324
|
+
verifier is one file (`src/cortexhub/verify.py`, standard library plus
|
|
325
|
+
`cryptography`) that also runs on its own: `python verify.py <file>`.
|
|
326
|
+
[How to verify](https://docs.cortexhub.ai/docs/architecture/verify-offline)
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "cortexhub"
|
|
3
|
-
version = "3.
|
|
3
|
+
version = "3.4.0"
|
|
4
4
|
description = "CortexHub platform SDK: point your agent at the governed LLM router + MCP gateway."
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
requires-python = ">=3.10"
|
|
@@ -8,7 +8,7 @@ license = { text = "MIT" }
|
|
|
8
8
|
authors = [
|
|
9
9
|
{ name = "CortexHub", email = "hello@cortexhub.ai" }
|
|
10
10
|
]
|
|
11
|
-
keywords = ["ai", "agents", "mcp" , "programmatic", "governance"]
|
|
11
|
+
keywords = ["ai", "agents", "mcp" , "programmatic", "governance", "audit", "verification"]
|
|
12
12
|
classifiers = [
|
|
13
13
|
"Development Status :: 5 - Production/Stable",
|
|
14
14
|
"Intended Audience :: Developers",
|
|
@@ -33,8 +33,17 @@ dependencies = []
|
|
|
33
33
|
# pip install 'cortexhub[mcp]' -> the official MCP client for cx.mcp() sessions
|
|
34
34
|
[project.optional-dependencies]
|
|
35
35
|
ai = ["openai>=1.40"]
|
|
36
|
-
|
|
37
|
-
|
|
36
|
+
# The CortexHub MCP gateway serves the 1.x Streamable-HTTP transport; the 2.x
|
|
37
|
+
# client's initialize handshake 404s on it. Cap to the gateway's major until it
|
|
38
|
+
# moves to 2.x, so `pip install cortexhub[mcp]` resolves a compatible client.
|
|
39
|
+
mcp = ["mcp>=1.0,<2"]
|
|
40
|
+
# `cortexhub verify`: check CortexHub receipts, authorization records and
|
|
41
|
+
# evidence packs offline (Ed25519 via the cryptography package).
|
|
42
|
+
verify = ["cryptography>=42"]
|
|
43
|
+
all = ["openai>=1.40", "mcp>=1.0,<2", "cryptography>=42"]
|
|
44
|
+
|
|
45
|
+
[project.scripts]
|
|
46
|
+
cortexhub = "cortexhub.cli:main"
|
|
38
47
|
|
|
39
48
|
[project.urls]
|
|
40
49
|
Homepage = "https://cortexhub.ai"
|
|
@@ -86,6 +95,7 @@ python-preference = "only-managed"
|
|
|
86
95
|
|
|
87
96
|
[dependency-groups]
|
|
88
97
|
dev = [
|
|
98
|
+
"cryptography==50.0.2",
|
|
89
99
|
"pytest==9.0.3",
|
|
90
100
|
"ruff==0.14.11",
|
|
91
101
|
"mypy==1.19.1",
|
|
@@ -31,7 +31,22 @@ 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.4.0"
|
|
35
|
+
def init(api_key: str | None = None, **kwargs: object) -> Cortexhub:
|
|
36
|
+
"""Create a CortexHub client. Alias for :class:`Cortexhub`.
|
|
37
|
+
|
|
38
|
+
.. code-block:: python
|
|
39
|
+
|
|
40
|
+
import cortexhub
|
|
41
|
+
cx = cortexhub.init("cxh_key_...")
|
|
42
|
+
s = cx.session(agent="support-bot", end_user_subject="user_42")
|
|
43
|
+
s.llm.chat.completions.create(...) # governed LLM router
|
|
44
|
+
s.mcp # governed MCP tool gateway
|
|
45
|
+
s.decide(approval_id, "approve") # end-user consent, no identity
|
|
46
|
+
"""
|
|
47
|
+
return Cortexhub(api_key=api_key, **kwargs) # type: ignore[arg-type]
|
|
48
|
+
|
|
49
|
+
|
|
35
50
|
__all__ = [
|
|
36
51
|
"APIError",
|
|
37
52
|
"AiGateway",
|
|
@@ -46,4 +61,5 @@ __all__ = [
|
|
|
46
61
|
"McpOAuthToken",
|
|
47
62
|
"SessionMcp",
|
|
48
63
|
"__version__",
|
|
64
|
+
"init",
|
|
49
65
|
]
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
"""``cortexhub`` command line.
|
|
2
|
+
|
|
3
|
+
Subcommands:
|
|
4
|
+
|
|
5
|
+
* ``cortexhub verify <file>``: verify a CortexHub receipt, authorization record
|
|
6
|
+
or evidence pack without CortexHub (see :mod:`cortexhub.verify`).
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import sys
|
|
12
|
+
|
|
13
|
+
from . import __version__
|
|
14
|
+
|
|
15
|
+
_USAGE = (
|
|
16
|
+
"usage: cortexhub <command> [options]\n"
|
|
17
|
+
"\n"
|
|
18
|
+
"commands:\n"
|
|
19
|
+
" verify verify a CortexHub receipt, authorization record or evidence pack offline\n"
|
|
20
|
+
"\n"
|
|
21
|
+
"Run 'cortexhub <command> --help' for a command's options."
|
|
22
|
+
)
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def main(argv: list[str] | None = None) -> int:
|
|
26
|
+
"""Entry point of the ``cortexhub`` console script."""
|
|
27
|
+
args = list(sys.argv[1:] if argv is None else argv)
|
|
28
|
+
if not args or args[0] in ("-h", "--help"):
|
|
29
|
+
print(_USAGE)
|
|
30
|
+
return 0 if args else 2
|
|
31
|
+
if args[0] == "--version":
|
|
32
|
+
print(f"cortexhub {__version__}")
|
|
33
|
+
return 0
|
|
34
|
+
command, rest = args[0], args[1:]
|
|
35
|
+
if command == "verify":
|
|
36
|
+
from .verify import main as verify_main
|
|
37
|
+
|
|
38
|
+
return verify_main(rest)
|
|
39
|
+
print(f"cortexhub: unknown command {command!r}\n\n{_USAGE}", file=sys.stderr)
|
|
40
|
+
return 2
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
if __name__ == "__main__":
|
|
44
|
+
sys.exit(main())
|