# 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**: `184ms` median, end-to-end; 3,000+ decisions/hr per tenant. 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 ` 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.