Metadata-Version: 2.4
Name: cngx
Version: 0.1.5
Summary: Local CLI that fingerprints coding-agent output and gates merges when verification is missing.
Project-URL: Homepage, https://github.com/aadi-joshi/cngx
Project-URL: Repository, https://github.com/aadi-joshi/cngx
Project-URL: Documentation, https://github.com/aadi-joshi/cngx/tree/main/docs
Project-URL: Bug Tracker, https://github.com/aadi-joshi/cngx/issues
Project-URL: Changelog, https://github.com/aadi-joshi/cngx/blob/main/CHANGELOG.md
Author: cngx Contributors
License-Expression: MIT
License-File: LICENSE
Keywords: ai-safety,behavior-policy,behavioral-fingerprinting,coding-agents,drift-detection,llm,local-first,policy-check,reasoning,verification
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT 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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: duckdb>=0.9.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: frouros>=0.9.0
Requires-Dist: holdout-evals>=0.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: scipy>=1.11.0
Requires-Dist: starlette>=0.37.0
Requires-Dist: typer>=0.9.0
Requires-Dist: uvicorn>=0.24.0
Provides-Extra: all
Requires-Dist: anthropic>=0.30.0; extra == 'all'
Requires-Dist: google-genai>=1.0.0; extra == 'all'
Requires-Dist: opentelemetry-api>=1.20.0; extra == 'all'
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0; extra == 'all'
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'all'
Requires-Dist: sentence-transformers>=2.2.0; extra == 'all'
Provides-Extra: claude
Requires-Dist: anthropic>=0.30.0; extra == 'claude'
Provides-Extra: dev
Requires-Dist: bandit>=1.7.0; extra == 'dev'
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: httpx[http2]>=0.25.0; extra == 'dev'
Requires-Dist: mypy>=1.6.0; extra == 'dev'
Requires-Dist: playwright>=1.40.0; extra == 'dev'
Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
Requires-Dist: pyinstaller>=6.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: safety>=2.3.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.4.0; extra == 'docs'
Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'docs'
Provides-Extra: gemini
Requires-Dist: google-genai>=1.0.0; extra == 'gemini'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20.0; extra == 'otel'
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'otel'
Provides-Extra: semantic
Requires-Dist: sentence-transformers>=2.2.0; extra == 'semantic'
Description-Content-Type: text/markdown

# cngx

