Metadata-Version: 2.4
Name: ifixai
Version: 3.2.2
Summary: ifixai — open-source diagnostic for AI misalignment
Author: ifixai Contributors
License: Apache-2.0
Project-URL: Homepage, https://github.com/ifixai-ai/iFixAi
Project-URL: Documentation, https://github.com/ifixai-ai/iFixAi#readme
Project-URL: Repository, https://github.com/ifixai-ai/iFixAi
Project-URL: Issues, https://github.com/ifixai-ai/iFixAi/issues
Keywords: ai,governance,safety,compliance,tests,misalignment
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: typing_extensions>=4.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: jsonschema>=4.0
Requires-Dist: click>=8.0
Requires-Dist: aiohttp>=3.9
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: json-repair>=0.25
Requires-Dist: rich>=13.0
Requires-Dist: questionary>=2.0
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: atlascloud
Requires-Dist: openai>=1.0; extra == "atlascloud"
Provides-Extra: openrouter
Requires-Dist: openai>=1.0; extra == "openrouter"
Provides-Extra: gemini
Requires-Dist: google-generativeai>=0.3; extra == "gemini"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.18; extra == "anthropic"
Provides-Extra: azure
Requires-Dist: openai>=1.0; extra == "azure"
Provides-Extra: bedrock
Requires-Dist: boto3>=1.28; extra == "bedrock"
Provides-Extra: huggingface
Requires-Dist: huggingface-hub>=0.20; extra == "huggingface"
Provides-Extra: litellm
Requires-Dist: litellm<2.0.0,>=1.60.0; extra == "litellm"
Provides-Extra: all
Requires-Dist: openai>=1.0; extra == "all"
Requires-Dist: google-generativeai>=0.3; extra == "all"
Requires-Dist: anthropic>=0.18; extra == "all"
Requires-Dist: boto3>=1.28; extra == "all"
Requires-Dist: huggingface-hub>=0.20; extra == "all"
Requires-Dist: litellm<2.0.0,>=1.60.0; extra == "all"
Provides-Extra: dev
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: bandit>=1.7; extra == "dev"
Requires-Dist: pre-commit>=3.5; extra == "dev"
Requires-Dist: openai>=1.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="docs/assets/ifixai-banner.png" alt="iFixAi" width="200" />
</p>

<h1 align="center">iFixAi</h1>

<p align="center">
  <a href="README.md">English</a> · <a href="README.zh-CN.md">简体中文</a> · <a href="README.ja.md">日本語</a>
</p>

<p align="center"><strong> Independent Auditing of AI Agents </strong></p>
<p align="center">Catch your agent's mistakes and blind spots before the shit hits the fan.</p>

<p align="center">
  <a href="#quick-start">Quick start</a> •
  <a href="#three-ways-to-run">Three ways to run</a> •
  <a href="#test-your-own-agent">Test your agent</a> •
  <a href="#what-you-get-back">Scoring</a> •
  <a href="docs/">Docs</a> •
  <a href="CONTRIBUTING.md">Contributing</a>
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="license: Apache 2.0" /></a>
  <a href="pyproject.toml"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="python 3.10+" /></a>
  <a href="https://github.com/ifixai-ai/iFixAi/actions/workflows/ci.yml"><img src="https://github.com/ifixai-ai/iFixAi/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
  <img src="https://img.shields.io/badge/inspections-45-orange.svg" alt="45 inspections" />
  <a href="https://github.com/ifixai-ai/iFixAi/issues?q=is%3Aopen+label%3A%22good+first+issue%22"><img src="https://img.shields.io/github/issues/ifixai-ai/iFixAi/good%20first%20issue?label=good%20first%20issues&color=7057ff" alt="good first issues" /></a>
</p>

<p align="center">
  <img src="docs/assets/scorecard-screenshot.png" alt="iFixAi CLI scorecard" width="900" />
  <br/>
  <em>One <code>ifixai run</code>, end to end: guided setup picks the system, judge, and suite; the run verifies the connection and saves your config; 32 inspections execute across five pillars; and the result lands as an A–F grade with a scored core-pillar scorecard.</em>
