cortexhub 0.5.28__tar.gz → 1.0.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.
Files changed (77) hide show
  1. cortexhub-1.0.0/PKG-INFO +188 -0
  2. cortexhub-1.0.0/README.md +165 -0
  3. cortexhub-1.0.0/pyproject.toml +78 -0
  4. cortexhub-1.0.0/src/cortexhub/__init__.py +43 -0
  5. cortexhub-1.0.0/src/cortexhub/client.py +68 -0
  6. cortexhub-1.0.0/src/cortexhub/errors.py +22 -0
  7. cortexhub-1.0.0/src/cortexhub/session.py +70 -0
  8. cortexhub-0.5.28/PKG-INFO +0 -148
  9. cortexhub-0.5.28/README.md +0 -81
  10. cortexhub-0.5.28/pyproject.toml +0 -137
  11. cortexhub-0.5.28/src/cortexhub/__init__.py +0 -134
  12. cortexhub-0.5.28/src/cortexhub/audit/__init__.py +0 -7
  13. cortexhub-0.5.28/src/cortexhub/audit/events.py +0 -51
  14. cortexhub-0.5.28/src/cortexhub/backend/__init__.py +0 -5
  15. cortexhub-0.5.28/src/cortexhub/backend/client.py +0 -672
  16. cortexhub-0.5.28/src/cortexhub/client.py +0 -5226
  17. cortexhub-0.5.28/src/cortexhub/config.py +0 -37
  18. cortexhub-0.5.28/src/cortexhub/constants.py +0 -174
  19. cortexhub-0.5.28/src/cortexhub/context/__init__.py +0 -5
  20. cortexhub-0.5.28/src/cortexhub/context/enricher.py +0 -73
  21. cortexhub-0.5.28/src/cortexhub/errors.py +0 -152
  22. cortexhub-0.5.28/src/cortexhub/gateway.py +0 -371
  23. cortexhub-0.5.28/src/cortexhub/guardrails/__init__.py +0 -3
  24. cortexhub-0.5.28/src/cortexhub/guardrails/injection.py +0 -180
  25. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/__init__.py +0 -10
  26. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/LICENSE +0 -19
  27. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/LICENSES_SOURCES +0 -66
  28. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/README.md +0 -47
  29. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/accuracy.json +0 -330
  30. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/attribute_ruler/patterns +0 -0
  31. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/config.cfg +0 -269
  32. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/lemmatizer/lookups/lookups.bin +0 -1
  33. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/meta.json +0 -521
  34. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/ner/cfg +0 -13
  35. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/ner/model +0 -0
  36. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/ner/moves +0 -1
  37. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/parser/cfg +0 -13
  38. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/parser/model +0 -0
  39. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/parser/moves +0 -1
  40. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/senter/cfg +0 -3
  41. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/senter/model +0 -0
  42. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tagger/cfg +0 -57
  43. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tagger/model +0 -0
  44. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tok2vec/cfg +0 -3
  45. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tok2vec/model +0 -0
  46. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tokenizer +0 -3
  47. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/key2row +0 -1
  48. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/lookups.bin +0 -0
  49. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/strings.json +0 -84782
  50. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/vectors +0 -0
  51. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/vectors.cfg +0 -3
  52. cortexhub-0.5.28/src/cortexhub/guardrails/models/en_core_web_sm/meta.json +0 -521
  53. cortexhub-0.5.28/src/cortexhub/guardrails/pii.py +0 -425
  54. cortexhub-0.5.28/src/cortexhub/guardrails/secrets.py +0 -206
  55. cortexhub-0.5.28/src/cortexhub/interceptors/__init__.py +0 -3
  56. cortexhub-0.5.28/src/cortexhub/interceptors/anthropic_llm.py +0 -272
  57. cortexhub-0.5.28/src/cortexhub/interceptors/framework_llm.py +0 -67
  58. cortexhub-0.5.28/src/cortexhub/interceptors/langchain_llm.py +0 -338
  59. cortexhub-0.5.28/src/cortexhub/interceptors/llama_index_llm.py +0 -493
  60. cortexhub-0.5.28/src/cortexhub/interceptors/mcp.py +0 -255
  61. cortexhub-0.5.28/src/cortexhub/interceptors/openai_agents.py +0 -409
  62. cortexhub-0.5.28/src/cortexhub/logging.py +0 -112
  63. cortexhub-0.5.28/src/cortexhub/policy/__init__.py +0 -6
  64. cortexhub-0.5.28/src/cortexhub/policy/absence.py +0 -78
  65. cortexhub-0.5.28/src/cortexhub/policy/constants.py +0 -6
  66. cortexhub-0.5.28/src/cortexhub/policy/effects.py +0 -148
  67. cortexhub-0.5.28/src/cortexhub/policy/evaluator.py +0 -569
  68. cortexhub-0.5.28/src/cortexhub/policy/loader.py +0 -185
  69. cortexhub-0.5.28/src/cortexhub/policy/models.py +0 -160
  70. cortexhub-0.5.28/src/cortexhub/policy/sync.py +0 -249
  71. cortexhub-0.5.28/src/cortexhub/signing.py +0 -192
  72. cortexhub-0.5.28/src/cortexhub/telemetry/__init__.py +0 -31
  73. cortexhub-0.5.28/src/cortexhub/telemetry/otel.py +0 -461
  74. cortexhub-0.5.28/src/cortexhub/tool.py +0 -287
  75. cortexhub-0.5.28/src/cortexhub/version.py +0 -27
  76. {cortexhub-0.5.28 → cortexhub-1.0.0}/.gitignore +0 -0
  77. {cortexhub-0.5.28 → cortexhub-1.0.0}/LICENSE +0 -0
