hiitl 0.1.0__py3-none-any.whl

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 (58) hide show
  1. hiitl/__init__.py +57 -0
  2. hiitl/core/__init__.py +17 -0
  3. hiitl/core/evaluator.py +408 -0
  4. hiitl/core/route_types.py +626 -0
  5. hiitl/core/tests/__init__.py +1 -0
  6. hiitl/core/tests/conformance/__init__.py +1 -0
  7. hiitl/core/tests/conformance/test_conformance.py +277 -0
  8. hiitl/core/tests/test_error_handling.py +532 -0
  9. hiitl/core/tests/test_evaluator.py +1151 -0
  10. hiitl/core/tests/test_route_types.py +502 -0
  11. hiitl/core/types.py +408 -0
  12. hiitl/sdk/__init__.py +69 -0
  13. hiitl/sdk/audit.py +476 -0
  14. hiitl/sdk/circuit_breaker.py +149 -0
  15. hiitl/sdk/client.py +890 -0
  16. hiitl/sdk/config.py +244 -0
  17. hiitl/sdk/exceptions.py +140 -0
  18. hiitl/sdk/http_client.py +255 -0
  19. hiitl/sdk/policy_loader.py +215 -0
  20. hiitl/sdk/rate_limiter.py +275 -0
  21. hiitl/sdk/route_loader.py +290 -0
  22. hiitl/sdk/sync_cache.py +466 -0
  23. hiitl/sdk/sync_client.py +415 -0
  24. hiitl/sdk/sync_engine.py +443 -0
  25. hiitl/sdk/telemetry.py +477 -0
  26. hiitl/sdk/tests/__init__.py +1 -0
  27. hiitl/sdk/tests/test_audit.py +441 -0
  28. hiitl/sdk/tests/test_client.py +475 -0
  29. hiitl/sdk/tests/test_config.py +185 -0
  30. hiitl/sdk/tests/test_exceptions.py +110 -0
  31. hiitl/sdk/tests/test_hosted.py +808 -0
  32. hiitl/sdk/tests/test_policy_loader.py +321 -0
  33. hiitl/sdk/tests/test_rate_limiter.py +489 -0
  34. hiitl/sdk/tests/test_route_loader.py +695 -0
  35. hiitl/sdk/tests/test_sync.py +1230 -0
  36. hiitl/sdk/tests/test_telemetry.py +650 -0
  37. hiitl/server/main.py +42 -0
  38. hiitl/synthetic/__init__.py +28 -0
  39. hiitl/synthetic/__main__.py +7 -0
  40. hiitl/synthetic/agent_loader.py +115 -0
  41. hiitl/synthetic/assertions.py +204 -0
  42. hiitl/synthetic/cli.py +362 -0
  43. hiitl/synthetic/envelope_factory.py +168 -0
  44. hiitl/synthetic/executor.py +329 -0
  45. hiitl/synthetic/grader.py +166 -0
  46. hiitl/synthetic/report.py +150 -0
  47. hiitl/synthetic/scenario_loader.py +93 -0
  48. hiitl/synthetic/tests/__init__.py +0 -0
  49. hiitl/synthetic/tests/test_assertions.py +173 -0
  50. hiitl/synthetic/tests/test_cli.py +116 -0
  51. hiitl/synthetic/tests/test_envelope_factory.py +140 -0
  52. hiitl/synthetic/tests/test_executor.py +318 -0
  53. hiitl/synthetic/tests/test_grader.py +220 -0
  54. hiitl/synthetic/types.py +235 -0
  55. hiitl-0.1.0.dist-info/METADATA +153 -0
  56. hiitl-0.1.0.dist-info/RECORD +58 -0
  57. hiitl-0.1.0.dist-info/WHEEL +5 -0
  58. hiitl-0.1.0.dist-info/top_level.txt +1 -0