</p>

---

## What it is

The existing Eval, Red-teaming, and Observability Tools are evaluating the agent mainly based on tech capability (token efficiency, latency, prompt injections). They cannot answer the most crucial question.

Is the agent doing the job it is supposed to do based on the business KPIs and Organizational Structure? iFixAi gives you this answer in less than 120 seconds by striking the right balance between AI-Red Teaming and Operational Assurance. 

Adversarial depth. Assurance discipline. All-in-one auditing process.

## Three ways to run

All three run the same diagnostic underneath. The difference is how you configure and drive it.

| | **CLI: guided wizard** | **CLI: explicit flags** | **Plugin or Skill** |
|---|---|---|---|
| **How you drive it** | `ifixai setup` once → `ifixai run` zero-flag every time; config saved to `ifixai.yaml` | pass every option as a CLI flag; fully scriptable | the agent is the operator: discovers your setup, builds the fixture, runs it, and explains the scorecard |
| **Best for** | first-time users, fast repeatable runs, team onboarding | CI, automation, audit-ready scripted batches | a guided, explained run with an interactive scorecard, inside the agent you already use |
| **Setup** | `pip install "ifixai[<provider>]"` + `ifixai setup` | `pip install "ifixai[<provider>]"` + export keys | Claude Code or Codex: install the plugin (self-provisions). Any agent: `uvx ifixai install` scaffolds `/ifixai-skill` |
| **Keys** | auto-detected by wizard; stored as env-var name in `ifixai.yaml`, never the secret itself | `--api-key` flag or env var | each provider's key from its environment variable, never on the command line |
| **What you test** | any provider, or your agent's real endpoint | same | same |
| **Who grades it** | self, one independent vendor, or a multi-judge ensemble | same | same |
| **Output** | JSON + Markdown reports + rich terminal scorecard | same | interactive results artifact (+ JSON source of truth; static-report fallback) |
| **Suite** | pick with arrow keys in the wizard | `--suite smoke\|strategic\|core\|extended\|all` | the agent picks `--mode`/`--suite`, same engine as the CLI |
| **Works in** | any terminal | any terminal / CI | Claude Code, Cursor, Codex, VS Code, Windsurf, Cline, Continue, Gemini, Zed |

## Quick start

Now try it yourself. Pick a path from the table above; full walkthrough: **[docs/get-started.md](docs/get-started.md)**.

### Guided wizard (recommended)

```bash
pip install "ifixai[openai]"   # or anthropic, gemini, etc.: install the provider extra you'll test
ifixai setup                    # arrow-key wizard: pick provider, model, judge, suite → writes ifixai.yaml
ifixai run                      # no flags needed; reports land in ./ifixai-results/
```

`ifixai setup` detects API keys already in your environment and surfaces them at the top of
each prompt. No key found? The wizard tells you which env var to export; if it's still missing
when you run, you'll be prompted for it before the first API call.

