Metadata-Version: 2.4
Name: aeo-audit-lite
Version: 0.1.0
Summary: Measure share of model: run a buyer prompt against an AI engine repeatedly and report how often a brand appears versus competitors, with a confidence interval.
Project-URL: Homepage, https://clearcited.com/
Project-URL: Source, https://github.com/Clear-Cited/aeo-audit-lite
Author-email: Logan Adams <hello@clearcited.com>
License: MIT License
        
        Copyright (c) 2026 Clear Cited
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: aeo,ai-search,citation,geo,structured-data
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# aeo-audit-lite

**Does AI actually recommend your product?** Run a buyer prompt against an AI
engine several times and measure how often your brand shows up versus named
competitors — your *share of model* — with a confidence interval.

A single ChatGPT screenshot proves nothing: AI answers are non-deterministic.
This measures properly, the same way every time.

- **Zero dependencies** — Python standard library only.
- **Mock mode by default** — runs offline with illustrative numbers.
- **Bring your own key** — set `PERPLEXITY_API_KEY` or `OPENAI_API_KEY` for real data.

## Usage

Offline demo (no key needed):

```bash
python aeo_audit_lite.py --brand "Acme" --competitors "Datadog,Grafana,New Relic" \
  --prompt "best observability tool for a Series A startup" --runs 12 --mock
```

Real measurement:

```bash
export PERPLEXITY_API_KEY=pplx-...
python aeo_audit_lite.py --brand "Acme" --competitors "Datadog,Grafana" \
  --prompt "best APM for kubernetes" --runs 10 --engine perplexity
```

### Example output

```
brand                       rate  95% CI           share
------------------------------------------------------------
Datadog                    10/12  [55.2–95.3%]   31.2%
Grafana                    10/12  [55.2–95.3%]   31.2%
New Relic                   8/12  [39.1–86.2%]   25.0%
Acme                        4/12  [13.8–60.9%]   12.5%  <- you

Your share of model: 12.5% (mentioned in 4 of 12 answers).
```

## How it works

1. Sends your prompt to the engine `--runs` times.
2. Checks each answer for whole-word mentions of your brand and each competitor.
3. Reports mention rate, a 95% **Wilson** confidence interval, and share of model
   (your mentions ÷ all brand mentions).

### Why repeat the prompt?

LLMs sample their output — ask twice, get two answers. One run is a coin flip.
Repeating and reporting the median/interval is the difference between data and
vibes.

## Options

| Flag | Meaning |
|---|---|
| `--brand` | your product name (required) |
| `--competitors` | comma-separated competitor names |
| `--prompt` | the buyer question (required) |
| `--runs` | number of repetitions (default 10) |
| `--engine` | `perplexity` (default) or `openai` |
| `--mock` | force offline mock mode |

## License

MIT © Clear Cited

---

This is the lite version. The full **[Clear Cited](https://clearcited.com)**
service measures dozens of prompts across every major engine (ChatGPT, Perplexity,
Claude, Gemini, Google AI Overviews), with human QC and a fix roadmap.
[Get a free teardown →](https://clearcited.com/free-teardown/)
