| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309 |
- """Wire models for the gateway connector routes.
- Tolerate added gateway fields; callers receive plain dictionaries. Correlate results by position, never wire ``index``.
- """
- from __future__ import annotations
- from typing import Any, Literal, Optional
- from pydantic import BaseModel, ConfigDict, Field
- CONNECTORS_PATH = "v1/connectors"
- CONNECTOR_SEARCH_PATH = f"{CONNECTORS_PATH}/search"
- CONNECTOR_SCHEMAS_PATH = f"{CONNECTORS_PATH}/schemas"
- CONNECTOR_EXECUTE_PATH = f"{CONNECTORS_PATH}/execute"
- CONNECTOR_CONNECTIONS_PATH = f"{CONNECTORS_PATH}/connections"
- CONNECTOR_ACCOUNTS_PATH = f"{CONNECTORS_PATH}/accounts"
- CONNECTOR_FILE_UPLOAD_PATH = f"{CONNECTORS_PATH}/files/upload"
- # The gateway's cap on a staged file's declared size.
- CONNECTOR_FILE_MAX_BYTES = 20 * 1024 * 1024
- # The gateway's six-state account status (contract `CONNECTOR_CONNECTION_STATUSES`; the vendor's
- # INITIALIZING and INITIATED both arrive as `pending`). Present only once the session binds an
- # account; a value outside this set is a contract break and fails validation.
- ConnectionStatus = Literal["pending", "active", "failed", "expired", "revoked", "inactive"]
- # Where the vendor's done page sends the browser after consent; the dev desktop registers hermes-dev://.
- ConnectorReturnTarget = Literal["hermes-desktop", "hermes-desktop-dev", "portal"]
- # Who asked for a connect, so the gateway can attribute each minted link. The gateway sets
- # ``execute_link`` and ``portal`` itself; an older gateway ignores the field.
- ConnectorInitiator = Literal["agent_tool", "desktop_page", "card_retry"]
- # Hermes dispatch caps batches lower, so client-side chunking is deliberately absent.
- WIRE_BATCH_MAX = 25
- # Any string: a gateway newer than this client may add codes, and an unknown code still renders.
- ConnectorErrorCode = str
- # `product`: the request or the user's setup is the cause. `backend`: the gateway or the vendor failed.
- ErrorFamily = Literal["product", "backend"]
- # Single-call execute failures: code -> (family, HTTP status). The legacy array envelope carries only
- # TOOL_NOT_ALLOWED, CONNECTION_REQUIRED, TOOL_NOT_FOUND and PROVIDER_ERROR, always under a 200.
- EXECUTE_ERROR_CODES: dict[str, tuple[ErrorFamily, int]] = {
- "TOOL_NOT_ALLOWED": ("product", 403),
- "CONNECTION_REQUIRED": ("product", 409),
- "CONNECTION_EXPIRED": ("product", 409),
- "ALIAS_REQUIRED": ("product", 422),
- "ALIAS_UNKNOWN": ("product", 422),
- "INVALID_ARGUMENTS": ("product", 422),
- "TOOL_NOT_FOUND": ("product", 404),
- "PROVIDER_ERROR": ("backend", 502),
- "PROVIDER_RATE_LIMITED": ("backend", 429),
- "PROVIDER_TIMEOUT": ("backend", 504),
- "POLICY_UNAVAILABLE": ("backend", 503),
- "GATEWAY_ERROR": ("backend", 500),
- }
- # Failures the agent reports itself while staging a file input, before the call reaches execute.
- FILE_ERROR_FAMILIES: dict[str, ErrorFamily] = {
- "FILE_NOT_ALLOWED": "product",
- "FILE_NOT_FOUND": "product",
- "FILE_TOO_LARGE": "product",
- "FILE_UPLOAD_FAILED": "backend",
- }
- def execute_error_family(code: str, family: Optional[str] = None) -> Optional[str]:
- """The gateway's family when it sent one, else the table's; ``None`` for an unknown code."""
- if family in ("product", "backend"):
- return family
- known = EXECUTE_ERROR_CODES.get(code)
- return known[0] if known else FILE_ERROR_FAMILIES.get(code)
- class _Wire(BaseModel):
- model_config = ConfigDict(extra="ignore", populate_by_name=True)
- class ConnectorSearchQuery(_Wire):
- use_case: str = Field(alias="useCase")
- known_fields: Optional[str] = Field(default=None, alias="knownFields")
- class ConnectorSearchRequest(_Wire):
- queries: list[ConnectorSearchQuery]
- class ConnectorToolSchema(_Wire):
- connector: str
- tool: str
- description: str = ""
- input_schema: dict[str, Any] = Field(default_factory=dict, alias="inputSchema")
- class ConnectorSearchResult(_Wire):
- # Vendor passthrough; result correlation uses array position.
- index: int
- use_case: str = Field(default="", alias="useCase")
- tools: list[str] = Field(default_factory=list)
- related_tools: list[str] = Field(default_factory=list, alias="relatedTools")
- connectors: list[str] = Field(default_factory=list)
- guidance: Optional[str] = None
- plan_steps: Optional[list[str]] = Field(default=None, alias="planSteps")
- pitfalls: Optional[list[str]] = None
- error: Optional[str] = None
- class ConnectorConnectionStatus(_Wire):
- connector: str
- connected: bool = False
- description: str = ""
- class ConnectorSearchResponse(_Wire):
- results: list[ConnectorSearchResult] = Field(default_factory=list)
- schemas: dict[str, ConnectorToolSchema] = Field(default_factory=dict)
- connections: list[ConnectorConnectionStatus] = Field(default_factory=list)
- next_steps: list[str] = Field(default_factory=list, alias="nextSteps")
- class ConnectorSchemasRequest(_Wire):
- tools: list[str]
- class ConnectorSchemasResponse(_Wire):
- schemas: dict[str, ConnectorToolSchema] = Field(default_factory=dict)
- not_found: list[str] = Field(default_factory=list, alias="notFound")
- suggestions: dict[str, list[str]] = Field(default_factory=dict)
- class ConnectorFileUploadRequest(_Wire):
- toolkit: str
- tool: str
- filename: str
- mimetype: str
- size: int
- class ConnectorFileDescriptor(_Wire):
- """The value a ``file_uploadable`` tool input takes on the wire."""
- name: str
- mimetype: str
- s3key: str
- class ConnectorFileUploadResponse(_Wire):
- upload_url: str = Field(alias="uploadUrl")
- headers: dict[str, str] = Field(default_factory=dict)
- descriptor: ConnectorFileDescriptor
- expires_at: str = Field(alias="expiresAt")
- class ConnectorToolError(_Wire):
- code: ConnectorErrorCode
- message: str
- connector: Optional[str] = None
- connect_url: Optional[str] = Field(default=None, alias="connectUrl")
- # The account the link was minted for; absent when the link mint failed. Absent means nothing to watch.
- connection_id: Optional[str] = Field(default=None, alias="connectionId")
- hint: Optional[str] = None
- family: Optional[str] = None
- class ConnectorExecuteFailure(ConnectorToolError):
- """The body of a non-2xx single-call execute answer."""
- request_id: Optional[str] = Field(default=None, alias="requestId")
- class ConnectorExecuteCall(_Wire):
- connector: str
- tool: str
- arguments: dict[str, Any] = Field(default_factory=dict)
- # Never sent by hermes: the model picks an account with the ``connector_alias`` argument, which
- # the gateway strips and resolves itself.
- account: Optional[str] = None
- class ConnectorExecuteRequest(_Wire):
- tools: list[ConnectorExecuteCall]
- # Ride any CONNECTION_REQUIRED link the call mints back to the surface that asked.
- return_to: Optional[ConnectorReturnTarget] = Field(default=None, alias="returnTo")
- op: Optional[str] = Field(default=None, min_length=1, max_length=128)
- class ConnectorExecuteSingleRequest(_Wire):
- call: ConnectorExecuteCall
- return_to: Optional[ConnectorReturnTarget] = Field(default=None, alias="returnTo")
- op: Optional[str] = Field(default=None, min_length=1, max_length=128)
- # What a model receiving this result must guarantee; absent when the connector asks nothing.
- DataUseRequirement = Literal["no_training", "zero_retention"]
- class ConnectorDataUse(_Wire):
- requires: list[DataUseRequirement]
- class ConnectorExecuteSingleResult(_Wire):
- connector: str = ""
- tool: str = ""
- data: Any = None
- account: Optional[str] = None
- data_use: Optional[ConnectorDataUse] = Field(default=None, alias="dataUse")
- class ConnectorExecuteSingleResponse(_Wire):
- result: ConnectorExecuteSingleResult
- class ConnectorExecuteResult(_Wire):
- # Never correlate results by wire index.
- index: int = 0
- connector: str = ""
- tool: str = ""
- data: Any = None
- error: Optional[ConnectorToolError] = None
- # The alias of the account the call ran under; null when that account has no alias.
- account: Optional[str] = None
- data_use: Optional[ConnectorDataUse] = Field(default=None, alias="dataUse")
- class ConnectorExecuteResponse(_Wire):
- results: list[ConnectorExecuteResult] = Field(default_factory=list)
- success_count: int = Field(default=0, alias="successCount")
- error_count: int = Field(default=0, alias="errorCount")
- total_count: int = Field(default=0, alias="totalCount")
- class ConnectorConnectionsRequest(_Wire):
- connectors: list[str]
- reinitiate: bool = False
- alias: Optional[str] = None
- # The existing account a reinitiate repairs; sent instead of ``alias`` when known.
- connection_id: Optional[str] = Field(default=None, alias="connectionId")
- return_to: Optional[ConnectorReturnTarget] = Field(default=None, alias="returnTo")
- # The caller's operation id, echoed on the hermes://connections/done link.
- op: Optional[str] = Field(default=None, min_length=1, max_length=128)
- initiator: Optional[ConnectorInitiator] = None
- class ConnectorConnectionResult(_Wire):
- connector: str
- status: Literal["active", "initiated", "failed"]
- connect_url: Optional[str] = Field(default=None, alias="connectUrl")
- # The vendor account the mint created or observed. Optional by vendor semantics (a no-auth toolkit
- # answers active with none); a target without one has nothing to watch.
- connection_id: Optional[str] = Field(default=None, alias="connectionId")
- alias: Optional[str] = None
- instruction: Optional[str] = None
- # Vendor error_message on ``failed``; the list route never carries it.
- status_reason: Optional[str] = Field(default=None, alias="statusReason")
- reinitiated: bool = False
- class ConnectorListItem(_Wire):
- connector: str
- enabled: bool = True
- connected: bool = False
- connection_status: Optional[ConnectionStatus] = Field(default=None, alias="connectionStatus")
- status_reason: Optional[str] = Field(default=None, alias="statusReason")
- gateway_disabled_tools: list[str] = Field(default_factory=list, alias="disabledTools")
- class ConnectorListResponse(_Wire):
- items: list[ConnectorListItem]
- next_cursor: Optional[str] = Field(default=None, alias="nextCursor")
- class ConnectorAccount(_Wire):
- connection_id: str = Field(alias="connectionId")
- connector: str
- status: ConnectionStatus
- status_reason: Optional[str] = Field(default=None, alias="statusReason")
- label: str = Field(min_length=1)
- alias: Optional[str] = None
- # The newest active account for this connector: the one the vendor executes with.
- active: bool
- # Retired by a reconnect that replaced it; kept, never selectable.
- disabled: bool = False
- created_at: str = Field(alias="createdAt")
- updated_at: str = Field(alias="updatedAt")
- class ConnectorAccountsResponse(_Wire):
- accounts: list[ConnectorAccount]
- class RemovedConnectorAccount(_Wire):
- connection_id: str = Field(alias="connectionId")
- connector: str
- status: Literal["removed"]
- class ConnectorConnectionsSummary(_Wire):
- total: int = 0
- active: int = 0
- initiated: int = 0
- failed: int = 0
- class ConnectorConnectionsResponse(_Wire):
- results: list[ConnectorConnectionResult] = Field(default_factory=list)
- summary: ConnectorConnectionsSummary = Field(
- default_factory=ConnectorConnectionsSummary
- )
|