tano-shield 0.1.0
API client for Tano Shield AI security services
Requires Python: >=3.10
Keywords: ai, security, firewall, pii, redaction, tano, shield

# Tano Shield

A Python client library for interacting with the Tano Shield AI security services.

## Installation

```bash
pip install tano-shield
# or
poetry add tano-shield
```

## Features

- **AI Issue Detector**: Protect your AI applications from harmful inputs and outputs
- **PII Redaction**: Detect and redact personally identifiable information

## Usage

### Quick Start

```python
from tano_shield import TanoShield

# Initialize the client with your API key
tano_shield = TanoShield(api_key="your-api-key")

# Use the services
def example():
    try:
        # Check user input with the Issue Detector
        firewall_result = tano_shield.firewall.check_input(
            system_prompt="You are a helpful AI assistant",
            user_input="Tell me about AI security",
            response="I can provide information about AI security...",
            event_id="conversation-12345",
            security_checks=[
                "sycophancy",
                "faithfulness",
                "harmfulness",
                "implausible_output",
                "information_disclosure",
                "jailbreak"
            ]
        )
        print('Issue Detector check result:', firewall_result)
        
        # Redact PII from text
        pii_result = tano_shield.pii.redact_text(
            text='My email is john.doe@example.com and my phone is 555-123-4567'
        )
        print('Redacted text:', pii_result['redacted_text'])
    except Exception as error:
        print('Error:', error)

example()
```

### Using Individual Services

You can also use each service independently:

```python
from tano_shield.firewall import FirewallClient
from tano_shield.pii import PIIClient

# Initialize just the Issue Detector client
firewall = FirewallClient(api_key="your-api-key")

# Check user input
result = firewall.check_input(
    user_input='User message here',
    system_prompt='You are a helpful assistant'
)
```

## API Reference

### TanoShield

The main client that provides access to all services.

```python
tano_shield = TanoShield(
    api_key="your-api-key",
    base_url="https://api.example.com",  # Optional
    timeout=30,  # Optional (default: 30)
    version="v1"  # Optional (default: 'v1')
)
```

#### Properties

- `firewall`: FirewallClient instance
- `pii`: PIIClient instance
- `CREDIT_CONSTANTS`: Credit cost constants

#### Methods

- `set_api_key(api_key)`: Update the API key for all services

### FirewallClient (Issue Detector)

Client for the AI Issue Detector service.

#### Methods

- `check_input(**params)`: Check user input for security issues
  - `params['system_prompt']`: The system prompt (optional)
  - `params['user_input']`: The user input to check (required)
  - `params['response']`: The AI response to check (optional)
  - `params['event_id']`: A unique identifier for the event (optional)
  - `params['security_checks']`: List of security checks to perform (optional)
- `get_settings()`: Get Issue Detector settings
- `update_settings(settings)`: Update Issue Detector settings
- `get_history(**options)`: Get Issue Detector call history
- `get_analytics(**options)`: Get Issue Detector analytics

### PIIClient

Client for the PII Redaction service.

#### Methods

- `redact_text(text, entity_types=None, mask_mode=False)`: Redact PII from text
- `detect_pii(text, entity_types=None)`: Detect PII in text without redacting
- `get_supported_entity_types()`: Get supported PII entity types

## Credit System

Tano Shield uses a credit system for API usage. Each API call consumes credits based on the service used.

```python
from tano_shield import CREDIT_CONSTANTS

print(CREDIT_CONSTANTS.FREE_CREDITS_PER_MONTH)  # 1000
print(CREDIT_CONSTANTS.FIREWALL_CHECK_COST)     # 1
print(CREDIT_CONSTANTS.PII_REDACTION_COST)      # 1
```

## Error Handling

The library provides custom error classes for different types of errors:

```python
from tano_shield.core.errors import (
    TanoShieldError, 
    AuthenticationError, 
    ApiRequestError
)

try:
    tano_shield.firewall.check_input(user_input='test')
except AuthenticationError as error:
    print('Authentication failed:', error)
except ApiRequestError as error:
    print('API request failed:', error, error.status)
except TanoShieldError as error:
    print('Tano Shield error:', error, error.code)
except Exception as error:
    print('Unknown error:', error)
```

## Example API Call

Here's an example of how to use the Issue Detector with requests:

```python
import requests
import json

url = "https://api.tanolabs.com/api/v1/firewall-check"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
data = {
    "prompt": "Tell me about AI security",
    "system_prompt": "You are a helpful AI assistant",
    "user_input": "Tell me about AI security",
    "response": "I can provide information about AI security...",
    "event_id": "conversation-12345",
    "securityChecks": ["sycophancy", "faithfulness", "harmfulness", "implausible_output", "information_disclosure", "jailbreak"]
}

response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.json())
```

## Building and Publishing

### Local Development

To build and install the package locally:

```bash
# Navigate to the package directory
cd tano-shield-py

# Run the build and install script
./build_and_install.sh
```

### Publishing to PyPI

To publish the package to PyPI:

1. Update the version number in `setup.py` and `pyproject.toml`
2. Run the publish script:
   ```bash
   ./publish_to_pypi.sh
   ```
3. Follow the prompts to publish to TestPyPI or PyPI

For detailed instructions, see [PUBLISHING.md](PUBLISHING.md).

## License

MIT