faebryk
- Repo stars 3,367
- License MIT
- Author repo atopile
- Domain
- Other
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 94 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @atopile · MIT
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- macOS · Linux · Windows
- Runtime requirements
- Node.js · Python
- Detected file/system behavior
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# Faebryk Core Module
The Faebryk core here is the **TypeGraph** + edge types implemented in Zig and exposed to Python via `faebryk.core.faebrykpy`.
Source-of-truth for API + behavior:
- `src/faebryk/core/faebrykpy.py` (Python-facing wrapper + type-safe `EdgeTrait.traverse`)
- `src/faebryk/core/zig/gen/faebryk/typegraph.pyi` (public stubbed API surface)
- `src/faebryk/core/zig/src/faebryk/*` (Zig implementation)
## Quick Start
```python
import faebryk.core.faebrykpy as fbrk
import faebryk.core.graph as graph
g = graph.GraphView.create()
tg = fbrk.TypeGraph.create(g=g)
```
## Relevant Files
- `src/faebryk/core/faebrykpy.py` (re-exports + `EdgeTraversal` + type-safe `EdgeTrait.traverse`)
- `src/faebryk/core/zig/gen/faebryk/typegraph.pyi` (TypeGraph stub)
- Key edge types (imported by `faebrykpy.py`):
- `EdgeComposition` (parent/child structure)
- `EdgeTrait` / `Trait` (trait attachment)
- `EdgePointer` (references)
- `EdgeInterfaceConnection` (interface connections)
- `EdgeOperand` (solver operand wiring)
- `EdgeType` / `EdgeNext` (type graph plumbing)
- Linker:
- `Linker` (used by compiler/linking stages)
## Dependants (Call Sites)
- FabLL: `src/faebryk/core/node.py` (binds Python classes into the TypeGraph; uses composition/trait edges)
- Compiler: `src/atopile/compiler/*` (creates and links TypeGraphs)
- Solver: `src/faebryk/core/solver/*` (operand edges and instance traversal)
- Build/export pipeline: `src/atopile/build_steps.py` (visits type/instance edges for PCB/layout features)
## How to Work With / Develop / Test
### Core Concepts
- **GraphView + TypeGraph**: a `TypeGraph` is created against a `GraphView`:
```python
import faebryk.core.graph as graph
import faebryk.core.faebrykpy as fbrk
g = graph.GraphView.create()
tg = fbrk.TypeGraph.create(g=g)
```
- **Type nodes vs instance nodes**:
- TypeGraph stores type definitions (“what exists structurally on a type”)
- GraphView also holds instances created from those types (“a concrete design graph”)
- **EdgeTraversal**: `TypeGraph.ensure_child_reference(..., path=[...])` uses `EdgeTraversal` items to walk references through the type graph.
### Development Workflow
1) Zig-side changes: edit `src/faebryk/core/zig/src/faebryk/*` (edges, typegraph internals).
2) Rebuild bindings: `ato dev compile` (imports `faebryk.core.zig`).
3) Python ergonomics: add wrappers/helpers in `src/faebryk/core/faebrykpy.py` (example: type-safe `EdgeTrait.traverse`).
### Testing
- TypeGraph-heavy tests live in compiler/runtime suites:
- `ato dev test --llm test/compiler/test_typegraph.py -q`
- `ato dev test --llm test/compiler/test_runtime.py -q`
- Zig-backed traversal tests:
- `ato dev test --llm test/core/zig/test_interface_pathfinder.py -q`
## Best Practices
- Import edges/TypeGraph via `faebryk.core.faebrykpy` (so callers get Python helpers, not just raw generated types).
- Prefer type-safe trait traversal:
- `EdgeTrait.traverse(trait_type=SomeTrait)` over stringly-typed `trait_type_name=...`.
- When building reference paths, be explicit about edge semantics (composition vs pointer vs trait) rather than relying on implicit string behavior.
Sections and files
Listed in source order.
sections -> Quick Start → Relevant Files → Dependants (Call Sites) → How to Work With / Develop / Test → Core Concepts → Development Workflow
terms -> TypeGraph · GraphView + TypeGraph · Type nodes vs instance nodes · EdgeTraversal
files/cmd -> faebryk.core.faebrykpy · src/faebryk/core/faebrykpy.py · EdgeTrait.traverse · src/faebryk/core/zig/gen/faebryk/typegraph.pyi · src/faebryk/core/zig/src/faebryk/* · EdgeTraversal · faebrykpy.py · EdgeComposition
body sha256 -> 5e0bc10f7159
Relevant Files
src/faebryk/core/faebrykpy.py(re-exports +EdgeTraversal+ type-safeEdgeTrait.traverse)src/faebryk/core/zig/gen/faebryk/typegraph.pyi(TypeGraph stub) Key edge types (imported byfaebrykpy.py):EdgeComposition(parent/child structure)EdgeTrait/Trait(trait attachment)Dependants (Call Sites)
FabLL:
src/faebryk/core/node.py(binds Python classes into the TypeGraph; uses composition/trait edges) Compiler:src/atopile/compiler/*(creates and links TypeGraphs) Solver:src/faebryk/core/solver/*(operand edges and instance traversal) Build/export pipeline:src/atopile/build_steps.py(visits type/instance edges for PCB/layout features)Core Concepts
GraphView + TypeGraph: a
TypeGraphis created against aGraphView: Type nodes vs instance nodes: TypeGraph stores type definitions (“what exists structurally on a type”) GraphView also holds instances created from those types (“a concrete design graph”) EdgeTraversal:TypeGraph.ensure_child_reference(..., path=[...])usesEdgeTraversalitems to walk references through the type graph.Development Workflow
Zig-side changes: edit
src/faebryk/core/zig/src/faebryk/*(edges, typegraph internals). Rebuild bindings:ato dev compile(importsfaebryk.core.zig). Python ergonomics: add wrappers/helpers insrc/faebryk/core/faebrykpy.py(example: type-safeEdgeTrait.traverse).Testing
TypeGraph-heavy tests live in compiler/runtime suites:
ato dev test --llm test/compiler/test_typegraph.py -qato dev test --llm test/compiler/test_runtime.py -qZig-backed traversal tests:ato dev test --llm test/core/zig/test_interface_pathfinder.py -q