outerproduct-http-types 0.1.0__py3-none-any.whl

outerproduct_http_types/__init__.py

@@ -0,0 +1,117 @@
+"""Shared HTTP-facing type definitions for OuterProduct services and SDKs."""
+
+from .agentic_documents import (
+    AnswerType,
+    CreateDocumentUploadRequest,
+    CreateDocumentUploadResponse,
+    DocumentRef,
+    InduceSchemaJobResponse,
+    InduceSchemaRequest,
+    Question,
+    Schema,
+    SchemaResultResponse,
+    TabularizeJobResponse,
+    TabularizeRequest,
+    TabularizeResultResponse,
+)
+from .common import (
+    ErrorResponse,
+    FeatureImportance,
+    JobResponse,
+    JobStatus,
+    StatusResponse,
+)
+from .connectors import (
+    ConnectorResponse,
+    ConnectorType,
+    CreateConnectorRequest,
+    DeleteConnectorResponse,
+    ListConnectorsResponse,
+    ListTablesRequest,
+    ListTablesResponse,
+    ValidateConnectorResponse,
+)
+from .inference import (
+    ExplainRequest,
+    ExplainResponse,
+    FeatureConstraintSchema,
+    InterpretRequest,
+    InterpretResponse,
+    PredictAndExplainRequest,
+    PredictAndExplainResponse,
+    PredictRequest,
+    PredictResponse,
+    ScenarioCandidate,
+    ScenarioChange,
+    ScenarioRequest,
+    ScenarioResponse,
+    ScenarioResultItem,
+)
+from .reasoning import ReasoningFitRequest, ReasoningFitResponse
+from .segment import ClusterPersonaSchema, SegmentRequest, SegmentResultResponse
+from .trainer import (
+    HardwareSpec,
+    ModalHardwareSpec,
+    TrainerRunRequest,
+    TrainerRunResponse,
+)
+from .uploads import CreateUploadRequest, CreateUploadResponse
+from .workers import WorkerJobRequest, WorkerJobResponse
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AnswerType",
+    "ClusterPersonaSchema",
+    "ConnectorResponse",
+    "ConnectorType",
+    "CreateConnectorRequest",
+    "CreateDocumentUploadRequest",
+    "CreateDocumentUploadResponse",
+    "CreateUploadRequest",
+    "CreateUploadResponse",
+    "DeleteConnectorResponse",
+    "DocumentRef",
+    "ErrorResponse",
+    "ExplainRequest",
+    "ExplainResponse",
+    "FeatureConstraintSchema",
+    "FeatureImportance",
+    "HardwareSpec",
+    "InduceSchemaJobResponse",
+    "InduceSchemaRequest",
+    "InterpretRequest",
+    "InterpretResponse",
+    "JobResponse",
+    "JobStatus",
+    "ListConnectorsResponse",
+    "ListTablesRequest",
+    "ListTablesResponse",
+    "ModalHardwareSpec",
+    "PredictAndExplainRequest",
+    "PredictAndExplainResponse",
+    "PredictRequest",
+    "PredictResponse",
+    "Question",
+    "ReasoningFitRequest",
+    "ReasoningFitResponse",
+    "ScenarioCandidate",
+    "ScenarioChange",
+    "ScenarioRequest",
+    "ScenarioResponse",
+    "ScenarioResultItem",
+    "Schema",
+    "SchemaResultResponse",
+    "SegmentRequest",
+    "SegmentResultResponse",
+    "StatusResponse",
+    "TabularizeJobResponse",
+    "TabularizeRequest",
+    "TabularizeResultResponse",
+    "TrainerRunRequest",
+    "TrainerRunResponse",
+    "ValidateConnectorResponse",
+    "WorkerJobRequest",
+    "WorkerJobResponse",
+    "__version__",
+]

outerproduct_http_types/agentic_documents.py

