Grok Bot Jev Router

# Grok Bot Jev Router

Connect [TypeSafe Jev](https://docs.typesafe.ai) to Grok Bot as a cheap decision layer. Jev classifies the request before expensive research, browser, retry, or subagent work, so Grok Bot can reuse a fresh artifact, stop a failing retry, cap research, or ask for approval.

This package is a small open-source reference implementation. It does not change Grok Bot's foundation model and does not route Cursor models.

## How it looks

Visualization of Grok Bot + Jev at work:

- [`media/jev-grok-bot-demo.mp4`](media/jev-grok-bot-demo.mp4)



## What

- A Python router around the TypeSafe SDK's `system_one` call.
- Explicit actions such as `reuse_cache`, `stop_retry`, `run_deterministic`, `chat_only`, `research_capped`, `allow_subagent`, and `ask_human`.
- `shadow` mode for measurement and `active` mode for a skill that honors the returned action.
- A kill switch through `enabled: false` or a `bypass jev` marker.

## Why

A small classification call can prevent needless tool work. The router is intentionally conservative: it never sends, publishes, pays, deletes, or changes permissions without a human approval path, and it logs decisions without logging the API key.

## Install

```bash
git clone https://github.com/Bodila51/grok-bot-jev.git
cd grok-bot-jev
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp config.example.yaml config.yaml
export TYPESAFE_API_KEY=...   # use your secret manager; do not commit the key
```

Keep `config.yaml`, `.env`, and local logs uncommitted. `src/secrets.py` reads only `TYPESAFE_API_KEY` from the environment; it never reads a secrets file.

## Run dry-run

The script sends the sample states through Jev and prints JSON decisions:

```bash
.venv/bin/python scripts/dry_run.py
# or one state:
.venv/bin/pytho