semantis 0.1.0__tar.gz

semantis-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include pyproject.toml
+recursive-include semantis *.py
+recursive-exclude semantis_ai_semantic_cache_api_client *
+exclude test_local.py
+prune semantis_ai_semantic_cache_api_client
+prune .ruff_cache

semantis-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: semantis
+Version: 0.1.0
+Summary: Python SDK for Semantis AI - Semantic LLM Cache
+Author: Semantis AI
+License: MIT
+Project-URL: Homepage, https://semantis.ai
+Project-URL: Documentation, https://docs.semantis.ai
+Project-URL: Repository, https://github.com/semantis-ai/semantis-python
+Keywords: llm,cache,semantic,openai,gpt
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: respx; extra == "dev"
+
+# Semantis Python SDK
+
+Drop-in replacement for the OpenAI Python client with automatic semantic caching.
+
+## Installation
+
+```bash
+pip install semantis
+```
+
+For automatic OpenAI fallback when Semantis is unreachable:
+
+```bash
+pip install semantis[openai]
+```
+
+## Quick Start
+
+```python
+from semantis import SemantisCache
+
+cache = SemantisCache(api_key="sc-myorg-xxxxxxxx")
+
+# OpenAI-compatible interface
+response = cache.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "What is machine learning?"}],
+)
+print(response.choices[0].message.content)
+print(f"Cache: {response.meta.hit} | Similarity: {response.meta.similarity}")
+```
+
+## Zero-Code Integration (Proxy Mode)
+
+Point your existing OpenAI client at Semantis:
+
+```python
+import openai
+
+client = openai.OpenAI(
+    base_url="https://api.semantis.ai/v1",
+    api_key="sc-myorg-xxxxxxxx",
+)
+
+# Existing code works unchanged - caching is transparent
+response = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "What is ML?"}],
+)
+```
+
+## Self-Hosted
+
+```python
+cache = SemantisCache(
+    api_key="sc-myorg-xxxxxxxx",
+    base_url="http://localhost:8000",
+)
+```
+
+## Features
+
+- **OpenAI-compatible**: Drop-in replacement, same interface
+- **Automatic retry**: Exponential backoff on 429/5xx errors
+- **Fallback**: If Semantis is unreachable, falls back to direct OpenAI (with `[openai]` extra)
+- **Cache metadata**: Every response includes `meta.hit`, `meta.similarity`, `meta.latency_ms`
+- **Context manager**: Use with `with` for automatic cleanup

semantis-0.1.0/README.md

@@ -0,0 +1,67 @@
+# Semantis Python SDK
+
+Drop-in replacement for the OpenAI Python client with automatic semantic caching.
+
+## Installation
+
+```bash
+pip install semantis
+```
+
+For automatic OpenAI fallback when Semantis is unreachable:
+
+```bash
+pip install semantis[openai]
+```
+
+## Quick Start
+
+```python
+from semantis import SemantisCache
+
+cache = SemantisCache(api_key="sc-myorg-xxxxxxxx")
+
+# OpenAI-compatible interface
+response = cache.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "What is machine learning?"}],
+)
+print(response.choices[0].message.content)
+print(f"Cache: {response.meta.hit} | Similarity: {response.meta.similarity}")
+```
+
+## Zero-Code Integration (Proxy Mode)
+
+Point your existing OpenAI client at Semantis:
+
+```python
+import openai
+
+client = openai.OpenAI(
+    base_url="https://api.semantis.ai/v1",
+    api_key="sc-myorg-xxxxxxxx",
+)
+
+# Existing code works unchanged - caching is transparent
+response = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "What is ML?"}],
+)
+```
+
+## Self-Hosted
+
+```python
+cache = SemantisCache(
+    api_key="sc-myorg-xxxxxxxx",
+    base_url="http://localhost:8000",
+)
+```
+
+## Features
+
+- **OpenAI-compatible**: Drop-in replacement, same interface
+- **Automatic retry**: Exponential backoff on 429/5xx errors
+- **Fallback**: If Semantis is unreachable, falls back to direct OpenAI (with `[openai]` extra)
+- **Cache metadata**: Every response includes `meta.hit`, `meta.similarity`, `meta.latency_ms`
+- **Context manager**: Use with `with` for automatic cleanup

