remote-embedding 0.1.0__tar.gz

remote_embedding-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Meshkat Shariat Bagheri
+
+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.

remote_embedding-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: remote-embedding
+Version: 0.1.0
+Summary: A PyPI-ready FastAPI embedding service and LangChain-compatible remote client.
+Author: Meshkat Shariat Bagheri
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MeshkatShB/remote-embedding
+Project-URL: Issues, https://github.com/MeshkatShB/remote-embedding/issues
+Keywords: embeddings,fastapi,langchain,huggingface,api
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.115
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: langchain-huggingface>=0.1.2
+Requires-Dist: pydantic>=2.7
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: requests>=2.32
+Requires-Dist: uvicorn>=0.30
+Dynamic: license-file
+
+# remote-embedding
+
+`remote-embedding` packages two things together:
+
+- A FastAPI server that exposes a `/embed` API backed by local Hugging Face models.
+- A LangChain-compatible `RemoteEmbeddings` client that calls that server remotely.
+
+## Install
+
+```bash
+pip install remote-embedding
+```
+
+## Package Layout
+
+The import package is `remote_embedding`.
+
+```python
+from remote_embedding import RemoteEmbeddings
+```
+
+## Run The Server
+
+Set the environment variables your model needs.
+
+PowerShell:
+
+```powershell
+$env:EMBEDDING_MODEL_NAME="BAAI/bge-base-en-v1.5"
+$env:EMBEDDING_DIR="C:\\path\\to\\model-cache"
+$env:DEVICE="cpu"
+```
+
+Bash:
+
+```bash
+export EMBEDDING_MODEL_NAME=BAAI/bge-base-en-v1.5
+export EMBEDDING_DIR=/path/to/model-cache
+export DEVICE=cpu
+```
+
+Start the API:
+
+```bash
+remote-embedding-server
+```
+
+Or:
+
+```bash
+python -m remote_embedding
+```
+
+Defaults:
+
+- `HOST=0.0.0.0`
+- `PORT=5055`
+
+## Use The Client
+
+```python
+from remote_embedding import RemoteEmbeddings
+
+embeddings = RemoteEmbeddings(
+    base_url="http://127.0.0.1:5055",
+    model_name="BAAI/bge-base-en-v1.5",
+)
+
+docs = embeddings.embed_documents(["hello world", "remote embeddings"])
+query = embeddings.embed_query("search text")
+```
+
+## Build For PyPI
+
+Build distributions locally:
+
+```bash
+python -m pip install --upgrade build
+python -m build
+```
+
+This creates:
+
+- `dist/*.tar.gz`
+- `dist/*.whl`
+
+Upload with Twine:
+
+```bash
+python -m pip install --upgrade twine
+python -m twine upload dist/*
+```

remote_embedding-0.1.0/README.md

@@ -0,0 +1,92 @@
+# remote-embedding
+
+`remote-embedding` packages two things together:
+
+- A FastAPI server that exposes a `/embed` API backed by local Hugging Face models.
+- A LangChain-compatible `RemoteEmbeddings` client that calls that server remotely.
+
+## Install
+
+```bash
+pip install remote-embedding
+```
+
+## Package Layout
+
+The import package is `remote_embedding`.
+
+```python
+from remote_embedding import RemoteEmbeddings
+```
+
+## Run The Server
+
+Set the environment variables your model needs.
+
+PowerShell:
+
+```powershell
+$env:EMBEDDING_MODEL_NAME="BAAI/bge-base-en-v1.5"
+$env:EMBEDDING_DIR="C:\\path\\to\\model-cache"
+$env:DEVICE="cpu"
+```
+
+Bash:
+
+```bash
+export EMBEDDING_MODEL_NAME=BAAI/bge-base-en-v1.5
+export EMBEDDING_DIR=/path/to/model-cache
+export DEVICE=cpu
+```
+
+Start the API:
+
+```bash
+remote-embedding-server
+```
+
+Or:
+
+```bash
+python -m remote_embedding
+```
+
+Defaults:
+
+- `HOST=0.0.0.0`
+- `PORT=5055`
+
+## Use The Client
+
+```python
+from remote_embedding import RemoteEmbeddings
+
+embeddings = RemoteEmbeddings(
+    base_url="http://127.0.0.1:5055",
+    model_name="BAAI/bge-base-en-v1.5",
+)
+
+docs = embeddings.embed_documents(["hello world", "remote embeddings"])
+query = embeddings.embed_query("search text")
+```
+
+## Build For PyPI
+
+Build distributions locally:
+
+```bash
+python -m pip install --upgrade build
+python -m build
+```
+
+This creates:
+
+- `dist/*.tar.gz`
+- `dist/*.whl`
+
+Upload with Twine:
+
+```bash
+python -m pip install --upgrade twine
+python -m twine upload dist/*
+```

