definite-sdk 0.1.4__py3-none-any.whl → 0.1.9__py3-none-any.whl

definite_sdk/__init__.py

@@ -0,0 +1,22 @@
+"""
+Definite SDK for Python
+
+A Python library for interacting with the Definite API and tools.
+"""
+
+from definite_sdk.client import DefiniteClient
+from definite_sdk.integration import DefiniteIntegrationStore
+from definite_sdk.message import DefiniteMessageClient
+from definite_sdk.secret import DefiniteSecretStore
+from definite_sdk.sql import DefiniteSqlClient
+from definite_sdk.store import DefiniteKVStore
+
+__version__ = "0.1.9"
+__all__ = [
+    "DefiniteClient",
+    "DefiniteIntegrationStore",
+    "DefiniteMessageClient",
+    "DefiniteSecretStore",
+    "DefiniteSqlClient",
+    "DefiniteKVStore",
+]

definite_sdk/client.py

@@ -1,5 +1,10 @@
+import os
+from typing import Optional
+
 from definite_sdk.integration import DefiniteIntegrationStore
+from definite_sdk.message import DefiniteMessageClient
 from definite_sdk.secret import DefiniteSecretStore
+from definite_sdk.sql import DefiniteSqlClient
 from definite_sdk.store import DefiniteKVStore
 
 API_URL = "https://api.definite.app"
@@ -8,11 +13,24 @@ API_URL = "https://api.definite.app"
 class DefiniteClient:
     """Client for interacting with the Definite API."""
 
-    def __init__(self, api_key: str, api_url: str = API_URL):
+    def __init__(self, api_key: Optional[str] = None, api_url: str = API_URL):
         """Creates a definite client with the provided API key.
 
+        Args:
+            api_key: API key for authentication. If not provided, will look for
+                    DEFINITE_API_KEY or DEF_API_KEY environment variables.
+            api_url: Base URL for the Definite API.
+
         See: https://docs.definite.app/definite-api for how to obtain an API key.
         """
+        if api_key is None:
+            api_key = os.getenv("DEFINITE_API_KEY") or os.getenv("DEF_API_KEY")
+            if not api_key:
+                raise ValueError(
+                    "API key must be provided or set in DEFINITE_API_KEY "
+                    "or DEF_API_KEY environment variable"
+                )
+
         self.api_key = api_key
         self.api_url = api_url
 