hiitl/__init__.py ADDED
@@ -0,0 +1,57 @@
1
+ """HIITL - Human Intelligence in the Loop.
2
+
3
+ Deterministic control point for software that can act.
4
+
5
+ This package provides policy-based access control for AI agents and
6
+ autonomous systems. It enables developers to define and enforce policies
7
+ that govern what actions agents can take.
8
+
9
+ Zero-config (observe everything):
10
+ >>> from hiitl import HIITL
11
+ >>> hiitl = HIITL()
12
+ >>> decision = hiitl.evaluate("send_email")
13
+ >>> if decision.allowed:
14
+ ... send_email()
15
+
16
+ With policy enforcement:
17
+ >>> hiitl = HIITL(
18
+ ... agent_id="payment-agent",
19
+ ... policy_path="./policy.yaml",
20
+ ... mode="RESPECT_POLICY",
21
+ ... )
22
+ >>> decision = hiitl.evaluate(
23
+ ... "process_payment",
24
+ ... parameters={"amount": 500, "currency": "USD"},
25
+ ... )
26
+ >>> if decision.allowed:
27
+ ... process_payment()
28
+ """
29
+
30
+ __version__ = "0.1.0"
31
+
32
+ # Import main SDK class
33
+ from hiitl.sdk.client import HIITL
34
+
35
+ # Import common exceptions
36
+ from hiitl.sdk.exceptions import (
37
+ AuditLogError,
38
+ ConfigurationError,
39
+ EnvelopeValidationError,
40
+ HIITLError,
41
+ NetworkError,
42
+ PolicyLoadError,
43
+ ServerError,
44
+ )
45
+
46
+ # Export public API
47
+ __all__ = [
48
+ "HIITL",
49
+ "HIITLError",
50
+ "PolicyLoadError",
51
+ "AuditLogError",
52
+ "ConfigurationError",
53
+ "EnvelopeValidationError",
54
+ "ServerError",
55
+ "NetworkError",
56
+ "__version__",
57
+ ]
hiitl/core/__init__.py ADDED
@@ -0,0 +1,17 @@
1
+ """HIITL Core - Policy evaluator and core types."""
2
+
3
+ from .evaluator import PolicyEvaluator, evaluate
4
+ from .types import Envelope, PolicySet, Rule, Decision, Remediation, RemediationType
5
+ from .route_types import Route
6
+
7
+ __all__ = [
8
+ "PolicyEvaluator",
9
+ "evaluate",
10
+ "Envelope",
11
+ "PolicySet",
12
+ "Rule",
13
+ "Decision",
14
+ "Remediation",
15
+ "RemediationType",
16
+ "Route",
17
+ ]
@@ -0,0 +1,408 @@
1
+ """Policy evaluator - deterministic rule evaluation engine.
2
+
3
+ This is the core runtime enforcement engine. It evaluates policies (JSON objects)
4
+ against execution envelopes and returns decisions.
5
+
6
+ Source of truth:
7
+ - specs/envelope_schema.json
8
+ - docs/specs/policy_format.md
9
+ - docs/specs/decision_response.md
10
+
11
+ Design principles:
12
+ - Deterministic: same (envelope, policy) always produces same decision
13
+ - Side-effect free: evaluation does not modify state
14
+ - Fast: sub-millisecond evaluation for typical policies
15
+ - Language-neutral: behavior validated by conformance test suite
16
+ """
17
+
18
+ import re
19
+ import time
20
+ import uuid
21
+ from typing import Any, Dict, List, Optional, Union
22
+
23
+ from .types import (
24
+ Condition,
25
+ ConditionOperator,
26
+ Decision,
27
+ DecisionType,
28
+ Envelope,
29
+ LogicalCondition,
30
+ MatchedRule,
31
+ PolicySet,
32
+ Rule,
33
+ Timing,
34
+ )
35
+
36
+
37
+ class PolicyEvaluator:
38
+ """Policy evaluator - evaluates policies against envelopes.
39
+
40
+ This evaluator works on JSON policy objects (Python dicts/Pydantic models).
41
+ It does not handle YAML parsing - that's a separate concern.
42
+
43
+ Example:
44
+ >>> evaluator = PolicyEvaluator()
45
+ >>> policy = PolicySet(**policy_dict) # From JSON
46
+ >>> envelope = Envelope(**envelope_dict) # From JSON
47
+ >>> decision = evaluator.evaluate(envelope, policy)
48
+ """
49
+
50
+ def __init__(self):
51
+ """Initialize the policy evaluator."""
52
+ pass
53
+
54
+ def evaluate(
55
+ self,
56
+ envelope: Union[Envelope, Dict[str, Any]],
57
+ policy: Union[PolicySet, Dict[str, Any]],
58
+ mode: str = "RESPECT_POLICY",
59
+ ) -> Decision:
60
+ """Evaluate an envelope against a policy and return a decision.
61
+
62
+ Args:
63
+ envelope: Execution envelope (Envelope model or dict)
64
+ policy: Policy set (PolicySet model or dict)
65
+ mode: Evaluation mode. "OBSERVE_ALL" wraps all blocking decisions
66
+ in OBSERVE (allowed=True). "RESPECT_POLICY" respects per-rule
67
+ mode field (default).
68
+
69
+ Returns:
70
+ Decision object with outcome, reason codes, and timing metadata
71
+
72
+ Raises:
73
+ ValidationError: If envelope or policy doesn't match schema
74
+ """
75
+ start_time = time.perf_counter()
76
+
77
+ # Validate and convert to Pydantic models
78
+ if not isinstance(envelope, Envelope):
79
+ envelope = Envelope(**envelope)
80
+
81
+ if not isinstance(policy, PolicySet):
82
+ policy = PolicySet(**policy)
83
+
84
+ ingest_end = time.perf_counter()
85
+ ingest_ms = (ingest_end - start_time) * 1000
86
+
87
+ # Evaluate policy rules
88
+ eval_start = time.perf_counter()
89
+ decision_type, reason_codes, matched_rules, matched_rule_obj = (
90
+ self._evaluate_rules(envelope, policy)
91
+ )
92
+ eval_end = time.perf_counter()
93
+ evaluation_ms = (eval_end - eval_start) * 1000
94
+
95
+ # Build decision response
96
+ total_ms = (eval_end - start_time) * 1000
97
+
98
+ # Escalation fields: resume_token + route_ref
99
+ escalation_types = {DecisionType.REQUIRE_APPROVAL, DecisionType.PAUSE, DecisionType.ESCALATE}
100
+ resume_token = None
101
+ route_ref = None
102
+ if decision_type in escalation_types:
103
+ resume_token = f"rtk_{uuid.uuid4().hex}"
104
+ if matched_rule_obj and matched_rule_obj.route:
105
+ route_ref = matched_rule_obj.route
106
+
107
+ # Remediation: pass through from matched rule (only for blocking decisions)
108
+ allowed = decision_type in [DecisionType.ALLOW, DecisionType.SANDBOX]
109
+ remediation = None
110
+ if not allowed and matched_rule_obj and matched_rule_obj.remediation:
111
+ remediation = matched_rule_obj.remediation
112
+
113
+ # Check if this decision should be wrapped in OBSERVE mode
114
+ should_observe = False
115
+ if mode == "OBSERVE_ALL" and not allowed:
116
+ should_observe = True
117
+ elif (mode == "RESPECT_POLICY" and matched_rule_obj is not None
118
+ and matched_rule_obj.mode == "observe" and not allowed):
119
+ should_observe = True
120
+
121
+ if should_observe:
122
+ return Decision(
123
+ action_id=envelope.action_id,
124
+ decision=DecisionType.OBSERVE,
125
+ allowed=True,
126
+ reason_codes=["OBSERVED"],
127
+ would_be=decision_type,
128
+ would_be_reason_codes=reason_codes,
129
+ policy_version=policy.version,
130
+ timing=Timing(
131
+ ingest_ms=ingest_ms,
132
+ evaluation_ms=evaluation_ms,
133
+ total_ms=total_ms,
134
+ ),
135
+ matched_rules=matched_rules if matched_rules else None,
136
+ )
137
+
138
+ decision = Decision(
139
+ action_id=envelope.action_id,
140
+ decision=decision_type,
141
+ allowed=allowed,
142
+ reason_codes=reason_codes,
143
+ policy_version=policy.version,
144
+ timing=Timing(
145
+ ingest_ms=ingest_ms,
146
+ evaluation_ms=evaluation_ms,
147
+ total_ms=total_ms,
148
+ ),
149
+ matched_rules=matched_rules if matched_rules else None,
150
+ resume_token=resume_token,
151
+ route_ref=route_ref,
152
+ remediation=remediation,
153
+ )
154
+
155
+ return decision
156
+
157
+ def _evaluate_rules(
158
+ self, envelope: Envelope, policy: PolicySet
159
+ ) -> tuple[DecisionType, List[str], List[MatchedRule], Optional[Rule]]:
160
+ """Evaluate rules in priority order and return first match.
161
+
162
+ Args:
163
+ envelope: Validated envelope
164
+ policy: Validated policy set
165
+
166
+ Returns:
167
+ Tuple of (decision_type, reason_codes, matched_rules, matched_rule_obj)
168
+ """
169
+ # Sort rules by priority (highest first)
170
+ sorted_rules = sorted(
171
+ policy.rules, key=lambda r: r.priority, reverse=True
172
+ )
173
+
174
+ # Evaluate rules in priority order (first match wins)
175
+ for rule in sorted_rules:
176
+ # Skip disabled rules
177
+ if not rule.enabled:
178
+ continue
179
+
180
+ # Evaluate rule conditions
181
+ if self._evaluate_condition(envelope, rule.conditions):
182
+ # Rule matched!
183
+ matched_rule = MatchedRule(
184
+ rule_name=rule.name,
185
+ policy_set=policy.name,
186
+ priority=rule.priority,
187
+ )
188
+ return (
189
+ rule.decision,
190
+ [rule.reason_code],
191
+ [matched_rule],
192
+ rule,
193
+ )
194
+
195
+ # No rules matched - default to BLOCK (safe by default)
196
+ return (DecisionType.BLOCK, ["NO_MATCHING_RULE"], [], None)
197
+
198
+ def _evaluate_condition(
199
+ self, envelope: Envelope, condition: Union[Condition, LogicalCondition]
200
+ ) -> bool:
201
+ """Evaluate a condition (atomic or logical) against an envelope.
202
+
203
+ Args:
204
+ envelope: Envelope to evaluate against
205
+ condition: Condition to evaluate (atomic or logical)
206
+
207
+ Returns:
208
+ True if condition matches, False otherwise
209
+ """
210
+ if isinstance(condition, Condition):
211
+ return self._evaluate_atomic_condition(envelope, condition)
212
+ elif isinstance(condition, LogicalCondition):
213
+ return self._evaluate_logical_condition(envelope, condition)
214
+ else:
215
+ raise ValueError(f"Unknown condition type: {type(condition)}")
216
+
217
+ def _evaluate_logical_condition(
218
+ self, envelope: Envelope, condition: LogicalCondition
219
+ ) -> bool:
220
+ """Evaluate a logical condition (all_of, any_of, none_of).
221
+
222
+ Args:
223
+ envelope: Envelope to evaluate against
224
+ condition: Logical condition
225
+
226
+ Returns:
227
+ True if logical condition matches, False otherwise
228
+ """
229
+ if condition.all_of is not None:
230
+ # AND: all conditions must be true
231
+ return all(
232
+ self._evaluate_condition(envelope, cond)
233
+ for cond in condition.all_of
234
+ )
235
+ elif condition.any_of is not None:
236
+ # OR: at least one condition must be true
237
+ return any(
238
+ self._evaluate_condition(envelope, cond)
239
+ for cond in condition.any_of
240
+ )
241
+ elif condition.none_of is not None:
242
+ # NOT: none of the conditions may be true
243
+ return not any(
244
+ self._evaluate_condition(envelope, cond)
245
+ for cond in condition.none_of
246
+ )
247
+ else:
248
+ raise ValueError("Logical condition must have one of: all_of, any_of, none_of")
249
+
250
+ def _evaluate_atomic_condition(
251
+ self, envelope: Envelope, condition: Condition
252
+ ) -> bool:
253
+ """Evaluate an atomic condition (field comparison).
254
+
255
+ Args:
256
+ envelope: Envelope to evaluate against
257
+ condition: Atomic condition
258
+
259
+ Returns:
260
+ True if condition matches, False otherwise
261
+ """
262
+ # Resolve field path (supports dot notation)
263
+ field_value = self._resolve_field_path(envelope, condition.field)
264
+
265
+ # Evaluate operator
266
+ return self._evaluate_operator(
267
+ field_value, condition.operator, condition.value
268
+ )
269
+
270
+ def _resolve_field_path(self, envelope: Envelope, field_path: str) -> Any:
271
+ """Resolve a field path (dot notation) in the envelope.
272
+
273
+ Examples:
274
+ tool_name -> envelope.tool_name
275
+ parameters.amount -> envelope.parameters["amount"]
276
+ target.account_id -> envelope.target["account_id"]
277
+
278
+ Args:
279
+ envelope: Envelope to resolve field in
280
+ field_path: Dot-notation field path
281
+
282
+ Returns:
283
+ Field value, or None if field doesn't exist
284
+ """
285
+ parts = field_path.split(".")
286
+ current = envelope
287
+
288
+ for part in parts:
289
+ # Backward compat: tool_name → action
290
+ if part == "tool_name":
291
+ part = "action"
292
+ if isinstance(current, dict):
293
+ current = current.get(part)
294
+ elif hasattr(current, part):
295
+ current = getattr(current, part)
296
+ else:
297
+ return None
298
+
299
+ if current is None:
300
+ return None
301
+
302
+ return current
303
+
304
+ def _evaluate_operator(
305
+ self, field_value: Any, operator: ConditionOperator, compare_value: Any
306
+ ) -> bool:
307
+ """Evaluate a comparison operator.
308
+
309
+ Args:
310
+ field_value: Value from envelope
311
+ operator: Comparison operator
312
+ compare_value: Value to compare against
313
+
314
+ Returns:
315
+ True if comparison matches, False otherwise
316
+ """
317
+ # Handle None/null fields
318
+ if operator == ConditionOperator.EXISTS:
319
+ return (field_value is not None) == compare_value
320
+
321
+ # If field doesn't exist and operator isn't EXISTS, return False
322
+ if field_value is None:
323
+ return False
324
+
325
+ # Equality operators
326
+ if operator == ConditionOperator.EQUALS:
327
+ return field_value == compare_value
328
+ elif operator == ConditionOperator.NOT_EQUALS:
329
+ return field_value != compare_value
330
+
331
+ # Numeric comparison operators
332
+ elif operator == ConditionOperator.GREATER_THAN:
333
+ return field_value > compare_value
334
+ elif operator == ConditionOperator.GREATER_THAN_OR_EQUAL:
335
+ return field_value >= compare_value
336
+ elif operator == ConditionOperator.LESS_THAN:
337
+ return field_value < compare_value
338
+ elif operator == ConditionOperator.LESS_THAN_OR_EQUAL:
339
+ return field_value <= compare_value
340
+
341
+ # String/array operators
342
+ elif operator == ConditionOperator.CONTAINS:
343
+ if isinstance(field_value, str):
344
+ return compare_value in field_value
345
+ elif isinstance(field_value, list):
346
+ return compare_value in field_value
347
+ else:
348
+ return False
349
+ elif operator == ConditionOperator.NOT_CONTAINS:
350
+ if isinstance(field_value, str):
351
+ return compare_value not in field_value
352
+ elif isinstance(field_value, list):
353
+ return compare_value not in field_value
354
+ else:
355
+ return True
356
+
357
+ elif operator == ConditionOperator.STARTS_WITH:
358
+ return isinstance(field_value, str) and field_value.startswith(
359
+ compare_value
360
+ )
361
+ elif operator == ConditionOperator.ENDS_WITH:
362
+ return isinstance(field_value, str) and field_value.endswith(
363
+ compare_value
364
+ )
365
+ elif operator == ConditionOperator.MATCHES:
366
+ # Regex match (use sparingly - can be slow)
367
+ if not isinstance(field_value, str):
368
+ return False
369
+ try:
370
+ pattern = re.compile(compare_value)
371
+ return pattern.search(field_value) is not None
372
+ except re.error:
373
+ return False
374
+
375
+ # Set operators
376
+ elif operator == ConditionOperator.IN:
377
+ return field_value in compare_value
378
+ elif operator == ConditionOperator.NOT_IN:
379
+ return field_value not in compare_value
380
+
381
+ else:
382
+ raise ValueError(f"Unknown operator: {operator}")
383
+
384
+
385
+ # Convenience function
386
+ def evaluate(
387
+ envelope: Union[Envelope, Dict[str, Any]],
388
+ policy: Union[PolicySet, Dict[str, Any]],
389
+ mode: str = "RESPECT_POLICY",
390
+ ) -> Decision:
391
+ """Evaluate an envelope against a policy (convenience function).
392
+
393
+ Args:
394
+ envelope: Execution envelope (Envelope model or dict)
395
+ policy: Policy set (PolicySet model or dict)
396
+ mode: Evaluation mode ("OBSERVE_ALL" or "RESPECT_POLICY")
397
+
398
+ Returns:
399
+ Decision object
400
+
401
+ Example:
402
+ >>> from hiitl.core import evaluate
403
+ >>> decision = evaluate(envelope_dict, policy_dict)
404
+ >>> if decision.allowed:
405
+ >>> execute_action()
406
+ """
407
+ evaluator = PolicyEvaluator()
408
+ return evaluator.evaluate(envelope, policy, mode=mode)