hap.types.protocol

Core types for the Haive Agent Protocol (HAP).

This module defines the fundamental types used throughout HAP, mirroring the structure of MCP but adapted for agents and graphs.

Enhanced with comprehensive Pydantic validation for: - Field-level validation with constraints - Cross-field validation - JSON-RPC 2.0 compliance - HAP protocol standards

Classes

AgentExecutionRequest	Request to execute an agent with validation.
AgentExecutionResult	Result from agent execution with validation.
AgentInfo	Agent metadata for HAP with enhanced validation.
BaseInfo	Base class for all HAP info types.
EdgeInfo	Graph edge metadata with validation.
ErrorCode	Standard error codes.
ExecutionStatus	Agent execution status values.
FieldInfo	Field metadata.
GraphExecutionRequest	Request to execute a graph with validation.
GraphExecutionResult	Result from graph execution with validation.
GraphExecutionStatus	Graph execution status values.
GraphInfo	Graph metadata for HAP with validation.
HAPError	Error structure for HAP protocol with enhanced validation.
HAPRequest	Base request structure for HAP protocol with JSON-RPC 2.0 compliance.
HAPResponse	Base response structure for HAP protocol with validation.
IHAPServer	Interface for HAP servers.
ITransport	Transport layer interface.
NodeInfo	Graph node metadata with validation.
NodeType	Graph node types.
PromptArgument	Prompt argument definition with validation.
PromptGet	Request to get a prompt.
PromptInfo	Prompt metadata with enhanced validation.
ResourceInfo	Resource metadata with validation.
ResourceRead	Request to read a resource.
ServerCapability	Server capabilities.
ServerRegistration	Registration info for a HAP server.
StateSchemaInfo	State schema metadata.
StateValidationRequest	Request to validate state.
StateValidationResult	Result of state validation.
ToolCall	Request to call a tool.
ToolInfo	Tool metadata with enhanced validation.
TransportConfig	Transport configuration.
TransportType	Available transport types.

Module Contents

class hap.types.protocol.AgentExecutionRequest(/, **data: Any)

Bases: pydantic.BaseModel

Request to execute an agent with validation.

Parameters:

data (Any)

config_overrides: Dict[str, Any] | None = None

input_data: Dict[str, Any] = None

metadata: Dict[str, Any] = None

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

stream: bool = None

timeout: float | None = None

class hap.types.protocol.AgentExecutionResult(/, **data: Any)

Bases: pydantic.BaseModel

Result from agent execution with validation.

Parameters:

data (Any)

validate_result_consistency() → AgentExecutionResult

Ensure result/error fields are consistent with status.

Return type:

AgentExecutionResult

error: str | None = None

execution_time: float = None

metadata: Dict[str, Any] = None

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

result: Any | None = None

status: ExecutionStatus = None

class hap.types.protocol.AgentInfo(/, **data: Any)

Bases: BaseInfo

Agent metadata for HAP with enhanced validation.

Parameters:

data (Any)

classmethod validate_capabilities(v: List[str]) → List[str]

Validate capability names.

Parameters:

v (List[str])

Return type:

List[str]

classmethod validate_tool_names(v: List[str]) → List[str]

Validate tool names format.

Parameters:

v (List[str])

Return type:

List[str]

capabilities: List[str] = None

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

state_schema: Dict[str, Any] | None = None

tools: List[str] = None

type: str = None

class hap.types.protocol.BaseInfo(/, **data: Any)

Bases: pydantic.BaseModel

Base class for all HAP info types.

Parameters:

data (Any)

classmethod validate_name_format(v: str) → str

Ensure name follows HAP naming conventions.

Parameters:

v (str)

Return type:

str

description: str = None

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str = None

class hap.types.protocol.EdgeInfo(/, **data: Any)

Bases: pydantic.BaseModel

Graph edge metadata with validation.

Parameters:

data (Any)

validate_edge() → EdgeInfo

Validate edge constraints.

Return type:

EdgeInfo

condition: str | None = None

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

source: str = None

target: str = None

class hap.types.protocol.ErrorCode

Bases: int, enum.Enum

Standard error codes.

AGENT_NOT_FOUND = -32001

AUTHENTICATION_ERROR = -32007

EXECUTION_ERROR = -32005

GRAPH_NOT_FOUND = -32002

INTERNAL_ERROR = -32603

INVALID_PARAMS = -32602

INVALID_REQUEST = -32600

METHOD_NOT_FOUND = -32601

PARSE_ERROR = -32700

RESOURCE_NOT_FOUND = -32004