@@ -39,3 +57,36 @@ class DefiniteClient:
         """
 
         return DefiniteIntegrationStore(self.api_key, self.api_url)
+
+    def get_sql_client(self) -> DefiniteSqlClient:
+        """Initializes the SQL client for executing SQL queries.
+
+        See DefiniteSqlClient for more how to execute SQL queries.
+        """
+
+        return DefiniteSqlClient(self.api_key, self.api_url)
+
+    # Alias methods for consistency
+    def kv_store(self, name: str) -> DefiniteKVStore:
+        """Alias for get_kv_store."""
+        return self.get_kv_store(name)
+
+    def secret_store(self) -> DefiniteSecretStore:
+        """Alias for get_secret_store."""
+        return self.get_secret_store()
+
+    def integration_store(self) -> DefiniteIntegrationStore:
+        """Alias for get_integration_store."""
+        return self.get_integration_store()
+
+    def get_message_client(self) -> DefiniteMessageClient:
+        """Initializes the message client for sending messages via various channels.
+
+        See DefiniteMessageClient for more how to send messages.
+        """
+
+        return DefiniteMessageClient(self.api_key, self.api_url)
+
+    def message_client(self) -> DefiniteMessageClient:
+        """Alias for get_message_client."""
+        return self.get_message_client()

definite_sdk/dlt.py

@@ -0,0 +1,237 @@
+"""DLT (Data Load Tool) integration for Definite SDK."""
+
+import os
+import json
+from typing import Any, Dict, Optional, Tuple, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import dlt
+    from dlt.common import Destination
+    from dlt.pipeline import Pipeline
+else:
+    try:
+        import dlt
+        from dlt.common import Destination
+        from dlt.pipeline import Pipeline
+    except ImportError:
+        dlt = None  # type: ignore
+        Destination = None  # type: ignore
+        Pipeline = None  # type: ignore
+
+from .client import DefiniteClient
+
+
+class DefiniteDLTPipeline:
+    """Wrapper for DLT pipelines with Definite state management."""
+
+    def __init__(
+        self,
+        name: str,
+        dataset_name: Optional[str] = None,
+        destination: Optional["Destination"] = None,
+        **kwargs: Any,
+    ):
+        """Initialize a DLT pipeline with Definite integration.
+
+        Args:
+            name: Pipeline name
+            dataset_name: Dataset name for the destination
+            destination: DLT destination (defaults to duckdb)
+            **kwargs: Additional arguments passed to dlt.pipeline()
+        """
+        if dlt is None:
+            raise ImportError(
+                "dlt package not installed. Install with: pip install definite-sdk[dlt]"
+            )
+
+        self.name = name
+        self._client = DefiniteClient()
+        self._state_store = self._client.kv_store(f"dlt_state_{name}")
+
+        # Default to DuckDB if no destination specified
+        if destination is None:
+            destination = "duckdb"
+
+        # Use dataset_name or default to pipeline name
+        if dataset_name is None:
+            dataset_name = name
+
+        # Create the underlying DLT pipeline
+        self._pipeline = dlt.pipeline(
+            pipeline_name=name,
+            destination=destination,
+            dataset_name=dataset_name,
+            **kwargs,
+        )
+
+    @property
+    def pipeline(self) -> "Pipeline":
+        """Get the underlying DLT pipeline."""
+        return self._pipeline
+
+    @property
+    def state(self) -> Dict[str, Any]:
+        """Get the current pipeline state."""
+        return dict(self._pipeline.state)
+
+    def run(
+        self,
+        data: Any,
+        *,
+        table_name: Optional[str] = None,
+        write_disposition: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Run the pipeline with the given data.
+
+        Args:
+            data: Data to load (resource, source, or iterator)
+            table_name: Name of the table to load data into
+            write_disposition: How to write data (append, replace, merge)
+            **kwargs: Additional arguments passed to pipeline.run()
+
+        Returns:
+            Load info from the pipeline run
+        """
+        # Run the pipeline
+        load_info = self._pipeline.run(
+            data, table_name=table_name, write_disposition=write_disposition, **kwargs
+        )
+
+        # Persist state to Definite after successful run
+        self._persist_state()
+
+        return load_info
+
+    def _persist_state(self) -> None:
+        """Persist current pipeline state to Definite."""
+        state = self._pipeline.state
+        if state:
+            # Store each state key separately for easier access
+            for key, value in state.items():
+                # Serialize value to JSON string
+                self._state_store[key] = json.dumps(value)
+            self._state_store.commit()
+
+    def get_state(self, key: Optional[str] = None) -> Any:
+        """Retrieve state from Definite store.
+
+        Args:
+            key: Specific state key to retrieve. If None, returns all state.
+
+        Returns:
+            State value or entire state dict
+        """
+        if key is not None:
+            value = self._state_store.get(key, None)
+            return json.loads(value) if value else None
+
+        # Return all state as dict
+        return {k: json.loads(self._state_store[k]) for k in self._state_store}
+
+    def set_state(self, key: str, value: Any) -> None:
+        """Set a state value.
+
+        Args:
+            key: State key
+            value: State value
+        """
+        self._pipeline.state[key] = value
+        # Also persist to Definite immediately
+        self._state_store[key] = json.dumps(value)
+        self._state_store.commit()
+
+    def resume_from_state(self) -> None:
+        """Resume pipeline from previously stored state."""
+        # Load state from Definite
+        stored_state: Dict[str, Any] = {
+            k: json.loads(self._state_store[k]) for k in self._state_store
+        }
+
+        # Apply state to pipeline
+        for key, value in stored_state.items():
+            self._pipeline.state[key] = value
+
+    def reset_state(self) -> None:
+        """Reset pipeline state."""
+        # Clear pipeline state
+        self._pipeline.state.clear()
+
+        # Clear Definite state
+        keys_to_delete = list(self._state_store)
+        for key in keys_to_delete:
+            del self._state_store[key]
+        self._state_store.commit()
+
+
+class DLTStateAdapter:
+    """Adapter for DLT state management conforming to Definite patterns."""
+
+    def __init__(self, pipeline_name: str):
+        """Initialize state adapter.
+
+        Args:
+            pipeline_name: Name of the DLT pipeline
+        """
+        self.pipeline_name = pipeline_name
+        self._client = DefiniteClient()
+        self._store = self._client.kv_store(f"dlt_state_{pipeline_name}")
+
+    def save_state(self, state: Dict[str, Any]) -> None:
+        """Save pipeline state.
+
+        Args:
+            state: State dictionary to save
+        """
+        for key, value in state.items():
+            self._store[key] = json.dumps(value)
+        self._store.commit()
+
+    def load_state(self) -> Dict[str, Any]:
+        """Load pipeline state.
+
+        Returns:
+            State dictionary
+        """
+        return {k: json.loads(self._store[k]) for k in self._store}
+
+    def clear_state(self) -> None:
+        """Clear all state."""
+        keys_to_delete = list(self._store)
+        for key in keys_to_delete:
+            del self._store[key]
+        self._store.commit()
+
+
+def get_duckdb_connection() -> Optional[Tuple[str, Any]]:
+    """Get DuckDB connection from Definite integration.
+
+    Uses the DEFINITE_API_KEY environment variable to authenticate and
+    lookup the team's DuckDB integration.
+
+    Returns:
+        Optional[Tuple[str, Any]]: Tuple of (integration_id, connection) if found,
+                                   None if no DuckDB integration or API key.
+    """
+    api_key = os.getenv("DEFINITE_API_KEY")
+    if not api_key:
+        return None
+
+    try:
+        import duckdb
+    except ImportError:
+        raise ImportError(
+            "duckdb package not installed. Install with: pip install duckdb"
+        )
+
+    client = DefiniteClient(api_key=api_key)
+    integration_store = client.integration_store()
+
+    result = integration_store.lookup_duckdb_integration()
+    if result:
+        integration_id, connection_uri = result
+        # Create DuckDB connection
+        connection = duckdb.connect(connection_uri)
+        return (integration_id, connection)
+
+    return None

