cortexhub 0.5.2__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 (63) hide show
  1. {cortexhub-0.5.2 → cortexhub-0.5.3}/PKG-INFO +1 -1
  2. {cortexhub-0.5.2 → cortexhub-0.5.3}/pyproject.toml +1 -1
  3. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/client.py +143 -23
  4. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/constants.py +23 -2
  5. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/policy/evaluator.py +4 -1
  6. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/signing.py +1 -1
  7. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/telemetry/otel.py +0 -25
  8. cortexhub-0.5.3/src/cortexhub/version.py +27 -0
  9. cortexhub-0.5.2/src/cortexhub/version.py +0 -15
  10. {cortexhub-0.5.2 → cortexhub-0.5.3}/.gitignore +0 -0
  11. {cortexhub-0.5.2 → cortexhub-0.5.3}/LICENSE +0 -0
  12. {cortexhub-0.5.2 → cortexhub-0.5.3}/README.md +0 -0
  13. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/__init__.py +0 -0
  14. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/audit/__init__.py +0 -0
  15. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/audit/events.py +0 -0
  16. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/backend/__init__.py +0 -0
  17. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/backend/client.py +0 -0
  18. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/config.py +0 -0
  19. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/context/__init__.py +0 -0
  20. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/context/enricher.py +0 -0
  21. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/errors.py +0 -0
  22. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/__init__.py +0 -0
  23. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/injection.py +0 -0
  24. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/__init__.py +0 -0
  25. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/LICENSE +0 -0
  26. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/LICENSES_SOURCES +0 -0
  27. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/README.md +0 -0
  28. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/accuracy.json +0 -0
  29. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/attribute_ruler/patterns +0 -0
  30. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/config.cfg +0 -0
  31. {cortexhub-0.5.2 → 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
  32. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/meta.json +0 -0
  33. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/ner/cfg +0 -0
  34. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/ner/model +0 -0
  35. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/ner/moves +0 -0
  36. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/parser/cfg +0 -0
  37. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/parser/model +0 -0
  38. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/parser/moves +0 -0
  39. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/senter/cfg +0 -0
  40. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/senter/model +0 -0
  41. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tagger/cfg +0 -0
  42. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tagger/model +0 -0
  43. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tok2vec/cfg +0 -0
  44. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tok2vec/model +0 -0
  45. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/tokenizer +0 -0
  46. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/key2row +0 -0
  47. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/lookups.bin +0 -0
  48. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/strings.json +0 -0
  49. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/vectors +0 -0
  50. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/en_core_web_sm-3.8.0/vocab/vectors.cfg +0 -0
  51. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/models/en_core_web_sm/meta.json +0 -0
  52. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/pii.py +0 -0
  53. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/guardrails/secrets.py +0 -0
  54. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/interceptors/__init__.py +0 -0
  55. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/interceptors/mcp.py +0 -0
  56. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/logging.py +0 -0
  57. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/policy/__init__.py +0 -0
  58. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/policy/effects.py +0 -0
  59. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/policy/loader.py +0 -0
  60. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/policy/models.py +0 -0
  61. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/policy/sync.py +0 -0
  62. {cortexhub-0.5.2 → cortexhub-0.5.3}/src/cortexhub/telemetry/__init__.py +0 -0
  63. {cortexhub-0.5.2 → 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.2
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.2"
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:
@@ -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)
@@ -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
  #
@@ -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
 
@@ -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,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