Skip to content

Models API Reference

Core Pydantic models for representing causal knowledge.

EdgeDirection

EdgeDirection

Direction of a causal edge between two nodes.

Attributes:

A_TO_B class-attribute instance-attribute 

A_TO_B = 'a_to_b'

B_TO_A class-attribute instance-attribute 

B_TO_A = 'b_to_a'

UNDIRECTED class-attribute instance-attribute 

UNDIRECTED = 'undirected'

EdgeKnowledge

EdgeKnowledge

Structured knowledge about a potential causal edge.

This model represents the result of querying a knowledge source about whether a causal relationship exists between two variables.

Attributes:

  • exists (Optional[bool]) –

    Whether a causal edge exists. True, False, or None (uncertain).

  • direction (Optional[EdgeDirection]) –

    The direction of the causal relationship if it exists. "a_to_b" means node_a causes node_b, "b_to_a" means the reverse, "undirected" means bidirectional or direction unknown.

  • confidence (float) –

    Confidence score from 0.0 (no confidence) to 1.0 (certain).

  • reasoning (str) –

    Human-readable explanation for the knowledge assessment.

  • model (Optional[str]) –

    The LLM or knowledge source that provided this response.

Example

knowledge = EdgeKnowledge( ... exists=True, ... direction="a_to_b", ... confidence=0.85, ... reasoning="Smoking causes lung cancer.", ... model="gpt-4o-mini" ... )

Methods:

  • is_uncertain –

    Check if this knowledge is uncertain.

  • to_dict –

    Convert to dictionary with string direction.

  • uncertain –

    Create an uncertain EdgeKnowledge instance.

  • validate_direction –

    Convert string direction to EdgeDirection enum.

confidence class-attribute instance-attribute 

confidence: float = Field(
    default=0.0, ge=0.0, le=1.0, description="Confidence score from 0.0 to 1.0."
)

direction class-attribute instance-attribute 

direction: Optional[EdgeDirection] = Field(
    default=None, description="Direction of the causal relationship if it exists."
)

exists class-attribute instance-attribute 

exists: Optional[bool] = Field(
    default=None, description="Whether a causal edge exists. None = uncertain."
)

model class-attribute instance-attribute 

model: Optional[str] = Field(
    default=None, description="The model/source that provided this knowledge."
)

reasoning class-attribute instance-attribute 

reasoning: str = Field(
    default="", description="Human-readable explanation for the assessment."
)

is_uncertain 

is_uncertain() -> bool

Check if this knowledge is uncertain.

Returns:

  • bool –

    True if exists is None or confidence is below 0.5.

to_dict 

to_dict() -> dict

Convert to dictionary with string direction.

Returns:

  • dict –

    Dictionary representation suitable for JSON serialization.

uncertain classmethod 

uncertain(
    reasoning: str = "Unable to determine", model: Optional[str] = None
) -> EdgeKnowledge

Create an uncertain EdgeKnowledge instance.

Useful for error cases or when knowledge source cannot provide an answer.

Parameters:

  • reasoning
    (str, default: 'Unable to determine' ) –

    Explanation for why the result is uncertain.

  • model
    (Optional[str], default: None ) –

    The model/source that was queried.

Returns:

  • EdgeKnowledge –

    EdgeKnowledge with exists=None and confidence=0.0.

validate_direction classmethod 

validate_direction(v: Optional[str]) -> Optional[EdgeDirection]

Convert string direction to EdgeDirection enum.