cortexhub 0.5.1__tar.gz → 0.5.3__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 (64) hide show
  1. {cortexhub-0.5.1 → cortexhub-0.5.3}/PKG-INFO +1 -1
  2. {cortexhub-0.5.1 → cortexhub-0.5.3}/pyproject.toml +1 -1
  3. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/client.py +149 -29
  4. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/constants.py +23 -2
  5. cortexhub-0.5.3/src/cortexhub/policy/effects.py +138 -0
  6. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/policy/evaluator.py +7 -4
  7. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/signing.py +1 -1
  8. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/telemetry/otel.py +0 -25
  9. cortexhub-0.5.3/src/cortexhub/version.py +27 -0
  10. cortexhub-0.5.1/src/cortexhub/policy/effects.py +0 -249
  11. cortexhub-0.5.1/src/cortexhub/version.py +0 -15
  12. {cortexhub-0.5.1 → cortexhub-0.5.3}/.gitignore +0 -0
  13. {cortexhub-0.5.1 → cortexhub-0.5.3}/LICENSE +0 -0
  14. {cortexhub-0.5.1 → cortexhub-0.5.3}/README.md +0 -0
  15. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/__init__.py +0 -0
  16. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/audit/__init__.py +0 -0
  17. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/audit/events.py +0 -0
  18. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/backend/__init__.py +0 -0
  19. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/backend/client.py +0 -0
  20. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/config.py +0 -0
  21. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/context/__init__.py +0 -0
  22. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/context/enricher.py +0 -0
  23. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/errors.py +0 -0
  24. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/__init__.py +0 -0
  25. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/injection.py +0 -0
  26. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/__init__.py +0 -0
  27. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/LICENSE +0 -0
  28. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/LICENSES_SOURCES +0 -0
  29. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/README.md +0 -0
  30. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/accuracy.json +0 -0
  31. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/attribute_ruler/patterns +0 -0
  32. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/config.cfg +0 -0
  33. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/lemmatizer/lookups/lookups.bin +0 -0
  34. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/meta.json +0 -0
  35. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/ner/cfg +0 -0
  36. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/ner/model +0 -0
  37. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/ner/moves +0 -0
  38. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/parser/cfg +0 -0
  39. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/parser/model +0 -0
  40. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/parser/moves +0 -0
  41. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/senter/cfg +0 -0
  42. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/senter/model +0 -0
  43. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tagger/cfg +0 -0
  44. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tagger/model +0 -0
  45. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tok2vec/cfg +0 -0
  46. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tok2vec/model +0 -0
  47. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tokenizer +0 -0
  48. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/key2row +0 -0
  49. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/lookups.bin +0 -0
  50. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/strings.json +0 -0
  51. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/vectors +0 -0
  52. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/vectors.cfg +0 -0
  53. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/meta.json +0 -0
  54. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/pii.py +0 -0
  55. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/guardrails/secrets.py +0 -0
  56. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/interceptors/__init__.py +0 -0
  57. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/interceptors/mcp.py +0 -0
  58. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/logging.py +0 -0
  59. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/policy/__init__.py +0 -0
  60. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/policy/loader.py +0 -0
  61. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/policy/models.py +0 -0
  62. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/policy/sync.py +0 -0
  63. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/telemetry/__init__.py +0 -0
  64. {cortexhub-0.5.1 → cortexhub-0.5.3}/src/cortexhub/tool.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: cortexhub
3
- Version: 0.5.1
3
+ Version: 0.5.3
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.1"
3
+ version = "0.5.3"
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"
@@ -1,24 +1,30 @@
1
- """CortexHub client - main SDK entrypoint.
1
+ """CortexHub client — main SDK entrypoint.
2
2
 
3
- SDK RESPONSIBILITIES (keep it simple)
4
- ======================================
5
- 1. **Telemetry redaction (privacy)**
6
- Controlled by the project Privacy setting in CortexHub (On = redact, Off = raw).
7
- The SDK uses the value from the API on validate/refresh; no SDK-level override.
3
+ SDK responsibilities
4
+ ====================
5
+ 1. Telemetry redaction (privacy). Controlled by the project Privacy setting in
6
+ CortexHub (On = redact, Off = raw). The SDK uses the value from the API on
7
+ validate/refresh; no SDK-level override.
8
8
 
9
- 2. **Guardrail redaction on LLM input/output**
10
- Apply guardrail config to actual LLM prompt and response (detect/redact PII, secrets, injection).
11
- Send a single input/output breakdown as span attributes (no legacy span events).
9
+ 2. Guardrail redaction on LLM input/output. Apply guardrail config to the
10
+ actual LLM prompt and response (detect/redact PII, secrets, injection).
11
+ Emit a single input/output breakdown as span attributes.
12
12
 
13
- 3. **Policy evaluation and enforcement**
14
- Evaluate synced policies before tool/LLM execution; enforce allow/deny/escalate/redact; handle approvals.
13
+ 3. Policy evaluation and enforcement. Evaluate synced policies before tool or
14
+ LLM execution and enforce the AARM decision vocabulary —
15
+ ``permit / deny / step_up / modify / defer`` — handling approvals when a
16
+ policy resolves to ``step_up``.
15
17
 
