Metadata-Version: 2.4
Name: gateforge-sdk
Version: 0.1.0
Summary: Privacy-first LLMOps SDK — Automatic PII masking, cost tracking, and prompt management for LLM applications
Project-URL: Homepage, https://gateforge.dev
Project-URL: Documentation, https://gateforge.dev/docs
Project-URL: Repository, https://github.com/gateforge/gateforge-sdk
Project-URL: Dashboard, https://app.gateforge.dev
Project-URL: Bug Tracker, https://github.com/gateforge/gateforge-sdk/issues
Author-email: Gateforge Team <support@gateforge.dev>
License: MIT
License-File: LICENSE
Keywords: anthropic,gemini,llm,llmops,mlops,openai,pii,privacy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: pii-firewall[langdetect,presidio]
Provides-Extra: all
Requires-Dist: anthropic>=0.40.0; extra == 'all'
Requires-Dist: google-genai>=1.0.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40.0; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Provides-Extra: gemini
Requires-Dist: google-genai>=1.0.0; extra == 'gemini'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

# Gateforge SDK

**Privacy-first LLMOps SDK** — Automatic PII masking, cost tracking, and prompt management for LLM applications.

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

## 🔒 What is Gateforge?

Gateforge is an LLMOps platform that automatically protects sensitive data (PII) in your LLM applications. The SDK processes everything **locally** — no content ever leaves your infrastructure.

