Response Models

outerproduct.models

Response models for the OuterProduct ClearTrace API.

All models are frozen Pydantic BaseModels — they validate API responses on construction (via Model.model_validate(payload_dict)) and behave like immutable value objects after that.

Classes:

Name	Description
UploadResult	Returned by POST /v1/uploads after a presigned URL generation completes.
JobResult	Returned by all async endpoints (fit, fit_distill, segment, narrative).
StatusResult	Status of an async job from GET /v1/models/{model_id}/status.
ExplanationResult	Batch prediction + AGOP-based explanation.
PredictAndExplainResult	Batch prediction + explanation with optional persona.
InterpretResult	Global feature importance via AGOP.
ScenarioChange	Single-feature diff between a query and one counterfactual row.
ScenarioCandidate	One counterfactual candidate returned for a query.
ScenarioResultItem	Result for a single query within a scenario response.
ScenarioResult	Result of a counterfactual scenario search.
ClusterPersona	Description of a single cluster's persona.
SegmentationResult	Result of supervised segmentation.
Narrative	LLM-generated summary of model behavior.
SchemaColumn	Per-column schema entry from the model's schema manifest.
SchemaResult	Persisted model schema manifest from GET /v1/models/{model_id}/schema.

UploadResult

Returned by POST /v1/uploads after a presigned URL generation completes.

Attributes:

Name	Type	Description
model_id	str	Auto-generated or custom model identifier.
upload_url	str	Presigned S3 URL to upload data to.
upload_key	str	S3 object key for the uploaded file.
file_format	str	Upload format: "csv", "parquet", or "pkl".
content_type	str	MIME type for the upload (e.g. text/csv).
expires_in	int	Seconds until the presigned URL expires.

JobResult

Returned by all async endpoints (fit, fit_distill, segment, narrative).

Attributes:

Name	Type	Description
model_id	str	Identifier of the model this job belongs to.
status	str	Job status: "pending" or "completed".
message	str	Optional status message from the server. Empty by default.

StatusResult

Status of an async job from GET /v1/models/{model_id}/status.

Attributes:

Name	Type	Description
model_id	str	Model identifier.
job_type	str	Type of job: "fit", "fit_distill", "segment", or "narrative".
status	str	Current status: "pending" | "running" | "completed" | "failed".
created_at	str	ISO-8601 timestamp when the job was created.
updated_at	str	ISO-8601 timestamp of the last status update.
progress	dict[str, Any] or None	Optional progress details reported by the server.
error_message	str or None	Error details if the job failed.

ExplanationResult

Batch prediction + AGOP-based explanation.

Attributes:

Name	Type	Description
model_id	str	Model identifier.
predictions	list[float]	Predicted values for each sample.
local_agop	list[list[float]]	Per-sample AGOP (Averaged Gradient Outer Product) scores.
local_drivers	list[list[float]] or None	Per-sample feature attribution scores.
raw_loadings	list[list[float]] or None	Raw loading vectors before normalization.
feature_names	list[str] or None	Original feature names from the training data.
ohe_feature_names	list[str] or None	Feature names after one-hot encoding expansion.

PredictAndExplainResult

Batch prediction + explanation with optional persona.

Attributes:

Name	Type	Description
model_id	str	Model identifier.
predictions	list[float]	Predicted values for each sample.
local_agop	list[list[float]]	Per-sample AGOP scores.
local_drivers	list[list[float]] or None	Per-sample feature attribution scores.
raw_loadings	list[list[float]] or None	Raw loading vectors before normalization.
grad_at_sample	list[list[float]] or None	Gradient evaluated at each sample point.
feature_vector	list[list[float]] or None	Feature vectors used for explanation.
persona	list[dict[str, Any] or None] or None	Persona description for each sample. Populated when with_persona=True.
persona_cluster_id	list[int or None] or None	Persona cluster assignment for each sample.
local_rules	list[dict[str, Any] or None] or None	Local decision rules for each prediction. Populated when rule_kwargs is provided.
feature_names	list[str] or None	Original feature names from the training data.
ohe_feature_names	list[str] or None	Feature names after one-hot encoding expansion.

InterpretResult

Global feature importance via AGOP.

