salesforce-data-customcode 6.0.5.dev1__tar.gz → 6.0.6.dev2__tar.gz

{salesforce_data_customcode-6.0.5.dev1 → salesforce_data_customcode-6.0.6.dev2}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: salesforce-data-customcode
-Version: 6.0.5.dev1
+Version: 6.0.6.dev2
 Summary: Data Cloud Custom Code SDK
 License-Expression: Apache-2.0
 License-File: LICENSE.txt
 Requires-Python: >=3.10,<3.12
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Operating System :: Unix
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
@@ -23,7 +23,7 @@ Requires-Dist: salesforce-cdp-connector (>=1.0.19)
 Requires-Dist: setuptools_scm (>=7.1.0,<8.0.0)
 Description-Content-Type: text/markdown
 
-# Data Cloud Custom Code SDK (BETA)
+# Data Cloud Custom Code SDK
 
 This package provides a development kit for creating custom data transformations in [Data Cloud](https://www.salesforce.com/data/). It allows you to write your own data processing logic in Python while leveraging Data Cloud's infrastructure for data access and running data transformations, mapping execution into Data Cloud data structures like [Data Model Objects](https://help.salesforce.com/s/articleView?id=data.c360_a_data_model_objects.htm&type=5) and [Data Lake Objects](https://help.salesforce.com/s/articleView?id=sf.c360_a_data_lake_objects.htm&language=en_US&type=5).
 
@@ -36,7 +36,7 @@ Use of this project with Salesforce is subject to the [TERMS OF USE](./TERMS_OF_
 - **Python 3.11 only** (currently supported version - if your system version is different, we recommend using [pyenv](https://github.com/pyenv/pyenv) to configure 3.11)
 - JDK 17
 - Docker support like [Docker Desktop](https://docs.docker.com/desktop/)
-- A salesforce org with some DLOs or DMOs with data and this feature enabled (it is not GA)
+- A salesforce org with some DLOs or DMOs with data and this feature enabled
 - **One of the following** for authentication:
   - A Salesforce org already authenticated via the [Salesforce CLI](https://developer.salesforce.com/tools/salesforcecli)
     (simplest — no External Client App needed)
@@ -116,7 +116,7 @@ After modifying the `entrypoint.py` as needed, using any dependencies you add in
 ```zsh
 cd my_package
 datacustomcode scan ./payload/entrypoint.py
-datacustomcode deploy --path ./payload --name my_custom_script --cpu-size CPU_L
+datacustomcode deploy --path ./payload --name my_custom_script --cpu-size CPU_L --sf-cli-org myorg
 ```
 
 > [!TIP]
@@ -170,15 +170,22 @@ Your Python dependencies can be packaged as .py files, .zip archives (containing
 
 ## API
 
-Your entry point script will define logic using the `Client` object which wraps data access layers.
+Your entry point script will define logic using the `Client` object (for batch transforms) or the `StreamingClient` object (for streaming delta transforms), which wrap the data access layers. Both are singletons; a single transform should use one or the other, not both.
 
-You should only need the following methods:
+For a batch transform, use `Client`. You should only need the following methods:
 * `find_file_path(file_name)` – Resolve a bundled file (placed under `payload/files/`) to a `pathlib.Path` that exists. Works the same locally and inside Data Cloud — see [Bundled file resolution](#bundled-file-resolution) below for the full lookup order. Raises `FileNotFoundError` if the file isn't found.
 * `read_dlo(name)` – Read from a Data Lake Object by name
 * `read_dmo(name)` – Read from a Data Model Object by name
 * `write_to_dlo(name, spark_dataframe, write_mode)` – Write to a Data Model Object by name with a Spark dataframe
 * `write_to_dmo(name, spark_dataframe, write_mode)` – Write to a Data Lake Object by name with a Spark dataframe
 
+For a streaming (delta) transform, use `StreamingClient`, which exposes the streaming counterparts:
+* `read_dlo_deltas()` – Read the streaming change feed (deltas) of a Data Lake Object as a streaming DataFrame.
+* `read_dmo_deltas()` – Read the streaming change feed (deltas) of a Data Model Object as a streaming DataFrame.
+* `write_dlo_deltas(name, spark_dataframe)` – Write a streaming DataFrame of deltas to a Data Lake Object; returns the started `StreamingQuery`
+
+`find_file_path`, `llm_gateway_generate_text`, and `einstein_predict` are available on both clients.
+
 For example:
 ```python
 from datacustomcode import Client
@@ -194,6 +201,36 @@ client.write_to_dlo('output_DLO')
 > [!WARNING]
 > Currently we only support reading from DMOs and writing to DMOs or reading from DLOs and writing to DLOs, but they cannot mix.
 
+### Streaming (delta) transforms
+
+Streaming BYOC transforms process a Data Lake Object's Change Data Feed continuously instead of reading a bounded snapshot. Use a `StreamingClient` and its `*_deltas` methods in place of the batch `Client` read/write methods:
+
+```python
+from pyspark.sql.functions import col, upper
+
+from datacustomcode import StreamingClient
+
+client = StreamingClient()
+
+# read_dlo_deltas returns a *streaming* DataFrame over the change feed.
+# The runtime resolves the single streaming source, so no name is passed.
+deltas = client.read_dlo_deltas()
+
+# Ordinary PySpark transform.
+transformed = deltas.withColumn("description__c", upper(col("description__c")))
+
+# write_dlo_deltas starts a streaming query and returns the StreamingQuery.
+# The runtime owns the trigger and checkpoint location; you
+# choose only the target table.
+query = client.write_dlo_deltas("Output__dll", transformed)
+query.awaitTermination()
+```
+
+Notes:
+
+- These methods only run inside the Data Cloud streaming (`DELTA_SYNC`) runtime. Locally (`datacustomcode run`) they raise `NotImplementedError`, since there is no change feed to stream.
+- A complete runnable entry point is provided in [`examples/streaming_deltas/entrypoint.py`](src/datacustomcode/templates/script/examples/streaming_deltas/entrypoint.py).
+
 ### Bundled file resolution
 
 Place bundled files (CSVs, prompt files, etc.) under `payload/files/`. The same `client.find_file_path("data.csv")` call resolves consistently across all three runtimes:
@@ -345,6 +382,7 @@ Options:
 - `--description TEXT`: Description of the transformation job (default: "")
 - `--network TEXT`: docker network (default: "default")
 - `--cpu-size TEXT`: CPU size for the deployment (default: `CPU_2XL`). Available options: CPU_L(Large), CPU_XL(Extra Large), CPU_2XL(2X Large), CPU_4XL(4X Large)
+- `--sf-cli-org TEXT`: Salesforce CLI org alias or username (e.g. `myorg`). Fetches credentials via `sf org display` — no `datacustomcode configure` step needed. Takes precedence over `--profile` if both are supplied.
 - `--function-invoke-opt TEXT`: Currently we support only `UnstructuredChunking` for functions.
 
 
@@ -397,6 +435,56 @@ datacustomcode run ./payload/entrypoint.py --sf-cli-org myorg
 ```
 
 
+## Testing Einstein Predictions
+
+You can use AI models configured in Einstein Studio to score your data while
+transforming it. As with the LLM Gateway, there are two flavors: a one-shot
+scalar call (`client.einstein_predict`) and a per-row column helper
+(`einstein_predict_col`). Below is a sample code example:
+
+```
+from datacustomcode.client import Client, einstein_predict_col
+from datacustomcode.einstein_predictions.types import PredictionType
+
+
+def main():
+  client = Client()
+  df = client.read_dlo("Input__dll")
+  # einstein_predict_col returns a struct
+  # {status, response, error_code, error_message} per row, so per-row
+  # failures don't abort the Spark job. `response` is the prediction
+  # payload as a JSON string. Pick the field you want with [].
+  df_scored = df.withColumn(
+    "prediction__c",
+    einstein_predict_col(
+        "my_regression_model",  # An AI model in your org
+        PredictionType.REGRESSION,
+        {"square_feet": col("square_feet__c"), "beds": col("beds__c")},
+    )["response"],
+  )
+
+  dlo_name = "Output_dll"
+  client.write_to_dlo(dlo_name, df_scored, write_mode=WriteMode.APPEND)
+
+  # One-shot scalar prediction returns the response payload as a dict
+  prediction = client.einstein_predict(
+    "my_regression_model",
+    PredictionType.REGRESSION,
+    {"square_feet": 1800, "beds": 3},
+  )
+
+if __name__ == "__main__":
+  main()
+```
+
+Testing this code locally uses the same External Client App setup described in
+[Testing LLM Gateway](#testing-llm-gateway). Once your `myorg` alias is set up,
+run:
+```
+datacustomcode run ./payload/entrypoint.py --sf-cli-org myorg
+```
+
+
 ## Docker usage
 
 The SDK provides Docker-based development options that allow you to test your code in an environment that closely resembles Data Cloud's execution environment.
@@ -508,7 +596,7 @@ sf --version
 **Browser-based (recommended for developer orgs and sandboxes):**
 ```zsh
 # Production / Developer Edition
-sf org login web --alias myorg
+sf org login web --alias myorg --instance-url <your-instance-url>
 
 # Sandbox
 sf org login web --alias mysandbox --instance-url https://test.salesforce.com

{salesforce_data_customcode-6.0.5.dev1 → salesforce_data_customcode-6.0.6.dev2}/README.md

@@ -1,4 +1,4 @@
-# Data Cloud Custom Code SDK (BETA)
+# Data Cloud Custom Code SDK
 
 This package provides a development kit for creating custom data transformations in [Data Cloud](https://www.salesforce.com/data/). It allows you to write your own data processing logic in Python while leveraging Data Cloud's infrastructure for data access and running data transformations, mapping execution into Data Cloud data structures like [Data Model Objects](https://help.salesforce.com/s/articleView?id=data.c360_a_data_model_objects.htm&type=5) and [Data Lake Objects](https://help.salesforce.com/s/articleView?id=sf.c360_a_data_lake_objects.htm&language=en_US&type=5).
 
@@ -11,7 +11,7 @@ Use of this project with Salesforce is subject to the [TERMS OF USE](./TERMS_OF_
 - **Python 3.11 only** (currently supported version - if your system version is different, we recommend using [pyenv](https://github.com/pyenv/pyenv) to configure 3.11)
 - JDK 17
 - Docker support like [Docker Desktop](https://docs.docker.com/desktop/)
-- A salesforce org with some DLOs or DMOs with data and this feature enabled (it is not GA)
+- A salesforce org with some DLOs or DMOs with data and this feature enabled
 - **One of the following** for authentication:
   - A Salesforce org already authenticated via the [Salesforce CLI](https://developer.salesforce.com/tools/salesforcecli)
     (simplest — no External Client App needed)
@@ -91,7 +91,7 @@ After modifying the `entrypoint.py` as needed, using any dependencies you add in
 ```zsh
 cd my_package
 datacustomcode scan ./payload/entrypoint.py
-datacustomcode deploy --path ./payload --name my_custom_script --cpu-size CPU_L
+datacustomcode deploy --path ./payload --name my_custom_script --cpu-size CPU_L --sf-cli-org myorg
 ```
 
 > [!TIP]
@@ -145,15 +145,22 @@ Your Python dependencies can be packaged as .py files, .zip archives (containing
 
 ## API
 
-Your entry point script will define logic using the `Client` object which wraps data access layers.
+Your entry point script will define logic using the `Client` object (for batch transforms) or the `StreamingClient` object (for streaming delta transforms), which wrap the data access layers. Both are singletons; a single transform should use one or the other, not both.
 
-You should only need the following methods:
+For a batch transform, use `Client`. You should only need the following methods:
 * `find_file_path(file_name)` – Resolve a bundled file (placed under `payload/files/`) to a `pathlib.Path` that exists. Works the same locally and inside Data Cloud — see [Bundled file resolution](#bundled-file-resolution) below for the full lookup order. Raises `FileNotFoundError` if the file isn't found.
 * `read_dlo(name)` – Read from a Data Lake Object by name
 * `read_dmo(name)` – Read from a Data Model Object by name
 * `write_to_dlo(name, spark_dataframe, write_mode)` – Write to a Data Model Object by name with a Spark dataframe
 * `write_to_dmo(name, spark_dataframe, write_mode)` – Write to a Data Lake Object by name with a Spark dataframe
 
+For a streaming (delta) transform, use `StreamingClient`, which exposes the streaming counterparts:
+* `read_dlo_deltas()` – Read the streaming change feed (deltas) of a Data Lake Object as a streaming DataFrame.
+* `read_dmo_deltas()` – Read the streaming change feed (deltas) of a Data Model Object as a streaming DataFrame.
+* `write_dlo_deltas(name, spark_dataframe)` – Write a streaming DataFrame of deltas to a Data Lake Object; returns the started `StreamingQuery`
+
+`find_file_path`, `llm_gateway_generate_text`, and `einstein_predict` are available on both clients.
+
 For example:
 ```python
 from datacustomcode import Client
@@ -169,6 +176,36 @@ client.write_to_dlo('output_DLO')
 > [!WARNING]
 > Currently we only support reading from DMOs and writing to DMOs or reading from DLOs and writing to DLOs, but they cannot mix.
 
+### Streaming (delta) transforms
+
+Streaming BYOC transforms process a Data Lake Object's Change Data Feed continuously instead of reading a bounded snapshot. Use a `StreamingClient` and its `*_deltas` methods in place of the batch `Client` read/write methods:
+
+```python
+from pyspark.sql.functions import col, upper
+
+from datacustomcode import StreamingClient
+
+client = StreamingClient()
+
+# read_dlo_deltas returns a *streaming* DataFrame over the change feed.
+# The runtime resolves the single streaming source, so no name is passed.
+deltas = client.read_dlo_deltas()
+
+# Ordinary PySpark transform.
+transformed = deltas.withColumn("description__c", upper(col("description__c")))
+
+# write_dlo_deltas starts a streaming query and returns the StreamingQuery.
+# The runtime owns the trigger and checkpoint location; you
+# choose only the target table.
+query = client.write_dlo_deltas("Output__dll", transformed)
+query.awaitTermination()
+```
+
+Notes:
+
+- These methods only run inside the Data Cloud streaming (`DELTA_SYNC`) runtime. Locally (`datacustomcode run`) they raise `NotImplementedError`, since there is no change feed to stream.
+- A complete runnable entry point is provided in [`examples/streaming_deltas/entrypoint.py`](src/datacustomcode/templates/script/examples/streaming_deltas/entrypoint.py).
+
 ### Bundled file resolution
 
 Place bundled files (CSVs, prompt files, etc.) under `payload/files/`. The same `client.find_file_path("data.csv")` call resolves consistently across all three runtimes:
@@ -320,6 +357,7 @@ Options:
 - `--description TEXT`: Description of the transformation job (default: "")
 - `--network TEXT`: docker network (default: "default")
 - `--cpu-size TEXT`: CPU size for the deployment (default: `CPU_2XL`). Available options: CPU_L(Large), CPU_XL(Extra Large), CPU_2XL(2X Large), CPU_4XL(4X Large)
+- `--sf-cli-org TEXT`: Salesforce CLI org alias or username (e.g. `myorg`). Fetches credentials via `sf org display` — no `datacustomcode configure` step needed. Takes precedence over `--profile` if both are supplied.
 - `--function-invoke-opt TEXT`: Currently we support only `UnstructuredChunking` for functions.
 
 
@@ -372,6 +410,56 @@ datacustomcode run ./payload/entrypoint.py --sf-cli-org myorg
 ```
 
 
+## Testing Einstein Predictions
+
+You can use AI models configured in Einstein Studio to score your data while
+transforming it. As with the LLM Gateway, there are two flavors: a one-shot
+scalar call (`client.einstein_predict`) and a per-row column helper
+(`einstein_predict_col`). Below is a sample code example:
+
+```
+from datacustomcode.client import Client, einstein_predict_col
+from datacustomcode.einstein_predictions.types import PredictionType
+
+
+def main():
+  client = Client()
+  df = client.read_dlo("Input__dll")
+  # einstein_predict_col returns a struct
+  # {status, response, error_code, error_message} per row, so per-row
+  # failures don't abort the Spark job. `response` is the prediction
+  # payload as a JSON string. Pick the field you want with [].
+  df_scored = df.withColumn(
+    "prediction__c",
+    einstein_predict_col(
+        "my_regression_model",  # An AI model in your org
+        PredictionType.REGRESSION,
+        {"square_feet": col("square_feet__c"), "beds": col("beds__c")},
+    )["response"],
+  )
+
+  dlo_name = "Output_dll"
+  client.write_to_dlo(dlo_name, df_scored, write_mode=WriteMode.APPEND)
+
+  # One-shot scalar prediction returns the response payload as a dict
+  prediction = client.einstein_predict(
+    "my_regression_model",
+    PredictionType.REGRESSION,
+    {"square_feet": 1800, "beds": 3},
+  )
+
+if __name__ == "__main__":
+  main()
+```
+
+Testing this code locally uses the same External Client App setup described in
+[Testing LLM Gateway](#testing-llm-gateway). Once your `myorg` alias is set up,
+run:
+```
+datacustomcode run ./payload/entrypoint.py --sf-cli-org myorg
+```
+
+
 ## Docker usage
 
 The SDK provides Docker-based development options that allow you to test your code in an environment that closely resembles Data Cloud's execution environment.
@@ -483,7 +571,7 @@ sf --version
 **Browser-based (recommended for developer orgs and sandboxes):**
 ```zsh
 # Production / Developer Edition
-sf org login web --alias myorg
+sf org login web --alias myorg --instance-url <your-instance-url>
 
 # Sandbox
 sf org login web --alias mysandbox --instance-url https://test.salesforce.com

{salesforce_data_customcode-6.0.5.dev1 → salesforce_data_customcode-6.0.6.dev2}/pyproject.toml

@@ -5,7 +5,7 @@ requires = ["poetry-core>=2.0.0", "poetry-dynamic-versioning>=1.0.0,<2.0.0"]
 [project]
 authors = []
 classifiers = [
-  "Development Status :: 4 - Beta",
+  "Development Status :: 5 - Production/Stable",
   "Operating System :: Unix",
   "Programming Language :: Python",
   "Programming Language :: Python :: 3",
@@ -18,7 +18,7 @@ license = "Apache-2.0"
 name = "salesforce-data-customcode"
 readme = "README.md"
 requires-python = ">=3.10,<3.12"
-version = "6.0.5.dev1"
+version = "6.0.6.dev2"
 
 [tool.black]
 exclude = '''

{salesforce_data_customcode-6.0.5.dev1 → salesforce_data_customcode-6.0.6.dev2}/src/datacustomcode/__init__.py

@@ -17,10 +17,14 @@ __all__ = [
     "AuthType",
     "Client",
     "Credentials",
+    "DefaultSparkEinsteinPredictions",
     "DefaultSparkLLMGateway",
     "PrintDataCloudWriter",
     "QueryAPIDataCloudReader",
+    "SparkEinsteinPredictions",
     "SparkLLMGateway",
+    "StreamingClient",
+    "einstein_predict_col",
     "llm_gateway_generate_text_col",
 ]
 
@@ -31,6 +35,10 @@ def __getattr__(name: str):
         from datacustomcode.client import Client
 
         return Client
+    elif name == "StreamingClient":
+        from datacustomcode.client import StreamingClient
+
+        return StreamingClient
     elif name == "AuthType":
         from datacustomcode.credentials import AuthType
 
@@ -59,4 +67,16 @@ def __getattr__(name: str):
         from datacustomcode.client import llm_gateway_generate_text_col
 
         return llm_gateway_generate_text_col
+    elif name == "SparkEinsteinPredictions":
+        from datacustomcode.einstein_predictions import SparkEinsteinPredictions
+
+        return SparkEinsteinPredictions
+    elif name == "DefaultSparkEinsteinPredictions":
+        from datacustomcode.einstein_predictions import DefaultSparkEinsteinPredictions
+
+        return DefaultSparkEinsteinPredictions
+    elif name == "einstein_predict_col":
+        from datacustomcode.client import einstein_predict_col
+
+        return einstein_predict_col
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")