InputSpec

InputSpec describes what inputs a graph needs and how they must be provided.

What counts as "required" depends on four dimensions that narrow the active subgraph:

Dimension	Method	Narrows from	Effect on required
Entrypoint (start)	with_entrypoint(...)	The front	Excludes upstream nodes
Select (end)	select(...)	The back	Excludes nodes not needed for selected outputs
Bind (pre-fill)	bind(...)	Individual params	Moves params from required to optional
Defaults (fallback)	Function signatures	Individual params	Params with defaults are optional

from hypergraph import node, Graph

@node(output_name="embedding")
def embed(text: str) -> list[float]:
    return [0.1, 0.2, 0.3]

@node(output_name="docs")
def retrieve(embedding: list[float], top_k: int = 5) -> list[str]:
    return ["doc1", "doc2"]

@node(output_name="answer")
def generate(docs: list[str], query: str) -> str:
    return f"Answer based on {len(docs)} docs"

g = Graph([embed, retrieve, generate])

# Full graph: all inputs
print(g.inputs.required)  # ('text', 'query')
print(g.inputs.optional)  # ('top_k',)

# Entrypoint narrows from the front
g2 = g.with_entrypoint("retrieve")
print(g2.inputs.required)  # ('embedding', 'query') - text no longer needed

# Select narrows from the back
g3 = g.select("docs")
print(g3.inputs.required)  # ('text',) - query no longer needed

# Bind pre-fills a value
g4 = g.bind(query="What is RAG?")
print(g4.inputs.required)  # ('text',)

# All four compose
configured = g.with_entrypoint("retrieve").select("answer").bind(top_k=10)
print(configured.inputs.required)  # ('embedding', 'query')
print(configured.inputs.optional)  # ('top_k',)

The InputSpec Dataclass

InputSpec is a frozen dataclass with four fields:

@dataclass(frozen=True)
class InputSpec:
    required: tuple[str, ...]
    optional: tuple[str, ...]
    entrypoints: dict[str, tuple[str, ...]]
    bound: dict[str, Any]

required: tuple[str, ...]

Parameters that must be provided at runtime. They have no default value and aren't bound.

@node(output_name="y")
def process(x: int) -> int:  # x has no default
    return x * 2

g = Graph([process])
print(g.inputs.required)  # ('x',)

optional: tuple[str, ...]

Parameters that can be omitted at runtime. They have default values.

@node(output_name="y")
def process(x: int, scale: int = 2) -> int:  # scale has default
    return x * scale

g = Graph([process])
print(g.inputs.required)  # ('x',)
print(g.inputs.optional)  # ('scale',)

entrypoints: dict[str, tuple[str, ...]]

Reserved for compatibility. For configured graphs, this field is {}.

Cyclic graphs must be constructed with graph-level entrypoint configuration (Graph(..., entrypoint=...)). Cycle bootstrap parameters are represented directly in canonical required/optional.

bound: dict[str, Any]

Parameters that are pre-filled with values via bind().

g = Graph([process])
print(g.inputs.bound)  # {}

bound = g.bind(x=5)
print(bound.inputs.bound)     # {'x': 5}
print(bound.inputs.required)  # () - x is no longer required

How Categories Are Determined

Categorization happens in two phases:

Phase 1: Scope narrowing. Determine which nodes are active using entrypoints (forward-reachable) and select (backward-reachable). Only active nodes contribute parameters to InputSpec.

Phase 2: Parameter classification. For each parameter in the active subgraph, apply the "edge cancels default" rule:

Condition	Category
No incoming edge, no default, not bound	required
No incoming edge, has default OR is bound	optional
Has incoming edge from another node	Not in InputSpec
Is bound via bind()	In bound dict, moves from required to optional
Node excluded by with_entrypoint() or select()	Not in InputSpec

Edge Cancels Default

When a parameter receives data from another node (has an incoming edge), it's not in InputSpec at all:

@node(output_name="doubled")
def double(x: int) -> int:
    return x * 2

@node(output_name="result")
def add(doubled: int) -> int:  # doubled comes from double node
    return doubled + 1

g = Graph([double, add])
print(g.inputs.required)  # ('x',) - only x
# 'doubled' is not in inputs - it comes from the double node

Cycles Require Entrypoint At Construction

@node(output_name="state")
def update(state: dict, input: int) -> dict:
    return {**state, "value": input}

# Invalid: cycle with no constructor entrypoint
# Graph([update])  # GraphConfigError

g = Graph([update], entrypoint="update")
print(g.inputs.required)    # ('state', 'input')
print(g.inputs.entrypoints) # {}

Scope Narrowing (Entrypoint and Select)

with_entrypoint() and select() narrow which nodes are considered when computing InputSpec. Parameters from excluded nodes do not appear in required, optional, or entrypoints.

from hypergraph import node, Graph

@node(output_name="a_val")
def step_a(x: int) -> int:
    return x * 2

@node(output_name="b_val")
def step_b(a_val: int, y: int) -> int:
    return a_val + y

@node(output_name="c_val")
def step_c(b_val: int) -> int:
    return b_val * 3

g = Graph([step_a, step_b, step_c])
print(g.inputs.required)  # ('x', 'y')

# Entrypoint: skip step_a, start at step_b
g2 = g.with_entrypoint("step_b")
print(g2.inputs.required)  # ('a_val', 'y') - a_val is now a user input

# Select: only need b_val, not c_val
g3 = g.select("b_val")
print(g3.inputs.required)  # ('x', 'y') - same, since step_a is still needed

