search-library 0.1.0__tar.gz

search_library-0.1.0/.github/workflows/cd.yml

@@ -0,0 +1,63 @@
+name: CD
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+    permissions:
+      contents: read
+
+  release:
+    needs: ci
+    runs-on: ubuntu-latest
+    concurrency:
+      group: release
+      cancel-in-progress: false
+
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Python Semantic Release
+        id: semantic
+        uses: python-semantic-release/python-semantic-release@v9
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish to PyPI
+        if: steps.semantic.outputs.released == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true
+
+      - name: Publish GitHub Release
+        if: steps.semantic.outputs.released == 'true'
+        uses: python-semantic-release/publish-action@v9
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          tag: ${{ steps.semantic.outputs.tag }}

search_library-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  lint-and-type-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python 3.11
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run Ruff linting
+        run: uv run ruff check src/ tests/
+
+      - name: Run Ruff formatting check
+        run: uv run ruff format --check src/ tests/
+
+      - name: Run MyPy type checking
+        run: uv run mypy src/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --python ${{ matrix.python-version }}
+
+      - name: Run tests with coverage
+        run: uv run pytest --cov=search_library --cov-report=xml --cov-report=term-missing --cov-fail-under=90
+
+      - name: Upload coverage report
+        if: matrix.python-version == '3.11'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage.xml

search_library-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing & Coverage
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+.pytest_cache/
+.mypy_cache/
+
+# Distribution / Packaging
+*.whl
+*.tar.gz
+
+# UV
+uv.lock
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Ruff
+.ruff_cache/

search_library-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