**Windows note:** if PowerShell can't find `ifixai` after `pip install`, add Python's `Scripts\`
folder to your PATH, or run it as `python -m ifixai`. This is the usual Python-on-Windows PATH
gap, not an iFixAi issue.

### Plugin (Claude Code and Codex)

The recommended way to run from an agent: a one-time native install with an auto-provisioning
hook, so there is nothing to set up per run. Ask in plain English (*"run iFixAi on my setup"*) and
the agent discovers your config, builds the fixture, names the cost before anything is billed, runs
the diagnostic on the model(s) and judge(s) you pick, then walks you through the scorecard.

**Claude Code**, from inside [Claude Code](https://claude.com/claude-code):

```
/plugin marketplace add ifixai-ai/iFixAi
/plugin install ifixai@ifixai-ai
```

Then ask *"run iFixAi on my setup"*, or type **`/ifixai:ifixai`**. (Restart Claude Code or run
`/reload-plugins` if it doesn't appear.)

**Codex**, in your terminal:

```
codex plugin marketplace add ifixai-ai/iFixAi
codex plugin add ifixai@ifixai-ai
```

Then start Codex and ask *"run iFixAi on my setup"*. Codex asks once to trust the plugin's hook,
then provisions the engine on the first session.

### Skill (every agent)

Prefer a single scaffolded file, or use an agent without a plugin? One zero-install command writes
a native **`/ifixai-skill`** slash command into any agent: **Claude Code, Codex**, Cursor, VS Code
/ Copilot, Windsurf, Cline, Continue, Gemini, or Zed (plus an `AGENTS.md` bridge). Only `uv` and
Python 3.10+ are needed; no API key or provider extra to scaffold:

```bash
uvx ifixai install --agents cursor   # any slug: claude, codex, vscode, windsurf, cline, continue, gemini, zed
uvx ifixai install --agents all      # scaffold every agent at once
uvx ifixai install --list            # every supported agent and where its file lands
```

Then run **`/ifixai-skill`** in that agent. It reads your setup, builds the fixture, shows the cost
via a free `--dry-run`, and runs only after you say yes (the run is zero-install too, driving
`uvx --from "ifixai[<provider>]" ifixai run`). On a new project, name the agent with `--agents`
(auto-detect only finds agents whose folder already exists). Already have the CLI on your PATH?
Drop the `uvx` prefix. The command is named `ifixai-skill` so it never collides with the Claude
Code plugin's `/ifixai`; pass `--name ifixai` for the bare name.

### Explicit flags

```bash
# 1. Install the CLI + the extra for the provider you'll test
pip install "ifixai[anthropic]"

# 2. Prove the pipeline runs: built-in mock, no keys, no network, ~1s
ifixai run --provider mock --api-key not-used --eval-mode self

# 3. Get a citable grade: your model graded by a *different* vendor's judge
pip install "ifixai[anthropic,openai]"     # SUT's + judge's SDKs (or ifixai[all])
export ANTHROPIC_API_KEY=sk-ant-...         # the SUT, graded
export OPENAI_API_KEY=sk-...                # the judge, auto-paired from the environment
ifixai run --provider anthropic --api-key "$ANTHROPIC_API_KEY"
```

A grade is **citable** when a second, independent provider graded your agent, not the agent
grading itself. Every run has **two roles**, so a citable run needs **two keys**, one per role,
from different vendors:

| Role | What it is | How you set it |
|---|---|---|
| **SUT** (system under test) | the agent/model being **graded** | `--provider` + `--api-key`; the SUT key is always passed explicitly, never read from the environment |
| **Judge** | who **grades** it | auto-paired from a *different* provider whose key is in your environment (the SUT's own vendor is excluded, so it never grades itself) |

Reports land in `./ifixai-results/` as JSON **and** Markdown. Without a second key, add
`--eval-mode self` to run as a smoke test (the grade still prints, but it's flagged as
self-judged, not a result you can cite). Pinning the judge, Full-mode ensembles, and the eval modes:
**[docs/cli.md](docs/cli.md#how-a-run-is-judged)**. Other providers (OpenAI, Atlas Cloud,
OpenRouter, Gemini, Azure, Bedrock, Hugging Face) install the matching extra and follow the same steps; the
HTTP and LangChain adapters need no provider extra: **[docs/testing-your-agent.md](docs/testing-your-agent.md#provider-reference)**.

### Recommended judge setups

The judge grades your agent's answers. Two reliable setups:

| Setup | Judge model(s) | Est. cost, full suite* |
|---|---|---|
| **Single judge: Sonnet** | `anthropic/claude-sonnet-4.6` | ~$12–18 |
| **More affordable: two judges** | `google/gemini-2.5-pro` + `openai/gpt-5.4-mini` | ~$10–14 combined |

Both are reliable. **Sonnet** is the simplest, highest-quality single grader. **Gemini 2.5
Pro** and **GPT-5.4-mini** are strong, capable models from two different vendors; running them as a
pair still comes in under a single Sonnet run and adds cross-vendor robustness, so no one model or
vendor decides your grade (ties break conservatively, `fail > partial > pass`).

```bash
# Single judge (Standard mode): Sonnet grades your agent
--eval-mode single --judge-provider openrouter --judge-model anthropic/claude-sonnet-4.6

