aksearch 0.1.0__tar.gz

aksearch-0.1.0/.gitignore

@@ -0,0 +1,68 @@
+# The directory Mix will write compiled artifacts to.
+/_build/
+
+# If you run "mix test --cover", coverage assets end up here.
+/cover/
+
+# The directory Mix downloads your dependencies sources to.
+/deps/
+
+# Where third-party dependencies like ExDoc output generated docs.
+/doc/
+
+# Temporary files, for example, from tests.
+/tmp/
+
+# If the VM crashes, it generates a dump, let's ignore it too.
+erl_crash.dump
+
+# Also ignore archive artifacts (built via "mix archive.build").
+*.ez
+
+# Ignore package tarball (built via "mix hex.build").
+aksearch-*.tar
+
+priv/repo/*.db
+priv/repo/*.db-shm
+priv/repo/*.db-wal
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+env/
+venv/
+ENV/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Editor & OS
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment variables & secrets
+.env
+.env.*
+!.env.example
+*.env
+

aksearch-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.5
+Name: aksearch
+Version: 0.1.0
+Summary: Official Python SDK and LangChain/LlamaIndex integration for Aksearch - Fast Korean Search with Clean Markdown Extraction
+Author: Aksearch Team
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: all
+Requires-Dist: langchain-core>=0.1.0; extra == 'all'
+Requires-Dist: llama-index-core>=0.10.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
+Provides-Extra: llama-index
+Requires-Dist: llama-index-core>=0.10.0; extra == 'llama-index'
+Description-Content-Type: text/markdown
+
+# Aksearch Python SDK
+
+Official Python client and LangChain / LlamaIndex integrations for **Aksearch** — a high-performance search aggregation engine tailored for Korean and global web queries with on-demand Clean Markdown extraction.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install aksearch
+```
+
+For LangChain or LlamaIndex support:
+```bash
+pip install "aksearch[langchain]"
+# or
+pip install "aksearch[llama-index]"
+```
+
+---
+
+## 🚀 Quickstart
+
+### 1. Basic Search
+
+```python
+from aksearch import AksearchClient
+
+client = AksearchClient(api_key="YOUR_AKSEARCH_API_KEY")
+
+# Basic meta search (Title, URL, Snippet)
+response = client.search("엘릭서 기본 문법")
+
+for item in response:
+    print(f"[{item.source}] {item.title} -> {item.url}")
+```
+
+### 2. LLM-Friendly Clean Markdown Extraction
+
+Set `include_content=True` to receive cleaned, boilerplate-free Markdown text extracted from the top authoritative pages:
+
+```python
+response = client.search(
+    "엘릭서 기본 문법",
+    include_content=True,
+    max_content_items=3  # Fetch full clean markdown for top 3 URLs
+)
+
+for item in response:
+    print(f"Title: {item.title}")
+    if item.content:
+        print(f"Clean Content:\n{item.content[:300]}...\n")
+```
+
+---
+
+## 🦜 LangChain Integration
+
+### As a Retriever (RAG Pipelines)
+
+```python
+from aksearch.integrations import AksearchRetriever
+
+retriever = AksearchRetriever(
+    api_key="YOUR_AKSEARCH_API_KEY",
+    include_content=True,
+    max_content_items=3
+)
+
+# Returns a list of langchain_core.documents.Document
+docs = retriever.invoke("최신 인공지능 트렌드")
+print(docs[0].page_content)
+print(docs[0].metadata["source"])
+```
+
+### As an Agent Tool
+
+```python
+from aksearch.integrations import AksearchSearchTool
+
+search_tool = AksearchSearchTool(api_key="YOUR_AKSEARCH_API_KEY")
+
+# Pass to any LangChain ReAct or Tool-calling agent:
+# tools = [search_tool]
+# agent = create_react_agent(model, tools, prompt)
+```
+
+---
+
+## 🦙 LlamaIndex Integration
+
+```python
+from aksearch.integrations import AksearchReader
+from llama_index.core import VectorStoreIndex
+
+reader = AksearchReader(api_key="YOUR_AKSEARCH_API_KEY")
+documents = reader.load_data("한국 역사 요약", include_content=True)
+
+index = VectorStoreIndex.from_documents(documents)
+query_engine = index.as_query_engine()
+response = query_engine.query("조선 건국 과정 요약해줘")
+print(response)
+```
+
+---
+
+## ⚙️ Environment Variables
+
+- `AKSEARCH_API_KEY`: Fallback API key when not explicitly passed to the client.
+- `AKSEARCH_BASE_URL`: Custom API endpoint (default: `http://localhost:4000/api`).

aksearch-0.1.0/README.md

@@ -0,0 +1,110 @@
+# Aksearch Python SDK
+
+Official Python client and LangChain / LlamaIndex integrations for **Aksearch** — a high-performance search aggregation engine tailored for Korean and global web queries with on-demand Clean Markdown extraction.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install aksearch
+```
+
+For LangChain or LlamaIndex support:
+```bash
+pip install "aksearch[langchain]"
+# or
+pip install "aksearch[llama-index]"
+```
+
+---
+
+## 🚀 Quickstart
+
+### 1. Basic Search
+
+```python
+from aksearch import AksearchClient
+
+client = AksearchClient(api_key="YOUR_AKSEARCH_API_KEY")
+
+# Basic meta search (Title, URL, Snippet)
+response = client.search("엘릭서 기본 문법")
+
+for item in response:
+    print(f"[{item.source}] {item.title} -> {item.url}")
+```
+
+### 2. LLM-Friendly Clean Markdown Extraction
+
+Set `include_content=True` to receive cleaned, boilerplate-free Markdown text extracted from the top authoritative pages:
+
+```python
+response = client.search(
+    "엘릭서 기본 문법",
+    include_content=True,
+    max_content_items=3  # Fetch full clean markdown for top 3 URLs
+)
+
+for item in response:
+    print(f"Title: {item.title}")
+    if item.content:
+        print(f"Clean Content:\n{item.content[:300]}...\n")
+```
+
+---
+
+## 🦜 LangChain Integration
+
+### As a Retriever (RAG Pipelines)
+
+```python
+from aksearch.integrations import AksearchRetriever
+
+retriever = AksearchRetriever(
+    api_key="YOUR_AKSEARCH_API_KEY",
+    include_content=True,
+    max_content_items=3
+)
+
+# Returns a list of langchain_core.documents.Document
+docs = retriever.invoke("최신 인공지능 트렌드")
+print(docs[0].page_content)
+print(docs[0].metadata["source"])
+```
+
+### As an Agent Tool
+
+```python
+from aksearch.integrations import AksearchSearchTool
+
+search_tool = AksearchSearchTool(api_key="YOUR_AKSEARCH_API_KEY")
+
+# Pass to any LangChain ReAct or Tool-calling agent:
+# tools = [search_tool]
+# agent = create_react_agent(model, tools, prompt)
+```
+
+---
+
+## 🦙 LlamaIndex Integration
+
+```python
+from aksearch.integrations import AksearchReader
+from llama_index.core import VectorStoreIndex
+
+reader = AksearchReader(api_key="YOUR_AKSEARCH_API_KEY")
+documents = reader.load_data("한국 역사 요약", include_content=True)
+
+index = VectorStoreIndex.from_documents(documents)
+query_engine = index.as_query_engine()
+response = query_engine.query("조선 건국 과정 요약해줘")
+print(response)
+```
+
+---
+
+## ⚙️ Environment Variables
+
+- `AKSEARCH_API_KEY`: Fallback API key when not explicitly passed to the client.
+- `AKSEARCH_BASE_URL`: Custom API endpoint (default: `http://localhost:4000/api`).

aksearch-0.1.0/aksearch/__init__.py

@@ -0,0 +1,27 @@
+from .client import AksearchClient, AsyncAksearchClient
+from .models import SearchResponse, SearchResult
+from .exceptions import (
+    AksearchError,
+    AuthenticationError,
+    RateLimitError,
+    BadRequestError,
+    SearchError,
+)
+from .integrations import AksearchRetriever, AksearchSearchTool, AksearchReader
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AksearchClient",
+    "AsyncAksearchClient",
+    "SearchResponse",
+    "SearchResult",
+    "AksearchError",
+    "AuthenticationError",
+    "RateLimitError",
+    "BadRequestError",
+    "SearchError",
+    "AksearchRetriever",
+    "AksearchSearchTool",
+    "AksearchReader",
+]

aksearch-0.1.0/aksearch/client.py

@@ -0,0 +1,185 @@
+import os
+from typing import Optional, Dict, Any
+import httpx
+
+from .exceptions import (
+    AuthenticationError,
+    RateLimitError,
+    BadRequestError,
+    SearchError,
+    AksearchError,
+)
+from .models import SearchResponse
+
+
+class BaseClient:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 10.0,
+    ):
+        self.api_key = api_key or os.environ.get("AKSEARCH_API_KEY")
+        if not self.api_key:
+            raise AuthenticationError(
+                "Aksearch API key is required. Pass `api_key='...'` or set the AKSEARCH_API_KEY environment variable."
+            )
+
+        raw_base_url = (
+            base_url
+            or os.environ.get("AKSEARCH_BASE_URL")
+            or "http://localhost:4000/api"
+        )
+        self.base_url = raw_base_url.rstrip("/") + "/"
+        self.timeout = timeout
+
+    def _build_headers(self) -> Dict[str, str]:
+        return {
+            "x-api-key": self.api_key,
+            "accept": "application/json",
+            "user-agent": "aksearch-python/0.1.0",
+        }
+
+    def _build_params(
+        self,
+        query: str,
+        include_content: bool,
+        max_content_items: int,
+        **extra_params,
+    ) -> Dict[str, Any]:
+        params = {
+            "q": query,
+            "include_content": "true" if include_content else "false",
+            "max_content_items": str(max(0, min(10, max_content_items))),
+        }
+        params.update(extra_params)
+        return params
+
+    def _handle_response(self, response: httpx.Response) -> Dict[str, Any]:
+        if response.status_code == 200:
+            return response.json()
+        elif response.status_code == 401:
+            raise AuthenticationError(
+                f"Unauthorized: {response.text or 'Invalid or missing API key.'}"
+            )
+        elif response.status_code == 429:
+            raise RateLimitError(
+                f"Rate limit exceeded: {response.text or 'Monthly quota reached.'}"
+            )
+        elif response.status_code == 400:
+            raise BadRequestError(f"Bad request: {response.text}")
+        else:
+            raise SearchError(
+                f"Search request failed with status {response.status_code}: {response.text}"
+            )
+
+
+class AksearchClient(BaseClient):
+    """Synchronous client for Aksearch API."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 10.0,
+        transport: Optional[httpx.BaseTransport] = None,
+    ):
+        super().__init__(api_key=api_key, base_url=base_url, timeout=timeout)
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers=self._build_headers(),
+            timeout=self.timeout,
+            transport=transport,
+        )
+
+    def close(self):
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+    def search(
+        self,
+        query: str,
+        include_content: bool = False,
+        max_content_items: int = 3,
+        **extra_params,
+    ) -> SearchResponse:
+        """
+        Execute a search query across Korean search engines with optional clean markdown extraction.
+
+        Args:
+            query: The search term or question.
+            include_content: When True, fetches and extracts clean markdown body text for top URLs.
+            max_content_items: Number of top results to enrich with full clean content (default: 3, max: 10).
+            **extra_params: Additional query parameters.
+
+        Returns:
+            SearchResponse: Parsed results including title, url, snippet, and clean markdown content.
+        """
+        params = self._build_params(
+            query=query,
+            include_content=include_content,
+            max_content_items=max_content_items,
+            **extra_params,
+        )
+
+        try:
+            response = self._client.get("search", params=params)
+            data = self._handle_response(response)
+            return SearchResponse.from_dict(data)
+        except httpx.RequestError as exc:
+            raise AksearchError(f"Network error during search: {exc}") from exc
+
+
+class AsyncAksearchClient(BaseClient):
+    """Asynchronous client for Aksearch API."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 10.0,
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+    ):
+        super().__init__(api_key=api_key, base_url=base_url, timeout=timeout)
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers=self._build_headers(),
+            timeout=self.timeout,
+            transport=transport,
+        )
+
+    async def close(self):
+        await self._client.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()
+
+    async def search(
+        self,
+        query: str,
+        include_content: bool = False,
+        max_content_items: int = 3,
+        **extra_params,
+    ) -> SearchResponse:
+        """Asynchronously execute a search query."""
+        params = self._build_params(
+            query=query,
+            include_content=include_content,
+            max_content_items=max_content_items,
+            **extra_params,
+        )
+
+        try:
+            response = await self._client.get("search", params=params)
+            data = self._handle_response(response)
+            return SearchResponse.from_dict(data)
+        except httpx.RequestError as exc:
+            raise AksearchError(f"Network error during search: {exc}") from exc

aksearch-0.1.0/aksearch/exceptions.py

@@ -0,0 +1,23 @@
+class AksearchError(Exception):
+    """Base exception for all Aksearch SDK errors."""
+    pass
+
+
+class AuthenticationError(AksearchError):
+    """Raised when API key is missing, invalid, or unauthorized."""
+    pass
+
+
+class RateLimitError(AksearchError):
+    """Raised when the plan's search or API call limit is reached."""
+    pass
+
+
+class BadRequestError(AksearchError):
+    """Raised when request parameters are invalid (e.g. empty query)."""
+    pass
+
+
+class SearchError(AksearchError):
+    """Raised when the search engine backend encounters an internal error."""
+    pass

aksearch-0.1.0/aksearch/integrations/__init__.py

@@ -0,0 +1,4 @@
+from .langchain import AksearchRetriever, AksearchSearchTool
+from .llama_index import AksearchReader
+
+__all__ = ["AksearchRetriever", "AksearchSearchTool", "AksearchReader"]

aksearch-0.1.0/aksearch/integrations/langchain.py

@@ -0,0 +1,129 @@
+from typing import List, Optional, Any, Dict
+from ..client import AksearchClient, AsyncAksearchClient
+from ..models import SearchResponse
+
+
+class AksearchRetriever:
+    """
+    LangChain-compatible Retriever for Aksearch.
+
+    Usage:
+        retriever = AksearchRetriever(api_key="...", include_content=True)
+        docs = retriever.invoke("엘릭서 기본 문법")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        include_content: bool = True,
+        max_content_items: int = 3,
+        client: Optional[AksearchClient] = None,
+        async_client: Optional[AsyncAksearchClient] = None,
+    ):
+        self.include_content = include_content
+        self.max_content_items = max_content_items
+        self.client = client or AksearchClient(api_key=api_key, base_url=base_url)
+        self._async_client = async_client
+
+    def _to_langchain_doc(self, result):
+        try:
+            from langchain_core.documents import Document
+        except ImportError:
+            # Fallback lightweight Document representation if langchain_core is not installed
+            class Document:
+                def __init__(self, page_content: str, metadata: dict):
+                    self.page_content = page_content
+                    self.metadata = metadata
+
+                def __repr__(self):
+                    return f"Document(page_content={self.page_content[:50]!r}..., metadata={self.metadata})"
+
+        text = result.content or result.snippet or result.title
+        metadata = {
+            "title": result.title,
+            "source": result.url,
+            "url": result.url,
+            "score": result.score,
+            "engine": result.source,
+            **result.metadata,
+        }
+        return Document(page_content=text, metadata=metadata)
+
+    def get_relevant_documents(self, query: str) -> List[Any]:
+        response: SearchResponse = self.client.search(
+            query=query,
+            include_content=self.include_content,
+            max_content_items=self.max_content_items,
+        )
+        return [self._to_langchain_doc(r) for r in response.results]
+
+    def invoke(self, query: str, config: Optional[Dict[str, Any]] = None) -> List[Any]:
+        """LangChain Runnable protocol compatibility."""
+        return self.get_relevant_documents(query)
+
+    async def aget_relevant_documents(self, query: str) -> List[Any]:
+        if not self._async_client:
+            self._async_client = AsyncAksearchClient(
+                api_key=self.client.api_key, base_url=self.client.base_url
+            )
+
+        response: SearchResponse = await self._async_client.search(
+            query=query,
+            include_content=self.include_content,
+            max_content_items=self.max_content_items,
+        )
+        return [self._to_langchain_doc(r) for r in response.results]
+
+    async def ainvoke(self, query: str, config: Optional[Dict[str, Any]] = None) -> List[Any]:
+        """LangChain Async Runnable protocol compatibility."""
+        return await self.aget_relevant_documents(query)
+
+
+class AksearchSearchTool:
+    """
+    LangChain agent tool for searching the web and retrieving clean markdown content.
+    """
+
+    name: str = "aksearch"
+    description: str = (
+        "Search the Korean and global web for real-time information, news, blogs, and articles. "
+        "Returns clean markdown content extracted from top authoritative websites."
+    )
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        include_content: bool = True,
+        max_content_items: int = 3,
+    ):
+        self.client = AksearchClient(api_key=api_key, base_url=base_url)
+        self.include_content = include_content
+        self.max_content_items = max_content_items
+
+    def run(self, query: str) -> str:
+        """Runs the search and formats results into an LLM-friendly context block."""
+        response = self.client.search(
+            query=query,
+            include_content=self.include_content,
+            max_content_items=self.max_content_items,
+        )
+
+        if not response.results:
+            return f"No search results found for query: {query}"
+
+        output_parts = []
+        for idx, item in enumerate(response.results, 1):
+            text_body = item.content or item.snippet or "No content available."
+            output_parts.append(
+                f"### [{idx}] {item.title}\n"
+                f"- **URL**: {item.url}\n"
+                f"- **Source**: {item.source or 'web'}\n\n"
+                f"{text_body}\n"
+            )
+
+        return "\n---\n".join(output_parts)
+
+    def __call__(self, query: str) -> str:
+        return self.run(query)

aksearch-0.1.0/aksearch/integrations/llama_index.py

@@ -0,0 +1,60 @@
+from typing import List, Optional, Any
+from ..client import AksearchClient
+from ..models import SearchResponse
+
+
+class AksearchReader:
+    """
+    LlamaIndex-compatible Reader for Aksearch.
+
+    Usage:
+        reader = AksearchReader(api_key="...")
+        documents = reader.load_data("한국 최신 뉴스", include_content=True)
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        client: Optional[AksearchClient] = None,
+    ):
+        self.client = client or AksearchClient(api_key=api_key, base_url=base_url)
+
+    def _to_llama_doc(self, result):
+        try:
+            from llama_index.core import Document
+        except ImportError:
+            # Fallback lightweight representation if llama_index is not installed
+            class Document:
+                def __init__(self, text: str, extra_info: dict):
+                    self.text = text
+                    self.extra_info = extra_info
+
+                def __repr__(self):
+                    return f"Document(text={self.text[:50]!r}..., extra_info={self.extra_info})"
+
+        text = result.content or result.snippet or result.title
+        extra_info = {
+            "title": result.title,
+            "url": result.url,
+            "source": result.source,
+            "score": result.score,
+            **result.metadata,
+        }
+        return Document(text=text, extra_info=extra_info)
+
+    def load_data(
+        self,
+        query: str,
+        include_content: bool = True,
+        max_content_items: int = 3,
+        **kwargs,
+    ) -> List[Any]:
+        """Loads search results as LlamaIndex Documents."""
+        response: SearchResponse = self.client.search(
+            query=query,
+            include_content=include_content,
+            max_content_items=max_content_items,
+            **kwargs,
+        )
+        return [self._to_llama_doc(r) for r in response.results]

aksearch-0.1.0/aksearch/models.py

@@ -0,0 +1,73 @@
+from dataclasses import dataclass, field
+from typing import List, Optional, Dict, Any
+
+
+@dataclass
+class SearchResult:
+    """Represents an individual search result, optionally enriched with clean markdown content."""
+    title: str
+    url: str
+    snippet: Optional[str] = None
+    content: Optional[str] = None
+    source: Optional[str] = None
+    score: Optional[float] = None
+    duplicate_sources: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "SearchResult":
+        return cls(
+            title=data.get("title", ""),
+            url=data.get("url", ""),
+            snippet=data.get("snippet"),
+            content=data.get("content"),
+            source=data.get("source"),
+            score=data.get("score"),
+            duplicate_sources=data.get("duplicate_sources", []),
+            metadata=data.get("metadata", {})
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "title": self.title,
+            "url": self.url,
+            "snippet": self.snippet,
+            "content": self.content,
+            "source": self.source,
+            "score": self.score,
+            "duplicate_sources": self.duplicate_sources,
+            "metadata": self.metadata
+        }
+
+
+@dataclass
+class SearchResponse:
+    """Represents the complete response from an Aksearch query."""
+    query: str
+    results: List[SearchResult]
+    counts: Dict[str, int] = field(default_factory=dict)
+    cache_status: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "SearchResponse":
+        results = [
+            SearchResult.from_dict(item)
+            for item in data.get("results", [])
+        ]
+        return cls(
+            query=data.get("query", ""),
+            results=results,
+            counts=data.get("counts", {}),
+            cache_status=data.get("cache_status"),
+            raw=data
+        )
+
+    def __iter__(self):
+        return iter(self.results)
+
+    def __len__(self):
+        return len(self.results)
+
+    def __getitem__(self, index):
+        return self.results[index]

aksearch-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aksearch"
+version = "0.1.0"
+description = "Official Python SDK and LangChain/LlamaIndex integration for Aksearch - Fast Korean Search with Clean Markdown Extraction"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+    { name = "Aksearch Team" }
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
+]
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[project.optional-dependencies]
+langchain = [
+    "langchain-core>=0.1.0",
+]
+llama-index = [
+    "llama-index-core>=0.10.0",
+]
+all = [
+    "langchain-core>=0.1.0",
+    "llama-index-core>=0.10.0",
+]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+]

aksearch-0.1.0/tests/test_client.py

@@ -0,0 +1,130 @@
+import os
+import json
+import httpx
+import pytest
+
+from aksearch import (
+    AksearchClient,
+    AsyncAksearchClient,
+    AuthenticationError,
+    RateLimitError,
+    BadRequestError,
+)
+from aksearch.integrations import AksearchRetriever, AksearchSearchTool, AksearchReader
+
+
+@pytest.fixture
+def mock_search_response():
+    return {
+        "query": "elixir",
+        "results": [
+            {
+                "title": "Elixir Programming",
+                "url": "https://elixir-lang.org",
+                "snippet": "Elixir is a dynamic, functional language.",
+                "content": "# Elixir Overview\n\nElixir is built on the BEAM VM.",
+                "source": "google",
+                "score": 100,
+                "metadata": {"freshness": 10}
+            }
+        ],
+        "counts": {"google": 1},
+        "cache_status": "fresh"
+    }
+
+
+def test_missing_api_key_raises_auth_error(monkeypatch):
+    monkeypatch.delenv("AKSEARCH_API_KEY", raising=False)
+    with pytest.raises(AuthenticationError):
+        AksearchClient()
+
+
+def test_search_success(mock_search_response):
+    def handler(request: httpx.Request):
+        assert request.url.path == "/api/search"
+        assert request.url.params["q"] == "elixir"
+        assert request.url.params["include_content"] == "true"
+        assert request.url.params["max_content_items"] == "3"
+        assert request.headers["x-api-key"] == "test_key"
+        return httpx.Response(200, json=mock_search_response)
+
+    transport = httpx.MockTransport(handler)
+    client = AksearchClient(api_key="test_key", transport=transport)
+
+    response = client.search("elixir", include_content=True, max_content_items=3)
+
+    assert response.query == "elixir"
+    assert len(response) == 1
+    item = response[0]
+    assert item.title == "Elixir Programming"
+    assert item.url == "https://elixir-lang.org"
+    assert item.content == "# Elixir Overview\n\nElixir is built on the BEAM VM."
+    assert item.source == "google"
+
+
+def test_error_status_codes():
+    transport_401 = httpx.MockTransport(lambda _: httpx.Response(401, text="Invalid API key"))
+    client = AksearchClient(api_key="bad_key", transport=transport_401)
+    with pytest.raises(AuthenticationError):
+        client.search("test")
+
+    transport_429 = httpx.MockTransport(lambda _: httpx.Response(429, text="Monthly quota reached"))
+    client = AksearchClient(api_key="test_key", transport=transport_429)
+    with pytest.raises(RateLimitError):
+        client.search("test")
+
+    transport_400 = httpx.MockTransport(lambda _: httpx.Response(400, text="Empty query"))
+    client = AksearchClient(api_key="test_key", transport=transport_400)
+    with pytest.raises(BadRequestError):
+        client.search("")
+
+
+@pytest.mark.asyncio
+async def test_async_search(mock_search_response):
+    def handler(request: httpx.Request):
+        return httpx.Response(200, json=mock_search_response)
+
+    transport = httpx.MockTransport(handler)
+    async with AsyncAksearchClient(api_key="test_key", transport=transport) as client:
+        response = await client.search("elixir")
+        assert len(response) == 1
+        assert response[0].title == "Elixir Programming"
+
+
+def test_langchain_retriever(mock_search_response):
+    transport = httpx.MockTransport(lambda _: httpx.Response(200, json=mock_search_response))
+    client = AksearchClient(api_key="test_key", transport=transport)
+
+    retriever = AksearchRetriever(client=client, include_content=True)
+    docs = retriever.invoke("elixir")
+
+    assert len(docs) == 1
+    doc = docs[0]
+    assert doc.page_content == "# Elixir Overview\n\nElixir is built on the BEAM VM."
+    assert doc.metadata["title"] == "Elixir Programming"
+    assert doc.metadata["source"] == "https://elixir-lang.org"
+
+
+def test_langchain_search_tool(mock_search_response):
+    transport = httpx.MockTransport(lambda _: httpx.Response(200, json=mock_search_response))
+    tool = AksearchSearchTool(api_key="test_key", base_url="http://localhost:4000/api")
+    tool.client._client = httpx.Client(base_url="http://localhost:4000/api/", transport=transport)
+
+    output = tool.run("elixir")
+    assert "### [1] Elixir Programming" in output
+    assert "https://elixir-lang.org" in output
+    assert "Elixir is built on the BEAM VM." in output
+
+
+def test_llama_index_reader(mock_search_response):
+    transport = httpx.MockTransport(lambda _: httpx.Response(200, json=mock_search_response))
+    client = AksearchClient(api_key="test_key", transport=transport)
+
+    reader = AksearchReader(client=client)
+    docs = reader.load_data("elixir", include_content=True)
+
+    assert len(docs) == 1
+    doc = docs[0]
+    assert doc.text == "# Elixir Overview\n\nElixir is built on the BEAM VM."
+    assert doc.extra_info["title"] == "Elixir Programming"
+    assert doc.extra_info["url"] == "https://elixir-lang.org"