Metadata-Version: 2.4
Name: promptguard-proxy
Version: 0.1.0
Summary: Local runtime prompt optimization and proxy engine for LLM providers.
Author: PromptGuard
License-Expression: MIT
Keywords: llm,prompt-optimization,proxy,fastapi,local-first
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi<1.0.0,>=0.116.0
Requires-Dist: uvicorn[standard]<1.0.0,>=0.31.0
Requires-Dist: pydantic<3.0.0,>=2.8.0
Requires-Dist: PyYAML<7.0.0,>=6.0.2
Requires-Dist: httpx<1.0.0,>=0.28.0
Requires-Dist: typer<1.0.0,>=0.16.0
Requires-Dist: prometheus-client<1.0.0,>=0.21.0
Provides-Extra: dev
Requires-Dist: build<2.0.0,>=1.2.2; extra == "dev"
Requires-Dist: pytest<9.0.0,>=8.3.0; extra == "dev"
Requires-Dist: pytest-asyncio<1.0.0,>=0.24.0; extra == "dev"
Requires-Dist: mypy<2.0.0,>=1.11.0; extra == "dev"
Requires-Dist: ruff<1.0.0,>=0.6.0; extra == "dev"
Requires-Dist: twine<7.0.0,>=6.1.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0.12.20250516; extra == "dev"
Dynamic: license-file

# PromptGuard Proxy

PromptGuard Proxy is a local-first runtime optimization engine that transforms prompts and returns compressed payloads plus optimization metrics.

## Design Principles

- Provider-agnostic optimization: all provider payloads map to a common `PromptRequest` model.
- Compiler-like pipeline: each request is parsed, transformed, optimized, and returned as local output.
- Privacy-first runtime: local execution, local SQLite stats, no telemetry or cloud sync.
- Extensibility: plugin-style optimization passes and adapter registry for new providers.

## Input Compatibility

- Anthropic payload shape
- OpenAI payload shape
- Gemini payload shape
- Groq payload shape
- OpenRouter payload shape

## Architecture

1. Incoming HTTP payload reaches a provider endpoint.
2. Adapter parses provider payload into `PromptRequest`.
3. Optimization pipeline executes pass chain.
4. Prompt AST is generated for diagnostics and pruning support.
5. Optimized request is serialized by adapter.
6. Local response with compressed prompt and stats is returned.
7. Statistics are persisted to SQLite and history is stored in JSONL.

## Project Layout

- `promptguard_proxy/adapters`: provider adapters (parsing, auth, serialization, response conversion only)
- `promptguard_proxy/core`: parser, models, optimizer, tokenizer, serializer, cache, plugins, statistics
- `promptguard_proxy/api`: FastAPI app, routes, dependencies
- `promptguard_proxy/storage`: runtime storage utilities
- `promptguard_proxy/tests`: unit tests

## Quick Start

### 1. Install

```bash
pip install promptguard-proxy
```

### 2. Initialize config

```bash
promptguard init
```

### 3. Configure provider API keys

Edit `promptguard.yaml` and fill provider keys.

### 4. Start proxy

```bash
promptguard start
```

### 5. Check health

```bash
curl http://127.0.0.1:8787/health
```

## API Endpoints

- `GET /health`
- `GET /stats`
- `GET /metrics`
- `GET /providers`
- `GET /history/context`
- `WS /dashboard/ws`
- `POST /v1/chat/completions`
- `POST /v1/messages`
- `POST /history/memory`
- `POST /reload`

## CLI Commands

- `promptguard init`
- `promptguard start`
- `promptguard stop`
- `promptguard status`
- `promptguard config`
- `promptguard doctor`

## Optimization Passes (v1)

- Duplicate Removal
- Prompt Compression
- Context Pruning
- Conversation Compression
- Markdown Compression
- JSON Compression
- Log Compression
- HTML Compression
- Dead Prompt Elimination
- Greedy Token Pruning

Each pass implements:

- `name()`
- `description()`
- `run()`
- `rollback()`
- `statistics()`
- `estimated_savings()`

## Dashboard Stats Shape

`GET /metrics` returns:

```json
{
  "requests": 142,
  "original_tokens": 294221,
  "optimized_tokens": 148003,
  "saved_tokens": 146218,
  "saved_money": 11.82,
  "compression_ratio": 50,
  "provider_usage": {},
  "model_usage": {},
  "optimization_breakdown": {}
}
```

## Testing

```bash
pip install -e .[dev]
pytest
```

## Publishing

Build and validate the distributions before uploading them:

```bash
python -m build
python -m twine check dist/*
python -m twine upload dist/*
```

## Notes

- This repository intentionally does not include cloud sync, user accounts, or telemetry.
- Provider-specific optimization is forbidden by design; only provider-neutral transformations occur.
- External provider API calls are disabled by architecture; this runtime is local-only.
