larkup 0.1.14__tar.gz

larkup-0.1.14/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: larkup
+Version: 0.1.14
+Summary: Official Python SDK for the Larkup API
+Keywords: rag,retrieval-augmented-generation,larkup,ai,sdk
+Author: Abdelrahman
+Author-email: Abdelrahman <abdelrahmanaboneda@gmail.com>
+License-Expression: MIT
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.13.4
+Requires-Python: >=3.10
+Project-URL: Homepage, https://larkup.de
+Project-URL: Documentation, https://larkup.de/docs
+Project-URL: Repository, https://github.com/BuddyHere-AI/buddy-rag
+Description-Content-Type: text/markdown
+
+# Larkup Python SDK
+
+The official Python client for the **Larkup** platform.
+
+This SDK provides a simple, Pythonic interface to interact with your running Larkup servers. It offers both synchronous and asynchronous clients, built on top of `httpx` and `pydantic`.
+
+## Installation
+
+Install the package via pip or uv:
+
+```bash
+pip install larkup
+# or
+uv pip install larkup
+```
+
+## Quick Start
+
+### Synchronous Client
+
+```python
+from larkup import LarkupClient
+
+# Initialize the client
+client = LarkupClient(base_url="http://localhost:4567")
+
+# 1. Query the RAG Pipeline
+response = client.query(
+    query="What is Larkup?",
+    top_k=5
+)
+for hit in response.hits:
+    print(hit.document.content)
+
+# 2. Add Documents to the Pipeline
+client.documents.add(
+    content="Larkup is building a new learning system for the AI Era.",
+    metadata={"source": "manual-entry"}
+)
+
+# 3. Trigger Indexing
+client.index()
+print("Documents indexed successfully.")
+```
+
+### Asynchronous Client
+
+```python
+import asyncio
+from larkup import AsyncLarkupClient
+
+async def main():
+    client = AsyncLarkupClient(base_url="http://localhost:4567")
+    
+    response = await client.query(
+        query="What is the future of education?",
+        top_k=3
+    )
+    print(response.hits)
+
+asyncio.run(main())
+```
+
+## Features
+
+- **Sync & Async Support**: Use `LarkupClient` or `AsyncLarkupClient`.
+- **Querying**: Execute semantic searches against your vector store.
+- **Data Ingestion**: Add documents and web pages programmatically.
+- **Strong Typing**: Built with Pydantic for validation and editor autocompletion.
+
+## Documentation
+
+For full API reference and advanced usage, visit the [Larkup Documentation](https://larkup.de/docs).

larkup-0.1.14/README.md

@@ -0,0 +1,73 @@
+# Larkup Python SDK
+
+The official Python client for the **Larkup** platform.
+
+This SDK provides a simple, Pythonic interface to interact with your running Larkup servers. It offers both synchronous and asynchronous clients, built on top of `httpx` and `pydantic`.
+
+## Installation
+
+Install the package via pip or uv:
+
+```bash
+pip install larkup
+# or
+uv pip install larkup
+```
+
+## Quick Start
+
+### Synchronous Client
+
+```python
+from larkup import LarkupClient
+
+# Initialize the client
+client = LarkupClient(base_url="http://localhost:4567")
+
+# 1. Query the RAG Pipeline
+response = client.query(
+    query="What is Larkup?",
+    top_k=5
+)
+for hit in response.hits:
+    print(hit.document.content)
+
+# 2. Add Documents to the Pipeline
+client.documents.add(
+    content="Larkup is building a new learning system for the AI Era.",
+    metadata={"source": "manual-entry"}
+)
+
+# 3. Trigger Indexing
+client.index()
+print("Documents indexed successfully.")
+```
+
+### Asynchronous Client
+
+```python
+import asyncio
+from larkup import AsyncLarkupClient
+
+async def main():
+    client = AsyncLarkupClient(base_url="http://localhost:4567")
+    
+    response = await client.query(
+        query="What is the future of education?",
+        top_k=3
+    )
+    print(response.hits)
+
+asyncio.run(main())
+```
+
+## Features
+
+- **Sync & Async Support**: Use `LarkupClient` or `AsyncLarkupClient`.
+- **Querying**: Execute semantic searches against your vector store.
+- **Data Ingestion**: Add documents and web pages programmatically.
+- **Strong Typing**: Built with Pydantic for validation and editor autocompletion.
+
+## Documentation
+
+For full API reference and advanced usage, visit the [Larkup Documentation](https://larkup.de/docs).

larkup-0.1.14/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "larkup"
+version = "0.1.14"
+description = "Official Python SDK for the Larkup API"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Abdelrahman", email = "abdelrahmanaboneda@gmail.com" }
+]
+requires-python = ">=3.10"
+keywords = ["rag", "retrieval-augmented-generation", "larkup", "ai", "sdk"]
+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",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.13.4",
+]
+
+[project.urls]
+Homepage = "https://larkup.de"
+Documentation = "https://larkup.de/docs"
+Repository = "https://github.com/BuddyHere-AI/buddy-rag"
+
+[build-system]
+requires = ["uv_build>=0.11.14,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "respx>=0.23.1",
+]