[![CI](https://github.com/aadi-joshi/cngx/actions/workflows/ci.yml/badge.svg)](https://github.com/aadi-joshi/cngx/actions/workflows/ci.yml)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/cngx/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

cngx checks whether a coding agent actually ran the verification your policy requires before you trust its output.

```bash
pipx install cngx
cngx quickstart          # mock demo, no API keys, under 30s
```

Gate existing agent output in CI (no provider calls, no API keys):

```bash
cngx check -c examples/contracts/coding_agent_verification.yaml \
  -p "Fix the pagination bug and run tests" \
  --output-file agent_output.txt
```

Live one-shot check against a provider:

```bash
cngx check -c examples/contracts/basic_reasoning.yaml "Fix the bug and run the test suite"
```

Python 3.10+. Requires [pipx](https://pipx.pypa.io/) or `pip install cngx`. See [installation](https://github.com/aadi-joshi/cngx/blob/main/docs/getting-started/installation.md).

## What it does

**Message one (offline CI):** `cngx check --output-file` fingerprints agent text you already have and enforces a behavior policy. Did the agent show test evidence, or only sound merge-ready?

**Message one (live):** `cngx check` with a provider adapter fingerprints a single response the same way.

**Long sessions:** `cngx wrap` and `cngx watch` proxy your agent, fingerprint every call, and compare live traffic to a baseline you pin. Alerts use corroborated statistical tests, not length alone.

```
  agent ──► cngx proxy ──► provider API
              │
              ├── fingerprint each response
              ├── cngx check / policy gate (optional)
              └── diff vs pinned baseline (session drift)
```

Honest limit: offline policies score the *text* of agent output. An agent that fabricates "12 passed" without running tests can still pass text-only checks. Pass `--evidence-file pytest.log` (or wire it in the GitHub Action) so cngx also requires a real tool log with a concrete result line. Pair with CI exit codes when you need proof of execution.

## Measured (synthetic benchmarks, alpha=0.05)

| Scenario | Method | False positive rate |
|----------|--------|---------------------|
| Correlated stationary, no drift (250 trials) | Legacy Fisher omnibus | 0.024 (6/250) |
| Correlated stationary, no drift (250 trials) | CCT batch (current) | 0.024 (6/250) |
| Independent stationary, no drift (250 trials) | Legacy (>=2 metrics) | 0.016 (4/250) |
| Independent stationary, no drift (250 trials) | CCT batch (current) | 0.032 (8/250) |
| Streaming stable series (150 steps) | KSWIN / MDDM | 0.000 (0/150) |
| Streaming stable series (150 steps) | Legacy ADWIN / Page-Hinkley | 0.000 (0/150) |

| Detection | Result |
|-----------|--------|
| Streaming shift (injected at step 80) | First KSWIN/MDDM alert at step 87 |
| Session verification collapse (synthetic) | Collapse from turn 13, warning at turn 22 (9-turn delay) |
| McNemar suite shift (binary) | p ≈ 0.000002 |
| Paired permutation (continuous) | p = 0.0002 |

Synthetic draws only. Pin your own baseline on real traffic before treating alerts as production signals. Details: [drift engine](https://github.com/aadi-joshi/cngx/blob/main/docs/concepts/drift.md), [sessions](https://github.com/aadi-joshi/cngx/blob/main/docs/concepts/sessions.md).

## Commands

| Command | Use |
|---------|-----|
| `cngx quickstart` | Zero-key demo: unverified agent patch blocked |
| `cngx check -c policy.yaml "…"` | One-shot policy check (CI-friendly exit codes) |
| `cngx check -c policy.yaml --output-file out.txt` | Gate existing agent output offline |
| `cngx check ... --evidence-file pytest.log` | Also require a real test log with `N passed` |
| `cngx wrap -- aider` | Route an agent through the local proxy |
| `cngx watch` | Live dashboard on proxied traffic |
| `cngx pin --label baseline` | Save normal behavior for a task |
| `cngx diff --baseline baseline` | Compare recent captures to that baseline |
| `cngx submit --baseline baseline` | Opt-in metrics to the [community tracker](https://aadi-joshi.github.io/cngx/) |

Set `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `GOOGLE_API_KEY` / `GEMINI_API_KEY` for live providers. Keys stay in memory for forwarding; they are not written to the local database.

## Local-first

Runs on your machine. Traces and fingerprints live in `.cngx/` (DuckDB). Proxy binds to `127.0.0.1` by default. Nothing leaves the host unless you run `cngx submit` after an explicit preview and confirm (numeric metrics only; no personal identity collected or stored).

## Docs

- [Quickstart](https://github.com/aadi-joshi/cngx/blob/main/docs/getting-started/quickstart.md)
- [Gate a coding agent in CI](https://github.com/aadi-joshi/cngx/blob/main/docs/guides/gate-coding-agent.md) (offline, no API keys)
- [Proxy and privacy](https://github.com/aadi-joshi/cngx/blob/main/docs/guides/proxy-and-privacy.md)
- [CLI reference](https://github.com/aadi-joshi/cngx/blob/main/docs/cli/reference.md)
- [Contributing](https://github.com/aadi-joshi/cngx/blob/main/CONTRIBUTING.md)

Created by [Kavya Bhand](https://github.com/kavyabhand) and [Aadi Joshi](https://github.com/aadi-joshi).

MIT. See [LICENSE](LICENSE).