remote_embedding-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "remote-embedding"
+version = "0.1.0"
+description = "A PyPI-ready FastAPI embedding service and LangChain-compatible remote client."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Meshkat Shariat Bagheri" }
+]
+keywords = ["embeddings", "fastapi", "langchain", "huggingface", "api"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Framework :: FastAPI",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "fastapi>=0.115",
+  "langchain-core>=0.3",
+  "langchain-huggingface>=0.1.2",
+  "pydantic>=2.7",
+  "python-dotenv>=1.0",
+  "requests>=2.32",
+  "uvicorn>=0.30",
+]
+
+[project.urls]
+Homepage = "https://github.com/MeshkatShB/remote-embedding"
+Issues = "https://github.com/MeshkatShB/remote-embedding/issues"
+
+[project.scripts]
+remote-embedding-server = "remote_embedding.app:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

remote_embedding-0.1.0/setup.cfg

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

remote_embedding-0.1.0/src/remote_embedding/__init__.py

@@ -0,0 +1,6 @@
+"""Public package exports for remote-embedding."""
+
+from .remote import RemoteEmbeddings
+
+__all__ = ["RemoteEmbeddings"]
+__version__ = "0.1.0"

remote_embedding-0.1.0/src/remote_embedding/__main__.py

@@ -0,0 +1,7 @@
+"""Module entry point for `python -m remote_embedding`."""
+
+from .app import main
+
+
+if __name__ == "__main__":
+    main()

remote_embedding-0.1.0/src/remote_embedding/app.py

