rag-plug 0.1.0__tar.gz

rag_plug-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: rag-plug
+Version: 0.1.0
+Summary: RAG client
+Author: George K
+Author-email: george@dormint.io
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: openai-agents (>=0.9.2,<0.10.0)
+Description-Content-Type: text/markdown
+
+# rag-plug
+
+Python-клиент для backend RAGPlug API.
+Поддерживает добавление памяти, семантический поиск и удаление записей по ID (sync/async).
+
+## Возможности
+- `RagPlug` с типизированными моделями ответов.
+- Аутентификация через `X-API-Key`.
+- Операции в рамках конкретной памяти (`memory_name`).
+- Готовые CLI-скрипты для быстрого add/search.
+
+## Требования
+- Python `3.10+`
+- [Poetry](https://python-poetry.org/) (рекомендуется)
+
+## Установка
+```bash
+poetry install
+```
+
+Или через pip (локальная разработка):
+```bash
+pip install -e .
+```
+
+## Конфигурация
+Создайте `.env` в корне проекта:
+
+```env
+API_KEY=your_api_key
+MEMORY_NAME=your_memory_name
+```
+
+`.env` добавлен в `.gitignore` и не должен попадать в репозиторий.
+
+## Использование в Python
+```python
+from ragplug import RagPlug
+
+client = RagPlug(api_key="YOUR_API_KEY", default_memory_name="main")
+
+item = client.add("Paris is the capital of France", metadata={"source": "docs"})
+result = client.search("capital of France", top_k=3)
+client.delete(item.id)
+```
+
+Async-пример:
+```python
+import asyncio
+from ragplug import RagPlug
+
+async def main():
+    client = RagPlug(api_key="YOUR_API_KEY", default_memory_name="main")
+    await client.aadd("Async memory text")
+    res = await client.asearch("Async memory")
+    print(res.results)
+
+asyncio.run(main())
+```
+
+## CLI-скрипты
+- `scripts/add_memory.py`
+- `scripts/search.py`
+
+Пример запуска:
+```bash
+set -a; source .env; set +a
+
+python scripts/add_memory.py \
+  --api-key "$API_KEY" \
+  --memory-name "$MEMORY_NAME" \
+  --text "Smoke test memory" \
+  --metadata '{"source":"scripts"}'
+
+python scripts/search.py \
+  --api-key "$API_KEY" \
+  --memory-name "$MEMORY_NAME" \
+  --query "Smoke test" \
+  --top-k 5
+```
+
+## Команды разработки
+```bash
+poetry check        # проверка метаданных пакета
+poetry build        # сборка sdist + wheel
+python -m compileall ragplug scripts
+```
+
+## Релиз
+CI публикует пакет в PyPI по тегам `v*`.
+Тег должен совпадать с версией в `pyproject.toml`.
+
+Пример:
+```bash
+poetry version patch
+git tag v$(poetry version -s)
+git push origin --tags
+```
+
+## Структура проекта
+- `ragplug/client.py`: публичный фасад `RagPlug`.
+- `ragplug/types.py`: модели ответов и `RagPlugError`.
+- `ragplug/_api.py`, `_transport.py`, `_error_handler.py`, `_validation.py`, `_response_parser.py`: внутренние слои клиента.
+- `scripts/`: CLI-утилиты.
+

rag_plug-0.1.0/README.md

@@ -0,0 +1,104 @@
+# rag-plug
+
+Python-клиент для backend RAGPlug API.
+Поддерживает добавление памяти, семантический поиск и удаление записей по ID (sync/async).
+
+## Возможности
+- `RagPlug` с типизированными моделями ответов.
+- Аутентификация через `X-API-Key`.
+- Операции в рамках конкретной памяти (`memory_name`).
+- Готовые CLI-скрипты для быстрого add/search.
+
+## Требования
+- Python `3.10+`
+- [Poetry](https://python-poetry.org/) (рекомендуется)
+
+## Установка
+```bash
+poetry install
+```
+
+Или через pip (локальная разработка):
+```bash
+pip install -e .
+```
+
+## Конфигурация
+Создайте `.env` в корне проекта:
+
+```env
+API_KEY=your_api_key
+MEMORY_NAME=your_memory_name
+```
+
+`.env` добавлен в `.gitignore` и не должен попадать в репозиторий.
+
+## Использование в Python
+```python
+from ragplug import RagPlug
+
+client = RagPlug(api_key="YOUR_API_KEY", default_memory_name="main")
+
+item = client.add("Paris is the capital of France", metadata={"source": "docs"})
+result = client.search("capital of France", top_k=3)
+client.delete(item.id)
+```
+
+Async-пример:
+```python
+import asyncio
+from ragplug import RagPlug
+
+async def main():
+    client = RagPlug(api_key="YOUR_API_KEY", default_memory_name="main")
+    await client.aadd("Async memory text")
+    res = await client.asearch("Async memory")
+    print(res.results)
+
+asyncio.run(main())
+```
+
+## CLI-скрипты
+- `scripts/add_memory.py`
+- `scripts/search.py`
+
+Пример запуска:
+```bash
+set -a; source .env; set +a
+
+python scripts/add_memory.py \
+  --api-key "$API_KEY" \
+  --memory-name "$MEMORY_NAME" \
+  --text "Smoke test memory" \
+  --metadata '{"source":"scripts"}'
+
+python scripts/search.py \
+  --api-key "$API_KEY" \
+  --memory-name "$MEMORY_NAME" \
+  --query "Smoke test" \
+  --top-k 5
+```
+
+## Команды разработки
+```bash
+poetry check        # проверка метаданных пакета
+poetry build        # сборка sdist + wheel
+python -m compileall ragplug scripts
+```
+
+## Релиз
+CI публикует пакет в PyPI по тегам `v*`.
+Тег должен совпадать с версией в `pyproject.toml`.
+
+Пример:
+```bash
+poetry version patch
+git tag v$(poetry version -s)
+git push origin --tags
+```
+
+## Структура проекта
+- `ragplug/client.py`: публичный фасад `RagPlug`.
+- `ragplug/types.py`: модели ответов и `RagPlugError`.
+- `ragplug/_api.py`, `_transport.py`, `_error_handler.py`, `_validation.py`, `_response_parser.py`: внутренние слои клиента.
+- `scripts/`: CLI-утилиты.

rag_plug-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[tool.poetry]
+name = "rag-plug"
+version = "0.1.0"
+description = "RAG client"
+authors = ["George K <george@dormint.io>"]
+readme = "README.md"
+packages = [{ include = "ragplug" }]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+openai-agents = "^0.9.2"
+httpx = "^0.28.1"
+
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

rag_plug-0.1.0/ragplug/__init__.py

@@ -0,0 +1,17 @@
+from .client import RagPlug
+from .types import (
+    MemoryDeleteResult,
+    MemoryItem,
+    RagPlugError,
+    SearchResponse,
+    SearchResult,
+)
+
+__all__ = [
+    "RagPlug",
+    "RagPlugError",
+    "MemoryItem",
+    "MemoryDeleteResult",
+    "SearchResult",
+    "SearchResponse",
+]

rag_plug-0.1.0/ragplug/_api.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+from urllib.parse import quote
+
+from ragplug._transport import _HttpTransport
+
+
+class _RagPlugApi:
+    def __init__(self, transport: _HttpTransport) -> None:
+        self._transport = transport
+
+    @staticmethod
+    def _segment(value: str) -> str:
+        return quote(value, safe="")
+
+    def version(self) -> Dict[str, Any]:
+        return self._transport.request_json("GET", "/version")
+
+    async def aversion(self) -> Dict[str, Any]:
+        return await self._transport.arequest_json("GET", "/version")
+
+    def add_memory(self, memory_name: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        path = f"/memory/{self._segment(memory_name)}"
+        return self._transport.request_json("POST", path, payload=payload)
+
+    async def aadd_memory(self, memory_name: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        path = f"/memory/{self._segment(memory_name)}"
+        return await self._transport.arequest_json("POST", path, payload=payload)
+
+    def delete_memory(self, memory_name: str, item_id: str) -> Dict[str, Any]:
+        path = f"/memory/{self._segment(memory_name)}/{self._segment(item_id)}"
+        return self._transport.request_json("DELETE", path)
+
+    async def adelete_memory(self, memory_name: str, item_id: str) -> Dict[str, Any]:
+        path = f"/memory/{self._segment(memory_name)}/{self._segment(item_id)}"
+        return await self._transport.arequest_json("DELETE", path)
+
+    def search_memory(self, memory_name: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        path = f"/search/{self._segment(memory_name)}"
+        return self._transport.request_json("POST", path, payload=payload)
+
+    async def asearch_memory(self, memory_name: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        path = f"/search/{self._segment(memory_name)}"
+        return await self._transport.arequest_json("POST", path, payload=payload)

rag_plug-0.1.0/ragplug/_error_handler.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+
+import httpx
+
+from ragplug.types import RagPlugError
+
+
+class _ErrorHandler:
+    @staticmethod
+    def raise_for_http_error(response: httpx.Response) -> None:
+        if response.is_success:
+            return
+
+        detail = None
+        try:
+            payload = response.json()
+            if isinstance(payload, dict):
+                detail = payload.get("detail")
+        except ValueError:
+            detail = None
+
+        message = str(detail) if detail else response.text.strip() or "Request failed"
+        raise RagPlugError(message=message, status_code=response.status_code)
+
+    @staticmethod
+    def raise_network_error(error: httpx.RequestError) -> None:
+        raise RagPlugError(f"Network error: {error}") from error
+
+    @staticmethod
+    def parse_json_dict(response: httpx.Response) -> Dict[str, Any]:
+        try:
+            data = response.json()
+        except ValueError as error:
+            raise RagPlugError(
+                "Invalid JSON response",
+                status_code=response.status_code,
+            ) from error
+
+        if not isinstance(data, dict):
+            raise RagPlugError(
+                "Unexpected response format",
+                status_code=response.status_code,
+            )
+        return data

rag_plug-0.1.0/ragplug/_response_parser.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from ragplug.types import (
+    MemoryDeleteResult,
+    MemoryItem,
+    RagPlugError,
+    SearchResponse,
+    SearchResult,
+)
+
+
+class _ResponseParser:
+    @staticmethod
+    def version(data: Dict[str, Any]) -> str:
+        version_value = data.get("version")
+        if version_value is None:
+            raise RagPlugError("Unexpected /version response format")
+        return str(version_value)
+
+    @staticmethod
+    def memory_item(data: Dict[str, Any]) -> MemoryItem:
+        return MemoryItem(
+            id=str(data.get("id", "")),
+            text=str(data.get("text", "")),
+            metadata=data.get("metadata") if isinstance(data.get("metadata"), dict) else {},
+        )
+
+    @staticmethod
+    def memory_delete(data: Dict[str, Any], item_id: str) -> MemoryDeleteResult:
+        return MemoryDeleteResult(
+            id=str(data.get("id", item_id)),
+            deleted=bool(data.get("deleted", False)),
+        )
+
+    @staticmethod
+    def search(data: Dict[str, Any]) -> SearchResponse:
+        raw_results = data.get("results")
+        results: List[SearchResult] = []
+
+        if isinstance(raw_results, list):
+            for row in raw_results:
+                if not isinstance(row, dict):
+                    continue
+                results.append(
+                    SearchResult(
+                        id=str(row.get("id", "")),
+                        text=str(row.get("text", "")),
+                        metadata=row.get("metadata") if isinstance(row.get("metadata"), dict) else {},
+                        score=float(row.get("score", 0.0) or 0.0),
+                    )
+                )
+
+        return SearchResponse(query=str(data.get("query", "")), results=results)

rag_plug-0.1.0/ragplug/_transport.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import httpx
+
+from ragplug._error_handler import _ErrorHandler
+
+
+class _HttpTransport:
+    def __init__(self, endpoint_url: str, api_key: str, timeout: float) -> None:
+        self.endpoint_url = endpoint_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+
+    @property
+    def headers(self) -> Dict[str, str]:
+        return {
+            "X-API-Key": self.api_key,
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+
+    def _url(self, path: str) -> str:
+        return f"{self.endpoint_url}{path}"
+
+    def request_json(
+        self,
+        method: str,
+        path: str,
+        payload: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        try:
+            with httpx.Client(timeout=self.timeout, headers=self.headers) as client:
+                response = client.request(method, self._url(path), json=payload)
+        except httpx.RequestError as error:
+            _ErrorHandler.raise_network_error(error)
+
+        _ErrorHandler.raise_for_http_error(response)
+        return _ErrorHandler.parse_json_dict(response)
+
+    async def arequest_json(
+        self,
+        method: str,
+        path: str,
+        payload: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout, headers=self.headers) as client:
+                response = await client.request(method, self._url(path), json=payload)
+        except httpx.RequestError as error:
+            _ErrorHandler.raise_network_error(error)
+
+        _ErrorHandler.raise_for_http_error(response)
+        return _ErrorHandler.parse_json_dict(response)

rag_plug-0.1.0/ragplug/_validation.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Optional
+
+
+class _Validator:
+    @staticmethod
+    def require_non_empty(value: str, name: str) -> str:
+        if not value or not value.strip():
+            raise ValueError(f"{name} must be a non-empty string")
+        return value
+
+    @staticmethod
+    def validate_top_k(top_k: int) -> int:
+        if top_k < 1 or top_k > 50:
+            raise ValueError("top_k must be between 1 and 50")
+        return top_k
+
+    @staticmethod
+    def resolve_memory_name(memory_name: Optional[str], default_memory_name: Optional[str]) -> str:
+        name = memory_name or default_memory_name
+        if not name or not name.strip():
+            raise ValueError("memory_name is required (or set default_memory_name in RagPlug)")
+        return name

rag_plug-0.1.0/ragplug/client.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from ragplug._api import _RagPlugApi
+from ragplug._response_parser import _ResponseParser
+from ragplug._transport import _HttpTransport
+from ragplug._validation import _Validator
+from ragplug.types import MemoryDeleteResult, MemoryItem, SearchResponse
+
+
+class RagPlug:
+    endpoint_url = "https://api-ragplug.dormint.io"
+
+    def __init__(
+        self,
+        api_key: str,
+        endpoint_url: Optional[str] = None,
+        default_memory_name: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.api_key = api_key
+        self.endpoint_url = (endpoint_url or self.endpoint_url).rstrip("/")
+        self.default_memory_name = default_memory_name
+        self.timeout = timeout
+
+        self._transport = _HttpTransport(
+            endpoint_url=self.endpoint_url,
+            api_key=self.api_key,
+            timeout=self.timeout,
+        )
+        self._api = _RagPlugApi(self._transport)
+
+    def _memory_name(self, memory_name: Optional[str]) -> str:
+        return _Validator.resolve_memory_name(memory_name, self.default_memory_name)
+
+    def version(self) -> str:
+        data = self._api.version()
+        return _ResponseParser.version(data)
+
+    async def aversion(self) -> str:
+        data = await self._api.aversion()
+        return _ResponseParser.version(data)
+
+    def add(
+        self,
+        text: str,
+        memory_name: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        item_id: Optional[str] = None,
+    ) -> MemoryItem:
+        _Validator.require_non_empty(text, "text")
+        resolved_memory_name = self._memory_name(memory_name)
+
+        payload: Dict[str, Any] = {
+            "text": text,
+            "metadata": metadata or {},
+            "id": item_id,
+        }
+        data = self._api.add_memory(resolved_memory_name, payload)
+        return _ResponseParser.memory_item(data)
+
+    async def aadd(
+        self,
+        text: str,
+        memory_name: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        item_id: Optional[str] = None,
+    ) -> MemoryItem:
+        _Validator.require_non_empty(text, "text")
+        resolved_memory_name = self._memory_name(memory_name)
+
+        payload: Dict[str, Any] = {
+            "text": text,
+            "metadata": metadata or {},
+            "id": item_id,
+        }
+        data = await self._api.aadd_memory(resolved_memory_name, payload)
+        return _ResponseParser.memory_item(data)
+
+    def delete(self, item_id: str, memory_name: Optional[str] = None) -> MemoryDeleteResult:
+        _Validator.require_non_empty(item_id, "item_id")
+        resolved_memory_name = self._memory_name(memory_name)
+
+        data = self._api.delete_memory(resolved_memory_name, item_id)
+        return _ResponseParser.memory_delete(data, item_id)
+
+    async def adelete(self, item_id: str, memory_name: Optional[str] = None) -> MemoryDeleteResult:
+        _Validator.require_non_empty(item_id, "item_id")
+        resolved_memory_name = self._memory_name(memory_name)
+
+        data = await self._api.adelete_memory(resolved_memory_name, item_id)
+        return _ResponseParser.memory_delete(data, item_id)
+
+    def search(
+        self,
+        query: str,
+        top_k: int = 5,
+        memory_name: Optional[str] = None,
+    ) -> SearchResponse:
+        _Validator.require_non_empty(query, "query")
+        _Validator.validate_top_k(top_k)
+        resolved_memory_name = self._memory_name(memory_name)
+
+        payload = {"query": query, "top_k": top_k}
+        data = self._api.search_memory(resolved_memory_name, payload)
+        return _ResponseParser.search(data)
+
+    async def asearch(
+        self,
+        query: str,
+        top_k: int = 5,
+        memory_name: Optional[str] = None,
+    ) -> SearchResponse:
+        _Validator.require_non_empty(query, "query")
+        _Validator.validate_top_k(top_k)
+        resolved_memory_name = self._memory_name(memory_name)
+
+        payload = {"query": query, "top_k": top_k}
+        data = await self._api.asearch_memory(resolved_memory_name, payload)
+        return _ResponseParser.search(data)

rag_plug-0.1.0/ragplug/types.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass(slots=True)
+class MemoryItem:
+    id: str
+    text: str
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class MemoryDeleteResult:
+    id: str
+    deleted: bool
+
+
+@dataclass(slots=True)
+class SearchResult:
+    id: str
+    text: str
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    score: float = 0.0
+
+
+@dataclass(slots=True)
+class SearchResponse:
+    query: str
+    results: List[SearchResult] = field(default_factory=list)
+
+
+class RagPlugError(RuntimeError):
+    def __init__(self, message: str, status_code: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code