> ## Documentation Index
> Fetch the complete documentation index at: https://docs.complior.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Reference

> Complete reference for MiddlewareConfig, AgentConfig, and TOML file-based configuration.

`@complior/sdk` accepts a `MiddlewareConfig` object at initialization. Every field is optional — sensible defaults are applied.

```typescript theme={null}
import { complior } from '@complior/sdk';
import OpenAI from 'openai';

const client = complior(new OpenAI(), {
  jurisdictions: ['EU'],
  role: 'provider',
  domain: 'hr',
  strict: true,
});
```

## Core

| Field           | Type                                                   | Default     | Description                                                                                      |
| --------------- | ------------------------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------ |
| `jurisdictions` | `('EU' \| 'US' \| 'UK' \| 'CA' \| 'AU' \| 'GLOBAL')[]` | `undefined` | Active jurisdictions for compliance checks                                                       |
| `role`          | `'provider' \| 'deployer' \| 'both'`                   | `undefined` | EU AI Act role classification                                                                    |
| `domain`        | `Domain \| Domain[]`                                   | `undefined` | Activates domain-specific hooks (`hr`, `finance`, `healthcare`, `education`, `legal`, `content`) |
| `logging`       | `boolean`                                              | `false`     | Enable request/response logging                                                                  |
| `strict`        | `boolean`                                              | `false`     | Throw on any compliance violation (vs. warn)                                                     |

## PII / Sanitize

| Field          | Type                             | Default     | Description                |
| -------------- | -------------------------------- | ----------- | -------------------------- |
| `sanitizeMode` | `'replace' \| 'block' \| 'warn'` | `'replace'` | How to handle detected PII |

```typescript theme={null}
const client = complior(new OpenAI(), {
  sanitizeMode: 'block', // Throw PIIDetectedError instead of redacting
});
```

* **`replace`** — redacts PII with labels like `[PII:SSN]`, `[PII:EMAIL]`, `[PII:IBAN]`
* **`block`** — throws `PIIDetectedError` on first PII match
* **`warn`** — passes through unmodified, adds `piiDetected` to metadata

<Info>See [PII Detection](/sdk/pii-detection) for the full list of 50+ detectable types and checksum validators.</Info>

## Disclosure

| Field                     | Type                                | Default               | Description                                       |
| ------------------------- | ----------------------------------- | --------------------- | ------------------------------------------------- |
| `disclosureInjection`     | `boolean`                           | `false`               | Inject "I am AI" disclosure into system messages  |
| `disclosureText`          | `string`                            | Built-in per language | Custom disclosure text                            |
| `disclosurePosition`      | `'prepend' \| 'append' \| 'header'` | `'prepend'`           | Where to inject disclosure                        |
| `disclosureFrequency`     | `'every' \| 'session-start'`        | `'every'`             | Injection frequency                               |
| `disclosureLanguages`     | `('EN' \| 'DE' \| 'FR' \| 'ES')[]`  | `['EN']`              | Languages for disclosure verification             |
| `disclosureMode`          | `'warn-only' \| 'block'`            | `'warn-only'`         | Action when disclosure is missing from response   |
| `customDisclosurePhrases` | `RegExp[]`                          | `undefined`           | Additional patterns to accept as valid disclosure |

```typescript theme={null}
const client = complior(new OpenAI(), {
  disclosureInjection: true,
  disclosureText: 'This response is generated by an AI system.',
  disclosurePosition: 'prepend',
  disclosureLanguages: ['EN', 'DE'],
  disclosureMode: 'block',
});
```

## Bias Detection

| Field           | Type                | Default                      | Description                                                     |
| --------------- | ------------------- | ---------------------------- | --------------------------------------------------------------- |
| `biasThreshold` | `number` (0–1)      | `0.3` (general), `0.15` (HR) | Aggregate score threshold — findings above this trigger action  |
| `biasAction`    | `'warn' \| 'block'` | `'warn'`                     | Throw `BiasDetectedError` (`block`) or add to metadata (`warn`) |

The threshold depends on the active `domain` profile. See [Bias Detection](/sdk/bias-detection) for domain-specific weights.

## Safety Filter

| Field             | Type                         | Default   | Description                                 |
| ----------------- | ---------------------------- | --------- | ------------------------------------------- |
| `safetyFilter`    | `boolean`                    | `false`   | Enable safety pattern scanning on responses |
| `safetyMode`      | `'block' \| 'warn' \| 'log'` | `'block'` | Action on safety violation                  |
| `safetyThreshold` | `number` (0–1)               | `0.5`     | Aggregate score threshold                   |

```typescript theme={null}
const client = complior(new OpenAI(), {
  safetyFilter: true,
  safetyMode: 'warn',    // Don't throw, add to metadata
  safetyThreshold: 0.3,  // Lower = stricter
});
```

## Human-in-the-Loop Gate

