snowleopard 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

snowleopard/__init__.py

@@ -1,5 +1,13 @@
 # -*- coding: utf-8 -*-
-# copyright 2024 Snow Leopard, Inc - all rights reserved
+# copyright 2025 Snow Leopard, Inc
+# released under the MIT license - see LICENSE file
 
+from snowleopard.async_client import AsyncSnowLeopardPlaygroundClient
+from snowleopard.client import SnowLeopardPlaygroundClient
 
-__version__ = '0.1.0'
+__version__ = "0.1.1"
+
+__all__ = [
+    "SnowLeopardPlaygroundClient",
+    "AsyncSnowLeopardPlaygroundClient",
+]

snowleopard/async_client.py

@@ -0,0 +1,62 @@
+# -*- coding: utf-8 -*-
+# copyright 2025 Snow Leopard, Inc
+# released under the MIT license - see LICENSE file
+
+import json
+from typing import AsyncGenerator, Optional, Dict, Any
+
+import httpx
+from snowleopard.client_base import SLClientBase
+from snowleopard.models import ResponseDataObjects, RetrieveResponseObjects, parse
+
+
+class AsyncSnowLeopardPlaygroundClient(SLClientBase):
+    client: httpx.AsyncClient
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        timeout: Optional[httpx.Timeout] = None,
+        loc: str = None,
+    ):
+        config = self._config(api_key, timeout, loc)
+        self.client = httpx.AsyncClient(
+            base_url=config.loc, headers=config.headers(), timeout=config.timeout
+        )
+
+    async def retrieve(
+        self,
+        datafile_id: str,
+        user_query: str,
+        known_data: Optional[Dict[str, Any]] = None,
+    ) -> RetrieveResponseObjects:
+        resp = await self.client.post(
+            url=self._build_path(datafile_id, "retrieve"),
+            json=self._build_request_body(user_query, known_data),
+        )
+        return self._parse_retrieve(resp)
+
+    async def response(
+        self,
+        datafile_id: str,
+        user_query: str,
+        known_data: Optional[Dict[str, Any]] = None,
+    ) -> AsyncGenerator[ResponseDataObjects, None]:
+        async with self.client.stream(
+            "POST",
+            self._build_path(datafile_id, "response"),
+            json=self._build_request_body(user_query, known_data),
+        ) as resp:
+            resp.raise_for_status()
+            async for line in resp.aiter_lines():
+                yield parse(json.loads(line))
+
+    async def __aenter__(self):
+        await self.client.__aenter__()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.client.__aexit__(exc_type, exc_val, exc_tb)
+
+    async def close(self):
+        await self.client.aclose()

snowleopard/cli.py