TOOL_NOT_FOUND = -32003

VALIDATION_ERROR = -32006

class hap.types.protocol.ExecutionStatus

Bases: str, enum.Enum

Agent execution status values.

CANCELLED = 'cancelled'

ERROR = 'error'

SUCCESS = 'success'

TIMEOUT = 'timeout'

class hap.types.protocol.FieldInfo(/, **data: Any)

Bases: pydantic.BaseModel

Field metadata.

Parameters:

data (Any)

default: Any | None = None

description: str = ''

name: str

required: bool = True

type: str

class hap.types.protocol.GraphExecutionRequest(/, **data: Any)

Bases: pydantic.BaseModel

Request to execute a graph with validation.

Parameters:

data (Any)

classmethod validate_input_not_empty(v: Dict[str, Any]) → Dict[str, Any]

Ensure input data is not empty.

Parameters:

v (Dict[str, Any])

Return type:

Dict[str, Any]

end_node: str | None = None

input_data: Dict[str, Any] = None

metadata: Dict[str, Any] = None

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

start_node: str | None = None

stream_nodes: bool = None

timeout: float | None = None

class hap.types.protocol.GraphExecutionResult(/, **data: Any)

Bases: pydantic.BaseModel

Result from graph execution with validation.

Parameters:

data (Any)

classmethod validate_path_items(v: List[str]) → List[str]

Validate all path items are valid node IDs.

Parameters:

v (List[str])

Return type:

List[str]

validate_result_consistency() → GraphExecutionResult

Ensure result fields are consistent with status.

Return type:

GraphExecutionResult

error: str | None = None

execution_time: float = None

final_output: Any | None = None

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

node_metadata: Dict[str, Any] = None

path: List[str] = None

results: Dict[str, Any] = None

status: GraphExecutionStatus = None

class hap.types.protocol.GraphExecutionStatus

Bases: str, enum.Enum

Graph execution status values.

CANCELLED = 'cancelled'

ERROR = 'error'

PARTIAL = 'partial'

SUCCESS = 'success'

TIMEOUT = 'timeout'

class hap.types.protocol.GraphInfo(/, **data: Any)

Bases: BaseInfo

Graph metadata for HAP with validation.

Parameters:

data (Any)

validate_graph_structure() → GraphInfo

Validate overall graph structure.

Return type:

GraphInfo

classmethod validate_unique_node_ids(v: List[NodeInfo]) → List[NodeInfo]

Ensure node IDs are unique.

Parameters:

v (List[NodeInfo])

Return type:

List[NodeInfo]

edges: List[EdgeInfo] = None

entry_point: str = None

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

nodes: List[NodeInfo] = None

class hap.types.protocol.HAPError(/, **data: Any)

Bases: pydantic.BaseModel

Error structure for HAP protocol with enhanced validation.

Parameters:

data (Any)

classmethod validate_error_code(v: int) → int

Validate error code is in expected ranges.

Parameters:

v (int)

Return type:

int

code: int = None

data: Any | None = None

message: str = None

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class hap.types.protocol.HAPRequest(/, **data: Any)

Bases: pydantic.BaseModel

Base request structure for HAP protocol with JSON-RPC 2.0 compliance.

Parameters:

data (Any)

classmethod validate_method(v: str) → str

Validate method follows HAP conventions.

Parameters:

v (str)

Return type:

str

id: str | int = None

jsonrpc: str = None

method: str = None

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

params: Dict[str, Any] = None

class hap.types.protocol.HAPResponse(/, **data: Any)

Bases: pydantic.BaseModel

Base response structure for HAP protocol with validation.

Parameters:

data (Any)

validate_result_or_error() → HAPResponse

Ensure response has either result or error, not both.

Return type:

HAPResponse

error: HAPError | None = None

id: str | int = None

jsonrpc: str = None

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

result: Any | None = None

class hap.types.protocol.IHAPServer

Bases: Protocol

Interface for HAP servers.

async handle_request(request: HAPRequest) → HAPResponse

Handle incoming HAP request.

Parameters:

request (HAPRequest)

Return type:

HAPResponse

list_prompts() → List[PromptInfo]

List available prompts.

Return type:

List[PromptInfo]

list_resources() → List[ResourceInfo]

List available resources.

Return type:

List[ResourceInfo]

list_tools() → List[ToolInfo]

List available tools.

Return type:

List[ToolInfo]

class hap.types.protocol.ITransport

Bases: Protocol

Transport layer interface.

async send_response(response: HAPResponse)

Send response to client.

Parameters:

response (HAPResponse)