definite_sdk/integration.py

@@ -1,8 +1,8 @@
-from typing import Iterator
+from typing import Iterator, Optional, Tuple
 
 import requests
 
-SECRET_STORE_ENDPOINT = "/v1/api/integration"
+INTEGRATION_ENDPOINT = "/v1/api/integration"
 
 
 class DefiniteIntegrationStore:
@@ -26,8 +26,8 @@ class DefiniteIntegrationStore:
             api_key (str): The API key for authorization.
         """
         self._api_key = api_key
-        self._integration_store_url = api_url + SECRET_STORE_ENDPOINT
-    
+        self._integration_store_url = api_url + INTEGRATION_ENDPOINT
+
     def list_integrations(self) -> Iterator[dict]:
         """
         Lists all integrations in the store.
@@ -57,4 +57,43 @@ class DefiniteIntegrationStore:
             headers={"Authorization": "Bearer " + self._api_key},
         )
         response.raise_for_status()
-        return response.json()
+        return dict(response.json())
+
+    def lookup_duckdb_integration(self) -> Optional[Tuple[str, str]]:
+        """
+        Look up the team's DuckDB integration.
+        
+        Note: Currently, the API only returns extractor (source) integrations.
+        Destination integrations like DuckDB are not yet exposed through this endpoint.
+        This method is provided for future compatibility when the API is updated.
+
+        Returns:
+            Optional[Tuple[str, str]]: Tuple of (integration_id, connection_uri)
+                if found, None if no DuckDB integration exists.
+        """
+        try:
+            response = requests.get(
+                self._integration_store_url,
+                headers={"Authorization": "Bearer " + self._api_key},
+            )
+            response.raise_for_status()
+            integrations = response.json()
+        except:
+            return None
+
+        # Check for DuckDB in the integrations
+        # Note: Currently this will not find DuckDB as it's a destination integration
+        for integration in integrations:
+            integration_type = integration.get("integration_type", "").lower()
+            if integration_type == "duckdb" and integration.get("active", True):
+                integration_id = integration.get("id")
+                # Connection URI might be in config or connection_string field
+                connection_uri = (
+                    integration.get("connection_string")
+                    or integration.get("config", {}).get("database_path")
+                    or integration.get("config", {}).get("connection_string")
+                )
+                if integration_id and connection_uri:
+                    return (integration_id, connection_uri)
+
+        return None

definite_sdk/message.py

