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.
@@ -1,13 +1,13 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: cortexhub
3
- Version: 3.1.1
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: mcp>=1.0; extra == 'all'
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>=1.0; extra == '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_...") # or set CORTEXHUB_API_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
- 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.
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`, and choose a `model`.
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
- base, key = cx.ai.base_url, cx.ai.api_key
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).chat.completions.create(model="cortexhub/auto", messages=[...])
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(base_url=base, api_key=key))
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 (governed toolkit calls, brain recall/learn, files search) then appear
153
- automatically -- and, on the session handle, group with that run's LLM turns.
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 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).
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
- print("Approve to continue:", task["consent_url"]) # show the end user
222
- text = await _await_decision(mcp, task["task_id"]) # wait for the decision
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 a signed consent_url.
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("consent_url"):
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, "wait_ms": 1000})
261
- if _payload(res).get("terminal"):
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_...") # or set CORTEXHUB_API_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
- 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.
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`, and choose a `model`.
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
- base, key = cx.ai.base_url, cx.ai.api_key
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).chat.completions.create(model="cortexhub/auto", messages=[...])
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(base_url=base, api_key=key))
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 (governed toolkit calls, brain recall/learn, files search) then appear
124
- automatically -- and, on the session handle, group with that run's LLM turns.
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 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).
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
- print("Approve to continue:", task["consent_url"]) # show the end user
193
- text = await _await_decision(mcp, task["task_id"]) # wait for the decision
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 a signed consent_url.
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("consent_url"):
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, "wait_ms": 1000})
232
- if _payload(res).get("terminal"):
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.1.1"
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
- mcp = ["mcp>=1.0"]
37
- all = ["openai>=1.40", "mcp>=1.0"]
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.1.1"
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())