Metadata-Version: 2.4
Name: vijil-sdk
Version: 0.0.1
Summary: Vijil SDK & CLI — measure and improve AI agent trustworthiness
Author: Vijil AI
Author-email: eng@vijil.ai
Requires-Python: >=3.12,<3.14
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: httpx (>=0.27.0)
Requires-Dist: pydantic (>=2.10.0,<3.0.0)
Requires-Dist: tomli-w (>=1.1.0,<2.0.0)
Description-Content-Type: text/markdown

# Vijil SDK & CLI

Measure and improve AI agent trustworthiness from your terminal or Python code.

Vijil provides a unified trust layer for the entire agent lifecycle — from discovery through deployment. Evaluate your agent against known standards, test it under adversarial pressure, adapt it to fix weaknesses, and protect it with runtime Guardrails.

## Install

```bash
pip install vijil-sdk
```

Requires Python 3.12+. Installs both the `vijil` CLI and the `vijil` Python SDK.

**Using Vijil from Claude Desktop, Cursor, or other MCP-aware agent frameworks?** See [`vijil-mcp`](https://github.com/vijilAI/vijil-mcp) — a separate package that exposes the Vijil platform as MCP tools. The SDK and the MCP server are independent: `vijil-sdk` runs in your Python process; `vijil-mcp` runs as a stdio server attached to your agent framework.

**Migrating from the legacy `vijil` PyPI package (pre-2026)?** See [`docs/migration-from-legacy-vijil.md`](docs/migration-from-legacy-vijil.md) for the install change, auth flow change, and command-by-command map.

## Authenticate

Create an API key at [console.vijil.ai](https://console.vijil.ai) > **Settings** > **API Keys** — a client ID (`vk_…`) plus a one-time secret. Export the pair; the SDK exchanges it for a short-lived access token automatically:

```bash
export VIJIL_CLIENT_ID="vk_..."
export VIJIL_CLIENT_SECRET="..."   # shown once at creation
```

Already have a bearer access token? Use it directly instead — `vijil auth login` saves one, or set it in the environment:

```bash
vijil auth login                   # paste an access token; saved to ~/.vijil/credentials.json
export VIJIL_API_KEY="<access-token>"
```

## Quick start: CLI

```bash
# Evaluate against standard trust Harnesses
vijil evaluate <agent-id> --baseline

# Test under adversarial pressure (Swarm)
vijil test <agent-id> --adaptive

# View trust scores
vijil scores show <agent-id>

# Configure runtime Guardrails
vijil protect <agent-id> --guards prompt_injection,pii --mode enforce

# Improve the agent through corrective evolution
vijil adapt <agent-id> --mode config
```

## Quick start: SDK

```python
from vijil import Vijil

client = Vijil()

# Evaluate and wait for results
evaluation = client.evaluate("my-agent", baseline=True)
print(f"Trust score: {evaluation.trust_score}")
print(f"Reliability: {evaluation.dimensions.reliability}")
print(f"Security:    {evaluation.dimensions.security}")
print(f"Safety:      {evaluation.dimensions.safety}")

# Test under adversarial pressure
job = client.test("my-agent", mode="adaptive")
print(f"Test status: {job.status}")

# Configure Guardrails
dome = client.protect("my-agent", guards=["prompt_injection", "pii"])

# Improve the agent
job = client.adapt("my-agent", mode="config")
```

## How it works

The CLI and SDK are organized into two tiers, inspired by Git:

### Porcelain commands (lifecycle verbs)

High-level commands that map to stages of the agent trust lifecycle:

| Command | What it does |
|---------|-------------|
| `vijil discover` | Find agents in GitHub repos or cloud infrastructure |
| `vijil register` | Convert agent source into an A2A card and genome |
| `vijil evaluate` | Measure against known standards (criterion-referenced) |
| `vijil test` | Explore under adversarial pressure (Swarm) |
| `vijil adapt` | Improve through corrective evolution (prompt, config, code, Dome) |
| `vijil protect` | Configure Dome runtime Guardrails |
| `vijil monitor` | View Dome telemetry (detections, traces, logs) |
| `vijil evolve` | Create a new agent through generative evolution |
| `vijil deploy` | Deploy to a production runtime |

### Plumbing commands (resource nouns)

Low-level CRUD operations on platform resources:

| Command | Subcommands |
|---------|------------|
| `vijil agents` | `list`, `show`, `create`, `update`, `delete` |
| `vijil evaluations` | `list`, `show` |
| `vijil harnesses` | `list`, `show`, `create`, `update` |
| `vijil genomes` | `list`, `show`, `diff`, `history` |
| `vijil jobs` | `list`, `status`, `cancel` |
| `vijil scores` | `show`, `history` |
| `vijil reports` | `list`, `show`, `download` |
| `vijil proposals` | `list`, `show`, `approve`, `apply`, `reject` |
| `vijil policies` | `list`, `show`, `create`, `update`, `delete` |
| `vijil personas` | `list`, `show`, `create`, `update`, `delete` |

### Setup commands

| Command | What it does |
|---------|-------------|
| `vijil auth` | `login`, `logout`, `status` |
| `vijil config` | `show`, `get`, `set` |

## Key concepts

**Evaluate vs Test**: `evaluate` measures against known standards (like a certification exam). `test` explores for unknown weaknesses through adversarial pressure (like a penetration test). Both produce trust scores.

**Adapt vs Evolve**: `adapt` improves an existing agent through corrective evolution, fixing weaknesses found by evaluation or testing. `evolve` creates an entirely new agent from a spec or natural-language description.

**Trust dimensions**: Every evaluation produces scores across three dimensions — **reliability** (does it work correctly?), **security** (can it resist exploitation?), and **safety** (does it behave responsibly?).

## Global options

```
--output, -o    Output format: table, json, yaml, quiet (default: auto)
--gateway       Gateway URL override
--api-key       API key override (or set VIJIL_API_KEY)
--quiet, -q     Quiet mode — IDs only
--verbose, -v   Debug logging
```

## Shell composability

The CLI supports shell scripting:

```bash
# JSON output for machine consumption
vijil evaluate my-agent --baseline -o json | jq '.trust_score'

# Quiet mode returns just the ID
EVAL_ID=$(vijil evaluate my-agent --baseline -q)
vijil reports download "$EVAL_ID"

# Pipe agent list to evaluation
vijil agents list -q | xargs -I{} vijil evaluate {} --baseline --no-wait
```

Exit codes follow Unix convention:

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Authentication error |
| 3 | Resource not found |
| 4 | Validation error |
| 5 | Job failed |

## Agent aliases

Set short names for agent IDs you use often:

```bash
vijil config set aliases.travel-agent d0087de1-a032-49f7-9d28-3abf4a34404d

# Now use the alias anywhere
vijil evaluate travel-agent --baseline
vijil scores show travel-agent
```

## Framework integrations

> **Coming soon** — Guides for integrating Vijil into agent development frameworks:
>
> - **Google ADK** — Evaluate and protect ADK agents
> - **LangGraph** — Add trust checks to LangGraph workflows
> - **CrewAI** — Monitor and adapt CrewAI agents
>
> See [docs/integrations/](docs/integrations/) for the roadmap.

## Documentation

| Document | Description |
|----------|-------------|
| [Configuration](docs/configuration.md) | Auth setup, config file, credentials, CI/CD |
| [CLI Reference](docs/cli-reference.md) | All commands with flags and examples |
| [SDK Reference](docs/sdk-reference.md) | Python client, resources, models, errors |
| [Lifecycle Guide](docs/lifecycle-guide.md) | End-to-end workflows for existing and new agents |
| [Testing Guide](docs/testing-guide.md) | Running unit and integration tests |
| [Integrations](docs/integrations/) | Framework integration guides |

## Requirements

- Python 3.12+
- A Vijil account ([console.vijil.ai](https://console.vijil.ai))

## License

Proprietary. Copyright 2024-2026 Vijil AI, Inc.