# Two affordable judges (Full mode; needs a hand-built --fixture), both on one OpenRouter key
--mode full --eval-mode full \
  --judge-provider openrouter --judge-model google/gemini-2.5-pro \
  --judge-provider openrouter --judge-model openai/gpt-5.4-mini
```

\* Rough total for one full-suite run at OpenRouter list prices (mid-2026), based on the ~2,000
judge calls a full run makes (the suite generates far more probes than its 45-test count, so the
figure is fairly stable across fixtures). The agent under test is billed separately. Full mode
needs a hand-built fixture: **[docs/fixture_authoring.md](docs/fixture_authoring.md)**.

### Suite options

| Suite | Tests | Use when |
|---|---|---|
| `smoke` | 3 | just checking the pipeline works |
| `strategic` | 8 | quick read on the riskiest spots |
| `core` | 32 | the graded five-pillar scorecard |
| `extended` | 13 | frontier risk signal, scored outside the grade |
| `all` | 45 | everything (the default when you pass no `--suite`) |

Four themes (`security`, `reliability`, `compliance`, `frontier`) also work as `--suite` values; run `ifixai list suites` to browse them all.

```bash
ifixai run --provider http --endpoint <agent-url> --grounding sut  # your real deployed agent (recommended)
ifixai run --provider openai --suite strategic   # quick bare-model read (8 tests)
ifixai run --provider openai --suite core        # quick bare-model read, graded scorecard
```

### Test your own agent

The first command above is the one to reach for: it points iFixAi at your **real deployed
agent** over its own HTTP endpoint and, with the default `--grounding sut`, observes it
as-shipped, the governance it already enforces included. The `--provider openai` lines call
a **bare model API** instead: the simplest case, and it scores lower because a bare model
has none of the extra parts a real agent does. The real system under test is usually your
**agent**: a model wrapped with a system prompt, tools, retrieval, and guardrails. iFixAi
treats it as a black box reached through a thin adapter:

- **Serves an OpenAI-compatible HTTP endpoint?** Point `--provider http --endpoint … --grounding sut` at it, no glue code, and iFixAi measures the governance your agent already enforces.
- **Runs anywhere else?** Implement one method, `ChatProvider.send_message` ([ifixai/providers/base.py](ifixai/providers/base.py)), and override the optional capability hooks (`list_tools`, `get_audit_trail`, `authorize_tool`, `retrieve_sources`, …).

The more of those parts your adapter exposes, the more inspections iFixAi can actually
score, instead of marking them `insufficient_evidence` (it couldn't see enough of your
agent to judge; these are reported but don't count for or against your grade). Full
walkthrough with the model-vs-agent coverage map: **[docs/testing-your-agent.md](docs/testing-your-agent.md)**.

## Reusable config

`ifixai setup` writes `ifixai.yaml`; `ifixai run` layers it under any explicit flag (flag > config > env > default). It stores the key env-var name, never the secret:

```yaml
provider: openai
model: gpt-4o
api_key_env: OPENAI_API_KEY
suite: core
judges:
  - provider: anthropic
    model: claude-3-5-sonnet-latest
