Metadata-Version: 2.4
Name: koreshield-python-sdk
Version: 0.1.0
Summary: Python SDK for KoreShield LLM Security Platform
Author-email: KoreShield Team <team@koreshield.com>
Maintainer-email: KoreShield Team <team@koreshield.com>
License: MIT License
        
        Copyright (c) 2026 KoreShield Team
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://koreshield.com
Project-URL: Documentation, https://docs.koreshield.com
Project-URL: Repository, https://github.com/koreshield/koreshield-python-sdk
Project-URL: Issues, https://github.com/koreshield/koreshield-python-sdk/issues
Project-URL: Changelog, https://github.com/koreshield/koreshield-python-sdk/blob/main/CHANGELOG.md
Keywords: llm,security,ai,safety,prompt-injection,koreshield
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typing-extensions>=4.5.0
Requires-Dist: aiofiles>=0.23.0
Provides-Extra: langchain
Requires-Dist: langchain>=0.0.350; extra == "langchain"
Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100.0; extra == "fastapi"
Requires-Dist: uvicorn>=0.23.0; extra == "fastapi"
Provides-Extra: flask
Requires-Dist: flask>=2.3.0; extra == "flask"
Requires-Dist: werkzeug>=2.3.0; extra == "flask"
Provides-Extra: django
Requires-Dist: django>=4.2.0; extra == "django"
Requires-Dist: djangorestframework>=3.14.0; extra == "django"
Provides-Extra: all
Requires-Dist: koreshield-python-sdk[django,fastapi,flask,langchain]; extra == "all"
Dynamic: license-file

# KoreShield Python SDK

