<!-- Source: https://docs.biosimulant.com/references/library/wiring-api -->

# WiringBuilder API

`WiringBuilder` assembles a named graph of modules and validated port connections for a `BioWorld`.

## Basic usage

```python

from src.vision_demo import Eye, LGN, SuperiorColliculus

world = biosim.BioWorld(communication_step=0.1)
builder = biosim.WiringBuilder(world)

builder.add("eye", Eye())
builder.add("lgn", LGN())
builder.add("sc", SuperiorColliculus())

builder.connect("eye.visual_stream", ["lgn.retina"])
builder.connect("lgn.thalamus", ["sc.vision"])
builder.apply()
```

## Methods

### `add(name, module)`

Register a module under a unique name:

```python
builder.add("my_module", MyModule())
```

Supports chaining:

```python
builder.add("a", ModuleA()).add("b", ModuleB()).add("c", ModuleC())
```

`add()` does not take a scheduler ordering field. Ordering is not part of the communication-step contract.

### `connect(source, destinations)`

Connect one output port to one or more input ports:

```python
builder.connect("source.port", ["target.port"])
builder.connect("source.port", ["target_a.port", "target_b.port"])
```

**Warning:**

  Always pass destinations as a list. `builder.connect("src.port", "dst.port")` passes a bare string and will be treated as an iterable of characters.

### `apply()`

Validate and commit the wiring to the world:

```python
builder.apply()
```

Validation checks:

- `from` and `to` references use `name.port`
- the source port exists in the source module's `outputs()`
- the destination port exists in the target module's `inputs()`
- source and destination `SignalSpec` contracts are compatible

## File-backed specs

```yaml
runtime:
  communication_step: 0.1
modules:
  eye: { class: examples.wiring_builder_demo.Eye }
  lgn: { class: examples.wiring_builder_demo.LGN }
  sc: { class: examples.wiring_builder_demo.SC }
wiring:
  - { from: eye.visual_stream, to: [lgn.retina] }
  - { from: lgn.thalamus, to: [sc.vision] }
```

Loader helpers:

- `biosim.build_from_spec(world, spec)`
- `biosim.load_wiring(world, path)`
- `biosim.load_wiring_yaml(world, path)`
- `biosim.load_wiring_toml(world, path)`

## See Also

- [BioWorld API](/references/library/bioworld-api)
- [BioModule API](/references/library/biomodule-api)
- [How to Use a BioWorld](/how-to/library/use-bioworld)