Metadata-Version: 2.4
Name: bg_nexus
Version: 2.0.0
Summary: High-Performance BotGuard Token Engine Library for Python (< 0.5ms)
Author: Google Deepmind Team
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx[http2]>=0.24.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.22.0
Requires-Dist: pydantic>=2.0.0
Dynamic: license-file
Dynamic: requires-python

# bg_nexus (v2.0.0)

> **High-Performance, Stateless BotGuard Token Engine Library for Python (< 0.5ms)**

`bg_nexus` is a production-ready, stateless, parameter-driven Python library and microservice designed to generate Google BotGuard / Web Attestation (WAA) integrity tokens in sub-millisecond speeds directly from Python memory.

---

## ⚡ Features

- **Sub-Millisecond In-Memory Execution (< 0.5ms)**: Evaluates BotGuard VM closures in memory without HTTP REST / TCP socket overhead.
- **100% Stateless & Parameter-Driven**: Accepts dynamic session credentials (`cookie_str`, `sapisid`, `user_agent`, `visit_id`, `prompt`) per request. No hardcoded profile bindings.
- **Embedded V8 Sandbox**: Includes high-fidelity synthetic DOM & sensor telemetry matrix (`synthetic_sensor_matrix.js`) for accurate BotGuard challenge solving.
- **Dual Operating Modes**:
  - **Python Library Mode**: `from bg_nexus import NexusEngine` for direct in-memory calls.
  - **FastAPI Microservice Mode**: Standalone CLI server `bg-nexus --port 8765`.

---

## 📦 Installation

Install directly as a local editable package or build wheel:

```bash
pip install -e .
```

---

## 🚀 Quick Start

### Mode 1: Direct Python Library Mode (Recommended - Instant Speed)

```python
import asyncio
from bg_nexus import NexusEngine

async def main():
    engine = NexusEngine()

    # Pass dynamic session parameters:
    token = await engine.generate_token(
        prompt="Explain quantum entanglement in one sentence.",
        cookie_str="SID=...; SAPISID=xyz...; __Secure-1PSID=...",
        sapisid="xyz123...",
        user_agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:152.0) Gecko/20100101 Firefox/152.0",
        visit_id="v1_abcdef123..."
    )

    print(f"Generated Token Length: {len(token)}")
    print(f"Token Preview: {token[:60]}...")

if __name__ == "__main__":
    asyncio.run(main())
```

### Mode 2: FastAPI Microservice Mode (HTTP REST API)

Launch the standalone HTTP microservice:

```bash
bg-nexus --port 8765
```

Or via module execution:

```bash
python3 -m bg_nexus.server --port 8765
```

#### HTTP POST `/token` Request Body:

```json
{
  "prompt": "Hello Gemini",
  "cookie_str": "SAPISID=xyz...",
  "sapisid": "xyz123...",
  "user_agent": "Mozilla/5.0...",
  "visit_id": "v1_abcdef..."
}
```

---

## 🏗️ Architecture Layout

```
bg_nexus/
├── bg_nexus/                      # Core Package Module
│   ├── __init__.py                # Package exports (NexusEngine, NexusClient)
│   ├── engine.py                  # Waa RPC fetcher & Token manager
│   ├── worker.py                  # Node.js V8 IPC Daemon Supervisor
│   ├── client.py                  # Async HTTP Client for Microservice
│   ├── server.py                  # FastAPI Application Server CLI
│   └── js/                        # Encapsulated V8 Sandbox Assets
│       ├── worker.js              # Node.js V8 Sandbox & RAM Closure Engine
│       └── synthetic_sensor_matrix.js # DOM & Sensor Telemetry Simulator
├── data/                          # Package Data (Fingerprints)
│   └── real_machine_fingerprint.json
├── setup.py                       # Package Setup
├── pyproject.toml                 # Package Build Specification
├── LICENSE                        # MIT License
└── README.md                      # Documentation
```

---

## 📄 License

MIT License. See [LICENSE](LICENSE) for details.
