# Roadmap: Meshulash Guard

## Overview

Build the meshulash-guard Python SDK — a translation layer over the existing AIM security server — and ship a MkDocs documentation site. The server gets one new endpoint first, then the SDK core types are established, then scanners are wired up, then the placeholder vault completes the PII protection workflow, and finally docs go live.

## Phases

**Phase Numbering:**
- Integer phases (1, 2, 3): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

- [x] **Phase 1: Foundation** - Server endpoint + SDK scaffold (types, base classes, enums, package config) in place
- [x] **Phase 2: Scanners** - All six scanners implemented, Guard.scan_input() wired end-to-end
- [x] **Phase 3: Vault** - Placeholder cache and deanonymize complete the PII protection workflow
- [x] **Phase 3.1: Demo Chatbot** - Gemini chatbot app stress-testing the SDK with varied scanner configs (INSERTED)
- [x] **Phase 4: Docs** - MkDocs site live with full scanner and engine reference
- [ ] **Phase 5: Publish & Deploy** - SDK on PyPI with CI/CD automation, docs live at docs.meshulash.ai

## Phase Details

### Phase 1: Foundation
**Goal**: Developers can install the package and the server has the new endpoint — everything needed to make an SDK call exists, even if scanners aren't implemented yet
**Depends on**: Nothing (first phase)
**Requirements**: SRV-01, SRV-02, SRV-03, SRV-04, SDK-01, SDK-04, SDK-05, SDK-06, SDK-07, SDK-08, PKG-01, PKG-02
**Success Criteria** (what must be TRUE):
  1. `pip install meshulash-guard` works and `from meshulash_guard import Guard` imports without error
  2. The security server accepts a JSON POST to `/api/security/scan` with `text` + `guardline_specs` and returns a per-scanner breakdown
  3. A `Guard(server_url=..., api_key=...)` instance can be constructed and its HTTP client is configured with the correct auth header
  4. `Action`, `Condition`, and structured result types are importable and usable in isolation (no scanner needed to inspect them)
**Plans:** 2 plans

Plans:
- [x] 01-01-PLAN.md — Server endpoint: /api/security/scan + authenticated health + process_sdk()
- [x] 01-02-PLAN.md — SDK package scaffold: types, enums, exceptions, Guard class, base classes

### Phase 2: Scanners
**Goal**: Developers can scan text for PII, topics, toxicity, cyber threats, and jailbreak attempts with a single `guard.scan_input()` call
**Depends on**: Phase 1
**Requirements**: SDK-02, SDK-03, SCAN-01, SCAN-02, SCAN-03, SCAN-04, SCAN-05, SCAN-06, SCAN-07
**Success Criteria** (what must be TRUE):
  1. `guard.scan_input(text, scanners=[PIIScanner(...)])` sends a real HTTP request and returns a structured `ScanResult` with status, processed_text, and per-scanner breakdown
  2. All six scanner classes (`PIIScanner`, `TopicScanner`, `ToxicityScanner`, `CyberScanner`, `JailbreakScanner`) are importable with their scoped label enums
  3. PIIScanner accepts risk bundle shortcuts (`PIILabel.PII`, `PIILabel.SECRETS`, etc.) as shorthand for predefined label groups
  4. `guard.scan_output()` raises `NotImplementedError` with a "coming in v2" message
  5. Each scanner's label enum maps to the correct TC head or label registry entries internally — developers never see TC head names
**Plans:** 2 plans

Plans:
- [x] 02-01-PLAN.md — PIIScanner with 53-label enum, bundle expansion, per-label overrides, and Guard multi-spec support
- [x] 02-02-PLAN.md — TC scanners (Topic, Toxicity, Cyber, Jailbreak) and package wiring

### Phase 3: Vault
**Goal**: Developers can anonymize PII in a prompt, pass redacted text to an LLM, and restore originals from the response — all without a second server call
**Depends on**: Phase 2
**Requirements**: VAULT-01, VAULT-02, VAULT-03
**Success Criteria** (what must be TRUE):
  1. After `guard.scan_input()` returns with REPLACE action results, `guard.deanonymize(llm_response)` restores original values from placeholders client-side
  2. Multiple `scan_input()` calls accumulate into the same session vault — placeholders from earlier scans are still restorable
  3. `guard.clear_cache()` resets the session so no prior placeholders remain