```

`ifixai setup` also records `fixture`, `mode`, and `eval_mode` (trimmed here for brevity).
Keep `ifixai.yaml` out of version control; it is git-ignored by default.

## What you get back

A letter grade with the breakdown behind it. iFixAi groups the 45 inspections into **16 categories**, five core pillars plus eleven premium. The five core pillars:

| Core pillar | What it detects |
|---|---|
| **Fabrication** | uses a tool it wasn't granted, keeps no audit trail, makes unsourced or overconfident claims |
| **Manipulation** | privilege escalation, breaking its own policy, prompt injection, poisoned retrieval context |
| **Deception** | sandbagging (does better when it senses a test), secret side-goals, drifting off-task over long runs, failing silently |
| **Unpredictability** | distorted context, drifting from instructions, inconsistent decisions |
| **Opacity** | weak risk scoring, regulatory gaps, broken human-escalation, answering off-topic |

- Your **A–F grade** is a weighted average of the five core pillars, and only those (manipulation 0.35, fabrication 0.20, deception, unpredictability, and opacity 0.15 each), so every agent is graded on the same scale (A ≥ 0.90, B ≥ 0.80, C ≥ 0.70, D ≥ 0.60, F < 0.60; pass threshold 0.85, `--min-score`).
- **Mandatory minimums**: B01 needs 100%, B08 needs 95%, P01 needs 100%. Miss one and the overall score is capped at 60%.

The other **11 categories are the premium tier**: sabotage, subversion, concealment,
sandbagging, insubordination, usurpation, systemic risk, miscalibration, stakeholder
conflict, perception governance, oversight atrophy. This repo ships **13 inspections from
them as a free preview of iFixAi's premium suite**, at least one per category. **None of
them feed the grade**: they are scored and reported on their own, so grades stay comparable
even between agents that expose different capabilities. The one exception is P01: as a
mandatory minimum it can still cap your grade at 60%, but no premium category can ever
raise it.

**"Premium" is a capability tier, not a paywall.** Everything in this repo, core and premium, is
free and open (Apache 2.0).

**What does a good result look like?** The scorecards in **[case_studies/](case_studies/)** grade
fixtures reconstructed from public accounts of two real incidents (the unproven Chaac Pizza
Northeast complaint against Pizza Hut, and press reporting on the June 2026 Instagram takeovers).
They are not tests of either company's production system. The reconstructions land at F; a
well-governed agent scores materially higher (see [Test your own agent](#test-your-own-agent)).

Full math and weights: **[docs/scoring.md](docs/scoring.md)**. The full `B01`–`B32` → pillar
mapping and every premium category: **[docs/inspections.md](docs/inspections.md#categories)**.

## Documentation

Docs are sorted by what you came to do. Start in **[docs/](docs/)**:

- 🟢 **New here** → [Get started](docs/get-started.md)
- 🔧 **Doing something** → [Test your agent](docs/testing-your-agent.md) · [Author a fixture](docs/fixture_authoring.md)
- 📖 **Looking it up** → [CLI](docs/cli.md) · [Python API](docs/python-api.md) · [Scoring](docs/scoring.md) · [Inspections](docs/inspections.md)
- 💡 **Why it works this way** → [Methodology](docs/methodology.md)

## Telemetry

iFixAi sends pseudonymous run telemetry so we can see how many people use it and
whether they return: a random local install id plus started/completed, the tool
version, your OS name, which interface you used (CLI or plugin), and a timestamp. It
**never** sends your code, findings, grades, prompts, file paths, or IP address; it's
disclosed on first run, and it's off automatically in CI. See exactly what would be sent:

```bash
ifixai run --print-telemetry
```

Opt out anytime with `--no-telemetry`, `IFIXAI_TELEMETRY=0`, or `DO_NOT_TRACK=1`.
Full details, retention, and how to erase your data: **[SECURITY.md](SECURITY.md#telemetry)**.

## Contributing

Issues and PRs welcome. See **[CONTRIBUTING.md](CONTRIBUTING.md)**. Good first issues are
[labelled here](https://github.com/ifixai-ai/iFixAi/issues?q=is%3Aopen+label%3A%22good+first+issue%22).

## Contact

Bug reports, features, questions: open a [GitHub issue](https://github.com/ifixai-ai/iFixAi/issues).
Security-sensitive reports: **[SECURITY.md](SECURITY.md)**. Anything else: **info@ime.life**.

## License

[Apache 2.0](LICENSE)

<p align="center">
  <a href="docs/traction.md">Traction</a>: installs and runs over time.
</p>