@@ -0,0 +1,239 @@
+"""Request/response schemas for the agentic-documents endpoints.
+
+Wire format for ``outerproduct.agentic.documents``: per-file presigned
+uploads, async ``induce_schema`` and ``tabularize`` jobs polled via the
+shared ``GET /v1/models/{model_id}/status`` route, and result fetches
+keyed by the same ``model_id``.
+
+Endpoint summary:
+
+- ``POST /v1/uploads/documents`` -> :class:`CreateDocumentUploadResponse`
+- ``POST /v1/agentic/documents/induce_schema`` -> :class:`InduceSchemaJobResponse`
+- ``GET  /v1/agentic/documents/schemas/{model_id}`` -> :class:`SchemaResultResponse`
+- ``POST /v1/agentic/documents/tabularize`` -> :class:`TabularizeJobResponse`
+- ``GET  /v1/agentic/documents/tables/{model_id}`` -> :class:`TabularizeResultResponse`
+"""
+
+from enum import StrEnum
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+from .common import JobResponse
+
+
+class AnswerType(StrEnum):
+    """The legal answer shapes for a :class:`Question`."""
+
+    BOOLEAN = "boolean"
+    NUMBER = "number"
+    INTEGER = "integer"
+    ENUM = "enum"
+    MULTI_ENUM = "multi_enum"
+    DATE = "date"
+    DATE_RANGE = "date_range"
+    STRING = "string"
+    TEXT = "text"
+
+
+_DOCUMENT_MEDIA_TYPES = Literal[
+    "application/pdf",
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "image/webp",
+    "text/plain",
+]
+
+
+class Question(BaseModel):
+    """One survey question in a :class:`Schema`."""
+
+    id: str = Field(
+        ...,
+        description="Snake-case identifier, unique within the schema.",
+        pattern=r"^[a-z][a-z0-9_]*$",
+    )
+    question: str = Field(..., description="Natural-language prompt the agent answers.")
+    answer_type: AnswerType
+    rationale: str | None = Field(
+        None, description="Why this question is on the schema; surfaced to the agent."
+    )
+    unit: str | None = Field(
+        None, description="Unit string for numeric answers (e.g. 'USD', 'kg')."
+    )
+    enum: list[str] | None = Field(
+        None,
+        description="Allowed values when answer_type is 'enum' or 'multi_enum'.",
+    )
+
+    @model_validator(mode="after")
+    def _check_enum(self):
+        if self.answer_type in (AnswerType.ENUM, AnswerType.MULTI_ENUM):
+            if not self.enum:
+                raise ValueError(
+                    f"Question {self.id!r}: answer_type={self.answer_type.value} "
+                    "requires non-empty `enum`"
+                )
+        elif self.enum is not None:
+            raise ValueError(
+                f"Question {self.id!r}: `enum` is only valid for "
+                "answer_type='enum' or 'multi_enum'"
+            )
+        return self
+
+
+class Schema(BaseModel):
+    """A frozen list of :class:`Question` for one document type and one use case."""
+
+    skill: str = Field(..., description="Skill slug (e.g. 'invoice', 'bank-statement').")
+    use_case: str = Field(..., description="Use-case description that drove induction.")
+    questions: list[Question]
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def _check_unique_ids(self):
+        seen: set[str] = set()
+        for q in self.questions:
+            if q.id in seen:
+                raise ValueError(f"Schema: duplicate question id {q.id!r}")
+            seen.add(q.id)
+        return self
+
+
+# --------------------------------------------------------------------------- #
+# Per-document upload                                                         #
+# --------------------------------------------------------------------------- #
+
+
+class CreateDocumentUploadRequest(BaseModel):
+    """``POST /v1/uploads/documents`` -- request a presigned URL for one file."""
+
+    document_id: str = Field(
+        ...,
+        description="Caller-chosen identifier; echoed back in subsequent requests.",
+    )
+    media_type: _DOCUMENT_MEDIA_TYPES = Field(
+        ...,
+        description="MIME type of the bytes you will PUT to the returned URL.",
+    )
+
+
+class CreateDocumentUploadResponse(BaseModel):
+    document_id: str
+    upload_url: str
+    upload_key: str = Field(
+        ...,
+        description="Reference to use as DocumentRef.upload_key in induce/tabularize.",
+    )
+    media_type: _DOCUMENT_MEDIA_TYPES
+    expires_in: int = Field(..., description="Seconds until the upload URL expires.")
+
+
+class DocumentRef(BaseModel):
+    """One uploaded document, by reference."""
+
+    document_id: str
+    upload_key: str
+    media_type: _DOCUMENT_MEDIA_TYPES
+
+
+# --------------------------------------------------------------------------- #
+# induce_schema                                                               #
+# --------------------------------------------------------------------------- #
+
+
+class InduceSchemaRequest(BaseModel):
+    """``POST /v1/agentic/documents/induce_schema`` -- async schema induction job.
+
+    Runs the agent over the supplied document sample to produce a frozen
+    :class:`Schema`. Submit, poll ``GET /v1/models/{model_id}/status`` until
+    ``status="completed"``, then fetch the result via
+    ``GET /v1/agentic/documents/schemas/{model_id}``.
+    """
+
+    documents: list[DocumentRef] = Field(
+        ...,
+        description="Sample of uploaded documents the agent inspects to draft the schema.",
+        min_length=1,
+    )
+    use_case: str = Field(
+        ...,
+        description="Free-text description of what the resulting features will be used for.",
+    )
+    skill: str = Field(
+        ...,
+        description="Skill slug; one of the values returned by GET /v1/agentic/documents/skills.",
+    )
+    model_id: str | None = Field(
+        None,
+        description="Custom model_id for the resulting schema; auto-generated if omitted.",
+    )
+
+
+class InduceSchemaJobResponse(JobResponse):
+    """``POST /v1/agentic/documents/induce_schema`` -- async submission response."""
+
+
+class SchemaResultResponse(BaseModel):
+    """``GET /v1/agentic/documents/schemas/{model_id}`` -- the produced schema."""
+
+    model_id: str
+    schema_: Schema = Field(..., alias="schema")
+
+    model_config = {"populate_by_name": True}
+
+
+# --------------------------------------------------------------------------- #
+# tabularize                                                                  #
+# --------------------------------------------------------------------------- #
+
+
+class TabularizeRequest(BaseModel):
+    """``POST /v1/agentic/documents/tabularize`` -- async tabularization job.
+
+    Extracts every uploaded document against ``schema`` and assembles a row
+    per document. Submit, poll status, then fetch the result via
+    ``GET /v1/agentic/documents/tables/{model_id}``.
+    """
+
+    documents: list[DocumentRef] = Field(..., min_length=1)
+    schema_: Schema = Field(..., alias="schema")
+    web_augmentation: bool = Field(
+        False,
+        description="If true, allow the agent to issue web searches to corroborate answers.",
+    )
+    concurrency: int = Field(
+        1,
+        ge=1,
+        description="Number of documents to extract in parallel on the worker.",
+    )
+    model_id: str | None = Field(
+        None,
+        description="Custom model_id for the resulting table; auto-generated if omitted.",
+    )
+
+    model_config = {"populate_by_name": True}
+
+
+class TabularizeJobResponse(JobResponse):
+    """``POST /v1/agentic/documents/tabularize`` -- async submission response."""
+
+
+class TabularizeResultResponse(BaseModel):
+    """``GET /v1/agentic/documents/tables/{model_id}`` -- the tabularized result.
+
+    The tabularized rows themselves live in object storage under the
+    returned ``model_id`` (same path used by trainer.run / reasoning.fit
+    in their pre-uploaded mode), so this response is metadata-only:
+    enough to construct a :class:`outerproduct.agentic.documents.DocumentDataset`
+    handle without materializing rows on the client.
+    """
+
+    model_id: str
+    schema_: Schema = Field(..., alias="schema")
+    document_ids: list[str]
+
+    model_config = {"populate_by_name": True}
+
+

