Metadata-Version: 2.5
Name: webai-scanner
Version: 0.1.0
Summary: AI Agent Readability auditor & local Steam game discovery engine
Author: Alexander Markovski
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# WebAI: The AI-Ready Internet Standard & Token Benchmarking Suite

**WebAI** is an open architectural standard, benchmarking suite, and agent identity framework designed to establish an **AI-Agent-Ready Internet** operating alongside the modern human-first web.

---

## 🌍 The WebAI Manifesto: Why Build This Now?

* **The 57% Reality:** Major internet infrastructure providers like Cloudflare have documented that **over 57% of all web traffic** is now generated by automated systems and AI agents.
* **The Structural Flaw:** Despite AI being the majority of internet consumers, the web remains engineered exclusively for human visual perception (deeply nested HTML DOM trees, CSS stylesheets, layout wrappers, and tracking scripts).
* **The Downstream Impact:** AI agents waste up to **95%+ of their I/O token budgets** simply parsing presentation boilerplate. This inflates task completion times, drives up inference costs, and needlessly ties up global GPU clusters that could be solving valuable societal tasks.
* **The Dual-Web Solution:** Humans keep their rich visual web interfaces, while websites provide a parallel **Agent-Ready Web** with zero presentation bloat.

### The Two Pillars of WebAI
1. **Pillar 1: Content & Representation Standards**
   * Standardized `llms.txt` and semantic JSON contracts.
   * **Storage4gaming.com:** Complete rewrite into the reference AI-agent-ready site.
   * **Empirical Benchmarks:** Quantifying token and latency savings across open-weight models on Storage4gaming and the Steam Storefront.
2. **Pillar 2: AI Agent Identity & Authentication (AIAID)**
   * Cryptographic machine identities for AI agents (analogous to MAC addresses / UUIDs).
   * A public depository and challenge-response handshake that unlocks high-speed semantic endpoints for verified agents while filtering malicious scrapers.

---

## 🌟 Key Highlights

- **~76% - 95% Token Reduction:** Cuts prompt tokens from thousands of tokens down to ~100 tokens.
- **1.5x - 2.5x Faster Latency:** Accelerates task completion by stripping away visual rendering layers.
- **Embedded SQLite Telemetry:** All benchmark runs, tokenizer token counts, throughput (tok/s), latency, and peak RAM are persisted to `webai_benchmarks.db` and synchronized with `benchmark_results.csv`.
- **Apple Silicon Optimized:** 100% offline inference on Apple Silicon using `mlx-lm` with sequential execution and automatic memory cache clearing to protect 16 GB Unified Memory.
- **Auto-Updating Documentation:** Live benchmark tables and model cache statuses in this README and `ARCHITECTURE.md` stay automatically synchronized with your local benchmark runs.

---

## 📊 Live Benchmark Performance Summary

