# CogNEXUS Labs Developer Reference

ArtzAIn is the model-agnostic agent control plane. CogNEXUS Labs builds it. `artzain` is the Python client you install to talk to it; `@cognexuslabs/artzain` is the TypeScript client on npm.

The `artzain` SDK is free to install and run locally. The ArtzAIn control plane is an enterprise deployment ([request a pilot](https://cognexuslabs.ai/artzain#pilot)).

This file is the current source of truth for the public SDK surface, versioned with the package.

## Links

- Website: https://cognexuslabs.ai
- ArtzAIn: https://cognexuslabs.ai/artzain
- Dashboard: https://app.cognexuslabs.ai
- PyPI: https://pypi.org/project/artzain/
- npm: https://www.npmjs.com/package/@cognexuslabs/artzain
- Source: https://github.com/CogNEXUSlabs/cognexus-tools
- Support: hello@cognexuslabs.ai

## Installation

```
pip install artzain
pip install --upgrade artzain
artzain quickstart    # signup + starter integration
artzain login         # existing account
```

Python first (`artzain`, previously published as `cognexus`). A remote-only TypeScript client for Node ≥ 18 ships as `@cognexuslabs/artzain`:

```
npm i @cognexuslabs/artzain
```

Supply chain: PyPI releases publish via a Trusted Publisher (OIDC, no long-lived secrets); npm releases carry a provenance attestation bound to the public repo. The guards derive from Microsoft's MIT-licensed agent-governance-toolkit, with attribution.

## Key capabilities

- **Prompt Defender**: build-time + runtime prompt-injection screening (LLM01 in the OWASP Top 10 for LLM Applications), graded A to F. `augment_system_prompt()` takes prebuilt `RuleSet.FINANCIAL` / `RuleSet.LEGAL` safeguards.
- **Client Policy Enforcement**: actions cleared against configurable enterprise rules: your policy bundle's rules on every decision, or rules derived from your policy documents, screened locally with `screen_client_policy()`.
- **Destructive-Action Guard**: screens SQL / shell / git / cloud actions by severity (low → critical).
- **Agent Kill Switch**: panic-threshold auto-stop. A `critical` match in `screen_agent_action(payload, run_id=...)` trips that run and raises `AgentKilledError`, and `raise_if_killed(run_id)` stops a tripped run at its next check. By default, five critical trips within 60 seconds in one process trip a global panic that stops every run until `clear_global_panic()`, as `trip_global()` does by hand. `screen_action()` only screens; it never trips the kill switch. A kill-switch *event*, not a verdict.
- **Signed Decision Records**: with an API key, each `decide()` decision is Ed25519-signed into an append-only, hash-chained ledger before it returns. Exported evidence verifies offline with `artzain audit verify`, which today reports `SELF-ATTESTED` (see Receipt verification).
- **Performance**: decides in the path of the action, before it runs. Throughput limits depend on the plan.

Delegation of Authority is the governance framing these controls implement (the agent's row on your DOA matrix), not a separate shipping feature.

## Verdicts

`allow` · `deny` · `review`, lowercase. `decide()` returns the verdict as `outcome`. With an API key, the decision is sealed into the hash-chained, Ed25519-signed audit ledger before it returns, and `audit_block_id` names the leaf. With no key, `decide()` runs the local guards only, `audit_block_id` is `None`, and nothing is sealed.

`kill` is not a fourth verdict. A kill-switch trip is an *event*, and your code sees it as `AgentKilledError`.

## SDK surface

### Decisions

`decide()` · `DecisionError`

### Screening

`screen_user_input()` · `evaluate_system_prompt()` · `augment_system_prompt()` · `screen_external_content()`

### Enforcement

`screen_client_policy()` · `screen_action()` · `screen_agent_action()` · `should_block()`

### Kill switch

`trip_global()` · `raise_if_killed()`

### Audit

`verify_chain()` · `post_generation_outcome()`

## Tool calls

ArtzAIn does not hook your LLM client, and nothing intercepts tool calls automatically. `decide()` goes in the gap between the model proposing a tool call and your code executing it: `action` is the tool name, `target` is the resource read out of the arguments, `payload` is the whole call as JSON (`{"tool": name, "arguments": {...}}`), and `kind` is `"tool_call"`. Only `allow` runs the tool. `decide()` raises `DecisionError` on any non-2xx response or when the engine cannot be reached; treat it as `deny`.

Gate the dispatcher rather than each call site, so tools added later are covered by construction. To make a forgotten tool stop instead of run, declare the known tools in the policy bundle's `tool_contracts` with `"*": {"deny_unknown_tools": true}` and escalate the finding with `"resolution": {"medium": "review"}`, which escalates every `medium` vote, not only this one. Offline (no API key), `decide()` runs the local guards only: nothing is sealed, and the shape check and bundle do not apply.

OpenAI and Anthropic loops, both coverage patterns, and choosing what to gate: https://cognexuslabs.ai/install#tool-calls

## AWS deployment

Two insertion points. Before the LLM (Bedrock or external) is called, screen the input with `screen_user_input(text, source=...)` and refuse it when `should_block()` returns `True`. Before any action or data write, gate the proposed call with `decide()` and run it only on `allow`. Inside a step that runs raw SQL or shell, also call `screen_agent_action(payload, run_id=...)`: a `critical` match trips the kill switch for that run. Call `raise_if_killed(run_id)` between steps so a tripped run stops.

Both insertion points as code: https://cognexuslabs.ai/artzain/developers#reference

## Receipt verification

`artzain audit verify <bundle>` checks an evidence bundle exported with `artzain audit export`, with no network. It recomputes every leaf hash, checks chain linkage and Merkle roots, and verifies Ed25519 signatures against the public keys inside the bundle. Signature checks need `pip install "artzain[verify]"`; without it they are reported as skipped and the verdict is capped at `SELF-ATTESTED`. Tamper with a leaf and verification fails, naming the sequence number that broke.

An intact bundle verifies as `VERIFIED, SELF-ATTESTED`: the signatures prove the bundle is intact and internally consistent, not which key holder produced it. `VERIFIED, ATTESTED` additionally requires the signing key to chain to the pinned CogNEXUS Evidence Root, and only then does verification need no trust in the producing server. As of `artzain` 0.6.19 that root is not pinned yet, so every bundle verifies `SELF-ATTESTED`.

`verify_chain(path)` is a different check. It verifies the hash chain and HMAC signatures of the SDK's local guard-event log, and those signatures verify only with the `COGNEXUS_AUDIT_HMAC_KEY` that wrote them.
