---
phase: 03.1-demo-chatbot
plan: "01"
subsystem: demo
tags: [google-genai, gemini, chatbot, pii, toxicity, cyber, jailbreak, repl, demo]

# Dependency graph
requires:
  - phase: 03-vault
    provides: Guard.scan_input, Guard.scan_output, Guard.deanonymize, all scanner types
  - phase: 02-scanners
    provides: PIIScanner, ToxicityScanner, TopicScanner, CyberScanner, JailbreakScanner with full enum labels
  - phase: 01-foundation
    provides: Guard HTTP client, ScanResult models, enums

provides:
  - Single-file demo chatbot at demo/chatbot.py exercising all SDK scanner types
  - Reference implementation of scan-input/gate/LLM/scan-output/deanonymize workflow
  - Five named security presets covering PII, content moderation, cyber threats, and full guard
  - Developer-realistic scan result output formatting pattern
  - Environment variable validation pattern for Guard + Gemini initialization

affects:
  - future-demos
  - documentation
  - onboarding

# Tech tracking
tech-stack:
  added:
    - google-genai==1.65.0 (Gemini API client — GA since May 2025)
  patterns:
    - Preset-based scanner configuration via hardcoded named dicts
    - Scan-input / gate / LLM / scan-output / deanonymize loop pattern
    - _require_env() helper for fail-fast env var validation at module level
    - Developer-realistic scan result printing (status + triggered scanner details only)

key-files:
  created:
    - demo/chatbot.py
  modified: []

key-decisions:
  - "Used google-genai 1.65.0 (not deprecated google-generativeai) with client.chats.create() for multi-turn history"
  - "Model gemini-2.5-flash chosen as current recommended price-performance model as of Feb 2026"
  - "JailbreakScanner included in Full Guard preset with forward-compat comment (server head coming soon)"
  - "MESHULASH_TENANT_ID added as required env var — Guard constructor requires tenant_id positional arg"
  - "Vault NOT cleared between turns — guard.clear_cache() never called inside loop so deanonymize works across turns"
  - "Same scanners list used for both scan_input and scan_output for simplicity in reference implementation"

patterns-established:
  - "Pattern: Scan before gate — always check result.status == 'blocked' before forwarding to LLM"
  - "Pattern: processed_text chain — always use input_result.processed_text (not raw user_input) as text sent to Gemini"
  - "Pattern: Deanonymize chain — gemini_response.text -> scan_output() -> output_result.processed_text -> deanonymize() -> final"
  - "Pattern: Preset dict structure — {key: {name, description, scanners: [...]}} for clean preset management"

# Metrics
duration: 2min
completed: 2026-02-26
---

# Phase 3.1 Plan 01: Demo Chatbot Summary

**Gemini terminal REPL chatbot with five security presets exercising all meshulash-guard scanner types end-to-end**

## Performance

- **Duration:** 2 min
- **Started:** 2026-02-26T19:38:11Z
- **Completed:** 2026-02-26T19:40:11Z
- **Tasks:** 2 (Task 1: create script; Task 2: verify constructors)
- **Files modified:** 1

## Accomplishments

- Created `demo/chatbot.py` (253 lines) — complete reference implementation of SDK integration
- Five named presets: PII Protection, PII+Overrides, Content Moderation, Cyber Threat Detection, Full Guard
- Full scan-input / gate / LLM / scan-output / deanonymize workflow correctly wired in `chat_turn()`
- All five preset scanner constructors verified against actual SDK source — no enum name mismatches found
- Installed google-genai 1.65.0 into project virtualenv alongside meshulash-guard

## Task Commits

Each task was committed atomically:

1. **Task 1: Install google-genai and create demo/chatbot.py** - `14ac492` (feat)
2. **Task 2: Verify scanner constructor calls match actual SDK signatures** - no separate commit (verification only, no changes needed)

**Plan metadata:** (docs commit follows)

## Files Created/Modified

- `demo/chatbot.py` — Complete Gemini chatbot demo with five security presets, scan/gate/deanonymize workflow, env validation, and developer-realistic scan output formatting

## Decisions Made

- **google-genai vs google-generativeai**: Used `google-genai` 1.65.0 (the current GA SDK) not the deprecated `google-generativeai`. Import pattern is `from google import genai; from google.genai import types`.
- **Model name**: Used `gemini-2.5-flash` — confirmed recommended model as of February 2026. Gemini 2.0 Flash scheduled for retirement June 2026.
- **JailbreakScanner in Full Guard**: Included with comment `# Forward-compatible: activates when server deploys jailbreak TC head`. This makes the demo forward-compatible and documents the pattern for future scanners.
- **MESHULASH_TENANT_ID**: Added as required env var. Guard constructor takes `tenant_id` as positional arg — demo must pass it.
- **Vault persistence**: `guard.clear_cache()` is never called inside the turn loop. Vault accumulates across turns so `deanonymize()` can restore PII that was replaced in an earlier turn's input and echoed back in a later response.
- **TopicLabel members verified**: `TopicLabel.SEXUAL_EXPLICIT` and `TopicLabel.IDENTITY_ATTACK` both exist in the actual SDK source — used correctly in Preset 3.

## Deviations from Plan

None — plan executed exactly as written. All enum member names verified from source before writing the script — no mismatches required fixing.

## Issues Encountered

None. Scanner constructor verification (Task 2) confirmed all five preset scanner lists construct without error. TopicLabel names matched exactly what the research specified.

## User Setup Required

**External services require manual configuration:**

- `GEMINI_API_KEY` — Google AI Studio -> Get API key (https://aistudio.google.com/apikey)
- `MESHULASH_API_KEY` — Meshulash dashboard or deployment config
- `MESHULASH_TENANT_ID` — Meshulash dashboard — tenant identifier
- `MESHULASH_SERVER_URL` — Meshulash server URL (e.g., https://app.meshulash.ai)

Run the demo with:
```bash
export GEMINI_API_KEY="..."
export MESHULASH_API_KEY="..."
export MESHULASH_TENANT_ID="..."
export MESHULASH_SERVER_URL="https://app.meshulash.ai"
.venv/bin/python demo/chatbot.py
```

## Next Phase Readiness

- `demo/chatbot.py` is complete and ready to run against a live meshulash-guard server
- All imports resolve, all scanner constructors verified, 253 lines of reference implementation
- Phase 3.1 is complete — demo chatbot built and verified

---
*Phase: 03.1-demo-chatbot*
*Completed: 2026-02-26*
