API Reference

This is a concise reference for the public exports from scopra.

Policy

Policy defines a business rule that can be evaluated by a PolicyPipeline.


new Policy({
  id: "policy-id",
  name: "Policy name",
  description: "Optional summary.",
  instruction: "Evaluator instructions.",
  denial: "Denial text.",
  evaluator,
  confidence: 0.8,
  escalation,
});

PolicyOptions

Field	Type	Required	Description
`id`	`string`	Yes	Stable identifier used to match evaluator findings.
`name`	`string`	Yes	Human-readable policy name.
`description`	`string`	No	Summary of what the policy protects.
`instruction`	`string`	Yes	Instruction passed to the evaluator.
`denial`	`string`	Yes	Text returned when the policy denies.
`evaluator`	`ScopraModel \| PolicyEvaluator`	No	Per-policy evaluator override.
`confidence`	`number`	No	Minimum failed-finding confidence required to deny.
`escalation`	`PolicyEscalationOptions`	No	Review-only nested policy evaluation for low-confidence findings.

PolicyPipeline

PolicyPipeline evaluates requests against configured policies.


const pipeline = new PolicyPipeline({
  evaluator,
  policies,
  system,
  abortSignal,
  modelOptions,
});
 
const decision = await pipeline.evaluate(request);

Evaluation Requests


type EvaluationRequest = {
  content: string;
};

Decisions

PolicyDecision is a discriminated union. Check allowed before reading blocking violations.


if (decision.allowed) {
  decision.violations; // []
} else {
  decision.violations; // PolicyViolation[]
}

Evaluator Types


type PolicyEvaluator = (
  context: PolicyEvaluatorContext,
) => readonly PolicyFinding[] | Promise<readonly PolicyFinding[]>;
 
type PolicyFinding = {
  policyId: string;
  passed: boolean;
  reason?: string;
  confidence?: number;
  severity?: PolicySeverity;
};
 
type PolicySeverity = "low" | "medium" | "high" | "critical";

severity is report-only metadata for how serious a failed finding is. It does not affect denial or escalation behavior; use policy confidence thresholds for enforcement.

Model Adapters

Export	Description
`openai(client, model)`	Adapts the official OpenAI SDK client.
`anthropic(client, model, options?)`	Adapts the official Anthropic SDK client.
`vercel(model)`	Adapts a Vercel AI SDK language model.
`tanstack(adapter)`	Adapts a TanStack AI text adapter.

anthropic(...) accepts AnthropicAdapterOptions with an optional maxTokens default for requests where modelOptions.max_tokens is not provided.

Built-In Policy Classes

Export	Constructor options
`AgentScopePolicy`	`AgentScopePolicyOptions` with required `scope`.
`CopyrightPolicy`	`CommonPolicyOptions`
`FinancialAdvicePolicy`	`CommonPolicyOptions`
`LegalAdvicePolicy`	`CommonPolicyOptions`
`MedicalAdvicePolicy`	`CommonPolicyOptions`
`NoSecretsPolicy`	`CommonPolicyOptions`
`PersonalDataPolicy`	`CommonPolicyOptions`
`PromptInjectionPolicy`	`CommonPolicyOptions`
`RegulatedAdvicePolicy`	`CommonPolicyOptions`
`SocialEngineeringPolicy`	`CommonPolicyOptions`
`ToxicLanguagePolicy`	`CommonPolicyOptions`
`UnsafeToolUsePolicy`	`CommonPolicyOptions`

generateViolationResponse

generateViolationResponse(model, decision, options) creates user-facing denial copy from a denied decision.

See the Violation Responses guide for usage patterns and option guidance.


const response = await generateViolationResponse(model, decision, {
  locale: "en-US",
  instructions: "Use a concise support tone.",
  abortSignal,
  modelOptions,
});

Error Handling

Scopra rejects with typed errors when evaluation or violation-response generation cannot complete.

Export	Description
`ScopraError`	Base class for typed Scopra errors.
`PolicyEvaluationError`	Error for evaluator, model, or policy-finding failures.
`ViolationResponseError`	Error for failed denial-response generation.
`isScopraError(error)`	Type guard for Scopra errors.
`ScopraErrorCode`	Stable error code union.


try {
  const decision = await pipeline.evaluate(request);
} catch (error) {
  if (isScopraError(error)) {
    console.warn(error.code, error.context);
    return error.publicMessage;
  }
 
  throw error;
}

See the Error Handling guide for production patterns.