cortexhub 0.3.5__tar.gz → 0.4.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {cortexhub-0.3.5 → cortexhub-0.4.0}/PKG-INFO +6 -4
- {cortexhub-0.3.5 → cortexhub-0.4.0}/README.md +4 -2
- {cortexhub-0.3.5 → cortexhub-0.4.0}/pyproject.toml +4 -4
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/__init__.py +23 -40
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/backend/__init__.py +1 -1
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/backend/client.py +80 -75
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/client.py +152 -203
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/config.py +1 -1
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/errors.py +1 -1
- cortexhub-0.4.0/src/cortexhub/interceptors/mcp.py +181 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/policy/__init__.py +1 -1
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/policy/effects.py +27 -9
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/policy/evaluator.py +37 -26
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/policy/loader.py +16 -15
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/policy/sync.py +18 -18
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/telemetry/otel.py +18 -18
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/tool.py +2 -2
- cortexhub-0.3.5/src/cortexhub/interceptors/mcp.py +0 -129
- {cortexhub-0.3.5 → cortexhub-0.4.0}/.gitignore +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/LICENSE +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/audit/__init__.py +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/audit/events.py +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/constants.py +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/context/__init__.py +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/context/enricher.py +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/__init__.py +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/injection.py +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/__init__.py +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/LICENSE +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/LICENSES_SOURCES +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/README.md +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/accuracy.json +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/attribute_ruler/patterns +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/config.cfg +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/lemmatizer/lookups/lookups.bin +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/meta.json +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/ner/cfg +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/ner/model +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/ner/moves +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/parser/cfg +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/parser/model +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/parser/moves +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/senter/cfg +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/senter/model +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tagger/cfg +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tagger/model +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tok2vec/cfg +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tok2vec/model +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tokenizer +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/key2row +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/lookups.bin +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/strings.json +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/vectors +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/vectors.cfg +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/models/en_core_web_sm/meta.json +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/pii.py +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/guardrails/secrets.py +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/interceptors/__init__.py +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/logging.py +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/policy/models.py +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/signing.py +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/telemetry/__init__.py +0 -0
- {cortexhub-0.3.5 → cortexhub-0.4.0}/src/cortexhub/version.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: cortexhub
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.4.0
|
|
4
4
|
Summary: CortexHub Python SDK — Runtime governance for AI systems. One decorator, any tool, any framework.
|
|
5
5
|
Project-URL: Homepage, https://cortexhub.ai
|
|
6
6
|
Project-URL: Documentation, https://docs.cortexhub.ai
|
|
@@ -8,7 +8,7 @@ Project-URL: Examples, https://github.com/CortexHub-AI/examples/
|
|
|
8
8
|
Author-email: CortexHub <hello@cortexhub.ai>
|
|
9
9
|
License: MIT
|
|
10
10
|
License-File: LICENSE
|
|
11
|
-
Keywords: agents,ai,authorization,
|
|
11
|
+
Keywords: agents,ai,authorization,governance,policy
|
|
12
12
|
Classifier: Development Status :: 4 - Beta
|
|
13
13
|
Classifier: Intended Audience :: Developers
|
|
14
14
|
Classifier: License :: OSI Approved :: MIT License
|
|
@@ -46,10 +46,12 @@ Python 3.10–3.12.
|
|
|
46
46
|
|
|
47
47
|
## Quick start
|
|
48
48
|
|
|
49
|
+
Identity comes from your **agent key** only — the control plane assigns the canonical agent id. Set `CORTEXHUB_AGENT_KEY` (or pass `agent_key=` to `init()`).
|
|
50
|
+
|
|
49
51
|
```python
|
|
50
52
|
import cortexhub
|
|
51
53
|
|
|
52
|
-
cx = cortexhub.init(
|
|
54
|
+
cx = cortexhub.init() # requires CORTEXHUB_AGENT_KEY (or pass agent_key=)
|
|
53
55
|
|
|
54
56
|
@cx.tool
|
|
55
57
|
def process_payment(customer_id: str, amount: str, reference: str) -> dict:
|
|
@@ -63,7 +65,7 @@ def process_payment(customer_id: str, amount: str, reference: str) -> dict:
|
|
|
63
65
|
|
|
64
66
|
| Env var | Description |
|
|
65
67
|
|--------|-------------|
|
|
66
|
-
| `
|
|
68
|
+
| `CORTEXHUB_AGENT_KEY` | Agent identity secret (required for cloud enforcement) |
|
|
67
69
|
| `CORTEXHUB_DEBUG` | Set to `1` or `true` for readable SDK logs: tool + arguments, policy name + condition, and decision |
|
|
68
70
|
| `CORTEXHUB_LOG_LEVEL` | e.g. `DEBUG`, `INFO` (default `INFO`) |
|
|
69
71
|
|
|
@@ -10,10 +10,12 @@ Python 3.10–3.12.
|
|
|
10
10
|
|
|
11
11
|
## Quick start
|
|
12
12
|
|
|
13
|
+
Identity comes from your **agent key** only — the control plane assigns the canonical agent id. Set `CORTEXHUB_AGENT_KEY` (or pass `agent_key=` to `init()`).
|
|
14
|
+
|
|
13
15
|
```python
|
|
14
16
|
import cortexhub
|
|
15
17
|
|
|
16
|
-
cx = cortexhub.init(
|
|
18
|
+
cx = cortexhub.init() # requires CORTEXHUB_AGENT_KEY (or pass agent_key=)
|
|
17
19
|
|
|
18
20
|
@cx.tool
|
|
19
21
|
def process_payment(customer_id: str, amount: str, reference: str) -> dict:
|
|
@@ -27,7 +29,7 @@ def process_payment(customer_id: str, amount: str, reference: str) -> dict:
|
|
|
27
29
|
|
|
28
30
|
| Env var | Description |
|
|
29
31
|
|--------|-------------|
|
|
30
|
-
| `
|
|
32
|
+
| `CORTEXHUB_AGENT_KEY` | Agent identity secret (required for cloud enforcement) |
|
|
31
33
|
| `CORTEXHUB_DEBUG` | Set to `1` or `true` for readable SDK logs: tool + arguments, policy name + condition, and decision |
|
|
32
34
|
| `CORTEXHUB_LOG_LEVEL` | e.g. `DEBUG`, `INFO` (default `INFO`) |
|
|
33
35
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "cortexhub"
|
|
3
|
-
version = "0.
|
|
3
|
+
version = "0.4.0"
|
|
4
4
|
description = "CortexHub Python SDK — Runtime governance for AI systems. One decorator, any tool, any framework."
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
requires-python = ">=3.10,<3.13"
|
|
@@ -8,7 +8,7 @@ license = { text = "MIT" }
|
|
|
8
8
|
authors = [
|
|
9
9
|
{ name = "CortexHub", email = "hello@cortexhub.ai" }
|
|
10
10
|
]
|
|
11
|
-
keywords = ["ai", "agents", "policy", "governance", "authorization"
|
|
11
|
+
keywords = ["ai", "agents", "policy", "governance", "authorization"]
|
|
12
12
|
classifiers = [
|
|
13
13
|
"Development Status :: 4 - Beta",
|
|
14
14
|
"Intended Audience :: Developers",
|
|
@@ -31,7 +31,7 @@ dependencies = [
|
|
|
31
31
|
"opentelemetry-api>=1.20.0",
|
|
32
32
|
"opentelemetry-sdk>=1.20.0",
|
|
33
33
|
"opentelemetry-exporter-otlp-proto-http>=1.20.0",
|
|
34
|
-
#
|
|
34
|
+
# In-process policy evaluation (no network per call)
|
|
35
35
|
"cedarpy>=4.0.0",
|
|
36
36
|
# Guardrails — PII and secrets detection before LLM calls
|
|
37
37
|
"presidio-analyzer>=2.2.360",
|
|
@@ -42,7 +42,7 @@ dependencies = [
|
|
|
42
42
|
"spacy-lookups-data>=1.0.0",
|
|
43
43
|
# Ed25519 decision signing — tamper-evident cryptographic audit trail
|
|
44
44
|
"cryptography>=43.0.0",
|
|
45
|
-
# .env file loading for
|
|
45
|
+
# .env file loading for CORTEXHUB_AGENT_KEY etc.
|
|
46
46
|
"python-dotenv>=1.0.0",
|
|
47
47
|
]
|
|
48
48
|
|
|
@@ -4,33 +4,26 @@ One decorator. Any tool. Any framework. Anywhere.
|
|
|
4
4
|
|
|
5
5
|
import cortexhub
|
|
6
6
|
|
|
7
|
-
cx = cortexhub.init(
|
|
7
|
+
cx = cortexhub.init()
|
|
8
8
|
|
|
9
9
|
@cx.tool
|
|
10
10
|
def prescribe_medication(patient_id: str, medication: str, dosage: str) -> str:
|
|
11
|
-
\"\"\"Prescribe medication to a patient.\"\"\"
|
|
11
|
+
\"\"\"Prescribe a medication to a patient.\"\"\"
|
|
12
12
|
return db.prescribe(patient_id, medication, dosage)
|
|
13
13
|
|
|
14
14
|
async with cx.run():
|
|
15
15
|
try:
|
|
16
16
|
result = await my_agent(user_input)
|
|
17
|
-
except cortexhub.
|
|
17
|
+
except cortexhub.ApprovalRequiredError as e:
|
|
18
18
|
await cx.wait_for_approval(e)
|
|
19
19
|
result = cx.retry_tool(e)
|
|
20
20
|
except cortexhub.PolicyViolationError as e:
|
|
21
21
|
return {"blocked": True, "reason": e.reasoning}
|
|
22
22
|
|
|
23
|
-
CortexHub
|
|
24
|
-
|
|
25
|
-
- PII, secrets, and prompt injection guardrails
|
|
26
|
-
- Cryptographically signed audit trail (Ed25519)
|
|
27
|
-
- Human-in-the-loop approval workflows
|
|
28
|
-
- EU AI Act Article 12 compliance telemetry
|
|
23
|
+
Set ``CORTEXHUB_AGENT_KEY`` to the key from your governed agent in CortexHub; the SDK
|
|
24
|
+
loads canonical ``agent_id`` and display metadata from the control plane on startup.
|
|
29
25
|
|
|
30
|
-
|
|
31
|
-
Claude Agents, raw Python, Flask, FastAPI, scripts, cron jobs — anything.
|
|
32
|
-
|
|
33
|
-
Get your API key at https://app.cortexhub.ai
|
|
26
|
+
Create an agent and copy its key from https://app.cortexhub.ai
|
|
34
27
|
"""
|
|
35
28
|
|
|
36
29
|
from cortexhub.client import CortexHub, SessionContext
|
|
@@ -53,21 +46,23 @@ _global_instance: CortexHub | None = None
|
|
|
53
46
|
|
|
54
47
|
|
|
55
48
|
def init(
|
|
56
|
-
agent_id: str,
|
|
57
49
|
*,
|
|
58
|
-
|
|
50
|
+
agent_key: str | None = None,
|
|
59
51
|
enable_mcp: bool = False,
|
|
60
52
|
log_level: str | None = None,
|
|
61
53
|
log_file: str | None = None,
|
|
62
54
|
log_to_console: bool | None = None,
|
|
63
|
-
|
|
64
|
-
delegation_chain: list[str] | None = None,
|
|
55
|
+
framework: str | None = None,
|
|
65
56
|
) -> CortexHub:
|
|
66
57
|
"""Initialise CortexHub governance and return a CortexHub instance.
|
|
67
58
|
|
|
68
|
-
Call once per agent
|
|
59
|
+
Call once per process (one governed agent key). Identity comes from the key::
|
|
60
|
+
|
|
61
|
+
cx = cortexhub.init()
|
|
62
|
+
|
|
63
|
+
Or pass the key explicitly::
|
|
69
64
|
|
|
70
|
-
cx = cortexhub.init("
|
|
65
|
+
cx = cortexhub.init(agent_key="ch_live_...")
|
|
71
66
|
|
|
72
67
|
Then use the returned instance to govern tools and LLM calls::
|
|
73
68
|
|
|
@@ -77,21 +72,15 @@ def init(
|
|
|
77
72
|
async with cx.run():
|
|
78
73
|
result = await my_agent(input)
|
|
79
74
|
|
|
80
|
-
Privacy (redact vs raw telemetry) is controlled
|
|
81
|
-
CortexHub dashboard (Privacy: On / Off). There is no SDK-level override.
|
|
75
|
+
Privacy (redact vs raw telemetry) is controlled in the CortexHub dashboard.
|
|
82
76
|
|
|
83
77
|
Args:
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
log_level: Log level override ("DEBUG", "INFO", "WARNING", "ERROR").
|
|
91
|
-
log_file: Path to write structured JSON logs.
|
|
92
|
-
log_to_console: If True, echo logs to stdout.
|
|
93
|
-
parent_agent_id: For multi-agent systems: the parent agent's ID.
|
|
94
|
-
delegation_chain: For multi-agent systems: pass parent.child_delegation_chain.
|
|
78
|
+
agent_key: Secret for this governed agent. Defaults to ``CORTEXHUB_AGENT_KEY``.
|
|
79
|
+
enable_mcp: If True, patch mcp.ClientSession.call_tool for MCP tool governance.
|
|
80
|
+
log_level: Log level override ("DEBUG", "INFO", "WARNING", "ERROR").
|
|
81
|
+
log_file: Path to write structured JSON logs.
|
|
82
|
+
log_to_console: If True, echo logs to stdout.
|
|
83
|
+
framework: Optional label sent on validation (e.g. ``langgraph``).
|
|
95
84
|
|
|
96
85
|
Returns:
|
|
97
86
|
CortexHub instance with .tool(), .run(), .enforce(), etc.
|
|
@@ -99,19 +88,16 @@ def init(
|
|
|
99
88
|
global _global_instance
|
|
100
89
|
|
|
101
90
|
instance = CortexHub(
|
|
102
|
-
|
|
103
|
-
agent_id=agent_id,
|
|
91
|
+
agent_key=agent_key,
|
|
104
92
|
log_level=log_level,
|
|
105
93
|
log_file=log_file,
|
|
106
94
|
log_to_console=log_to_console,
|
|
107
|
-
|
|
108
|
-
delegation_chain=delegation_chain,
|
|
95
|
+
framework=framework,
|
|
109
96
|
)
|
|
110
97
|
|
|
111
98
|
if enable_mcp:
|
|
112
99
|
instance.enable_mcp()
|
|
113
100
|
|
|
114
|
-
# Store as global for get_instance() convenience
|
|
115
101
|
_global_instance = instance
|
|
116
102
|
return instance
|
|
117
103
|
|
|
@@ -122,15 +108,12 @@ def get_instance() -> CortexHub | None:
|
|
|
122
108
|
|
|
123
109
|
|
|
124
110
|
__all__ = [
|
|
125
|
-
# Primary API
|
|
126
111
|
"init",
|
|
127
112
|
"get_instance",
|
|
128
113
|
"CortexHub",
|
|
129
114
|
"SessionContext",
|
|
130
115
|
"__version__",
|
|
131
|
-
# Audit / compliance verification
|
|
132
116
|
"verify_signature",
|
|
133
|
-
# Governance errors — catch these in your agent code
|
|
134
117
|
"CortexHubError",
|
|
135
118
|
"ConfigurationError",
|
|
136
119
|
"PolicyViolationError",
|
|
@@ -40,54 +40,56 @@ class GuardrailConfig:
|
|
|
40
40
|
|
|
41
41
|
@dataclass
|
|
42
42
|
class PolicyBundle:
|
|
43
|
-
"""Policy bundle from backend.
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
43
|
+
"""Policy bundle from backend (v2).
|
|
44
|
+
|
|
45
|
+
When no active policies exist for the governed agent, the bundle is empty and every tool is
|
|
46
|
+
**ungoverned** (SDK does not run Cedar). When policies exist, evaluation is per-tool:
|
|
47
|
+
tools without an entry in ``tool_policies`` are ungoverned (permit).
|
|
48
|
+
|
|
49
49
|
privacy_mode controls telemetry redaction:
|
|
50
50
|
- "on" : redact PII/secrets in telemetry before sending (default)
|
|
51
51
|
- "off" : send raw data (dev/staging only)
|
|
52
|
-
|
|
53
|
-
When policies is empty AND enforcement_mode is "active", SDK is in observation mode
|
|
54
|
-
(no policies to evaluate). When policies is non-empty and enforcement_mode is "active",
|
|
55
|
-
full enforcement is active.
|
|
56
52
|
|
|
57
|
-
tool_policies: when present, SDK evaluates only the policies for the tool being invoked
|
|
58
|
-
(per-tool Cedar + per-tool schema). Preferred over flat policies + merged schema.
|
|
53
|
+
tool_policies: when present, SDK evaluates only the policies for the tool being invoked.
|
|
59
54
|
"""
|
|
60
55
|
version: str
|
|
61
|
-
policies: str #
|
|
62
|
-
schema: dict[str, Any] | None = None #
|
|
56
|
+
policies: str # Policy source text (empty when using per-tool bundles only)
|
|
57
|
+
schema: dict[str, Any] | None = None # Merged schema when tool_policies not used
|
|
63
58
|
policy_metadata: dict[str, dict[str, Any]] | None = None
|
|
64
|
-
# Per-tool policies: tool_name -> { "cedar", "schema", "policy_metadata" }; SDK uses this at runtime.
|
|
65
59
|
tool_policies: dict[str, dict[str, Any]] | None = None
|
|
66
|
-
# Guardrail configurations (keyed by policy type: "pii", "secrets")
|
|
67
60
|
guardrail_configs: dict[str, GuardrailConfig] | None = None
|
|
68
61
|
policy_defaults: dict[str, Any] | None = None
|
|
69
62
|
policy_packs: list[dict[str, Any]] | None = None
|
|
70
|
-
|
|
71
|
-
# NoDecision behavior: allow_and_log | deny_and_log | escalate (project-level from backend)
|
|
63
|
+
# NoDecision / engine edge cases only (not used for ungoverned tools in per-tool mode)
|
|
72
64
|
default_behavior: str = "allow_and_log"
|
|
73
|
-
guardrail_version: str = "0"
|
|
74
|
-
privacy_mode: str = "on"
|
|
65
|
+
guardrail_version: str = "0"
|
|
66
|
+
privacy_mode: str = "on"
|
|
75
67
|
|
|
76
68
|
|
|
77
69
|
@dataclass
|
|
78
70
|
class SDKConfig:
|
|
79
71
|
"""SDK configuration from backend.
|
|
80
|
-
|
|
81
|
-
Returned
|
|
72
|
+
|
|
73
|
+
Returned after successful agent-key validation.
|
|
82
74
|
"""
|
|
83
|
-
|
|
75
|
+
|
|
76
|
+
agent_id: str
|
|
84
77
|
organization_id: str
|
|
85
78
|
plan: str
|
|
86
79
|
policies: PolicyBundle
|
|
87
|
-
|
|
80
|
+
agent_name: str | None = None
|
|
81
|
+
agent_slug: str | None = None
|
|
82
|
+
environment: str | None = None
|
|
83
|
+
group_id: str | None = None
|
|
84
|
+
|
|
85
|
+
@property
|
|
86
|
+
def project_id(self) -> str:
|
|
87
|
+
"""Alias for :attr:`agent_id` (governed agent ObjectId string)."""
|
|
88
|
+
return self.agent_id
|
|
89
|
+
|
|
88
90
|
@property
|
|
89
91
|
def has_policies(self) -> bool:
|
|
90
|
-
"""
|
|
92
|
+
"""True if the governed agent has at least one active policy row (governed tools may exist)."""
|
|
91
93
|
if self.policies.tool_policies:
|
|
92
94
|
return True
|
|
93
95
|
return bool(self.policies.policies.strip())
|
|
@@ -95,51 +97,54 @@ class SDKConfig:
|
|
|
95
97
|
|
|
96
98
|
class BackendClient:
|
|
97
99
|
"""Client for communicating with CortexHub backend.
|
|
98
|
-
|
|
99
|
-
Handles
|
|
100
|
-
- API key validation + policy retrieval
|
|
100
|
+
|
|
101
|
+
Handles agent-key validation, policy retrieval, and SDK HTTP calls.
|
|
101
102
|
"""
|
|
102
103
|
|
|
103
|
-
def __init__(self,
|
|
104
|
+
def __init__(self, agent_key: str | None, backend_url: str):
|
|
104
105
|
"""Initialize backend client.
|
|
105
|
-
|
|
106
|
+
|
|
106
107
|
Args:
|
|
107
|
-
|
|
108
|
-
backend_url: Backend API URL
|
|
108
|
+
agent_key: Secret issued for this agent identity (sent as ``X-API-Key``).
|
|
109
|
+
backend_url: Backend API URL (must include ``/v1`` base path used by the SDK).
|
|
109
110
|
"""
|
|
110
|
-
self.
|
|
111
|
+
self.agent_key = agent_key
|
|
111
112
|
self.backend_url = backend_url.rstrip("/")
|
|
112
113
|
self._client: httpx.Client | None = None
|
|
113
|
-
|
|
114
|
-
if
|
|
114
|
+
|
|
115
|
+
if agent_key:
|
|
115
116
|
self._client = httpx.Client(
|
|
116
117
|
base_url=self.backend_url,
|
|
117
|
-
headers={"X-API-Key":
|
|
118
|
+
headers={"X-API-Key": agent_key},
|
|
118
119
|
timeout=10.0,
|
|
119
120
|
)
|
|
120
|
-
|
|
121
|
-
def
|
|
122
|
-
|
|
123
|
-
|
|
121
|
+
|
|
122
|
+
def validate_agent_key(
|
|
123
|
+
self,
|
|
124
|
+
*,
|
|
125
|
+
mode: str | None = None,
|
|
126
|
+
framework: str | None = None,
|
|
127
|
+
) -> tuple[bool, SDKConfig | None]:
|
|
128
|
+
"""Validate the agent key with the backend and load SDK configuration.
|
|
129
|
+
|
|
124
130
|
Returns:
|
|
125
131
|
(is_valid, SDKConfig or None)
|
|
126
|
-
|
|
127
|
-
SDKConfig includes
|
|
128
|
-
- project_id, organization_id
|
|
129
|
-
- policies (empty = observation mode, non-empty = enforcement mode)
|
|
132
|
+
|
|
133
|
+
SDKConfig includes governed ``agent_id`` (ObjectId string), display metadata, and policies.
|
|
130
134
|
"""
|
|
131
|
-
if not self.
|
|
135
|
+
if not self.agent_key or not self._client:
|
|
132
136
|
return False, None
|
|
133
137
|
|
|
134
138
|
try:
|
|
135
139
|
# Note: base_url already includes /v1, so just /api-keys/validate.
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
+
payload: dict[str, str] = {}
|
|
141
|
+
if mode:
|
|
142
|
+
payload["mode"] = mode
|
|
143
|
+
if framework:
|
|
144
|
+
payload["framework"] = framework
|
|
140
145
|
response = self._client.post(
|
|
141
146
|
"/api-keys/validate",
|
|
142
|
-
headers={"X-API-Key": self.
|
|
147
|
+
headers={"X-API-Key": self.agent_key},
|
|
143
148
|
json=payload if payload else None,
|
|
144
149
|
timeout=5.0,
|
|
145
150
|
)
|
|
@@ -149,7 +154,7 @@ class BackendClient:
|
|
|
149
154
|
|
|
150
155
|
# Check if valid
|
|
151
156
|
if not data.get("valid", False):
|
|
152
|
-
logger.warning("
|
|
157
|
+
logger.warning("Agent key validation failed", message=data.get("message"))
|
|
153
158
|
return False, None
|
|
154
159
|
|
|
155
160
|
# Parse policy bundle from backend
|
|
@@ -159,12 +164,6 @@ class BackendClient:
|
|
|
159
164
|
if not isinstance(policies_data, dict):
|
|
160
165
|
policies_data = {}
|
|
161
166
|
raw_policies = policies_data.get("policies", [])
|
|
162
|
-
if agent_id:
|
|
163
|
-
raw_policies = [
|
|
164
|
-
policy
|
|
165
|
-
for policy in raw_policies
|
|
166
|
-
if policy.get("agent_id") in (agent_id, "all", None, "")
|
|
167
|
-
]
|
|
168
167
|
guardrail_configs: dict[str, GuardrailConfig] = {}
|
|
169
168
|
|
|
170
169
|
# Project-level guardrail config (applies to all agents; used for data sent to LLMs)
|
|
@@ -203,10 +202,10 @@ class BackendClient:
|
|
|
203
202
|
)
|
|
204
203
|
|
|
205
204
|
if isinstance(raw_policies, list):
|
|
206
|
-
# Backend returns list of policy objects - extract
|
|
205
|
+
# Backend returns list of policy objects - extract policy text (no guardrail_config on policies)
|
|
207
206
|
cedar_parts = []
|
|
208
207
|
# Default permit: allow all tool invocations unless a forbid policy matches.
|
|
209
|
-
# Without this,
|
|
208
|
+
# Without this, the engine default would deny every tool that has no policy
|
|
210
209
|
# (e.g. lookup_patient when only prescribe_medication has a policy).
|
|
211
210
|
if raw_policies:
|
|
212
211
|
cedar_parts.append("// Default: allow unless a forbid matches (tools with no policy are allowed)")
|
|
@@ -265,25 +264,31 @@ class BackendClient:
|
|
|
265
264
|
guardrail_configs=guardrail_configs if guardrail_configs else None,
|
|
266
265
|
policy_defaults=policies_data.get("policy_defaults"),
|
|
267
266
|
policy_packs=policies_data.get("policy_packs"),
|
|
268
|
-
enforcement_mode=policies_data.get("enforcement_mode", "active"),
|
|
269
267
|
default_behavior=policies_data.get("default_behavior", "allow_and_log"),
|
|
270
268
|
guardrail_version=policies_data.get("guardrail_version", "0"),
|
|
271
269
|
privacy_mode=_privacy,
|
|
272
270
|
)
|
|
273
271
|
logger.debug("Validate response privacy_mode", privacy_mode=_privacy)
|
|
274
272
|
|
|
273
|
+
_aid = data.get("agent_id") or data.get("project_id") or ""
|
|
274
|
+
_gid = data.get("group_id")
|
|
275
275
|
config = SDKConfig(
|
|
276
|
-
|
|
276
|
+
agent_id=str(_aid),
|
|
277
277
|
organization_id=data.get("org_id", ""),
|
|
278
278
|
plan=data.get("plan", "free"),
|
|
279
279
|
policies=policies,
|
|
280
|
+
agent_name=data.get("agent_name"),
|
|
281
|
+
agent_slug=data.get("agent_slug"),
|
|
282
|
+
environment=data.get("environment"),
|
|
283
|
+
group_id=str(_gid) if _gid else None,
|
|
280
284
|
)
|
|
281
|
-
|
|
282
|
-
|
|
285
|
+
|
|
286
|
+
gov = "governed" if config.has_policies else "ungoverned"
|
|
283
287
|
logger.info(
|
|
284
|
-
"
|
|
285
|
-
|
|
286
|
-
|
|
288
|
+
"Agent key validated",
|
|
289
|
+
agent_id=config.agent_id,
|
|
290
|
+
agent_name=config.agent_name,
|
|
291
|
+
governance=gov,
|
|
287
292
|
policy_version=policies.version,
|
|
288
293
|
)
|
|
289
294
|
_debug_bundle = os.getenv("CORTEXHUB_DEBUG_POLICY_BUNDLE", "").lower() in ("1", "true", "yes")
|
|
@@ -298,13 +303,13 @@ class BackendClient:
|
|
|
298
303
|
tool_names=[v.get("tool_name") for v in policy_map.values()],
|
|
299
304
|
)
|
|
300
305
|
if _debug_text or _debug_any:
|
|
301
|
-
logger.info("Policy bundle
|
|
306
|
+
logger.info("Policy bundle source (full)", policies=policies_str)
|
|
302
307
|
return True, config
|
|
303
308
|
else:
|
|
304
|
-
error_detail = response.json().get("detail", "Invalid
|
|
305
|
-
logger.warning("
|
|
309
|
+
error_detail = response.json().get("detail", "Invalid agent key")
|
|
310
|
+
logger.warning("Agent key validation failed", error=error_detail)
|
|
306
311
|
return False, None
|
|
307
|
-
|
|
312
|
+
|
|
308
313
|
except httpx.ConnectError:
|
|
309
314
|
logger.warning(
|
|
310
315
|
"Backend unreachable - running in offline observation mode",
|
|
@@ -312,7 +317,7 @@ class BackendClient:
|
|
|
312
317
|
)
|
|
313
318
|
return False, None
|
|
314
319
|
except Exception as e:
|
|
315
|
-
logger.error("
|
|
320
|
+
logger.error("Agent key validation error", error=str(e))
|
|
316
321
|
return False, None
|
|
317
322
|
|
|
318
323
|
def close(self):
|
|
@@ -323,8 +328,8 @@ class BackendClient:
|
|
|
323
328
|
def register_public_key(self, public_key_b64: str, fingerprint: str) -> bool:
|
|
324
329
|
"""Register the session's Ed25519 public key with the backend.
|
|
325
330
|
|
|
326
|
-
Called once on SDK init after
|
|
327
|
-
the public key against the
|
|
331
|
+
Called once on SDK init after agent-key validation. The backend stores
|
|
332
|
+
the public key against the agent key so it can verify span signatures
|
|
328
333
|
on receipt and serve it to external auditors.
|
|
329
334
|
|
|
330
335
|
Args:
|
|
@@ -334,7 +339,7 @@ class BackendClient:
|
|
|
334
339
|
Returns:
|
|
335
340
|
True if registered successfully, False on failure (non-fatal).
|
|
336
341
|
"""
|
|
337
|
-
if not self._client or not self.
|
|
342
|
+
if not self._client or not self.agent_key:
|
|
338
343
|
return False
|
|
339
344
|
try:
|
|
340
345
|
response = self._client.post(
|
|
@@ -356,7 +361,7 @@ class BackendClient:
|
|
|
356
361
|
|
|
357
362
|
def register_tools(self, tools: list[dict[str, Any]]) -> bool:
|
|
358
363
|
"""Register tool inventory with backend (best-effort)."""
|
|
359
|
-
if not self._client or not self.
|
|
364
|
+
if not self._client or not self.agent_key:
|
|
360
365
|
return False
|
|
361
366
|
if not tools:
|
|
362
367
|
return True
|