@@ -0,0 +1,199 @@
+from typing import Any, Dict, List, Optional
+
+import requests
+
+MESSAGE_ENDPOINT = "/v3"
+
+
+class DefiniteMessageClient:
+    """
+    A message client for sending messages via various channels through the Definite API.
+
+    Initialization:
+    >>> client = DefiniteClient("MY_API_KEY")
+    >>> message_client = client.get_message_client()
+
+    Sending messages:
+    >>> # Send a Slack message
+    >>> result = message_client.send_message(
+    ...     channel="slack",
+    ...     integration_id="slack_integration_id",
+    ...     to="C0920MVPWFN",  # channel_id
+    ...     content="Hello from Definite SDK!"
+    ... )
+    
+    >>> # Send a Slack message with blocks and thread
+    >>> result = message_client.send_message(
+    ...     channel="slack",
+    ...     integration_id="slack_integration_id",
+    ...     to="C0920MVPWFN",
+    ...     content="Hello!",
+    ...     blocks=[{"type": "section", "text": {"type": "mrkdwn", "text": "Hello!"}}],
+    ...     thread_ts="1234567890.123456"
+    ... )
+    """
+
+    def __init__(self, api_key: str, api_url: str):
+        """
+        Initializes the DefiniteMessageClient.
+
+        Args:
+            api_key (str): The API key for authorization.
+            api_url (str): The base URL for the Definite API.
+        """
+        self._api_key = api_key
+        self._message_url = api_url + MESSAGE_ENDPOINT
+
+    def send_message(
+        self,
+        channel: str,
+        integration_id: str,
+        to: str,
+        content: str,
+        subject: Optional[str] = None,
+        blocks: Optional[List[Dict[str, Any]]] = None,
+        thread_ts: Optional[str] = None,
+        **kwargs: Any
+    ) -> Dict[str, Any]:
+        """
+        Sends a message through the specified channel.
+
+        Args:
+            channel (str): The messaging channel to use (e.g., "slack", "email").
+            integration_id (str): The ID of the integration to use.
+            to (str): The recipient identifier (channel_id for Slack, email address for email).
+            content (str): The message content (text for Slack, body for email).
+            subject (Optional[str]): Subject line (used for email).
+            blocks (Optional[List[Dict[str, Any]]]): Slack Block Kit blocks for formatting.
+            thread_ts (Optional[str]): Slack thread timestamp to reply to.
+            **kwargs: Additional channel-specific parameters.
+
+        Returns:
+            Dict[str, Any]: The response from the API.
+
+        Raises:
+            requests.HTTPError: If the API request fails.
+            ValueError: If the channel is not supported.
+
+        Example:
+            >>> # Slack message
+            >>> result = message_client.send_message(
+            ...     channel="slack",
+            ...     integration_id="slack_123",
+            ...     to="C0920MVPWFN",
+            ...     content="Hello team!"
+            ... )
+            
+            >>> # Slack message with blocks
+            >>> result = message_client.send_message(
+            ...     channel="slack",
+            ...     integration_id="slack_123",
+            ...     to="C0920MVPWFN",
+            ...     content="Fallback text",
+            ...     blocks=[{
+            ...         "type": "section",
+            ...         "text": {"type": "mrkdwn", "text": "*Important Update*"}
+            ...     }]
+            ... )
+        """
+        channel_lower = channel.lower()
+        
+        if channel_lower == "slack":
+            return self._send_slack_message(
+                integration_id=integration_id,
+                channel_id=to,
+                text=content,
+                blocks=blocks,
+                thread_ts=thread_ts,
+                **kwargs
+            )
+        else:
+            raise ValueError(f"Unsupported channel: {channel}")
+
+    def _send_slack_message(
+        self,
+        integration_id: str,
+        channel_id: str,
+        text: str,
+        blocks: Optional[List[Dict[str, Any]]] = None,
+        thread_ts: Optional[str] = None,
+        **kwargs: Any
+    ) -> Dict[str, Any]:
+        """
+        Internal method to send a Slack message.
+
+        Args:
+            integration_id (str): The Slack integration ID.
+            channel_id (str): The Slack channel ID.
+            text (str): The message text.
+            blocks (Optional[List[Dict[str, Any]]]): Slack blocks for formatting.
+            thread_ts (Optional[str]): Thread timestamp for replies.
+            **kwargs: Additional Slack-specific parameters.
+
+        Returns:
+            Dict[str, Any]: The API response.
+        """
+        url = f"{self._message_url}/slack/message"
+        
+        payload = {
+            "integration_id": integration_id,
+            "channel_id": channel_id,
+            "text": text
+        }
+        
+        if blocks:
+            payload["blocks"] = blocks
+        if thread_ts:
+            payload["thread_ts"] = thread_ts
+            
+        # Add any additional kwargs to the payload
+        payload.update(kwargs)
+
+        response = requests.post(
+            url,
+            json=payload,
+            headers={"Authorization": "Bearer " + self._api_key},
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def send_slack_message(
+        self,
+        integration_id: str,
+        channel_id: str,
+        text: str,
+        blocks: Optional[List[Dict[str, Any]]] = None,
+        thread_ts: Optional[str] = None,
+        **kwargs: Any
+    ) -> Dict[str, Any]:
+        """
+        Convenience method to send a Slack message directly.
+
+        Args:
+            integration_id (str): The Slack integration ID.
+            channel_id (str): The Slack channel ID.
+            text (str): The message text.
+            blocks (Optional[List[Dict[str, Any]]]): Slack blocks for formatting.
+            thread_ts (Optional[str]): Thread timestamp for replies.
+            **kwargs: Additional Slack-specific parameters.
+
+        Returns:
+            Dict[str, Any]: The API response.
+
+        Example:
+            >>> result = message_client.send_slack_message(
+            ...     integration_id="slack_123",
+            ...     channel_id="C0920MVPWFN",
+            ...     text="Hello from Definite SDK! 👋"
+            ... )
+            >>> print(f"Message sent! Timestamp: {result['ts']}")
+        """
+        return self.send_message(
+            channel="slack",
+            integration_id=integration_id,
+            to=channel_id,
+            content=text,
+            blocks=blocks,
+            thread_ts=thread_ts,
+            **kwargs
+        )

definite_sdk/secret.py

@@ -47,7 +47,7 @@ class DefiniteSecretStore:
         )
         response.raise_for_status()
         return iter(response.json()["secrets"])
