evofabric.core.typing

General General

MISSING = object()

Empty parameter descriptor.

Graph Related

class evofabric.core.typing.SpecialNode(Enum)

The enumeration of special nodes in the graph, used to identify the start and end nodes of the graph.

is_special_node(name: str) → bool

Determine whether the given name is a special node.

Parameters:

name (str) – Node name.

Returns:

Return True if it is a special node, otherwise return False.

Return type:

bool

is_end_node(name: str | SpecialNode) → bool

Determine whether the given name or node is an end node.

Parameters:

name (Union[str, SpecialNode]) – Node name or SpecialNode instance.

Returns:

If it is an end node, return True, otherwise return False.

Return type:

bool

is_start_node(name: str | SpecialNode) → bool

Determine whether the given name or node is a starting node.

Parameters:

name (Union[str, SpecialNode]) – Node name or SpecialNode instance.

Returns:

If it is the starting node, return True, otherwise return False.

Return type:

bool

class evofabric.core.typing.GraphMode(Enum)

Graph execution mode enumeration, representing the graph’s execution mode.

RUN = "run"

Graph’s normal operation mode.

DEBUG = "debug"

Graph Debugging Run Mode

class evofabric.core.typing.NodeActionMode(str, Enum)

Node action mode enumeration class, used to define the execution conditions of a node when it has multiple predecessor nodes.

ANY = "any"

Arbitrary mode: The node executes immediately upon receiving a message from any predecessor node.

ALL = "all"

All Mode: The node executes only after receiving messages from all predecessor nodes.

DEFAULT_EDGE_GROUP = "all"

Default edge grouping identifier.

STREAM_CHUNK = Any

Streaming data block type alias, representing any type of stream fragment.

StateDelta = Dict

State increment type alias, representing the dictionary structure of state changes.

State = Union[BaseModel, Dict]

State type alias, can be a BaseModel instance or a regular dictionary.

StateSchema = Union[dict, BaseModel]

Status Schema’s data type.

Messages

class evofabric.core.typing.ChatUsage(BaseModel)

Define the usage information for the LLM chat client.

Parameters:

• completion_tokens (Optional[int]) – The number of tokens used to generate the completion.

• prompt_tokens (Optional[int]) – Number of tokens used in the prompt.

• total_tokens (Optional[int]) – Total number of tokens used in the request (prompt + completion content).

• generation_time (Optional[float]) – Time consumed for generation (seconds).

class evofabric.core.typing.EmbedUsage(BaseModel)

Define the usage information of embedding (embedding).

Parameters:

generation_time (int) – Time consumed for generation (seconds).

class evofabric.core.typing.Reranking(BaseModel)

Definition of reranking (reranking) usage information.

Parameters:

generation_time (int) – Time consumed for generation (seconds).

class evofabric.core.typing.Function(BaseModel)

Define function call information.

Parameters:

• arguments (str) – JSON-formatted function parameters.

• name (str) – Function name.

class evofabric.core.typing.ToolCall(BaseModel)

Define tool call information.

Parameters:

• id (str) – Unique identifier for function calls.

• function (Function) – Function object called by the model.

• type (Literal['function']) – call type.

class evofabric.core.typing.ChatStreamChunk(BaseModel)

Define the streaming chunked content of the LLM chat client.

Parameters:

• reasoning_content (Optional[str]) – Reasoning content.

• content (Optional[str]) – Output content.

class evofabric.core.typing.LLMChatResponse(BaseModel)

Define the response format for the LLM client.

Parameters:

• content (str) – Response content.

• tool_calls (Optional[List[ToolCall]]) – Tool Call List

• reasoning_content (Optional[str]) – Response reasoning content.

• usage (Optional[ChatUsage]) – Usage Information.

• id (str) – Unique identifier for the response.

• meta (dict) – Metadata.

class evofabric.core.typing.EmbedResponse(BaseModel)

Define the response format for the embedded client.

Parameters:

• embeddings (List[float]) – Embedding vector (list of floating-point numbers).

• usage (Optional[EmbedUsage]) – Usage Information.

class evofabric.core.typing.RerankResponse(BaseModel)

Define the response format for the reordering client.

Parameters:

• scores (List[float]) – Re-ranking score.