async start(server: IHAPServer)

Start transport.

Parameters:

server (IHAPServer)

async stop()

Stop transport.

class hap.types.protocol.NodeInfo(/, **data: Any)

Bases: pydantic.BaseModel

Graph node metadata with validation.

Parameters:

data (Any)

validate_node_requirements() → NodeInfo

Validate node-type specific requirements.

Return type:

NodeInfo

agent_name: str | None = None

description: str | None = None

id: str = None

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

type: NodeType = None

class hap.types.protocol.NodeType

Bases: str, enum.Enum

Graph node types.

AGENT = 'agent'

DECISION = 'decision'

END = 'end'

MERGE = 'merge'

PARALLEL = 'parallel'

START = 'start'

TOOL = 'tool'

class hap.types.protocol.PromptArgument(/, **data: Any)

Bases: pydantic.BaseModel

Prompt argument definition with validation.

Parameters:

data (Any)

description: str = None

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str = None

required: bool = None

class hap.types.protocol.PromptGet(/, **data: Any)

Bases: pydantic.BaseModel

Request to get a prompt.

Parameters:

data (Any)

arguments: dict = None

name: str

class hap.types.protocol.PromptInfo(/, **data: Any)

Bases: BaseInfo

Prompt metadata with enhanced validation.

Parameters:

data (Any)

classmethod validate_unique_arguments(v: List[PromptArgument]) → List[PromptArgument]

Ensure argument names are unique.

Parameters:

v (List[PromptArgument])

Return type:

List[PromptArgument]

arguments: List[PromptArgument] = None

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class hap.types.protocol.ResourceInfo(/, **data: Any)

Bases: pydantic.BaseModel

Resource metadata with validation.

Parameters:

data (Any)

classmethod validate_uri_format(v: str) → str

Validate URI has proper format.

Parameters:

v (str)

Return type:

str

description: str = None

mime_type: str = None

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str = None

uri: str = None

class hap.types.protocol.ResourceRead(/, **data: Any)

Bases: pydantic.BaseModel

Request to read a resource.

Parameters:

data (Any)

uri: str

class hap.types.protocol.ServerCapability

Bases: str, enum.Enum

Server capabilities.

AUTHENTICATION = 'authentication'

PROMPTS = 'prompts'

RESOURCES = 'resources'

STATE_PERSISTENCE = 'state_persistence'

STREAMING = 'streaming'

TOOLS = 'tools'

class hap.types.protocol.ServerRegistration(/, **data: Any)

Bases: pydantic.BaseModel

Registration info for a HAP server.

Parameters:

data (Any)

capabilities: List[ServerCapability] = None

endpoint: str

health_check_url: str | None = None

metadata: dict = None

name: str

registered_at: datetime.datetime = None

type: str

class hap.types.protocol.StateSchemaInfo(/, **data: Any)

Bases: pydantic.BaseModel

State schema metadata.

Parameters:

data (Any)

description: str

fields: List[FieldInfo] = None

name: str

schema: dict

class hap.types.protocol.StateValidationRequest(/, **data: Any)

Bases: pydantic.BaseModel

Request to validate state.

Parameters:

data (Any)

data: dict

strict: bool = True

class hap.types.protocol.StateValidationResult(/, **data: Any)

Bases: pydantic.BaseModel

Result of state validation.

Parameters:

data (Any)

errors: List[str] = None

valid: bool

validated_data: dict | None = None

class hap.types.protocol.ToolCall(/, **data: Any)

Bases: pydantic.BaseModel

Request to call a tool.

Parameters:

data (Any)

arguments: dict = None

name: str

class hap.types.protocol.ToolInfo(/, **data: Any)

Bases: BaseInfo

Tool metadata with enhanced validation.

Parameters:

data (Any)

classmethod validate_json_schema(v: Dict[str, Any] | None) → Dict[str, Any] | None

Validate that schema is a valid JSON Schema structure.

Parameters:

v (Optional[Dict[str, Any]])

Return type:

Optional[Dict[str, Any]]

input_schema: Dict[str, Any] = None

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

output_schema: Dict[str, Any] | None = None

class hap.types.protocol.TransportConfig(/, **data: Any)

Bases: pydantic.BaseModel

Transport configuration.

Parameters:

data (Any)

host: str | None = None

options: dict = None

path: str | None = None

port: int | None = None

type: TransportType

class hap.types.protocol.TransportType

Bases: str, enum.Enum

Available transport types.

HTTP = 'http'

SSE = 'sse'

STDIO = 'stdio'

WEBSOCKET = 'websocket'