ico-cache 1.0.0__py3-none-any.whl

ico_cache/__init__.py

@@ -0,0 +1,7 @@
+from .core.cache_engine import CacheEngine, CacheEngine as ICOCache
+from .core.config import ICOConfig
+from .loaders.auto_loader import ingest, AutoLoader
+
+__version__ = "0.1.0"
+
+__all__ = ["CacheEngine", "ICOCache", "ICOConfig", "ingest", "AutoLoader", "__version__"]

ico_cache/async_ingest.py

@@ -0,0 +1,207 @@
+import asyncio
+import logging
+import os
+import threading
+import time
+import uuid
+from typing import Dict, Optional
+from pydantic import BaseModel, Field
+
+from .loaders.auto_loader import AutoLoader
+from .core.cache_engine import CacheEngine
+from .core.metadata_guard import MetadataSchema
+
+logger = logging.getLogger("ico_cache.async_ingest")
+
+
+class IngestionJob(BaseModel):
+    job_id: str
+    tenant_id: str
+    file_path: str
+    file_size_bytes: int
+    status: str = "queued"  # queued, processing, completed, failed
+    is_async: bool = False
+    chunks_total: int = 0
+    chunks_processed: int = 0
+    created_at: float = Field(default_factory=time.time)
+    completed_at: Optional[float] = None
+    elapsed_s: float = 0.0
+    error: Optional[str] = None
+
+
+class IngestionJobManager:
+    """
+    Manages synchronous and asynchronous document ingestion.
+    Files exceeding async_threshold_bytes (default 1MB) are ingested
+    asynchronously in background tasks with queryable job status.
+    """
+
+    def __init__(
+        self,
+        async_threshold_bytes: int = 1 * 1024 * 1024,
+        job_ttl_seconds: int = 3600,
+        max_jobs: int = 10000,
+    ):
+        self.async_threshold_bytes = async_threshold_bytes
+        self.job_ttl_seconds = job_ttl_seconds
+        self.max_jobs = max_jobs
+        self.jobs: Dict[str, IngestionJob] = {}
+        self._lock = threading.Lock()
+
+    def _cleanup_expired_unlocked(self, now: Optional[float] = None) -> int:
+        """Evicts completed/failed jobs older than job_ttl_seconds, and enforces max_jobs cap."""
+        ts = now if now is not None else time.time()
+        to_delete = []
+
+        # 1. Evict by TTL
+        for jid, job in self.jobs.items():
+            if job.status in ["completed", "failed"] and job.completed_at:
+                if (ts - job.completed_at) > self.job_ttl_seconds:
+                    to_delete.append(jid)
+
+        for jid in to_delete:
+            del self.jobs[jid]
+
+        # 2. Evict oldest finished jobs if exceeding capacity cap
+        if len(self.jobs) > self.max_jobs:
+            finished = sorted(
+                [j for j in self.jobs.values() if j.status in ["completed", "failed"]],
+                key=lambda x: x.completed_at or 0.0,
+            )
+            excess = len(self.jobs) - self.max_jobs
+            for j in finished[:excess]:
+                if j.job_id in self.jobs:
+                    del self.jobs[j.job_id]
+                    to_delete.append(j.job_id)
+
+        return len(to_delete)
+
+    def cleanup_expired_jobs(self, now: Optional[float] = None) -> int:
+        """Public thread-safe cleanup method."""
+        with self._lock:
+            return self._cleanup_expired_unlocked(now=now)
+
+    def get_job(self, job_id: str) -> Optional[IngestionJob]:
+        with self._lock:
+            self._cleanup_expired_unlocked()
+            job = self.jobs.get(job_id)
+            if job and job.status == "processing":
+                job.elapsed_s = time.time() - job.created_at
+            return job
+
+    def list_jobs(self, tenant_id: Optional[str] = None) -> Dict[str, IngestionJob]:
+        with self._lock:
+            self._cleanup_expired_unlocked()
+            if tenant_id:
+                return {k: v for k, v in self.jobs.items() if v.tenant_id == tenant_id}
+            return dict(self.jobs)
+
+    def submit_ingest(
+        self,
+        file_path: str,
+        tenant_id: str,
+        cache_engine: CacheEngine,
+        schema: Optional[MetadataSchema] = None,
+        force_async: Optional[bool] = None,
+    ) -> IngestionJob:
+        if not os.path.exists(file_path):
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        file_size = os.path.getsize(file_path)
+        job_id = str(uuid.uuid4())
+        should_async = force_async if force_async is not None else (file_size >= self.async_threshold_bytes)
+
+        job = IngestionJob(
+            job_id=job_id,
+            tenant_id=tenant_id,
+            file_path=file_path,
+            file_size_bytes=file_size,
+            status="processing",
+            is_async=should_async,
+            created_at=time.time(),
+        )
+
+        with self._lock:
+            self.jobs[job_id] = job
+
+        if should_async:
+            # Dispatch background worker thread
+            worker = threading.Thread(
+                target=self._run_ingest,
+                args=(job_id, file_path, tenant_id, cache_engine, schema),
+                daemon=True,
+            )
+            worker.start()
+            return job
+        else:
+            # Run synchronously in an isolated thread to protect caller's event loop
+            worker = threading.Thread(
+                target=self._run_ingest,
+                args=(job_id, file_path, tenant_id, cache_engine, schema),
+                daemon=True,
+            )
+            worker.start()
+            worker.join()
+            with self._lock:
+                return self.jobs[job_id]
+
+    def _run_ingest(
+        self,
+        job_id: str,
+        file_path: str,
+        tenant_id: str,
+        cache_engine: CacheEngine,
+        schema: Optional[MetadataSchema] = None,
+    ):
+        start_t = time.time()
+        try:
+            loader = AutoLoader(schema=schema)
+            chunks = loader.load(file_path)
+
+            with self._lock:
+                job = self.jobs[job_id]
+                job.chunks_total = len(chunks)
+
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+
+            try:
+                for idx, chunk in enumerate(chunks):
+                    loader_kind = getattr(chunk, "loader_type", None) or (chunk.metadata.get("loader") if isinstance(chunk.metadata, dict) else "text")
+                    dummy_resp = {
+                        "content": chunk.text[:200],
+                        "source": chunk.source_file,
+                        "section": chunk.page_or_section,
+                        "loader_type": loader_kind,
+                        "extraction_method": chunk.metadata.get("extraction_method", "direct") if isinstance(chunk.metadata, dict) else "direct",
+                        "metadata": chunk.metadata if isinstance(chunk.metadata, dict) else {},
+                    }
+                    cache_engine.set_l1(chunk.text[:100], dummy_resp, meta=chunk.metadata, tenant_id=tenant_id)
+                    loop.run_until_complete(
+                        cache_engine.async_write_l2(
+                            chunk.text[:100], dummy_resp, meta=chunk.metadata, tenant_id=tenant_id
+                        )
+                    )
+                    with self._lock:
+                        job.chunks_processed = idx + 1
+            finally:
+                loop.close()
+
+            with self._lock:
+                job = self.jobs[job_id]
+                job.status = "completed"
+                job.completed_at = time.time()
+                job.elapsed_s = job.completed_at - start_t
+                logger.info(f"Ingestion job {job_id} completed: {job.chunks_processed} chunks in {job.elapsed_s:.2f}s")
+
+        except Exception as e:
+            with self._lock:
+                job = self.jobs[job_id]
+                job.status = "failed"
+                job.completed_at = time.time()
+                job.elapsed_s = job.completed_at - start_t
+                job.error = str(e)
+            logger.error(f"Ingestion job {job_id} failed: {e}", exc_info=True)
+
+
+job_manager = IngestionJobManager()

