seltz 0.1.1__tar.gz → 0.1.3__tar.gz

seltz-0.1.3/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: seltz
+Version: 0.1.3
+Summary: Seltz Python SDK for AI-powered search
+Author-email: Seltz <support@seltz.ai>
+Project-URL: Homepage, https://seltz.ai
+Project-URL: Documentation, https://docs.seltz.ai
+Project-URL: Repository, https://github.com/seltz-ai/seltz-python-sdk
+Project-URL: Bug Tracker, https://github.com/seltz-ai/seltz-python-sdk/issues
+Keywords: search,ai,sdk,api
+Classifier: Development Status :: 4 - Beta
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: grpcio>=1.76.0
+Requires-Dist: protobuf<6.0
+
+# Seltz Python SDK
+
+The official Python SDK for the Seltz AI-powered search API.
+
+## Installation
+
+```bash
+pip install seltz
+```
+
+## Quick Start
+
+```python
+from seltz import Seltz
+
+# Initialize with API key
+client = Seltz(api_key="your-api-key")
+
+# Perform a search
+response = client.search("your search query")
+
+# Access results
+for document in response.documents:
+    print(f"URL: {document.url}")
+    print(f"Content: {document.content}")
+```
+
+## API Key
+
+Set your API key using one of these methods:
+
+1. **Environment variable** (recommended):
+   ```bash
+   export SELTZ_API_KEY="your-api-key"
+   ```
+
+2. **Direct parameter**:
+   ```python
+   client = Seltz(api_key="your-api-key")
+   ```
+
+## API Reference
+
+### `Seltz(api_key=None, endpoint="grpc.seltz.ai", insecure=False)`
+
+Creates a new Seltz client instance.
+
+**Parameters:**
+- `api_key` (str, optional): API key for authentication. Defaults to `SELTZ_API_KEY` environment variable.
+- `endpoint` (str): API endpoint. Defaults to "grpc.seltz.ai".
+- `insecure` (bool): Use insecure connection. Defaults to False.
+
+**Returns:** `Seltz` instance
+
+### `client.search(query, *, includes=None, context=None, profile=None)`
+
+Performs a search query.
+
+**Parameters:**
+- `query` (str): The search query text. Keep concise for best performance.
+- `includes` (Includes | int, optional): What to include in results.
+- `context` (str, optional): Additional context for the query. Include as much relevant information as feasible to improve search quality.
+- `profile` (str, optional): Search profile to use (contact support for available profiles).
+
+**Returns:** `SearchResult` with documents and helper methods.
+
+**Examples:**
+
+```python
+response = client.search("Python asyncio tutorial")
+
+# With Includes configuration
+from seltz import Includes
+response = client.search(
+    "Python tutorial",
+    includes=Includes(max_documents=10)
+)
+
+# Access results
+for doc in response:
+    print(f"URL: {doc.url}")
+    print(f"Content: {doc.content}")
+
+# Or use helper methods
+first_doc = response.first()
+all_urls = response.get_urls()
+```
+
+### `Includess`
+
+Configuration for what to include in search results.
+
+**Parameters:**
+- `max_documents` (int, optional): Maximum number of documents to return.
+
+**Constructor Pattern (simple cases):**
+```python
+from seltz import Includes
+
+# Simple constructor
+includes = Includes(max_documents=5)
+response = client.search("query", includes=includes)
+```
+
+**Fluent Builder Pattern (complex cases):**
+```python
+from seltz import Includes
+
+# Single field
+includes = Includes().max_documents(10)
+
+# Mixed approach
+includes = Includes(max_documents=5).max_documents(10)
+```
+
+### `SearchResult`
+
+Search result wrapper with helper methods.
+
+**Properties:**
+- `documents`: List of Document objects
+
+**Methods:**
+- `__len__()`: Get number of documents (`len(result)`)
+- `__iter__()`: Iterate over documents (`for doc in result:`)
+- `__getitem__(index)`: Get document by index (`result[0]`, `result[-1]`)
+- `first()`: Get first document (or None if empty)
+- `get_urls()`: Get list of all URLs
+- `get_contents()`: Get list of all contents
+- `to_dict()`: Convert to dictionary for JSON serialization
+
+**Example:**
+```python
+result = client.search("Python tutorial")
+
+print(f"Found {len(result)} documents")
+
+for doc in result:
+    print(doc.url)
+
+first = result.first()
+if first:
+    print(f"Top result: {first.url}")
+
+urls = result.get_urls()
+
+import json
+json_data = json.dumps(result.to_dict())
+```
+
+### `Document`
+
+Individual search result document.
+
+**Properties:**
+- `url`: Document URL (optional)
+- `content`: Document content (optional)
+
+**Methods:**
+- `has_url()`: Check if URL exists
+- `has_content()`: Check if content exists
+- `to_dict()`: Convert to dictionary
+
+**Example:**
+```python
+doc = result[0]
+
+if doc.has_url():
+    print(f"URL: {doc.url}")
+
+if doc.has_content():
+    print(f"Content: {doc.content[:100]}")
+
+doc_dict = doc.to_dict()
+```
+
+## Error Handling
+
+```python
+from seltz import (
+    Seltz,
+    SeltzConfigurationError,
+    SeltzAuthenticationError,
+    SeltzConnectionError,
+    SeltzAPIError,
+    SeltzTimeoutError,
+    SeltzRateLimitError,
+)
+
+try:
+    client = Seltz(api_key="your-api-key")
+    response = client.search("query")
+except SeltzConfigurationError as e:
+    print(f"Configuration error: {e}")
+except SeltzAuthenticationError as e:
+    print(f"Authentication error: {e}")
+except SeltzConnectionError as e:
+    print(f"Connection error: {e}")
+except SeltzTimeoutError as e:
+    print(f"Timeout error: {e}")
+except SeltzRateLimitError as e:
+    print(f"Rate limit error: {e}")
+except SeltzAPIError as e:
+    print(f"API error: {e}")
+```
+
+## Requirements
+
+- Python 3.8+
+- grpcio >= 1.76.0
+- protobuf < 6.0