**Plans:** 1 plan

Plans:
- [x] 03-01-PLAN.md — Complete vault workflow: extract _scan(), implement scan_output(), enhance deanonymize() with debug logging

### Phase 3.1: Demo Chatbot (INSERTED)
**Goal**: A working Gemini-powered chatbot demo script that exercises all SDK scanner types with varied configurations, proving the SDK works end-to-end on a real app
**Depends on**: Phase 3
**Requirements**: None (demo/integration test, not a product requirement)
**Success Criteria** (what must be TRUE):
  1. A runnable demo script connects to Gemini and sends user prompts through meshulash-guard before forwarding to the LLM
  2. The demo exercises multiple scanner configurations (PII with bundles, PII with overrides, topic filtering, toxicity blocking, cyber detection)
  3. The deanonymize workflow is demonstrated: scan → redact → LLM → restore originals
  4. The script produces visible output showing scan results, actions taken, and restored text
**Plans:** 1 plan

Plans:
- [x] 03.1-01-PLAN.md — Demo chatbot script with five scanner presets, Gemini integration, and full scan/gate/deanonymize workflow

### Phase 4: Docs
**Goal**: Any developer can land on the docs site, understand what the SDK does, install it, and write working code without reading source
**Depends on**: Phase 3
**Requirements**: DOC-01, DOC-02, DOC-03, DOC-04, DOC-05
**Success Criteria** (what must be TRUE):
  1. MkDocs site builds and deploys to the custom domain without error
  2. A developer with no prior knowledge can follow the installation and quickstart guide to run their first scan
  3. Every scanner has a dedicated reference page listing its labels, actions, conditions, and a working code example
  4. The engine reference explains what each label detects, which detection sources it uses, and which validators auto-run
  5. The deanonymize workflow page walks through the full anonymize → LLM → restore pattern with example code
**Plans:** 3 plans

Plans:
- [x] 04-01-PLAN.md — MkDocs infrastructure: mkdocs.yml, AIM purple theme, logo, nav structure
- [x] 04-02-PLAN.md — Core content pages: quickstart, concepts, and deanonymize workflow
- [x] 04-03-PLAN.md — Scanner reference pages: PIIScanner (bundles/overrides) + 4 TC scanners + site verification

### Phase 5: Publish & Deploy
**Goal**: `pip install meshulash-guard` pulls from PyPI, docs are live at docs.meshulash.ai, and pushing to production auto-publishes a new SDK version
**Depends on**: Phase 4
**Requirements**: PKG-03, PKG-04, DOC-06
**Success Criteria** (what must be TRUE):
  1. `pip install meshulash-guard` installs the package from PyPI (public or private index)
  2. Pushing to the `main` branch triggers an automated workflow that builds, versions, and publishes the SDK to PyPI
  3. A `dev` branch exists for development; only merges to `main` trigger publishing
  4. `docs.meshulash.ai` serves the MkDocs site over HTTPS with a valid certificate
  5. Docs rebuild and redeploy automatically when the docs repo is updated
**Plans:** 3 plans

Plans:
- [ ] 05-01-PLAN.md -- SDK CI/CD workflows (ci.yml + publish.yml) and pyproject.toml Python version update
- [ ] 05-02-PLAN.md -- Docs domain update (CNAME + site_url) and deploy workflow
- [ ] 05-03-PLAN.md -- Manual setup: PyPI Trusted Publisher, GitHub environment, dev branch, Pages config

## Progress

**Execution Order:**
Phases execute in numeric order: 1 → 2 → 3 → 3.1 → 4 → 5

| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Foundation | 2/2 | Complete ✓ | 2026-02-26 |
| 2. Scanners | 2/2 | Complete ✓ | 2026-02-26 |
| 3. Vault | 1/1 | Complete ✓ | 2026-02-26 |
| 3.1 Demo Chatbot | 1/1 | Complete ✓ | 2026-02-26 |
| 4. Docs | 3/3 | Complete ✓ | 2026-02-27 |
| 5. Publish & Deploy | 0/0 | Not started | — |