• texts (List[str]) – Reorder text.

• usage (Optional[RerankUsage]) – Usage Information.

class evofabric.core.typing.StateBaseMessage(BaseModel)

Base class representing status messages.

Parameters:

• content (Any) – Message content.

• msg_id (Optional[str]) – Message Unique ID (automatically added by the append_message strategy).

• node_name (Optional[str]) – Which Node emitted the message (injected at runtime by GraphNodeSpec).

class evofabric.core.typing.SystemMessage(StateBaseMessage)

System message.

Inherits from StateBaseMessage

Parameters:

• content (Any) – Message content.

• msg_id (Optional[str]) – Unique Message ID.

• role (Literal['system']) – Message role, fixed as system.

class evofabric.core.typing.UserMessage(StateBaseMessage)

User message.

Inherits from StateBaseMessage

Parameters:

• content (Any) – Message content.

• msg_id (Optional[str]) – Unique Message ID.

• role (Literal['user']) – Message role, fixed as user.

class evofabric.core.typing.AssistantMessage(StateBaseMessage)

Assistant message.

Inherits from StateBaseMessage

Parameters:

• content (Any) – Message content.

• msg_id (Optional[str]) – Unique Message ID.

• role (Literal['assistant']) – Message role, fixed as assistant.

• reasoning_content (Optional[str]) – Reasoning content.

• tool_calls (Optional[List[ToolCall]]) – Tool Call List

• usage (Optional[ChatUsage]) – Usage Information.

class evofabric.core.typing.ToolMessage(StateBaseMessage)

Tool message.

Inherits from StateBaseMessage

Parameters:

• content (Any) – Message content.

• msg_id (Optional[str]) – Unique Message ID.

• tool_call_id (str) – Tool Call ID.

• role (Literal['tool']) – Message role, fixed as tool.

class evofabric.core.typing.ToolCallResult(BaseModel)

Define the execution result of tool calls.

Parameters:

• tool_call_id (str) – Tool Call ID.

• success (bool) – Did the tool successfully return the result.

• content (Any) – The specific information returned by the tool. If successful, the expected result; if failed, a brief error description.

• traceback (str) – Complete error backtrace.

evofabric.core.typing.cast_state_message(msg) → StateMessage

Convert the input message to a validated StateMessage instance.

Returns:

A verified StateMessage instance.

Return type:

StateMessage

class evofabric.core.typing.StateMessage

Chat message type alias, representing any message types that may appear in the conversation history. Including UserMessage, ToolMessage, AssistantMessage, SystemMessage, or StateBaseMessage.

Defined as:

StateMessage = Union[UserMessage, ToolMessage, AssistantMessage, SystemMessage, StateBaseMessage]

Tool

class evofabric.core.typing.CodeExecDockerConfig(BaseModel)

Code Sandbox Initialization Configuration Class

Parameters:

• image (str) – Docker image name, default is "python:3-slim"

• auto_remove (bool) – Whether to automatically delete the container after it finishes running, default is True

• working_dir (str) – Working directory inside the container, default is "/tmp"

• tty (bool) – Whether to allocate a pseudo-terminal, default: True

• detach (bool) – Whether to run the container in the background, default is True

• mem_limit (str) – Memory limit, default is "4096m"

• cpu_quota (int) – CPU quota, default is 50000

• entrypoint (str) – Container entry point, default to "/bin/sh"

• command (Union[str, List[str]]) – Command to execute when the container starts, default is None

• name (str) – Container name, default is "evofabric_sandbox"

• network (str) – The network mode used by the container, defaulting to "host"

• volumes (dict) – Volume mount mapping, default is None

class evofabric.core.typing.PromptRequest(BaseModel)

PromptRequest is used to define prompt requests.

Parameters:

• server_name (str) – Server name.

• prompt_name (str) – Prompt Template Name

• arguments (Dict[str, str]) – Parameter Dictionary.

class evofabric.core.typing.ResourceRequest(BaseModel)

ResourceRequest is used to define resource requests.

Parameters:

• server_name (str) – Server name.

• url (str) – Resource URL address.

class evofabric.core.typing.StdioLink(StdioServerParameters)

Define the standard input and output (Stdio) link type configuration for the MCP server.