@@ -0,0 +1,112 @@
+# -*- coding: utf-8 -*-
+# copyright 2025 Snow Leopard, Inc
+# released under the MIT license - see LICENSE file
+
+import dataclasses
+import json
+import sys
+import argparse
+from typing import List, Optional, Dict, Any
+
+from httpx import HTTPStatusError
+from snowleopard import __version__, SnowLeopardPlaygroundClient
+from snowleopard.models import RetrieveResponseError
+
+
+def _create_parser() -> argparse.ArgumentParser:
+    """Create and return the argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="snowy", description="Snow Leopard client library CLI"
+    )
+    parser.add_argument("--apikey", "-a", required=False, help="Snow Leopard API key")
+    parser.add_argument("--loc", "-l", required=False, help="Snow Leopard location")
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+
+    parser.set_defaults(command_func=None)
+    subparsers = parser.add_subparsers(
+        dest="command",
+        metavar="command",
+        help="run with <command name> --help for more info",
+    )
+
+    retrieve = subparsers.add_parser(
+        "retrieve", help="Retrieve data for natural language query"
+    )
+    retrieve.set_defaults(command_func=_retrieve)
+    response = subparsers.add_parser(
+        "response", help="Get streaming response for natural language query"
+    )
+    response.set_defaults(command_func=_response)
+
+    for subparser in (retrieve, response):
+        subparser.add_argument(
+            "--knownData",
+            "-d",
+            action="append",
+            help="Known data in key=value format (can be specified multiple times)",
+        )
+        subparser.add_argument("datafile", type=str, help="ID for Datafile to query")
+        subparser.add_argument("question", type=str, help="Natural language query")
+
+    return parser
+
+
+def _parse_known_data(known_data_list: Optional[List[str]]) -> Optional[Dict[str, Any]]:
+    if not known_data_list:
+        return None
+
+    result = {}
+    for item in known_data_list:
+        if "=" not in item:
+            print(f"Error: Invalid knownData format '{item}'. Expected key=value", file=sys.stderr)
+            sys.exit(1)
+        key, value = item.split("=", 1)
+        result[key] = value
+    return result
+
+
+def _get_client(parsed_args):
+    try:
+        client = SnowLeopardPlaygroundClient(api_key=parsed_args.apikey, loc=parsed_args.loc)
+    except Exception as e:
+        print(str(e), file=sys.stderr)
+        sys.exit(1)
+    return client
+
+
+def _retrieve(parsed_args):
+    try:
+        known_data = _parse_known_data(parsed_args.knownData)
+        with _get_client(parsed_args) as client:
+            resp = client.retrieve(parsed_args.datafile, parsed_args.question, known_data)
+            print(json.dumps(dataclasses.asdict(resp)))
+            if isinstance(resp, RetrieveResponseError):
+                sys.exit(1)
+    except HTTPStatusError as e:
+        print(str(e), file=sys.stderr)
+        sys.exit(1)
+
+
+def _response(parsed_args):
+    try:
+        known_data = _parse_known_data(parsed_args.knownData)
+        with _get_client(parsed_args) as client:
+            for chunk in client.response(parsed_args.datafile, parsed_args.question, known_data):
+                print(json.dumps(dataclasses.asdict(chunk)))
+    except HTTPStatusError as e:
+        print(str(e), file=sys.stderr)
+        sys.exit(1)
+
+
+def main(args: Optional[List[str]] = None) -> None:
+    """CLI entry point for snowleopard."""
+    parser = _create_parser()
+    parsed_args = parser.parse_args(args=args)
+
+    if parsed_args.command_func is not None:
+        parsed_args.command_func(parsed_args)
+    else:
+        parser.print_help(file=sys.stderr)
+        sys.exit(1)

snowleopard/client.py

@@ -0,0 +1,64 @@
+# -*- coding: utf-8 -*-
+# copyright 2025 Snow Leopard, Inc
+# released under the MIT license - see LICENSE file
+
+import json
+from typing import Optional, Generator, Dict, Any
+
+import httpx
+from snowleopard.client_base import SLClientBase
+from snowleopard.models import parse, RetrieveResponseObjects, ResponseDataObjects
+
+
+class SnowLeopardPlaygroundClient(SLClientBase):
+    client: httpx.Client
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        timeout: Optional[httpx.Timeout] = None,
+        loc: str = None,
+    ):
+        config = self._config(api_key, timeout, loc)
+        self.client = httpx.Client(
+            base_url=config.loc, headers=config.headers(), timeout=config.timeout
+        )
+
+    def retrieve(
+        self,
+        datafile_id: str,
+        user_query: str,
+        known_data: Optional[Dict[str, Any]] = None,
+    ) -> RetrieveResponseObjects:
+        resp = self.client.post(
+            url=self._build_path(datafile_id, "retrieve"),
+            json=self._build_request_body(user_query, known_data),
+        )
+        if resp.status_code not in (200, 409):
+            resp.raise_for_status()
+        return self._parse_retrieve(resp)
+
+    def response(
+        self,
+        datafile_id: str,
+        user_query: str,
+        known_data: Optional[Dict[str, Any]] = None,
+    ) -> Generator[ResponseDataObjects, None, None]:
+        with self.client.stream(
+            "POST",
+            url=self._build_path(datafile_id, "response"),
+            json=self._build_request_body(user_query, known_data),
+        ) as resp:
+            resp.raise_for_status()
+            for line in resp.iter_lines():
+                yield parse(json.loads(line))
+
+    def __enter__(self):
+        self.client.__enter__()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.client.__exit__(exc_type, exc_val, exc_tb)
+
+    def close(self):
+        self.client.close()

snowleopard/client_base.py

@@ -0,0 +1,66 @@
+# -*- coding: utf-8 -*-
+# copyright 2025 Snow Leopard, Inc
+# released under the MIT license - see LICENSE file
+
+import os
+from dataclasses import dataclass
+from typing import Optional, Dict, Any
+
+import httpx
+
+from snowleopard.models import parse
+
+
+@dataclass
+class SLConfig:
+    api_key: str
+    timeout: httpx.Timeout
+    loc: str
+
+    def headers(self):
+        headers = {}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+
+class SLClientBase:
+    @staticmethod
+    def _config(
+        api_key: Optional[str], timeout: Optional[httpx.Timeout], loc: Optional[str]
+    ) -> SLConfig:
+        api_key = api_key or os.environ.get("SNOWLEOPARD_API_KEY")
+        if api_key is None:
+            raise ValueError(
+                'Missing required argument "api_key" and environment variable "SNOWLEOPARD_API_KEY" not set'
+            )
+        timeout = timeout or httpx.Timeout(
+            connect=5.0, read=600.0, write=10.0, pool=5.0
+        )
+        loc = loc or os.environ.get("SNOWLEOPARD_LOC", "https://api.snowleopard.ai")
+        if not loc:
+            raise ValueError(
+                'Missing required argument "loc" and environment variable "SNOWLEOPARD_LOC" not set'
+            )
+        return SLConfig(api_key, timeout, loc)
+
+    @staticmethod
+    def _build_path(datafile_id: str, endpoint: str) -> str:
+        return f"datafiles/{datafile_id}/{endpoint}"
+
+    @staticmethod
+    def _build_request_body(
+        user_query: str, known_data: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        body = {"userQuery": user_query}
+        if known_data is not None:
+            body["knownData"] = known_data
+        return body
+
+    @staticmethod
+    def _parse_retrieve(resp):
+        try:
+            return parse(resp.json())
+        except Exception:
+            resp.raise_for_status()
+            raise

snowleopard/models.py

@@ -0,0 +1,144 @@
+# -*- coding: utf-8 -*-
+# copyright 2025 Snow Leopard, Inc
+# released under the MIT license - see LICENSE file
+
+from __future__ import annotations
+
+from dataclasses import dataclass, fields
+from enum import Enum
+from typing import Any, Dict, List, Optional, Union
+
+
+class StrEnum(str, Enum):
+    """String enum compatible with Python 3.8"""
+    pass
+
+
+@dataclass
+class RetrieveResponse:
+    objType = "retrieveResponse"
+
+    callId: str
+    data: List[Union[SchemaData, ErrorSchemaData]]
+    responseStatus: ResponseStatus
+
+
+@dataclass
+class RetrieveResponseError:
+    objType = "apiError"
+
+    callId: str
+    responseStatus: str
+    description: str
+
+
+@dataclass
+class SchemaData:
+    objType = "schemaData"
+
+    schemaId: str
+    schemaType: str
+    query: str
+    rows: List[Dict[str, Any]]
+    querySummary: Dict[str, Any]
+    rowMax: int
+    isTrimmed: bool
+    callId: str = None
+
+
+@dataclass
+class ErrorSchemaData:
+    objType = "errorSchemaData"
+
+    schemaType: str
+    schemaId: str
+    query: str
+    error: str
+    querySummary: Dict[str, Any]
+    datastoreExceptionInfo: Optional[str] = None
+    callId: str = None
+
+
+@dataclass
+class ResponseStart:
+    objType = "responseStart"
+
+    callId: str
+    userQuery: str
+
+
+@dataclass
+class ResponseData:
+    objType = "responseData"
+
+    callId: str
+    data: List[Union[SchemaData, ErrorSchemaData]]
+
+
+@dataclass
+class EarlyTermination:
+    objType = "earlyTermination"
+
+    callId: str
+    responseStatus: ResponseStatus
+    reason: str
+    extra: dict
+
+
+@dataclass
+class ResponseLLMResult:
+    objType = "responseResult"
+
+    callId: str
+    responseStatus: ResponseStatus
+    llmResponse: Dict[str, Any]
+
+
+class ResponseStatus(StrEnum):
+    SUCCESS = "SUCCESS"
+    NOT_FOUND_IN_SCHEMA = "NOT_FOUND_IN_SCHEMA"
+    UNKNOWN = "UNKNOWN"
+    INTERNAL_SERVER_ERROR = "INTERNAL_SERVER_ERROR"
+    AUTHORIZATION_FAILED = "AUTHORIZATION_FAILED"
+    LLM_ERROR = "LLM_ERROR"
+    LLM_TOKEN_LIMIT_REACHED = "LLM_TOKEN_LIMIT_REACHED"
+
+
+_PARSE_OBJS = {
+    o.objType: o
+    for o in (
+        RetrieveResponse,
+        RetrieveResponseError,
+        SchemaData,
+        ErrorSchemaData,
+        ResponseStart,
+        ResponseData,
+        EarlyTermination,
+        ResponseLLMResult,
+    )
+}
+
+RetrieveResponseObjects = Union[RetrieveResponse, RetrieveResponseError]
+
+ResponseDataObjects = Union[
+    ErrorSchemaData,
+    ResponseStart,
+    ResponseData,
+    EarlyTermination,
+    ResponseLLMResult,
+]
+
+
+def parse(obj):
+    if isinstance(obj, dict):
+        kind = _PARSE_OBJS.get(obj.get("__type__"))
+        if kind:
+            keys = {f.name for f in fields(kind)}
+            kwargs = {k: parse(v) for k, v in obj.items() if k in keys}
+            return kind(**kwargs)
+        else:
+            return obj
+    elif isinstance(obj, list):
+        return [parse(v) for v in obj]
+    else:
+        return obj

snowleopard-0.1.1.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: snowleopard
+Version: 0.1.1
+Summary: snowleopard.ai client library
+Author-email: Snowy <hello@snowleopard.ai>
+License: MIT License
+        
+        Copyright (c) 2025 Snow Leopard AI
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.28.1
+Description-Content-Type: text/markdown
+
+# Snow Leopard SDK for Python
+
+Python client library for [Snow Leopard Playground](https://try.snowleopard.ai) APIs.
+
+## Installation
+
+```bash
+pip install snowleopard
+```
+
+## Quick Start
+
+```python
+from snowleopard import SnowLeopardPlaygroundClient
+
+# Initialize the client (or AsyncSnowLeopardPlaygroundClient)
+client = SnowLeopardPlaygroundClient(api_key="your-api-key")
+
+# Query your data in natural language
+response = client.retrieve(
+    datafile_id="your-datafile-id",
+    user_query="How many users signed up last month?"
+)
+```
+
+## Getting Started
+
+1. **Get your API key** from [https://auth.snowleopard.ai/account/api_keys](https://auth.snowleopard.ai/account/api_keys)
+2. **Upload your datafiles** at [https://try.snowleopard.ai](https://try.snowleopard.ai)
+3. **Set your API key** via environment variable:
+    ```bash
+    export SNOWLEOPARD_API_KEY="your-api-key"
+    ```
+    
+    Or pass it directly to the client:
+    
+    ```python
+    SnowLeopardPlaygroundClient(api_key="your-api-key")
+    ```
+
+## Usage
+
+### Synchronous Client
+
+```python
+from snowleopard import SnowLeopardPlaygroundClient
+
+with SnowLeopardPlaygroundClient() as client:
+    # Get data directly from a natural language query
+    response = client.retrieve("datafile-id", "What's the total revenue?")
+    print(response.data)
+    
+    # Stream natural language summary of live data
+    for chunk in client.response("datafile-id", "Show me top 10 customers"):
+        print(chunk)
+```
+
+### Async Client
+
+```python
+from snowleopard import AsyncSnowLeopardPlaygroundClient
+
+async with AsyncSnowLeopardPlaygroundClient() as client:
+    # Get complete results
+    response = await client.retrieve("datafile-id", "What's the total revenue?")
+    print(response.data)
+
+    # Get streaming results
+    async for chunk in client.response("datafile-id", "Show me top 10 customers"):
+        print(chunk)
+```
+
+### CLI
+
+The SDK includes a command-line interface:
+
+```bash
+pip install snowleopard
+snowy retrieve <datafile-id> "How many records are there?"
+snowy response <datafile-id> "Summarize the data"
+```
+
+## Contributing
+
+For SDK developer docs and how to contribute, see [CONTRIBUTING.md](CONTRIBUTING.md)

snowleopard-0.1.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+snowleopard/__init__.py,sha256=bN7CK0iAiVg6get_gDBW47JWYzwJ83AZzeVf1bTc_II,354
+snowleopard/async_client.py,sha256=ybTkgqO5SUHq8K0QJbrsvyzZQxlmecjExfacOF4PR2U,1948
+snowleopard/cli.py,sha256=xb1DlP2nm-pkiH4I4U0fHko06yaQZnOwIhjn2tIvc7Y,3705
+snowleopard/client.py,sha256=-oVa7yegfVgJ2p7DVCZhTdA6DOs_Rs69mryCNsH9p6I,1944
+snowleopard/client_base.py,sha256=7hoFmnCfeC1fcBMoOYKVmniSUqsWhe5moGUhlhqf_lo,1903
+snowleopard/models.py,sha256=5kFRjfwe79Cx6tYneLMWKloyGQylYc2pPHoFcwO3GlU,2858
+snowleopard-0.1.1.dist-info/METADATA,sha256=01OaSIIMjzC8jSY-x6yMKNhsOQAPyA3nVuae58mARQY,3804
+snowleopard-0.1.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+snowleopard-0.1.1.dist-info/entry_points.txt,sha256=KoByMlsBKmDB6_iwkrTCFyl2BT9bjBuKUZth40aXx70,47
+snowleopard-0.1.1.dist-info/licenses/LICENSE,sha256=Lw8Ah-T2MngQlqtV8GCML7qD1OPJ5QnccfJBB_U3f2A,1072
+snowleopard-0.1.1.dist-info/RECORD,,

{snowleopard-0.1.0.dist-info → snowleopard-0.1.1.dist-info}/WHEEL

@@ -1,5 +1,4 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.2.0)
+Generator: hatchling 1.27.0
 Root-Is-Purelib: true
 Tag: py3-none-any
-

snowleopard-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+snowy = snowleopard.cli:main

snowleopard-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Snow Leopard AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

snowleopard-0.1.0.dist-info/LICENSE

@@ -1,2 +0,0 @@
-copyright 2024 Snow Leopard, Inc
-all rights reserved

snowleopard-0.1.0.dist-info/METADATA

@@ -1,16 +0,0 @@
-Metadata-Version: 2.1
-Name: snowleopard
-Version: 0.1.0
-Summary: snowleopard.ai client library
-License: copyright 2024 Snow Leopard, Inc
-        all rights reserved
-        
-Classifier: Development Status :: 1 - Planning
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: importlib-metadata>=4.6; python_version < "3.10"
-
-# SnowLeopard-ai python client library

snowleopard-0.1.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-snowleopard/__init__.py,sha256=O45mmYZDpAiBmrpcZeDsutcbvhcJ_emeLIxYN1gbn58,105
-snowleopard-0.1.0.dist-info/LICENSE,sha256=INFxg3nwCPqYuWoS7c7a8p4DwyLKPexz6gWWu3yLn34,53
-snowleopard-0.1.0.dist-info/METADATA,sha256=ourB-fPFb18vq6L2Natsq6NTm5FTBrY7jdjPwxYv3jY,488
-snowleopard-0.1.0.dist-info/WHEEL,sha256=OVMc5UfuAQiSplgO0_WdW7vXVGAt9Hdd6qtN4HotdyA,91
-snowleopard-0.1.0.dist-info/top_level.txt,sha256=OBLtbUHAAsmV0w5ThT3dRUHSGbq0zwnxn2Xmbb4EGMM,12
-snowleopard-0.1.0.dist-info/RECORD,,

snowleopard-0.1.0.dist-info/top_level.txt

@@ -1 +0,0 @@
-snowleopard