larkup-0.1.14/src/larkup/__init__.py

@@ -0,0 +1,27 @@
+from .client import LarkupClient, AsyncLarkupClient, LarkupError
+from .types import (
+    Document,
+    QueryRequest,
+    QueryHit,
+    QueryResponse,
+    PaginatedDocuments,
+    ScrapeRequest,
+    ScrapeResponse,
+    HealthResponse,
+    LarkupClientOptions,
+)
+
+__all__ = [
+    "LarkupClient",
+    "AsyncLarkupClient",
+    "LarkupError",
+    "Document",
+    "QueryRequest",
+    "QueryHit",
+    "QueryResponse",
+    "PaginatedDocuments",
+    "ScrapeRequest",
+    "ScrapeResponse",
+    "HealthResponse",
+    "LarkupClientOptions",
+]

larkup-0.1.14/src/larkup/client.py

@@ -0,0 +1,214 @@
+import os
+import httpx
+from typing import Optional, Union, Dict, Any
+from .types import (
+    Document,
+    PaginatedDocuments,
+    QueryRequest,
+    QueryResponse,
+    ScrapeResponse,
+    HealthResponse,
+    LarkupClientOptions,
+)
+
+class LarkupError(Exception):
+    def __init__(self, message: str, status_code: Optional[int] = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+class LarkupClient:
+    """Synchronous client for Larkup API."""
+    
+    def __init__(self, options: Optional[LarkupClientOptions] = None):
+        options = options or LarkupClientOptions()
+        
+        base_url = options.base_url or os.getenv("LARKUP_API_URL", "http://localhost:8080")
+        self.base_url = base_url.rstrip("/")
+        self.api_key = options.api_key or os.getenv("LARKUP_API_KEY")
+        self._client = httpx.Client(base_url=self.base_url)
+
+    def _get_headers(self) -> Dict[str, str]:
+        headers = {}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    def _handle_error(self, response: httpx.Response):
+        if not response.is_success:
+            error_msg = response.reason_phrase
+            try:
+                err_body = response.json()
+                if isinstance(err_body, dict) and "error" in err_body:
+                    error_msg = err_body["error"]
+            except Exception:
+                pass
+            raise LarkupError(f"Larkup API Error ({response.status_code}): {error_msg}", response.status_code)
+
+    def _request(self, method: str, path: str, **kwargs) -> Any:
+        headers = self._get_headers()
+        if "headers" in kwargs:
+            headers.update(kwargs.pop("headers"))
+            
+        response = self._client.request(method, path, headers=headers, **kwargs)
+        self._handle_error(response)
+        return response.json()
+
+    def health(self) -> HealthResponse:
+        """Health check"""
+        data = self._request("GET", "/health")
+        return HealthResponse(**data)
+
+    def query(self, request: Union[QueryRequest, str], top_k: Optional[int] = None) -> QueryResponse:
+        """Query the RAG knowledge base"""
+        if isinstance(request, str):
+            request_data = QueryRequest(query=request, topK=top_k)
+        else:
+            request_data = request
+            
+        data = self._request("POST", "/query", json=request_data.model_dump(exclude_none=True))
+        return QueryResponse(**data)
+
+    def list_documents(self, page: int = 1, limit: int = 20) -> PaginatedDocuments:
+        """List documents with pagination"""
+        data = self._request("GET", "/documents", params={"page": page, "limit": limit})
+        return PaginatedDocuments(**data)
+
+    def get_document(self, id: str) -> Document:
+        """Get a specific document by ID"""
+        data = self._request("GET", f"/documents/{id}")
+        return Document(**data)
+
+    def add_document(self, document: Document) -> Dict[str, Any]:
+        """Add a new document to the vector store"""
+        # We allow 'id' in Document to be optionally ignored by the server, 
+        # but to mirror JS we just send it as dict.
+        payload = document.model_dump(exclude_none=True)
+        if "id" in payload and not payload["id"]:
+            del payload["id"]
+            
+        data = self._request("POST", "/documents", json=payload)
+        return data
+
+    def update_document(self, id: str, document: Document) -> Dict[str, Any]:
+        """Update an existing document"""
+        payload = document.model_dump(exclude_none=True)
+        data = self._request("PUT", f"/documents/{id}", json=payload)
+        return data
+
+    def delete_document(self, id: str) -> Dict[str, Any]:
+        """Delete a document"""
+        data = self._request("DELETE", f"/documents/{id}")
+        return data
+
+    def scrape(self, url: str) -> ScrapeResponse:
+        """Scrape a URL and add it to the corpus"""
+        data = self._request("POST", "/scrape", json={"url": url})
+        return ScrapeResponse(**data)
+
+    def close(self):
+        """Close the underlying HTTP client"""
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+
+class AsyncLarkupClient:
+    """Asynchronous client for Larkup API."""
+    
+    def __init__(self, options: Optional[LarkupClientOptions] = None):
+        options = options or LarkupClientOptions()
+        
+        base_url = options.base_url or os.getenv("LARKUP_API_URL", "http://localhost:8080")
+        self.base_url = base_url.rstrip("/")
+        self.api_key = options.api_key or os.getenv("LARKUP_API_KEY")
+        self._client = httpx.AsyncClient(base_url=self.base_url)
+
+    def _get_headers(self) -> Dict[str, str]:
+        headers = {}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    def _handle_error(self, response: httpx.Response):
+        if not response.is_success:
+            error_msg = response.reason_phrase
+            try:
+                err_body = response.json()
+                if isinstance(err_body, dict) and "error" in err_body:
+                    error_msg = err_body["error"]
+            except Exception:
+                pass
+            raise LarkupError(f"Larkup API Error ({response.status_code}): {error_msg}", response.status_code)
+
+    async def _request(self, method: str, path: str, **kwargs) -> Any:
+        headers = self._get_headers()
+        if "headers" in kwargs:
+            headers.update(kwargs.pop("headers"))
+            
+        response = await self._client.request(method, path, headers=headers, **kwargs)
+        self._handle_error(response)
+        return response.json()
+
+    async def health(self) -> HealthResponse:
+        """Health check"""
+        data = await self._request("GET", "/health")
+        return HealthResponse(**data)
+
+    async def query(self, request: Union[QueryRequest, str], top_k: Optional[int] = None) -> QueryResponse:
+        """Query the RAG knowledge base"""
+        if isinstance(request, str):
+            request_data = QueryRequest(query=request, topK=top_k)
+        else:
+            request_data = request
+            
+        data = await self._request("POST", "/query", json=request_data.model_dump(exclude_none=True))
+        return QueryResponse(**data)
+
+    async def list_documents(self, page: int = 1, limit: int = 20) -> PaginatedDocuments:
+        """List documents with pagination"""
+        data = await self._request("GET", "/documents", params={"page": page, "limit": limit})
+        return PaginatedDocuments(**data)
+
+    async def get_document(self, id: str) -> Document:
+        """Get a specific document by ID"""
+        data = await self._request("GET", f"/documents/{id}")
+        return Document(**data)
+
+    async def add_document(self, document: Document) -> Dict[str, Any]:
+        """Add a new document to the vector store"""
+        payload = document.model_dump(exclude_none=True)
+        if "id" in payload and not payload["id"]:
+            del payload["id"]
+            
+        data = await self._request("POST", "/documents", json=payload)
+        return data
+
+    async def update_document(self, id: str, document: Document) -> Dict[str, Any]:
+        """Update an existing document"""
+        payload = document.model_dump(exclude_none=True)
+        data = await self._request("PUT", f"/documents/{id}", json=payload)
+        return data
+
+    async def delete_document(self, id: str) -> Dict[str, Any]:
+        """Delete a document"""
+        data = await self._request("DELETE", f"/documents/{id}")
+        return data
+
+    async def scrape(self, url: str) -> ScrapeResponse:
+        """Scrape a URL and add it to the corpus"""
+        data = await self._request("POST", "/scrape", json={"url": url})
+        return ScrapeResponse(**data)
+
+    async def close(self):
+        """Close the underlying HTTP client"""
+        await self._client.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()

larkup-0.1.14/src/larkup/types.py

@@ -0,0 +1,48 @@
+from typing import List, Optional
+from pydantic import BaseModel, Field
+
+class Document(BaseModel):
+    id: str
+    text: str
+    title: Optional[str] = None
+    url: Optional[str] = None
+    documentId: Optional[str] = None
+
+class QueryRequest(BaseModel):
+    query: str
+    topK: Optional[int] = None
+
+class QueryHit(BaseModel):
+    id: str
+    score: float
+    text: str
+    title: str
+    url: Optional[str] = None
+    documentId: str
+
+class QueryResponse(BaseModel):
+    query: str
+    hits: List[QueryHit]
+
+class PaginatedDocuments(BaseModel):
+    documents: List[Document]
+    total: int
+    page: int
+    limit: int
+    totalPages: int
+
+class ScrapeRequest(BaseModel):
+    url: str
+
+class ScrapeResponse(BaseModel):
+    success: bool
+    documentId: Optional[str] = None
+    error: Optional[str] = None
+
+class HealthResponse(BaseModel):
+    ok: bool
+    service: Optional[str] = None
+
+class LarkupClientOptions(BaseModel):
+    base_url: Optional[str] = None
+    api_key: Optional[str] = None