@@ -0,0 +1,188 @@
1
+ Metadata-Version: 2.4
2
+ Name: cortexhub
3
+ Version: 1.0.0
4
+ Summary: MCP gateway client for cortexhub agents — authenticate, hand the MCP URL to your framework of choice, done.
5
+ Project-URL: Homepage, https://cortexhub.ai
6
+ Project-URL: Documentation, https://docs.cortexhub.ai
7
+ Project-URL: Examples, https://github.com/CortexHub-AI/examples/
8
+ Author-email: CortexHub <hello@cortexhub.ai>
9
+ License: MIT
10
+ License-File: LICENSE
11
+ Keywords: agents,ai,gateway,governance,mcp
12
+ Classifier: Development Status :: 5 - Production/Stable
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
21
+ Requires-Python: >=3.10
22
+ Description-Content-Type: text/markdown
23
+
24
+ # cortexhub
25
+
26
+ MCP gateway client for cortexhub agents. Authenticate, hand the MCP URL to your framework of choice, done.
27
+
28
+ [Documentation](https://docs.cortexhub.ai) · [Examples](https://github.com/CortexHub-AI/examples)
29
+
30
+ ## Install
31
+
32
+ ```bash
33
+ pip install cortexhub
34
+ ```
35
+
36
+ ## Quickstart
37
+
38
+ ```python
39
+ from cortexhub import Cortexhub
40
+
41
+ cortexhub = Cortexhub() # reads CORTEXHUB_API_KEY
42
+ session = cortexhub.create(user_id="user_123")
43
+
44
+ print(session.mcp.url) # https://api.cortexhub.ai/v1/mcp-http
45
+ print(session.mcp.headers) # {"Authorization": "Bearer ch_live_…", "X-Cortexhub-End-User-Subject": "user_123"}
46
+ ```
47
+
48
+ Get an API key by registering an agent at [app.cortexhub.ai](https://app.cortexhub.ai).
49
+
50
+ ## Use it with your framework
51
+
52
+ The SDK only hands you an MCP URL + headers. Plug them into whichever framework you use.
53
+
54
+ ### Claude Agent SDK
55
+
56
+ ```python
57
+ from cortexhub import Cortexhub
58
+ from claude_agent_sdk import ClaudeAgentOptions
59
+
60
+ cortexhub = Cortexhub()
61
+ session = cortexhub.create(user_id="user_123")
62
+
63
+ options = ClaudeAgentOptions(
64
+ mcp_servers={
65
+ "cortexhub": {
66
+ "type": "http",
67
+ "url": session.mcp.url,
68
+ "headers": session.mcp.headers,
69
+ },
70
+ },
71
+ )
72
+ ```
73
+
74
+ ### OpenAI Agents SDK
75
+
76
+ ```python
77
+ from cortexhub import Cortexhub
78
+ from agents import Agent, HostedMCPTool
79
+
80
+ cortexhub = Cortexhub()
81
+ session = cortexhub.create(user_id="user_123")
82
+
83
+ agent = Agent(
84
+ name="Assistant",
85
+ tools=[
86
+ HostedMCPTool(
87
+ tool_config={
88
+ "type": "mcp",
89
+ "server_label": "cortexhub",
90
+ "server_url": session.mcp.url,
91
+ "headers": session.mcp.headers,
92
+ "require_approval": "never",
93
+ }
94
+ )
95
+ ],
96
+ )
97
+ ```
98
+
99
+ ### Vercel AI SDK (TypeScript)
100
+
101
+ ```typescript
102
+ import { Cortexhub } from "@cortexhub/core"; // see @cortexhub/core (TS)
103
+ import { createMCPClient } from "@ai-sdk/mcp";
104
+
105
+ const cortexhub = new Cortexhub();
106
+ const session = await cortexhub.create("user_123");
107
+
108
+ const client = await createMCPClient({
109
+ transport: {
110
+ type: "http",
111
+ url: session.mcp.url,
112
+ headers: session.mcp.headers,
113
+ },
114
+ });
115
+ const tools = await client.tools();
116
+ ```
117
+
118
+ ### LangGraph (raw MCP)
119
+
120
+ Use the standard MCP client; pass the URL + headers from the session.
121
+
122
+ ```python
123
+ from cortexhub import Cortexhub
124
+ from mcp.client.streamable_http import streamablehttp_client
125
+ from mcp import ClientSession
126
+
127
+ cortexhub = Cortexhub()
128
+ session = cortexhub.create(user_id="user_123")
129
+
130
+ async with streamablehttp_client(session.mcp.url, headers=session.mcp.headers) as (read, write, _):
131
+ async with ClientSession(read, write) as mcp:
132
+ await mcp.initialize()
133
+ tools = await mcp.list_tools()
134
+ ```
135
+
136
+ ### Claude Desktop / Cursor / ChatGPT (no SDK)
137
+
138
+ Drop the URL + headers into the client's MCP server config — see [docs.cortexhub.ai/mcp-gateway/clients](https://docs.cortexhub.ai/mcp-gateway/clients).
139
+
140
+ ## Configuration
141
+
142
+ The SDK reads exactly one environment variable:
143
+
144
+ | Variable | Purpose |
145
+ |---|---|
146
+ | `CORTEXHUB_API_KEY` | Per-agent API key (`ch_live_…`) |
147
+
148
+ Or pass it explicitly:
149
+
150
+ ```python
151
+ cortexhub = Cortexhub(api_key="ch_live_…")
152
+ ```
153
+
154
+ The MCP gateway URL is fixed — `https://api.cortexhub.ai/v1/mcp-http`. There is no self-hosted mode and no base-URL override.
155
+
156
+ ## How `user_id` works
157
+
158
+ `user_id` is opaque to cortexhub — pass whatever stable identifier your application uses for the human (DB id, email hash, Auth0 sub, …). Cortexhub uses it to:
159
+
160
+ - Route per-end-user OAuth tokens (when the toolkit needs them)
161
+ - Attribute every tool call to that user in the audit log
162
+ - Evaluate per-user budget caps and rate limits
163
+
164
+ Calling `create()` with the same `user_id` twice is a no-op — the session is fully local and cheap to construct.
165
+
166
+ ## What this SDK doesn't do
167
+
168
+ The cortexhub MCP gateway is the source of truth for governance. The SDK has no:
169
+
170
+ - Decorators (no `@cx.tool` — the gateway discovers tools from your registered toolkits)
171
+ - Local Policy evaluation
172
+ - Local PII / secret / prompt-injection scanning
173
+ - Local span recording / OTLP export
174
+
175
+ All of that runs server-side at the gateway when the agent calls a tool through the URL above. The SDK is a thin wrapper around two strings (URL + headers).
176
+
177
+ ## Migrating from cortexhub 0.5.x
178
+
179
+ The v1 SDK is a complete rewrite. The decorator surface (`@cx.tool`, `cx.session`, `cx.run`, `cx.llm_call`, `cx.enforce`, …) is gone. If you used 0.5.x:
180
+
181
+ 1. Remove `cortexhub.init()` calls.
182
+ 2. Remove `@cx.tool` decorators — your tools come from cortexhub toolkits configured in the dashboard.
183
+ 3. Replace the function-call orchestration with an MCP-aware framework (Claude Agent SDK, OpenAI Agents, Vercel AI SDK, LangGraph, …).
184
+ 4. Use the snippets above to wire the MCP gateway into the framework.
185
+
186
+ ## License
187
+
188
+ MIT.
@@ -0,0 +1,165 @@
1
+ # cortexhub
2
+
3
+ MCP gateway client for cortexhub agents. Authenticate, hand the MCP URL to your framework of choice, done.
4
+
5
+ [Documentation](https://docs.cortexhub.ai) · [Examples](https://github.com/CortexHub-AI/examples)
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ pip install cortexhub
11
+ ```
12
+
13
+ ## Quickstart
14
+
15
+ ```python
16
+ from cortexhub import Cortexhub
17
+
18
+ cortexhub = Cortexhub() # reads CORTEXHUB_API_KEY
19
+ session = cortexhub.create(user_id="user_123")
20
+
21
+ print(session.mcp.url) # https://api.cortexhub.ai/v1/mcp-http
22
+ print(session.mcp.headers) # {"Authorization": "Bearer ch_live_…", "X-Cortexhub-End-User-Subject": "user_123"}
23
+ ```
24
+
25
+ Get an API key by registering an agent at [app.cortexhub.ai](https://app.cortexhub.ai).
26
+
27
+ ## Use it with your framework
28
+
29
+ The SDK only hands you an MCP URL + headers. Plug them into whichever framework you use.
30
+
31
+ ### Claude Agent SDK
32
+
33
+ ```python
34
+ from cortexhub import Cortexhub
35
+ from claude_agent_sdk import ClaudeAgentOptions
36
+
37
+ cortexhub = Cortexhub()
38
+ session = cortexhub.create(user_id="user_123")
39
+
40
+ options = ClaudeAgentOptions(
41
+ mcp_servers={
42
+ "cortexhub": {
43
+ "type": "http",
44
+ "url": session.mcp.url,
45
+ "headers": session.mcp.headers,
46
+ },
47
+ },
48
+ )
49
+ ```
50
+
51
+ ### OpenAI Agents SDK
52
+
53
+ ```python
54
+ from cortexhub import Cortexhub
55
+ from agents import Agent, HostedMCPTool
56
+
57
+ cortexhub = Cortexhub()
58
+ session = cortexhub.create(user_id="user_123")
59
+
60
+ agent = Agent(
61
+ name="Assistant",
62
+ tools=[
63
+ HostedMCPTool(
64
+ tool_config={
65
+ "type": "mcp",
66
+ "server_label": "cortexhub",
67
+ "server_url": session.mcp.url,
68
+ "headers": session.mcp.headers,
69
+ "require_approval": "never",
70
+ }
71
+ )
72
+ ],
73
+ )
74
+ ```
75
+
76
+ ### Vercel AI SDK (TypeScript)
77
+
78
+ ```typescript
79
+ import { Cortexhub } from "@cortexhub/core"; // see @cortexhub/core (TS)
80
+ import { createMCPClient } from "@ai-sdk/mcp";
81
+
82
+ const cortexhub = new Cortexhub();
83
+ const session = await cortexhub.create("user_123");
84
+
85
+ const client = await createMCPClient({
86
+ transport: {
87
+ type: "http",
88
+ url: session.mcp.url,
89
+ headers: session.mcp.headers,
90
+ },
91
+ });
92
+ const tools = await client.tools();
93
+ ```
94
+
95
+ ### LangGraph (raw MCP)
96
+
97
+ Use the standard MCP client; pass the URL + headers from the session.
98
+
99
+ ```python
100
+ from cortexhub import Cortexhub
101
+ from mcp.client.streamable_http import streamablehttp_client
102
+ from mcp import ClientSession
103
+
104
+ cortexhub = Cortexhub()
105
+ session = cortexhub.create(user_id="user_123")
106
+
107
+ async with streamablehttp_client(session.mcp.url, headers=session.mcp.headers) as (read, write, _):
108
+ async with ClientSession(read, write) as mcp:
109
+ await mcp.initialize()
110
+ tools = await mcp.list_tools()
111
+ ```
112
+
113
+ ### Claude Desktop / Cursor / ChatGPT (no SDK)
114
+
115
+ Drop the URL + headers into the client's MCP server config — see [docs.cortexhub.ai/mcp-gateway/clients](https://docs.cortexhub.ai/mcp-gateway/clients).
116
+
117
+ ## Configuration
118
+
119
+ The SDK reads exactly one environment variable:
120
+
121
+ | Variable | Purpose |
122
+ |---|---|
123
+ | `CORTEXHUB_API_KEY` | Per-agent API key (`ch_live_…`) |
124
+
125
+ Or pass it explicitly:
126
+
127
+ ```python
128
+ cortexhub = Cortexhub(api_key="ch_live_…")
129
+ ```
130
+
131
+ The MCP gateway URL is fixed — `https://api.cortexhub.ai/v1/mcp-http`. There is no self-hosted mode and no base-URL override.
132
+
133
+ ## How `user_id` works
134
+
135
+ `user_id` is opaque to cortexhub — pass whatever stable identifier your application uses for the human (DB id, email hash, Auth0 sub, …). Cortexhub uses it to:
136
+
137
+ - Route per-end-user OAuth tokens (when the toolkit needs them)
138
+ - Attribute every tool call to that user in the audit log
139
+ - Evaluate per-user budget caps and rate limits
140
+
141
+ Calling `create()` with the same `user_id` twice is a no-op — the session is fully local and cheap to construct.
142
+
143
+ ## What this SDK doesn't do
144
+
145
+ The cortexhub MCP gateway is the source of truth for governance. The SDK has no:
146
+
147
+ - Decorators (no `@cx.tool` — the gateway discovers tools from your registered toolkits)
148
+ - Local Policy evaluation
149
+ - Local PII / secret / prompt-injection scanning
150
+ - Local span recording / OTLP export
151
+
152
+ All of that runs server-side at the gateway when the agent calls a tool through the URL above. The SDK is a thin wrapper around two strings (URL + headers).
153
+
154
+ ## Migrating from cortexhub 0.5.x
155
+
156
+ The v1 SDK is a complete rewrite. The decorator surface (`@cx.tool`, `cx.session`, `cx.run`, `cx.llm_call`, `cx.enforce`, …) is gone. If you used 0.5.x:
157
+
158
+ 1. Remove `cortexhub.init()` calls.
159
+ 2. Remove `@cx.tool` decorators — your tools come from cortexhub toolkits configured in the dashboard.
160
+ 3. Replace the function-call orchestration with an MCP-aware framework (Claude Agent SDK, OpenAI Agents, Vercel AI SDK, LangGraph, …).
161
+ 4. Use the snippets above to wire the MCP gateway into the framework.
162
+
163
+ ## License
164
+
165
+ MIT.
@@ -0,0 +1,78 @@
1
+ [project]
2
+ name = "cortexhub"
3
+ version = "1.0.0"
4
+ description = "MCP gateway client for cortexhub agents — authenticate, hand the MCP URL to your framework of choice, done."
5
+ readme = "README.md"
6
+ requires-python = ">=3.10"
7
+ license = { text = "MIT" }
8
+ authors = [
9
+ { name = "CortexHub", email = "hello@cortexhub.ai" }
10
+ ]
11
+ keywords = ["ai", "agents", "mcp", "gateway", "governance"]
12
+ classifiers = [
13
+ "Development Status :: 5 - Production/Stable",
14
+ "Intended Audience :: Developers",
15
+ "License :: OSI Approved :: MIT License",
16
+ "Programming Language :: Python :: 3",
17
+ "Programming Language :: Python :: 3.10",
18
+ "Programming Language :: Python :: 3.11",
19
+ "Programming Language :: Python :: 3.12",
20
+ "Programming Language :: Python :: 3.13",
21
+ "Topic :: Software Development :: Libraries :: Python Modules",
22
+ ]
23
+
24
+ # v1 has no runtime dependencies. Construction is fully local — the SDK only
25
+ # computes a URL and a header dict. We deliberately do NOT pull in httpx /
26
+ # pydantic / opentelemetry / policy engine / presidio / spacy here: those used to
27
+ # do client-side governance and that work now lives on the cortexhub gateway.
28
+ dependencies = []
29
+
30
+ [project.urls]
31
+ Homepage = "https://cortexhub.ai"
32
+ Documentation = "https://docs.cortexhub.ai"
33
+ Examples = "https://github.com/CortexHub-AI/examples/"
34
+
35
+ [build-system]
36
+ requires = ["hatchling"]
37
+ build-backend = "hatchling.build"
38
+
39
+ [tool.hatch.build.targets.wheel]
40
+ packages = ["src/cortexhub"]
41
+ include = ["LICENSE"]
42
+
43
+ [tool.hatch.build.targets.sdist]
44
+ include = [
45
+ "/src",
46
+ "/README.md",
47
+ "/LICENSE",
48
+ ]
49
+
50
+ [tool.pytest.ini_options]
51
+ testpaths = ["tests"]
52
+ pythonpath = ["src"]
53
+ addopts = "-v --tb=short"
54
+
55
+ [tool.ruff]
56
+ target-version = "py310"
57
+ line-length = 100
58
+ src = ["src", "tests"]
59
+
60
+ [tool.ruff.lint]
61
+ select = ["E", "F", "I", "N", "W", "UP", "B", "C4", "DTZ", "T10", "RUF"]
62
+ ignore = ["E501"]
63
+
64
+ [tool.mypy]
65
+ python_version = "3.10"
66
+ strict = true
67
+ warn_return_any = true
68
+ warn_unused_ignores = true
69
+
70
+ [tool.uv]
71
+ python-preference = "only-managed"
72
+
73
+ [dependency-groups]
74
+ dev = [
75
+ "pytest>=9.0.2",
76
+ "ruff>=0.4.0",
77
+ "mypy>=1.10.0",
78
+ ]
@@ -0,0 +1,43 @@
1
+ """cortexhub — MCP gateway client for cortexhub agents.
2
+
3
+ Authenticate with your agent's API key, hand the MCP URL + headers to your
4
+ framework of choice (Claude Agent SDK, OpenAI Agents, Vercel AI SDK,
5
+ LangGraph, raw MCP — anything that speaks MCP streamable HTTP), and you're
6
+ done. Policies, approvals, scope checks, budget caps, and audit live on the
7
+ cortexhub MCP gateway; the SDK doesn't run anything client-side.
8
+
9
+ Quickstart::
10
+
11
+ from cortexhub import Cortexhub
12
+
13
+ cortexhub = Cortexhub() # reads CORTEXHUB_API_KEY
14
+ session = cortexhub.create(user_id="user_123")
15
+
16
+ # Hand to your framework
17
+ mcp_url = session.mcp.url
18
+ mcp_headers = session.mcp.headers
19
+
20
+ See README.md for end-to-end snippets per framework.
21
+ """
22
+
23
+ from __future__ import annotations
24
+
25
+ from .client import Cortexhub
26
+ from .errors import (
27
+ AuthenticationError,
28
+ ConfigurationError,
29
+ CortexhubError,
30
+ )
31
+ from .session import Session, SessionMcp
32
+
33
+ __version__ = "1.0.0"
34
+
35
+ __all__ = [
36
+ "Cortexhub",
37
+ "Session",
38
+ "SessionMcp",
39
+ "CortexhubError",
40
+ "ConfigurationError",
41
+ "AuthenticationError",
42
+ "__version__",
43
+ ]
@@ -0,0 +1,68 @@
1
+ """``Cortexhub`` — entry point for the v1 SDK.
2
+
3
+ Usage:
4
+
5
+ from cortexhub import Cortexhub
6
+
7
+ cortexhub = Cortexhub() # reads CORTEXHUB_API_KEY
8
+ session = cortexhub.create(user_id="user_123")
9
+ print(session.mcp.url, session.mcp.headers)
10
+
11
+ The class has exactly one method (``create``). The constructor reads
12
+ ``CORTEXHUB_API_KEY`` from the environment unless the caller passes one in.
13
+
14
+ There is **no base-URL override**: the cortexhub MCP gateway is a hosted SaaS
15
+ at ``https://api.cortexhub.ai`` and the SDK always points there. We don't
16
+ support self-hosted deployments.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import os
22
+
23
+ from .errors import ConfigurationError
24
+ from .session import Session
25
+
26
+ # Hosted gateway origin. Hard-coded on purpose — see module docstring.
27
+ _API_ORIGIN = "https://api.cortexhub.ai"
28
+
29
+
30
+ class Cortexhub:
31
+ """Per-agent cortexhub client.
32
+
33
+ One ``Cortexhub`` corresponds to one registered agent — its API key is
34
+ the agent's. Different agents (or different environments — staging vs
35
+ prod, separate agent keys) use different ``Cortexhub`` instances.
36
+ """
37
+
38
+ def __init__(self, api_key: str | None = None) -> None:
39
+ resolved_key = api_key or os.environ.get("CORTEXHUB_API_KEY")
40
+ if not resolved_key or not resolved_key.strip():
41
+ raise ConfigurationError(
42
+ "Missing API key. Pass api_key=... to Cortexhub() "
43
+ "or set the CORTEXHUB_API_KEY environment variable. "
44
+ "Get a key by registering an agent at https://app.cortexhub.ai."
45
+ )
46
+ self.api_key: str = resolved_key.strip()
47
+
48
+ def create(self, user_id: str) -> Session:
49
+ """Create a session bound to one end-user.
50
+
51
+ ``user_id`` is opaque to cortexhub — it's whatever stable identifier
52
+ your application uses for the human (DB id, email hash, Auth0 sub,
53
+ etc.). The cortexhub MCP gateway will use it to:
54
+
55
+ * Route per-end-user OAuth tokens (when the toolkit needs them)
56
+ * Attribute every tool call to that user in the audit log
57
+ * Evaluate per-user budget caps and rate limits
58
+
59
+ The same ``user_id`` always produces the same per-user session state
60
+ on the gateway side; calling ``create`` twice for the same user is a
61
+ no-op (and cheap — fully local).
62
+ """
63
+ return Session(api_key=self.api_key, user_id=user_id)
64
+
65
+ def __repr__(self) -> str:
66
+ # Echo only the key prefix so logs are useful but leak nothing.
67
+ prefix = self.api_key[:10] + "…" if len(self.api_key) > 10 else "…"
68
+ return f"Cortexhub(api_key={prefix!r})"
@@ -0,0 +1,22 @@
1
+ """Minimal error hierarchy for the cortexhub SDK.
2
+
3
+ Everything in v1.0 is a thin client around the cortexhub MCP gateway, so the SDK
4
+ itself raises only on **local** problems (missing API key, malformed URL).
5
+ Server-side errors — policy violations, budget caps, approvals — surface as
6
+ MCP tool-call responses; the framework you wrap them in is responsible for
7
+ displaying them.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+
13
+ class CortexhubError(Exception):
14
+ """Base for every error this SDK raises."""
15
+
16
+
17
+ class ConfigurationError(CortexhubError):
18
+ """The SDK was initialised without a usable API key or base URL."""
19
+
20
+
21
+ class AuthenticationError(CortexhubError):
22
+ """Reserved for future use — when SDK methods do call the cortexhub API."""
@@ -0,0 +1,70 @@
1
+ """Session — what ``Cortexhub.create(user_id=...)`` returns.
2
+
3
+ A ``Session`` is a tiny value object: it holds the (api_key, user_id) pair
4
+ and exposes ``session.mcp.url`` + ``session.mcp.headers`` which the caller
5
+ hands to their framework's MCP client.
6
+
7
+ Construction is fully local — no network call. The cortexhub MCP gateway
8
+ authenticates each tool call by reading the ``Authorization`` header (the
9
+ agent's API key) and the ``X-Cortexhub-End-User-Subject`` header (the
10
+ end-user the session is bound to). Per-end-user OAuth state, per-agent
11
+ budget caps, Policy decisions, and HITL approvals are all resolved
12
+ server-side at the gateway — the SDK has no governance code.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ from dataclasses import dataclass, field
18
+
19
+ # Hosted gateway URL. Hard-coded — the SDK does not support self-hosted
20
+ # deployments, so there is no override to thread through.
21
+ _MCP_URL = "https://api.cortexhub.ai/v1/mcp-http"
22
+
23
+ # Header the gateway reads to bind a session to a specific end-user. Mirrors
24
+ # the convention used elsewhere in cortexhub (``X-Cortexhub-...``); kept in
25
+ # one place so a future rename only needs to touch this module.
26
+ _END_USER_SUBJECT_HEADER = "X-Cortexhub-End-User-Subject"
27
+
28
+
29
+ @dataclass(frozen=True)
30
+ class SessionMcp:
31
+ """The MCP connection details — pass straight to your framework.
32
+
33
+ ``url`` is the streamable-HTTP MCP endpoint; ``headers`` carry the agent
34
+ API key plus the end-user subject. Frozen so callers can't accidentally
35
+ mutate the dict and lose auth on subsequent calls.
36
+ """
37
+
38
+ url: str
39
+ headers: dict[str, str] = field(default_factory=dict)
40
+
41
+
42
+ class Session:
43
+ """A per-end-user session bound to one cortexhub agent.
44
+
45
+ Created via :meth:`Cortexhub.create`. Carries ``user_id`` for caller
46
+ introspection and ``mcp`` for the framework hand-off. The constructor is
47
+ keyword-only so accidental positional drift on a future signature change
48
+ fails loudly.
49
+ """
50
+
51
+ def __init__(self, *, api_key: str, user_id: str) -> None:
52
+ if not user_id:
53
+ raise ValueError("user_id is required.")
54
+ # Public — callers may want to log it / pass it back into their
55
+ # downstream context (e.g. structured log fields).
56
+ self.user_id: str = user_id
57
+ # Private — exposed only via ``mcp.headers`` so callers don't get
58
+ # tempted to do ad-hoc HTTP with these credentials.
59
+ self._api_key = api_key
60
+ self.mcp: SessionMcp = SessionMcp(
61
+ url=_MCP_URL,
62
+ headers={
63
+ "Authorization": f"Bearer {api_key}",
64
+ _END_USER_SUBJECT_HEADER: user_id,
65
+ },
66
+ )
67
+
68
+ def __repr__(self) -> str:
69
+ # Don't echo the key.
70
+ return f"Session(user_id={self.user_id!r}, mcp={self.mcp.url!r})"