# BIASCOPE — Embedded bias probe suite — demographic / occupational / geographic

> Part of the **[Cognis Neural Suite](https://github.com/cognis-digital)** by [Cognis Digital](https://cognis.digital)
> Cognis Open Collaboration License (COCL) v1.0 · domain: `ai-security`

[![PyPI](https://img.shields.io/pypi/v/cognis-biascope.svg)](https://pypi.org/project/cognis-biascope/)
[![CI](https://github.com/cognis-digital/biascope/actions/workflows/ci.yml/badge.svg)](https://github.com/cognis-digital/biascope/actions)
[![License: COCL 1.0](https://img.shields.io/badge/License-COCL%201.0-2b6cb0.svg)](LICENSE)
[![Suite](https://img.shields.io/badge/Cognis-Neural%20Suite-6b46c1.svg)](https://github.com/cognis-digital)

**Embedded bias probe suite — demographic / occupational / geographic.**

*AI Security & Governance — securing LLMs, agents, and the MCP supply chain.*


<!-- cognis:example:start -->
## 🔎 Example output

Real, reproducible output from the tool — runs offline:

```console
$ biascope-emit --version
biascope 0.1.0
```

```console
$ biascope-emit --help
usage: biascope [-h] [--version] [--format {table,json}] {scan,probes} ...

BIASCOPE - embedded bias probe suite. Scans recorded model completions for
demographic, occupational, and geographic bias. Offline, deterministic, CI-
friendly.

positional arguments:
  {scan,probes}
    scan                scan a completions file for bias
    probes              list the built-in probe catalog

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --format {table,json}
                        output format (default: table)

Exit code 1 indicates one or more bias findings were detected.
```

> Blocks above are real `biascope` output — reproduce them from a clone.

**Sample result format** _(illustrative values — run on your own data for real findings):_

```
{
"findings": [
    {
        "id": "1234567890",
        "title": "Suspicious Network Activity",
        "description": "Network traffic anomalies detected",
        "indicator": {
            "type": "ip",
            "value": "192.168.1.100"
        },
        "observable": {
            "type": "network_traffic",
            "data": [
                {
                    "protocol": "tcp",
                    "source_port": 1234,
                    "destination_port": 80
                }
            ]
        }
    }
]
}
```

<!-- cognis:example:end -->

## Usage — step by step

1. **Install** the probe suite:
   ```bash
   pip install cognis-biascope
   ```
2. **Scan a completions file** for demographic / occupational / geographic bias. `scan` takes the recorded completions path:
   ```bash
   biascope scan demos/completions.jsonl
   ```
3. **Tune the sensitivity** — `--threshold` (default 3) sets how many probe hits flag a bias finding:
   ```bash
   biascope scan demos/completions.jsonl --threshold 2
   ```
4. **Read the output** as JSON (the global `--format` flag is `table` or `json` and precedes the subcommand), and inspect the probe catalog behind the findings:
   ```bash
   biascope --format json scan demos/completions.jsonl
   biascope probes
   ```
5. **Automate in CI** — capture model completions, then scan them on every eval run:
   ```yaml
   - run: pip install cognis-biascope
   - run: biascope --format json scan eval/completions.jsonl > biascope.json
   ```

## Why

Security and intelligence teams need embedded bias probe suite — demographic / occupational / geographic without standing up heavyweight infrastructure. `biascope` is single-purpose, scriptable, CI-friendly, and self-hostable: point it at a target, get prioritized findings in the format your workflow already speaks (table, JSON, SARIF, HTML), and wire it into agents over MCP when you want it autonomous.

## Install

```bash
pip install cognis-biascope
# or, from this repo:
pip install -e ".[dev]"
```

## Quick start

```bash
biascope --version
biascope scan demos/                      # run against the bundled demo
biascope scan demos/ --format sarif --out r.sarif --fail-on high
biascope scan demos/ --format html --out report.html
biascope mcp                              # expose as an MCP server (Cognis.Studio / Claude Desktop / Cursor)
```

## Built-in demo scenarios

Each scenario folder includes a `SCENARIO.md` describing the situation and the findings to expect.

- [`demos/01-basic/`](demos/01-basic/SCENARIO.md)
- [`demos/01-loan-approval/`](demos/01-loan-approval/SCENARIO.md)
- [`demos/02-clean-chatbot/`](demos/02-clean-chatbot/SCENARIO.md)
- [`demos/03-customer-segmentation/`](demos/03-customer-segmentation/SCENARIO.md)

## Output formats

- **Table** (default) — human-readable terminal summary
- **JSON** — machine-readable findings for pipelines
- **SARIF** — drops into GitHub code-scanning / IDE problem panes
- **HTML** — shareable report with severity rollups

## Credits / Built on

Cognis composes and credits the best of open source. This tool builds on / interoperates with:

- [`stanford-crfm/helm`](https://github.com/stanford-crfm/helm) — probe data
- [`nyu-mll/BBQ`](https://github.com/nyu-mll/BBQ) — bias benchmark

Missing a credit? Open a PR — see [CONTRIBUTING.md](CONTRIBUTING.md).

## How it fits the Cognis Neural Suite

`biascope` is one of **52 tools** in the [Cognis Neural Suite](https://github.com/cognis-digital). Every tool ships an MCP server, so [Cognis.Studio](https://cognis.studio) agents can call them as scoped capabilities.

**Sibling tools in `ai-security`:** [`aegis`](https://github.com/cognis-digital/aegis), [`promptmirror`](https://github.com/cognis-digital/promptmirror), [`ledgermind`](https://github.com/cognis-digital/ledgermind), [`adversa`](https://github.com/cognis-digital/adversa), [`guardpost`](https://github.com/cognis-digital/guardpost), [`hallumark`](https://github.com/cognis-digital/hallumark), [`aicard`](https://github.com/cognis-digital/aicard), [`mcpharden`](https://github.com/cognis-digital/mcpharden), [`agentlog`](https://github.com/cognis-digital/agentlog), [`ragshield`](https://github.com/cognis-digital/ragshield)

## Architecture & roadmap

- Design notes: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
- Planned work: [`ROADMAP.md`](ROADMAP.md)

## Contributing

PRs, new detections, and demo scenarios are welcome under the collaboration-pull model. See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).

## Interoperability

`biascope` composes with the 300+ tool Cognis suite — JSON in/out and a shared
OpenAI-compatible `/v1` backbone. See **[INTEROP.md](INTEROP.md)** for the
suite map, composition patterns, and reference stacks.

## Integrations

Forward `biascope`'s findings to STIX/MISP/Sigma/Splunk/Elastic/Slack/webhooks via
[`cognis-connect`](https://github.com/cognis-digital/cognis-connect). See **[INTEGRATIONS.md](INTEGRATIONS.md)**.

## License

Source-available under the **Cognis Open Collaboration License (COCL) v1.0** — free for personal, internal-evaluation, research, and educational use; **commercial / production use requires a license** (licensing@cognis.digital). See [LICENSE](LICENSE).

## Responsible use

This is dual-use security software. Use it only against systems, data, and identities you own or are explicitly authorized in writing to test, and in compliance with applicable law.

## About

**[Cognis Digital](https://cognis.digital)** — Wyoming, USA · *Making Tomorrow Better Today: Advanced Cybersecurity, AI Innovation, and Blockchain Expertise.*