16
- MODE
18
+ Mode
17
19
  ====
18
20
  - No policies from backend → observation (record + detect, no block).
19
- - Policies from backend → enforcement (evaluate + block/allow/escalate/redact).
21
+ - Policies from backend → enforcement (evaluate + permit/deny/step_up; MODIFY
22
+ and DEFER raise ``PolicyViolationError`` in-process because the adapter
23
+ closure has already captured the original tool arguments — use the hosted
24
+ MCP gateway for arg-rewriting MODIFY policies).
20
25
 
21
- Architecture: adapters call execute_governed_tool / execute_governed_llm_call; SDK creates OTLP spans and enforces policy.
26
+ Architecture: adapters call ``execute_governed_tool`` / ``execute_governed_llm_call``;
27
+ the SDK creates OTLP spans and enforces policy.
22
28
  """
23
29
 
24
30
  import contextvars
@@ -662,7 +668,16 @@ class CortexHub:
662
668
 
663
669
  def _attach_run_session_attrs(self, span: Any) -> None:
664
670
  """Attach cortexhub.run.id and optionally cortexhub.session.id to a span.
665
- Every run/llm/tool span must call this. Run ID when in a run; session ID only when inside cx.session()."""
671
+
672
+ Every run/llm/tool span must call this. Run ID when in a run;
673
+ session ID only when inside cx.session().
674
+
675
+ ``cortexhub.governance.mode`` is deliberately **not** set here —
676
+ the tool-span emitter sets it per-tool so the Decisions audit
677
+ view can tell a governed tool from an ungoverned one on the same
678
+ agent. The old agent-level "has any policies at all" flag was
679
+ misleading for any agent with a mix.
680
+ """
666
681
  run_id = _run_id_var.get()
667
682
  if run_id is not None:
668
683
  span.set_attribute(ATTR_RUN_ID, run_id)
@@ -677,11 +692,6 @@ class CortexHub:
677
692
  span.set_attribute("cortexhub.mode", "sdk")
678
693
  if getattr(self, "_framework", None):
679
694
  span.set_attribute("cortexhub.framework", self._framework)
680
- sc = getattr(self, "_sdk_config", None)
681
- span.set_attribute(
682
- "cortexhub.governance.mode",
683
- "governed" if (sc and sc.has_policies) else "ungoverned",
684
- )
685
695
 
686
696
  def _normalize_api_url(self, url: str) -> str:
687
697
  base_url = url.rstrip("/")
@@ -981,6 +991,16 @@ class CortexHub:
981
991
  default_behavior = getattr(
982
992
  sdk_config.policies, "default_behavior", "allow_and_log"
983
993
  ) or "allow_and_log"
994
+ # Bucket policies and tool classifications arrive on every fresh
995
+ # validate response; persisting them here keeps the offline cache
996
+ # aligned with what the online path sees. Without this the SDK
997
+ # falls back to tool-specific policies only and misses bucket
998
+ # coverage when the backend is unreachable.
999
+ bucket_policies = getattr(sdk_config.policies, "bucket_policies", None) or {}
1000
+ tool_classifications = (
1001
+ getattr(sdk_config.policies, "tool_classifications", None) or {}
1002
+ )
1003
+ tool_policies = getattr(sdk_config.policies, "tool_policies", None) or []
984
1004
  bundle = {
985
1005
  "version": sdk_config.policies.version,
986
1006
  "synced_at": datetime.utcnow().isoformat(),
@@ -989,6 +1009,9 @@ class CortexHub:
989
1009
  "schema": sdk_config.policies.schema or {},
990
1010
  "default_behavior": default_behavior,
991
1011
  "policy_map": policy_map,
1012
+ "bucket_policies": bucket_policies,
1013
+ "tool_classifications": tool_classifications,
1014
+ "tool_policies": tool_policies,
992
1015
  "agent_id": sdk_config.agent_id,
993
1016
  "project_id": sdk_config.agent_id,
994
1017
  }
@@ -1426,6 +1449,25 @@ class CortexHub:
1426
1449
  span.set_attribute("cortexhub.tool.name", tool_name)
1427
1450
  span.set_attribute("cortexhub.tool.framework", framework)
1428
1451
  span.set_attribute("cortexhub.tool.governed", _this_tool_governed)
1452
+ # Per-tool governance mode — matches the MCP gateway emitter.
1453
+ # The ingest path uses this to decide whether to write an
1454
+ # EnforcementDecisionDocument.
1455
+ span.set_attribute(
1456
+ "cortexhub.governance.mode",
1457
+ "governed" if _this_tool_governed else "ungoverned",
1458
+ )
1459
+ # Default decision. Any later policy evaluation overrides this
1460
+ # with ``deny`` / ``step_up`` / ``modify`` / ``defer`` when a
1461
+ # user rule applies. Governed tools default to ``permit``
1462
+ # because that's the outcome absent a rejecting rule; they
1463
+ # upgrade to a more specific effect only if evaluation finds
1464
+ # one. Ungoverned tools get ``ungoverned`` so operators can
1465
+ # tell apart "no policy applies" from "policy said permit".
1466
+ # Gateway has the same semantics.
1467
+ span.set_attribute(
1468
+ "cortexhub.policy.decision",
1469
+ "permit" if _this_tool_governed else "ungoverned",
1470
+ )
1429
1471
 
