Metadata-Version: 2.4
Name: vindicara
Version: 0.2.0
Summary: Server-side engine behind Vindicara AIR Cloud. Not intended for direct pip install. The open-source developer SDK is `projectair` (https://pypi.org/project/projectair/).
Project-URL: Homepage, https://vindicara.io
Project-URL: Repository, https://github.com/get-sltr/vindicara-ai
Project-URL: Documentation, https://docs.vindicara.io
Author-email: Vindicara <eng@vindicara.io>
License-Expression: Apache-2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: httpx<1.0,>=0.27.0
Requires-Dist: pydantic-settings<3.0,>=2.3.0
Requires-Dist: pydantic<3.0,>=2.7.0
Requires-Dist: structlog<26.0,>=24.1.0
Provides-Extra: api
Requires-Dist: bcrypt<5.0,>=4.2.0; extra == 'api'
Requires-Dist: boto3-stubs[dynamodb,events,s3]<2.0,>=1.35.0; extra == 'api'
Requires-Dist: boto3<2.0,>=1.35.0; extra == 'api'
Requires-Dist: fastapi<1.0,>=0.115.0; extra == 'api'
Requires-Dist: jinja2<4.0,>=3.1.0; extra == 'api'
Requires-Dist: mangum<1.0,>=0.19.0; extra == 'api'
Requires-Dist: pyjwt<3.0,>=2.9.0; extra == 'api'
Requires-Dist: pyotp<3.0,>=2.9.0; extra == 'api'
Requires-Dist: python-multipart<1.0,>=0.0.9; extra == 'api'
Requires-Dist: qrcode<9.0,>=8.0; extra == 'api'
Requires-Dist: uvicorn<1.0,>=0.30.0; extra == 'api'
Provides-Extra: cdk
Requires-Dist: aws-cdk-lib<3.0,>=2.150.0; extra == 'cdk'
Requires-Dist: constructs<11.0,>=10.0.0; extra == 'cdk'
Provides-Extra: dev
Requires-Dist: hypothesis<7.0,>=6.100.0; extra == 'dev'
Requires-Dist: mypy<2.0,>=1.11.0; extra == 'dev'
Requires-Dist: pip-audit<3.0,>=2.7.0; extra == 'dev'
Requires-Dist: pytest-asyncio<1.0,>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov<6.0,>=5.0.0; extra == 'dev'
Requires-Dist: pytest<9.0,>=8.3.0; extra == 'dev'
Requires-Dist: ruff<1.0,>=0.6.0; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://vindicara.io/hero-mesh.png" alt="" width="100%">
</p>

<h1 align="center">Project AIR</h1>

<p align="center">
  <strong>Forensic reconstruction and incident response for AI agents.</strong><br>
  When your AI agent goes off-script, AIR tells you what happened and proves it.
</p>

<p align="center">
  <a href="https://vindicara.io">vindicara.io</a> ·
  <a href="https://vindicara.io/blog/secure-ai-agents-5-minutes">Quickstart</a> ·
  <a href="https://vindicara.io/pricing">Pricing</a> ·
  <a href="https://vindicara.io/blog">Blog</a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/python-3.12%2B-blue?style=flat-square" alt="Python 3.12+">
  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT">
  <img src="https://img.shields.io/badge/status-alpha-orange?style=flat-square" alt="Alpha">
</p>

---

## What AIR is

AIR writes a **signed forensic record** of every agent decision (llm, tool, finish) as an AgDR (AI Decision Record). Each record is content-hashed with BLAKE3, signed with Ed25519, and chained to the previous step. The `air` CLI replays the chain, verifies every signature, and reports OWASP Top 10 for Agentic Applications violations (5 of 10 detectors shipped today: ASI01, ASI02, ASI03, ASI05, ASI09. ASI04, ASI06, ASI07, ASI08, ASI10 on roadmap).

It is the layer that runs **behind** your guardrails. Prevention tools (Lakera, NeMo Guardrails, Bedrock Guardrails) try to stop bad things from happening. AIR produces the evidence of what actually happened, in a form security, legal, and insurance can act on.

## Install

```bash
pip install projectair
```

This installs both the `air` terminal command and the `airsdk` Python library.

## 10-second sanity check

```bash
air demo
```

Generates a fresh signed AgDR chain (13 steps, two baked-in ASI violations), verifies every signature, runs the detectors, and writes `forensic-report.json` next to you. No agent, no log file, no wiring required.

## 30-second usage

Instrument your LangChain agent:

```python
from airsdk import AIRCallbackHandler
from langchain.agents import AgentExecutor

handler = AIRCallbackHandler(
    key="...",                           # Ed25519 signing key; auto-generated when omitted
    log_path="my-agent.log",
    user_intent="Draft a Q3 sales report from the CRM data",
)
agent = AgentExecutor(callbacks=[handler], ...)
```

Every step the agent takes is appended to `my-agent.log` as a signed AgDR record.

Replay the trace:

```bash
air trace my-agent.log
```

You get a console report: signatures verified, ASI01/ASI02 findings flagged, detector coverage shown honestly, and `forensic-report.json` emitted alongside.

## What's in this repo

This is a monorepo.

- **[`packages/projectair/`](packages/projectair/)**: the MIT-licensed `projectair` package published to PyPI. Ships the `air` CLI and the `airsdk` Python library. This is the public, supported AIR surface.
- **[`site/`](site/)**: the SvelteKit source for [vindicara.io](https://vindicara.io).
- **`src/vindicara/`**: the older Apache-2.0 runtime security engine (policy evaluator, MCP scanner, agent IAM, drift monitor, compliance collector). This is now the engine substrate underneath AIR, not the public product surface. Retained for reference and for future integrations.

For the legacy five-pillar README that used to live here, see [`docs/legacy-vindicara-readme.md`](docs/legacy-vindicara-readme.md).

## Status

| Surface                                 | Status                    |
|-----------------------------------------|---------------------------|
| BLAKE3 + Ed25519 signed AgDR chain      | implemented, tested       |
| Tamper detection on chain replay        | implemented, tested       |
| LangChain `AIRCallbackHandler`          | implemented               |
| ASI01 Agent Goal Hijack detector        | implemented (heuristic)   |
| ASI02 Tool Misuse detector              | implemented (regex)       |
| ASI03 Prompt Injection detector         | implemented (heuristic)   |
| ASI05 Sensitive Data Exposure detector  | implemented (pattern set) |
| ASI09 Supply Chain / MCP Risk detector  | implemented (heuristic)   |
| ASI04, ASI06, ASI07, ASI08, ASI10       | not yet implemented       |
| JSON forensic export                    | implemented               |
| PDF forensic export                     | implemented (fpdf2)       |
| SIEM forensic export (ArcSight CEF v0)  | implemented               |
| LangChain callback integration          | implemented               |
| OpenAI SDK integration                  | implemented               |
| Anthropic, LlamaIndex, CrewAI, AutoGen  | not yet implemented       |
| AIR Cloud (hosted dashboards, SIEM)     | not yet implemented       |

Pre-1.0. The detector heuristics will produce false positives and false negatives. The signed chain itself is production-grade cryptography. See the [pricing page](https://vindicara.io/pricing) for what's planned next.

## Contributing

Issues, traces that break the detectors, and new ASI detector PRs are welcome. Bugs and feature requests: https://github.com/get-sltr/vindicara-ai/issues.

## License

- `packages/projectair/` and the `projectair` PyPI distribution: **MIT**. See [`packages/projectair/LICENSE`](packages/projectair/LICENSE).
- `src/vindicara/` (engine substrate, not published): **Apache-2.0**.