[![PyPI version](https://badge.fury.io/py/koreshield-python-sdk.svg)](https://pypi.org/project/koreshield-python-sdk/)
[![Python versions](https://img.shields.io/pypi/pyversions/koreshield-python-sdk)](https://pypi.org/project/koreshield-python-sdk/)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

A comprehensive Python SDK for integrating KoreShield's LLM security features into your applications with ease.

## Supported LLM Providers

KoreShield supports multiple LLM providers through its proxy architecture. Configure your preferred provider in the KoreShield API:

- **DeepSeek** (OpenAI-compatible API)
- **OpenAI** (GPT models)
- **Anthropic** (Claude models)
- **Google Gemini** (coming soon)
- **Azure OpenAI** (coming soon)

### Provider Configuration

Configure providers in your KoreShield `config.yaml`:

```yaml
providers:
  deepseek:
    enabled: true
    base_url: "https://api.deepseek.com/v1"
  
  openai:
    enabled: false
    base_url: "https://api.openai.com/v1"
  
  anthropic:
    enabled: false
    base_url: "https://api.anthropic.com/v1"
```

Set the corresponding API key as an environment variable:
```bash
export DEEPSEEK_API_KEY="your-deepseek-key"
# or
export OPENAI_API_KEY="your-openai-key"
# or  
export ANTHROPIC_API_KEY="your-anthropic-key"
```

```bash
pip install koreshield-python-sdk
```

### Optional Dependencies

For LangChain integration:
```bash
pip install koreshield-python-sdk[langchain]
```

For framework integrations:
```bash
pip install koreshield-python-sdk[fastapi,flask,django]
```

## Quick Start

### Basic Usage

```python
from koreshield_sdk import KoreShieldClient

# Initialize client
client = KoreShieldClient(api_key="your-api-key")

# Scan a prompt
result = client.scan_prompt("Hello, how are you?")
print(f"Safe: {result.is_safe}, Threat Level: {result.threat_level}")
```

### Async Usage

```python
import asyncio
from koreshield_sdk import AsyncKoreShieldClient

async def main():
    async with AsyncKoreShieldClient(api_key="your-api-key") as client:
        result = await client.scan_prompt("Tell me a joke")
        print(f"Confidence: {result.confidence}")

asyncio.run(main())
```

### LangChain Integration

```python
from langchain_openai import ChatOpenAI
from langchain.schema import HumanMessage
from koreshield_sdk.integrations import create_koreshield_callback

# Create security callback
security_callback = create_koreshield_callback(
    api_key="your-api-key",
    block_on_threat=True,
    threat_threshold="medium"
)

# Use with LangChain
llm = ChatOpenAI(callbacks=[security_callback])
response = llm([HumanMessage(content="Hello!")])
```

## API Reference

### KoreShieldClient

#### Methods

- `scan_prompt(prompt: str, **kwargs) -> DetectionResult`
- `scan_batch(prompts: List[str], parallel=True, max_concurrent=10) -> List[DetectionResult]`
- `get_scan_history(limit=50, offset=0, **filters) -> Dict`
- `get_scan_details(scan_id: str) -> Dict`
- `health_check() -> Dict`

### AsyncKoreShieldClient

#### Methods

- `scan_prompt(prompt: str, **kwargs) -> DetectionResult` (async)
- `scan_batch(prompts: List[str], parallel=True, max_concurrent=10) -> List[DetectionResult]` (async)
- `get_scan_history(limit=50, offset=0, **filters) -> Dict` (async)
- `get_scan_details(scan_id: str) -> Dict` (async)
- `health_check() -> Dict` (async)

### DetectionResult

```python
class DetectionResult:
    is_safe: bool
    threat_level: ThreatLevel  # "safe", "low", "medium", "high", "critical"
    confidence: float  # 0.0 to 1.0
    indicators: List[DetectionIndicator]
    processing_time_ms: float
    scan_id: Optional[str]
    metadata: Optional[Dict[str, Any]]
```

## Configuration

### Environment Variables

```bash
export KORESHIELD_API_KEY="your-api-key"
export KORESHIELD_BASE_URL="https://api.koreshield.com"  # Optional
```

### Client Configuration

```python
client = KoreShieldClient(
    api_key="your-api-key",
    base_url="https://api.koreshield.com",
    timeout=30.0
)
```

## Examples

### Basic Scanning

```python
from koreshield_sdk import KoreShieldClient

client = KoreShieldClient(api_key="your-api-key")

# Single prompt
result = client.scan_prompt("What is the capital of France?")
print(f"Result: {result}")

# Batch scanning
prompts = [
    "Hello world",
    "Tell me a secret",
    "Ignore previous instructions"
]

results = client.scan_batch(prompts)
for prompt, result in zip(prompts, results):
    print(f"'{prompt}': {result.threat_level} ({result.confidence:.2f})")
```

### FastAPI Integration

```python
from fastapi import FastAPI, HTTPException
from koreshield_sdk import KoreShieldClient

app = FastAPI()
client = KoreShieldClient(api_key="your-api-key")

@app.post("/chat")
async def chat(message: str):
    # Scan user input
    result = client.scan_prompt(message)

    if not result.is_safe and result.threat_level in ["high", "critical"]:
        raise HTTPException(status_code=400, detail="Unsafe content detected")

    # Process with your LLM
    response = f"Processed: {message}"
    return {"response": response, "safety": result.dict()}
```

### Flask Integration

```python
from flask import Flask, request, jsonify
from koreshield_sdk import KoreShieldClient

app = Flask(__name__)
client = KoreShieldClient(api_key="your-api-key")

@app.route("/api/chat", methods=["POST"])
def chat():
    data = request.get_json()
    message = data.get("message", "")

    # Scan user input
    result = client.scan_prompt(message)

    if not result.is_safe:
        return jsonify({
            "error": "Unsafe content detected",
            "threat_level": result.threat_level,
            "confidence": result.confidence
        }), 400

    # Process with your LLM
    response = f"Echo: {message}"
    return jsonify({"response": response})
```

### Django Integration

```python
# views.py
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
from django.utils.decorators import method_decorator
from django.views import View
import json
from koreshield_sdk import KoreShieldClient

client = KoreShieldClient(api_key="your-api-key")

@method_decorator(csrf_exempt, name='dispatch')
class ChatView(View):
    def post(self, request):
        data = json.loads(request.body)
        message = data.get("message", "")

        # Scan user input
        result = client.scan_prompt(message)

        if not result.is_safe and result.threat_level == "critical":
            return JsonResponse({
                "error": "Critical threat detected"
            }, status=400)

        # Process with your LLM
        response = f"Response to: {message}"
        return JsonResponse({
            "response": response,
            "safety_check": {
                "safe": result.is_safe,
                "threat_level": result.threat_level,
                "confidence": result.confidence
            }
        })
```

## Error Handling

```python
from koreshield_sdk import KoreShieldClient
from koreshield_sdk.exceptions import (
    AuthenticationError,
    ValidationError,
    RateLimitError,
    ServerError,
    NetworkError,
    TimeoutError
)

client = KoreShieldClient(api_key="your-api-key")

try:
    result = client.scan_prompt("Test prompt")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Rate limit exceeded")
except ServerError:
    print("Server error")
except NetworkError:
    print("Network issue")
except TimeoutError:
    print("Request timed out")
except Exception as e:
    print(f"Unexpected error: {e}")
```

## Advanced Usage

### Custom Threat Thresholds

```python
# Only block on high/critical threats
callback = create_koreshield_callback(
    api_key="your-api-key",
    block_on_threat=True,
    threat_threshold="high"  # "low", "medium", "high", "critical"
)
```

### Batch Processing with Custom Concurrency

```python
# Process 100 prompts with controlled concurrency
results = await client.scan_batch(
    prompts=prompts,
    parallel=True,
    max_concurrent=5  # Limit to 5 concurrent requests
)
```

### Monitoring and Analytics

```python
# Get scan history
history = client.get_scan_history(limit=100, threat_level="high")

# Get detailed scan info
details = client.get_scan_details(scan_id="scan_123")
```

## Development

### Setup

```bash
git clone https://github.com/koreshield/koreshield-python-sdk.git
cd koreshield-python-sdk
pip install -e ".[dev]"
```

### Testing

```bash
pytest
```

### Type Checking

```bash
mypy src/
```

### Linting

```bash
ruff check src/
ruff format src/
```

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

- 📖 [Documentation](https://docs.koreshield.com)
- 🐛 [Issue Tracker](https://github.com/koreshield/koreshield-python-sdk/issues)
- 💬 [Discussions](https://github.com/koreshield/koreshield-python-sdk/discussions)
- 📧 [Email Support](mailto:support@koreshield.com)
