seltz 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

seltz/__init__.py

@@ -0,0 +1,23 @@
+"""Seltz Python SDK for interacting with the Seltz API."""
+
+from .exceptions import (
+    SeltzAPIError,
+    SeltzAuthenticationError,
+    SeltzConfigurationError,
+    SeltzConnectionError,
+    SeltzError,
+    SeltzRateLimitError,
+    SeltzTimeoutError,
+)
+from .seltz import Seltz
+
+__all__ = [
+    "Seltz",
+    "SeltzError",
+    "SeltzConfigurationError",
+    "SeltzAuthenticationError",
+    "SeltzConnectionError",
+    "SeltzAPIError",
+    "SeltzTimeoutError",
+    "SeltzRateLimitError",
+]

seltz/client.py

@@ -0,0 +1,36 @@
+import grpc
+
+
+class SeltzClient:
+    """Low-level gRPC client for Seltz API."""
+
+    def __init__(
+        self, endpoint: str, api_key: str | None = None, insecure: bool = False
+    ):
+        """Initialize the Seltz gRPC client.
+
+        Args:
+            endpoint: The gRPC endpoint to connect to
+            api_key: API key for authentication
+            insecure: Whether to use insecure connection (default: False)
+        """
+        options = [
+            ("grpc.keepalive_time_ms", 30000),
+            ("grpc.keepalive_timeout_ms", 5000),
+            ("grpc.keepalive_permit_without_calls", True),
+            ("grpc.http2.max_pings_without_data", 0),
+            ("grpc.http2.min_time_between_pings_ms", 10000),
+            ("grpc.http2.min_ping_interval_without_data_ms", 300000),
+            ("grpc.http2.write_buffer_size", 0),
+            ("grpc.http2.max_frame_size", 4194304),
+        ]
+
+        if insecure:
+            channel = grpc.insecure_channel(endpoint, options=options)
+        else:
+            channel = grpc.secure_channel(
+                endpoint, grpc.ssl_channel_credentials(), options=options
+            )
+
+        self.channel = channel
+        self.api_key = api_key

seltz/exceptions.py

@@ -0,0 +1,53 @@
+"""Custom exceptions for the Seltz SDK."""
+
+import grpc
+
+
+class SeltzError(Exception):
+    """Base exception for all Seltz SDK errors."""
+
+    pass
+
+
+class SeltzConfigurationError(SeltzError):
+    """Raised when there's a configuration issue."""
+
+    pass
+
+
+class SeltzAuthenticationError(SeltzError):
+    """Raised when authentication fails."""
+
+    pass
+
+
+class SeltzConnectionError(SeltzError):
+    """Raised when connection to the API fails."""
+
+    pass
+
+
+class SeltzAPIError(SeltzError):
+    """Raised when the API returns an error."""
+
+    def __init__(
+        self,
+        message: str,
+        grpc_code: grpc.StatusCode | None = None,
+        grpc_details: str | None = None,
+    ):
+        super().__init__(message)
+        self.grpc_code = grpc_code
+        self.grpc_details = grpc_details
+
+
+class SeltzTimeoutError(SeltzError):
+    """Raised when a request times out."""
+
+    pass
+
+
+class SeltzRateLimitError(SeltzError):
+    """Raised when rate limit is exceeded."""
+
+    pass

seltz/seltz.py

@@ -0,0 +1,48 @@
+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 = "api.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: api.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/seltz_public_api/proto/v1/seltz_pb2.py

@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+# 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
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+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,
+    '',
+    'seltz_public_api/proto/v1/seltz.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_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')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'seltz_public_api.proto.v1.seltz_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  DESCRIPTOR._loaded_options = None
+  _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
+# @@protoc_insertion_point(module_scope)

seltz/seltz_public_api/proto/v1/seltz_pb2.pyi