ico_cache/backends/base.py

@@ -0,0 +1,47 @@
+from abc import ABC, abstractmethod
+from typing import List, Any, Optional
+
+class BaseEmbedder(ABC):
+    @abstractmethod
+    def embed(self, text: str) -> List[float]:
+        pass
+
+class BaseVectorStore(ABC):
+    @abstractmethod
+    async def insert(self, collection: str, id: int, vector: Any, payload: dict):
+        pass
+
+    @abstractmethod
+    async def search(self, collection: str, vector: Any, query_filter: Any, limit: int, score_threshold: float, using: Optional[str] = None, **kwargs: Any) -> List[Any]:
+        pass
+
+    @abstractmethod
+    async def delete(self, collection: str, id: int):
+        pass
+
+    @abstractmethod
+    def collection_exists(self, collection: str) -> bool:
+        pass
+
+    @abstractmethod
+    def create_collection(self, collection: str, config: Any):
+        pass
+
+    def delete_collection(self, collection: str):
+        pass
+
+    async def delete_matching(self, collection: str, filter_dict: Optional[dict] = None) -> int:
+        return 0
+
+class BaseExactStore(ABC):
+    @abstractmethod
+    def get(self, key: str) -> Optional[bytes]:
+        pass
+
+    @abstractmethod
+    def set(self, key: str, value: bytes, ex: Optional[int] = None, nx: bool = False):
+        pass
+
+    def delete_prefix(self, prefix: str) -> int:
+        return 0
+

ico_cache/backends/embedding/fastembed_embedder.py

