alloy-runtime-types 0.1.0__tar.gz

alloy_runtime_types-0.1.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: alloy-runtime-types
+Version: 0.1.0
+Summary: Type definitions and DTOs for Alloy Runtime
+Author-email: Grant Jordan <gjordan1997@gmail.com>
+Project-URL: Repository, https://github.com/alloy-runtime/alloy-runtime
+Project-URL: Issues, https://github.com/alloy-runtime/alloy-runtime/issues
+Keywords: alloy,api,dto,python,types
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.12.3
+
+# alloy-runtime-types
+
+Shared DTOs, enums, and parsing helpers for Alloy Runtime Python clients.
+
+## Install
+
+```bash
+pip install alloy-runtime-types
+```
+
+## What it includes
+
+- Pydantic request and response models used by the SDK and CLI.
+- Shared enums for ownership scope, providers, and tool metadata.
+- Parsing helpers used by higher-level packages.
+
+This package is published separately so `alloy-runtime-sdk` and `alloy-runtime-cli`
+can be installed cleanly from PyPI without a workspace checkout.

alloy_runtime_types-0.1.0/README.md

@@ -0,0 +1,18 @@
+# alloy-runtime-types
+
+Shared DTOs, enums, and parsing helpers for Alloy Runtime Python clients.
+
+## Install
+
+```bash
+pip install alloy-runtime-types
+```
+
+## What it includes
+
+- Pydantic request and response models used by the SDK and CLI.
+- Shared enums for ownership scope, providers, and tool metadata.
+- Parsing helpers used by higher-level packages.
+
+This package is published separately so `alloy-runtime-sdk` and `alloy-runtime-cli`
+can be installed cleanly from PyPI without a workspace checkout.

alloy_runtime_types-0.1.0/alloy_runtime_types/__init__.py

@@ -0,0 +1 @@
+# Empty per project convention - import directly from submodules

alloy_runtime_types-0.1.0/alloy_runtime_types/dtos/__init__.py

@@ -0,0 +1 @@
+# Empty per project convention - import directly from submodules

alloy_runtime_types-0.1.0/alloy_runtime_types/dtos/admin.py

@@ -0,0 +1,25 @@
+"""DTOs for admin operations."""
+
+from pydantic import BaseModel
+
+
+class SyncModelsRequest(BaseModel):
+    """Request to sync AI models from external providers."""
+
+    pass
+
+
+class ProviderSyncResult(BaseModel):
+    """Results from syncing a single provider source."""
+
+    models_synced: int
+    providers_synced: int
+    error: str | None = None
+
+
+class SyncModelsResponse(BaseModel):
+    """Aggregated sync results from all provider sources."""
+
+    total_models_synced: int
+    total_providers_synced: int
+    by_source: dict[str, ProviderSyncResult]

alloy_runtime_types-0.1.0/alloy_runtime_types/dtos/agents.py

