Implement cache-aside client

.github/workflows/tests.yml

@@ -0,0 +1,39 @@
+name: Tests
+
+on:
+  push
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[dev]"
+
+    - name: Format check with black
+      run: |
+        black --check src tests
+
+    - name: Type check with mypy
+      run: |
+        mypy src
+
+    - name: Run unit tests
+      run: |
+        pytest tests/test_client.py -v --cov=semcache --cov-report=xml
+
+
+    # todo run integration tests pointing at real docker image of semcache

.gitignore

@@ -0,0 +1,140 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/
+
+# VSCode
+.vscode/
+
+# macOS
+.DS_Store
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# Project specific
+*.log
+.cache/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sensoris
+
+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.

MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE
+include README.md
+include pyproject.toml
+include src/semcache/py.typed
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]

Makefile

@@ -0,0 +1,36 @@
+.PHONY: install install-dev test test-integration test-all coverage format type-check clean build upload upload-test
+
+install:
+	pip install -e .
+
+install-dev:
+	pip install -e ".[dev]"
+
+test:
+	PYTHONPATH=src pytest tests/test_client.py -v
+
+test-integration:
+	PYTHONPATH=src pytest tests/test_integration.py
+
+format:
+	black src tests
+
+type-check:
+	mypy src
+
+clean:
+	rm -rf build/
+	rm -rf dist/
+	rm -rf *.egg-info
+	rm -rf src/*.egg-info
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+
+build: clean
+	python -m build
+
+upload-test: build
+	twine upload --repository testpypi dist/*
+
+upload: build
+	twine upload dist/*

README.md

@@ -0,0 +1,142 @@
+# 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"
+```
+
+## 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.