@@ -0,0 +1,10 @@
+from fastembed import TextEmbedding
+from typing import List
+from ..base import BaseEmbedder
+
+class FastEmbedder(BaseEmbedder):
+    def __init__(self, model_name: str = "BAAI/bge-small-en-v1.5"):
+        self.model = TextEmbedding(model_name=model_name)
+
+    def embed(self, text: str) -> List[float]:
+        return list(self.model.embed([text]))[0].tolist()

ico_cache/backends/exact/redis_store.py

@@ -0,0 +1,42 @@
+import redis
+from typing import Optional
+from ..base import BaseExactStore
+
+class RedisStore(BaseExactStore):
+    def __init__(self, host: str = "localhost", port: int = 6379, password: str = None):
+        self.r = redis.Redis(host=host, port=port, password=password)
+
+    @property
+    def client(self):
+        return self.r
+
+    def get(self, key: str) -> Optional[bytes]:
+        return self.r.get(key)
+
+    def set(self, key: str, value: bytes, ex: Optional[int] = None, nx: bool = False) -> bool:
+        # nx=True only writes when the key is absent (conditional write).
+        result = self.r.set(key, value, ex=ex, nx=nx)
+        return result is not None
+
+    def delete(self, key: str) -> bool:
+        return bool(self.r.delete(key))
+
+    def delete_prefix(self, prefix: str) -> int:
+        cursor = 0
+        deleted = 0
+        match_pattern = f"{prefix}*"
+        while True:
+            cursor, keys = self.r.scan(cursor=cursor, match=match_pattern, count=100)  # type: ignore[misc]
+            if keys:
+                deleted += self.r.delete(*keys)  # type: ignore[operator]
+            if cursor == 0:
+                break
+        return deleted
+
+    def xadd(self, stream: str, fields: dict) -> str:
+        res = self.r.xadd(stream, fields)
+        return res.decode() if isinstance(res, bytes) else str(res)
+
+    def xread(self, streams: dict, count: Optional[int] = None, block: Optional[int] = None):
+        return self.r.xread(streams, count=count, block=block)
+

ico_cache/backends/exact/sqlite_store.py

@@ -0,0 +1,43 @@
+import sqlite3
+from typing import Optional
+from ..base import BaseExactStore
+
+class SQLiteStore(BaseExactStore):
+    def __init__(self, db_path: str = "cache.db"):
+        self.db_path = db_path
+        self._init_db()
+
+    def _init_db(self):
+        with sqlite3.connect(self.db_path) as conn:
+            conn.execute('''CREATE TABLE IF NOT EXISTS cache
+                            (key TEXT PRIMARY KEY, value BLOB)''')
+
+    def get(self, key: str) -> Optional[bytes]:
+        with sqlite3.connect(self.db_path) as conn:
+            cursor = conn.cursor()
+            cursor.execute("SELECT value FROM cache WHERE key=?", (key,))
+            row = cursor.fetchone()
+            if row:
+                return row[0]
+            return None
+
+    def set(self, key: str, value: bytes, ex: Optional[int] = None, nx: bool = False) -> bool:
+        # Note: SQLite store doesn't support TTL out of the box in this simple
+        # implementation. nx=True performs a conditional (insert-if-absent) write.
+        verb = "INSERT OR IGNORE" if nx else "INSERT OR REPLACE"
+        with sqlite3.connect(self.db_path) as conn:
+            cur = conn.execute(f"{verb} INTO cache (key, value) VALUES (?, ?)", (key, value))
+            if nx:
+                return cur.rowcount > 0
+            return True
+
+    def delete(self, key: str) -> bool:
+        with sqlite3.connect(self.db_path) as conn:
+            cur = conn.execute("DELETE FROM cache WHERE key = ?", (key,))
+            return cur.rowcount > 0
+
+    def delete_prefix(self, prefix: str) -> int:
+        with sqlite3.connect(self.db_path) as conn:
+            cur = conn.execute("DELETE FROM cache WHERE key LIKE ?", (f"{prefix}%",))
+            return cur.rowcount
+

ico_cache/backends/vector/lancedb_store.py

