cortexhub 0.5.0__tar.gz → 0.5.2__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 (62) hide show
  1. {cortexhub-0.5.0 → cortexhub-0.5.2}/PKG-INFO +1 -1
  2. {cortexhub-0.5.0 → cortexhub-0.5.2}/pyproject.toml +1 -1
  3. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/backend/client.py +22 -2
  4. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/client.py +6 -6
  5. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/policy/effects.py +39 -53
  6. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/policy/evaluator.py +3 -3
  7. {cortexhub-0.5.0 → cortexhub-0.5.2}/.gitignore +0 -0
  8. {cortexhub-0.5.0 → cortexhub-0.5.2}/LICENSE +0 -0
  9. {cortexhub-0.5.0 → cortexhub-0.5.2}/README.md +0 -0
  10. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/__init__.py +0 -0
  11. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/audit/__init__.py +0 -0
  12. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/audit/events.py +0 -0
  13. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/backend/__init__.py +0 -0
  14. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/config.py +0 -0
  15. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/constants.py +0 -0
  16. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/context/__init__.py +0 -0
  17. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/context/enricher.py +0 -0
  18. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/errors.py +0 -0
  19. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/__init__.py +0 -0
  20. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/injection.py +0 -0
  21. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/__init__.py +0 -0
  22. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/LICENSE +0 -0
  23. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/LICENSES_SOURCES +0 -0
  24. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/README.md +0 -0
  25. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/accuracy.json +0 -0
  26. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/attribute_ruler/patterns +0 -0
  27. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/config.cfg +0 -0
  28. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/lemmatizer/lookups/lookups.bin +0 -0
  29. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/meta.json +0 -0
  30. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/ner/cfg +0 -0
  31. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/ner/model +0 -0
  32. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/ner/moves +0 -0
  33. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/parser/cfg +0 -0
  34. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/parser/model +0 -0
  35. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/parser/moves +0 -0
  36. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/senter/cfg +0 -0
  37. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/senter/model +0 -0
  38. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tagger/cfg +0 -0
  39. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tagger/model +0 -0
  40. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tok2vec/cfg +0 -0
  41. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tok2vec/model +0 -0
  42. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tokenizer +0 -0
  43. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/key2row +0 -0
  44. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/lookups.bin +0 -0
  45. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/strings.json +0 -0
  46. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/vectors +0 -0
  47. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/vectors.cfg +0 -0
  48. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/models/en_core_web_sm/meta.json +0 -0
  49. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/pii.py +0 -0
  50. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/guardrails/secrets.py +0 -0
  51. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/interceptors/__init__.py +0 -0
  52. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/interceptors/mcp.py +0 -0
  53. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/logging.py +0 -0
  54. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/policy/__init__.py +0 -0
  55. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/policy/loader.py +0 -0
  56. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/policy/models.py +0 -0
  57. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/policy/sync.py +0 -0
  58. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/signing.py +0 -0
  59. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/telemetry/__init__.py +0 -0
  60. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/telemetry/otel.py +0 -0
  61. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/tool.py +0 -0
  62. {cortexhub-0.5.0 → cortexhub-0.5.2}/src/cortexhub/version.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: cortexhub
3
- Version: 0.5.0
3
+ Version: 0.5.2
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
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "cortexhub"
3
- version = "0.5.0"
3
+ version = "0.5.2"
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"
@@ -11,6 +11,24 @@ import structlog
11
11
  logger = structlog.get_logger(__name__)
12
12
 
13
13
 
14
+ def _extract_error_message(body: Any) -> str | None:
15
+ """Return a human‑readable error message from either the standard
16
+ CortexHub envelope ``{"error": {"code","message","details"}}`` or a
17
+ legacy FastAPI ``{"detail": "..."}`` body. Returns ``None`` when neither
18
+ shape is present."""
19
+ if not isinstance(body, dict):
20
+ return None
21
+ err = body.get("error")
22
+ if isinstance(err, dict):
23
+ msg = err.get("message")
24
+ if isinstance(msg, str) and msg:
25
+ return msg
26
+ detail = body.get("detail")
27
+ if isinstance(detail, str) and detail:
28
+ return detail
29
+ return None
30
+
31
+
14
32
  @dataclass
