promptguard-proxy 0.1.0

Local runtime prompt optimization and proxy engine for LLM providers.

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

pip install promptguard-proxy

2. Initialize config

promptguard init

3. Configure provider API keys

Edit promptguard.yaml and fill provider keys.

4. Start proxy

promptguard start

5. Check health

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:

{
  "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

pip install -e .[dev]
pytest

Publishing

Build and validate the distributions before uploading them:

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.