Skip to main content

​
Running a Function

run_function(self, name: str, input_data: dict)
Parameters:
  • name (str): The name of the function to run.
  • input_data (dict or Pydantic model): The input data to pass to the function. Refer to instructions from the Sutro team or your the Sutro web app for the specific input parameters required for your function.
Returns:
  • response (str|array|object): The response from the function.
  • confidence (float): The confidence score for the response.
  • predictions (list): A list of predictions from the function.
  • run_id (str): The ID of the function run.
Examples: Using a dictionary: 
import sutro as so

result = so.run_function(
  name="is-hotdog",
  input_data={"brand": "Oscar Meyer", "description": "Classic frankfurter, 8-pack"}
)
Using a Pydantic model: 
import sutro as so
from pydantic import BaseModel

class HotdogModelInput(BaseModel):
  brand: str
  description: str

result = so.run_function(
  name="is-hotdog",
  input_data=HotdogModelInput(
    brand="Oscar Meyer",
    description="Classic frankfurter, 8-pack"
  )
)

​
Running a Function using Sutro Batch

When you want to run a function over a larger dataset (thousands to millions of rows), it generally makes sense to use Sutro’s batch inference tooling which is built for quickly and efficiently processing large datasets. With batch, you get predictable and constant job completion time (1hr for P1 jobs across any dataset scale), no rate limits, and lower costs. 
batch_run_function(
  self,
  name: str,
  data: Union[List[dict], pl.DataFrame, pd.DataFrame, str],
  job_priority: int | None = 0,
  output_column: str = "inference_result",
  dry_run: bool = False,
  stay_attached: bool = False,
  job_name: Optional[str] = None,
  description: Optional[str] = None,
)
Run a Sutro Function on a large table, dataframe, or file using batch processing. This is a convenience method for running batch inference with functions.
batch_run_function uses the same batch inference primitives as infer. For more details on job management, result retrieval, and advanced options, see the Batch Inference documentation.
Parameters:
  • name (str): The name of the Sutro Function to use.
  • data (List[dict] | pd.DataFrame | pl.DataFrame | str): The data to run inference on. Accepts a list of dictionaries, a DataFrame, or a path to a parquet/CSV file. Dictionary keys or table columns must match the function’s expected schema.
  • job_priority (int, optional): The priority of the job. Defaults to 0.
  • output_column (str, optional): The column name to store the inference results. Defaults to “inference_result”.
  • dry_run (bool, optional): If True, return cost estimates instead of running inference. Defaults to False.
  • stay_attached (bool, optional): If True, the SDK will stay attached to the job and stream progress updates. Defaults to False.
  • job_name (str, optional): A job name for experiment/metadata tracking purposes. Defaults to None.
  • description (str, optional): A job description for experiment/metadata tracking purposes. Defaults to None.
Returns:
  • job_id (str): The ID of the batch job.
Examples: Using a list of dictionaries: 
import sutro as so

job_id = so.batch_run_function(
  name="is-hotdog",
  data=[
    {"brand": "Oscar Meyer", "description": "Classic frankfurter, 8-pack"},
    {"brand": "Hebrew National", "description": "Beef franks, 7-pack"},
    {"brand": "Ball Park", "description": "Bun length hot dogs, 8-pack"},
  ]
)
Using a Polars DataFrame: 
import sutro as so
import polars as pl

df = pl.DataFrame({
  "brand": ["Oscar Meyer", "Hebrew National", "Ball Park"],
  "description": ["Classic frankfurter, 8-pack", "Beef franks, 7-pack", "Bun length hot dogs, 8-pack"]
})

job_id = so.batch_run_function(
  name="is-hotdog",
  data=df
)
Using a file path: 
import sutro as so

job_id = so.batch_run_function(
  name="is-hotdog",
  data="path/to/hotdogs.csv"
)

​
Working with Results

Since batch jobs run asynchronously, use await_job_completion to wait for the job to finish and retrieve results: 
import sutro as so

job_id = so.batch_run_function(
  name="is-hotdog",
  data=df,
  job_priority=1
)

# Wait for job completion and get results as a Polars DataFrame
results_df = so.await_job_completion(job_id)
The results DataFrame contains two columns:
  • inference_result (str): JSON string containing the function’s output
  • confidence_score (float): Confidence score for each prediction (0.0-1.0)
Example output for a classification/judge function: 
+----------------------------------------------------+------------------+
| inference_result                                   | confidence_score |
| ---                                                | ---              |
| str                                                | f64              |
+====================================================+==================+
| {"content": {"rationale": "...", "label": "true"}} | 1.0              |
| {"content": {"rationale": "...", "label": "false"}}| 0.8              |
+----------------------------------------------------+------------------+
The structure of inference_result varies by function type. Classification and judge functions typically return label and rationale fields, while extraction functions will return different fields specific to that task. Refer to your advice from the Sutro team or the schema you entered for an extraction task, for the expected output schema. To parse the JSON results and access individual fields: 
import json

# Access a single result
first_result = json.loads(results_df["inference_result"][0])

# For some classification/judge functions:
print(first_result["content"]["label"])
print(first_result["content"]["rationale"])

# For other function types, access the relevant fields:
# print(first_result["content"]["your_field"])
Alternatively, use get_job_results to retrieve results for a previously completed job: 
results_df = so.get_job_results(job_id)

​
Notes

  • Your input data must contain keys or columns matching the function’s expected schema. Refer to instructions from the Sutro team or your Sutro web app for the required field names.
  • For lower volume or real-time workloads, use the run_function method instead.
  • Ensure the combined token count of your input fields does not exceed your function’s max context length (please reach out to team@sutro.sh and we can advise here).