echocache 1.0.0__tar.gz

echocache-1.0.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: echocache
+Version: 1.0.0
+Summary: Official Python SDK for EchoCache — Dynamic Semantic Cache for LLM APIs
+Home-page: https://echocache.dev
+Author: EchoCache Team
+Author-email: echocache322@gmail.com
+Project-URL: Source, https://github.com/echo-cache/echocache-python
+Project-URL: Tracker, https://github.com/echo-cache/echocache-python/issues
+Classifier: Development Status :: 5 - Production/Stable
+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 :: Python Modules
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# echocache
+
+Official Python SDK for [EchoCache](https://echocache.dev) — The Enterprise Dynamic Semantic Cache for LLM APIs.
+
+Reduce LLM API costs by **up to 80%** and accelerate response times from **~1.8s down to <25ms** using vector similarity lookups.
+
+## Installation
+
+```bash
+pip install echocache
+```
+
+## Quickstart
+
+```python
+import os
+from echocache import EchoCache
+
+# 1. Initialize EchoCache client
+echo = EchoCache(os.environ["ECHOCACHE_API_KEY"])
+
+# 2. Wrap your LLM generator call
+def generate_llm_response(prompt: str) -> str:
+    # Example using OpenAI Python SDK
+    response = openai.chat.completions.create(
+        model="gpt-5.6-sol",
+        messages=[{"role": "user", "content": prompt}]
+    )
+    return response.choices[0].message.content
+
+# 3. Intercept request (returns cached answer on HIT, or calls generator on MISS)
+prompt = "What is the capital of France?"
+answer = echo.ask(prompt, generate_llm_response)
+
+print(answer)
+```
+
+## Configuration Options
+
+```python
+echo = EchoCache(
+    "ec_prod_your_api_key_here",
+    {"baseUrl": "https://echocache.dev"} # Optional: Custom self-hosted EchoCache endpoint
+)
+```
+
+## License
+
+MIT © EchoCache Team

echocache-1.0.0/README.md

@@ -0,0 +1,49 @@
+# echocache
+
+Official Python SDK for [EchoCache](https://echocache.dev) — The Enterprise Dynamic Semantic Cache for LLM APIs.
+
+Reduce LLM API costs by **up to 80%** and accelerate response times from **~1.8s down to <25ms** using vector similarity lookups.
+
+## Installation
+
+```bash
+pip install echocache
+```
+
+## Quickstart
+
+```python
+import os
+from echocache import EchoCache
+
+# 1. Initialize EchoCache client
+echo = EchoCache(os.environ["ECHOCACHE_API_KEY"])
+
+# 2. Wrap your LLM generator call
+def generate_llm_response(prompt: str) -> str:
+    # Example using OpenAI Python SDK
+    response = openai.chat.completions.create(
+        model="gpt-5.6-sol",
+        messages=[{"role": "user", "content": prompt}]
+    )
+    return response.choices[0].message.content
+
+# 3. Intercept request (returns cached answer on HIT, or calls generator on MISS)
+prompt = "What is the capital of France?"
+answer = echo.ask(prompt, generate_llm_response)
+
+print(answer)
+```
+
+## Configuration Options
+
+```python
+echo = EchoCache(
+    "ec_prod_your_api_key_here",
+    {"baseUrl": "https://echocache.dev"} # Optional: Custom self-hosted EchoCache endpoint
+)
+```
+
+## License
+
+MIT © EchoCache Team

echocache-1.0.0/echocache/__init__.py

@@ -0,0 +1,3 @@
+from .client import EchoCache
+
+__all__ = ["EchoCache"]

echocache-1.0.0/echocache/cache.py

@@ -0,0 +1,49 @@
+import sys
+import requests
+
+def check_cache(prompt: str, api_key: str, base_url: str, project_id: str = "proj_default") -> dict:
+    """
+    Queries the EchoCache backend for a matching cached answer.
+    """
+    response = requests.post(
+        f"{base_url}/api/cache",
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {api_key}",
+            "x-project-id": project_id
+        },
+        json={"prompt": prompt, "project_id": project_id},
+        timeout=5
+    )
+    if response.status_code != 200:
+        raise RuntimeError(f"Cache read failed (HTTP {response.status_code})")
+    return response.json()
+
+def save_to_cache(prompt: str, llm_response: str, latency_ms: int, api_key: str, base_url: str, project_id: str = "proj_default") -> None:
+    """
+    Sends the generated LLM response to EchoCache to be saved for future hits.
+    """
+    try:
+        # Rough token estimation: ~4 characters per token
+        tokens_saved = (len(prompt) // 4) + (len(llm_response) // 4)
+        response = requests.post(
+            f"{base_url}/api/cache/save",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {api_key}",
+                "x-project-id": project_id
+            },
+            json={
+                "prompt": prompt,
+                "llm_response": llm_response,
+                "status": "miss",
+                "latency_ms": latency_ms,
+                "tokens_saved": tokens_saved,
+                "project_id": project_id
+            },
+            timeout=10
+        )
+        if response.status_code != 200:
+            print(f"[EchoCache] Background sync returned HTTP {response.status_code}", file=sys.stderr)
+    except Exception as e:
+        print(f"[EchoCache] Background sync failed: {e}", file=sys.stderr)

echocache-1.0.0/echocache/client.py

@@ -0,0 +1,109 @@
+import os
+import time
+import threading
+from typing import Callable, Optional, Union
+
+from .connection import parse_connection_string
+from .validate import validate_key
+from .cache import check_cache, save_to_cache
+
+class EchoCache:
+    def __init__(self, target: Optional[Union[str, dict]] = None, options: Optional[dict] = None):
+        api_key = None
+        base_url = None
+        project_id = "proj_default"
+
+        if isinstance(target, str):
+            if target.startswith("echocache://") or target.startswith("echocaches://") or "@" in target:
+                parsed = parse_connection_string(target)
+                api_key = parsed["apiKey"]
+                base_url = parsed["baseUrl"]
+                project_id = parsed["projectId"]
+            elif target.startswith("ec_prod_"):
+                api_key = target
+                options = options or {}
+                base_url = options.get("baseUrl") or os.getenv("ECHOCACHE_BASE_URL")
+                project_id = options.get("projectId") or "proj_default"
+                if not base_url:
+                    raise ValueError(
+                        "Missing EchoCache baseUrl. Please pass a full connection string 'echocache://<api_key>@<host>/<project_id>' or set os.environ['ECHOCACHE_CONNECTION_STRING']."
+                    )
+            else:
+                raise ValueError(
+                    f"Invalid EchoCache connection argument: '{target}'. Expected connection string format: 'echocache://ec_prod_xxx@host/proj_default'"
+                )
+        elif isinstance(target, dict):
+            api_key = target.get("apiKey")
+            base_url = target.get("baseUrl") or os.getenv("ECHOCACHE_BASE_URL")
+            project_id = target.get("projectId") or "proj_default"
+        else:
+            env_conn = os.getenv("ECHOCACHE_CONNECTION_STRING")
+            if env_conn:
+                parsed = parse_connection_string(env_conn)
+                api_key = parsed["apiKey"]
+                base_url = parsed["baseUrl"]
+                project_id = parsed["projectId"]
+            else:
+                raise ValueError(
+                    "Missing EchoCache connection string. Please pass an explicit connection string 'echocache://<api_key>@<host>/<project_id>' or set os.environ['ECHOCACHE_CONNECTION_STRING']."
+                )
+
+        if not api_key or not api_key.startswith("ec_prod_"):
+            raise ValueError("Invalid EchoCache API Key. Key must start with 'ec_prod_'")
+
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.project_id = project_id
+        self.is_validated = False
+        
+        # Validation runs in a background thread to prevent constructor blocking
+        self._init_thread = threading.Thread(target=self._init, daemon=True)
+        self._init_thread.start()
+
+    def _init(self):
+        self.is_validated = validate_key(self.api_key, self.base_url)
+        if self.is_validated:
+            print("[EchoCache] Successfully connected to Semantic Cache.")
+
+    def ask(self, prompt: str, fallback_llm_call: Callable[[str], str]) -> str:
+        # Wait for the handshake thread to finish before proceeding queries
+        self._init_thread.join()
+
+        if not self.is_validated:
+            # Bypass cache checks if validation failed
+            return fallback_llm_call(prompt)
+
+        start_time = time.time()
+
+        try:
+            # 1. Check cache
+            cache_data = check_cache(prompt, self.api_key, self.base_url, self.project_id)
+
+            # 2. Cache HIT
+            if cache_data.get("cache") == "HIT":
+                latency_ms = int((time.time() - start_time) * 1000)
+                score = cache_data.get("score", "Exact")
+                print(f"[EchoCache] HIT! ({latency_ms}ms) - Score: {score}")
+                return cache_data.get("response")
+
+            # 3. Cache MISS
+            print("[EchoCache] MISS. Calling LLM...")
+            # Execute the dev's actual LLM generation
+            llm_start = time.time()
+            llm_response = fallback_llm_call(prompt)
+            miss_latency_ms = int((time.time() - llm_start) * 1000)
+
+            # 4. Background Sync (runs in background daemon thread)
+            sync_thread = threading.Thread(
+                target=save_to_cache,
+                args=(prompt, llm_response, miss_latency_ms, self.api_key, self.base_url, self.project_id),
+                daemon=True
+            )
+            sync_thread.start()
+
+            return llm_response
+
+        except Exception as e:
+            # Fallback to LLM on caching server failure
+            print(f"[EchoCache] Fallback triggered. Reason: {e}")
+            return fallback_llm_call(prompt)

echocache-1.0.0/echocache/connection.py

@@ -0,0 +1,40 @@
+import re
+from typing import Dict
+
+def parse_connection_string(connection_string: str) -> Dict[str, str]:
+    """
+    Parses an EchoCache proprietary connection string.
+    Format: echocache://<api_key>@<host>/<project_id>
+    Example: echocache://ec_prod_d880430bbc14e293b8716f472c17e867d90f995f29dcc50e@localhost:3000/proj_default
+    """
+    if not connection_string or not isinstance(connection_string, str):
+        raise ValueError(
+            "Missing EchoCache connection string. You must explicitly provide a connection string "
+            "(e.g. 'echocache://ec_prod_xxx@localhost:3000/proj_default') or set os.environ['ECHOCACHE_CONNECTION_STRING']."
+        )
+
+    s = connection_string.strip()
+
+    pattern = r"^(?:echocaches?|https?):\/\/(ec_prod_[^@]+)@([^/]+)(?:\/(.+))?$"
+    match = re.match(pattern, s)
+
+    if not match:
+        raise ValueError(
+            f"Invalid EchoCache connection string format: \"{connection_string}\". "
+            f"Expected format: echocache://<api_key>@<host>/<project_id> "
+            f"(e.g. 'echocache://ec_prod_d880430b...@localhost:3000/proj_default')"
+        )
+
+    api_key, host, raw_project_id = match.groups()
+    project_id = raw_project_id.strip("/") if raw_project_id else "proj_default"
+
+    is_local = host.startswith("localhost") or host.startswith("127.0.0.1") or host.startswith("0.0.0.0")
+    protocol = "http" if s.startswith("http://") or is_local else "https"
+    base_url = f"{protocol}://{host}"
+
+    return {
+        "apiKey": api_key,
+        "baseUrl": base_url,
+        "projectId": project_id,
+        "connectionString": f"echocache://{api_key}@{host}/{project_id}",
+    }

echocache-1.0.0/echocache/validate.py

@@ -0,0 +1,21 @@
+import sys
+import requests
+
+def validate_key(api_key: str, base_url: str) -> bool:
+    """
+    Validates the EchoCache API key against the server validate route.
+    Returns True if valid, False otherwise.
+    """
+    try:
+        response = requests.post(
+            f"{base_url}/api/validate",
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=5
+        )
+        if response.status_code != 200:
+            print("❌ [EchoCache] Invalid or inactive API Key.", file=sys.stderr)
+            return False
+        return True
+    except Exception as e:
+        print(f"⚠️ [EchoCache] Could not reach validation server: {e}", file=sys.stderr)
+        return False

echocache-1.0.0/echocache.egg-info/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: echocache
+Version: 1.0.0
+Summary: Official Python SDK for EchoCache — Dynamic Semantic Cache for LLM APIs
+Home-page: https://echocache.dev
+Author: EchoCache Team
+Author-email: echocache322@gmail.com
+Project-URL: Source, https://github.com/echo-cache/echocache-python
+Project-URL: Tracker, https://github.com/echo-cache/echocache-python/issues
+Classifier: Development Status :: 5 - Production/Stable
+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 :: Python Modules
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# echocache
+
+Official Python SDK for [EchoCache](https://echocache.dev) — The Enterprise Dynamic Semantic Cache for LLM APIs.
+
+Reduce LLM API costs by **up to 80%** and accelerate response times from **~1.8s down to <25ms** using vector similarity lookups.
+
+## Installation
+
+```bash
+pip install echocache
+```
+
+## Quickstart
+
+```python
+import os
+from echocache import EchoCache
+
+# 1. Initialize EchoCache client
+echo = EchoCache(os.environ["ECHOCACHE_API_KEY"])
+
+# 2. Wrap your LLM generator call
+def generate_llm_response(prompt: str) -> str:
+    # Example using OpenAI Python SDK
+    response = openai.chat.completions.create(
+        model="gpt-5.6-sol",
+        messages=[{"role": "user", "content": prompt}]
+    )
+    return response.choices[0].message.content
+
+# 3. Intercept request (returns cached answer on HIT, or calls generator on MISS)
+prompt = "What is the capital of France?"
+answer = echo.ask(prompt, generate_llm_response)
+
+print(answer)
+```
+
+## Configuration Options
+
+```python
+echo = EchoCache(
+    "ec_prod_your_api_key_here",
+    {"baseUrl": "https://echocache.dev"} # Optional: Custom self-hosted EchoCache endpoint
+)
+```
+
+## License
+
+MIT © EchoCache Team

echocache-1.0.0/echocache.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+setup.py
+echocache/__init__.py
+echocache/cache.py
+echocache/client.py
+echocache/connection.py
+echocache/validate.py
+echocache.egg-info/PKG-INFO
+echocache.egg-info/SOURCES.txt
+echocache.egg-info/dependency_links.txt
+echocache.egg-info/requires.txt
+echocache.egg-info/top_level.txt

echocache-1.0.0/echocache.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

echocache-1.0.0/echocache.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.25.0

echocache-1.0.0/echocache.egg-info/top_level.txt

@@ -0,0 +1 @@
+echocache

echocache-1.0.0/setup.cfg

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

echocache-1.0.0/setup.py

@@ -0,0 +1,38 @@
+import os
+from setuptools import setup, find_packages
+
+this_directory = os.path.abspath(os.path.dirname(__file__))
+with open(os.path.join(this_directory, "README.md"), encoding="utf-8") as f:
+    long_description = f.read()
+
+setup(
+    name="echocache",
+    version="1.0.0",
+    description="Official Python SDK for EchoCache — Dynamic Semantic Cache for LLM APIs",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    author="EchoCache Team",
+    author_email="echocache322@gmail.com",
+    url="https://echocache.dev",
+    project_urls={
+        "Source": "https://github.com/echo-cache/echocache-python",
+        "Tracker": "https://github.com/echo-cache/echocache-python/issues",
+    },
+    packages=find_packages(),
+    install_requires=[
+        "requests>=2.25.0",
+    ],
+    python_requires=">=3.7",
+    classifiers=[
+        "Development Status :: 5 - Production/Stable",
+        "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 :: Python Modules",
+    ],
+)