@@ -0,0 +1,362 @@
+"""DTOs for agent operations."""
+
+from datetime import datetime
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel, Field, model_validator
+from typing_extensions import Self
+
+from alloy_runtime_types.dtos.generation import GenerationParameters
+from alloy_runtime_types.dtos.mcp_servers import (
+    AgentMCPServerConfig,
+    AgentMCPServerResponse,
+)
+from alloy_runtime_types.enums.ownership_scope import OwnershipScope
+from alloy_runtime_types.enums.provider import Provider
+
+
+class AgentModelConfig(BaseModel):
+    """Configuration for an agent model."""
+
+    provider_key: Provider = Field(min_length=1)
+    provider_model_name: str = Field(min_length=1)
+    preference_order: int = Field(default=0, ge=0)
+
+
+class AgentToolConfig(BaseModel):
+    """Configuration for an agent tool.
+
+    Configuration can come from either:
+    - Inline config (config field): Direct configuration dict
+    - Config reference (tool_config_id): Reference to a reusable ToolConfig
+
+    These are mutually exclusive - at most one can be set.
+
+    The tool_alias enables multiple instances of the same tool per agent.
+    It defaults to tool_id when not provided and is used as the OpenAI function name.
+    """
+
+    tool_id: str = Field(min_length=1)
+    tool_alias: str | None = Field(
+        default=None,
+        min_length=1,
+        description="Unique alias for this tool instance within the agent. "
+        "Used as the OpenAI function name. Defaults to tool_id if not provided.",
+    )
+    org_credential_id: UUID | None = None
+    is_enabled: bool = True
+    tool_order: int = Field(default=0, ge=0)
+    config: dict[str, Any] | None = Field(
+        default=None,
+        description="Inline tool configuration. Validated against tool's parameter_schema.",
+    )
+    tool_config_id: UUID | None = Field(
+        default=None,
+        description="Reference to a reusable ToolConfig. Mutually exclusive with config.",
+    )
+    llm_instruction: str | None = Field(
+        default=None,
+        description="Optional instruction appended to tool description for LLM. "
+        "Provides per-agent hints about when/how to use this tool.",
+    )
+
+    @model_validator(mode="after")
+    def validate_config_exclusivity(self) -> Self:
+        """Ensure config and tool_config_id are mutually exclusive."""
+        if self.config is not None and self.tool_config_id is not None:
+            raise ValueError(
+                "Cannot specify both config and tool_config_id. Provide one or neither."
+            )
+        return self
+
+    @property
+    def effective_alias(self) -> str:
+        """Return tool_alias if set, otherwise tool_id."""
+        return self.tool_alias if self.tool_alias else self.tool_id
+
+
+class CreateAgentRequest(BaseModel):
+    """Request to create a new agent."""
+
+    name: str = Field(min_length=1)
+    models: list[AgentModelConfig] = Field(min_length=1)
+    tags: list[str] = Field(
+        default_factory=list,
+        description="List of tag paths to associate with this agent. Required for user and organization scoped agents. Must be empty for global agents.",
+    )
+    scope: OwnershipScope = Field(default=OwnershipScope.USER)
+    base_agent_id: UUID | None = None
+    description: str | None = None
+    system_instruction_template: str | UUID | None = Field(
+        default=None,
+        description="System instruction template identifier - can be UUID or template name. "
+        "Names are resolved with priority: user-owned > org-owned > global.",
+    )
+    system_instruction_version_id: UUID | None = None
+    input_schema_id: UUID | None = None
+    output_schema_id: UUID | None = None
+    output_schema: dict[str, Any] | None = None
+    default_request_headers: dict[str, str] | None = None
+    generation_params: GenerationParameters | None = Field(
+        default=None,
+        description="Default generation parameters for this agent",
+    )
+    tools: list[AgentToolConfig] | None = None
+    mcp_servers: list[AgentMCPServerConfig] | None = None
+
+    @model_validator(mode="after")
+    def validate_output_schema_exclusivity(self) -> Self:
+        """Ensure output_schema_id and output_schema are mutually exclusive."""
+        if self.output_schema_id is not None and self.output_schema is not None:
+            raise ValueError(
+                "Cannot specify both output_schema_id and output_schema. "
+                "Provide one or neither."
+            )
+        return self
+
+    @model_validator(mode="after")
+    def validate_tool_alias_uniqueness(self) -> Self:
+        """Ensure tool_alias is unique within the tools list."""
+        if self.tools:
+            aliases = [t.effective_alias for t in self.tools]
+            if len(aliases) != len(set(aliases)):
+                raise ValueError(
+                    "Each tool must have a unique tool_alias. "
+                    "Duplicate aliases found in tools list."
+                )
+        return self
+
+    @model_validator(mode="after")
+    def validate_mcp_server_id_uniqueness(self) -> Self:
+        """Ensure mcp_server_id is unique within the mcp_servers list."""
+        if self.mcp_servers:
+            ids = [m.mcp_server_id for m in self.mcp_servers]
+            if len(ids) != len(set(ids)):
+                raise ValueError(
+                    "Duplicate mcp_server_id found in mcp_servers list. "
+                    "Each MCP server can only be attached once."
+                )
+        return self
+
+
+class AgentModelResponse(BaseModel):
+    """Response model for agent model configuration."""
+
+    agent_id: UUID
+    provider_key: Provider
+    provider_model_name: str
+    preference_order: int
+
+
+class AgentToolResponse(BaseModel):
+    """Response model for agent tool configuration."""
+
+    agent_id: UUID
+    tool_alias: str = Field(description="Unique alias for this tool within the agent")
+    tool_id: str = Field(description="Tool implementation ID (references ai.tools.id)")
+    org_credential_id: UUID | None
+    is_enabled: bool
+    tool_order: int
+    config: dict[str, Any] | None = None
+    tool_config_id: UUID | None = None
+    tool_config_name: str | None = Field(
+        default=None,
+        description="Name of the referenced ToolConfig (convenience field for display)",
+    )
+    llm_instruction: str | None = Field(
+        default=None,
+        description="Optional instruction appended to tool description for LLM",
+    )
+    created_at: datetime
+
+
+class AgentTagResponse(BaseModel):
+    """Response model for agent tag."""
+
+    tag_id: UUID
+    tag_path: str
+    display_name: str
+
+
+class CreateAgentResponse(BaseModel):
+    """Response after creating an agent."""
+
+    id: UUID
+    name: str
+    organization_id: UUID | None
+    user_id: UUID | None
+    base_agent_id: UUID | None
+    description: str | None
+    system_instruction_version_id: UUID | None
+    input_schema_id: UUID | None
+    output_schema_id: UUID | None
+    default_request_headers: dict[str, str] | None
+    generation_params: GenerationParameters | None = None
+    created_at: datetime
+    updated_at: datetime
+    models: list[AgentModelResponse]
+    tools: list[AgentToolResponse]
+    mcp_servers: list[AgentMCPServerResponse] = []
+    tags: list[AgentTagResponse]
+
+
+class UpdateAgentRequest(BaseModel):
+    """Request to update an existing agent.
+
+    All fields are optional - None means no change to that field.
+    """
+
+    name: str | None = Field(default=None, min_length=1)
+    description: str | None = None
+    models: list[AgentModelConfig] | None = None
+    tags: list[str] | None = Field(
+        default=None,
+        description="List of tag paths to associate with this agent. If provided, replaces all existing tags.",
+    )
+    system_instruction_template: str | UUID | None = Field(
+        default=None,
+        description="System instruction template identifier - can be UUID or template name. "
+        "Names are resolved with priority: user-owned > org-owned > global.",
+    )
+    system_instruction_version_id: UUID | None = None
+    input_schema_id: UUID | None = None
+    output_schema_id: UUID | None = None
+    output_schema: dict[str, Any] | None = None
+    default_request_headers: dict[str, str] | None = None
+    generation_params: GenerationParameters | None = Field(
+        default=None,
+        description="Default generation parameters for this agent",
+    )
+    tools: list[AgentToolConfig] | None = None
+    mcp_servers: list[AgentMCPServerConfig] | None = None
+
+    @model_validator(mode="after")
+    def validate_output_schema_exclusivity(self) -> Self:
+        """Ensure output_schema_id and output_schema are mutually exclusive."""
+        if self.output_schema_id is not None and self.output_schema is not None:
+            raise ValueError(
+                "Cannot specify both output_schema_id and output_schema. "
+                "Provide one or neither."
+            )
+        return self
+
+    @model_validator(mode="after")
+    def validate_tool_alias_uniqueness(self) -> Self:
+        """Ensure tool_alias is unique within the tools list."""
+        if self.tools:
+            aliases = [t.effective_alias for t in self.tools]
+            if len(aliases) != len(set(aliases)):
+                raise ValueError(
+                    "Each tool must have a unique tool_alias. "
+                    "Duplicate aliases found in tools list."
+                )
+        return self
+
+    @model_validator(mode="after")
+    def validate_mcp_server_id_uniqueness(self) -> Self:
+        """Ensure mcp_server_id is unique within the mcp_servers list."""
+        if self.mcp_servers:
+            ids = [m.mcp_server_id for m in self.mcp_servers]
+            if len(ids) != len(set(ids)):
+                raise ValueError(
+                    "Duplicate mcp_server_id found in mcp_servers list. "
+                    "Each MCP server can only be attached once."
+                )
+        return self
+
+
+# Response type alias - update returns same structure as create
+UpdateAgentResponse = CreateAgentResponse
+
+
+# ============================================================================
+# List Agents DTOs
+# ============================================================================
+
+
+class AgentSummary(BaseModel):
+    """Summary of an agent for list responses."""
+
+    id: UUID
+    name: str
+    description: str | None
+    organization_id: UUID | None
+    user_id: UUID | None
+    model_count: int
+    system_instruction_version_id: UUID | None
+    input_schema_id: UUID | None
+    output_schema_id: UUID | None
+    created_at: datetime
+    updated_at: datetime
+    usage_count: int | None = Field(
+        default=None,
+        description="Number of named sessions using this agent. Only populated when sort_by=usage.",
+    )
+
+
+class ListAgentsResponse(BaseModel):
+    """Response for listing agents."""
+
+    agents: list[AgentSummary]
+    total: int
+
+
+# ============================================================================
+# Get Agent DTO
+# ============================================================================
+
+
+class GetAgentResponse(BaseModel):
+    """Response for getting a single agent with full details."""
+
+    id: UUID
+    name: str
+    organization_id: UUID | None
+    user_id: UUID | None
+    base_agent_id: UUID | None
+    description: str | None
+    system_instruction_version_id: UUID | None
+    input_schema_id: UUID | None
+    output_schema_id: UUID | None
+    default_request_headers: dict[str, str] | None
+    generation_params: GenerationParameters | None = None
+    created_at: datetime
+    updated_at: datetime
+    models: list[AgentModelResponse]
+    tools: list[AgentToolResponse]
+    tags: list[AgentTagResponse]
+    mcp_servers: list[AgentMCPServerResponse] = []
+
+
+# ============================================================================
+# Delete Agent DTOs
+# ============================================================================
+
+
+class DeletedAgentResponse(BaseModel):
+    """Response model for a deleted agent's final state."""
+
+    id: UUID
+    name: str
+    organization_id: UUID | None
+    user_id: UUID | None
+    base_agent_id: UUID | None
+    description: str | None
+    system_instruction_version_id: UUID | None
+    input_schema_id: UUID | None
+    output_schema_id: UUID | None
+    default_request_headers: dict[str, str] | None
+    generation_params: GenerationParameters | None = None
+    created_at: datetime
+    updated_at: datetime
+    models: list[AgentModelResponse]
+    tools: list[AgentToolResponse]
+    mcp_servers: list[AgentMCPServerResponse] = []
+    tags: list[AgentTagResponse]
+
+
+class DeleteAgentResponse(BaseModel):
+    """Response after deleting an agent."""
+
+    deleted_agent: DeletedAgentResponse