1430
1472
  # Delegation provenance — lets the backend reconstruct orchestration scope
1431
1473
  if self.parent_agent_id:
@@ -1526,7 +1568,7 @@ class CortexHub:
1526
1568
  reasoning=decision.reasoning,
1527
1569
  )
1528
1570
 
1529
- if decision and decision.effect == Effect.ESCALATE:
1571
+ if decision and decision.effect == Effect.STEP_UP:
1530
1572
  context_hash = self._compute_context_hash(tool_name, policy_args)
1531
1573
 
1532
1574
  with self._approval_lock:
@@ -1540,7 +1582,7 @@ class CortexHub:
1540
1582
  context_hash=context_hash,
1541
1583
  )
1542
1584
  span.set_attribute("cortexhub.approval_id", approval_id)
1543
- decision = Decision.allow(
1585
+ decision = Decision.permit(
1544
1586
  reasoning=f"Approved (previously granted via {approval_id})",
1545
1587
  policy_id=decision.policy_id,
1546
1588
  policy_name=decision.policy_name,
@@ -1579,7 +1621,7 @@ class CortexHub:
1579
1621
  approval_id=pending_id,
1580
1622
  )
1581
1623
  span.set_attribute("cortexhub.approval_id", pending_id)
1582
- decision = Decision.allow(
1624
+ decision = Decision.permit(
1583
1625
  reasoning=f"Approved (auto-granted via {pending_id})",
1584
1626
  policy_id=decision.policy_id,
1585
1627
  policy_name=decision.policy_name,
@@ -1701,13 +1743,51 @@ class CortexHub:
1701
1743
  )
1702
1744
  span.set_attribute("cortexhub.policy.decision", decision.effect.value)
1703
1745
 
1746
+ # MODIFY and DEFER must not silently fall through to
1747
+ # ``call_original()``. The in‑process closure already
1748
+ # captured the original args, so we can't safely rewrite
1749
+ # them here — if a policy asks for MODIFY we block the
1750
+ # call with a clear reason instead of running with the
1751
+ # unmodified args. DEFER means the decision needs more
1752
+ # context; surface that to the caller so their code can
1753
+ # supply it and retry rather than executing blindly.
1754
+ if decision and decision.effect in (Effect.MODIFY, Effect.DEFER):
1755
+ span.add_event(
1756
+ "policy.decision",
1757
+ attributes=self._decision_event_attributes(decision),
1758
+ )
1759
+ span.set_status(Status(StatusCode.ERROR, decision.reasoning))
1760
+ span.set_attribute("cortexhub.policy.decision", decision.effect.value)
1761
+ if decision.effect == Effect.MODIFY:
1762
+ raise PolicyViolationError(
1763
+ (
1764
+ f"Policy requires MODIFY for '{tool_name}' but in‑process SDK "
1765
+ "governance cannot rewrite tool arguments today. Use the hosted "
1766
+ "MCP gateway for MODIFY policies, or convert this rule to a deny "
1767
+ "or step‑up policy."
1768
+ ),
1769
+ policy_id=decision.policy_id,
1770
+ reasoning=decision.reasoning,
1771
+ )
1772
+ raise PolicyViolationError(
1773
+ (
1774
+ f"Policy deferred the decision for '{tool_name}' "
1775
+ f"({decision.reasoning}). Supply the missing context and retry."
1776
+ ),
1777
+ policy_id=decision.policy_id,
1778
+ reasoning=decision.reasoning,
1779
+ )
1780
+
1704
1781
  # Step 5: Execute tool
1705
1782
  exec_start = time.perf_counter()
1706
1783
  result = call_original()
1707
1784
  exec_latency_ms = (time.perf_counter() - exec_start) * 1000
1708
1785
 
1709
- # Step 6: Record success result on span
1786
+ # Step 6: Record success result on span. ``cortexhub.latency_ms``
1787
+ # matches the MCP gateway key so the Activity / Runs UI
1788
+ # doesn't need to know which path produced the span.
1710
1789
  span.set_attribute("cortexhub.result.success", True)
1790
+ span.set_attribute("cortexhub.latency_ms", exec_latency_ms)
1711
1791
  span.set_status(Status(StatusCode.OK))
1712
1792
 
1713
1793
  # Telemetry: always send result; redact when privacy mode is redacted
@@ -1829,6 +1909,17 @@ class CortexHub:
1829
1909
  span.set_attribute("cortexhub.tool.name", tool_name)
1830
1910
  span.set_attribute("cortexhub.tool.framework", framework)
1831
1911
  span.set_attribute("cortexhub.tool.governed", _this_tool_governed_a)
1912
+ # Per-tool governance mode + default decision — see the sync
1913
+ # path for the full rationale. Keeps both execution paths
1914
+ # emitting the same shape so the ingest pipeline is path-agnostic.
1915
+ span.set_attribute(
1916
+ "cortexhub.governance.mode",
1917
+ "governed" if _this_tool_governed_a else "ungoverned",
1918
+ )
1919
+ span.set_attribute(
1920
+ "cortexhub.policy.decision",
1921
+ "permit" if _this_tool_governed_a else "ungoverned",
1922
+ )
1832
1923
 
1833
1924
  if tool_description:
1834
1925
  span.set_attribute("cortexhub.tool.description", tool_description)
@@ -1911,7 +2002,7 @@ class CortexHub:
1911
2002
  reasoning=decision.reasoning,
1912
2003
  )
1913
2004
 
1914
- if decision and decision.effect == Effect.ESCALATE:
2005
+ if decision and decision.effect == Effect.STEP_UP:
1915
2006
  context_hash = self._compute_context_hash(tool_name, policy_args)
1916
2007
 
1917
2008
  with self._approval_lock:
@@ -1924,7 +2015,7 @@ class CortexHub:
1924
2015
  context_hash=context_hash,
1925
2016
  )