@@ -0,0 +1,43 @@
+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 import descriptor as _descriptor
+from google.protobuf import message as _message
+from google.protobuf.internal import containers as _containers
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class Includes(_message.Message):
+    __slots__ = ()
+    MAX_DOCUMENTS_FIELD_NUMBER: _ClassVar[int]
+    max_documents: int
+    def __init__(self, max_documents: _Optional[int] = ...) -> None: ...
+
+class SearchRequest(_message.Message):
+    __slots__ = ()
+    QUERY_FIELD_NUMBER: _ClassVar[int]
+    INCLUDES_FIELD_NUMBER: _ClassVar[int]
+    CONTEXT_FIELD_NUMBER: _ClassVar[int]
+    PROFILE_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: ...
+
+class Document(_message.Message):
+    __slots__ = ()
+    URL_FIELD_NUMBER: _ClassVar[int]
+    CONTENT_FIELD_NUMBER: _ClassVar[int]
+    url: str
+    content: str
+    def __init__(self, url: _Optional[str] = ..., content: _Optional[str] = ...) -> None: ...
+
+class SearchResponse(_message.Message):
+    __slots__ = ()
+    DOCUMENTS_FIELD_NUMBER: _ClassVar[int]
+    documents: _containers.RepeatedCompositeFieldContainer[Document]
+    def __init__(self, documents: _Optional[_Iterable[_Union[Document, _Mapping]]] = ...) -> None: ...

seltz/seltz_public_api/proto/v1/seltz_pb2_grpc.py