15
33
  class CustomPattern:
16
34
  """Custom regex pattern for detection."""
@@ -381,9 +399,11 @@ class BackendClient:
381
399
  else:
382
400
  try:
383
401
  body = response.json()
384
- error_detail = body.get("detail", "Invalid agent key") if isinstance(body, dict) else str(body)
385
402
  except Exception:
386
- error_detail = (response.text or "")[:500] or f"HTTP {response.status_code}"
403
+ body = None
404
+ error_detail = _extract_error_message(body) or (
405
+ (response.text or "")[:500] or f"HTTP {response.status_code}"
406
+ )
387
407
  logger.warning("Agent key validation failed", error=error_detail)
388
408
  return False, None
389
409
 
@@ -1526,7 +1526,7 @@ class CortexHub:
1526
1526
  reasoning=decision.reasoning,
1527
1527
  )
1528
1528
 
1529
- if decision and decision.effect == Effect.ESCALATE:
1529
+ if decision and decision.effect == Effect.STEP_UP:
1530
1530
  context_hash = self._compute_context_hash(tool_name, policy_args)
1531
1531
 
1532
1532
  with self._approval_lock:
@@ -1540,7 +1540,7 @@ class CortexHub:
1540
1540
  context_hash=context_hash,
1541
1541
  )
1542
1542
  span.set_attribute("cortexhub.approval_id", approval_id)