-    
+
     def get_secret(self, key: str) -> str:
         """
         Retrieves the value of a secret.
@@ -63,8 +63,8 @@ class DefiniteSecretStore:
             headers={"Authorization": "Bearer " + self._api_key},
         )
         response.raise_for_status()
-        return response.json()["value"]
-    
+        return str(response.json()["value"])
+
     def set_secret(self, key: str, value: str):
         """
         Sets the value of a secret.

definite_sdk/sql.py

@@ -0,0 +1,126 @@
+from typing import Any, Dict, List, Optional, Union
+
+import requests
+
+SQL_ENDPOINT = "/v1/query"
+
+
+class DefiniteSqlClient:
+    """
+    A SQL client for executing SQL queries via the Definite API.
+
+    Initialization:
+    >>> client = DefiniteClient("MY_API_KEY")
+    >>> sql_client = client.get_sql_client()
+
+    Executing SQL queries:
+    >>> result = sql_client.execute("SELECT * FROM my_table LIMIT 10")
+    >>> print(result)
+
+    Executing SQL queries with integration ID:
+    >>> result = sql_client.execute(
+    ...     "SELECT * FROM my_table LIMIT 10",
+    ...     integration_id="my_integration_id"
+    ... )
+    >>> print(result)
+
+    Executing Cube queries:
+    >>> cube_query = {
+    ...     "dimensions": [],
+    ...     "measures": ["sales.total_amount"],
+    ...     "timeDimensions": [{"dimension": "sales.date", "granularity": "month"}],
+    ...     "limit": 1000
+    ... }
+    >>> result = sql_client.execute_cube_query(cube_query, integration_id="my_cube_integration")
+    >>> print(result)
+    """
+
+    def __init__(self, api_key: str, api_url: str):
+        """
+        Initializes the DefiniteSqlClient.
+
+        Args:
+            api_key (str): The API key for authorization.
+            api_url (str): The base URL for the Definite API.
+        """
+        self._api_key = api_key
+        self._sql_url = api_url + SQL_ENDPOINT
+
+    def execute(
+        self, 
+        sql: str, 
+        integration_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Executes a SQL query against a database integration.
+
+        Args:
+            sql (str): The SQL query to execute.
+            integration_id (Optional[str]): The integration ID to query against.
+                If not provided, the default integration will be used.
+
+        Returns:
+            Dict[str, Any]: The query result as returned by the API.
+
+        Raises:
+            requests.HTTPError: If the API request fails.
+
+        Example:
+            >>> result = sql_client.execute("SELECT COUNT(*) FROM users")
+            >>> print(result)
+        """
+        payload = {"sql": sql}
+        if integration_id:
+            payload["integration_id"] = integration_id
+
+        response = requests.post(
+            self._sql_url,
+            json=payload,
+            headers={"Authorization": "Bearer " + self._api_key},
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def execute_cube_query(
+        self, 
+        cube_query: Dict[str, Any], 
+        integration_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Executes a Cube query against a Cube integration.
+
+        Args:
+            cube_query (Dict[str, Any]): The Cube query in JSON format.
+            integration_id (Optional[str]): The Cube integration ID to query against.
+                If not provided, the default integration will be used.
+
+        Returns:
+            Dict[str, Any]: The query result as returned by the API.
+
+        Raises:
+            requests.HTTPError: If the API request fails.
+
+        Example:
+            >>> cube_query = {
+            ...     "dimensions": [],
+            ...     "measures": ["sales.total_amount"],
+            ...     "timeDimensions": [{
+            ...         "dimension": "sales.date",
+            ...         "granularity": "month"
+            ...     }],
+            ...     "limit": 1000
+            ... }
+            >>> result = sql_client.execute_cube_query(cube_query, "my_cube_integration")
+            >>> print(result)
+        """
+        payload = {"cube_query": cube_query}
+        if integration_id:
+            payload["integration_id"] = integration_id
+
+        response = requests.post(
+            self._sql_url,
+            json=payload,
+            headers={"Authorization": "Bearer " + self._api_key},
+        )
+        response.raise_for_status()
+        return response.json()

definite_sdk/store.py

@@ -1,4 +1,4 @@
-from typing import Iterator
+from typing import Iterator, Union, Optional
 
 import requests
 
@@ -109,7 +109,7 @@ class DefiniteKVStore:
         self._data = {}
         self._version_id = None
 
-    def __getitem__(self, key: str) -> str | None:
+    def __getitem__(self, key: str) -> Optional[str]:
         """
         Gets the value for a given key.
 
@@ -190,3 +190,19 @@ class DefiniteKVStore:
             print(store)
         """
         return repr(self._data)
+
+    def get(self, key: str, default: Optional[str] = None) -> Optional[str]:
+        """
+        Gets the value for a given key with a default.
+
+        Args:
+            key (str): The key to retrieve the value for.
+            default: The default value to return if key doesn't exist.
+
+        Returns:
+            The value associated with the key, or default if the key does not exist.
+
+        Example:
+            value = store.get("key1", "default_value")
+        """
+        return self._data.get(key, default)

definite_sdk-0.1.9.dist-info/METADATA

@@ -0,0 +1,314 @@
+Metadata-Version: 2.3
+Name: definite-sdk
+Version: 0.1.9
+Summary: Definite SDK for Python
+License: MIT
+Author: Definite
+Author-email: hello@definite.app
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.13
+Provides-Extra: dlt
+Requires-Dist: dlt (>=1.0,<2.0) ; extra == "dlt"
+Requires-Dist: duckdb (>=1.0,<2.0) ; extra == "dlt"
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+# Definite SDK
+
+A Python client for interacting with the Definite API, providing a convenient interface for key-value store operations, SQL query execution, secrets management, messaging capabilities, and DLT (Data Load Tool) integration with state persistence.
+
+## Installation
+
+**pip:**
+```bash
+pip install definite-sdk
+
+# For dlt support
+pip install "definite-sdk[dlt]"
+```
+
+**poetry:**
+```bash
+poetry add definite-sdk
+
+# For dlt support
+poetry add "definite-sdk[dlt]"
+```
+
+## Quick Start
+
+```python
+from definite_sdk import DefiniteClient
+
+# Initialize the client
+client = DefiniteClient("YOUR_API_KEY")
+```
+
+## Features
+
+- **Key-Value Store**: Persistent storage with version control and transactional commits
+- **SQL Query Execution**: Execute SQL queries against your connected database integrations
+- **Cube Query Execution**: Execute Cube queries for advanced analytics and data modeling
+- **Secret Management**: Secure storage and retrieval of application secrets
+- **Integration Store**: Read-only access to integration configurations
+- **Messaging**: Send messages through various channels (Slack, and more coming soon)
+- **dlt Integration**: Run dlt pipelines with automatic state persistence to Definite
+- **DuckDB Support**: Automatic discovery and connection to team's DuckDB integrations
+
+## Basic Usage
+
+### 🗄️ Key-Value Store
+
+Store and retrieve key-value pairs that can be accessed by custom Python scripts hosted on Definite.
+
+```python
+# Initialize or retrieve an existing key-value store
+store = client.get_kv_store('test_store')
+# Or use the alias method
+store = client.kv_store('test_store')
+
+# Add or update key-value pairs
+store['replication_key'] = 'created_at'
+store['replication_state'] = '2024-05-20'
+store["key1"] = "value1"
+store["key2"] = {"nested": "data"}
+
+# Commit changes
+store.commit()
+
+# Retrieve values
+print(store['replication_key'])  # 'created_at'
+value = store["key1"]
+```
+
+### 🗃️ SQL Query Execution
+
+Execute SQL queries against your connected database integrations.
+
+```python
+# Initialize the SQL client
+sql_client = client.get_sql_client()
+
+# Execute a SQL query
+result = sql_client.execute("SELECT * FROM users LIMIT 10")
+print(result)
+
+# Execute a SQL query with a specific integration
+result = sql_client.execute(
+    "SELECT COUNT(*) FROM orders WHERE status = 'completed'",
+    integration_id="my_database_integration"
+)
+print(result)
+```
+
+### 📊 Cube Query Execution
+
+Execute Cube queries for advanced analytics and data modeling.
+
+```python
+# Prepare a Cube query
+cube_query = {
+    "dimensions": [],
+    "measures": ["sales.total_amount"],
+    "timeDimensions": [{
+        "dimension": "sales.date", 
+        "granularity": "month"
+    }],
+    "limit": 1000
+}
+
+# Execute the Cube query
+result = sql_client.execute_cube_query(
+    cube_query, 
+    integration_id="my_cube_integration"
+)
+print(result)
+```
+
+### 🔒 Secret Store
+
+Securely store and retrieve secrets for your integrations.
+
+```python
+# Initialize the secret store
+secret_store = client.get_secret_store()
+# Or use the alias method
+secret_store = client.secret_store()
+
+# Set a secret
+secret_store.set_secret("database_password", "my_secure_password")
+
+# Get a secret
+password = secret_store.get_secret("database_password")
+
+# List all secrets
+secrets = list(secret_store.list_secrets())
+```
+
+### 🔗 Integration Management
+
+Manage your data integrations and connections.
+
+```python
+# Initialize the integration store
+integration_store = client.get_integration_store()
+# Or use the alias method
+integration_store = client.integration_store()
+
+# List all integrations
+integrations = list(integration_store.list_integrations())
+
+# Get a specific integration
+integration = integration_store.get_integration("my_integration")
+```
+
+### 💬 Messaging
+
+Send messages through various channels using the messaging client.
+
+```python
+# Initialize the message client
+message_client = client.get_message_client()
+# Or use the alias method
+message_client = client.message_client()
+
+# Send a Slack message using the unified interface
+result = message_client.send_message(
+    channel="slack",
+    integration_id="your_slack_integration_id",
+    to="C0920MVPWFN",  # Slack channel ID
+    content="Hello from Definite SDK! 👋"
+)
+
+# Send a Slack message with blocks and threading
+result = message_client.send_message(
+    channel="slack",
+    integration_id="your_slack_integration_id",
+    to="C0920MVPWFN",
+    content="Fallback text",
+    blocks=[{
+        "type": "section",
+        "text": {"type": "mrkdwn", "text": "*Important Update*"}
+    }],
+    thread_ts="1234567890.123456"  # Reply in thread
+)
+
+# Or use the convenience method for Slack
+result = message_client.send_slack_message(
+    integration_id="your_slack_integration_id",
+    channel_id="C0920MVPWFN",
+    text="Quick message using the convenience method!",
+    blocks=[{
+        "type": "section",
+        "text": {"type": "mrkdwn", "text": "Message with *rich* _formatting_"}
+    }]
+)
+```
+
+### dlt Integration
+
+```python
+from definite_sdk.dlt import DefiniteDLTPipeline
+import dlt
+
+# Create an incremental resource
+@dlt.resource(primary_key="id", write_disposition="merge")
+def orders(cursor=dlt.sources.incremental("created_at")):
+    # Your data loading logic here
+    pass
+
+# Create and run pipeline
+pipeline = DefiniteDLTPipeline("orders_sync")
+pipeline.run(orders())
+
+# State is automatically persisted to Definite
+last_cursor = pipeline.get_state("orders")
+```
+
+### DuckDB Integration Discovery
+
+```python
+from definite_sdk.dlt import get_duckdb_connection
+
+# Automatically discovers DuckDB integration using DEFINITE_API_KEY env var
+result = get_duckdb_connection()
+if result:
+    integration_id, connection = result
+    # Use the DuckDB connection
+    connection.execute("SELECT * FROM my_table")
+```
+
+**Note**: DuckDB integration discovery is currently limited as the API only exposes source integrations, not destination integrations. This functionality is provided for future compatibility.
+
+### State Management
+
+```python
+# Set custom state
+pipeline.set_state("custom_key", "custom_value")
+
+# Get all state
+all_state = pipeline.get_state()
+
+# Resume from previous state
+pipeline.resume_from_state()
+
+# Reset state
+pipeline.reset_state()
+```
+
+## Authentication
+
+To use the Definite SDK, you'll need an API key. You can find and copy your API key from the bottom left user menu in your Definite workspace.
+
+For SQL queries, you'll also need your integration ID, which can be found in your integration's page URL.
+
+## Environment Variables
+
+- `DEFINITE_API_KEY`: Your Definite API key (auto-injected in Definite runtime)
+- `DEF_API_KEY`: Alternative environment variable for API key
+
+## Error Handling
+
+The SDK uses standard HTTP status codes and raises `requests.HTTPError` for API errors:
+
+```python
+import requests
+
+try:
+    result = sql_client.execute("SELECT * FROM invalid_table")
+except requests.HTTPError as e:
+    print(f"API Error: {e}")
+```
+
+## Testing
+
+```bash
+# Run all tests
+DEF_API_KEY=your_api_key poetry run pytest
+
+# Run specific test file
+DEF_API_KEY=your_api_key poetry run pytest tests/test_dlt.py
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License.
+
+## Documentation
+
+For more detailed documentation, visit: https://docs.definite.app/
+
+## Support
+
+If you encounter any issues or have questions, please reach out to hello@definite.app
+

definite_sdk-0.1.9.dist-info/RECORD

@@ -0,0 +1,13 @@
+definite_sdk/__init__.py,sha256=Y3GwfDOkpWt6EILoZ7PRT7nXuoVnk0zHrNOPHlkEHS4,604
+definite_sdk/client.py,sha256=2wRrFFwMMeGfP5riaEGhCLk1OiyBsJj_uMqFb3hIooY,3199
+definite_sdk/dlt.py,sha256=JC-S1jd6zqnpGSnvk9kYb8GQ1IPZRd1zVKTVYAbeA4w,7188
+definite_sdk/integration.py,sha256=v15QIpWm3eAZr-cmavfA39LXTjpskEEQ2SM_TBV4E1U,3395
+definite_sdk/message.py,sha256=I3qx2v9gIcC9NZyr5zEp_Seft8clRoER4WeUbAaDiFc,6549
+definite_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+definite_sdk/secret.py,sha256=3wvEnTZ946hOxJBdB29dxvppwJ0x-TJV_LxRcXGqtis,2503
+definite_sdk/sql.py,sha256=K5cPXM7B60Fzd8CyI-B4rXwK7hLpLT1Z8XZSZJjSogQ,3878
+definite_sdk/store.py,sha256=7VYvROIrlWyM_ZX3LpqWWAfVLNDm0XMccMLv6qi9id8,5575
+definite_sdk-0.1.9.dist-info/LICENSE,sha256=jMd7PtwNWiMoGIDgFutC1v4taO69W9SRZLKe9o470Vk,1064
+definite_sdk-0.1.9.dist-info/METADATA,sha256=jZfdfG0EFt7kfN6HpbSCnAzhZHBrEy7SV7WKH-K0LVU,8196
+definite_sdk-0.1.9.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+definite_sdk-0.1.9.dist-info/RECORD,,

{definite_sdk-0.1.4.dist-info → definite_sdk-0.1.9.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 1.9.0
+Generator: poetry-core 2.1.3
 Root-Is-Purelib: true
 Tag: py3-none-any

definite_sdk-0.1.4.dist-info/METADATA

@@ -1,21 +0,0 @@
-Metadata-Version: 2.1
-Name: definite-sdk
-Version: 0.1.4
-Summary: Definite SDK for Python
-License: MIT
-Author: Definite
-Author-email: hello@definite.app
-Requires-Python: >=3.9,<4.0
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: requests (>=2.31.0,<3.0.0)
-Description-Content-Type: text/markdown
-
-# Definite SDK
-
-A Python client for interacting with the Definite API, providing a convenient interface for key-value store operations.
-

definite_sdk-0.1.4.dist-info/RECORD

@@ -1,8 +0,0 @@
-definite_sdk/client.py,sha256=DjckW-kZOGSQ5RKwRfpPub_ucxAcUaTLknZz5YKe4nE,1354
-definite_sdk/integration.py,sha256=z7i_q9m5dMNJPG3_J29aH1jov0b5u6rhO3IZj1V9KVg,1647
-definite_sdk/secret.py,sha256=pgRzY40MwOaZBVEw-yQPWX3ag1B7AMoCJKJjzcLQnTs,2506
-definite_sdk/store.py,sha256=FimC3RqLtiJc3PlOSORCIiMFaUcNtc-r45c54j3l92g,5034
-definite_sdk-0.1.4.dist-info/LICENSE,sha256=jMd7PtwNWiMoGIDgFutC1v4taO69W9SRZLKe9o470Vk,1064
-definite_sdk-0.1.4.dist-info/METADATA,sha256=PWkSNNRsjSKb1oU0a32FPUtqnP010jriQfRlI67p0i4,702
-definite_sdk-0.1.4.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-definite_sdk-0.1.4.dist-info/RECORD,,