outerproduct-http-types 0.1.0__tar.gz

outerproduct_http_types-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+.DS_Store
+
+# Python bytecode and caches
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.ty/
+
+# Python build artifacts
+build/
+dist/
+*.egg-info/
+
+# Local virtual environments
+.venv/
+
+# Local editor and environment files
+.env
+.env.*
+!.env.example
+.vscode/
+.idea/
+

outerproduct_http_types-0.1.0/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.

outerproduct_http_types-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,54 @@
+# 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/pyproject.toml

@@ -0,0 +1,88 @@
+[project]
+name = "outerproduct-http-types"
+version = "0.1.0"
+description = "Shared HTTP-facing type definitions for OuterProduct services and SDKs."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [
+    { name = "OuterProduct, Inc." },
+]
+keywords = [
+    "outerproduct",
+    "sdk",
+    "http",
+    "pydantic",
+    "wire-types",
+    "api",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet :: WWW/HTTP",
+    "Typing :: Typed",
+]
+license-files = ["LICENSE"]
+dependencies = [
+    "pydantic>=2.13.3",
+]
+
+[project.urls]
+Homepage = "https://outerproduct.com"
+
+[dependency-groups]
+dev = [
+    "prek>=0.3.11",
+    "pytest>=8.0",
+    "ruff>=0.15.12",
+]
+lsp = [
+    "ty>=0.0.32",
+]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/outerproduct_http_types"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/outerproduct_http_types",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src"]
+extend-exclude = [".agents"]
+force-exclude = true
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "RUF"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["outerproduct_http_types"]
+
+[tool.ty.environment]
+python-version = "3.12"
+
+[tool.ty.src]
+include = ["src/**/*.py"]
+exclude = [".agents/**"]
+
+[tool.ty.terminal]
+output-format = "full"
+error-on-warning = false
+

outerproduct_http_types-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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"')