# Semantic EQ SDK

Python SDK for the Semantic Equivalence API - optimize prompts for semantic equivalence.

## Installation

```bash
pip install semantic-eq
```

## Quick Start

```python
from semantic_eq_sdk import SemanticEQClient

# Initialize the client (API key is required)
client = SemanticEQClient(
    api_key="your-api-key",  # Get from https://semantic-eq.com
    base_url="https://api.semantic-eq.com"  # or your deployed URL
)

# Optimize a prompt
result = client.optimize_prompt("Write a compelling email subject line for our product launch")

print(f"Original: {result.original_prompt}")
print(f"Optimized: {result.optimized_prompt}")
if result.improvement_score:
    print(f"Improvement score: {result.improvement_score}")
```

## API Reference

### SemanticEQClient

Initialize the client with your API endpoint:

```python
client = SemanticEQClient(
    api_key="your-api-key",           # Required - get from https://semantic-eq.com
    base_url="http://localhost:8001"  # Your API URL
)
```

### optimize_prompt(prompt)

Optimize a single prompt for better semantic equivalence.

**Parameters:**
- `prompt` (str): The prompt text to optimize

**Returns:**
- `OptimizationResult`: Contains original and optimized prompt

**Example:**
```python
result = client.optimize_prompt("Your prompt here")
print(result.optimized_prompt)
```

### health_check()

Check if the API is healthy and accessible.

**Returns:**
- `dict`: Health status information

**Example:**
```python
health = client.health_check()
print(f"API Status: {health['status']}")
```

## Response Objects

### OptimizationResult

The result of a prompt optimization:

```python
@dataclass
class OptimizationResult:
    original_prompt: str           # The original prompt
    optimized_prompt: str          # The optimized version
    improvement_score: float       # Optional improvement score (0-1)
```

## Error Handling

```python
from semantic_eq_sdk import SemanticEQError, OptimizationError

try:
    result = client.optimize_prompt("Your prompt")
    print(result.optimized_prompt)
except OptimizationError as e:
    print(f"Optimization failed: {e}")
except SemanticEQError as e:
    print(f"SDK error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")
```

## API Endpoints

This SDK expects your API to have these endpoints:

- `POST /optimize` - Optimize a prompt
  ```json
  // Request
  {"prompt": "Your prompt text"}
  
  // Response
  {
    "original_prompt": "Your prompt text",
    "optimized_prompt": "Optimized version",
    "improvement_score": 0.85
  }
  ```

- `GET /health` - Health check
  ```json
  // Response
  {"status": "healthy"}
  ```

## Development

### Running Tests

```bash
# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest test/
```

### Code Style

```bash
# Format code
black src/

# Lint code  
flake8 src/
```

## License

MIT License - see LICENSE file for details.