outerproduct_http_types/common.py

@@ -0,0 +1,49 @@
+"""Shared types used across all endpoint schemas."""
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class JobStatus(StrEnum):
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class ErrorResponse(BaseModel):
+    error: str
+    detail: str | None = None
+
+
+class JobResponse(BaseModel):
+    """Base response returned by async job-submission endpoints."""
+
+    model_id: str = Field(description="Unique identifier for this model")
+    status: JobStatus
+    message: str
+
+
+class StatusResponse(BaseModel):
+    """Returned by GET /models/{model_id}/status."""
+
+    model_id: str
+    job_type: str = Field(description=("One of: trainer_run, reasoning_fit, segment."))
+    status: JobStatus
+    progress: dict[str, Any] | None = Field(
+        None, description='Progress info, e.g. {"step": 3, "total_steps": 5}'
+    )
+    error_message: str | None = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class FeatureImportance(BaseModel):
+    """A single feature's importance score with direction."""
+
+    feature_name: str
+    importance: float
+    direction: str | None = Field(None, description='"positive" or "negative"')

outerproduct_http_types/connectors.py

@@ -0,0 +1,115 @@
+"""Request/response schemas for connector CRUD endpoints.
+
+Connectors represent registered references to external data sources
+(S3 buckets, GCS buckets, Snowflake warehouses, Databricks workspaces,
+BigQuery datasets). They are persisted server-side with encrypted
+credentials and expose table listing and validation endpoints.
+
+Endpoints
+---------
+- ``POST   /v1/connectors``                     → create a connector
+- ``GET    /v1/connectors``                      → list connectors for the org
+- ``GET    /v1/connectors/{connector_id}``       → get a single connector
+- ``GET    /v1/connectors/by-name/{name}``       → look up by user-facing name
+- ``DELETE /v1/connectors/{connector_id}``       → delete a connector
+- ``POST   /v1/connectors/{connector_id}/tables``   → list tables/paths
+- ``POST   /v1/connectors/{connector_id}/validate`` → test connectivity
+"""
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ConnectorType(StrEnum):
+    """Supported external data source types."""
+
+    S3 = "s3"
+    SNOWFLAKE = "snowflake"
+    DATABRICKS = "databricks"
+
+
+class CreateConnectorRequest(BaseModel):
+    """POST /v1/connectors -- register a new external data source.
+
+    Credentials are encrypted at rest and never returned by GET endpoints.
+    """
+
+    name: str = Field(
+        ...,
+        description="Unique user-facing name for this connector within the org.",
+    )
+    connector_type: ConnectorType = Field(
+        ...,
+        description="The type of external data source.",
+    )
+    connection_params: dict[str, Any] = Field(
+        ...,
+        description=(
+            "Non-secret connection parameters. Contents vary by connector type: "
+            "S3/GCS use 'root_dir'; Snowflake uses 'account', 'warehouse', "
+            "'database', 'schema_name'; Databricks uses 'server_hostname', "
+            "'http_path', 'catalog', 'schema'; BigQuery uses 'project', "
+            "'dataset_id'."
+        ),
+    )
+    credentials: dict[str, str] | None = Field(
+        None,
+        description=(
+            "Secret credentials for the data source. Encrypted at rest, "
+            "never returned by GET. Omit for sources using IAM role-based auth "
+            "(e.g. S3/GCS)."
+        ),
+    )
+
+
+class ConnectorResponse(BaseModel):
+    """Returned by create, get, and list endpoints.
+
+    Credentials are intentionally omitted — they are write-only.
+    """
+
+    connector_id: str = Field(..., description="Server-generated unique identifier.")
+    name: str = Field(..., description="User-facing name.")
+    connector_type: ConnectorType
+    connection_params: dict[str, Any]
+
+
+class ListConnectorsResponse(BaseModel):
+    """GET /v1/connectors -- all connectors for the authenticated org."""
+
+    connectors: list[ConnectorResponse]
+
+
+class DeleteConnectorResponse(BaseModel):
+    """DELETE /v1/connectors/{connector_id}."""
+
+    connector_id: str
+    deleted: bool
+
+
+class ListTablesRequest(BaseModel):
+    """POST /v1/connectors/{connector_id}/tables -- list available tables.
+
+    Currently empty; extensible with filters (prefix, schema, limit) later.
+    """
+
+
+class ListTablesResponse(BaseModel):
+    """Response for table listing."""
+
+    tables: list[str] = Field(
+        ...,
+        description="Table names (database connectors) or object paths (file connectors).",
+    )
+
+
+class ValidateConnectorResponse(BaseModel):
+    """POST /v1/connectors/{connector_id}/validate -- test connectivity."""
+
+    valid: bool = Field(..., description="Whether the connection succeeded.")
+    error: str | None = Field(
+        None,
+        description="Human-readable error message when valid=False.",
+    )

outerproduct_http_types/inference.py