> The table below is automatically synchronized with [`webai_benchmarks.db`](file:///Users/alexandermarkovski/Coding/In_Progress/WebAI/webai_benchmarks.db) by `doc_updater.py`:

<!-- BENCHMARK_TABLE_START -->

| Model                        | Target Game      | Human Tokens   | Agent Tokens   | Token Savings   | Human Latency   | Agent Latency   | Speedup     |
|------------------------------|------------------|----------------|----------------|-----------------|-----------------|-----------------|-------------|
| `Llama-3.2-1B-Instruct-4bit` | Apex Legends     | 565 tok        | 132 tok        | **76.64%**      | 0.56s           | 0.42s           | 1.3x faster |
| `Llama-3.2-1B-Instruct-4bit` | Counter-Strike 2 | 567 tok        | 136 tok        | **76.01%**      | 0.99s           | 0.45s           | 2.2x faster |
| `Llama-3.2-1B-Instruct-4bit` | Halo Infinite    | 565 tok        | 132 tok        | **76.64%**      | 0.50s           | 0.42s           | 1.2x faster |
| `gemma-4-e4b-it-OptiQ-4bit`  | Apex Legends     | 635 tok        | 125 tok        | **80.31%**      | 4.69s           | 3.45s           | 1.4x faster |
| `gemma-4-e4b-it-OptiQ-4bit`  | Counter-Strike 2 | 637 tok        | 132 tok        | **79.28%**      | 6.96s           | 4.77s           | 1.5x faster |
| `gemma-4-e4b-it-OptiQ-4bit`  | Halo Infinite    | 636 tok        | 126 tok        | **80.19%**      | 3.61s           | 3.31s           | 1.1x faster |

<!-- BENCHMARK_TABLE_END -->

---

## 🤖 Supported Model Matrix & Local Cache Status

The suite evaluates models across two buckets, all optimized in 4-bit quantization for 16 GB Unified Memory:
- **Bucket 1 (< 4B):** Ultra-lightweight models for fast edge inference.
- **Bucket 2 (4B – 12B):** Desktop-class models including Google's **Gemma 4 12B** and **Gemma 4 E4B (8B)**.

> Check your local cache anytime with `python download_models.py --list`:

<!-- MODEL_STATUS_START -->

| Status       | Bucket   | Est. RAM (4-bit)   | Hugging Face Model ID                            |
|--------------|----------|--------------------|--------------------------------------------------|
| **[CACHED]** | <4B      | ~1.0 GB            | `mlx-community/Llama-3.2-1B-Instruct-4bit`       |
| [NOT CACHED] | <4B      | ~2.2 GB            | `mlx-community/Llama-3.2-3B-Instruct-4bit`       |
| [NOT CACHED] | <4B      | ~2.1 GB            | `mlx-community/Qwen2.5-3B-Instruct-4bit`         |
| [NOT CACHED] | <4B      | ~2.5 GB            | `mlx-community/Phi-4-mini-instruct-4bit`         |
| **[CACHED]** | 4B-12B   | ~7.5 GB            | `mlx-community/gemma-4-12B-it-qat-4bit`          |
| **[CACHED]** | 4B-12B   | ~3.5 GB            | `mlx-community/gemma-4-e4b-it-OptiQ-4bit`        |
| [NOT CACHED] | 4B-12B   | ~4.8 GB            | `mlx-community/Qwen2.5-7B-Instruct-4bit`         |
| [NOT CACHED] | 4B-12B   | ~5.2 GB            | `mlx-community/Llama-3.1-8B-Instruct-4bit`       |
| [NOT CACHED] | 4B-12B   | ~5.2 GB            | `mlx-community/DeepSeek-R1-Distill-Qwen-8B-4bit` |

<!-- MODEL_STATUS_END -->

---

## 🚀 Quickstart

### Prerequisites
- macOS on Apple Silicon (M-series).
- Homebrew installed (`/opt/homebrew/bin/brew`).
- Python 3.11 (`brew install python@3.11`).

### One-Command Setup & Benchmark
Execute the master runner to set up the environment, run unit tests, and launch a benchmark:
```bash
chmod +x run.sh
./run.sh
```

---

## 🛠️ CLI Usage Guide

### 1. Download / Install Models Without Running Inference
Download model weights directly to your local Hugging Face cache (`~/.cache/huggingface/hub/`) without loading them into RAM:
```bash
# Check cache status of all models:
.venv/bin/python3 download_models.py --list

# Download a specific model (e.g. Gemma 4 12B):
.venv/bin/python3 download_models.py --models mlx-community/gemma-4-12B-it-qat-4bit

# Download all models in a bucket:
.venv/bin/python3 download_models.py --bucket "<4B"
```

### 2. Run Comparative Token Benchmarks
Run side-by-side comparative evaluation between human-first HTML and agent-first JSON:
```bash
# Benchmark specific models:
.venv/bin/python3 benchmark_runner.py --models mlx-community/gemma-4-e4b-it-OptiQ-4bit mlx-community/Llama-3.2-1B-Instruct-4bit

# Benchmark a specific game title:
.venv/bin/python3 benchmark_runner.py --game "Cyberpunk 2077"

# Enable live web scraping from https://www.storage4gaming.com:
.venv/bin/python3 benchmark_runner.py --live
```

### 3. Scan Local Steam Game Catalog
Discover locally installed games and owned account library titles from Steam (Windows & macOS):
```bash
# Standard discovery:
.venv/bin/python3 catalog_scanner.py

# Test with synthetic sample catalog:
.venv/bin/python3 catalog_scanner.py --sample
```

### 4. Steam Storefront Specs & Hardware Capacity Calculator
Query the Steam Store API vs. storefront HTML, and calculate total library storage and RAM:
```bash
# Benchmark single Steam game (e.g. Apex Legends):
.venv/bin/python3 steam_client.py --appid 1172470

# Calculate aggregate storage & RAM for your entire scanned Steam library:
.venv/bin/python3 steam_client.py --scan
```

### 5. Update Documentation Automatically
Keep `README.md` and `ARCHITECTURE.md` updated with the latest SQLite benchmark records and model cache status:
```bash
.venv/bin/python3 doc_updater.py
```

---

## 🗄️ Database & Telemetry Inspection

All metrics are stored in SQLite (`webai_benchmarks.db`) and CSV (`benchmark_results.csv`).

### Query Recent Runs
```bash
sqlite3 webai_benchmarks.db "SELECT model_id, site_format, prompt_tokens, token_savings_pct, total_time_sec, peak_memory_mb FROM benchmarks ORDER BY id DESC LIMIT 6;"
```

### View CSV Log
```bash
cat benchmark_results.csv
```

---

## 📚 Central Documentation (`docs/`)

All architectural designs, research, and design decision logs are organized in the [`docs/`](file:///Users/alexandermarkovski/Coding/In_Progress/WebAI/docs) folder:
* **[docs/decisions.md](file:///Users/alexandermarkovski/Coding/In_Progress/WebAI/docs/decisions.md)**: Design log covering Skills vs. Scripts, `llms.txt`, local filesystem discovery, PyPI packaging, readability scoring metrics, and the AIAID protocol.
* **[docs/research.md](file:///Users/alexandermarkovski/Coding/In_Progress/WebAI/docs/research.md)**: Research on publishing platforms (GitHub, Hugging Face Datasets & Spaces, Model Context Protocol / MCP, `llms.txt` directories, and PyPI).
* **[docs/ARCHITECTURE.md](file:///Users/alexandermarkovski/Coding/In_Progress/WebAI/docs/ARCHITECTURE.md)**: Full system design, Mermaid data flow, AIAID authentication handshake, and Storage4gaming rewrite blueprint.
* **[docs/WebAI_specification.md](file:///Users/alexandermarkovski/Coding/In_Progress/WebAI/docs/WebAI_specification.md)**: Master project specification and criteria.
* **[docs/starter.md](file:///Users/alexandermarkovski/Coding/In_Progress/WebAI/docs/starter.md)**: Task requirements and model testing matrix.

---

## 📂 Repository Layout

```
├── docs/                        # Central documentation folder
│   ├── decisions.md             # Pending design decisions and architectural trade-offs
│   ├── research.md              # Research on publishing platforms (GitHub, Hugging Face, MCP)
│   ├── ARCHITECTURE.md          # Technical design, data flow, and database schema
│   ├── WebAI_specification.md   # Core project specification
│   └── starter.md               # Task requirements and model evaluation matrix
├── llms.txt                     # Standard machine-readable AI agent spec index
├── llms-full.txt                # Comprehensive agent knowledge base and sizing formulas
├── README.md                    # Project overview, manifesto, quickstart, and live scoreboard
├── ARCHITECTURE.md              # Root link to technical design
├── telemetry_db.py              # SQLite telemetry database engine and CSV exporter
├── storage4gaming_client.py     # Storage4gaming comparative payload generator (HTML vs JSON vs llms.txt)
├── steam_client.py              # Steam Storefront API client & aggregate hardware calculator
├── benchmark_runner.py          # MLX sequential inference and benchmarking harness
├── download_models.py           # Standalone model downloader/installer
├── catalog_scanner.py           # Cross-platform Steam game library detector (Windows & macOS)
├── doc_updater.py               # Documentation auto-synchronizer
├── test_telemetry.py            # Automated test suite for database and telemetry
├── run.sh                       # Master setup and execution script
├── webai_benchmarks.db          # SQLite database storing benchmark records
└── benchmark_results.csv        # Exported benchmark CSV dataset
```