1543
- decision = Decision.allow(
1543
+ decision = Decision.permit(
1544
1544
  reasoning=f"Approved (previously granted via {approval_id})",
1545
1545
  policy_id=decision.policy_id,
1546
1546
  policy_name=decision.policy_name,
@@ -1579,7 +1579,7 @@ class CortexHub:
1579
1579
  approval_id=pending_id,
1580
1580
  )
1581
1581
  span.set_attribute("cortexhub.approval_id", pending_id)
1582
- decision = Decision.allow(
1582
+ decision = Decision.permit(
1583
1583
  reasoning=f"Approved (auto-granted via {pending_id})",
1584
1584
  policy_id=decision.policy_id,
1585
1585
  policy_name=decision.policy_name,
@@ -1911,7 +1911,7 @@ class CortexHub:
1911
1911
  reasoning=decision.reasoning,
1912
1912
  )
1913
1913
 
1914
- if decision and decision.effect == Effect.ESCALATE:
1914
+ if decision and decision.effect == Effect.STEP_UP:
1915
1915
  context_hash = self._compute_context_hash(tool_name, policy_args)
1916
1916
 
1917
1917
  with self._approval_lock:
@@ -1924,7 +1924,7 @@ class CortexHub:
1924
1924
  context_hash=context_hash,
1925
1925
  )
1926
1926
  span.set_attribute("cortexhub.approval_id", approval_id)
1927
- decision = Decision.allow(
1927
+ decision = Decision.permit(
1928
1928
  reasoning=f"Approved (previously granted via {approval_id})",
1929
1929
  policy_id=decision.policy_id,
1930
1930
  policy_name=decision.policy_name,
@@ -1958,7 +1958,7 @@ class CortexHub:
1958
1958
  approval_id=pending_id,
1959
1959
  )
1960
1960
  span.set_attribute("cortexhub.approval_id", pending_id)
1961
- decision = Decision.allow(
1961
+ decision = Decision.permit(
1962
1962
  reasoning=f"Approved (auto-granted via {pending_id})",
1963
1963
  policy_id=decision.policy_id,
1964
1964
  policy_name=decision.policy_name,
@@ -1,7 +1,8 @@
1
- """Decision effects from policy evaluation.
1
+ """Policy decision effects — AARM vocabulary (R4).
2
2
 
3
- Critical: Determinism guarantee - Same AuthorizationRequest MUST always produce
4
- same Decision. This is essential for testing and auditability.
3
+ Every governed tool call resolves to exactly one of these five decisions.
4
+ The evaluator is deterministic: the same ``AuthorizationRequest`` MUST
5
+ always produce the same ``Decision``.
5
6
  """
6
7
 
7
8
  from enum import Enum
@@ -10,25 +11,17 @@ from pydantic import BaseModel
10
11
 
11
12
 
12
13
  class Effect(str, Enum):
13
- """Policy decision effect (v2: permit / deny / escalate in telemetry)."""
14
+ """The five AARM authorization decisions."""
14
15
 
15
16
  PERMIT = "permit"
16
17
  DENY = "deny"
17
- ESCALATE = "escalate"
18
- REDACT = "redact" # PII/secrets were redacted before LLM call
18
+ MODIFY = "modify"
19
+ STEP_UP = "step_up"
20
+ DEFER = "defer"
19
21
 
20
22
 
21
23
  class Decision(BaseModel):
22
- """Result of policy evaluation.
23
-
24
- Attributes:
25
- effect: The decision (PERMIT/DENY/ESCALATE)
26
- reasoning: Human-readable explanation
27
- policy_id: Which policy triggered this decision (if any)
28
- policy_name: Friendly policy name (if available)
29
- policy_effect: Policy effect metadata (if available)
30
- policy_decisions: All matching policy decisions (if available)
31
- """
24
+ """Result of policy evaluation."""
32
25
 
33
26
  effect: Effect
34
27
  reasoning: str
@@ -36,20 +29,23 @@ class Decision(BaseModel):
36
29
  policy_name: str | None = None
37
30
  policy_effect: str | None = None
38
31
  policy_decisions: list[dict[str, str | None]] | None = None
39
- # When approval expires or wait times out: "deny" (default) or "allow"
40
32
  policy_timeout_behavior: str | None = None
33
+ modified_args: dict[str, object] | None = None
41
34
 
42
- def is_allowed(self) -> bool:
43
- """Check if the decision allows execution (permit)."""
35
+ def is_permitted(self) -> bool:
44
36
  return self.effect == Effect.PERMIT
45
37
 
46
38
  def is_denied(self) -> bool:
47
- """Check if the decision denies execution."""
48
39
  return self.effect == Effect.DENY
49
40
 
41
+ def is_modified(self) -> bool:
42
+ return self.effect == Effect.MODIFY
43
+
50
44
  def requires_approval(self) -> bool:
51
- """Check if the decision requires approval (escalation)."""
52
- return self.effect == Effect.ESCALATE
45
+ return self.effect == Effect.STEP_UP
46
+
47
+ def is_deferred(self) -> bool:
48
+ return self.effect == Effect.DEFER
53
49
 
54
50
  @classmethod
55
51
  def permit(
@@ -59,8 +55,7 @@ class Decision(BaseModel):
59
55
  policy_name: str | None = None,
60
56
  policy_effect: str | None = None,
61
57
  policy_decisions: list[dict[str, str | None]] | None = None,
62
- ):
63
- """Create a PERMIT decision."""
58
+ ) -> "Decision":
64
59
  return cls(
65
60
  effect=Effect.PERMIT,
66
61
  reasoning=reasoning,
@@ -71,16 +66,16 @@ class Decision(BaseModel):
71
66
  )
72
67
 
73
68
  @classmethod
74
- def allow(
69
+ def deny(
75
70
  cls,
76
- reasoning: str = "Permitted by policy",
71
+ reasoning: str,
77
72
  policy_id: str | None = None,
78
73
  policy_name: str | None = None,
79
74
  policy_effect: str | None = None,
80
75
  policy_decisions: list[dict[str, str | None]] | None = None,
81
- ):
82
- """Deprecated alias for :meth:`permit` (same effect: ``permit``)."""
83
- return cls.permit(
76
+ ) -> "Decision":
77
+ return cls(
78
+ effect=Effect.DENY,
84
79
  reasoning=reasoning,
85
80
  policy_id=policy_id,
86
81
  policy_name=policy_name,
@@ -89,26 +84,25 @@ class Decision(BaseModel):
89
84
  )
90
85
 
91
86
  @classmethod
92
- def deny(
87
+ def modify(
93
88
  cls,
94
89
  reasoning: str,
90
+ modified_args: dict[str, object],
95
91
  policy_id: str | None = None,
96
92
  policy_name: str | None = None,
97
- policy_effect: str | None = None,
98
- policy_decisions: list[dict[str, str | None]] | None = None,
99
- ):
100
- """Create a DENY decision."""
93
+ ) -> "Decision":
94
+ """Execute the tool with ``modified_args`` instead of the original
95
+ arguments (e.g. PII redacted, values clamped)."""
101
96
  return cls(
102
- effect=Effect.DENY,
97
+ effect=Effect.MODIFY,
103
98
  reasoning=reasoning,
104
99
  policy_id=policy_id,
105
100
  policy_name=policy_name,
106
- policy_effect=policy_effect,
107
- policy_decisions=policy_decisions,
101
+ modified_args=modified_args,
108
102
  )
109
103
 
110
104
  @classmethod
111
- def escalate(
105
+ def step_up(
112
106
  cls,
113
107
  reasoning: str,
114
108
  policy_id: str | None = None,
@@ -116,10 +110,10 @@ class Decision(BaseModel):
116
110
  policy_effect: str | None = None,
117
111
  policy_decisions: list[dict[str, str | None]] | None = None,
118
112
  policy_timeout_behavior: str | None = None,
119
- ):
120
- """Create an ESCALATE decision."""
113
+ ) -> "Decision":
114
+ """Require a human approval before the tool runs."""
121
115
  return cls(
122
- effect=Effect.ESCALATE,
116
+ effect=Effect.STEP_UP,
123
117
  reasoning=reasoning,
124
118
  policy_id=policy_id,
125
119
  policy_name=policy_name,
@@ -129,24 +123,16 @@ class Decision(BaseModel):
129
123
  )
130
124
 
131
125
  @classmethod
132
- def redact(
126
+ def defer(
133
127
  cls,
134
128
  reasoning: str,
135
129
  policy_id: str | None = None,
136
130
  policy_name: str | None = None,
137
- policy_effect: str | None = None,
138
- policy_decisions: list[dict[str, str | None]] | None = None,
139
- ):
140
- """Create a REDACT decision (PII/secrets were redacted before execution)."""
131
+ ) -> "Decision":
132
+ """Suspend the decision pending more context."""
141
133
  return cls(
142
- effect=Effect.REDACT,
134
+ effect=Effect.DEFER,
143
135
  reasoning=reasoning,
144
136
  policy_id=policy_id,
145
137
  policy_name=policy_name,
146
- policy_effect=policy_effect,
147
- policy_decisions=policy_decisions,
148
138
  )
149
-
150
- def is_redacted(self) -> bool:
151
- """Check if the decision resulted in redaction."""
152
- return self.effect == Effect.REDACT
@@ -128,7 +128,7 @@ class PolicyEvaluator:
128
128
  policy_decisions=[],
129
129
  )
130
130
  if self.default_behavior == "escalate":
131
- return Decision.escalate(
131
+ return Decision.step_up(
132
132
  f"Tool '{tool_name}' requires approval (unknown tool)",
133
133
  policy_id="default",
134
134
  policy_decisions=[],
@@ -286,7 +286,7 @@ class PolicyEvaluator:
286
286
  if result.decision == cedar_module.Decision.Deny:
287
287
  # Engine Deny: one or more forbid policies matched. Never allow, even when reasons are empty.
288
288
  if not result.diagnostics.reasons:
289
- return Decision.escalate(
289
+ return Decision.step_up(
290
290
  "Tool requires approval (policy condition matched)",
291
291
  policy_id="policy",
292
292
  policy_decisions=policy_decisions,
@@ -318,7 +318,7 @@ class PolicyEvaluator:
318
318
  timeout_behavior = "deny"
319
319
  if first_reason and policy_map:
320
320
  timeout_behavior = (policy_map.get(first_reason, {}).get("approval_timeout_behavior") or "deny").lower()
321
- return Decision.escalate(
321
+ return Decision.step_up(
322
322
  reasoning="Approval required by policy",
323
323
  policy_id=policy_id,
324
324
  policy_name=policy_name,
File without changes
File without changes
File without changes