@@ -0,0 +1,160 @@
+import json
+import re
+import lancedb
+from typing import Any, List, Optional
+from ..base import BaseVectorStore
+
+# Metadata keys/filter field names are identifiers, never expressions.
+_IDENT_RE = re.compile(r"^[A-Za-z0-9_.-]+$")
+
+
+def _sql_str(value: Any) -> str:
+    """Render a value as a single-quoted SQL string literal, escaping quotes."""
+    return "'" + str(value).replace("'", "''") + "'"
+
+
+class LanceDBStore(BaseVectorStore):
+    def __init__(self, uri: str = "./lancedb"):
+        self.db = lancedb.connect(uri)
+
+    def _table_names(self) -> List[str]:
+        if hasattr(self.db, "list_tables"):
+            res = self.db.list_tables()
+            if hasattr(res, "tables"):
+                return list(res.tables)
+        try:
+            return list(self.db.table_names())
+        except Exception:
+            return []
+
+    async def insert(self, collection: str, id: int, vector: Any, payload: dict):
+        if isinstance(vector, dict):
+            row = {"id": id}
+            for v_k, v_v in vector.items():
+                row[f"vector_{v_k}"] = v_v
+            row["vector"] = vector.get("query") or list(vector.values())[0]
+        else:
+            row = {"id": id, "vector": vector}
+
+        for k, v in payload.items():
+            # Structured values are stored as JSON text (LanceDB rows are flat),
+            # and decoded again on read. Never rely on Python repr().
+            if isinstance(v, (dict, list)):
+                row[k] = json.dumps(v, default=str)
+            else:
+                row[k] = v
+
+        if collection not in self._table_names():
+            self.db.create_table(collection, data=[row])
+        else:
+            table = self.db.open_table(collection)
+            table.add([row])
+
+    async def search(
+        self,
+        collection: str,
+        vector: Any,
+        query_filter: Any,
+        limit: int,
+        score_threshold: float,
+        using: Optional[str] = None,
+        **kwargs: Any,
+    ) -> List[Any]:
+        if collection not in self._table_names():
+            return []
+
+        table = self.db.open_table(collection)
+        schema_names = table.schema.names if hasattr(table, "schema") else []
+        vec_col = f"vector_{using}" if using and f"vector_{using}" in schema_names else "vector"
+
+        try:
+            res = table.search(vector, vector_column_name=vec_col).metric("cosine").limit(limit).to_list()
+        except Exception:
+            try:
+                res = table.search(vector).metric("cosine").limit(limit).to_list()
+            except Exception:
+                res = table.search(vector).limit(limit).to_list()
+
+        filter_tenant_id = kwargs.get("tenant_id")
+        if not filter_tenant_id and query_filter is not None and hasattr(query_filter, "must"):
+            for cond in (query_filter.must or []):
+                if getattr(cond, "key", None) == "tenant_id" and hasattr(cond, "match") and hasattr(cond.match, "value"):
+                    filter_tenant_id = cond.match.value
+
+        class Hit:
+            def __init__(self, payload, id):
+                self.payload = payload
+                self.id = id
+
+        hits = []
+        for r in res:
+            hid = r.pop("id", None)
+            r.pop("vector", None)
+            r.pop("vector_query", None)
+            r.pop("vector_context", None)
+            dist = r.pop("_distance", 0.0)
+            similarity = 1.0 - dist
+            if score_threshold > 0 and similarity < score_threshold:
+                continue
+
+            # Reconstruct dict payload
+            payload_dict = {}
+            for k, v in r.items():
+                if k in ("meta", "answer") and isinstance(v, str):
+                    try:
+                        payload_dict[k] = json.loads(v)
+                    except Exception:
+                        payload_dict[k] = v
+                else:
+                    payload_dict[k] = v
+
+            if filter_tenant_id and payload_dict.get("tenant_id") != filter_tenant_id:
+                continue
+
+            hits.append(Hit(payload=payload_dict, id=hid))
+        return hits
+
+    async def delete(self, collection: str, id: int):
+        if collection in self._table_names():
+            table = self.db.open_table(collection)
+            table.delete(f"id = {id}")
+
+    def collection_exists(self, collection: str) -> bool:
+        return collection in self._table_names()
+
+    def create_collection(self, collection: str, config: Any):
+        pass
+
+    def delete_collection(self, collection: str):
+        if collection in self._table_names():
+            self.db.drop_table(collection)
+
+    async def delete_matching(self, collection: str, filter_dict: Optional[dict] = None) -> int:
+        if collection not in self._table_names():
+            return 0
+        if not filter_dict:
+            self.db.drop_table(collection)
+            return -1
+        table = self.db.open_table(collection)
+        clauses = []
+        for k, v in filter_dict.items():
+            # Reject keys that could break out of the identifier/JSON context.
+            if not isinstance(k, str) or not _IDENT_RE.match(k):
+                continue
+            if not isinstance(v, (str, int, float, bool)):
+                continue
+            if k == "tenant_id":
+                clauses.append(f"tenant_id = {_sql_str(v)}")
+            else:
+                # LanceDB stores meta as a JSON string; match the escaped literal.
+                pattern = '%"' + str(k) + '": "' + str(v) + '"%'
+                clauses.append("meta LIKE " + _sql_str(pattern))
+        if not clauses:
+            return 0
+        where_clause = " AND ".join(clauses)
+        try:
+            table.delete(where_clause)
+            return len(clauses)
+        except Exception:
+            return 0
+