seltz-0.1.3/README.md

@@ -0,0 +1,211 @@
+# Seltz Python SDK
+
+The official Python SDK for the Seltz AI-powered search API.
+
+## Installation
+
+```bash
+pip install seltz
+```
+
+## Quick Start
+
+```python
+from seltz import Seltz
+
+# Initialize with API key
+client = Seltz(api_key="your-api-key")
+
+# Perform a search
+response = client.search("your search query")
+
+# Access results
+for document in response.documents:
+    print(f"URL: {document.url}")
+    print(f"Content: {document.content}")
+```
+
+## API Key
+
+Set your API key using one of these methods:
+
+1. **Environment variable** (recommended):
+   ```bash
+   export SELTZ_API_KEY="your-api-key"
+   ```
+
+2. **Direct parameter**:
+   ```python
+   client = Seltz(api_key="your-api-key")
+   ```
+
+## API Reference
+
+### `Seltz(api_key=None, endpoint="grpc.seltz.ai", insecure=False)`
+
+Creates a new Seltz client instance.
+
+**Parameters:**
+- `api_key` (str, optional): API key for authentication. Defaults to `SELTZ_API_KEY` environment variable.
+- `endpoint` (str): API endpoint. Defaults to "grpc.seltz.ai".
+- `insecure` (bool): Use insecure connection. Defaults to False.
+
+**Returns:** `Seltz` instance
+
+### `client.search(query, *, includes=None, context=None, profile=None)`
+
+Performs a search query.
+
+**Parameters:**
+- `query` (str): The search query text. Keep concise for best performance.
+- `includes` (Includes | int, optional): What to include in results.
+- `context` (str, optional): Additional context for the query. Include as much relevant information as feasible to improve search quality.
+- `profile` (str, optional): Search profile to use (contact support for available profiles).
+
+**Returns:** `SearchResult` with documents and helper methods.
+
+**Examples:**
+
+```python
+response = client.search("Python asyncio tutorial")
+
+# With Includes configuration
+from seltz import Includes
+response = client.search(
+    "Python tutorial",
+    includes=Includes(max_documents=10)
+)
+
+# Access results
+for doc in response:
+    print(f"URL: {doc.url}")
+    print(f"Content: {doc.content}")
+
+# Or use helper methods
+first_doc = response.first()
+all_urls = response.get_urls()
+```
+
+### `Includess`
+
+Configuration for what to include in search results.
+
+**Parameters:**
+- `max_documents` (int, optional): Maximum number of documents to return.
+
+**Constructor Pattern (simple cases):**
+```python
+from seltz import Includes
+
+# Simple constructor
+includes = Includes(max_documents=5)
+response = client.search("query", includes=includes)
+```
+
+**Fluent Builder Pattern (complex cases):**
+```python
+from seltz import Includes
+
+# Single field
+includes = Includes().max_documents(10)
+
+# Mixed approach
+includes = Includes(max_documents=5).max_documents(10)
+```
+
+### `SearchResult`
+
+Search result wrapper with helper methods.
+
+**Properties:**
+- `documents`: List of Document objects
+
+**Methods:**
+- `__len__()`: Get number of documents (`len(result)`)
+- `__iter__()`: Iterate over documents (`for doc in result:`)
+- `__getitem__(index)`: Get document by index (`result[0]`, `result[-1]`)
+- `first()`: Get first document (or None if empty)
+- `get_urls()`: Get list of all URLs
+- `get_contents()`: Get list of all contents
+- `to_dict()`: Convert to dictionary for JSON serialization
+
+**Example:**
+```python
+result = client.search("Python tutorial")
+
+print(f"Found {len(result)} documents")
+
+for doc in result:
+    print(doc.url)
+
+first = result.first()
+if first:
+    print(f"Top result: {first.url}")
+
+urls = result.get_urls()
+
+import json
+json_data = json.dumps(result.to_dict())
+```
+
+### `Document`
+
+Individual search result document.
+
+**Properties:**
+- `url`: Document URL (optional)
+- `content`: Document content (optional)
+
+**Methods:**
+- `has_url()`: Check if URL exists
+- `has_content()`: Check if content exists
+- `to_dict()`: Convert to dictionary
+
+**Example:**
+```python
+doc = result[0]
+
+if doc.has_url():
+    print(f"URL: {doc.url}")
+
+if doc.has_content():
+    print(f"Content: {doc.content[:100]}")
+
+doc_dict = doc.to_dict()
+```
+
+## Error Handling
+
+```python
+from seltz import (
+    Seltz,
+    SeltzConfigurationError,
+    SeltzAuthenticationError,
+    SeltzConnectionError,
+    SeltzAPIError,
+    SeltzTimeoutError,
+    SeltzRateLimitError,
+)
+
+try:
+    client = Seltz(api_key="your-api-key")
+    response = client.search("query")
+except SeltzConfigurationError as e:
+    print(f"Configuration error: {e}")
+except SeltzAuthenticationError as e:
+    print(f"Authentication error: {e}")
+except SeltzConnectionError as e:
+    print(f"Connection error: {e}")
+except SeltzTimeoutError as e:
+    print(f"Timeout error: {e}")
+except SeltzRateLimitError as e:
+    print(f"Rate limit error: {e}")
+except SeltzAPIError as e:
+    print(f"API error: {e}")
+```
+
+## Requirements
+
+- Python 3.8+
+- grpcio >= 1.76.0
+- protobuf < 6.0