@@ -0,0 +1,206 @@
+"""Request/response schemas for inference endpoints."""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# --- POST /v1/models/{model_id}/predict ---
+
+
+class PredictRequest(BaseModel):
+    """POST /v1/models/{model_id}/predict -- Batch predictions."""
+
+    samples: list[list[float | str | bool | None]] = Field(
+        description="2D array, shape (n_samples, n_features). "
+        "Cells may be numeric, string (categorical), or bool."
+    )
+    feature_names: list[str] = Field(
+        description="Column names for features. Must match the model's training "
+        "schema in name and order."
+    )
+
+
+class PredictResponse(BaseModel):
+    model_id: str
+    predictions: list[float]
+
+
+# --- POST /v1/models/{model_id}/explain ---
+
+
+class ExplainRequest(BaseModel):
+    """POST /v1/models/{model_id}/explain -- Batch local explanations."""
+
+    samples: list[list[float | str | bool | None]] = Field(
+        description="2D array, shape (n_samples, n_features). "
+        "Cells may be numeric, string (categorical), or bool."
+    )
+    feature_names: list[str] = Field(
+        description="Column names for features. Must match the model's training "
+        "schema in name and order."
+    )
+
+
+class ExplainResponse(BaseModel):
+    """Batch-shaped explanation arrays. Dimension 0 is the batch.
+
+    `/explain` is purely an attribution endpoint — it does not return
+    predictions. Callers that need both predictions and attributions
+    should use `/predict_and_explain` instead.
+    """
+
+    model_id: str
+    attributions: list[list[float]]
+    feature_names: list[str]
+    ohe_feature_names: list[str] | None = Field(
+        default=None,
+        description=(
+            "OHE-expanded column labels aligned to attributions. Present when "
+            "the model has categorical features; the raw feature_names list has "
+            "fewer entries than the attributions array in that case."
+        ),
+    )
+
+
+# --- POST /v1/models/{model_id}/predict_and_explain ---
+
+
+class PredictAndExplainRequest(BaseModel):
+    """POST /v1/models/{model_id}/predict_and_explain -- Predict + explain in one call."""
+
+    samples: list[list[float | str | bool | None]] = Field(
+        description="2D array, shape (n_samples, n_features). "
+        "Cells may be numeric, string (categorical), or bool."
+    )
+    feature_names: list[str] = Field(
+        description="Column names for features. Must match the model's training "
+        "schema in name and order."
+    )
+    with_persona: bool = False
+    rule_kwargs: dict[str, Any] | None = Field(
+        default=None,
+        description=(
+            "Gates local-rule computation, forwarded to the rule-explanation "
+            "backend. Omitted/null → rules skipped. "
+            "{} → backend defaults. "
+            "Populated dict → use these kwargs (e.g. "
+            '{"selector": "lift_threshold", "lift_threshold": 0.9}).'
+        ),
+    )
+
+
+class PredictAndExplainResponse(BaseModel):
+    """Batch-shaped predict + explain arrays. Dimension 0 is the batch."""
+
+    model_id: str
+    predictions: list[float]
+    attributions: list[list[float]]
+    persona: list[dict[str, Any] | None] | None = None
+    persona_cluster_id: list[int | None] | None = None
+    local_rules: list[dict[str, Any] | None] | None = Field(
+        default=None,
+        description=(
+            "Per-sample rule explanations when rule_kwargs was supplied. "
+            "Each entry has sample_prediction, global_mean, direction, "
+            "active_features, rules[]."
+        ),
+    )
+    feature_names: list[str]
+    ohe_feature_names: list[str] | None = Field(
+        default=None,
+        description=("OHE-expanded column labels aligned to attributions."),
+    )
+
+
+# --- POST /v1/models/{model_id}/interpret ---
+
+
+class InterpretRequest(BaseModel):
+    """POST /v1/models/{model_id}/interpret -- Global feature importance."""
+
+    pass
+
+
+class InterpretResponse(BaseModel):
+    model_id: str
+    global_drivers: list[float] = Field(description="Per-feature importance scores.")
+    feature_names: list[str] | None = None
+    ohe_feature_names: list[str] | None = Field(
+        default=None,
+        description=(
+            "OHE-expanded column labels aligned to global_drivers. Present when "
+            "the model has categorical features."
+        ),
+    )
+
+
+# GET /v1/models/{model_id}/schema returns the SchemaManifest defined alongside
+# the S3 sidecar wire schema in the API repo (app.schemas.messages); the HTTP
+# response and the on-disk manifest share one definition there.
+
+
+# --- POST /v1/models/{model_id}/scenario ---
+
+
+class FeatureConstraintSchema(BaseModel):
+    """Per-feature restriction applied during counterfactual walks.
+
+    Mirrors cleartrace.FeatureConstraint. Continuous-only fields
+    (value_range, monotonic) and categorical-only fields (allowed_values)
+    are validated server-side against the model's feature groups.
+    """
+
+    immutable: bool = False
+    monotonic: Literal["increase", "decrease"] | None = None
+    value_range: tuple[float | None, float | None] | None = None
+    allowed_values: list[Any] | None = None
+
+
+class ScenarioRequest(BaseModel):
+    """POST /v1/models/{model_id}/scenario -- Counterfactual search with constraints."""
+
+    queries: list[list[float | str | bool | None]] = Field(
+        description="2D array, shape (n_queries, n_features). "
+        "Cells may be numeric, string (categorical), or bool."
+    )
+    feature_names: list[str] = Field(
+        description="Column names for features. Must match the model's training "
+        "schema in name and order."
+    )
+    desired_class: int = 1
+    n_walks: int = 500
+    max_steps: int = 30
+    epsilon: float = 0.2
+    random_state: int | None = 42
+    constraints: dict[str, FeatureConstraintSchema] = Field(default_factory=dict)
+
+
+class ScenarioChange(BaseModel):
+    """Single-feature diff between a query and one counterfactual row."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    from_: Any = Field(alias="from")
+    to: Any
+    delta: float | None = None
+
+
+class ScenarioCandidate(BaseModel):
+    row: dict[str, Any]
+    changes: dict[str, ScenarioChange]
+    n_changes: int
+
+
+class ScenarioResultItem(BaseModel):
+    query_index: int
+    query: dict[str, Any]
+    baseline_prediction: float
+    already_at_desired_class: bool
+    scenarios: list[ScenarioCandidate]
+    scenario_count: int
+
+
+class ScenarioResponse(BaseModel):
+    model_id: str
+    desired_class: int
+    results: list[ScenarioResultItem]

outerproduct_http_types/py.typed

@@ -0,0 +1 @@
+

outerproduct_http_types/reasoning.py

@@ -0,0 +1,163 @@
+"""Request schema for the /v1/reasoning/fit endpoint.
+
+`/v1/reasoning/fit` is the wire equivalent of
+`outerproduct_reasoning.reasoning.fit(...)`. The worker imports the real
+`outerproduct_reasoning` package and calls `reasoning.fit(...)`, returning a
+fitted `ReasoningModel` artifact. Both supervised training (no teacher) and
+distillation (teacher_predict_url set) flow through the same request.
+"""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+from .common import JobResponse
+from .trainer import HardwareSpec
+
+
+class ReasoningFitRequest(BaseModel):
+    """POST /v1/reasoning/fit -- Fit a ReasoningModel.
+
+    Dataset delivery mirrors the other training endpoints:
+      * Inline: set `data` and `labels`. `label_column` is ignored.
+      * Pre-uploaded: set `data_uploaded=True`, supply `model_id` and
+        `label_column`. When `teacher_predict_url` is set, labels become
+        evaluation-only (the teacher provides the training target).
+    """
+
+    # --- dataset
+    data: list[list[float | str | bool | None]] | None = Field(
+        None,
+        description="2D feature matrix (n_samples, n_features). Omit when data_uploaded=True.",
+    )
+    labels: list[float] | None = Field(
+        None,
+        description="Target values. Required for supervised training. Optional "
+        "(eval-only) when teacher_predict_url is set.",
+    )
+    feature_names: list[str] | None = Field(
+        None,
+        description="Column names for inline features. Required when inline data "
+        "contains non-numeric values.",
+    )
+    feature_schema: dict[str, dict[str, Any]] | None = Field(
+        None,
+        description="Optional per-column schema for inline data.",
+    )
+    data_uploaded: bool = Field(
+        False,
+        description="If true, read the dataset already at "
+        "traces/{org_id}/{model_id}/training_data.{pkl|csv|parquet}.",
+    )
+    label_column: str | None = Field(
+        None,
+        description="Target column name in the uploaded table.",
+    )
+    model_id: str | None = Field(
+        None, description="Custom model ID; required when data_uploaded=True."
+    )
+
+    # --- connector-based data source
+    data_connector: bool = Field(
+        False,
+        description="If true, read the dataset from a registered connector. "
+        "Mutually exclusive with inline data and data_uploaded.",
+    )
+    connector_id: str | None = Field(
+        None,
+        description="Connector identifier. Required when data_connector=True.",
+    )
+    table_name: str | None = Field(
+        None,
+        description="Table or path within the connector. Required when data_connector=True.",
+    )
+
+    # --- reasoning.fit kwargs
+    model_types: list[str] | None = Field(
+        None,
+        description="Candidate model-family identifiers. reasoning.fit pins the "
+        "surrogate via force_model_type, so at most one entry is accepted.",
+    )
+    n_hyperopt_steps: int = 5
+    device: str | None = Field(None, description="'auto' | 'cuda' | 'cpu'.")
+    random_state: int = 42
+    task_type: Literal["regression", "binclass", "multiclass"] | None = Field(
+        None,
+        description="Learning task. Required for supervised fits; optional when "
+        "teacher_predict_url is set (the teacher pins the task).",
+    )
+    hardware: HardwareSpec | None = Field(
+        None,
+        description="Modal trainer hardware. Omit to use the API server's "
+        "default — currently ModalHardware with the API's pinned trainer "
+        "image. In-process execution is not supported at the API edge to "
+        "prevent the orchestrator from materializing X. Synth-gen and "
+        "finalize always run on the worker server (also out of process); "
+        "no caller-controlled toggle.",
+    )
+
+    # --- distillation
+    teacher_predict_url: str | None = Field(
+        None, description="If set, distil this teacher instead of training on labels."
+    )
+    teacher_predict_headers: dict[str, str] | None = Field(
+        None, description="Headers to send when calling teacher_predict_url."
+    )
+
+    @model_validator(mode="after")
+    def _check_dataset_source(self):
+        # Exactly one of three modes: inline, uploaded, or connector.
+        if self.data_connector and self.data_uploaded:
+            raise ValueError("data_connector and data_uploaded are mutually exclusive")
+        if self.data_connector and self.data is not None:
+            raise ValueError("data_connector and inline data are mutually exclusive")
+
+        if self.data_connector:
+            if not self.connector_id:
+                raise ValueError("connector_id is required when data_connector=True")
+            if not self.table_name:
+                raise ValueError("table_name is required when data_connector=True")
+            if not self.label_column and not self.teacher_predict_url:
+                raise ValueError(
+                    "label_column is required when data_connector=True (unless "
+                    "teacher_predict_url is set)"
+                )
+        elif self.data_uploaded:
+            if not self.model_id:
+                raise ValueError("model_id is required when data_uploaded=True")
+            if not self.label_column and not self.teacher_predict_url:
+                raise ValueError(
+                    "label_column is required when data_uploaded=True (unless "
+                    "teacher_predict_url is set)"
+                )
+        else:
+            if self.data is None:
+                raise ValueError("data is required when data_uploaded is False")
+            if self.labels is None and self.teacher_predict_url is None:
+                raise ValueError(
+                    "labels is required when data_uploaded is False (unless "
+                    "teacher_predict_url is set)"
+                )
+        return self
+
+    @model_validator(mode="after")
+    def _check_model_types_length(self):
+        if self.model_types is not None and len(self.model_types) > 1:
+            raise ValueError(
+                "reasoning.fit pins the surrogate via force_model_type, so "
+                "model_types accepts at most one entry; pass a single value "
+                "or omit."
+            )
+        return self
+
+    @model_validator(mode="after")
+    def _check_feature_names_for_mixed_types(self):
+        if self.data is not None and self.feature_names is None:
+            has_non_numeric = any(isinstance(val, (bool, str)) for row in self.data for val in row)
+            if has_non_numeric:
+                raise ValueError("feature_names is required when data contains non-numeric values")
+        return self
+
+
+class ReasoningFitResponse(JobResponse):
+    """POST /v1/reasoning/fit -- async reasoning-fit job submission response."""

outerproduct_http_types/segment.py

@@ -0,0 +1,59 @@
+"""Request/response schemas for segmentation endpoints."""
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ClusterPersonaSchema(BaseModel):
+    """One cluster's persona description as exposed over HTTP.
+
+    Mirrors the shape written into ``segments.json`` by the segment Lambda;
+    the API repo aliases that S3 wire type onto this HTTP type at the
+    response boundary.
+    """
+
+    model_config = ConfigDict(from_attributes=True)
+
+    cluster_id: int
+    persona_name: str
+    persona_description: str
+    stats: dict[str, Any]
+    differentiating_features: list[dict[str, Any]] | None = None
+
+
+class SegmentRequest(BaseModel):
+    """POST /v1/models/{model_id}/segment -- Supervised segmentation (async)."""
+
+    data: list[list[float | str | bool | None]] | None = Field(
+        None,
+        description="Dataset to segment; uses training data if omitted. "
+        "Cells may be numeric, string (categorical), or bool.",
+    )
+    target_values: list[float] | None = None
+    feature_names: list[str] | None = None
+    min_clusters: int = 4
+    max_clusters: int | None = 10
+    n_search_steps: int = 50
+    use_agent: bool | None = None
+    kpi_field: str | None = None
+    problem_context: str | None = None
+
+
+class SegmentResultResponse(BaseModel):
+    """GET /v1/models/{model_id}/segments -- Retrieve segmentation results.
+
+    Result fields are Optional because pending/running/failed jobs return
+    only model_id + status; populated only once the Lambda has uploaded
+    segments.json and the SegmentsResult is available.
+    """
+
+    model_id: str
+    status: str
+    n_clusters: int | None = None
+    cluster_ids: list[int] | None = None
+    resolution: float | None = None
+    quality: float | None = None
+    personas: list[ClusterPersonaSchema] | None = None
+    agent_score: float | None = None
+    agent_reasoning: str | None = None

outerproduct_http_types/trainer.py

@@ -0,0 +1,197 @@
+"""Request schema for the /v1/trainer/run endpoint.
+
+`/v1/trainer/run` runs the server-side `Trainer` (the replacement for
+`ModelOrchestrator` in `outerproduct-trainer`). It compiles a model matrix
+across one or more model families and runs HPO, optionally with k-fold CV,
+ensembling, or a Pareto sweep over multiple metrics.
+"""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+from .common import JobResponse
+
+
+class ModalHardwareSpec(BaseModel):
+    """Fan trials out to additional Modal containers.
+
+    The only supported hardware spec for API requests. Local execution is
+    intentionally not exposed at the wire — running PlanNodes in-process
+    means materializing the dataset in the API container, which OOM's the
+    Render server on any non-trivial input. Library / notebook callers can
+    still construct ``LocalHardware()`` directly via ``outerproduct-trainer``;
+    the wire-level lockdown only applies to API requests.
+    """
+
+    kind: Literal["modal"] = "modal"
+    gpu: str = Field("A10G", description="Modal GPU type, e.g. 'A10G', 'T4', 'L40S'.")
+    timeout_s: int = Field(1200, description="Per-trial timeout in seconds.")
+    n_concurrent: int = Field(4, description="Max parallel trial containers.")
+
+
+HardwareSpec = ModalHardwareSpec
+
+
+class TrainerRunRequest(BaseModel):
+    """POST /v1/trainer/run -- Configure a Trainer and run HPO across a model matrix.
+
+    Dataset delivery mirrors the other training endpoints:
+      * Inline: set `data` and `labels`. `label_column` is ignored.
+      * Pre-uploaded: set `data_uploaded=True`, supply `model_id` and
+        `label_column` (the column in the uploaded table that holds the target).
+    """
+
+    # --- dataset
+    data: list[list[float | str | bool | None]] | None = Field(
+        None,
+        description="2D feature matrix (n_samples, n_features). Omit when data_uploaded=True.",
+    )
+    labels: list[float] | None = Field(
+        None,
+        description="Target values, length n_samples. Omit when data_uploaded=True.",
+    )
+    feature_names: list[str] | None = Field(
+        None,
+        description="Column names for inline features. Required when inline data "
+        "contains non-numeric values.",
+    )
+    feature_schema: dict[str, dict[str, Any]] | None = Field(
+        None,
+        description="Optional per-column schema for inline data: "
+        "{name: {dtype: 'float' | 'int' | 'bool' | 'categorical'}}.",
+    )
+    data_uploaded: bool = Field(
+        False,
+        description="If true, read the dataset already at "
+        "traces/{org_id}/{model_id}/training_data.{pkl|csv|parquet}.",
+    )
+    label_column: str | None = Field(
+        None,
+        description="Target column name in the uploaded table. Required when data_uploaded=True.",
+    )
+    model_id: str | None = Field(
+        None, description="Custom model ID; required when data_uploaded=True."
+    )
+
+    # --- connector-based data source
+    data_connector: bool = Field(
+        False,
+        description="If true, read the dataset from a registered connector. "
+        "Mutually exclusive with inline data and data_uploaded.",
+    )
+    connector_id: str | None = Field(
+        None,
+        description="Connector identifier. Required when data_connector=True.",
+    )
+    table_name: str | None = Field(
+        None,
+        description="Table or path within the connector. Required when data_connector=True.",
+    )
+
+    # --- trainer configuration
+    model_types: list[str] | None = Field(
+        None,
+        description="Candidate model-family identifiers, e.g. ['tabm', 'xgboost', "
+        "'xrfm', 'tabicl']. Resolved server-side. If omitted, the server picks a "
+        "default set based on dataset shape.",
+    )
+    metrics: list[str] | None = Field(
+        None,
+        description="Metric names to optimise, e.g. ['auc'] or ['auc', "
+        "'neg_class_error']. Multi-metric requests trigger a Pareto sweep when "
+        "grid_size is set. Custom Python callables are not supported in v1.",
+    )
+    strategy: str = Field(
+        "random",
+        description="HPO strategy: 'random' or 'optuna'. Resolved server-side.",
+    )
+    n_trials: int = Field(4, description="Number of HPO trials per matrix row.")
+    n_splits: int | None = Field(
+        None,
+        description="K-fold cross-validation folds. None means a single holdout split.",
+    )
+    ensemble: bool = Field(
+        False,
+        description="If true, build a Caruana-style ensemble across stage-1 fold/trial "
+        "models instead of refitting the winner on full data.",
+    )
+    grid_size: float | None = Field(
+        None,
+        description="Simplex grid step for Pareto-style multi-metric sweeps.",
+    )
+    task_type: Literal["regression", "binclass", "multiclass"] | None = Field(
+        None,
+        description="Learning task. Required for supervised runs; optional when "
+        "teacher_predict_url is set.",
+    )
+
+    # --- distillation
+    teacher_predict_url: str | None = Field(
+        None,
+        description="If set, distil this teacher's predictions instead of training "
+        "against `label_column`. The worker calls this URL with "
+        "{'samples': [[...]], 'feature_names': [...]}.",
+    )
+    teacher_predict_headers: dict[str, str] | None = Field(
+        None, description="Headers to send when calling teacher_predict_url."
+    )
+
+    # --- execution
+    hardware: HardwareSpec | None = Field(
+        None,
+        description="Modal trials hardware. Omit to use the API server's "
+        "default — currently ModalHardware with the API's pinned trainer "
+        "image. In-process execution is not supported at the API edge to "
+        "prevent the orchestrator from materializing X.",
+    )
+    random_state: int = 42
+
+    @model_validator(mode="after")
+    def _check_dataset_source(self):
+        # Exactly one of three modes: inline, uploaded, or connector.
+        if self.data_connector and self.data_uploaded:
+            raise ValueError("data_connector and data_uploaded are mutually exclusive")
+        if self.data_connector and self.data is not None:
+            raise ValueError("data_connector and inline data are mutually exclusive")
+
+        if self.data_connector:
+            if not self.connector_id:
+                raise ValueError("connector_id is required when data_connector=True")
+            if not self.table_name:
+                raise ValueError("table_name is required when data_connector=True")
+            if not self.label_column and not self.teacher_predict_url:
+                raise ValueError(
+                    "label_column is required when data_connector=True (unless "
+                    "teacher_predict_url is set)"
+                )
+        elif self.data_uploaded:
+            if not self.model_id:
+                raise ValueError("model_id is required when data_uploaded=True")
+            if not self.label_column and not self.teacher_predict_url:
+                raise ValueError(
+                    "label_column is required when data_uploaded=True (unless "
+                    "teacher_predict_url is set, in which case the teacher provides "
+                    "the training target)"
+                )
+        else:
+            if self.data is None:
+                raise ValueError("data is required when data_uploaded is False")
+            if self.labels is None and self.teacher_predict_url is None:
+                raise ValueError(
+                    "labels is required when data_uploaded is False (unless "
+                    "teacher_predict_url is set)"
+                )
+        return self
+
+    @model_validator(mode="after")
+    def _check_feature_names_for_mixed_types(self):
+        if self.data is not None and self.feature_names is None:
+            has_non_numeric = any(isinstance(val, (bool, str)) for row in self.data for val in row)
+            if has_non_numeric:
+                raise ValueError("feature_names is required when data contains non-numeric values")
+        return self
+
+
+class TrainerRunResponse(JobResponse):
+    """POST /v1/trainer/run -- async trainer job submission response."""

outerproduct_http_types/uploads.py

@@ -0,0 +1,34 @@
+"""Request/response schemas for the presigned-upload endpoint."""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class CreateUploadRequest(BaseModel):
+    """POST /v1/uploads -- request a presigned URL for direct-to-S3 upload."""
+
+    model_id: str | None = Field(
+        None,
+        description="Custom model ID; auto-generated if omitted.",
+    )
+    file_format: Literal["pkl", "csv", "parquet"] = Field(
+        ...,
+        description=(
+            "Format of the dataset you will PUT to the returned URL. "
+            "'pkl' = a pickled pandas DataFrame, 'csv' = RFC4180 CSV with a "
+            "header row, 'parquet' = Apache Parquet. The label column must be "
+            "present in the uploaded table and its name is supplied on the "
+            "subsequent /v1/trainer/run or /v1/reasoning/fit call as "
+            "`label_column`."
+        ),
+    )
+
+
+class CreateUploadResponse(BaseModel):
+    model_id: str
+    upload_url: str
+    upload_key: str
+    file_format: Literal["pkl", "csv", "parquet"]
+    content_type: str
+    expires_in: int

outerproduct_http_types/workers.py

@@ -0,0 +1,25 @@
+"""Request/response schemas for the worker server (finalize + synth_gen)."""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class WorkerJobRequest(BaseModel):
+    """Body for POST /v1/workers/{finalize,synthgen}.
+
+    Mirrors the AWS Lambda event shape that preceded the worker server: the
+    caller uploads a cloudpickled kwargs dict to ``s3://{s3_bucket}/{input_key}``
+    and the worker writes its cloudpickled output back to ``output_key``.
+    """
+
+    s3_bucket: str
+    input_key: str = Field(description="S3 key of the cloudpickled input dict.")
+    output_key: str = Field(description="S3 key the worker writes its cloudpickled result to.")
+
+
+class WorkerJobResponse(BaseModel):
+    """Response from POST /v1/workers/{finalize,synthgen}."""
+
+    status: Literal["ok"] = "ok"
+    output_key: str

outerproduct_http_types-0.1.0.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: outerproduct-http-types
+Version: 0.1.0
+Summary: Shared HTTP-facing type definitions for OuterProduct services and SDKs.
+Project-URL: Homepage, https://outerproduct.com
+Author: OuterProduct, Inc.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,http,outerproduct,pydantic,sdk,wire-types
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.13.3
+Description-Content-Type: text/markdown
+
+# outerproduct-http-types
+
+Shared HTTP-facing type definitions for the [OuterProduct](https://outerproduct.com) API.
+
+This package contains the [Pydantic](https://docs.pydantic.dev) models that
+describe the request and response shapes used across OuterProduct services and
+SDKs. It is the source of truth for the wire contract between the OuterProduct
+backend and any client (including the official Python SDK).
+
+Most users should not depend on this package directly. Instead, install the
+OuterProduct SDK, which re-exports the relevant types and provides a typed
+client. Use this package only when you are building tooling that needs to
+construct or parse OuterProduct API payloads independently of the SDK.
+
+## Installation
+
+```bash
+pip install outerproduct-http-types
+```
+
+Requires Python 3.12 or newer.
+
+## Usage
+
+Import the model that matches the endpoint you are working with and construct
+or validate payloads as you would with any Pydantic model:
+
+```python
+from outerproduct_http_types import PredictRequest, PredictResponse
+
+request = PredictRequest(
+    samples=[[1.0, "x"], [2.5, "y"]],
+    feature_names=["feature_a", "feature_b"],
+)
+payload = request.model_dump_json()
+
+# ... POST `payload` to /v1/models/{model_id}/predict, then parse:
+response = PredictResponse.model_validate_json(raw_response_body)
+print(response.model_id, response.predictions)
+```
+
+The package ships with a `py.typed` marker, so type checkers (mypy, pyright,
+ty) will pick up the type information automatically.
+
+## Versioning
+
+This package follows [semantic versioning](https://semver.org/). Breaking
+changes to wire types are released as a new major version. Minor versions add
+new endpoints or optional fields; patch versions are reserved for documentation
+and non-behavioral fixes.
+
+## License
+
+Licensed under the [MIT License](https://opensource.org/license/mit).

outerproduct_http_types-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+outerproduct_http_types/__init__.py,sha256=nhMPlPi-KVnaRVkZcxtPiyrH-mYnDHh21D0UnRs50mo,2865
+outerproduct_http_types/agentic_documents.py,sha256=izshgOeU4w2qv6Ohe6hGWbctmAm1BPiZde2zQbV4pTU,7975
+outerproduct_http_types/common.py,sha256=pp-LG2rq2sKYyHDQyea-DZkTUpIooIJj63V-TRaUCpw,1248
+outerproduct_http_types/connectors.py,sha256=OfWDjNL_-7dsQr_sDYIrt6BOYJIBz1RknpfTsvAfZA8,3698
+outerproduct_http_types/inference.py,sha256=c-DwT9XVZ9KHT8uUw2pSGe-0LlulFvpmim9IV2OQTRw,6553
+outerproduct_http_types/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+outerproduct_http_types/reasoning.py,sha256=fSRe22uk14BM-4oaV5JXhmwOAmxnaOTw1eLGE3ja9v0,6792
+outerproduct_http_types/segment.py,sha256=X5z1JpcYeP4RBstfvNjSiBWLWQlN5KhjDV9GcFwdCcQ,1892
+outerproduct_http_types/trainer.py,sha256=Xidgwt1FHk4whF9LKwVmXcsH2bSJCMnNSsd97bzrIcE,8169
+outerproduct_http_types/uploads.py,sha256=_EYUJAh2o1WovzCmeJ9rZX1LGfMnfoRN0TjN6DSSz0Y,1083
+outerproduct_http_types/workers.py,sha256=LMREW5tbi2Rw0mcgv053a-Ccqb3ooMCsr2cWzcHcths,827
+outerproduct_http_types-0.1.0.dist-info/METADATA,sha256=SFNUQPEfcqahKp8YSi-u_FciKNwfLoWW3qbZ6qPcVWg,2804
+outerproduct_http_types-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+outerproduct_http_types-0.1.0.dist-info/licenses/LICENSE,sha256=5PAE0YxWHzDk5S9Jhmii65APx30_BVTzefsO8tCMgrU,1068
+outerproduct_http_types-0.1.0.dist-info/RECORD,,

outerproduct_http_types-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

outerproduct_http_types-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OuterProduct
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.