# gustavofelipem/search_lib architecture

> Architecture diagram of the GitHub repository gustavofelipem/search_lib, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gustavofelipem/search_lib
- Repository: https://github.com/gustavofelipem/search_lib

## Overview

`search_lib` is a Python library for exploring state spaces with interchangeable search strategies. A caller supplies an initial state and a problem; a strategy checks goal states, asks the problem for actions, applies valid actions, and builds search nodes in its frontier. It returns a solution node and search metrics, with parent links supporting path reconstruction. The documented extension points include additional problems and algorithms; the sampled implementation contains tree-search BFS, DFS, and depth-limited DFS. The grid example is not mapped because its source was not sampled.

Main entry points: [`search_lib/algorithms/bfs_tree.py`](https://github.com/gustavofelipem/search_lib/blob/main/search_lib/algorithms/bfs_tree.py) (BFS), [`search_lib/algorithms/dfs_tree.py`](https://github.com/gustavofelipem/search_lib/blob/main/search_lib/algorithms/dfs_tree.py) (DFS), [`search_lib/algorithms/dls_tree.py`](https://github.com/gustavofelipem/search_lib/blob/main/search_lib/algorithms/dls_tree.py) (Depth-Limited DFS), [`search_lib/core.py`](https://github.com/gustavofelipem/search_lib/blob/main/search_lib/core.py) (Search Node)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Problem Model"]
  node_state["State<br/>[core.py]"]
  node_action["Action<br/>[core.py]"]
  node_problem["Problem<br/>[core.py]"]
end

subgraph group_runtime["Search Runtime"]
  node_strategy["Strategy Base<br/>[core.py]"]
  node_node["Search Node<br/>[core.py]"]
  node_metrics["Search Metrics<br/>[core.py]"]
  node_result["Search Result<br/>[core.py]"]
  node_callbacks["Search Callbacks<br/>[core.py]"]
end

subgraph group_algorithms["Tree Algorithms"]
  node_bfs["BFS<br/>[bfs_tree.py]"]
  node_dfs["DFS<br/>[dfs_tree.py]"]
  node_dls["Depth-Limited DFS<br/>[dls_tree.py]"]
end

node_caller(("Library Caller"))
node_api["Public API<br/>[__init__.py]"]

node_caller -->|"imports"| node_api
node_caller -->|"selects strategy"| node_bfs
node_caller -->|"selects strategy"| node_dfs
node_caller -->|"selects strategy"| node_dls
node_caller -->|"provides problem"| node_problem
node_caller -->|"provides initial state"| node_state
node_strategy -->|"stores problem"| node_problem
node_bfs -->|"extends"| node_strategy
node_dfs -->|"extends"| node_strategy
node_dls -->|"extends"| node_strategy
node_bfs -->|"checks goal; gets actions"| node_problem
node_dfs -->|"checks goal; gets actions"| node_problem
node_dls -->|"checks goal; gets actions"| node_problem
node_bfs -->|"applies actions"| node_action
node_dfs -->|"applies actions"| node_action
node_dls -->|"applies actions"| node_action
node_bfs -->|"creates frontier nodes"| node_node
node_dfs -->|"creates frontier nodes"| node_node
node_dls -->|"creates frontier nodes"| node_node
node_bfs -->|"updates metrics"| node_metrics
node_dfs -->|"updates metrics"| node_metrics
node_dls -->|"updates metrics"| node_metrics
node_bfs -->|"dispatches events"| node_callbacks
node_dfs -->|"dispatches events"| node_callbacks
node_dls -->|"dispatches events"| node_callbacks
node_bfs -->|"returns result"| node_result
node_dfs -->|"returns result"| node_result
node_dls -->|"returns result"| node_result
node_node -->|"represents"| node_state
node_node -->|"records generating action"| node_action
node_node -->|"links parent"| node_node
node_caller -->|"receives"| node_result

click node_api "https://github.com/gustavofelipem/search_lib/blob/main/search_lib/__init__.py"
click node_state "https://github.com/gustavofelipem/search_lib/blob/main/search_lib/core.py"
click node_action "https://github.com/gustavofelipem/search_lib/blob/main/search_lib/core.py"
click node_problem "https://github.com/gustavofelipem/search_lib/blob/main/search_lib/core.py"
click node_strategy "https://github.com/gustavofelipem/search_lib/blob/main/search_lib/core.py"
click node_node "https://github.com/gustavofelipem/search_lib/blob/main/search_lib/core.py"
click node_metrics "https://github.com/gustavofelipem/search_lib/blob/main/search_lib/core.py"
click node_result "https://github.com/gustavofelipem/search_lib/blob/main/search_lib/core.py"
click node_callbacks "https://github.com/gustavofelipem/search_lib/blob/main/search_lib/core.py"
click node_bfs "https://github.com/gustavofelipem/search_lib/blob/main/search_lib/algorithms/bfs_tree.py"
click node_dfs "https://github.com/gustavofelipem/search_lib/blob/main/search_lib/algorithms/dfs_tree.py"
click node_dls "https://github.com/gustavofelipem/search_lib/blob/main/search_lib/algorithms/dls_tree.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_state,node_action,node_problem toneBlue
class node_strategy,node_node,node_metrics,node_result,node_callbacks toneAmber
class node_bfs,node_dfs,node_dls,node_api toneMint
class node_caller toneIndigo
```

## Components

### Problem Model

- [State](https://github.com/gustavofelipem/search_lib/blob/main/search_lib/core.py): `search_lib/core.py`
- [Action](https://github.com/gustavofelipem/search_lib/blob/main/search_lib/core.py): `search_lib/core.py`
- [Problem](https://github.com/gustavofelipem/search_lib/blob/main/search_lib/core.py): `search_lib/core.py`

### Search Runtime

- [Strategy Base](https://github.com/gustavofelipem/search_lib/blob/main/search_lib/core.py): `search_lib/core.py`
- [Search Node](https://github.com/gustavofelipem/search_lib/blob/main/search_lib/core.py): `search_lib/core.py`
- [Search Metrics](https://github.com/gustavofelipem/search_lib/blob/main/search_lib/core.py): `search_lib/core.py`
- [Search Result](https://github.com/gustavofelipem/search_lib/blob/main/search_lib/core.py): `search_lib/core.py`
- [Search Callbacks](https://github.com/gustavofelipem/search_lib/blob/main/search_lib/core.py): `search_lib/core.py`

### Tree Algorithms

- [BFS](https://github.com/gustavofelipem/search_lib/blob/main/search_lib/algorithms/bfs_tree.py): `search_lib/algorithms/bfs_tree.py`
- [DFS](https://github.com/gustavofelipem/search_lib/blob/main/search_lib/algorithms/dfs_tree.py): `search_lib/algorithms/dfs_tree.py`
- [Depth-Limited DFS](https://github.com/gustavofelipem/search_lib/blob/main/search_lib/algorithms/dls_tree.py): `search_lib/algorithms/dls_tree.py`

### Other components

- **Library Caller**
- [Public API](https://github.com/gustavofelipem/search_lib/blob/main/search_lib/__init__.py): `search_lib/__init__.py`

## Connections

- Library Caller → Public API: imports
- Library Caller → BFS: selects strategy
- Library Caller → DFS: selects strategy
- Library Caller → Depth-Limited DFS: selects strategy
- Library Caller → Problem: provides problem
- Library Caller → State: provides initial state
- Strategy Base → Problem: stores problem
- BFS → Strategy Base: extends
- DFS → Strategy Base: extends
- Depth-Limited DFS → Strategy Base: extends
- BFS → Problem: checks goal; gets actions
- DFS → Problem: checks goal; gets actions
- Depth-Limited DFS → Problem: checks goal; gets actions
- BFS → Action: applies actions
- DFS → Action: applies actions
- Depth-Limited DFS → Action: applies actions
- BFS → Search Node: creates frontier nodes
- DFS → Search Node: creates frontier nodes
- Depth-Limited DFS → Search Node: creates frontier nodes
- BFS → Search Metrics: updates metrics
- DFS → Search Metrics: updates metrics
- Depth-Limited DFS → Search Metrics: updates metrics
- BFS → Search Callbacks: dispatches events
- DFS → Search Callbacks: dispatches events
- Depth-Limited DFS → Search Callbacks: dispatches events
- BFS → Search Result: returns result
- DFS → Search Result: returns result
- Depth-Limited DFS → Search Result: returns result
- Search Node → State: represents
- Search Node → Action: records generating action
- Search Node → Search Node: links parent
- Library Caller → Search Result: receives