ico_cache/backends/vector/qdrant_store.py

@@ -0,0 +1,90 @@
+import asyncio
+import threading
+from typing import List, Any, Optional
+from qdrant_client import QdrantClient, AsyncQdrantClient
+from qdrant_client.models import VectorParams, Distance
+from ..base import BaseVectorStore
+
+class QdrantStore(BaseVectorStore):
+    def __init__(self, host: str = "localhost", port: int = 6333):
+        self.host = host
+        self.port = port
+        self.qc = QdrantClient(host, port=port, check_compatibility=False)
+        self._local = threading.local()
+
+    @property
+    def aqc(self) -> AsyncQdrantClient:
+        if not hasattr(self._local, "client"):
+            self._local.client = AsyncQdrantClient(self.host, port=self.port, check_compatibility=False)
+        return self._local.client
+
+    async def insert(self, collection: str, id: int, vector: Any, payload: dict):
+        await self.aqc.upsert(
+            collection_name=collection,
+            points=[{
+                "id": id,
+                "vector": vector,
+                "payload": payload
+            }]
+        )
+
+    async def search(self, collection: str, vector: Any, query_filter: Any, limit: int, score_threshold: float, using: Optional[str] = None, **kwargs: Any) -> List[Any]:
+        # Use the async client so the event loop is never blocked by network I/O.
+        if using:
+            res = await self.aqc.query_points(
+                collection_name=collection,
+                query=vector,
+                using=using,
+                query_filter=query_filter,
+                limit=limit,
+                score_threshold=score_threshold,
+            )
+        else:
+            res = await self.aqc.query_points(
+                collection_name=collection,
+                query=vector,
+                query_filter=query_filter,
+                limit=limit,
+                score_threshold=score_threshold,
+            )
+        return res.points
+
+    async def delete(self, collection: str, id: int):
+        await self.aqc.delete(collection_name=collection, points_selector=[id])
+
+    def collection_exists(self, collection: str) -> bool:
+        return self.qc.collection_exists(collection)
+
+    def create_collection(self, collection: str, config: Any = None):
+        if config is None:
+            config = VectorParams(size=384, distance=Distance.COSINE)
+        elif isinstance(config, dict):
+            # parse custom dict to VectorParams
+            new_config = {}
+            for k, v in config.items():
+                if isinstance(v, dict):
+                    new_config[k] = VectorParams(size=v["size"], distance=Distance.COSINE)
+                else:
+                    new_config[k] = v
+            config = new_config
+        self.qc.create_collection(collection, vectors_config=config)
+
+    def delete_collection(self, collection: str):
+        if self.qc.collection_exists(collection):
+            self.qc.delete_collection(collection)
+
+    async def delete_matching(self, collection: str, filter_dict: Optional[dict] = None) -> int:
+        if not await asyncio.to_thread(self.qc.collection_exists, collection):
+            return 0
+        from qdrant_client.http import models
+        if not filter_dict:
+            await asyncio.to_thread(self.qc.delete_collection, collection)
+            return -1
+        conditions = []
+        for k, v in filter_dict.items():
+            field_key = f"meta.{k}" if (not k.startswith("meta.") and k != "tenant_id" and k != "doc_id") else k
+            conditions.append(models.FieldCondition(key=field_key, match=models.MatchValue(value=v)))
+        q_filter = models.Filter(must=conditions)
+        await self.aqc.delete(collection_name=collection, points_selector=models.FilterSelector(filter=q_filter))
+        return len(conditions)
+

ico_cache/client.py

@@ -0,0 +1,20 @@
+import requests
+
+class IcoCache:
+    def __init__(self, base_url="http://localhost:8000", semantic_threshold=0.92):
+        self.base_url = base_url
+        self.semantic_threshold = semantic_threshold
+
+    def resolve(self, query: str, context: str, callback):
+        resp = requests.post(f"{self.base_url}/resolve", json={"query": query, "context": context}).json()
+        if resp.get("source") != "MISS":
+            return resp.get("response")
+
+        # MISS
+        generated = callback()
+
+        requests.post(f"{self.base_url}/ingest", json={"query": query, "context": context, "response": generated})
+        return generated
+
+def ico_cache(base_url="http://localhost:8000", semantic_threshold=0.92):
+    return IcoCache(base_url, semantic_threshold)