@@ -0,0 +1,77 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+
+from seltz_public_api.proto.v1 import seltz_pb2 as seltz__public__api_dot_proto_dot_v1_dot_seltz__pb2
+
+
+class SeltzServiceStub(object):
+    """Missing associated documentation comment in .proto file."""
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.Search = channel.unary_unary(
+                '/seltz_public_api.proto.v1.SeltzService/Search',
+                request_serializer=seltz__public__api_dot_proto_dot_v1_dot_seltz__pb2.SearchRequest.SerializeToString,
+                response_deserializer=seltz__public__api_dot_proto_dot_v1_dot_seltz__pb2.SearchResponse.FromString,
+                _registered_method=True)
+
+
+class SeltzServiceServicer(object):
+    """Missing associated documentation comment in .proto file."""
+
+    def Search(self, request, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_SeltzServiceServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'Search': grpc.unary_unary_rpc_method_handler(
+                    servicer.Search,
+                    request_deserializer=seltz__public__api_dot_proto_dot_v1_dot_seltz__pb2.SearchRequest.FromString,
+                    response_serializer=seltz__public__api_dot_proto_dot_v1_dot_seltz__pb2.SearchResponse.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'seltz_public_api.proto.v1.SeltzService', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+    server.add_registered_method_handlers('seltz_public_api.proto.v1.SeltzService', rpc_method_handlers)
+
+
+ # This class is part of an EXPERIMENTAL API.
+class SeltzService(object):
+    """Missing associated documentation comment in .proto file."""
+
+    @staticmethod
+    def Search(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/seltz_public_api.proto.v1.SeltzService/Search',
+            seltz__public__api_dot_proto_dot_v1_dot_seltz__pb2.SearchRequest.SerializeToString,
+            seltz__public__api_dot_proto_dot_v1_dot_seltz__pb2.SearchResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)

seltz/services/__init__.py

@@ -0,0 +1,18 @@
+"""Service layer with centralized protobuf imports for API version management."""
+
+# Centralized protobuf imports - update these when API version changes
+from ..seltz_public_api.proto.v1.seltz_pb2 import (
+    Document,
+    Includes,
+    SearchRequest,
+    SearchResponse,
+)
+from ..seltz_public_api.proto.v1.seltz_pb2_grpc import SeltzServiceStub
+
+__all__ = [
+    "SeltzServiceStub",
+    "SearchRequest",
+    "SearchResponse",
+    "Includes",
+    "Document",
+]

seltz/services/search_service.py

@@ -0,0 +1,62 @@
+import grpc
+
+from ..exceptions import (
+    SeltzAPIError,
+    SeltzAuthenticationError,
+    SeltzConnectionError,
+    SeltzRateLimitError,
+    SeltzTimeoutError,
+)
+from . import Includes, SearchRequest, SearchResponse, SeltzServiceStub
+
+
+class SearchService:
+    """Service for performing search operations via gRPC."""
+
+    def __init__(self, channel: grpc.Channel, api_key: str | None):
+        """Initialize the search service.
+
+        Args:
+            channel: gRPC channel for communication
+            api_key: API key for authentication
+        """
+        self._stub = SeltzServiceStub(channel)
+        self._api_key = api_key
+
+    def search(self, query: str, max_documents: int = 10) -> SearchResponse:
+        """Perform a search query.
+
+        Args:
+            query: The search query string
+            max_documents: Maximum number of documents to return (default: 10)
+
+        Returns:
+            SearchResponse containing the search results
+
+        Raises:
+            grpc.RpcError: If the gRPC call fails
+        """
+        includes = Includes(max_documents=max_documents)
+        req = SearchRequest(query=query, includes=includes)
+
+        metadata = []
+        if self._api_key:
+            metadata.append(("authorization", f"Bearer {self._api_key}"))
+
+        try:
+            return self._stub.Search(req, metadata=metadata, timeout=30)
+        except grpc.RpcError as e:
+            if e.code() == grpc.StatusCode.UNAUTHENTICATED:
+                raise SeltzAuthenticationError(
+                    f"Authentication failed: {e.details()}"
+                ) from e
+            elif e.code() == grpc.StatusCode.UNAVAILABLE:
+                raise SeltzConnectionError(f"Connection failed: {e.details()}") from e
+            elif e.code() == grpc.StatusCode.DEADLINE_EXCEEDED:
+                raise SeltzTimeoutError(f"Request timed out: {e.details()}") from e
+            elif e.code() == grpc.StatusCode.RESOURCE_EXHAUSTED:
+                raise SeltzRateLimitError(f"Rate limit exceeded: {e.details()}") from e
+            else:
+                raise SeltzAPIError(
+                    f"API error: {e.details()}", e.code(), e.details()
+                ) from e

seltz-0.1.0.dist-info/METADATA

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: seltz
+Version: 0.1.0
+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-py
+Project-URL: Bug Tracker, https://github.com/seltz-ai/seltz-py/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.8
+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 :: 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.33.1
+
+# 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.create(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.create(api_key="your-api-key")
+   ```
+
+## API Reference
+
+### `Seltz.create(api_key=None, endpoint="api.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 "api.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.create(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.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+seltz/__init__.py,sha256=PfEylMpsO-APEQfWbj7nl36ieJVGSb-6RK4501EIpnE,491
+seltz/client.py,sha256=OKdesdOfz84v9zw8oAANC-WwnYrO06zh6ZJIMPnl2cM,1206
+seltz/exceptions.py,sha256=PCFXFY0c5lJuczoB0oWwSMlCAEvVM_HOrU2RR69aZXA,994
+seltz/seltz.py,sha256=HsPOQhuftxT3bb8j1cWZWY2DSgQevcDWBynMSlNJN_c,1604
+seltz/seltz_public_api/proto/v1/seltz_pb2.py,sha256=H5J1GBGixJSdSV_tFIP69x2VMlstAZuvxM2ngikGoHo,2624
+seltz/seltz_public_api/proto/v1/seltz_pb2.pyi,sha256=RN_gWIqg7KLndmm7UG6a3BAhDPFZTkNovngPjpgmUlo,1625
+seltz/seltz_public_api/proto/v1/seltz_pb2_grpc.py,sha256=Gt-sDKmEsNYzRbzXKvQKIDFoVVnjU8LtEm_sbKyTuro,3024
+seltz/services/__init__.py,sha256=HtZ9sFTWp5jMI7TkhY7xr9mfB4t0Kdf-o2cmgox9br8,461
+seltz/services/search_service.py,sha256=2t3LzHXWNg_dWHrhSbMBCht0WMz26LpIa5Rgy7kmkRI,2194
+seltz-0.1.0.dist-info/METADATA,sha256=yR8uDSkKMVWLdU7MDhf2AVI3m4DFgKrprHm889w0xxM,3242
+seltz-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+seltz-0.1.0.dist-info/top_level.txt,sha256=4E4pi6jXnZTfkvK2Wm0csGgdHvhjE0UeYaYuld8zOCo,6
+seltz-0.1.0.dist-info/RECORD,,

{seltz-0.0.1.dist-info → seltz-0.1.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.45.1)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

seltz-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+seltz

seltz-0.0.1.dist-info/METADATA

@@ -1,9 +0,0 @@
-Metadata-Version: 2.1
-Name: seltz
-Version: 0.0.1
-Home-page: 
-Author: Elias Bassani
-Author-email: elias.bssn@gmail.com
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-

seltz-0.0.1.dist-info/RECORD

@@ -1,4 +0,0 @@
-seltz-0.0.1.dist-info/METADATA,sha256=f6pqnfuXUV36MwWFq9snAP6WekntcMe2s_pXkS6uMP8,182
-seltz-0.0.1.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
-seltz-0.0.1.dist-info/top_level.txt,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-seltz-0.0.1.dist-info/RECORD,,

seltz-0.0.1.dist-info/top_level.txt

@@ -1 +0,0 @@
-