@@ -0,0 +1,158 @@
+"""FastAPI application serving remote embedding inference."""
+
+import asyncio
+import os
+from contextlib import asynccontextmanager
+from typing import Literal, Optional, Union
+
+import uvicorn
+from dotenv import load_dotenv
+from fastapi import FastAPI, HTTPException
+from langchain_huggingface import HuggingFaceEmbeddings
+from pydantic import BaseModel, Field
+
+load_dotenv()
+
+DEFAULT_HOST = os.getenv("HOST", "0.0.0.0")
+DEFAULT_PORT = int(os.getenv("PORT", "5055"))
+EMBEDDING_MODEL_NAME = os.getenv("EMBEDDING_MODEL_NAME")
+EMBEDDING_DIR = os.getenv("EMBEDDING_DIR")
+DEVICE = os.getenv("DEVICE")
+
+
+class EmbeddingRequest(BaseModel):
+    input: Union[str, list[str]] = Field(..., description="String or list of strings")
+    mode: Literal["documents", "query"] = "documents"
+    model_name: Optional[str] = None
+    instruction: Optional[str] = None
+
+
+class EmbeddingResponse(BaseModel):
+    model: str
+    dimensions: int
+    count: int
+    data: list[list[float]]
+
+
+class HealthResponse(BaseModel):
+    status: str
+    model: str
+    device: Optional[str]
+
+
+class EmbeddingService:
+    def __init__(self) -> None:
+        self.embed_models: dict[str, HuggingFaceEmbeddings] = {}
+        self.lock = asyncio.Lock()
+
+    def _resolve_model_name(self, model_name: Optional[str] = None) -> str:
+        resolved_model_name = (model_name or EMBEDDING_MODEL_NAME or "").strip()
+        if not resolved_model_name:
+            raise RuntimeError(
+                "No embedding model specified. Set EMBEDDING_MODEL_NAME or pass model_name in the request."
+            )
+        return resolved_model_name
+
+    def load(self, model_name: Optional[str] = None) -> HuggingFaceEmbeddings:
+        resolved_model_name = self._resolve_model_name(model_name)
+        if resolved_model_name in self.embed_models:
+            return self.embed_models[resolved_model_name]
+
+        embed_model = HuggingFaceEmbeddings(
+            model_name=resolved_model_name,
+            model_kwargs={
+                "device": DEVICE,
+                "local_files_only": True,
+                "trust_remote_code": True,
+            },
+            cache_folder=EMBEDDING_DIR,
+        )
+        self.embed_models[resolved_model_name] = embed_model
+        return embed_model
+
+    async def embed_documents(
+        self,
+        texts: list[str],
+        model_name: Optional[str] = None,
+    ) -> list[list[float]]:
+        embed_model = self.load(model_name)
+
+        # Serialize GPU access to avoid VRAM spikes from concurrent requests.
+        async with self.lock:
+            return await asyncio.to_thread(embed_model.embed_documents, texts)
+
+    async def embed_query(self, text: str, model_name: Optional[str] = None) -> list[float]:
+        embed_model = self.load(model_name)
+
+        async with self.lock:
+            return await asyncio.to_thread(embed_model.embed_query, text)
+
+
+svc = EmbeddingService()
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI):
+    if EMBEDDING_MODEL_NAME:
+        svc.load()
+    yield
+
+
+app = FastAPI(title="Shared Embedding Service", version="0.1.0", lifespan=lifespan)
+
+
+@app.get("/health", response_model=HealthResponse)
+async def health() -> HealthResponse:
+    configured_model_name = (EMBEDDING_MODEL_NAME or "").strip()
+    loaded_model_name = configured_model_name or next(iter(svc.embed_models), "")
+
+    if not loaded_model_name:
+        raise HTTPException(status_code=503, detail="Model not loaded")
+
+    return HealthResponse(
+        status="ok",
+        model=loaded_model_name,
+        device=DEVICE,
+    )
+
+
+@app.post("/embed", response_model=EmbeddingResponse)
+async def embed(req: EmbeddingRequest) -> EmbeddingResponse:
+    texts = [req.input] if isinstance(req.input, str) else req.input
+
+    if not texts or any(not isinstance(text, str) or not text.strip() for text in texts):
+        raise HTTPException(status_code=400, detail="Input must contain non-empty strings")
+
+    resolved_model_name = (req.model_name or EMBEDDING_MODEL_NAME or "").strip()
+    if not resolved_model_name:
+        raise HTTPException(
+            status_code=400,
+            detail="No embedding model specified. Set EMBEDDING_MODEL_NAME or pass model_name.",
+        )
+
+    try:
+        if req.mode == "query":
+            if len(texts) != 1:
+                raise HTTPException(
+                    status_code=400,
+                    detail="mode='query' requires a single input string",
+                )
+            vectors = [await svc.embed_query(texts[0], model_name=resolved_model_name)]
+        else:
+            vectors = await svc.embed_documents(texts, model_name=resolved_model_name)
+
+        dimensions = len(vectors[0]) if vectors else 0
+        return EmbeddingResponse(
+            model=resolved_model_name,
+            dimensions=dimensions,
+            count=len(vectors),
+            data=vectors,
+        )
+    except HTTPException:
+        raise
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=f"Embedding failed: {exc}") from exc
+
+
+def main() -> None:
+    uvicorn.run("remote_embedding.app:app", host=DEFAULT_HOST, port=DEFAULT_PORT)

remote_embedding-0.1.0/src/remote_embedding/remote.py

