Get Started

First forensic report
in under 5 minutes

From install to signed evidence chain. Works on macOS, Windows, and Linux.

0

Prerequisites

›

Python 3.10 or newer

macOS ships with Python 3 on recent versions. Check with python3 --version. If not installed, the fastest path:

# Option A: Homebrew (recommended)
brew install python@3.13
# Option B: Official installer
https://www.python.org/downloads/macos/
›

pip or pipx

pip works in any virtual environment. pipx installs the air CLI globally without polluting your system Python.

brew install pipx && pipx ensurepath
1

Install Project AIR

Choose one method. Both give you the air CLI and airsdk library.

pipx (recommended)

Global CLI

Isolated install. Does not touch your project venv.

pip

In venv

Inside a virtual environment or project.

2

Verify the install

terminal
$ air --version
projectair 1.0.x
$ air demo
[AIR] Generating signed forensic chain...
[AIR] 14 detectors evaluated, 6 findings
[AIR] Chain verified. Report saved to forensic-report.json

air demo generates a real signed chain, runs the 14 offline detectors (16 in the full taxonomy; the 2 NemoGuard detectors activate with an NVIDIA NemoGuard NIM), and exports a forensic report. No API key, no cloud, no config. Under 30 seconds.

3

Instrument your agent

The recorder writes signed, tamper-evident records to a local JSONL chain. Every call is an Intent Capsule: BLAKE3-hashed, Ed25519-signed, forward-chained.

from airsdk import AIRRecorder

recorder = AIRRecorder("chain.jsonl")

recorder.llm_start(prompt="Analyze this data...")
recorder.llm_end(response="Here is the analysis...")

recorder.tool_start(tool_name="db_query", tool_args={"sql": "SELECT ..."})
recorder.tool_end(tool_output="42 rows returned")

recorder.agent_finish(final_output="Task complete")
4

Framework integrations

Already using a framework? One-line instrumentation. Same signed chain, zero boilerplate.

OpenAI

from airsdk.integrations import instrument_openai
instrument_openai(client, recorder)

Anthropic

from airsdk.integrations import instrument_anthropic
instrument_anthropic(client, recorder)

LangChain

from airsdk import AIRCallbackHandler
agent.run("task", callbacks=[AIRCallbackHandler(recorder)])

Google Gemini

from airsdk.integrations import instrument_gemini
instrument_gemini(client, recorder)

Google ADK

from airsdk.integrations import instrument_adk
instrument_adk(agent, recorder)

LlamaIndex

from airsdk.integrations import instrument_llamaindex
instrument_llamaindex(llm, recorder)

Any OpenAI-compatible endpoint (NVIDIA NIM, vLLM, Together AI, Groq, Fireworks) also works via instrument_openai.

5

Analyze and export

terminal
# Verify signatures + run the offline detectors (14 of 16)
<span class="text-brand-red">$</span> air trace chain.jsonl
# Verify using only public infrastructure (no Vindicara dependency)
<span class="text-brand-red">$</span> air verify-public chain.jsonl
# Generate EU AI Act Article 72 compliance report
<span class="text-brand-red">$</span> air report article72
# Causal explanation for a specific finding
<span class="text-brand-red">$</span> air explain --finding ASI02

CLI Reference

air demo Run the full demo (30 seconds, zero setup)
air demo --healthcare HIPAA-aligned clinical AI demo
air trace chain.jsonl Verify signatures, run detectors, export report
air verify-public chain.jsonl Verify using only public infrastructure
air explain --finding ASI02 Causal explanation for a finding
air verify-intent chain.jsonl Did the agent honor its declared intent?
air report article72 Generate EU AI Act Article 72 report

Troubleshooting

air command not found

If you used pipx, run pipx ensurepath and restart your shell. If you installed with pip inside a venv, make sure the venv is activated. As a fallback: python3 -m projectair.cli demo.

Python version too old

Project AIR requires Python 3.10+. Check with python3 --version. If you have multiple versions, use python3.13 -m pip install projectair to target the right one.

Permission errors on install

Never use sudo pip install. Use pipx (installs to ~/.local/) or create a virtual environment: python3 -m venv .venv && source .venv/bin/activate && pip install projectair.

Still stuck?

Open an issue on GitHub or email support@vindicara.io.

Ready for more?

Full documentation, architecture deep-dives, and the complete API reference live on GitHub.

Read the docs See pricing