Documentation Index
Fetch the complete documentation index at: https://docs.sutro.sh/llms.txt
Use this file to discover all available pages before exploring further.
Use run_function() for one request and batch_run_function() for many rows.
Call the Function by name and pass the input fields it expects. Sutro uses the Function’s published setup automatically.
Use the Function name only. Do not include a namespace, owner, or revision. The authenticated API key determines which customer namespace is searched, and the currently published revision is resolved automatically.
Only text Functions are supported today. Image, PDF, and other multimodal Functions are not yet runnable through run_function() or batch_run_function().
Running a Function
run_function(
name: str,
input_data: dict | BaseModel,
langsmith_metadata: Optional[Dict[str, Any]] = None,
langsmith_tags: Optional[List[str]] = None,
)
Parameters
name — Function name to execute.input_data — Input object matching the Function inputs. Can be a plain dictionary or a Pydantic model.langsmith_metadata — Optional trace metadata when LangSmith tracing is enabled.langsmith_tags — Optional trace tags when LangSmith tracing is enabled.
Return shape
Most Functions return one of two payload shapes. For the full response reference, see Running a Function.
Classification-style Functions return one primary answer:
{
"response": "qualified",
"confidence": 0.91,
"predictions": [
{ "label": "qualified", "confidence": 0.91 },
{ "label": "not_qualified", "confidence": 0.09 }
],
"rationale": "The lead matches the qualification rubric.",
"usage": {
"input_tokens": 173,
"output_tokens": 42,
"system_prompt": "Return one lead qualification label."
}
}
{
"output": {
"company": "Acme Labs",
"segment": "B2B analytics",
"region": "APAC"
},
"rationale": "The requested fields are present in the input.",
"confidence": 0.82,
"usage": {
"input_tokens": 244,
"output_tokens": 66,
"system_prompt": "Extract the requested lead fields."
}
}
run_id in this response.
Examples
Replace lead-qualifier with your published Function name and add the correct input data (structured to adhere to the Function’s input schema).
Using a dictionary:
import sutro as so
result = so.run_function(
name="lead-qualifier",
input_data={
"query": "Find cybersecurity leaders evaluating AI vendors.",
"region": "APAC",
},
)
print(result)
import sutro as so
from pydantic import BaseModel
class LeadInput(BaseModel):
query: str
region: str | None = None
result = so.run_function(
name="lead-qualifier",
input_data=LeadInput(
query="Find cybersecurity leaders evaluating AI vendors.",
region="APAC",
),
)
print(result)
Running a Function in Batch
batch_run_function(
name: str,
data: List[dict] | pd.DataFrame | pl.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,
langsmith_metadata: Optional[Dict[str, Any]] = None,
langsmith_tags: Optional[List[str]] = None,
)
batch_run_function() submits many rows to the same Function.
Parameters
name — Function name to execute.data — One of:
List[dict]pandas.DataFramepolars.DataFrame- local
.csv or .parquet file path
- pre-signed download URL pointing to a
.csv or .parquet file
job_priority — Batch priority level. Defaults to 0.output_column — Output column name for downstream results.dry_run — If True, submit a cost-estimate job instead of full inference. The SDK maps this to the Batch API’s cost_estimate request field.stay_attached — If True, stay attached to the job and stream progress.job_name — Optional job name.description — Optional job description.langsmith_metadata — Optional trace metadata when LangSmith tracing is enabled.langsmith_tags — Optional trace tags when LangSmith tracing is enabled.
When data is a local CSV or Parquet path, the SDK reads the file locally and submits rows whose column names must match the Function inputs.
Dataset IDs are not supported by batch_run_function(). Use a list of dictionaries, a DataFrame, or a local CSV/Parquet file path.
Examples
Using a list of dictionaries:
import sutro as so
job_id = so.batch_run_function(
name="lead-qualifier",
data=[
{
"query": "Find cybersecurity leaders evaluating AI vendors.",
"region": "APAC",
},
{
"query": "Find sales operations leaders replacing manual enrichment.",
"region": "EMEA",
},
],
)
print(job_id)
import polars as pl
import sutro as so
df = pl.DataFrame(
{
"query": [
"Find cybersecurity leaders evaluating AI vendors.",
"Find sales operations leaders replacing manual enrichment.",
],
"region": ["APAC", "EMEA"],
}
)
job_id = so.batch_run_function(
name="lead-qualifier",
data=df,
)
print(job_id)
import sutro as so
job_id = so.batch_run_function(
name="lead-qualifier",
data="./lead_inputs.csv",
)
print(job_id)
Working with batch results
Batch jobs run asynchronously. Use await_job_completion() to wait for completion and retrieve results:
import sutro as so
job_id = so.batch_run_function(
name="lead-qualifier",
data=[
{
"query": "Find cybersecurity leaders evaluating AI vendors.",
"region": "APAC",
}
],
)
results_df = so.await_job_completion(job_id)
print(results_df)
get_job_results() and await_job_completion() unpack JSON outputs when possible. For a Function that returns label and rationale, the result DataFrame may contain columns such as:
shape: (1, 3)
┌───────────┬─────────────────────────────────────────────┬──────────────────┐
│ label ┆ rationale ┆ confidence_score │
│ --- ┆ --- ┆ --- │
│ str ┆ str ┆ f64 │
╞═══════════╪═════════════════════════════════════════════╪══════════════════╡
│ qualified ┆ The lead matches the qualification rubric. ┆ 1.0 │
└───────────┴─────────────────────────────────────────────┴──────────────────┘
import json
import sutro as so
raw_results_df = so.get_job_results(job_id, unpack_json=False)
first_result = json.loads(raw_results_df["inference_result"][0])
content = first_result.get("content", first_result)
print(content)
print(first_result.get("reasoning_content"))
print(raw_results_df["confidence_score"][0])
run_function().
