# optulus-anchor

Runtime validation SDK for AI tool callables.

## Install

`pip install optulus-anchor`

## What it does

- validates tool input params before execution (`params_schema`)
- validates tool output after execution (`response_schema`)
- supports sync + async wrapped functions
- emits structured traces and optional sink callbacks
- persists trace rows to SQLite by default

## Main API

```python
validate_tool(
    *,
    params_schema: type[Any] | None = None,
    response_schema: type[Any] | None = None,
    on_param_error: Literal["raise", "log", "warn", "self_correct"] = "raise",
    on_response_error: Literal["raise", "log", "warn"] = "log",
    max_correction_attempts: int = 2,
)
```

Parameter error policy:

- `raise`: emit `PARAM_FAIL`, raise `ToolValidationError`
- `log` / `warn`: emit `PARAM_FAIL`, continue
- `self_correct`: emit `PARAM_FAIL`, raise `ToolCorrectionNeeded` with correction payload

Response error policy:

- `raise`: emit `RESPONSE_FAIL`, raise `SchemaDriftError`
- `log` / `warn`: emit `RESPONSE_FAIL`, return original output

## Trace integrations

- `set_trace_sink(callable_or_none)` is supported (yes, trace sink is a real SDK feature)
- default logger: `optulus_anchor.tool_validator`
- statuses: `PASS`, `PARAM_FAIL`, `RESPONSE_FAIL`, `EXECUTION_FAIL`
- persistent DB path: `.trace/traces.sqlite`
- env controls:
  - `OPTULUS_ANCHOR_TRACE_DIR` to relocate trace root
  - `OPTULUS_ANCHOR_NO_TRACE=1|true|yes|on` to disable persistence
- runtime controls:
  - `disable_persistent_tracelog()`
  - `enable_persistent_tracelog()`

## CLI

- `anchor report --hours 24`
- summarizes recent call/failure counts and schema-drift hints from trace data

## Public exports

- `validate_tool`
- `set_trace_sink`
- `enable_persistent_tracelog`
- `disable_persistent_tracelog`
- `ToolValidationError`
- `SchemaDriftError`
- `ToolCorrectionNeeded`

## Full reference

See `llms-full.txt`.