@@ -0,0 +1,71 @@
+"""Client for the remote embedding FastAPI service."""
+
+from typing import Optional
+
+import requests
+from langchain_core.embeddings import Embeddings
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+
+class RemoteEmbeddings(Embeddings):
+    def __init__(
+        self,
+        base_url: str = "http://127.0.0.1:5055",
+        timeout: int = 300,
+        expected_dimensions: Optional[int] = None,
+        model_name: Optional[str] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.expected_dimensions = expected_dimensions
+        self.model_name = model_name
+
+        self.session = requests.Session()
+        retries = Retry(
+            total=3,
+            backoff_factor=0.5,
+            status_forcelist=[429, 500, 502, 503, 504],
+            allowed_methods=["POST", "GET"],
+        )
+        adapter = HTTPAdapter(max_retries=retries)
+        self.session.mount("http://", adapter)
+        self.session.mount("https://", adapter)
+
+    def _check_dim(self, vectors: list[list[float]]) -> None:
+        if not vectors or self.expected_dimensions is None:
+            return
+        if len(vectors[0]) != self.expected_dimensions:
+            raise ValueError(
+                f"Embedding dimension mismatch: expected {self.expected_dimensions}, got {len(vectors[0])}"
+            )
+
+    def embed_documents(self, texts: list[str]) -> list[list[float]]:
+        payload = {"input": texts, "mode": "documents"}
+        if self.model_name:
+            payload["model_name"] = self.model_name
+
+        response = self.session.post(
+            f"{self.base_url}/embed",
+            json=payload,
+            timeout=self.timeout,
+        )
+        response.raise_for_status()
+        vectors = response.json()["data"]
+        self._check_dim(vectors)
+        return vectors
+
+    def embed_query(self, text: str) -> list[float]:
+        payload = {"input": text, "mode": "query"}
+        if self.model_name:
+            payload["model_name"] = self.model_name
+
+        response = self.session.post(
+            f"{self.base_url}/embed",
+            json=payload,
+            timeout=self.timeout,
+        )
+        response.raise_for_status()
+        vectors = response.json()["data"]
+        self._check_dim(vectors)
+        return vectors[0]

remote_embedding-0.1.0/src/remote_embedding.egg-info/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: remote-embedding
+Version: 0.1.0
+Summary: A PyPI-ready FastAPI embedding service and LangChain-compatible remote client.
+Author: Meshkat Shariat Bagheri
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MeshkatShB/remote-embedding
+Project-URL: Issues, https://github.com/MeshkatShB/remote-embedding/issues
+Keywords: embeddings,fastapi,langchain,huggingface,api
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.115
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: langchain-huggingface>=0.1.2
+Requires-Dist: pydantic>=2.7
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: requests>=2.32
+Requires-Dist: uvicorn>=0.30
+Dynamic: license-file
+
+# remote-embedding
+
+`remote-embedding` packages two things together:
+
+- A FastAPI server that exposes a `/embed` API backed by local Hugging Face models.
+- A LangChain-compatible `RemoteEmbeddings` client that calls that server remotely.
+
+## Install
+
+```bash
+pip install remote-embedding
+```
+
+## Package Layout
+
+The import package is `remote_embedding`.
+
+```python
+from remote_embedding import RemoteEmbeddings
+```
+
+## Run The Server
+
+Set the environment variables your model needs.
+
+PowerShell:
+
+```powershell
+$env:EMBEDDING_MODEL_NAME="BAAI/bge-base-en-v1.5"
+$env:EMBEDDING_DIR="C:\\path\\to\\model-cache"
+$env:DEVICE="cpu"
+```
+
+Bash:
+
+```bash
+export EMBEDDING_MODEL_NAME=BAAI/bge-base-en-v1.5
+export EMBEDDING_DIR=/path/to/model-cache
+export DEVICE=cpu
+```
+
+Start the API:
+
+```bash
+remote-embedding-server
+```
+
+Or:
+
+```bash
+python -m remote_embedding
+```
+
+Defaults:
+
+- `HOST=0.0.0.0`
+- `PORT=5055`
+
+## Use The Client
+
+```python
+from remote_embedding import RemoteEmbeddings
+
+embeddings = RemoteEmbeddings(
+    base_url="http://127.0.0.1:5055",
+    model_name="BAAI/bge-base-en-v1.5",
+)
+
+docs = embeddings.embed_documents(["hello world", "remote embeddings"])
+query = embeddings.embed_query("search text")
+```
+
+## Build For PyPI
+
+Build distributions locally:
+
+```bash
+python -m pip install --upgrade build
+python -m build
+```
+
+This creates:
+
+- `dist/*.tar.gz`
+- `dist/*.whl`
+
+Upload with Twine:
+
+```bash
+python -m pip install --upgrade twine
+python -m twine upload dist/*
+```

remote_embedding-0.1.0/src/remote_embedding.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/remote_embedding/__init__.py
+src/remote_embedding/__main__.py
+src/remote_embedding/app.py
+src/remote_embedding/remote.py
+src/remote_embedding.egg-info/PKG-INFO
+src/remote_embedding.egg-info/SOURCES.txt
+src/remote_embedding.egg-info/dependency_links.txt
+src/remote_embedding.egg-info/entry_points.txt
+src/remote_embedding.egg-info/requires.txt
+src/remote_embedding.egg-info/top_level.txt

remote_embedding-0.1.0/src/remote_embedding.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

remote_embedding-0.1.0/src/remote_embedding.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+remote-embedding-server = remote_embedding.app:main

remote_embedding-0.1.0/src/remote_embedding.egg-info/requires.txt

@@ -0,0 +1,7 @@
+fastapi>=0.115
+langchain-core>=0.3
+langchain-huggingface>=0.1.2
+pydantic>=2.7
+python-dotenv>=1.0
+requests>=2.32
+uvicorn>=0.30

remote_embedding-0.1.0/src/remote_embedding.egg-info/top_level.txt

@@ -0,0 +1 @@
+remote_embedding