semantis-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "semantis"
+version = "0.1.0"
+description = "Python SDK for Semantis AI - Semantic LLM Cache"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+authors = [
+    {name = "Semantis AI"},
+]
+keywords = ["llm", "cache", "semantic", "openai", "gpt"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[project.optional-dependencies]
+openai = ["openai>=1.0.0"]
+dev = ["pytest", "pytest-asyncio", "respx"]
+
+[project.urls]
+Homepage = "https://semantis.ai"
+Documentation = "https://docs.semantis.ai"
+Repository = "https://github.com/semantis-ai/semantis-python"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["semantis"]

semantis-0.1.0/semantis/__init__.py

@@ -0,0 +1,40 @@
+"""
+Semantis AI Python SDK
+
+Drop-in replacement for OpenAI with automatic semantic caching.
+
+Usage:
+    from semantis import SemantisCache
+
+    cache = SemantisCache(api_key="sc-myorg-xxxxxxxx")
+    response = cache.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=[{"role": "user", "content": "What is ML?"}],
+    )
+    print(response.choices[0].message.content)
+"""
+
+from semantis.client import SemantisCache
+from semantis.models import (
+    ChatCompletion,
+    ChatCompletionMessage,
+    ChatCompletionChoice,
+    ChatCompletionChunk,
+    ChatCompletionChunkDelta,
+    ChatCompletionChunkChoice,
+    CacheMeta,
+    Usage,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "SemantisCache",
+    "ChatCompletion",
+    "ChatCompletionMessage",
+    "ChatCompletionChoice",
+    "ChatCompletionChunk",
+    "ChatCompletionChunkDelta",
+    "ChatCompletionChunkChoice",
+    "CacheMeta",
+    "Usage",
+]

semantis-0.1.0/semantis/client.py

@@ -0,0 +1,219 @@
+"""
+Semantis AI Client - OpenAI-compatible interface with automatic semantic caching.
+"""
+
+import json
+import time
+from typing import Generator, Iterator, Optional, List, Dict, Any, Union
+
+import httpx
+
+from semantis.models import ChatCompletion, ChatCompletionChunk
+
+
+_DEFAULT_BASE_URL = "https://api.semantis.ai"
+_DEFAULT_TIMEOUT = 60.0
+_MAX_RETRIES = 3
+
+
+class _Completions:
+    """Mirrors openai.chat.completions interface."""
+
+    def __init__(self, client: "SemantisCache"):
+        self._client = client
+
+    def create(
+        self,
+        *,
+        model: str = "gpt-4o-mini",
+        messages: List[Dict[str, str]],
+        temperature: float = 0.2,
+        stream: bool = False,
+        ttl_seconds: int = 604800,
+        **kwargs,
+    ) -> Union[ChatCompletion, Iterator["ChatCompletionChunk"]]:
+        """Create a chat completion (with automatic semantic caching).
+
+        Accepts the same parameters as ``openai.chat.completions.create``.
+        When ``stream=True``, returns an iterator of ``ChatCompletionChunk``.
+        """
+        payload: Dict[str, Any] = {
+            "model": model,
+            "messages": messages,
+            "temperature": temperature,
+            "stream": stream,
+            "ttl_seconds": ttl_seconds,
+        }
+        payload.update(kwargs)
+
+        if stream:
+            return self._client._post_stream("/v1/chat/completions", json=payload)
+
+        data = self._client._post("/v1/chat/completions", json=payload)
+        return ChatCompletion.from_dict(data)
+
+
+class _Chat:
+    """Mirrors openai.chat namespace."""
+
+    def __init__(self, client: "SemantisCache"):
+        self.completions = _Completions(client)
+
+
+class SemantisCache:
+    """Semantis AI SDK client.
+
+    Drop-in replacement for ``openai.OpenAI`` that routes requests through
+    the Semantis semantic cache.
+
+    Example::
+
+        from semantis import SemantisCache
+
+        cache = SemantisCache(api_key="sc-myorg-xxxxxxxx")
+        resp = cache.chat.completions.create(
+            model="gpt-4o-mini",
+            messages=[{"role": "user", "content": "What is ML?"}],
+        )
+        print(resp.choices[0].message.content)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: int = _MAX_RETRIES,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            timeout=self.timeout,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": "semantis-python/0.1.0",
+            },
+        )
+        self.chat = _Chat(self)
+
+    def _post(self, path: str, **kwargs) -> dict:
+        """POST with retry + exponential backoff."""
+        last_exc: Optional[Exception] = None
+        for attempt in range(self.max_retries):
+            try:
+                resp = self._http.post(path, **kwargs)
+                if resp.status_code == 429:
+                    wait = min(2 ** attempt, 8)
+                    time.sleep(wait)
+                    continue
+                resp.raise_for_status()
+                return resp.json()
+            except httpx.HTTPStatusError as e:
+                if e.response.status_code >= 500:
+                    last_exc = e
+                    time.sleep(min(2 ** attempt, 8))
+                    continue
+                raise
+            except (httpx.ConnectError, httpx.ReadTimeout) as e:
+                last_exc = e
+                if attempt == self.max_retries - 1:
+                    return self._openai_fallback(path, kwargs)
+                time.sleep(min(2 ** attempt, 8))
+        if last_exc:
+            raise last_exc
+        raise RuntimeError("Request failed after retries")
+
+    def _post_stream(self, path: str, **kwargs) -> Generator[ChatCompletionChunk, None, None]:
+        """POST with SSE streaming. Yields ChatCompletionChunk objects."""
+        with self._http.stream("POST", path, **kwargs) as resp:
+            resp.raise_for_status()
+            for line in resp.iter_lines():
+                if not line or not line.startswith("data: "):
+                    continue
+                data_str = line[6:]
+                if data_str.strip() == "[DONE]":
+                    return
+                try:
+                    data = json.loads(data_str)
+                    yield ChatCompletionChunk.from_dict(data)
+                except json.JSONDecodeError:
+                    continue
+
+    def _openai_fallback(self, path: str, kwargs: dict) -> dict:
+        """When Semantis is unreachable, fall back to direct OpenAI call."""
+        try:
+            import openai as _openai
+            payload = kwargs.get("json", {})
+            # Remove Semantis-specific params that OpenAI doesn't accept
+            openai_payload = {k: v for k, v in payload.items() if k not in ("ttl_seconds",)}
+            client = _openai.OpenAI()
+            resp = client.chat.completions.create(**openai_payload)
+            return {
+                "id": resp.id,
+                "object": resp.object,
+                "created": resp.created,
+                "model": resp.model,
+                "choices": [
+                    {
+                        "index": c.index,
+                        "message": {"role": c.message.role, "content": c.message.content},
+                        "finish_reason": c.finish_reason,
+                    }
+                    for c in resp.choices
+                ],
+                "usage": {
+                    "prompt_tokens": resp.usage.prompt_tokens if resp.usage else None,
+                    "completion_tokens": resp.usage.completion_tokens if resp.usage else None,
+                    "total_tokens": resp.usage.total_tokens if resp.usage else None,
+                },
+                "meta": {"hit": "fallback", "similarity": 0.0, "latency_ms": 0, "strategy": "openai_fallback"},
+            }
+        except ImportError:
+            raise RuntimeError(
+                "Semantis API unreachable and openai package not installed for fallback. "
+                "Install with: pip install semantis[openai]"
+            )
+        except Exception as e:
+            raise RuntimeError(f"Both Semantis and OpenAI fallback failed: {e}")
+
+    # ── Convenience methods ──
+
+    def query(self, prompt: str, model: str = "gpt-4o-mini") -> dict:
+        """Simple query interface (non-OpenAI-compatible)."""
+        resp = self._http.get("/query", params={"prompt": prompt, "model": model})
+        resp.raise_for_status()
+        return resp.json()
+
+    def health(self) -> dict:
+        """Check Semantis API health."""
+        resp = self._http.get("/health")
+        resp.raise_for_status()
+        return resp.json()
+
+    def metrics(self) -> dict:
+        """Get cache metrics for the authenticated tenant."""
+        resp = self._http.get("/metrics")
+        resp.raise_for_status()
+        return resp.json()
+
+    def close(self):
+        """Close the underlying HTTP client."""
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def __del__(self):
+        try:
+            self.close()
+        except Exception:
+            pass

semantis-0.1.0/semantis/models.py

@@ -0,0 +1,128 @@
+"""Response models mirroring OpenAI's API shape."""
+
+from dataclasses import dataclass, field
+from typing import Optional, List, Dict, Any
+
+
+@dataclass
+class ChatCompletionMessage:
+    role: str
+    content: str
+
+    def to_dict(self) -> dict:
+        return {"role": self.role, "content": self.content}
+
+
+@dataclass
+class Usage:
+    prompt_tokens: Optional[int] = None
+    completion_tokens: Optional[int] = None
+    total_tokens: Optional[int] = None
+
+
+@dataclass
+class CacheMeta:
+    hit: str = "miss"
+    similarity: float = 0.0
+    latency_ms: float = 0.0
+    strategy: str = "miss"
+
+
+@dataclass
+class ChatCompletionChoice:
+    index: int
+    message: ChatCompletionMessage
+    finish_reason: str = "stop"
+
+
+@dataclass
+class ChatCompletion:
+    id: str
+    object: str = "chat.completion"
+    created: int = 0
+    model: str = ""
+    choices: List[ChatCompletionChoice] = field(default_factory=list)
+    usage: Optional[Usage] = None
+    meta: Optional[CacheMeta] = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ChatCompletion":
+        choices = []
+        for c in data.get("choices", []):
+            msg = c.get("message", {})
+            choices.append(ChatCompletionChoice(
+                index=c.get("index", 0),
+                message=ChatCompletionMessage(
+                    role=msg.get("role", "assistant"),
+                    content=msg.get("content", ""),
+                ),
+                finish_reason=c.get("finish_reason", "stop"),
+            ))
+
+        usage_data = data.get("usage")
+        usage = Usage(
+            prompt_tokens=usage_data.get("prompt_tokens") if usage_data else None,
+            completion_tokens=usage_data.get("completion_tokens") if usage_data else None,
+            total_tokens=usage_data.get("total_tokens") if usage_data else None,
+        ) if usage_data else None
+
+        meta_data = data.get("meta")
+        meta = CacheMeta(
+            hit=meta_data.get("hit", "miss"),
+            similarity=meta_data.get("similarity", 0.0),
+            latency_ms=meta_data.get("latency_ms", 0.0),
+            strategy=meta_data.get("strategy", "miss"),
+        ) if meta_data else None
+
+        return cls(
+            id=data.get("id", ""),
+            object=data.get("object", "chat.completion"),
+            created=data.get("created", 0),
+            model=data.get("model", ""),
+            choices=choices,
+            usage=usage,
+            meta=meta,
+        )
+
+
+@dataclass
+class ChatCompletionChunkDelta:
+    role: Optional[str] = None
+    content: Optional[str] = None
+
+
+@dataclass
+class ChatCompletionChunkChoice:
+    index: int = 0
+    delta: ChatCompletionChunkDelta = field(default_factory=ChatCompletionChunkDelta)
+    finish_reason: Optional[str] = None
+
+
+@dataclass
+class ChatCompletionChunk:
+    id: str = ""
+    object: str = "chat.completion.chunk"
+    created: int = 0
+    model: str = ""
+    choices: List[ChatCompletionChunkChoice] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ChatCompletionChunk":
+        choices = []
+        for c in data.get("choices", []):
+            delta = c.get("delta", {})
+            choices.append(ChatCompletionChunkChoice(
+                index=c.get("index", 0),
+                delta=ChatCompletionChunkDelta(
+                    role=delta.get("role"),
+                    content=delta.get("content"),
+                ),
+                finish_reason=c.get("finish_reason"),
+            ))
+        return cls(
+            id=data.get("id", ""),
+            object=data.get("object", "chat.completion.chunk"),
+            created=data.get("created", 0),
+            model=data.get("model", ""),
+            choices=choices,
+        )

semantis-0.1.0/semantis.egg-info/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: semantis
+Version: 0.1.0
+Summary: Python SDK for Semantis AI - Semantic LLM Cache
+Author: Semantis AI
+License: MIT
+Project-URL: Homepage, https://semantis.ai
+Project-URL: Documentation, https://docs.semantis.ai
+Project-URL: Repository, https://github.com/semantis-ai/semantis-python
+Keywords: llm,cache,semantic,openai,gpt
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: respx; extra == "dev"
+
+# Semantis Python SDK
+
+Drop-in replacement for the OpenAI Python client with automatic semantic caching.
+
+## Installation
+
+```bash
+pip install semantis
+```
+
+For automatic OpenAI fallback when Semantis is unreachable:
+
+```bash
+pip install semantis[openai]
+```
+
+## Quick Start
+
+```python
+from semantis import SemantisCache
+
+cache = SemantisCache(api_key="sc-myorg-xxxxxxxx")
+
+# OpenAI-compatible interface
+response = cache.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "What is machine learning?"}],
+)
+print(response.choices[0].message.content)
+print(f"Cache: {response.meta.hit} | Similarity: {response.meta.similarity}")
+```
+
+## Zero-Code Integration (Proxy Mode)
+
+Point your existing OpenAI client at Semantis:
+
+```python
+import openai
+
+client = openai.OpenAI(
+    base_url="https://api.semantis.ai/v1",
+    api_key="sc-myorg-xxxxxxxx",
+)
+
+# Existing code works unchanged - caching is transparent
+response = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "What is ML?"}],
+)
+```
+
+## Self-Hosted
+
+```python
+cache = SemantisCache(
+    api_key="sc-myorg-xxxxxxxx",
+    base_url="http://localhost:8000",
+)
+```
+
+## Features
+
+- **OpenAI-compatible**: Drop-in replacement, same interface
+- **Automatic retry**: Exponential backoff on 429/5xx errors
+- **Fallback**: If Semantis is unreachable, falls back to direct OpenAI (with `[openai]` extra)
+- **Cache metadata**: Every response includes `meta.hit`, `meta.similarity`, `meta.latency_ms`
+- **Context manager**: Use with `with` for automatic cleanup

semantis-0.1.0/semantis.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+MANIFEST.in
+README.md
+pyproject.toml
+semantis/__init__.py
+semantis/client.py
+semantis/models.py
+semantis.egg-info/PKG-INFO
+semantis.egg-info/SOURCES.txt
+semantis.egg-info/dependency_links.txt
+semantis.egg-info/requires.txt
+semantis.egg-info/top_level.txt

semantis-0.1.0/semantis.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

semantis-0.1.0/semantis.egg-info/requires.txt

@@ -0,0 +1,9 @@
+httpx>=0.24.0
+
+[dev]
+pytest
+pytest-asyncio
+respx
+
+[openai]
+openai>=1.0.0

semantis-0.1.0/semantis.egg-info/top_level.txt

@@ -0,0 +1 @@
+semantis

semantis-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+