seltz 0.1.2__tar.gz → 0.1.3__tar.gz

{seltz-0.1.2 → seltz-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: seltz
-Version: 0.1.2
+Version: 0.1.3
 Summary: Seltz Python SDK for AI-powered search
 Author-email: Seltz <support@seltz.ai>
 Project-URL: Homepage, https://seltz.ai
@@ -21,7 +21,7 @@ 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.33.1
+Requires-Dist: protobuf<6.0
 
 # Seltz Python SDK
 
@@ -77,15 +77,127 @@ Creates a new Seltz client instance.
 
 **Returns:** `Seltz` instance
 
-### `client.search(text, max_documents=10)`
+### `client.search(query, *, includes=None, context=None, profile=None)`
 
 Performs a search query.
 
 **Parameters:**
-- `text` (str): The search query text.
-- `max_documents` (int): Maximum number of documents to return. Defaults to 10.
+- `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:** `SearchResponse` with a `documents` field containing search results.
+**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
 
@@ -121,4 +233,4 @@ except SeltzAPIError as e:
 
 - Python 3.8+
 - grpcio >= 1.76.0
-- protobuf >= 6.33.1
+- 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.2 → seltz-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "seltz"
-version = "0.1.2"
+version = "0.1.3"
 description = "Seltz Python SDK for AI-powered search"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -26,7 +26,7 @@ classifiers = [
 ]
 dependencies = [
     "grpcio>=1.76.0",
-    "protobuf>=6.33.1",
+    "protobuf<6.0",
 ]
 
 [project.urls]
@@ -57,5 +57,5 @@ split-on-trailing-comma = true
 
 [tool.ruff]
 exclude = [
-    "src/seltz/seltz_public_api/"
+    "src/seltz_public_api/"
 ]

{seltz-0.1.2 → 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.2 → 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.2 → 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(

seltz-0.1.3/src/seltz/types.py

@@ -0,0 +1,285 @@
+"""Type definitions for the Seltz SDK."""
+
+from typing import Iterator, Optional
+
+from seltz_public_api.proto.v1.seltz_pb2 import (
+    Document as PbDocument,
+)
+from seltz_public_api.proto.v1.seltz_pb2 import (
+    Includes as PbIncludes,
+)
+from seltz_public_api.proto.v1.seltz_pb2 import (
+    SearchResponse as PbSearchResponse,
+)
+
+
+class Includes:
+    """Configuration for what to include in search results.
+
+    This class provides a user-friendly interface for configuring search result
+    inclusions, wrapping the underlying protobuf Includes message.
+
+    Supports both constructor and fluent builder patterns:
+
+    Constructor pattern (simple):
+        >>> includes = Includes(max_documents=5)
+        >>> response = client.search("query", includes=includes)
+
+    Fluent builder pattern (for multiple fields):
+        >>> includes = Includes().max_documents(5)
+        >>> response = client.search("query", includes=includes)
+
+    Attributes:
+        max_documents: Maximum number of documents to return in the response.
+    """
+
+    def __init__(
+        self,
+        max_documents: int = 10,
+    ):
+        """Initialize the Includes configuration.
+
+        Args:
+            max_documents: Maximum number of documents to return. If not specified,
+                the server will use its default value.
+        """
+        self._max_documents = max_documents
+
+    def max_documents(self, value: int) -> "Includes":
+        """Set maximum number of documents (fluent builder method).
+
+        Args:
+            value: Maximum number of documents to return.
+
+        Returns:
+            Self for method chaining.
+
+        Example:
+            >>> includes = Includes().max_documents(10)
+            >>> # Or chain multiple fields (when more fields are available)
+            >>> includes = Includes().max_documents(10).include_metadata(True)
+        """
+        self._max_documents = value
+        return self
+
+    def _to_protobuf(self) -> PbIncludes:
+        """Convert to protobuf Includes message.
+
+        Internal method used by the SDK to convert this user-facing object
+        to the underlying protobuf representation.
+
+        Returns:
+            PbIncludes: Protobuf Includes message.
+        """
+        pb_includes = PbIncludes()
+        pb_includes.max_documents = self._max_documents
+        return pb_includes
+
+    def __repr__(self) -> str:
+        """String representation for debugging."""
+        params = []
+        params.append(f"max_documents={self._max_documents}")
+        return f"Includes({', '.join(params)})"
+
+
+class Document:
+    """A search result document.
+
+    This class wraps the protobuf Document message with a more user-friendly
+    interface and helper methods.
+
+    Example:
+        >>> doc = response.documents[0]
+        >>> print(doc.url)
+        >>> print(doc.content[:100])
+        >>> if doc.has_content():
+        ...     print("Document has content")
+
+    Attributes:
+        url: URL of the document (may be None for non-web documents)
+        content: Content/snippet of the document
+    """
+
+    def __init__(self, pb_document: PbDocument):
+        """Initialize from protobuf Document.
+
+        Args:
+            pb_document: Protobuf Document message
+        """
+        self._pb = pb_document
+
+    @property
+    def url(self) -> Optional[str]:
+        """Get the document URL.
+
+        Returns:
+            URL string if available, None otherwise.
+        """
+        return self._pb.url if self._pb.HasField("url") else None
+
+    @property
+    def content(self) -> Optional[str]:
+        """Get the document content.
+
+        Returns:
+            Content string if available, None otherwise.
+        """
+        return self._pb.content if self._pb.HasField("content") else None
+
+    def has_url(self) -> bool:
+        """Check if document has a URL.
+
+        Returns:
+            True if URL is present, False otherwise.
+        """
+        return self._pb.HasField("url")
+
+    def has_content(self) -> bool:
+        """Check if document has content.
+
+        Returns:
+            True if content is present, False otherwise.
+        """
+        return self._pb.HasField("content")
+
+    def to_dict(self) -> dict:
+        """Convert document to a dictionary.
+
+        Useful for JSON serialization or logging.
+
+        Returns:
+            Dictionary with url and content fields (only if present).
+        """
+        result = {}
+        if self.has_url():
+            result["url"] = self.url
+        if self.has_content():
+            result["content"] = self.content
+        return result
+
+    def __repr__(self) -> str:
+        """String representation for debugging."""
+        parts = []
+        if self.has_url():
+            parts.append(f"url='{self.url}'")
+        if self.content is not None:
+            content_preview = (
+                self.content[:50] + "..." if len(self.content) > 50 else self.content
+            )
+            parts.append(f"content='{content_preview}'")
+        return f"Document({', '.join(parts)})"
+
+    def __str__(self) -> str:
+        """Human-readable string representation."""
+        if self.url is not None:
+            return f"{self.url}: {self.content[:100] if self.content is not None else 'No content'}"
+        return self.content if self.content is not None else "Empty document"
+
+
+class SearchResult:
+    """Search result containing documents and metadata.
+
+    This class wraps the protobuf SearchResponse message with a more user-friendly
+    interface and helper methods.
+
+    Example:
+        >>> result = client.search("Python tutorial")
+        >>> print(f"Found {len(result)} documents")
+        >>> for doc in result:
+        ...     print(doc.url)
+        >>> first = result.first()
+        >>> urls = result.get_urls()
+
+    Attributes:
+        documents: List of Document objects in the search results
+    """
+
+    def __init__(self, pb_response: PbSearchResponse):
+        """Initialize from protobuf SearchResponse.
+
+        Args:
+            pb_response: Protobuf SearchResponse message
+        """
+        self._pb = pb_response
+        self._documents = [Document(pb_doc) for pb_doc in pb_response.documents]
+
+    @property
+    def documents(self) -> list[Document]:
+        """Get the list of documents.
+
+        Returns:
+            List of Document objects.
+        """
+        return self._documents
+
+    def __len__(self) -> int:
+        """Get the number of documents.
+
+        Returns:
+            Number of documents in the result.
+        """
+        return len(self._documents)
+
+    def __iter__(self) -> Iterator[Document]:
+        """Iterate over documents.
+
+        Returns:
+            Iterator over Document objects.
+        """
+        return iter(self._documents)
+
+    def __getitem__(self, index: int) -> Document:
+        """Get document by index.
+
+        Args:
+            index: Index of the document (supports negative indexing)
+
+        Returns:
+            Document at the specified index.
+
+        Raises:
+            IndexError: If index is out of range.
+        """
+        return self._documents[index]
+
+    def first(self) -> Optional[Document]:
+        """Get the first document.
+
+        Returns:
+            First document if available, None if result is empty.
+        """
+        return self._documents[0] if self._documents else None
+
+    def get_urls(self) -> list[str]:
+        """Get all document URLs.
+
+        Returns:
+            List of URLs from documents that have URLs.
+        """
+        return [doc.url for doc in self._documents if doc.url is not None]
+
+    def get_contents(self) -> list[str]:
+        """Get all document contents.
+
+        Returns:
+            List of content strings from documents that have content.
+        """
+        return [doc.content for doc in self._documents if doc.content is not None]
+
+    def to_dict(self) -> dict:
+        """Convert result to a dictionary.
+
+        Useful for JSON serialization or logging.
+
+        Returns:
+            Dictionary with documents list.
+        """
+        return {"documents": [doc.to_dict() for doc in self._documents]}
+
+    def __repr__(self) -> str:
+        """String representation for debugging."""
+        return f"SearchResult(documents={len(self._documents)})"
+
+    def __str__(self) -> str:
+        """Human-readable string representation."""
+        return f"SearchResult with {len(self._documents)} document(s)"

{seltz-0.1.2 → seltz-0.1.3}/src/seltz.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: seltz
-Version: 0.1.2
+Version: 0.1.3
 Summary: Seltz Python SDK for AI-powered search
 Author-email: Seltz <support@seltz.ai>
 Project-URL: Homepage, https://seltz.ai
@@ -21,7 +21,7 @@ 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.33.1
+Requires-Dist: protobuf<6.0
 
 # Seltz Python SDK
 
@@ -77,15 +77,127 @@ Creates a new Seltz client instance.
 
 **Returns:** `Seltz` instance
 
-### `client.search(text, max_documents=10)`
+### `client.search(query, *, includes=None, context=None, profile=None)`
 
 Performs a search query.
 
 **Parameters:**
-- `text` (str): The search query text.
-- `max_documents` (int): Maximum number of documents to return. Defaults to 10.
+- `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:** `SearchResponse` with a `documents` field containing search results.
+**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
 
@@ -121,4 +233,4 @@ except SeltzAPIError as e:
 
 - Python 3.8+
 - grpcio >= 1.76.0
-- protobuf >= 6.33.1
+- protobuf < 6.0

{seltz-0.1.2 → seltz-0.1.3}/src/seltz.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ src/seltz/__init__.py
 src/seltz/client.py
 src/seltz/exceptions.py
 src/seltz/seltz.py
+src/seltz/types.py
 src/seltz.egg-info/PKG-INFO
 src/seltz.egg-info/SOURCES.txt
 src/seltz.egg-info/dependency_links.txt

seltz-0.1.3/src/seltz.egg-info/requires.txt

@@ -0,0 +1,2 @@
+grpcio>=1.76.0
+protobuf<6.0

{seltz-0.1.2 → seltz-0.1.3}/src/seltz_public_api/proto/v1/seltz_pb2.py

@@ -2,7 +2,7 @@
 # Generated by the protocol buffer compiler.  DO NOT EDIT!
 # NO CHECKED-IN PROTOBUF GENCODE
 # source: seltz_public_api/proto/v1/seltz.proto
-# Protobuf Python Version: 6.33.1
+# Protobuf Python Version: 5.29.5
 """Generated protocol buffer code."""
 from google.protobuf import descriptor as _descriptor
 from google.protobuf import descriptor_pool as _descriptor_pool
@@ -11,9 +11,9 @@ from google.protobuf import symbol_database as _symbol_database
 from google.protobuf.internal import builder as _builder
 _runtime_version.ValidateProtobufRuntimeVersion(
     _runtime_version.Domain.PUBLIC,
-    6,
-    33,
-    1,
+    5,
+    29,
+    5,
     '',
     'seltz_public_api/proto/v1/seltz.proto'
 )
@@ -24,7 +24,7 @@ _sym_db = _symbol_database.Default()
 
 
 
-DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n%seltz_public_api/proto/v1/seltz.proto\x12\x19seltz_public_api.proto.v1\"F\n\x08Includes\x12(\n\rmax_documents\x18\x01 \x01(\rH\x00R\x0cmaxDocuments\x88\x01\x01\x42\x10\n\x0e_max_documents\"\xce\x01\n\rSearchRequest\x12\x14\n\x05query\x18\x01 \x01(\tR\x05query\x12\x44\n\x08includes\x18\x02 \x01(\x0b\x32#.seltz_public_api.proto.v1.IncludesH\x00R\x08includes\x88\x01\x01\x12\x1d\n\x07\x63ontext\x18\x03 \x01(\tH\x01R\x07\x63ontext\x88\x01\x01\x12\x1d\n\x07profile\x18\x04 \x01(\tH\x02R\x07profile\x88\x01\x01\x42\x0b\n\t_includesB\n\n\x08_contextB\n\n\x08_profile\"T\n\x08\x44ocument\x12\x15\n\x03url\x18\x01 \x01(\tH\x00R\x03url\x88\x01\x01\x12\x1d\n\x07\x63ontent\x18\x02 \x01(\tH\x01R\x07\x63ontent\x88\x01\x01\x42\x06\n\x04_urlB\n\n\x08_content\"S\n\x0eSearchResponse\x12\x41\n\tdocuments\x18\x01 \x03(\x0b\x32#.seltz_public_api.proto.v1.DocumentR\tdocuments2m\n\x0cSeltzService\x12]\n\x06Search\x12(.seltz_public_api.proto.v1.SearchRequest\x1a).seltz_public_api.proto.v1.SearchResponseb\x06proto3')
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n%seltz_public_api/proto/v1/seltz.proto\x12\x19seltz_public_api.proto.v1\"F\n\x08Includes\x12(\n\rmax_documents\x18\x01 \x01(\rH\x00R\x0cmaxDocuments\x88\x01\x01\x42\x10\n\x0e_max_documents\"\xe7\x01\n\rSearchRequest\x12\x14\n\x05query\x18\x01 \x01(\tR\x05query\x12\x44\n\x08includes\x18\x02 \x01(\x0b\x32#.seltz_public_api.proto.v1.IncludesH\x00R\x08includes\x88\x01\x01\x12\x1d\n\x07\x63ontext\x18\x03 \x01(\tH\x01R\x07\x63ontext\x88\x01\x01\x12\x1d\n\x07profile\x18\x04 \x01(\tH\x02R\x07profile\x88\x01\x01\x12\x17\n\x07\x61pi_key\x18\x05 \x01(\tR\x06\x61piKeyB\x0b\n\t_includesB\n\n\x08_contextB\n\n\x08_profile\"T\n\x08\x44ocument\x12\x15\n\x03url\x18\x01 \x01(\tH\x00R\x03url\x88\x01\x01\x12\x1d\n\x07\x63ontent\x18\x02 \x01(\tH\x01R\x07\x63ontent\x88\x01\x01\x42\x06\n\x04_urlB\n\n\x08_content\"S\n\x0eSearchResponse\x12\x41\n\tdocuments\x18\x01 \x03(\x0b\x32#.seltz_public_api.proto.v1.DocumentR\tdocuments2o\n\x0cSeltzService\x12_\n\x06Search\x12(.seltz_public_api.proto.v1.SearchRequest\x1a).seltz_public_api.proto.v1.SearchResponse\"\x00\x62\x06proto3')
 
 _globals = globals()
 _builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
@@ -34,11 +34,11 @@ if not _descriptor._USE_C_DESCRIPTORS:
   _globals['_INCLUDES']._serialized_start=68
   _globals['_INCLUDES']._serialized_end=138
   _globals['_SEARCHREQUEST']._serialized_start=141
-  _globals['_SEARCHREQUEST']._serialized_end=347
-  _globals['_DOCUMENT']._serialized_start=349
-  _globals['_DOCUMENT']._serialized_end=433
-  _globals['_SEARCHRESPONSE']._serialized_start=435
-  _globals['_SEARCHRESPONSE']._serialized_end=518
-  _globals['_SELTZSERVICE']._serialized_start=520
-  _globals['_SELTZSERVICE']._serialized_end=629
+  _globals['_SEARCHREQUEST']._serialized_end=372
+  _globals['_DOCUMENT']._serialized_start=374
+  _globals['_DOCUMENT']._serialized_end=458
+  _globals['_SEARCHRESPONSE']._serialized_start=460
+  _globals['_SEARCHRESPONSE']._serialized_end=543
+  _globals['_SELTZSERVICE']._serialized_start=545
+  _globals['_SELTZSERVICE']._serialized_end=656
 # @@protoc_insertion_point(module_scope)

{seltz-0.1.2 → seltz-0.1.3}/src/seltz_public_api/proto/v1/seltz_pb2.pyi

@@ -1,35 +1,32 @@
-from collections.abc import Iterable as _Iterable
-from collections.abc import Mapping as _Mapping
-from typing import ClassVar as _ClassVar
-from typing import Optional as _Optional
-from typing import Union as _Union
-
+from google.protobuf.internal import containers as _containers
 from google.protobuf import descriptor as _descriptor
 from google.protobuf import message as _message
-from google.protobuf.internal import containers as _containers
+from typing import ClassVar as _ClassVar, Iterable as _Iterable, Mapping as _Mapping, Optional as _Optional, Union as _Union
 
 DESCRIPTOR: _descriptor.FileDescriptor
 
 class Includes(_message.Message):
-    __slots__ = ()
+    __slots__ = ("max_documents",)
     MAX_DOCUMENTS_FIELD_NUMBER: _ClassVar[int]
     max_documents: int
     def __init__(self, max_documents: _Optional[int] = ...) -> None: ...
 
 class SearchRequest(_message.Message):
-    __slots__ = ()
+    __slots__ = ("query", "includes", "context", "profile", "api_key")
     QUERY_FIELD_NUMBER: _ClassVar[int]
     INCLUDES_FIELD_NUMBER: _ClassVar[int]
     CONTEXT_FIELD_NUMBER: _ClassVar[int]
     PROFILE_FIELD_NUMBER: _ClassVar[int]
+    API_KEY_FIELD_NUMBER: _ClassVar[int]
     query: str
     includes: Includes
     context: str
     profile: str
-    def __init__(self, query: _Optional[str] = ..., includes: _Optional[_Union[Includes, _Mapping]] = ..., context: _Optional[str] = ..., profile: _Optional[str] = ...) -> None: ...
+    api_key: str
+    def __init__(self, query: _Optional[str] = ..., includes: _Optional[_Union[Includes, _Mapping]] = ..., context: _Optional[str] = ..., profile: _Optional[str] = ..., api_key: _Optional[str] = ...) -> None: ...
 
 class Document(_message.Message):
-    __slots__ = ()
+    __slots__ = ("url", "content")
     URL_FIELD_NUMBER: _ClassVar[int]
     CONTENT_FIELD_NUMBER: _ClassVar[int]
     url: str
@@ -37,7 +34,7 @@ class Document(_message.Message):
     def __init__(self, url: _Optional[str] = ..., content: _Optional[str] = ...) -> None: ...
 
 class SearchResponse(_message.Message):
-    __slots__ = ()
+    __slots__ = ("documents",)
     DOCUMENTS_FIELD_NUMBER: _ClassVar[int]
     documents: _containers.RepeatedCompositeFieldContainer[Document]
     def __init__(self, documents: _Optional[_Iterable[_Union[Document, _Mapping]]] = ...) -> None: ...

seltz-0.1.2/README.md

@@ -1,99 +0,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(text, max_documents=10)`
-
-Performs a search query.
-
-**Parameters:**
-- `text` (str): The search query text.
-- `max_documents` (int): Maximum number of documents to return. Defaults to 10.
-
-**Returns:** `SearchResponse` with a `documents` field containing search results.
-
-## 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.33.1

seltz-0.1.2/src/seltz/seltz.py

@@ -1,48 +0,0 @@
-import os
-
-from .client import SeltzClient
-from .exceptions import SeltzConfigurationError
-from .services import SearchResponse
-from .services.search_service import SearchService
-
-
-class Seltz:
-    """Main Seltz SDK client for interacting with the Seltz API."""
-
-    _ENDPOINT: str = "grpc.seltz.ai"
-
-    def __init__(
-        self,
-        api_key: str | None = 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, text: str, max_documents: int = 10) -> SearchResponse:
-        """Perform a search query.
-
-        Args:
-            text: The search query text
-            max_documents: Maximum number of documents to return (default: 10)
-
-        Returns:
-            SearchResponse: The search results
-        """
-        return self._search.search(text, max_documents=max_documents)

seltz-0.1.2/src/seltz.egg-info/requires.txt

@@ -1,2 +0,0 @@
-grpcio>=1.76.0
-protobuf>=6.33.1