PR #25 · pramaan-io/pramaan-agents · merged 2026-06-03
An agent answering in court can't afford a hallucinated citation, a leaked matter, or a runaway bill.
Admissibility needs 4 hard checks, not a polite filter.
End-of-pipeline check is too late — the breach already happened.
The fix — Check, cap, lock, verify — every run, every answer.
Roadmap · Agent Platform
sequenceDiagram autonumber participant request as Agent run participant controller as Guardrail controller participant model as Model + tools participant recorder as MatterChat recorder request->>controller: AgentRunRequest controller->>controller: circuit_breaker.check_before_run controller->>model: cost_cap.check_before_model_call model->>model: tool call → tenant_boundary model->>controller: validate_answer (citations) controller-->>recorder: record_run_outcome
| Method | in → out | what it does |
|---|---|---|
CircuitStateStore | (class) | |
load | (firm_id) → list[dict[str, Any]] | |
save | (firm_id, samples) → None |
Implements the CircuitBreakerGuardrail that tracks per-firm error rate in a rolling window and emits the circuit_open status, blocking cascading retries on the MatterChat recorder path.
| new class | signature |
|---|---|
CircuitStateStore | (class) |
load | (firm_id) → list[dict[str, Any]] |
save | (firm_id, samples) → None |
DynamoDBCircuitStateStore | (class) |
CircuitBreakerGuardrail | (store, threshold, window_seconds, min_samples) |
check_before_run | (firm_id) → None |
record_outcome | (firm_id, error) → None |
_fresh_samples | (firm_id) → list[dict[str, Any]] |
Hosts the GuardrailController, GuardrailRunContext and GuardrailToolCallRecorder that orchestrate the four guardrails across run, model, tool and answer stages of every AgentRunRequest.
| new class | signature |
|---|---|
GuardrailRunContext | (request, run_id, source_verification, cost_cap) |
GuardrailController | (circuit_breaker) |
context_for | (request, run_id) → GuardrailRunContext |
record_run_outcome | (firm_id, error) → None |
wrap_recorder | (recorder, context) → ToolCallRecorder |
before_model_call | (context, prompt_text, user_message, history) → None |
after_model_call | (context, input_tokens, output_tokens) → None |
validate_answer | (context, content) → None |
GuardrailToolCallRecorder | (inner, context, _tool_names) |
after_tool_call | (event) → None |
Implements the CostCapGuardrail that estimates USD cost from token counts and aborts the model call before spend exceeds the configured cap, emitting the aborted_cost status.
| new class | signature |
|---|---|
CostCapGuardrail | (cap_usd, input_price_per_million, output_price_per_million, spent_usd) |
check_before_model_call | (prompt_text, user_message, history_text) → None |
record_model_usage | (input_tokens, output_tokens) → None |
_cost | (input_tokens, output_tokens) → Decimal |
_ensure_under_cap | (additional_usd) → None |
estimate_tokens | (text) → int |
_decimal_env | (name, default) → Decimal |
Defines the SourceVerificationGuardrail that re-checks every citation in the final answer against the fetched quotes before the answer leaves the agent.
| new class | signature |
|---|---|
SourceVerificationGuardrail | (fetched_quotes) |
validate_answer | (content) → None |
citations_in | (content) → list[tuple[str, str]] |
Defines the TenantBoundaryGuardrail that validates firm_id and matter_id on every tool call so no cross-tenant data access can slip through the MatterChat recorder.
| new class | signature |
|---|---|
TenantBoundaryGuardrail | (firm_id, matter_id) |
_uuid_from_input | (value) → UUID | None |
StrandsHarness now holds guardrail_controller and guardrail_context fields so the four guardrails are invoked inside the agent loop, not bolted on after.
guardrail_controller : GuardrailController | Noneguardrail_context : GuardrailRunContext | NoneAgent runtime app now owns a GuardrailController instance, wiring the four guardrails into every AgentRunRequest path that flows through the runtime.
guardrails : GuardrailControllerAdded the _failure_status helper that maps runtime errors to the canonical block statuses (circuit_open, aborted_cost, guardrail_blocked) before they are persisted to the run record.
| new method | signature |
|---|---|
_failure_status | (error) → str |
Introduces GuardrailBlockedError and GuardrailTerminalError so guardrail failures are distinguishable from regular runtime errors throughout the recorder path.
| new class | signature |
|---|---|
GuardrailBlockedError | (class) |
GuardrailTerminalError | (class) |
__init__ | (status, message) → None |
MatterChat tool schema gained an optional matter_id field so the TenantBoundaryGuardrail can verify which matter a tool call is operating on before it executes.
matter_id : UUID | None