alloy_runtime_types-0.1.0/alloy_runtime_types/dtos/api_keys.py

@@ -0,0 +1,124 @@
+"""DTOs for API key management operations."""
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, Field, field_validator
+
+from alloy_runtime_types.enums.api_key_scope import CANONICAL_SCOPE_ORDER, ApiKeyScope
+
+
+class CreateApiKeyRequest(BaseModel):
+    """Request to create a new API key.
+
+    Requires explicit non-empty scopes. Duplicates are normalized to unique set
+    in canonical order: read, update, delete, use.
+    """
+
+    scopes: list[ApiKeyScope] = Field(
+        ...,
+        description="Permission scopes for the API key (non-empty, normalized to unique set)",
+        min_length=1,
+    )
+    description: str | None = Field(
+        default=None,
+        max_length=500,
+        description="User-visible label for the key",
+    )
+    expires_at: datetime | None = Field(
+        default=None,
+        description="Optional expiration timestamp",
+    )
+
+    @field_validator("scopes")
+    @classmethod
+    def normalize_scopes(cls, value: list[ApiKeyScope]) -> list[ApiKeyScope]:
+        """Normalize scopes to unique set in canonical order."""
+        # Remove duplicates while preserving order
+        seen: set[ApiKeyScope] = set()
+        unique: list[ApiKeyScope] = []
+        for scope in value:
+            if scope not in seen:
+                seen.add(scope)
+                unique.append(scope)
+
+        # Sort by canonical order
+        return sorted(unique, key=lambda s: CANONICAL_SCOPE_ORDER.index(s))
+
+
+class CreateApiKeyResponse(BaseModel):
+    """Response after creating an API key.
+
+    Returns the plaintext key once. Never exposes hashed_key.
+    """
+
+    id: UUID
+    key: str  # Plaintext, only returned once
+    prefix: str
+    description: str | None
+    scopes: list[ApiKeyScope]
+    created_at: datetime
+    expires_at: datetime | None = None
+
+
+class ApiKeyResponse(BaseModel):
+    """Common response shape for API key data."""
+
+    id: UUID
+    prefix: str
+    description: str | None
+    scopes: list[ApiKeyScope]
+    created_at: datetime
+    expires_at: datetime | None = None
+    last_used_at: datetime | None = None
+
+
+class ListApiKeysResponse(BaseModel):
+    """Response listing all API keys for authenticated user."""
+
+    keys: list[ApiKeyResponse]
+    total: int
+
+
+class UpdateApiKeyRequest(BaseModel):
+    """Request to update an existing API key.
+
+    All fields are optional - only provided fields are updated.
+    """
+
+    description: str | None = Field(
+        default=None,
+        max_length=500,
+        description="User-visible label for the key",
+    )
+    expires_at: datetime | None = Field(
+        default=None,
+        description="Expiration timestamp (set to None to remove expiration)",
+    )
+    scopes: list[ApiKeyScope] | None = Field(
+        default=None,
+        description="Permission scopes (non-empty if provided, normalized to unique set)",
+    )
+
+    @field_validator("scopes")
+    @classmethod
+    def normalize_scopes(
+        cls, value: list[ApiKeyScope] | None
+    ) -> list[ApiKeyScope] | None:
+        """Normalize scopes to unique set in canonical order if provided."""
+        if value is None:
+            return None
+
+        if len(value) == 0:
+            raise ValueError("scopes must be non-empty if provided")
+
+        # Remove duplicates while preserving order
+        seen: set[ApiKeyScope] = set()
+        unique: list[ApiKeyScope] = []
+        for scope in value:
+            if scope not in seen:
+                seen.add(scope)
+                unique.append(scope)
+
+        # Sort by canonical order
+        return sorted(unique, key=lambda s: CANONICAL_SCOPE_ORDER.index(s))

alloy_runtime_types-0.1.0/alloy_runtime_types/dtos/audio.py

@@ -0,0 +1,9 @@
+"""DTOs for audio transcription endpoints."""
+
+from pydantic import BaseModel, Field
+
+
+class AudioTranscriptResponse(BaseModel):
+    """Response containing transcribed text from audio."""
+
+    text: str = Field(min_length=1, description="Transcribed text from audio")