| Field               | Type                                          | Default          | Description                                          |
| ------------------- | --------------------------------------------- | ---------------- | ---------------------------------------------------- |
| `hitlGate`          | `boolean`                                     | `false`          | Enable HITL gate for critical actions                |
| `hitlGateTimeoutMs` | `number`                                      | `300000` (5 min) | Timeout before auto-deny                             |
| `hitlGateRules`     | `GateRule[]`                                  | 4 built-in rules | Custom gate trigger rules                            |
| `onGateTriggered`   | `(req: GateRequest) => Promise<GateDecision>` | `undefined`      | Approval callback — if absent, auto-deny (fail-safe) |

```typescript theme={null}
const client = complior(new OpenAI(), {
  hitlGate: true,
  hitlGateTimeoutMs: 60_000,
  onGateTriggered: async (request) => {
    const approved = await askHumanOperator(request);
    return approved
      ? { approved: true }
      : { approved: false, reason: 'Operator denied' };
  },
});
```

See [Safety & HITL](/sdk/safety) for built-in rules and types.

## Interaction Logging

| Field                | Type      | Default                             | Description                     |
| -------------------- | --------- | ----------------------------------- | ------------------------------- |
| `interactionLogger`  | `boolean` | `false`                             | Enable structured JSONL logging |
| `interactionLogPath` | `string`  | `.complior/logs/interactions.jsonl` | Log file path                   |

Logs include provider, model, prompt/response hashes, token counts, latency, and compliance check results. Auto-rotates at 100 MB.

## Runtime

| Field        | Type              | Default                | Description                                             |
| ------------ | ----------------- | ---------------------- | ------------------------------------------------------- |
| `configPath` | `string \| false` | `.complior/proxy.toml` | TOML config file path, or `false` to disable hot-reload |
| `retry`      | `RetryConfig`     | See below              | Retry configuration for transient errors                |

### RetryConfig

| Field         | Type      | Default | Description                      |
| ------------- | --------- | ------- | -------------------------------- |
| `enabled`     | `boolean` | `true`  | Enable automatic retries         |
| `maxRetries`  | `number`  | `3`     | Maximum retry attempts           |
| `baseDelayMs` | `number`  | `1000`  | Base delay (exponential backoff) |
| `maxDelayMs`  | `number`  | `30000` | Maximum delay cap                |

Retries apply to status codes `429`, `500`–`504` and network errors (`ECONNREFUSED`, `ECONNRESET`, `ETIMEDOUT`, `EPIPE`, `EAI_AGAIN`). Compliance errors (`MiddlewareError` subclasses) are never retried.

## TOML File Configuration

Create `.complior/proxy.toml` for file-based configuration with hot-reload (100ms debounce):

```toml theme={null}
[hooks]
logging = true
safety_filter = true
hitl_gate = false
interaction_logger = true
disclosure_injection = true

[thresholds]
bias_threshold = 0.2
bias_action = "block"
safety_threshold = 0.3
safety_mode = "warn"

[sanitize]
mode = "replace"

[disclosure]
mode = "block"
languages = ["EN", "DE"]
text = "This response is AI-generated."
position = "prepend"
frequency = "every"

[hitl]
timeout_ms = 60000

[logging]
interaction_log_path = ".complior/logs/interactions.jsonl"

[retry]
enabled = true
max_retries = 5
base_delay_ms = 2000
max_delay_ms = 60000
```

Programmatic config takes precedence over file-based config on conflicts.

## AgentConfig

`AgentConfig` extends `MiddlewareConfig` with passport enforcement fields. See [Agent Mode](/sdk/agent-mode) for the full reference.

| Field                | Type                                 | Description                                           |
| -------------------- | ------------------------------------ | ----------------------------------------------------- |
| `passport`           | `Record<string, unknown>`            | Agent Passport JSON (loaded from `.complior/agents/`) |
| `budgetLimitUsd`     | `number`                             | Session budget cap                                    |
| `onBudgetExceeded`   | `'warn' \| 'block'`                  | Action when budget exceeded                           |
| `onPermissionDenied` | `'warn' \| 'block'`                  | Action on denied method                               |
| `toolCallAction`     | `ToolCallAction`                     | How to handle denied tool calls                       |
| `onToolCallDenied`   | `(denied: DeniedToolCall[]) => void` | Callback for denied tools                             |
| `onAction`           | `(entry: ActionLogEntry) => void`    | Audit callback for each LLM call                      |
| `circuitBreaker`     | `CircuitBreakerConfig`               | Circuit breaker settings                              |

<CardGroup cols={2}>
  <Card title="Agent Mode" icon="robot" href="/sdk/agent-mode">
    Passport enforcement, budget, rate limits.
  </Card>

  <Card title="Advanced Features" icon="gear" href="/sdk/advanced">
    Hot-reload, retry, streaming, logging.
  </Card>
</CardGroup>