keiro-client 0.1.0__tar.gz

keiro_client-0.1.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Manas Ranjan Jena
+
+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.

keiro_client-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: keiro-client
+Version: 0.1.0
+Summary: Python client SDK for Keiro — self-hostable adaptive RAG infrastructure
+License: MIT License
+        
+        Copyright (c) 2025 Manas Ranjan Jena
+        
+        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.
+        
+Project-URL: Repository, https://github.com/ManasRanjanJena253/Keiro
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.7.0
+Dynamic: license-file
+
+# keiro-client
+
+Python client SDK for [Keiro](https://github.com/yourusername/keiro) — a self-hostable adaptive RAG infrastructure.
+
+## Installation
+
+```bash
+pip install keiro-client
+```
+
+## Quickstart
+
+```python
+from keiro import KeiroClient
+
+client = KeiroClient(
+    base_url="http://localhost:8080",
+    secret="your-shared-secret",
+    namespace="my-docs"
+)
+
+# Ingest a document
+job_id = client.ingest("document.pdf")
+
+# Poll until complete
+while True:
+    status = client.job_status(job_id)
+    if status.is_terminal:
+        break
+
+# Query
+response = client.query("What are the main compliance obligations?")
+print(response.response)
+print(f"Strategy used: {response.retrieval_details.tier_name}")
+print(f"Cache hit: {response.cache_hit}")
+print(f"Total tokens: {response.total_tokens}")
+```
+
+## Configuration
+
+| Parameter | Description |
+|-----------|-------------|
+| `base_url` | URL of your Keiro gateway, e.g. `http://localhost:8080` |
+| `secret` | Shared secret set in `KEIRO_SECRET` env var |
+| `namespace` | Namespace identifier scoping all operations |
+| `timeout` | Request timeout in seconds (default 120) |
+
+## Exception Handling
+
+```python
+from keiro import (
+    KeiroClient,
+    AuthenticationError,
+    RateLimitError,
+    IngestionError,
+    ConnectionError,
+)
+
+try:
+    response = client.query("What is the refund policy?")
+except AuthenticationError:
+    print("Invalid secret")
+except RateLimitError as e:
+    print(f"Rate limited — retry after {e.retry_after}s")
+except ConnectionError:
+    print("Gateway unreachable")
+```
+
+## Links
+
+- [Keiro repository](https://github.com/ManasRanjanJena253/Keiro)
+- [Report issues](https://github.com/ManasRanjanJena253/Keiro/issues)

keiro_client-0.1.0/README.md

@@ -0,0 +1,72 @@
+# keiro-client
+
+Python client SDK for [Keiro](https://github.com/yourusername/keiro) — a self-hostable adaptive RAG infrastructure.
+
+## Installation
+
+```bash
+pip install keiro-client
+```
+
+## Quickstart
+
+```python
+from keiro import KeiroClient
+
+client = KeiroClient(
+    base_url="http://localhost:8080",
+    secret="your-shared-secret",
+    namespace="my-docs"
+)
+
+# Ingest a document
+job_id = client.ingest("document.pdf")
+
+# Poll until complete
+while True:
+    status = client.job_status(job_id)
+    if status.is_terminal:
+        break
+
+# Query
+response = client.query("What are the main compliance obligations?")
+print(response.response)
+print(f"Strategy used: {response.retrieval_details.tier_name}")
+print(f"Cache hit: {response.cache_hit}")
+print(f"Total tokens: {response.total_tokens}")
+```
+
+## Configuration
+
+| Parameter | Description |
+|-----------|-------------|
+| `base_url` | URL of your Keiro gateway, e.g. `http://localhost:8080` |
+| `secret` | Shared secret set in `KEIRO_SECRET` env var |
+| `namespace` | Namespace identifier scoping all operations |
+| `timeout` | Request timeout in seconds (default 120) |
+
+## Exception Handling
+
+```python
+from keiro import (
+    KeiroClient,
+    AuthenticationError,
+    RateLimitError,
+    IngestionError,
+    ConnectionError,
+)
+
+try:
+    response = client.query("What is the refund policy?")
+except AuthenticationError:
+    print("Invalid secret")
+except RateLimitError as e:
+    print(f"Rate limited — retry after {e.retry_after}s")
+except ConnectionError:
+    print("Gateway unreachable")
+```
+
+## Links
+
+- [Keiro repository](https://github.com/ManasRanjanJena253/Keiro)
+- [Report issues](https://github.com/ManasRanjanJena253/Keiro/issues)

keiro_client-0.1.0/keiro/__init__.py

@@ -0,0 +1,31 @@
+from .client import KeiroClient
+from .exceptions import (
+    AuthenticationError,
+    ConnectionError,
+    IngestionError,
+    KeiroError,
+    RateLimitError,
+)
+from .models import (
+    JobStatus,
+    JobStatusResponse,
+    QueryResponse,
+    RetrievalDetails,
+    RetrievalType,
+)
+
+__all__ = [
+    "KeiroClient",
+    "KeiroError",
+    "AuthenticationError",
+    "RateLimitError",
+    "IngestionError",
+    "ConnectionError",
+    "QueryResponse",
+    "RetrievalDetails",
+    "RetrievalType",
+    "JobStatus",
+    "JobStatusResponse",
+]
+
+__version__ = "0.1.0"

keiro_client-0.1.0/keiro/client.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import httpx
+from pathlib import Path
+
+from .exceptions import (
+    AuthenticationError,
+    ConnectionError,
+    IngestionError,
+    KeiroError,
+    RateLimitError,
+)
+from .models import IngestResponse, JobStatusResponse, QueryResponse
+
+
+class KeiroClient:
+    """
+    Synchronous client for the Keiro adaptive RAG gateway.
+
+    Parameters
+    ----------
+    base_url:  Base URL of the Go gateway, e.g. "http://localhost:8080"
+    secret:    Shared secret configured in KEIRO_SECRET
+    namespace: Namespace identifier scoping all operations to an isolated
+               ChromaDB collection
+    timeout:   httpx timeout in seconds (default 120 — multi-hop queries
+               can be slow)
+    """
+
+    def __init__(
+            self,
+            base_url: str,
+            secret: str,
+            namespace: str,
+            timeout: float = 120.0,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._headers = {
+            "X-Secret":    secret,
+            "X-Namespace": namespace,
+        }
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers=self._headers,
+            timeout=timeout,
+        )
+
+    # ── public interface ──────────────────────────────────────────────────────
+
+    def query(self, query_text: str) -> QueryResponse:
+        """
+        Submit a query to the adaptive RAG pipeline.
+
+        The gateway classifies the query, selects the appropriate retrieval
+        tier, runs retrieval and generation, and returns the response with
+        full metadata including strategy used, token counts, and cache status.
+
+        Parameters
+        ----------
+        query_text: The question or instruction to answer from the ingested
+                    document corpus
+
+        Returns
+        -------
+        QueryResponse with fields: response, prompt_tokens, completion_tokens,
+        response_model, cache_hit, retrieval_details (tier + top_k)
+        """
+        raw = self._post("/v1/query", json={"query": query_text})
+        return QueryResponse.model_validate(raw)
+
+    def ingest(self, file_path: str | Path) -> str:
+        """
+        Upload a document for ingestion into the namespace.
+
+        The request returns immediately with a job ID. Ingestion runs
+        asynchronously — use job_status() to poll until complete.
+
+        Parameters
+        ----------
+        file_path: Path to a PDF or plain text file
+
+        Returns
+        -------
+        job_id string — use with job_status() to track progress
+        """
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"File not found: {path}")
+
+        with path.open("rb") as f:
+            raw = self._post_multipart(
+                "/v1/ingest",
+                files={"file": (path.name, f, _mime_type(path))},
+            )
+        return IngestResponse.model_validate(raw).job_id
+
+    def job_status(self, job_id: str) -> JobStatusResponse:
+        """
+        Poll the status of an ingestion job.
+
+        Parameters
+        ----------
+        job_id: Job ID returned by ingest()
+
+        Returns
+        -------
+        JobStatusResponse with job_status (pending/processing/complete/failed),
+        and error string if failed. Use .is_terminal, .is_complete, .is_failed
+        properties to branch on status without comparing integers directly.
+
+        Raises
+        ------
+        IngestionError if the job has reached failed status
+        """
+        raw = self._get(f"/v1/jobs/{job_id}")
+        result = JobStatusResponse.model_validate(raw)
+        if result.is_failed:
+            raise IngestionError(job_id, result.error)
+        return result
+
+    def health(self) -> dict:
+        """
+        Check liveness and readiness of all stack components.
+
+        Returns the raw health response dict from the gateway.
+        """
+        return self._get("/health")
+
+    def close(self) -> None:
+        """Close the underlying httpx client. Call when done if not using
+        the client as a context manager."""
+        self._client.close()
+
+    # ── context manager ───────────────────────────────────────────────────────
+
+    def __enter__(self) -> KeiroClient:
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.close()
+
+    # ── internal helpers ──────────────────────────────────────────────────────
+
+    def _post(self, path: str, **kwargs) -> dict:
+        return self._request("POST", path, **kwargs)
+
+    def _post_multipart(self, path: str, **kwargs) -> dict:
+        return self._request("POST", path, **kwargs)
+
+    def _get(self, path: str) -> dict:
+        return self._request("GET", path)
+
+    def _request(self, method: str, path: str, **kwargs) -> dict:
+        try:
+            response = self._client.request(method, path, **kwargs)
+        except httpx.ConnectError as e:
+            raise ConnectionError(
+                f"Cannot reach Keiro gateway at {self._base_url}: {e}"
+            ) from e
+        except httpx.TimeoutException as e:
+            raise KeiroError(f"Request timed out: {e}") from e
+
+        if response.status_code == 401:
+            raise AuthenticationError("Invalid or missing X-Secret header")
+        if response.status_code == 429:
+            retry_after = float(response.headers.get("Retry-After", 0) or 0)
+            raise RateLimitError(retry_after=retry_after or None)
+        if response.status_code >= 400:
+            raise KeiroError(
+                f"Gateway returned {response.status_code}: {response.text}"
+            )
+
+        return response.json()
+
+
+# ── helpers ───────────────────────────────────────────────────────────────────
+
+def _mime_type(path: Path) -> str:
+    suffix = path.suffix.lower()
+    return {
+        ".pdf": "application/pdf",
+        ".txt": "text/plain",
+        ".md":  "text/markdown",
+    }.get(suffix, "application/octet-stream")

keiro_client-0.1.0/keiro/exceptions.py

@@ -0,0 +1,32 @@
+class KeiroError(Exception):
+    """Base exception for all Keiro client errors."""
+    pass
+
+
+class AuthenticationError(KeiroError):
+    """Raised when the shared secret is invalid or missing (HTTP 401)."""
+    pass
+
+
+class RateLimitError(KeiroError):
+    """Raised when the namespace rate limit is exceeded (HTTP 429)."""
+
+    def __init__(self, retry_after: float | None = None):
+        self.retry_after = retry_after
+        msg = "Rate limit exceeded"
+        if retry_after:
+            msg += f" — retry after {retry_after}s"
+        super().__init__(msg)
+
+
+class IngestionError(KeiroError):
+    """Raised when an ingestion job reaches failed status."""
+
+    def __init__(self, job_id: str, detail: str = ""):
+        self.job_id = job_id
+        super().__init__(f"Ingestion job {job_id} failed: {detail}")
+
+
+class ConnectionError(KeiroError):
+    """Raised when the gateway cannot be reached."""
+    pass

keiro_client-0.1.0/keiro/models.py

@@ -0,0 +1,66 @@
+from enum import IntEnum
+from pydantic import BaseModel, Field
+
+
+class RetrievalType(IntEnum):
+    UNSPECIFIED = 0
+    HYBRID      = 1   # simple tier — top-2, no reranking
+    SELF_QUERYING = 2 # multi-hop tier — iterative, max 3 hops
+    MULTI_VECTOR  = 3 # complex tier — top-8, MMR + cross-encoder
+
+
+class JobStatus(IntEnum):
+    PENDING    = 0
+    PROCESSING = 1
+    COMPLETE   = 2
+    FAILED     = 3
+
+
+class RetrievalDetails(BaseModel):
+    retrieval_type: RetrievalType
+    top_k: int
+
+    @property
+    def tier_name(self) -> str:
+        return {
+            RetrievalType.HYBRID:        "simple",
+            RetrievalType.SELF_QUERYING: "multi_hop",
+            RetrievalType.MULTI_VECTOR:  "complex",
+        }.get(self.retrieval_type, "unspecified")
+
+
+class QueryResponse(BaseModel):
+    response:          str
+    prompt_tokens:     int
+    completion_tokens: int = Field(alias="completion_token")
+    response_model:    str
+    cache_hit:         bool
+    retrieval_details: RetrievalDetails
+
+    model_config = {"populate_by_name": True}
+
+    @property
+    def total_tokens(self) -> int:
+        return self.prompt_tokens + self.completion_tokens
+
+
+class IngestResponse(BaseModel):
+    job_id: str
+
+
+class JobStatusResponse(BaseModel):
+    job_id:     str
+    job_status: JobStatus
+    error:      str = ""
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.job_status in (JobStatus.COMPLETE, JobStatus.FAILED)
+
+    @property
+    def is_complete(self) -> bool:
+        return self.job_status == JobStatus.COMPLETE
+
+    @property
+    def is_failed(self) -> bool:
+        return self.job_status == JobStatus.FAILED

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

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: keiro-client
+Version: 0.1.0
+Summary: Python client SDK for Keiro — self-hostable adaptive RAG infrastructure
+License: MIT License
+        
+        Copyright (c) 2025 Manas Ranjan Jena
+        
+        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.
+        
+Project-URL: Repository, https://github.com/ManasRanjanJena253/Keiro
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.7.0
+Dynamic: license-file
+
+# keiro-client
+
+Python client SDK for [Keiro](https://github.com/yourusername/keiro) — a self-hostable adaptive RAG infrastructure.
+
+## Installation
+
+```bash
+pip install keiro-client
+```
+
+## Quickstart
+
+```python
+from keiro import KeiroClient
+
+client = KeiroClient(
+    base_url="http://localhost:8080",
+    secret="your-shared-secret",
+    namespace="my-docs"
+)
+
+# Ingest a document
+job_id = client.ingest("document.pdf")
+
+# Poll until complete
+while True:
+    status = client.job_status(job_id)
+    if status.is_terminal:
+        break
+
+# Query
+response = client.query("What are the main compliance obligations?")
+print(response.response)
+print(f"Strategy used: {response.retrieval_details.tier_name}")
+print(f"Cache hit: {response.cache_hit}")
+print(f"Total tokens: {response.total_tokens}")
+```
+
+## Configuration
+
+| Parameter | Description |
+|-----------|-------------|
+| `base_url` | URL of your Keiro gateway, e.g. `http://localhost:8080` |
+| `secret` | Shared secret set in `KEIRO_SECRET` env var |
+| `namespace` | Namespace identifier scoping all operations |
+| `timeout` | Request timeout in seconds (default 120) |
+
+## Exception Handling
+
+```python
+from keiro import (
+    KeiroClient,
+    AuthenticationError,
+    RateLimitError,
+    IngestionError,
+    ConnectionError,
+)
+
+try:
+    response = client.query("What is the refund policy?")
+except AuthenticationError:
+    print("Invalid secret")
+except RateLimitError as e:
+    print(f"Rate limited — retry after {e.retry_after}s")
+except ConnectionError:
+    print("Gateway unreachable")
+```
+
+## Links
+
+- [Keiro repository](https://github.com/ManasRanjanJena253/Keiro)
+- [Report issues](https://github.com/ManasRanjanJena253/Keiro/issues)

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

@@ -0,0 +1,12 @@
+LICENSE.md
+README.md
+pyproject.toml
+keiro/__init__.py
+keiro/client.py
+keiro/exceptions.py
+keiro/models.py
+keiro_client.egg-info/PKG-INFO
+keiro_client.egg-info/SOURCES.txt
+keiro_client.egg-info/dependency_links.txt
+keiro_client.egg-info/requires.txt
+keiro_client.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,2 @@
+httpx>=0.27.0
+pydantic>=2.7.0

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

@@ -0,0 +1 @@
+keiro

keiro_client-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "keiro-client"
+version = "0.1.0"
+description = "Python client SDK for Keiro — self-hostable adaptive RAG infrastructure"
+readme = "README.md"
+license = { file = "LICENSE.md" }
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.7.0",
+]
+
+[project.urls]
+Repository = "https://github.com/ManasRanjanJena253/Keiro"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["keiro*"]

keiro_client-0.1.0/setup.cfg

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