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.
@@ -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.
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "cortexhub"
3
- version = "3.0.0"
3
+ version = "3.1.1"
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"
@@ -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.0.0"
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 MCP transport details (``.mcp.url`` and ``.mcp.headers``).
115
+ """Return a session handle for ONE conversation or autonomous run.
116
116
 
117
- ``agent`` is required on every call.
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