snowleopard 0.1.0__tar.gz → 0.2.0__tar.gz

snowleopard-0.2.0/.claude/settings.local.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(mkdir:*)",
+      "Bash(uv add:*)",
+      "Bash(uv run pytest:*)",
+      "WebFetch(domain:www.python-httpx.org)",
+      "Bash(python -c:*)",
+      "Bash(uv run python:*)",
+      "WebFetch(domain:github.com)",
+      "Bash(uv run snowy response --help:*)",
+      "Bash(uv run:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

snowleopard-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+# python
+__pycache__
+.venv
+*.egg-info
+dist
+
+# misc
+.DS_Store
+.env
+.idea
+.vscode
+snowleopard_py.iml
+CLAUDE.md

snowleopard-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing
+
+Thanks for your interest in contributing to the Snow Leopard Python SDK!
+
+Questions? Reach out on [Discord](https://discord.gg/WGAyr8NpEX)
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.11 (our default dev version)
+- [uv](https://docs.astral.sh/uv/) package manager
+
+### Setup
+
+0. **Fork this repository**
+   If you are unfamiliar contributing to open source projects, see [first-contributions](https://github.com/firstcontributions/first-contributions) for a great walkthrough.
+
+1. **Clone your fork**
+   ```bash
+   git clone https://github.com/SnowLeopard-AI/snowleopard_py.git
+   cd snowleopard_py
+   ```
+
+2. **Install dependencies**
+   ```bash
+   uv sync --dev
+   ```
+
+3. **Running tests**
+   ```bash
+   uv run pytest
+   ```
+
+### Testing with Different Python Versions
+
+To test against a specific Python version:
+```bash
+uv run --python 3.10 pytest
+```
+
+
+### Re-Recording Cassettes or Writing New Tests
+
+Tests use cassettes to be able to easily mock snowleopard network traffic. No configuration is needed when re-running 
+tests, but to re-record or author new tests a .env file is needed in tests.
+
+```bash
+touch tests/.env
+```
+
+```.dotenv
+#SNOWLEOPARD_LOC=
+#SUPERHEROES_DFID=
+#SNOWLEOPARD_API_KEY=
+SNOWLEOPARD_TEST_RECORD_MODE=once
+```
+See [pyvcr docs](https://vcrpy.readthedocs.io/en/latest/usage.html#record-modes) for more information on recording 
+modes. Once will re-record only if the file is missing, so to re-record you must delete it first.
+

snowleopard-0.2.0/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.2.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: snowleopard
+Version: 0.2.0
+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
+
+This repo contains the Python client library for [Snow Leopard Playground](https://try.snowleopard.ai) APIs. 
+
+See our [API documentation](https://docs.snowleopard.ai/#api-documentation) for more details.
+
+## Installation
+
+```bash
+pip install snowleopard
+```
+
+## Quick Start
+
+```python
+from snowleopard import SnowLeopardClient
+
+# Initialize the client (or AsyncSnowLeopardClient)
+client = SnowLeopardClient(api_key="your-api-key")
+
+# Query your data in natural language
+response = client.retrieve(user_query="How many users signed up last month?", datafile_id="your-datafile-id")
+```
+
+## 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
+    SnowLeopardClient(api_key="your-api-key")
+    ```
+
+## Usage
+
+### Synchronous Client
+
+```python
+from snowleopard import SnowLeopardClient
+
+with SnowLeopardClient() as client:
+   # Get data directly from a natural language query
+   response = client.retrieve(user_query="How many superheroes are there?")
+   print(response.data)
+
+   # Stream natural language summary of live data
+   for chunk in client.response(user_query="How many superheroes are there?"):
+      print(chunk)
+```
+
+### Async Client
+
+```python
+from snowleopard import AsyncSnowLeopardClient
+
+async with AsyncSnowLeopardClient() as client:
+   # Get complete results
+   response = await client.retrieve(user_query="How many superheroes are there?")
+   print(response.data)
+
+   # Get streaming results
+   async for chunk in client.response(user_query="How many superheroes are there?"):
+      print(chunk)
+```
+
+### CLI
+
+The SDK includes a command-line interface:
+
+```bash
+pip install snowleopard
+snowy retrieve --datafile <datafile-id> "How many records are there?"
+snowy response --datafile <datafile-id> "Summarize the data"
+```
+
+### On Premise Customers
+
+For our customers who have a separate deployment per dataset, you should declare <url> explicitly when creating a 
+client and omit <datafile id> when querying.
+
+Example:
+```python
+client = SnowLeopardClient(url="https://{your-vm-ip}:{port}", api_key="your-api-key")
+response = client.retrieve(user_query="How many users signed up last month?")
+```
+
+
+## Contributing
+
+For SDK developer docs and how to contribute, see [CONTRIBUTING.md](CONTRIBUTING.md)

snowleopard-0.2.0/README.md

@@ -0,0 +1,96 @@
+# Snow Leopard SDK for Python
+
+This repo contains the Python client library for [Snow Leopard Playground](https://try.snowleopard.ai) APIs. 
+
+See our [API documentation](https://docs.snowleopard.ai/#api-documentation) for more details.
+
+## Installation
+
+```bash
+pip install snowleopard
+```
+
+## Quick Start
+
+```python
+from snowleopard import SnowLeopardClient
+
+# Initialize the client (or AsyncSnowLeopardClient)
+client = SnowLeopardClient(api_key="your-api-key")
+
+# Query your data in natural language
+response = client.retrieve(user_query="How many users signed up last month?", datafile_id="your-datafile-id")
+```
+
+## 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
+    SnowLeopardClient(api_key="your-api-key")
+    ```
+
+## Usage
+
+### Synchronous Client
+
+```python
+from snowleopard import SnowLeopardClient
+
+with SnowLeopardClient() as client:
+   # Get data directly from a natural language query
+   response = client.retrieve(user_query="How many superheroes are there?")
+   print(response.data)
+
+   # Stream natural language summary of live data
+   for chunk in client.response(user_query="How many superheroes are there?"):
+      print(chunk)
+```
+
+### Async Client
+
+```python
+from snowleopard import AsyncSnowLeopardClient
+
+async with AsyncSnowLeopardClient() as client:
+   # Get complete results
+   response = await client.retrieve(user_query="How many superheroes are there?")
+   print(response.data)
+
+   # Get streaming results
+   async for chunk in client.response(user_query="How many superheroes are there?"):
+      print(chunk)
+```
+
+### CLI
+
+The SDK includes a command-line interface:
+
+```bash
+pip install snowleopard
+snowy retrieve --datafile <datafile-id> "How many records are there?"
+snowy response --datafile <datafile-id> "Summarize the data"
+```
+
+### On Premise Customers
+
+For our customers who have a separate deployment per dataset, you should declare <url> explicitly when creating a 
+client and omit <datafile id> when querying.
+
+Example:
+```python
+client = SnowLeopardClient(url="https://{your-vm-ip}:{port}", api_key="your-api-key")
+response = client.retrieve(user_query="How many users signed up last month?")
+```
+
+
+## Contributing
+
+For SDK developer docs and how to contribute, see [CONTRIBUTING.md](CONTRIBUTING.md)

snowleopard-0.2.0/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "snowleopard"
+dynamic = ["version"]
+
+description = "snowleopard.ai client library"
+
+readme = "README.md"
+license = {file = "LICENSE"}
+
+authors = [
+    { name = "Snowy", email = "hello@snowleopard.ai" }
+]
+
+# list of classifier strings, defined here: https://pypi.org/classifiers/
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+]
+
+requires-python = ">=3.8"
+
+dependencies = [
+    "httpx>=0.28.1",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.5",
+    "pytest-asyncio>=0.24.0",
+    "pytest-recording>=0.13.2",
+    "python-dotenv>=1.0.1",
+    "ruff>=0.14.4",
+]
+
+[project.scripts]
+snowy = "snowleopard.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/snowleopard/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+# NOTE: .gitignore cannot be excluded from the sdist, see:
+#   https://github.com/pypa/hatch/discussions/368
+exclude = [
+    "/.github",
+    "/tests",
+    "/uv.lock",
+    "/.python-version",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = [
+    "src/snowleopard",
+]

snowleopard-0.2.0/src/snowleopard/__init__.py

@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+# copyright 2025 Snow Leopard, Inc
+# released under the MIT license - see LICENSE file
+
+from snowleopard.async_client import AsyncSnowLeopardClient
+from snowleopard.client import SnowLeopardClient
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "SnowLeopardClient",
+    "AsyncSnowLeopardClient",
+]

snowleopard-0.2.0/src/snowleopard/async_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 AsyncGenerator, Optional, Dict, Any
+
+import httpx
+from snowleopard.client_base import SLClientBase
+from snowleopard.models import ResponseDataObjects, RetrieveResponseObjects, parse
+
+
+class AsyncSnowLeopardClient(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,
+        *,
+        user_query: str,
+        known_data: Optional[Dict[str, Any]] = None,
+        datafile_id: Optional[str] = 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,
+        *,
+        known_data: Optional[Dict[str, Any]] = None,
+        user_query: str,
+        datafile_id: Optional[str] = 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-0.2.0/src/snowleopard/cli.py

@@ -0,0 +1,125 @@
+# -*- 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__, SnowLeopardClient
+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(
+            "--datafile", "-df", type=str, help="ID for playground datafile to query"
+        )
+        subparser.add_argument(
+            "--knownData",
+            "-d",
+            action="append",
+            help="Known data in key=value format (can be specified multiple times)",
+        )
+        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 = SnowLeopardClient(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(
+                user_query=parsed_args.question,
+                known_data=known_data,
+                datafile_id=parsed_args.datafile,
+            )
+            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(
+                known_data=known_data,
+                user_query=parsed_args.question,
+                datafile_id=parsed_args.datafile,
+            ):
+                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-0.2.0/src/snowleopard/client.py

@@ -0,0 +1,66 @@
+# -*- 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 SnowLeopardClient(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,
+        *,
+        user_query: str,
+        known_data: Optional[Dict[str, Any]] = None,
+        datafile_id: Optional[str] = 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,
+        *,
+        known_data: Optional[Dict[str, Any]] = None,
+        user_query: str,
+        datafile_id: Optional[str] = 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-0.2.0/src/snowleopard/client_base.py

@@ -0,0 +1,108 @@
+# -*- coding: utf-8 -*-
+# copyright 2025 Snow Leopard, Inc
+# released under the MIT license - see LICENSE file
+
+import os
+from abc import abstractmethod
+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:
+    @abstractmethod
+    def retrieve(
+        self,
+        *,
+        user_query: str,
+        known_data: Optional[Dict[str, Any]] = None,
+        datafile_id: Optional[str] = None,
+    ):
+        """
+        The primary for developers building AI agents that needs to retrieve data from a database directly.
+
+        Takes a natural language question (usually from the user or the agent) and returns the data required to answer
+        the query in an LLM-friendly object.
+
+        :param datafile_id: (optional) The playground datafile-id if hitting a Snow Leopard api directly
+        :param user_query: Natural language query to execute against the Playground datafile
+        :param known_data: Additional context about the user_query
+        """
+        ...
+
+    @abstractmethod
+    def response(
+        self,
+        *,
+        known_data: Optional[Dict[str, Any]] = None,
+        user_query: str,
+        datafile_id: Optional[str] = None,
+    ):
+        """
+        Takes a natural language question (usually from the user or the agent) and returns the data required to answer
+        the query as well as a LLM summary of the returned data.
+
+        :param datafile_id: (optional) The playground datafile-id if hitting a Snow Leopard api directly
+        :param user_query: Natural language query to execute against the Playground datafile
+        :param known_data: (optional) Additional context about the user_query
+        """
+        ...
+
+    @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:
+        if datafile_id is None:
+            return endpoint
+        else:
+            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-0.2.0/src/snowleopard/models.py

@@ -0,0 +1,145 @@
+# -*- 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.0/LICENSE

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

snowleopard-0.1.0/PKG-INFO

@@ -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/README.md

@@ -1 +0,0 @@
-# SnowLeopard-ai python client library

snowleopard-0.1.0/pyproject.toml

@@ -1,39 +0,0 @@
-
-
-[build-system]
-requires = ["setuptools>=61.0.0", "wheel"]
-build-backend = "setuptools.build_meta"
-
-
-[project]
-name = "snowleopard"
-dynamic = ["version"]
-
-description = "snowleopard.ai client library"
-
-readme = "README.md"
-license = {file = "LICENSE"}
-
-# list of classifier strings, defined here: https://pypi.org/classifiers/
-classifiers = [
-	"Development Status :: 1 - Planning",
-	"Environment :: Console",
-	"Intended Audience :: Developers",
-	]
-
-# see https://devguide.python.org/versions/#versions for end-of-life dates
-# next update: 3.8 EoL is 2024-10
-requires-python = ">=3.8"
-
-dependencies = [
-	"importlib_metadata >= 4.6 ; python_version < '3.10'"
-	]
-
-
-[tool.setuptools]
-
-[tool.setuptools.packages.find]
-where = ["src"]
-
-[tool.setuptools.dynamic]
-version = { attr = "snowleopard.__version__" }

snowleopard-0.1.0/setup.cfg

@@ -1,4 +0,0 @@
-[egg_info]
-tag_build = 
-tag_date = 0
-

snowleopard-0.1.0/src/snowleopard/__init__.py

@@ -1,5 +0,0 @@
-# -*- coding: utf-8 -*-
-# copyright 2024 Snow Leopard, Inc - all rights reserved
-
-
-__version__ = '0.1.0'

snowleopard-0.1.0/src/snowleopard.egg-info/PKG-INFO

@@ -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/src/snowleopard.egg-info/SOURCES.txt

@@ -1,9 +0,0 @@
-LICENSE
-README.md
-pyproject.toml
-src/snowleopard/__init__.py
-src/snowleopard.egg-info/PKG-INFO
-src/snowleopard.egg-info/SOURCES.txt
-src/snowleopard.egg-info/dependency_links.txt
-src/snowleopard.egg-info/requires.txt
-src/snowleopard.egg-info/top_level.txt

snowleopard-0.1.0/src/snowleopard.egg-info/dependency_links.txt

@@ -1 +0,0 @@
-

snowleopard-0.1.0/src/snowleopard.egg-info/requires.txt

@@ -1,3 +0,0 @@
-
-[:python_version < "3.10"]
-importlib_metadata>=4.6

snowleopard-0.1.0/src/snowleopard.egg-info/top_level.txt

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