search_library-0.1.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# CHANGELOG
+
+
+## v0.1.0 (2026-06-20)
+
+### Bug Fixes
+
+- Formatting for grid.py and add workflow_call trigger to CI
+  ([`8d75c31`](https://github.com/ahincho/search-library/commit/8d75c314464b2b2090786a66ae4c3785c839d0d1))
+
+- Use pip+build instead of uv in semantic-release container
+  ([`a740379`](https://github.com/ahincho/search-library/commit/a74037961a15263a40bc9b86740afb2f25a9d6a7))
+
+### Chores
+
+- Add workflow_dispatch trigger to CD for manual releases
+  ([`15c5bb0`](https://github.com/ahincho/search-library/commit/15c5bb020e562d4ea9906c190cffacde2a321349))
+
+### Documentation
+
+- Improve README with badges, examples, architecture and roadmap
+  ([`e6e21ab`](https://github.com/ahincho/search-library/commit/e6e21abd928097180bd5ad6b1f81c2820a7f9fb6))
+
+### Features
+
+- Initial implementation of search-library with A* algorithm - Core abstractions: Node, State,
+  SearchProblem, SearchResult - A* search algorithm with heapq priority queue (f=g+h) - Heuristics:
+  Manhattan, Euclidean, extensible base ABC - Graph support: weighted directed/undirected graphs -
+  Grid support: 2D pathfinding with obstacles, 4/8 directions - Custom exceptions and utility
+  helpers - Full test suite (92 tests, 98.87% coverage) - Ruff + MyPy strict configuration - CI/CD:
+  GitHub Actions (matrix 3.11-3.14) + semantic-release + PyPI - pyproject.toml with complete PyPI
+  metadata (MIT license)
+  ([`ae2c4e7`](https://github.com/ahincho/search-library/commit/ae2c4e794f1312e2297237ce0ebd3093908b8fc4))

search_library-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ahincho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

search_library-0.1.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: search-library
+Version: 0.1.0
+Summary: A professional, extensible search algorithm framework for discrete spaces (graphs and grids). Implements A* with pluggable heuristics.
+Project-URL: Homepage, https://github.com/ahincho/search-library
+Project-URL: Repository, https://github.com/ahincho/search-library
+Project-URL: Issues, https://github.com/ahincho/search-library/issues
+Project-URL: Documentation, https://github.com/ahincho/search-library#readme
+Author-email: ahincho <ahincho@unsa.edu.pe>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: a-star,algorithm,astar,graph,grid,heuristic,pathfinding,search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# search-library
+
+[![CI](https://github.com/ahincho/search-library/actions/workflows/ci.yml/badge.svg)](https://github.com/ahincho/search-library/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![MyPy](https://img.shields.io/badge/type--checked-mypy-blue.svg)](http://mypy-lang.org/)
+[![Coverage](https://img.shields.io/badge/coverage-98%25-brightgreen.svg)]()
+
+A professional, extensible search algorithm framework for discrete spaces (graphs and 2D grids).
+
+## Features
+
+- **A\* Search Algorithm** — optimal pathfinding with `f(n) = g(n) + h(n)`
+- **Graph support** — weighted directed/undirected graphs with adjacency lists
+- **Grid support** — 2D pathfinding with obstacles, variable costs, 4/8-directional movement
+- **Pluggable heuristics** — Manhattan, Euclidean, or bring your own
+- **Extensible architecture** — designed for adding BFS, DFS, Dijkstra without modifying base code
+- **Strict typing** — full `mypy --strict` compliance with Generics and Protocols
+- **Zero runtime dependencies** — pure Python standard library only
+
+## Installation
+
+```bash
+pip install search-library
+```
+
+Or with uv:
+
+```bash
+uv add search-library
+```
+
+## Quick Start
+
+### Graph Search
+
+```python
+from search_library import Graph, AStarSearch
+
+# Create an undirected weighted graph
+graph = Graph[str](directed=False)
+graph.add_edge("A", "B", 1.0)
+graph.add_edge("B", "C", 2.0)
+graph.add_edge("A", "C", 5.0)
+
+# Solve with A*
+problem = graph.to_search_problem("A", "C")
+solver = AStarSearch(problem)
+result = solver.search()
+
+print(result.path)           # ['A', 'B', 'C']
+print(result.total_cost)     # 3.0
+print(result.nodes_explored) # 3
+```
+
+### Grid Pathfinding (Maze)
+
+```python
+from search_library import Grid, AStarSearch
+from search_library.grid import GridSearchProblem
+
+# 0 = walkable, 1 = obstacle
+matrix = [
+    [0, 0, 0, 0, 0],
+    [0, 1, 1, 1, 0],
+    [0, 0, 0, 1, 0],
+    [0, 1, 0, 0, 0],
+    [0, 0, 0, 0, 0],
+]
+
+grid = Grid.from_matrix(matrix)
+problem = GridSearchProblem(grid, start=(0, 0), goal=(4, 4))
+solver = AStarSearch(problem)
+result = solver.search()
+
+print(result.success)         # True
+print(result.total_cost)      # 8.0
+print(result.nodes_explored)  # Number of states explored
+```
+
+### Custom Heuristic
+
+```python
+from search_library.heuristics.base import Heuristic
+
+class ChebyshevHeuristic(Heuristic[tuple[int, int]]):
+    """Chebyshev distance — useful for 8-directional grids."""
+    def estimate(self, state: tuple[int, int], goal: tuple[int, int]) -> float:
+        return float(max(abs(state[0] - goal[0]), abs(state[1] - goal[1])))
+```
+
+### Custom Search Problem
+
+```python
+from search_library.core.problem import SearchProblem
+from search_library.algorithms.astar import AStarSearch
+
+class EightPuzzle(SearchProblem[tuple[int, ...]]):
+    """Example: define any discrete search problem."""
+    def initial_state(self) -> tuple[int, ...]:
+        return (1, 2, 3, 4, 0, 5, 6, 7, 8)
+
+    def is_goal(self, state: tuple[int, ...]) -> bool:
+        return state == (1, 2, 3, 4, 5, 6, 7, 8, 0)
+
+    def successors(self, state: tuple[int, ...]) -> list[tuple[tuple[int, ...], float]]:
+        # Return list of (next_state, cost) tuples
+        ...
+```
+
+## Architecture
+
+```
+src/search_library/
+├── core/           # Node, State (Protocol), SearchProblem (ABC), SearchResult
+├── algorithms/     # A* implementation (extensible for BFS, DFS, Dijkstra)
+├── heuristics/     # Heuristic ABC + Manhattan + Euclidean
+├── graph/          # Graph + Edge + GraphSearchProblem adapter
+├── grid/           # Grid + GridSearchProblem adapter (4/8 directions)
+├── utils/          # Formatting helpers
+└── exceptions/     # SearchError hierarchy
+```
+
+### Design Principles
+
+- **SOLID** — each class has a single responsibility; open for extension, closed for modification
+- **Strategy Pattern** — heuristics are interchangeable at runtime
+- **Adapter Pattern** — Graph and Grid adapt to the unified SearchProblem interface
+- **Generic Types** — algorithms work with any hashable state type
+
+## Development
+
+```bash
+# Install all dependencies (including dev tools)
+uv sync
+
+# Run tests with coverage
+uv run pytest
+
+# Lint
+uv run ruff check src/ tests/
+
+# Format
+uv run ruff format src/ tests/
+
+# Type check (strict mode)
+uv run mypy src/
+
+# Build wheel + sdist
+uv build
+```
+
+## CI/CD
+
+| Pipeline | Trigger | What it does |
+|----------|---------|--------------|
+| **CI** | push, PR | Ruff + MyPy + Pytest (matrix: 3.11, 3.12, 3.13, 3.14) |
+| **CD** | push to main | CI + Semantic Release + PyPI publish |
+
+Versioning follows [Conventional Commits](https://www.conventionalcommits.org/):
+- `feat:` → minor version bump
+- `fix:` → patch version bump
+- `feat!:` / `BREAKING CHANGE:` → major version bump
+
+## Roadmap
+
+- [x] A* Search Algorithm
+- [x] Manhattan & Euclidean heuristics
+- [x] Graph support (directed/undirected, weighted)
+- [x] Grid support (4/8 directions, obstacles)
+- [ ] BFS (Breadth-First Search)
+- [ ] DFS (Depth-First Search)
+- [ ] Dijkstra's Algorithm
+- [ ] Bidirectional Search
+- [ ] Visualization utilities
+
+## License
+
+[MIT](LICENSE) — free for academic and commercial use.

search_library-0.1.0/README.md

@@ -0,0 +1,180 @@
+# search-library
+
+[![CI](https://github.com/ahincho/search-library/actions/workflows/ci.yml/badge.svg)](https://github.com/ahincho/search-library/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![MyPy](https://img.shields.io/badge/type--checked-mypy-blue.svg)](http://mypy-lang.org/)
+[![Coverage](https://img.shields.io/badge/coverage-98%25-brightgreen.svg)]()
+
+A professional, extensible search algorithm framework for discrete spaces (graphs and 2D grids).
+
+## Features
+
+- **A\* Search Algorithm** — optimal pathfinding with `f(n) = g(n) + h(n)`
+- **Graph support** — weighted directed/undirected graphs with adjacency lists
+- **Grid support** — 2D pathfinding with obstacles, variable costs, 4/8-directional movement
+- **Pluggable heuristics** — Manhattan, Euclidean, or bring your own
+- **Extensible architecture** — designed for adding BFS, DFS, Dijkstra without modifying base code
+- **Strict typing** — full `mypy --strict` compliance with Generics and Protocols
+- **Zero runtime dependencies** — pure Python standard library only
+
+## Installation
+
+```bash
+pip install search-library
+```
+
+Or with uv:
+
+```bash
+uv add search-library
+```
+
+## Quick Start
+
+### Graph Search
+
+```python
+from search_library import Graph, AStarSearch
+
+# Create an undirected weighted graph
+graph = Graph[str](directed=False)
+graph.add_edge("A", "B", 1.0)
+graph.add_edge("B", "C", 2.0)
+graph.add_edge("A", "C", 5.0)
+
+# Solve with A*
+problem = graph.to_search_problem("A", "C")
+solver = AStarSearch(problem)
+result = solver.search()
+
+print(result.path)           # ['A', 'B', 'C']
+print(result.total_cost)     # 3.0
+print(result.nodes_explored) # 3
+```
+
+### Grid Pathfinding (Maze)
+
+```python
+from search_library import Grid, AStarSearch
+from search_library.grid import GridSearchProblem
+
+# 0 = walkable, 1 = obstacle
+matrix = [
+    [0, 0, 0, 0, 0],
+    [0, 1, 1, 1, 0],
+    [0, 0, 0, 1, 0],
+    [0, 1, 0, 0, 0],
+    [0, 0, 0, 0, 0],
+]
+
+grid = Grid.from_matrix(matrix)
+problem = GridSearchProblem(grid, start=(0, 0), goal=(4, 4))
+solver = AStarSearch(problem)
+result = solver.search()
+
+print(result.success)         # True
+print(result.total_cost)      # 8.0
+print(result.nodes_explored)  # Number of states explored
+```
+
+### Custom Heuristic
+
+```python
+from search_library.heuristics.base import Heuristic
+
+class ChebyshevHeuristic(Heuristic[tuple[int, int]]):
+    """Chebyshev distance — useful for 8-directional grids."""
+    def estimate(self, state: tuple[int, int], goal: tuple[int, int]) -> float:
+        return float(max(abs(state[0] - goal[0]), abs(state[1] - goal[1])))
+```
+
+### Custom Search Problem
+
+```python
+from search_library.core.problem import SearchProblem
+from search_library.algorithms.astar import AStarSearch
+
+class EightPuzzle(SearchProblem[tuple[int, ...]]):
+    """Example: define any discrete search problem."""
+    def initial_state(self) -> tuple[int, ...]:
+        return (1, 2, 3, 4, 0, 5, 6, 7, 8)
+
+    def is_goal(self, state: tuple[int, ...]) -> bool:
+        return state == (1, 2, 3, 4, 5, 6, 7, 8, 0)
+
+    def successors(self, state: tuple[int, ...]) -> list[tuple[tuple[int, ...], float]]:
+        # Return list of (next_state, cost) tuples
+        ...
+```
+
+## Architecture
+
+```
+src/search_library/
+├── core/           # Node, State (Protocol), SearchProblem (ABC), SearchResult
+├── algorithms/     # A* implementation (extensible for BFS, DFS, Dijkstra)
+├── heuristics/     # Heuristic ABC + Manhattan + Euclidean
+├── graph/          # Graph + Edge + GraphSearchProblem adapter
+├── grid/           # Grid + GridSearchProblem adapter (4/8 directions)
+├── utils/          # Formatting helpers
+└── exceptions/     # SearchError hierarchy
+```
+
+### Design Principles
+
+- **SOLID** — each class has a single responsibility; open for extension, closed for modification
+- **Strategy Pattern** — heuristics are interchangeable at runtime
+- **Adapter Pattern** — Graph and Grid adapt to the unified SearchProblem interface
+- **Generic Types** — algorithms work with any hashable state type
+
+## Development
+
+```bash
+# Install all dependencies (including dev tools)
+uv sync
+
+# Run tests with coverage
+uv run pytest
+
+# Lint
+uv run ruff check src/ tests/
+
+# Format
+uv run ruff format src/ tests/
+
+# Type check (strict mode)
+uv run mypy src/
+
+# Build wheel + sdist
+uv build
+```
+
+## CI/CD
+
+| Pipeline | Trigger | What it does |
+|----------|---------|--------------|
+| **CI** | push, PR | Ruff + MyPy + Pytest (matrix: 3.11, 3.12, 3.13, 3.14) |
+| **CD** | push to main | CI + Semantic Release + PyPI publish |
+
+Versioning follows [Conventional Commits](https://www.conventionalcommits.org/):
+- `feat:` → minor version bump
+- `fix:` → patch version bump
+- `feat!:` / `BREAKING CHANGE:` → major version bump
+
+## Roadmap
+
+- [x] A* Search Algorithm
+- [x] Manhattan & Euclidean heuristics
+- [x] Graph support (directed/undirected, weighted)
+- [x] Grid support (4/8 directions, obstacles)
+- [ ] BFS (Breadth-First Search)
+- [ ] DFS (Depth-First Search)
+- [ ] Dijkstra's Algorithm
+- [ ] Bidirectional Search
+- [ ] Visualization utilities
+
+## License
+
+[MIT](LICENSE) — free for academic and commercial use.