# safe-genai

A PyPI library that wraps Google GenAI (Gemini) with a mandatory 3-step agent pipeline: generation → formatting → validation.

## Package manager & build

- **Package manager**: `uv` (not pip)
- **Build tool**: `uv-build` with hatchling backend
- Install deps: `uv sync`
- Build package: `uv build`
- Run tests: `uv run pytest`

## Project structure

```
safe_genai/           # installable package
  __init__.py
  agent.py            # SafeAgent — public facade
  config.py           # AgentConfig dataclass + default model constants
  result.py           # AgentResult[T] generic dataclass
  exceptions.py       # SafeGenAIError hierarchy
  pipeline/
    orchestrator.py   # Pipeline — retry loop + step sequencing
    generator.py      # Step 1: raw text generation with Google Search grounding
    formatter.py      # Step 2: coerce raw text into Pydantic model via LLM
    validator.py      # Step 3: semantic LLM validation pass/fail
  providers/
    base.py           # BaseProvider ABC
    google.py         # GoogleGenAIProvider
tests/
```

## Key design decisions

- 3-step pipeline always runs: generate → format → validate
- Formatter uses LLM structured output (not regex/JSON heuristics)
- Validator returns pass/fail + feedback string
- `max_retries=0` (default) = one attempt, raises `SafeGenAIValidationError` on failure
- Sync `run()` wraps async `arun()` via `asyncio.run()`
- All three pipeline steps share one provider instance per `SafeAgent`
- Provider abstraction (`BaseProvider`) allows future non-Google providers

## Default models

- Main generator: `gemini-2.5-pro-preview-05-06`
- Formatter + Validator: `gemini-2.0-flash`

## Environment

- `GEMINI_API_KEY` — Google GenAI API key (required at runtime)
- Python 3.12+
