Metadata-Version: 2.4
Name: semcache
Version: 0.1.0
Summary: A Python library for the Semcache API
Author-email: Louis Cameron Booth <contact@semcache.io>, Jacob Hedén Malm <contact@semcache.io>
License: MIT
Project-URL: Homepage, https://github.com/sensoris/semcache-python
Project-URL: Bug Tracker, https://github.com/sensoris/semcache-python/issues
Project-URL: Documentation, https://github.com/sensoris/semcache-python#readme
Project-URL: Source Code, https://github.com/sensoris/semcache-python
Keywords: cache,semantic,caching,semcache,api,client
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 :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: types-requests>=2.28.0; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# Semcache Python SDK

A Python client library for [Semcache](https://github.com/sensoris/semcache)

## Installation

```bash
pip install semcache
```

## Quick Start

```python
from semcache import Semcache

# Initialize the client
client = Semcache(base_url="http://localhost:8080")

# Store a key-data pair
client.put("What is the capital of France?", "Paris")

# Retrieve data by semantic similarity
response = client.get("What's the capital city of France?")
print(response)  # "Paris"
```

The above snippet requires a running Semcache server. You can start one using Docker:

```bash
docker run -p 8080:8080 ghcr.io/sensoris/semcache:latest
````

## Configuration

```python
client = Semcache(
    base_url="http://localhost:8080",  # Semcache server URL
    timeout=30,                         # Request timeout in seconds
)
```

## Usage Examples

### Basic Usage

```python
from semcache import Semcache

# Create a client instance
client = Semcache()

# Store some key-data pairs
client.put("What is Python?", "Python is a high-level programming language")
client.put("What is machine learning?", "Machine learning is a subset of AI that enables systems to learn from data")

# Retrieve data - exact match not required
response = client.get("Tell me about Python")
print(response)  # "Python is a high-level programming language"
```

### Error Handling

```python
from semcache import Semcache, SemcacheConnectionError, SemcacheTimeoutError

client = Semcache(base_url="http://localhost:8080", timeout=5)

try:
    client.put("test query", "test response")
except SemcacheConnectionError:
    print("Failed to connect to Semcache server")
except SemcacheTimeoutError:
    print("Request timed out")
```

## API Reference

### `Semcache(base_url="http://localhost:8080", timeout=30)`

Initialize a new Semcache client.

**Parameters:**
- `base_url` (str): The base URL of the Semcache server
- `timeout` (int): Request timeout in seconds

### `put(key: str, data: str) -> None`

Store a key-data pair in the cache.

**Parameters:**
- `key` (str): The key/query to cache
- `data` (str): The data/response to cache

**Raises:**
- `SemcacheError`: If the request fails

### `get(key: str) -> Optional[str]`

Retrieve cached data for a key using semantic similarity.

**Parameters:**
- `key` (str): The key/query to look up

**Returns:**
- `Optional[str]`: The cached data if found, None otherwise

**Raises:**
- `SemcacheError`: If the request fails

## Exceptions

- `SemcacheError`: Base exception for all Semcache errors
- `SemcacheConnectionError`: Raised when unable to connect to the server
- `SemcacheTimeoutError`: Raised when a request times out
- `SemcacheAPIError`: Raised when the API returns an error response

## Development

### Setup Development Environment

```bash
# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

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

### Run Tests

```bash
pytest
```

### Format Code

```bash
black src tests
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit a pull request.