Attributes:

Name	Type	Description
model_id	str	Model identifier.
global_drivers	list[float]	Global feature importance scores across the full training set.
feature_names	list[str] or None	Original feature names from the training data.
ohe_feature_names	list[str] or None	Feature names after one-hot encoding expansion.

ScenarioChange

Single-feature diff between a query and one counterfactual row.

The wire field from is a Python keyword, so it's exposed as from_ on the model with alias="from" for round-tripping.

Attributes:

Name	Type	Description
from\_	Any	Original feature value in the query.
to	Any	Counterfactual feature value.
delta	float or None	Numeric difference (to - from), if applicable.

ScenarioCandidate

One counterfactual candidate returned for a query.

Attributes:

Name	Type	Description
row	dict[str, Any]	Full feature values of the counterfactual sample.
changes	dict[str, ScenarioChange]	Per-feature diffs between the original query and this candidate.
n_changes	int	Number of features that were changed.

ScenarioResultItem

Result for a single query within a scenario response.

Supports indexing and iteration over its candidates::

item[0]          # first ScenarioCandidate
len(item)        # number of candidates
for c in item:   # iterate candidates

Attributes:

Name	Type	Description
query_index	int	Zero-based index of this query in the request batch.
query	dict[str, Any]	Original feature values submitted for this query.
baseline_prediction	float	Model prediction for the original query.
already_at_desired_class	bool	Whether the query already belongs to the desired class.
scenarios	list[ScenarioCandidate]	List of counterfactual candidates found.
scenario_count	int	Number of counterfactual candidates found.

ScenarioResult

Result of a counterfactual scenario search.

Supports indexing and iteration over its result items::

result[0]          # first ScenarioResultItem
len(result)        # number of query results
for item in result:  # iterate result items

Attributes:

Name	Type	Description
model_id	str	Model identifier.
desired_class	int	Target class used for the counterfactual search.
results	list[ScenarioResultItem]	Per-query scenario results.

ClusterPersona

Description of a single cluster's persona.

Attributes:

Name	Type	Description
cluster_id	int	Numeric cluster identifier.
persona_name	str	Short label for this cluster's persona.
persona_description	str	Natural-language description of the cluster's characteristics.
stats	dict[str, Any]	Summary statistics for this cluster (e.g. size, mean target).
differentiating_features	list[dict[str, Any]] or None	Features that most distinguish this cluster from others.

SegmentationResult

Result of supervised segmentation.

Attributes:

Name	Type	Description
model_id	str	Model identifier.
status	str	Job status.
n_clusters	int or None	Number of clusters chosen by the optimizer.
cluster_ids	list[int] or None	Cluster assignment for each sample in the input data.
resolution	float or None	Resolution parameter selected during clustering.
quality	float or None	Quality score for the chosen clustering.
personas	list[ClusterPersona] or None	Natural-language persona descriptions for each cluster.
agent_score	float or None	Agent-assigned quality score, if use_agent was enabled.
agent_reasoning	str or None	Agent's reasoning for the score, if use_agent was enabled.

Narrative

LLM-generated summary of model behavior.

The narrative endpoint is async. This model represents the result retrieved after polling for completion.

Attributes:

Name	Type	Description
model_id	str	Model identifier.
status	str	Job status.
narrative	str or None	LLM-generated natural-language summary of model behavior.
prediction	float or None	Aggregate prediction value referenced by the narrative.
scenarios	list[dict[str, Any]]	Scenario analyses referenced in the narrative.
n_records	int or None	Number of records the narrative was generated from.

SchemaColumn

Per-column schema entry from the model's schema manifest.

Attributes:

Name	Type	Description
dtype	str	Data type: "float", "int", "bool", or "categorical".
categories	list[Any] or None	Allowed category values for categorical columns.
unknown_code	int or None	Integer code assigned to unknown/unseen categories.

SchemaResult

Persisted model schema manifest from GET /v1/models/{model_id}/schema.

Attributes:

Name	Type	Description
feature_names	list[str]	Ordered list of all feature names in the model.
columns	dict[str, SchemaColumn]	Per-column schema details keyed by column name.
target	dict[str, Any]	Schema metadata for the target column.