1926
2017
  span.set_attribute("cortexhub.approval_id", approval_id)
1927
- decision = Decision.allow(
2018
+ decision = Decision.permit(
1928
2019
  reasoning=f"Approved (previously granted via {approval_id})",
1929
2020
  policy_id=decision.policy_id,
1930
2021
  policy_name=decision.policy_name,
@@ -1958,7 +2049,7 @@ class CortexHub:
1958
2049
  approval_id=pending_id,
1959
2050
  )
1960
2051
  span.set_attribute("cortexhub.approval_id", pending_id)
1961
- decision = Decision.allow(
2052
+ decision = Decision.permit(
1962
2053
  reasoning=f"Approved (auto-granted via {pending_id})",
1963
2054
  policy_id=decision.policy_id,
1964
2055
  policy_name=decision.policy_name,
@@ -2075,15 +2166,44 @@ class CortexHub:
2075
2166
  )
2076
2167
  span.set_attribute("cortexhub.policy.decision", decision.effect.value)
2077
2168
 
2169
+ # MODIFY / DEFER handling — see the sync path for rationale.
2170
+ if decision and decision.effect in (Effect.MODIFY, Effect.DEFER):
2171
+ span.add_event(
2172
+ "policy.decision",
2173
+ attributes=self._decision_event_attributes(decision),
2174
+ )
2175
+ span.set_status(Status(StatusCode.ERROR, decision.reasoning))
2176
+ span.set_attribute("cortexhub.policy.decision", decision.effect.value)
2177
+ if decision.effect == Effect.MODIFY:
2178
+ raise PolicyViolationError(
2179
+ (
2180
+ f"Policy requires MODIFY for '{tool_name}' but in‑process SDK "
2181
+ "governance cannot rewrite tool arguments today. Use the hosted "
2182
+ "MCP gateway for MODIFY policies, or convert this rule to a deny "
2183
+ "or step‑up policy."
2184
+ ),
2185
+ policy_id=decision.policy_id,
2186
+ reasoning=decision.reasoning,
2187
+ )
2188
+ raise PolicyViolationError(
2189
+ (
2190
+ f"Policy deferred the decision for '{tool_name}' "
2191
+ f"({decision.reasoning}). Supply the missing context and retry."
2192
+ ),
2193
+ policy_id=decision.policy_id,
2194
+ reasoning=decision.reasoning,
2195
+ )
2196
+
2078
2197
  # Step 5: Execute tool (async)
2079
2198
  exec_start = time.perf_counter()
2080
2199
  result = await call_original()
2081
2200
  exec_latency_ms = (time.perf_counter() - exec_start) * 1000
2082
2201
 
2083
- # Step 6: Record success result on span
2202
+ # Step 6: Record success result on span — unified key with the
2203
+ # sync path and the MCP gateway emitter.
2084
2204
  span.set_attribute("cortexhub.result.success", True)
2085
2205
  span.set_status(Status(StatusCode.OK))
2086
- span.set_attribute("cortexhub.result.latency_ms", exec_latency_ms)
2206
+ span.set_attribute("cortexhub.latency_ms", exec_latency_ms)
2087
2207
 
2088
2208
  # Telemetry: always send result; redact when privacy mode is redacted
2089
2209
  if result is not None:
@@ -42,7 +42,12 @@ ATTR_TOOL_ARG_SCHEMA = "cortexhub.tool.arg_schema"
42
42
  # Result attributes (tool and LLM spans)
43
43
  # ---------------------------------------------------------------------------
44
44
  ATTR_RESULT_SUCCESS = "cortexhub.result.success"
45
- ATTR_RESULT_LATENCY_MS = "cortexhub.result.latency_ms"
45
+ # Unified latency key shared with the MCP gateway's ``insert_studio_tool_span``
46
+ # so the Sessions/Runs/Activity UIs only need to look at one attribute.
47
+ # (Older SDK releases emitted ``cortexhub.result.latency_ms`` — the backend
48
+ # ingest tolerates both for a transition window but new spans stick to this
49
+ # single key.)
50
+ ATTR_RESULT_LATENCY_MS = "cortexhub.latency_ms"
46
51
  ATTR_ERROR_MESSAGE = "cortexhub.error.message"
47
52
 
48
53
  # ---------------------------------------------------------------------------
@@ -85,13 +90,29 @@ ATTR_REDACTION_SECRETS_TYPES = "cortexhub.redaction.secrets_types"
85
90
 
86
91
  # ---------------------------------------------------------------------------
87
92
  # Policy decision attributes
88
- # ---------------------------------------------------------------------------
93
+ #
94
+ # ``cortexhub.policy.decision`` is emitted on every tool span so the audit
95
+ # pipeline always produces an EnforcementDecisionDocument — including for
96
+ # ungoverned permits (the value is simply ``"ungoverned"`` in that case).
97
+ # This matches the MCP gateway, which has always emitted one decision per
98
+ # tool invocation. Keeping both paths consistent is the whole point of the
99
+ # ingest unification — see ``backend/app/services/span_ingest.py``.
100
+ # ---------------------------------------------------------------------------
101
+ ATTR_POLICY_DECISION = "cortexhub.policy.decision"
89
102
  ATTR_POLICY_EFFECT = "cortexhub.policy.effect"
90
103
  ATTR_POLICY_ID = "cortexhub.policy.id"
91
104
  ATTR_POLICY_NAME = "cortexhub.policy.name"
92
105
  ATTR_POLICY_REASONING = "cortexhub.policy.reasoning"
93
106
  ATTR_POLICY_LATENCY_MS = "cortexhub.policy.latency_ms"
94
107
 
108
+ # Per-tool governance mode. Matches the gateway emitter: ``"governed"`` when
109
+ # a policy row exists for this (agent, tool) pair, ``"ungoverned"`` otherwise.
110
+ # Previously the SDK stamped an agent-level "has any policies at all" flag
111
+ # here, which meant a single agent with mixed governed/ungoverned tools
112
+ # reported the same governance.mode on every span and the Decisions view
113
+ # couldn't distinguish them.
114
+ ATTR_GOVERNANCE_MODE = "cortexhub.governance.mode"
115
+
95
116
  # ---------------------------------------------------------------------------
96
117
  # Decision signing attributes (Ed25519 tamper-evident proof)
97
118
  #
@@ -0,0 +1,138 @@
1
+ """Policy decision effects — AARM vocabulary (R4).
2
+
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``.
6
+ """
7
+
8
+ from enum import Enum
9
+
10
+ from pydantic import BaseModel
11
+
12
+
13
+ class Effect(str, Enum):
14
+ """The five AARM authorization decisions."""
15
+
16
+ PERMIT = "permit"
17
+ DENY = "deny"
18
+ MODIFY = "modify"
19
+ STEP_UP = "step_up"
20
+ DEFER = "defer"
21
+
22
+
23
+ class Decision(BaseModel):
24
+ """Result of policy evaluation."""
25
+
26
+ effect: Effect
27
+ reasoning: str
28
+ policy_id: str | None = None
29
+ policy_name: str | None = None
30
+ policy_effect: str | None = None
31
+ policy_decisions: list[dict[str, str | None]] | None = None
32
+ policy_timeout_behavior: str | None = None
33
+ modified_args: dict[str, object] | None = None
34
+
35
+ def is_permitted(self) -> bool:
36
+ return self.effect == Effect.PERMIT
37
+
38
+ def is_denied(self) -> bool:
39
+ return self.effect == Effect.DENY
40
+
41
+ def is_modified(self) -> bool:
42
+ return self.effect == Effect.MODIFY
43
+
44
+ def requires_approval(self) -> bool:
45
+ return self.effect == Effect.STEP_UP
46
+
47
+ def is_deferred(self) -> bool:
48
+ return self.effect == Effect.DEFER
49
+
50
+ @classmethod
51
+ def permit(
52
+ cls,
53
+ reasoning: str = "Permitted by policy",
54
+ policy_id: str | None = None,
55
+ policy_name: str | None = None,
56
+ policy_effect: str | None = None,
57
+ policy_decisions: list[dict[str, str | None]] | None = None,
58
+ ) -> "Decision":
59
+ return cls(
60
+ effect=Effect.PERMIT,
61
+ reasoning=reasoning,
62
+ policy_id=policy_id,
63
+ policy_name=policy_name,
64
+ policy_effect=policy_effect,
65
+ policy_decisions=policy_decisions,
66
+ )
67
+
68
+ @classmethod
69
+ def deny(
70
+ cls,
71
+ reasoning: str,
72
+ policy_id: str | None = None,
73
+ policy_name: str | None = None,
74
+ policy_effect: str | None = None,
75
+ policy_decisions: list[dict[str, str | None]] | None = None,
76
+ ) -> "Decision":
77
+ return cls(
78
+ effect=Effect.DENY,
79
+ reasoning=reasoning,
80
+ policy_id=policy_id,
81
+ policy_name=policy_name,
82
+ policy_effect=policy_effect,
83
+ policy_decisions=policy_decisions,
84
+ )
85
+
86
+ @classmethod
87
+ def modify(
88
+ cls,
89
+ reasoning: str,
90
+ modified_args: dict[str, object],
91
+ policy_id: str | None = None,
92
+ policy_name: str | None = None,
93
+ ) -> "Decision":
94
+ """Execute the tool with ``modified_args`` instead of the original
95
+ arguments (e.g. PII redacted, values clamped)."""
96
+ return cls(
97
+ effect=Effect.MODIFY,
98
+ reasoning=reasoning,
99
+ policy_id=policy_id,
100
+ policy_name=policy_name,
101
+ modified_args=modified_args,
102
+ )
103
+
104
+ @classmethod
105
+ def step_up(
106
+ cls,
107
+ reasoning: str,
108
+ policy_id: str | None = None,
109
+ policy_name: str | None = None,
110
+ policy_effect: str | None = None,
111
+ policy_decisions: list[dict[str, str | None]] | None = None,
112
+ policy_timeout_behavior: str | None = None,
113
+ ) -> "Decision":
114
+ """Require a human approval before the tool runs."""
115
+ return cls(
116
+ effect=Effect.STEP_UP,
117
+ reasoning=reasoning,
118
+ policy_id=policy_id,
119
+ policy_name=policy_name,
120
+ policy_effect=policy_effect,
121
+ policy_decisions=policy_decisions,
122
+ policy_timeout_behavior=policy_timeout_behavior,
123
+ )
124
+
125
+ @classmethod
126
+ def defer(
127
+ cls,
128
+ reasoning: str,
129
+ policy_id: str | None = None,
130
+ policy_name: str | None = None,
131
+ ) -> "Decision":
132
+ """Suspend the decision pending more context."""
133
+ return cls(
134
+ effect=Effect.DEFER,
135
+ reasoning=reasoning,
136
+ policy_id=policy_id,
137
+ policy_name=policy_name,
138
+ )
@@ -70,7 +70,10 @@ class PolicyEvaluator:
70
70
  request: Authorization request to evaluate
71
71
 
72
72
  Returns:
73
- Decision (ALLOW/DENY/ESCALATE)
73
+ ``Decision`` carrying one of the AARM effects — ``permit``,
74
+ ``deny``, or ``step_up``. ``modify`` and ``defer`` are emitted by
75
+ the control plane only; the in-process evaluator does not produce
76
+ them today.
74
77
  """
75
78
  start_time = time.perf_counter()
76
79
 
@@ -128,7 +131,7 @@ class PolicyEvaluator:
128
131
  policy_decisions=[],
129
132
  )
130
133
  if self.default_behavior == "escalate":
131
- return Decision.escalate(
134
+ return Decision.step_up(
132
135
  f"Tool '{tool_name}' requires approval (unknown tool)",
133
136
  policy_id="default",
134
137
  policy_decisions=[],
@@ -286,7 +289,7 @@ class PolicyEvaluator:
286
289
  if result.decision == cedar_module.Decision.Deny:
287
290
  # Engine Deny: one or more forbid policies matched. Never allow, even when reasons are empty.
288
291
  if not result.diagnostics.reasons:
289
- return Decision.escalate(
292
+ return Decision.step_up(
290
293
  "Tool requires approval (policy condition matched)",
291
294
  policy_id="policy",
292
295
  policy_decisions=policy_decisions,
@@ -318,7 +321,7 @@ class PolicyEvaluator:
318
321
  timeout_behavior = "deny"
319
322
  if first_reason and policy_map:
320
323
  timeout_behavior = (policy_map.get(first_reason, {}).get("approval_timeout_behavior") or "deny").lower()
321
- return Decision.escalate(
324
+ return Decision.step_up(
322
325
  reasoning="Approval required by policy",
323
326
  policy_id=policy_id,
324
327
  policy_name=policy_name,
@@ -14,7 +14,7 @@ Canonical payload (what is signed):
14
14
  "name": "tool.invoke" | "llm.call",
15
15
  "agent_id": "<agent id>",
16
16
  "tool_name": "<tool name>",
17
- "decision_effect": "allow" | "deny" | "escalate" | "redact" | "",
17
+ "decision_effect": "permit" | "deny" | "step_up" | "modify" | "defer" | "",
18
18
  "policy_id": "<policy id or empty>",
19
19
  "start_time_unix_nano": <int>
20
20
  }
@@ -397,31 +397,6 @@ class OTelTelemetry:
397
397
  }
398
398
  )
399
399
 
400
- def add_policy_decision(
401
- self,
402
- span: Span,
403
- effect: str,
404
- policy_id: str | None = None,
405
- reasoning: str | None = None,
406
- ) -> None:
407
- """Add a policy decision as a span event.
408
-
409
- Args:
410
- span: The span to add the event to
411
- effect: Policy effect ("allow", "deny", "escalate")
412
- policy_id: ID of the policy that matched
413
- reasoning: Explanation for the decision
414
- """
415
- attributes = {
416
- "policy.effect": effect,
417
- }
418
- if policy_id:
419
- attributes["policy.id"] = policy_id
420
- if reasoning:
421
- attributes["policy.reasoning"] = reasoning
422
-
423
- span.add_event("policy.decision", attributes=attributes)
424
-
425
400
  def shutdown(self) -> None:
426
401
  """Flush pending spans and shutdown."""
427
402
  if hasattr(self.provider, 'shutdown'):
@@ -0,0 +1,27 @@
1
+ """Version information for CortexHub SDK.
2
+
3
+ Kept in sync with ``pyproject.toml``'s ``project.version``. We prefer
4
+ the installed package metadata when available — that's the
5
+ ground‑truth for a pip/uv install — and fall back to the baked‑in
6
+ string for editable installs, frozen binaries (pyinstaller), and
7
+ source checkouts where ``importlib.metadata`` has nothing to return.
8
+ The old fallback of ``"0.0.0"`` made downstream code that compared
9
+ versions (``parse(cortexhub.__version__) >= parse("0.5")``) behave
10
+ incorrectly in those environments.
11
+ """
12
+
13
+ from importlib.metadata import PackageNotFoundError, version
14
+
15
+ __fallback_version__ = "0.5.3"
16
+
17
+
18
+ def _resolve_version() -> str:
19
+ try:
20
+ return version("cortexhub")
21
+ except PackageNotFoundError:
22
+ return __fallback_version__
23
+
24
+
25
+ __version__ = _resolve_version()
26
+
27
+ __all__ = ["__version__"]
@@ -1,249 +0,0 @@
1
- """Decision effects from policy evaluation.
2
-
3
- Vocabulary follows the five AARM decisions:
4
-
5
- * ``permit`` — allow the action as‑is.
6
- * ``deny`` — block the action.
7
- * ``modify`` — allow the action with rewritten arguments (PII redaction,
8
- value clamps, field removal). ``redact`` is a narrower
9
- synonym kept for dashboards that filter by it.
10
- * ``step_up`` — require human approval before the action runs.
11
- ``escalate`` is the historical SDK name and remains a
12
- synonym so existing integrations keep working.
13
- * ``defer`` — suspend the decision pending additional context (rarely
14
- emitted by the SDK today; included so telemetry
15
- vocabulary matches AARM end‑to‑end).
16
-
17
- The evaluator is deterministic: the same ``AuthorizationRequest`` MUST
18
- always produce the same ``Decision``.
19
- """
20
-
21
- from enum import Enum
22
-
23
- from pydantic import BaseModel
24
-
25
-
26
- class Effect(str, Enum):
27
- """Policy decision effect (AARM R4)."""
28
-
29
- PERMIT = "permit"
30
- DENY = "deny"
31
- MODIFY = "modify"
32
- STEP_UP = "step_up"
33
- DEFER = "defer"
34
-
35
- # Historical SDK values — kept so existing customer code comparing
36
- # ``decision.effect == Effect.ESCALATE`` keeps working. New code should
37
- # prefer STEP_UP / MODIFY.
38
- ESCALATE = "escalate"
39
- REDACT = "redact"
40
-
41
-
42
- class Decision(BaseModel):
43
- """Result of policy evaluation.
44
-
45
- Attributes
46
- ----------
47
- effect
48
- One of the AARM decisions.
49
- reasoning
50
- Human‑readable explanation shown in span events and dashboards.
51
- policy_id / policy_name
52
- Which policy produced the decision.
53
- policy_effect
54
- Policy effect metadata (if available).
55
- policy_decisions
56
- All matching policy decisions (if available).
57
- policy_timeout_behavior
58
- For step‑up decisions: ``"deny"`` (default) or ``"allow"`` — what
59
- happens when ``wait_for_approval`` times out.
60
- modified_args
61
- For ``modify`` decisions: the rewritten argument dict the tool
62
- should be invoked with. ``None`` for other decisions.
63
- """
64
-
65
- effect: Effect
66
- reasoning: str
67
- policy_id: str | None = None
68
- policy_name: str | None = None
69
- policy_effect: str | None = None
70
- policy_decisions: list[dict[str, str | None]] | None = None
71
- policy_timeout_behavior: str | None = None
72
- modified_args: dict[str, object] | None = None
73
-
74
- # ── Predicates ───────────────────────────────────────────────────────
75
- def is_allowed(self) -> bool:
76
- """True for ``permit`` decisions."""
77
- return self.effect == Effect.PERMIT
78
-
79
- def is_denied(self) -> bool:
80
- """True for ``deny`` decisions."""
81
- return self.effect == Effect.DENY
82
-
83
- def is_modified(self) -> bool:
84
- """True when policy rewrote arguments (``modify`` or the legacy ``redact``)."""
85
- return self.effect in (Effect.MODIFY, Effect.REDACT)
86
-
87
- def is_redacted(self) -> bool:
88
- """True specifically for the legacy ``redact`` effect."""
89
- return self.effect == Effect.REDACT
90
-
91
- def requires_approval(self) -> bool:
92
- """True when human approval is required (``step_up`` / legacy ``escalate``)."""
93
- return self.effect in (Effect.STEP_UP, Effect.ESCALATE)
94
-
95
- def is_deferred(self) -> bool:
96
- """True when the decision is suspended pending more context."""
97
- return self.effect == Effect.DEFER
98
-
99
- # ── Factories ────────────────────────────────────────────────────────
100
- @classmethod
101
- def permit(
102
- cls,
103
- reasoning: str = "Permitted by policy",
104
- policy_id: str | None = None,
105
- policy_name: str | None = None,
106
- policy_effect: str | None = None,
107
- policy_decisions: list[dict[str, str | None]] | None = None,
108
- ) -> "Decision":
109
- return cls(
110
- effect=Effect.PERMIT,
111
- reasoning=reasoning,
112
- policy_id=policy_id,
113
- policy_name=policy_name,
114
- policy_effect=policy_effect,
115
- policy_decisions=policy_decisions,
116
- )
117
-
118
- @classmethod
119
- def allow(
120
- cls,
121
- reasoning: str = "Permitted by policy",
122
- policy_id: str | None = None,
123
- policy_name: str | None = None,
124
- policy_effect: str | None = None,
125
- policy_decisions: list[dict[str, str | None]] | None = None,
126
- ) -> "Decision":
127
- """Alias for :meth:`permit` kept for older SDK users."""
128
- return cls.permit(
129
- reasoning=reasoning,
130
- policy_id=policy_id,
131
- policy_name=policy_name,
132
- policy_effect=policy_effect,
133
- policy_decisions=policy_decisions,
134
- )
135
-
136
- @classmethod
137
- def deny(
138
- cls,
139
- reasoning: str,
140
- policy_id: str | None = None,
141
- policy_name: str | None = None,
142
- policy_effect: str | None = None,
143
- policy_decisions: list[dict[str, str | None]] | None = None,
144
- ) -> "Decision":
145
- return cls(
146
- effect=Effect.DENY,
147
- reasoning=reasoning,
148
- policy_id=policy_id,
149
- policy_name=policy_name,
150
- policy_effect=policy_effect,
151
- policy_decisions=policy_decisions,
152
- )
153
-
154
- @classmethod
155
- def modify(
156
- cls,
157
- reasoning: str,
158
- modified_args: dict[str, object],
159
- policy_id: str | None = None,
160
- policy_name: str | None = None,
161
- ) -> "Decision":
162
- """Allow the action with rewritten arguments (AARM MODIFY)."""
163
- return cls(
164
- effect=Effect.MODIFY,
165
- reasoning=reasoning,
166
- policy_id=policy_id,
167
- policy_name=policy_name,
168
- modified_args=modified_args,
169
- )
170
-
171
- @classmethod
172
- def redact(
173
- cls,
174
- reasoning: str,
175
- policy_id: str | None = None,
176
- policy_name: str | None = None,
177
- policy_effect: str | None = None,
178
- policy_decisions: list[dict[str, str | None]] | None = None,
179
- ) -> "Decision":
180
- """Narrower alias of :meth:`modify` emitted when PII / secrets were
181
- redacted before the action ran. Preferred for backwards compatibility
182
- with existing dashboards that filter by ``redact``.
183
- """
184
- return cls(
185
- effect=Effect.REDACT,
186
- reasoning=reasoning,
187
- policy_id=policy_id,
188
- policy_name=policy_name,
189
- policy_effect=policy_effect,
190
- policy_decisions=policy_decisions,
191
- )
192
-
193
- @classmethod
194
- def step_up(
195
- cls,
196
- reasoning: str,
197
- policy_id: str | None = None,
198
- policy_name: str | None = None,
199
- policy_effect: str | None = None,
200
- policy_decisions: list[dict[str, str | None]] | None = None,
201
- policy_timeout_behavior: str | None = None,
202
- ) -> "Decision":
203
- """Require human approval before the action runs (AARM STEP_UP)."""
204
- return cls(
205
- effect=Effect.STEP_UP,
206
- reasoning=reasoning,
207
- policy_id=policy_id,
208
- policy_name=policy_name,
209
- policy_effect=policy_effect,
210
- policy_decisions=policy_decisions,
211
- policy_timeout_behavior=policy_timeout_behavior,
212
- )
213
-
214
- @classmethod
215
- def escalate(
216
- cls,
217
- reasoning: str,
218
- policy_id: str | None = None,
219
- policy_name: str | None = None,
220
- policy_effect: str | None = None,
221
- policy_decisions: list[dict[str, str | None]] | None = None,
222
- policy_timeout_behavior: str | None = None,
223
- ) -> "Decision":
224
- """Legacy SDK factory. Identical to :meth:`step_up` but emits the
225
- ``escalate`` effect so older dashboards keep filtering correctly."""
226
- return cls(
227
- effect=Effect.ESCALATE,
228
- reasoning=reasoning,
229
- policy_id=policy_id,
230
- policy_name=policy_name,
231
- policy_effect=policy_effect,
232
- policy_decisions=policy_decisions,
233
- policy_timeout_behavior=policy_timeout_behavior,
234
- )
235
-
236
- @classmethod
237
- def defer(
238
- cls,
239
- reasoning: str,
240
- policy_id: str | None = None,
241
- policy_name: str | None = None,
242
- ) -> "Decision":
243
- """Suspend the decision pending more context (AARM DEFER)."""
244
- return cls(
245
- effect=Effect.DEFER,
246
- reasoning=reasoning,
247
- policy_id=policy_id,
248
- policy_name=policy_name,
249
- )
@@ -1,15 +0,0 @@
1
- """Version information for CortexHub SDK."""
2
-
3
- from importlib.metadata import PackageNotFoundError, version
4
-
5
-
6
- def _resolve_version() -> str:
7
- try:
8
- return version("cortexhub")
9
- except PackageNotFoundError:
10
- return "0.0.0"
11
-
12
-
13
- __version__ = _resolve_version()
14
-
15
- __all__ = ["__version__"]
File without changes
File without changes
File without changes