> **Note:** This SDK is free and open source (MIT license). It requires a Gateforge account to use. We offer a generous free tier: **1,000 requests/month**. See [pricing](https://gateforge.dev/pricing) for details.

**Key Features:**
- ✅ **Automatic PII Detection & Masking** — Names, emails, SSN, phone numbers, credit cards, and more
- ✅ **Multi-Provider Support** — OpenAI, Anthropic, Gemini with unified interface
- ✅ **Cost Tracking** — Real-time metrics and dashboards
- ✅ **Domain-Specific Detection** — Healthcare, Finance, Legal, Generic
- ✅ **Custom Regex Patterns** — Add your own entity types
- ✅ **Zero Network Overhead** — All PII processing happens locally

## 🚀 Quick Start

### Installation

```bash
pip install gateforge-sdk
```

With provider support:
```bash
pip install gateforge-sdk[openai]      # OpenAI only
pip install gateforge-sdk[anthropic]   # Anthropic only
pip install gateforge-sdk[gemini]      # Google Gemini only
pip install gateforge-sdk[all]         # All providers
```

### Get Your API Key

1. Sign up at [https://gateforge.dev](https://gateforge.dev)
2. Get your API key from [https://app.gateforge.dev/dashboard/keys](https://app.gateforge.dev/dashboard/keys)

### Basic Usage

```python
import gateforge

# Initialize once at startup
gateforge.init(
    api_key="your-gateforge-api-key",
    openai_key="your-openai-key",
)

# Make LLM calls with automatic PII protection
response = gateforge.chat(
    model="gpt-4.1-nano",
    messages=[
        {"role": "user", "content": "My email is john@example.com, can you help?"}
    ]
)

print(response.content)          # "Hello! I'd be happy to help..."
print(response.pii_detected)     # ['EMAIL']
print(response.tokens)           # 45
print(response.cost_usd)         # 0.000023
```

## 📖 Examples

### Healthcare Domain

```python
response = gateforge.chat(
    model="gpt-4.1-nano",
    messages=[
        {
            "role": "user",
            "content": "Patient John Doe, SSN 123-45-6789, has hypertension. Recommend treatment."
        }
    ],
    pii_domain="healthcare"  # Detects medical entities
)

print(response.pii_detected)  # ['PERSON', 'SSN', 'SYMPTOM']
```

### Multiple Providers

```python
import gateforge

gateforge.init(
    api_key="your-gateforge-key",
    openai_key="sk-...",
    anthropic_key="sk-ant-...",
    gemini_key="...",
)

# OpenAI
r1 = gateforge.chat(model="gpt-4.1-nano", messages=[...])

# Anthropic
r2 = gateforge.chat(model="claude-haiku-4-5", messages=[...])

# Gemini
r3 = gateforge.chat(model="gemini-2.5-flash", messages=[...])
```

### Custom PII Patterns

Configure custom patterns in your dashboard at [https://app.gateforge.dev/dashboard/pii/settings](https://app.gateforge.dev/dashboard/pii/settings), and the SDK will download them automatically.

## 🔧 Configuration

### Initialization Options

```python
gateforge.init(
    api_key="your-gateforge-api-key",    # Required
    openai_key="sk-...",                  # Optional
    anthropic_key="sk-ant-...",           # Optional
    gemini_key="...",                     # Optional
)
```

### Chat Parameters

```python
response = gateforge.chat(
    model="gpt-4.1-nano",              # Required: model name
    messages=[...],                     # Required: chat messages
    pii_domain="generic",              # Optional: "generic", "healthcare", "finance", "legal"
    provider_key="sk-...",             # Optional: override provider key
    prompt_id="user-signup",           # Optional: for prompt tracking
    temperature=0.7,                   # Optional: model parameters
    max_tokens=500,                    # Optional: model parameters
)
```

### Response Object

```python
response = gateforge.chat(...)

response.content           # str: The response content
response.pii_detected      # list[str]: Detected PII types
response.tokens            # int: Total tokens
response.prompt_tokens     # int: Input tokens
response.completion_tokens # int: Output tokens
response.cost_usd          # float: Cost in USD
response.latency_ms        # float: Latency in milliseconds
response.model             # str: Model used
response.raw               # dict: Raw provider response
```

## 🔒 Privacy & Security

### How it Works

1. **Local Processing**: All PII detection happens locally in your environment
2. **Content Never Sent**: Only metadata (tokens, cost) is sent to Gateforge API
3. **Automatic Masking**: PII is replaced with tokens before sending to LLM providers
4. **Automatic Rehydration**: Responses are reconstructed with original context

### What Gets Detected?

- **Personal**: Names, emails, phone numbers, addresses
- **Financial**: Credit cards, bank accounts, SSN, tax IDs
- **Healthcare**: Medical record numbers, symptoms, diagnoses
- **Technical**: IP addresses, URLs, API keys
- **Custom**: Your own regex patterns

### Supported Backends

- **Presidio** (default): ML-based, highest accuracy
- **Regex**: Pattern matching, fastest
- **Hybrid**: Combined ML + regex
- **GLiNER**: Zero-shot NER
- **Transformers**: HuggingFace models

## 📊 Dashboard & Monitoring

View real-time metrics at [https://app.gateforge.dev/dashboard](https://app.gateforge.dev/dashboard):

- 📈 Request volume and trends
- 💰 Cost breakdown by model and provider
- ⚡ Latency analytics
- 🔒 PII detection statistics
- 🔑 API key management

## 🛠️ Advanced Usage

### Streaming (Coming Soon)

```python
for chunk in gateforge.chat_stream(model="gpt-4.1-nano", messages=[...]):
    print(chunk.content, end="", flush=True)
```

### Async Support (Coming Soon)

```python
response = await gateforge.achat(model="gpt-4.1-nano", messages=[...])
```

### Direct Anonymization

```python
from gateforge.pii import anonymize_messages

context = {
    "tenant_id": "user-123",
    "case_id": "case-456",
    "thread_id": "thread-789",
    "actor_id": "user"
}

anonymized, entities = anonymize_messages(
    messages=[{"role": "user", "content": "My email is john@example.com"}],
    domain="generic",
    backend="presidio",
    context=context
)

print(anonymized)  # [{"role": "user", "content": "My email is [EMAIL_001]"}]
print(entities)    # ['EMAIL']
```

## 🌐 Supported Models

### OpenAI
- GPT-4.1-nano, GPT-4.1-mini, GPT-4.1, GPT-4.1-turbo
- GPT-4o, GPT-4o-mini
- GPT-3.5-turbo

### Anthropic
- Claude Haiku 4-5
- Claude Sonnet 4-5
- Claude Opus 4

### Google Gemini
- Gemini 2.5 Flash
- Gemini 2.5 Pro

## 📝 Configuration via Dashboard

### PII Settings

1. Go to [https://app.gateforge.dev/dashboard/pii/settings](https://app.gateforge.dev/dashboard/pii/settings)
2. Select domain: Generic, Healthcare, Finance, Legal
3. Choose backend: Presidio, Regex, Hybrid
4. Set language: Auto-detect or specific language
5. Add custom regex patterns

The SDK downloads your configuration automatically on init.

### Custom Patterns

Add patterns like:
```
Entity Type: EMPLOYEE_ID
Regex: EMP-\d{6}
Confidence: 0.95
```

## 🐛 Troubleshooting

### ImportError: No module named 'gateforge'

```bash
pip install gateforge-sdk
```

### RuntimeError: Call gateforge.init() first

Make sure to initialize before making calls:
```python
gateforge.init(api_key="your-key")
```

### API Key Not Working

1. Verify your key at [https://app.gateforge.dev/dashboard/keys](https://app.gateforge.dev/dashboard/keys)
2. Check it's not revoked
3. Ensure you're using the correct environment

### PII Not Detected

1. Check your domain setting matches your use case
2. Try different backends (presidio is most accurate)
3. Add custom patterns for domain-specific entities

## 📚 Documentation

- **Website**: [https://gateforge.dev](https://gateforge.dev)
- **Dashboard**: [https://app.gateforge.dev](https://app.gateforge.dev)
- **API Docs**: [https://api.gateforge.dev/docs](https://api.gateforge.dev/docs)

## 🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request.

## 📄 License

MIT License - See [LICENSE](LICENSE) for details.

**Important:** While the SDK is open source, the Gateforge service is commercial. You need a Gateforge account (free tier available) to use this SDK.

## 🔗 Links

- [Website](https://gateforge.dev)
- [Dashboard](https://app.gateforge.dev)
- [API Health](https://api.gateforge.dev/v1/health)
- [Documentation](https://gateforge.dev/docs)

## 💬 Support

- **Email**: support@gateforge.dev
- **Issues**: [GitHub Issues](https://github.com/gateforge/gateforge-sdk/issues)

---

**Made with ❤️ by the Gateforge team**
