Technical Schema: GoalDefinition, NodeDef, and GraphTopology

Arachne uses a structured schema for defining and executing tasks, implemented using Pydantic.

GoalDefinition

The input schema for the system.

class GoalDefinition(BaseModel):
    objective: str
    success_criteria: list[str] = []
    constraints: list[Constraint] = []

Constraint

class ConstraintType(StrEnum):
    COST = "cost"
    TIME = "time"
    SAFETY = "safety"
    QUALITY = "quality"

class Constraint(BaseModel):
    type: ConstraintType
    value: float | None = None
    description: str
    is_hard_boundary: bool = False

NodeDef

Defines an individual task within the execution graph.

class NodeRole(StrEnum):
    CHAIN_OF_THOUGHT = "chain_of_thought"
    REACT = "react"
    PREDICT = "predict"
    HUMAN_IN_LOOP = "human_in_loop"
    RECURSIVE = "recursive"

class QuestionType(StrEnum):
    TEXT = "text"
    SELECT = "select"
    CONFIRM = "confirm"

class Question(BaseModel):
    query: str
    type: QuestionType = QuestionType.TEXT
    default: str = ""
    choices: list[str] = []

class ToolParameter(BaseModel):
    name: str
    type: str = "str"
    description: str = ""
    required: bool = True

class ToolDef(BaseModel):
    name: str
    description: str
    parameters: list[ToolParameter] = []

class NodeDef(BaseModel):
    id: str
    role: NodeRole
    name: str
    description: str
    inputs: list[str] = []
    output: str
    depends_on: list[str] = []
    max_tokens: int = 4096
    timeout: int | None = None
    tools: list[ToolDef] = []
    mcp_servers: list[str] = []
    skills: list[str] = []
    question: Question | None = None

EdgeDef

class EdgeDef(BaseModel):
    source: str
    target: str
    label: str = ""

GraphTopology

The complete execution graph generated by the Weaver.

class CustomToolRequest(BaseModel):
    name: str
    description: str
    code: str

class CustomSkillRequest(BaseModel):
    name: str
    description: str
    content: str

class GraphTopology(BaseModel):
    name: str
    objective: str
    nodes: list[NodeDef] = []
    edges: list[EdgeDef] = []
    runtime_inputs: list[str] = []
    custom_tools: list[CustomToolRequest] = []
    custom_skills: list[CustomSkillRequest] = []

ResultStatus

class ResultStatus(StrEnum):
    COMPLETED = "completed"
    FAILED = "failed"
    PAUSED = "paused"
    SKIPPED = "skipped"

NodeResult

class NodeResult(BaseModel):
    node_id: str
    status: ResultStatus = ResultStatus.COMPLETED
    output: dict = {}
    error: str | None = None
    cost_usd: float = 0.0
    tokens_used: int = 0
    duration_seconds: float = 0.0

RunResult

class RunResult(BaseModel):
    graph_name: str
    goal: str
    node_results: list[NodeResult] = []
    total_cost_usd: float = 0.0
    total_tokens: int = 0
    duration_seconds: float = 0.0
    attempts: int = 1
    success: bool = True
    evaluation_source: str = "none"
    confidence_score: float = 1.0

FailureReport

class FailureReport(BaseModel):
    goal: str
    attempt: int
    failed_nodes: list[str] = []
    error_details: dict[str, str] = {}
    partial_results: dict[str, dict] = {}
    diagnosis: str = ""
    topology_fix: str = ""
    confidence_score: float = 1.0
    evaluation_source: str = "none"
    requires_human: bool = False
    evaluation_details: dict[str, object] = {}