Inherits from StdioServerParameters

Parameters:

• type (Literal["StdioLink"]) – Type identifier, fixed as "StdioLink".

• read_time_out (float) – Read timeout, default is 10.0 seconds.

• command (str) – Execution method for starting the server (inherited from the parent class).

• args (List[str]) – Command parameters for starting the server (inherited from the parent class).

class evofabric.core.typing.SseLink(BaseModel)

Define the SSE (Server-Sent Events) link type configuration for the MCP server.

Parameters:

• type (Literal["SseLink"]) – Type identifier, fixed as "SseLink".

• url (str) – SSE server address.

• headers (Dict[str, Any]) – Request header, default to None.

• timeout (float) – Request timeout, default is 30.0 seconds.

• sse_read_timeout (float) – SSE stream read timeout, default is 300.0 seconds.

class evofabric.core.typing.StreamableHttpLink(BaseModel)

Define the streamable HTTP link configuration for the MCP server.

Parameters:

• type (Literal["StreamableHttpLink"]) – Type identifier, fixed to "StreamableHttpLink".

• url (str) – HTTP server address.

• headers (Dict[str, Any]) – Request header, default to None.

• timeout (float) – Request timeout, default is 30.0 seconds.

• sse_read_timeout (float) – SSE stream read timeout, default is 300.0 seconds.

• terminate_on_close (bool) – Whether to terminate when the connection is closed, default is True.

class evofabric.core.typing.MCPConfig(BaseModel)

MCPConfig is MCP’s configuration class.

Parameters:

url (str) – URL for SSE/HTTP transmission. When using stdio transmission, you can fill in the absolute path of the MCP server.

class evofabric.core.typing.ToolInnerState(BaseModel)

Define the internal state of a single tool.

Parameters:

• type (Literal["ToolInnerState"]) – Tool internal state type, fixed as "ToolInnerState".

• state (Dict[str, Any]) – Tool state content, format is {state_name: state_content}.

• meta_state (Dict[str, Any]) – Tool meta state content, format is {state_name: state_content}.

class evofabric.core.typing.ToolManagerState(BaseModel)

Define the overall state of the tool manager.

Parameters:

• type (Literal["ToolManagerState"]) – State type, fixed as "ToolManagerState".

• state (Dict[str, ToolInnerState]) – Tool management state. Keys are tool names, values are the corresponding ToolInnerState.

class evofabric.core.typing.McpServerLink

MCP server connection type alias, used to represent different types of MCP server communication methods.

Supported connection types:

• StdioLink

• SseLink

• StreamableHttpLink

Using Annotated and Pydantic’s Field to set type distinctions:

McpServerLink = Annotated[
    Union[StdioLink, SseLink, StreamableHttpLink],
    Field(discriminator="type")
]

Explanation:

This type is used in the MCP tool management system to facilitate unified management and invocation between servers with different communication methods.

VectorStore

class evofabric.core.typing.DBItem

A basic database project for vector storage and retrieval.

Parameters:

• text (str) – Text content requiring vectorization

• ids (Optional[str]) – Unique identifier in the database

• metadata (Optional[dict]) – Additional Metadata Dictionary

Usage Example:

from evofabric.core.typing import DBItem

# Create a database item
item = DBItem(
    text="This is a sample document text",
    ids="doc_001",
    metadata={"category": "article", "author": "John Doe"}
)

# Access item attributes
print(item.text)      # "This is a sample document text"
print(item.ids)       # "doc_001"
print(item.metadata)  # {"category": "article", "author": "John Doe"}

class evofabric.core.typing.SearchResult

The data structure of the results returned by similarity search.

Parameters:

• text (str) – Document text

• metadata (Optional[Dict[str, Any]]) – Associated Metadata

• score (Optional[float]) – Similarity score (0-1, higher values indicate greater similarity)

• id (str) – Unique Document Identifier

Usage Example:

from evofabric.core.typing import SearchResult

# Create a search result
result = SearchResult(
    text="This is a matching document",
    metadata={"category": "article", "source": "web"},
    score=0.95,
    id="result_001"
)

# Access result attributes
print(result.text)      # "This is a matching document"
print(result.score)     # 0.95
print(result.metadata)  # {"category": "article", "source": "web"}