{seltz-0.1.1 → seltz-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "seltz"
-version = "0.1.1"
+version = "0.1.3"
 description = "Seltz Python SDK for AI-powered search"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -26,14 +26,14 @@ classifiers = [
 ]
 dependencies = [
     "grpcio>=1.76.0",
-    "protobuf>=6.33.1",
+    "protobuf<6.0",
 ]
 
 [project.urls]
 Homepage = "https://seltz.ai"
 Documentation = "https://docs.seltz.ai"
-Repository = "https://github.com/seltz-ai/seltz-py"
-"Bug Tracker" = "https://github.com/seltz-ai/seltz-py/issues"
+Repository = "https://github.com/seltz-ai/seltz-python-sdk"
+"Bug Tracker" = "https://github.com/seltz-ai/seltz-python-sdk/issues"
 
 [tool.setuptools.packages.find]
 where = ["src"]
@@ -57,5 +57,5 @@ split-on-trailing-comma = true
 
 [tool.ruff]
 exclude = [
-    "src/seltz/seltz_public_api/"
+    "src/seltz_public_api/"
 ]

{seltz-0.1.1 → seltz-0.1.3}/src/seltz/__init__.py

@@ -10,9 +10,16 @@ from .exceptions import (
     SeltzTimeoutError,
 )
 from .seltz import Seltz
+from .types import Document, Includes, SearchResult
 
 __all__ = [
+    # Main client
     "Seltz",
+    # Types
+    "Includes",
+    "SearchResult",
+    "Document",
+    # Exceptions
     "SeltzError",
     "SeltzConfigurationError",
     "SeltzAuthenticationError",

{seltz-0.1.1 → seltz-0.1.3}/src/seltz/client.py

@@ -1,11 +1,12 @@
 import grpc
+from typing import Optional
 
 
 class SeltzClient:
     """Low-level gRPC client for Seltz API."""
 
     def __init__(
-        self, endpoint: str, api_key: str | None = None, insecure: bool = False
+        self, endpoint: str, api_key: Optional[str] = None, insecure: bool = False
     ):
         """Initialize the Seltz gRPC client.
 

seltz-0.1.3/src/seltz/seltz.py

@@ -0,0 +1,79 @@
+import os
+from typing import Optional
+
+from .client import SeltzClient
+from .exceptions import SeltzConfigurationError
+from .services.search_service import SearchService
+from .types import Includes, SearchResult
+
+
+class Seltz:
+    """Main Seltz SDK client for interacting with the Seltz API."""
+
+    _ENDPOINT: str = "grpc.seltz.ai"
+
+    def __init__(
+        self,
+        api_key: Optional[str] = os.environ.get("SELTZ_API_KEY"),
+        endpoint: str = _ENDPOINT,
+        insecure: bool = False,
+    ):
+        """Initialize the Seltz client.
+
+        Args:
+            api_key: API key for authentication. If None, will try to read from SELTZ_API_KEY environment variable
+            endpoint: The API endpoint to connect to (default: grpc.seltz.ai)
+            insecure: Whether to use insecure connection (default: False)
+
+        Returns:
+            Seltz: A new Seltz client instance
+
+        Raises:
+            SeltzConfigurationError: If no API key is provided
+        """
+        if api_key is None:
+            raise SeltzConfigurationError("No API key provided")
+        self._client = SeltzClient(
+            endpoint=endpoint, api_key=api_key, insecure=insecure
+        )
+        self._search = SearchService(self._client.channel, self._client.api_key)
+
+    def search(
+        self,
+        query: str,
+        *,
+        includes: Optional[Includes] = None,
+        context: Optional[str] = None,
+        profile: Optional[str] = None,
+    ) -> SearchResult:
+        """Perform a search query.
+
+        This method searches using the Seltz AI-powered search engine. You can
+        customize the search behavior using optional parameters.
+
+        Args:
+            query: The search query string. Keep this concise for best performance.
+            includes: Configuration for what to include in results. If not specified
+                server defaults are used.
+            context: Additional context for the query. Include as much relevant
+                information as feasible to improve search quality. For example,
+                "user is looking for Python documentation for beginners".
+            profile: Search profile to use. Different profiles may use different
+                ranking algorithms or have different data source preferences.
+
+        Returns:
+            SearchResult: Search results containing documents and metadata.
+
+        Raises:
+            SeltzAuthenticationError: If API key is invalid
+            SeltzConnectionError: If connection to API fails
+            SeltzTimeoutError: If request times out
+            SeltzRateLimitError: If rate limit is exceeded
+            SeltzAPIError: For other API errors
+        """
+        return self._search.search(
+            query=query,
+            includes=includes,
+            context=context,
+            profile=profile,
+        )

{seltz-0.1.1 → seltz-0.1.3}/src/seltz/services/search_service.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 import grpc
 
 from ..exceptions import (
@@ -7,7 +9,8 @@ from ..exceptions import (
     SeltzRateLimitError,
     SeltzTimeoutError,
 )
-from . import Includes, SearchRequest, SearchResponse, SeltzServiceStub
+from ..types import Includes, SearchResult
+from . import SearchRequest, SeltzServiceStub
 
 
 class SearchService:
@@ -23,28 +26,46 @@ class SearchService:
         self._stub = SeltzServiceStub(channel)
         self._api_key = api_key
 
-    def search(self, query: str, max_documents: int = 10) -> SearchResponse:
+    def search(
+        self,
+        query: str,
+        *,
+        includes: Optional[Includes] = None,
+        context: Optional[str] = None,
+        profile: Optional[str] = None,
+    ) -> SearchResult:
         """Perform a search query.
 
         Args:
             query: The search query string
-            max_documents: Maximum number of documents to return (default: 10)
+            includes: Either an Includes object
+            context: Additional context for the query
+            profile: Search profile to use
 
         Returns:
-            SearchResponse containing the search results
+            SearchResult: Wrapped search response with helper methods
 
         Raises:
-            grpc.RpcError: If the gRPC call fails
+            SeltzAuthenticationError: If authentication fails
+            SeltzConnectionError: If connection fails
+            SeltzTimeoutError: If request times out
+            SeltzRateLimitError: If rate limit exceeded
+            SeltzAPIError: For other API errors
         """
-        includes = Includes(max_documents=max_documents)
-        req = SearchRequest(query=query, includes=includes)
+        req = SearchRequest(
+            query=query,
+            includes=includes._to_protobuf() if includes is not None else None,
+            context=context,
+            profile=profile,
+            api_key=self._api_key,
+        )
 
         metadata = []
         if self._api_key:
             metadata.append(("authorization", f"Bearer {self._api_key}"))
 
         try:
-            return self._stub.Search(req, metadata=metadata, timeout=30)
+            return SearchResult(self._stub.Search(req, metadata=metadata, timeout=30))
         except grpc.RpcError as e:
             if e.code() == grpc.StatusCode.UNAUTHENTICATED:
                 raise SeltzAuthenticationError(