# Both: start at step_b, only need b_val
g4 = g.with_entrypoint("step_b").select("b_val")
print(g4.inputs.required)  # ('a_val', 'y')

Accessing InputSpec

From a Graph

g = Graph([double, add])
spec = g.inputs  # Returns InputSpec

print(spec.required)      # tuple of required param names
print(spec.optional)      # tuple of optional param names
print(spec.entrypoints)  # {} (reserved for compatibility)
print(spec.bound)         # dict of bound values

Getting All Input Names

Use the all property to get all input names:

spec = g.inputs
print(spec.all)  # ('x',) - required + optional

Iteration

InputSpec is not directly iterable. Use all or access individual tuples:

for param in g.inputs.required:
    print(f"Required: {param}")

for param in g.inputs.optional:
    print(f"Optional: {param}")

DAG Slicing Matrix

from hypergraph import Graph, node

@node(output_name="a")
def step_a(x: int) -> int: return x * 2

@node(output_name="b")
def step_b(a: int, y: int) -> int: return a + y

@node(output_name="c")
def step_c(b: int, z: int = 10) -> int: return b * z

base = Graph([step_a, step_b, step_c])

• base: required=('x', 'y'), optional=('z',)

• base.with_entrypoint("step_b"): required=('a', 'y'), optional=('z',)

• base.select("b"): required=('x', 'y'), optional=()

• base.with_entrypoint("step_b").select("b"): required=('a', 'y'), optional=()

Examples

Simple Graph: Required and Optional

from hypergraph import node, Graph

@node(output_name="embedding")
def embed(text: str) -> list[float]:
    return [0.1, 0.2, 0.3]

@node(output_name="docs")
def retrieve(embedding: list[float], top_k: int = 5) -> list[str]:
    return ["doc1", "doc2"]

g = Graph([embed, retrieve])

print(g.inputs.required)      # ('text',)
print(g.inputs.optional)      # ('top_k',)
print(g.inputs.entrypoints)  # {}
print(g.inputs.bound)         # {}

Bound Values

# Bind a value
bound = g.bind(top_k=10)

print(bound.inputs.required)  # ('text',) - unchanged
print(bound.inputs.optional)  # ('top_k',) - still optional (has fallback)
print(bound.inputs.bound)     # {'top_k': 10}

# Bind another value
fully_bound = bound.bind(text="hello")

print(fully_bound.inputs.required)  # ()
print(fully_bound.inputs.bound)     # {'top_k': 10, 'text': 'hello'}

Graph with Cycles

@node(output_name="messages")
def chat(messages: list[str], user_input: str) -> list[str]:
    return messages + [user_input]

# Invalid (cycle without constructor entrypoint):
# Graph([chat])

g = Graph([chat], entrypoint="chat")
print(g.inputs.required)      # ('messages', 'user_input')
print(g.inputs.entrypoints)   # {}

Multiple Nodes Sharing a Parameter

When multiple nodes use the same parameter name, defaults must be consistent:

@node(output_name="x")
def a(value: int = 10) -> int:
    return value

@node(output_name="y")
def b(value: int = 10) -> int:  # Same default as 'a'
    return value * 2

g = Graph([a, b])
print(g.inputs.optional)  # ('value',) - appears once despite two nodes

If defaults don't match, Graph construction fails:

@node(output_name="x")
def a(value: int = 10) -> int:
    return value

@node(output_name="y")
def b(value: int = 20) -> int:  # Different default!
    return value * 2

Graph([a, b])
# GraphConfigError: Inconsistent defaults for 'value'

Design Decisions

Canonical Scope

InputSpec is computed from graph-level scope only:

• entrypoint / with_entrypoint(...)

• select(...)

• bind(...)

Runtime scope switching (run(..., select=...), run(..., entrypoint=...)) is not supported.

Value Resolution Order

When multiple sources provide the same value, the runner uses: EDGE > PROVIDED > BOUND > DEFAULT

• Internal edge-produced parameters supplied at runtime are rejected deterministically (ValueError).

Complete Example

from hypergraph import node, Graph

# Nodes with various input types
@node(output_name="embedding")
def embed(text: str) -> list[float]:
    """Required input: text"""
    return [0.1, 0.2]

@node(output_name="results")
def search(embedding: list[float], top_k: int = 5, threshold: float = 0.8) -> list[str]:
    """Optional inputs: top_k, threshold"""
    return ["result1", "result2"]

@node(output_name="history")
def update_history(history: list[str], results: list[str]) -> list[str]:
    return history + results

# Build graph (cycle -> constructor entrypoint required)
g = Graph([embed, search, update_history], entrypoint="update_history")

# Inspect InputSpec
print("Required:", g.inputs.required)        # ('text', 'history')
print("Optional:", g.inputs.optional)        # ('top_k', 'threshold')
print("Entry points:", g.inputs.entrypoints)  # {}
print("Bound:", g.inputs.bound)              # {}
print("All:", g.inputs.all)                  # ('text', 'history', 'top_k', 'threshold')

# Bind some values
configured = g.bind(top_k=10, threshold=0.9)
print("\nAfter bind:")
print("Required:", configured.inputs.required)        # ('text', 'history')
print("Optional:", configured.inputs.optional)        # ('top_k', 'threshold') - still have fallback
print("Entry points:", configured.inputs.entrypoints)  # {}
print("Bound:", configured.inputs.bound)              # {'top_k': 10, 'threshold': 0.9}