{"id":46491918,"url":"https://github.com/queelius/algograph","last_synced_at":"2026-03-06T11:01:18.113Z","repository":{"id":324082440,"uuid":"1084623756","full_name":"queelius/AlgoGraph","owner":"queelius","description":"Immutable graph data structures and algorithms library with interactive shell","archived":false,"fork":false,"pushed_at":"2026-01-23T16:26:15.000Z","size":985,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-24T00:44:17.380Z","etag":null,"topics":["algorithms","bfs","data-structures","dfs","dijkstra","graph","graph-algorithms","graph-theory","graph-visualization","immutable","interactive-shell","python","shortest-path"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/queelius.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-27T23:50:26.000Z","updated_at":"2026-01-23T16:26:19.000Z","dependencies_parsed_at":"2026-03-06T11:01:15.240Z","dependency_job_id":null,"html_url":"https://github.com/queelius/AlgoGraph","commit_stats":null,"previous_names":["queelius/algograph"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/queelius/AlgoGraph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/queelius%2FAlgoGraph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/queelius%2FAlgoGraph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/queelius%2FAlgoGraph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/queelius%2FAlgoGraph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/queelius","download_url":"https://codeload.github.com/queelius/AlgoGraph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/queelius%2FAlgoGraph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30173342,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T07:56:45.623Z","status":"ssl_error","status_checked_at":"2026-03-06T07:55:55.621Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algorithms","bfs","data-structures","dfs","dijkstra","graph","graph-algorithms","graph-theory","graph-visualization","immutable","interactive-shell","python","shortest-path"],"created_at":"2026-03-06T11:00:56.884Z","updated_at":"2026-03-06T11:01:18.099Z","avatar_url":"https://github.com/queelius.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AlgoGraph\n\nImmutable graph data structures and algorithms library with functional transformers, declarative selectors, and lazy views.\n\n[![PyPI version](https://badge.fury.io/py/AlgoGraph.svg)](https://pypi.org/project/AlgoGraph/)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Installation\n\n```bash\npip install AlgoGraph\n```\n\n## Overview\n\nAlgoGraph provides immutable graph data structures with a clean, functional API. Version 2.0.0 brings AlgoTree-level API elegance with pipe-based transformers, declarative selectors, and lazy views—achieving ~90% code reduction for common operations.\n\n## Key Features\n\n- **Immutable by default**: All operations return new graph objects\n- **56+ algorithms**: Traversal, shortest path, centrality, flow, matching, coloring\n- **Pipe-based transformers**: Composable operations with `|` operator (v2.0.0)\n- **Declarative selectors**: Pattern matching with logical operators (v2.0.0)\n- **Lazy views**: Memory-efficient filtering without copying (v2.0.0)\n- **Fluent builder API**: Construct graphs with 82% less code\n- **Type-safe**: Full type hints for IDE support\n- **Optional AlgoTree integration**: Convert between trees and graphs\n\n## Quick Start\n\n```python\nfrom AlgoGraph import Graph, Vertex, Edge\n\n# Create a graph\ng = (Graph.builder()\n     .add_vertex('A', age=30)\n     .add_vertex('B', age=25)\n     .add_edge('A', 'B', weight=5.0)\n     .build())\n\n# Query the graph\ng.has_edge('A', 'B')  # True\ng.neighbors('A')       # {'B'}\n\n# Run algorithms\nfrom AlgoGraph.algorithms import dijkstra, pagerank\ndistances = dijkstra(g, source='A')\n```\n\n## Advanced Features (v2.0.0)\n\n### Transformer Pipelines\n\nCompose graph operations using the `|` pipe operator:\n\n```python\nfrom AlgoGraph.transformers import filter_vertices, largest_component, stats\n\n# Filter → extract component → compute stats\nresult = (graph\n    | filter_vertices(lambda v: v.get('active'))\n    | largest_component()\n    | stats())\n\n# result: {'vertex_count': 42, 'edge_count': 156, 'density': 0.18, ...}\n```\n\n**Available Transformers:**\n- `filter_vertices(pred)`, `filter_edges(pred)` - Filter by predicate\n- `map_vertices(fn)`, `map_edges(fn)` - Transform attributes\n- `reverse()`, `to_undirected()` - Structure transformations\n- `largest_component()`, `minimum_spanning_tree()` - Algorithm-based\n- `to_dict()`, `to_adjacency_list()`, `stats()` - Export operations\n\n### Declarative Selectors\n\nQuery vertices and edges with logical operators:\n\n```python\nfrom AlgoGraph.graph_selectors import vertex as v, edge as e\n\n# Find active users with high degree\npower_users = graph.select_vertices(\n    v.attrs(active=True) \u0026 v.degree(min_degree=10)\n)\n\n# Find heavy edges from admin nodes\nadmin_edges = graph.select_edges(\n    e.source(v.attrs(role='admin')) \u0026 e.weight(min_weight=100)\n)\n\n# Complex queries with OR, NOT, XOR\nspecial = graph.select_vertices(\n    (v.attrs(vip=True) | v.degree(min_degree=50)) \u0026 ~v.attrs(banned=True)\n)\n```\n\n**Selector Types:**\n- `vertex.id(pattern)` - Match by ID (glob/regex)\n- `vertex.attrs(**attrs)` - Match attributes (supports callables)\n- `vertex.degree(min/max/exact)` - Match by degree\n- `edge.weight(min/max/exact)` - Match by weight\n- `edge.source(selector)`, `edge.target(selector)` - Match endpoints\n\n### Lazy Views\n\nEfficient filtering without copying data:\n\n```python\nfrom AlgoGraph.views import filtered_view, neighborhood_view\n\n# Create view without copying\nview = filtered_view(\n    large_graph,\n    vertex_filter=lambda v: v.get('active'),\n    edge_filter=lambda e: e.weight \u003e 5.0\n)\n\n# Iterate lazily\nfor vertex in view.vertices():\n    process(vertex)\n\n# Materialize only when needed\nsmall_graph = view.materialize()\n\n# Explore k-hop neighborhood\nlocal = neighborhood_view(graph, center='Alice', k=2)\n```\n\n**View Types:**\n- `filtered_view()` - Filter vertices/edges\n- `subgraph_view()` - View specific vertices\n- `reversed_view()` - Reverse edge directions\n- `undirected_view()` - View as undirected\n- `neighborhood_view()` - k-hop neighborhood\n\n## Core Classes\n\n### Vertex\n\n```python\nfrom AlgoGraph import Vertex\n\nv = Vertex('A', attrs={'value': 10, 'color': 'red'})\nv2 = v.with_attrs(value=20)      # Immutable update\nv3 = v.without_attrs('color')    # Remove attribute\n```\n\n### Edge\n\n```python\nfrom AlgoGraph import Edge\n\ne = Edge('A', 'B', directed=True, weight=5.0)\ne2 = e.with_weight(10.0)  # Immutable update\ne3 = e.reversed()         # B -\u003e A\n```\n\n### Graph\n\n```python\nfrom AlgoGraph import Graph, Vertex, Edge\n\n# Direct construction\ng = Graph({Vertex('A'), Vertex('B')}, {Edge('A', 'B')})\n\n# Fluent builder\ng = (Graph.builder()\n     .add_vertex('A', age=30)\n     .add_edge('A', 'B', weight=5.0)\n     .add_path('B', 'C', 'D')\n     .add_cycle('X', 'Y', 'Z')\n     .build())\n\n# From edges (auto-creates vertices)\ng = Graph.from_edges(('A', 'B'), ('B', 'C'), ('C', 'A'))\n\n# Immutable operations\ng2 = g.add_vertex(Vertex('D'))\ng3 = g.remove_vertex('A')\ng4 = g.subgraph({'B', 'C', 'D'})\n```\n\n## Algorithms\n\n### Traversal\n\n```python\nfrom AlgoGraph.algorithms import dfs, bfs, topological_sort, has_cycle, find_path\n\nvisited = dfs(graph, start_vertex='A')\nlevels = bfs(graph, start_vertex='A')\norder = topological_sort(graph)  # DAG only\npath = find_path(graph, 'A', 'Z')\n```\n\n### Shortest Paths\n\n```python\nfrom AlgoGraph.algorithms import dijkstra, bellman_ford, floyd_warshall, a_star\n\ndistances = dijkstra(graph, source='A')\ndistances = bellman_ford(graph, source='A')  # Handles negative weights\nall_pairs = floyd_warshall(graph)\npath = a_star(graph, 'A', 'Z', heuristic=h)\n```\n\n### Connectivity\n\n```python\nfrom AlgoGraph.algorithms import (\n    connected_components, strongly_connected_components,\n    is_connected, is_bipartite, find_bridges, find_articulation_points\n)\n\ncomponents = connected_components(graph)\nscc = strongly_connected_components(graph)\nbridges = find_bridges(graph)\narticulation = find_articulation_points(graph)\n```\n\n### Spanning Trees\n\n```python\nfrom AlgoGraph.algorithms import minimum_spanning_tree, kruskal, prim\n\nmst = minimum_spanning_tree(graph)\nmst = kruskal(graph)\nmst = prim(graph, start='A')\n```\n\n### Centrality\n\n```python\nfrom AlgoGraph.algorithms import (\n    pagerank, betweenness_centrality, closeness_centrality,\n    degree_centrality, eigenvector_centrality\n)\n\npr = pagerank(social_network)\nbc = betweenness_centrality(network)\ncc = closeness_centrality(network)\n```\n\n### Flow Networks\n\n```python\nfrom AlgoGraph.algorithms import max_flow, min_cut, edmonds_karp\n\nflow_value = max_flow(network, 'Source', 'Sink')\ncut_value, source_set, sink_set = min_cut(network, 'Source', 'Sink')\n```\n\n### Matching\n\n```python\nfrom AlgoGraph.algorithms import hopcroft_karp, maximum_bipartite_matching, is_perfect_matching\n\nmatching = hopcroft_karp(bipartite_graph, left_set, right_set)\nmax_matching = maximum_bipartite_matching(graph, left, right)\n```\n\n### Graph Coloring\n\n```python\nfrom AlgoGraph.algorithms import welsh_powell, chromatic_number, dsatur, is_k_colorable\n\ncoloring = welsh_powell(graph)\nnum_colors = chromatic_number(graph)\ncoloring = dsatur(graph)  # Often better than greedy\n```\n\n## Serialization\n\n```python\nfrom AlgoGraph import save_graph, load_graph\n\n# Save/load JSON\nsave_graph(graph, 'network.json')\ngraph = load_graph('network.json')\n```\n\n## AlgoTree Integration (Optional)\n\n```python\nfrom AlgoTree import Node, Tree\nfrom AlgoGraph import tree_to_graph, graph_to_tree\n\n# Tree to Graph\ntree = Tree(Node('root', Node('child1'), Node('child2')))\ngraph = tree_to_graph(tree)\n\n# Graph to Tree (extracts spanning tree)\ntree = graph_to_tree(graph, root='root')\n```\n\n## Interactive Shell\n\nExplore graphs with a filesystem-like interface:\n\n```bash\npip install AlgoGraph\nalgograph                    # Start with sample graph\nalgograph network.json       # Load from file\n```\n\n```\ngraph(5v):/$ ls\nAlice/  [2 neighbors]\nBob/    [3 neighbors]\n\ngraph(5v):/$ cd Alice\ngraph(5v):/Alice$ ls\nAttributes:\n  age = 30\nneighbors/  [2 vertices]\n\ngraph(5v):/Alice$ path Bob Eve\nPath found: Alice -\u003e Bob -\u003e Diana -\u003e Eve\n```\n\n## Examples\n\n### Social Network Analysis\n\n```python\nfrom AlgoGraph import Graph\nfrom AlgoGraph.algorithms import pagerank, betweenness_centrality\nfrom AlgoGraph.transformers import filter_vertices, stats\nfrom AlgoGraph.graph_selectors import vertex as v\n\n# Build network\nnetwork = (Graph.builder()\n    .add_vertex('Alice', followers=1000)\n    .add_vertex('Bob', followers=500)\n    .add_vertex('Charlie', followers=2000)\n    .add_edge('Alice', 'Bob', directed=False)\n    .add_edge('Bob', 'Charlie', directed=False)\n    .add_edge('Alice', 'Charlie', directed=False)\n    .build())\n\n# Find influencers\npr = pagerank(network)\ntop_influencer = max(pr, key=pr.get)\n\n# Find power users with selector\npower_users = network.select_vertices(\n    v.attrs(followers=lambda f: f \u003e 800)\n)\n\n# Analyze active subgraph\nanalysis = (network\n    | filter_vertices(lambda v: v.get('followers', 0) \u003e 500)\n    | stats())\n```\n\n### Road Network\n\n```python\nfrom AlgoGraph import Graph\nfrom AlgoGraph.algorithms import dijkstra, minimum_spanning_tree\n\nroads = (Graph.builder()\n    .add_edge('NYC', 'Boston', weight=215, directed=False)\n    .add_edge('NYC', 'DC', weight=225, directed=False)\n    .add_edge('Boston', 'DC', weight=440, directed=False)\n    .build())\n\n# Shortest routes from NYC\ndistances = dijkstra(roads, 'NYC')\n\n# Minimum cost network\nmst = minimum_spanning_tree(roads)\n```\n\n## Design Philosophy\n\n1. **Immutability**: All operations return new objects\n2. **Composability**: Chain operations with `|` pipe operator\n3. **Declarative**: Express *what*, not *how* (selectors vs lambdas)\n4. **Lazy evaluation**: Views defer computation until needed\n5. **Type safety**: Full type hints throughout\n\n## Related Projects\n\n- **[AlgoTree](https://github.com/queelius/AlgoTree)**: Tree data structures and algorithms\n- **[NetworkX](https://networkx.org/)**: Comprehensive Python graph library (mutable)\n- **[graph-tool](https://graph-tool.skewed.de/)**: High-performance graph analysis\n\n## License\n\nMIT License - see LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqueelius%2Falgograph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqueelius%2Falgograph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqueelius%2Falgograph/lists"}