YiGraph: an LLM agent that calls graph algorithms instead of writing code

The gap YiGraph targets: business questions versus graph query languages

Graph analytics has a translation problem. A fraud analyst knows the question (which accounts form a circular fund flow, which devices share an address with a flagged account) but not the query language, the algorithm name, or the parameter that makes the result meaningful. The README frames YiGraph around exactly this gap: users describe business problems in natural language, and the system plans the analysis, executes it, and produces what the project calls clear, interpretable and traceable reports. The stated audience is domain analysts in anti-money-laundering, e-commerce risk control, enterprise association and compliance investigation, park or city event analysis, and supply chain risk. These are settings where the data is relational by nature and the questions are about structure rather than aggregates. The pitch is narrower than a general-purpose BI assistant: YiGraph is built for questions whose answer is a subgraph, a ranking of nodes, or a path, not a sum or an average.

AAG: the model plans, the algorithm modules compute

The core design claim is the Analytics-Augmented Generation framework. Instead of letting the model write and run arbitrary code, YiGraph treats analytical computation as a fixed capability and invokes graph algorithms at key stages, then has the model interpret and summarize the numeric output. The README is explicit that the system will not let the model arbitrarily write a piece of uncontrollable code and run it. That is a deliberate constraint with a visible consequence: each analysis step is described as reproducible (same input, stable output), traceable (which algorithms ran, in what order), and computed by professional modules rather than text reasoning. The trade-off is coverage. A fixed algorithm library answers the questions it was built for and nothing else. When an analyst needs a bespoke metric, a custom traversal, or a graph transformation no module implements, the AAG pipeline has no escape hatch described in the README. The reliability argument and the expressiveness limit come from the same decision.

Task-aware graph construction rather than one big graph

The second mechanism is selective graph building. YiGraph does not indiscriminately load all raw data into a single graph. It extracts and constructs only the entities and relationships relevant to the current question, which the README says avoids interference from irrelevant structures and organizes the graph into a form more suitable for execution. For anyone who has worked with a monolithic enterprise graph, the motivation is familiar: traversal cost and noise both scale with the parts of the graph you did not need. The cost is that graph construction becomes part of the answer, not a one-time setup step. If the planner picks the wrong entity type or omits a relationship the question depends on, the analysis is wrong before any algorithm runs, and the report may still look coherent. The README does not describe how entity extraction is validated or how a user inspects the constructed graph before execution. That is the point I would probe first in a trial.

What the algorithm library covers, and what the README leaves open

The README claims more than 200 graph algorithms across 21 categories and lists a subset: 10 basics (BFS, DFS, topological sort, DAG detection, ancestor and descendant queries), 13 path algorithms (Dijkstra, Bellman-Ford, Floyd-Warshall, Eulerian path, DAG longest path), 14 centrality measures (PageRank, betweenness, closeness, eigenvector, HITS, VoteRank), 13 connectivity and component routines (connected components, strongly connected components, cut vertices and edges, minimum cut, node and edge connectivity), and 17 clustering and community methods (Louvain, Leiden, label propagation, k-clique, Girvan-Newman, clustering coefficient, cycle detection). The table is truncated in the supplied material, so the remaining categories and the exact algorithm count cannot be confirmed here. The online documentation is the only place the README points to for the complete list. Notice what the categories imply: path, centrality, community and connectivity cover the anti-money-laundering and risk-investigation scenarios named earlier. The library is not a general graph query engine, and the README does not describe how a user selects or overrides an algorithm when the planner's choice is wrong.

Getting it running: Python 3.11, a docs site, and little else in the README

The README states Python 3.11 or later via its badge and links to a documentation site at iDC-NEU.github.io/YiGraphDocs. It does not include an install command, a requirements file listing, a configuration sample, or a quickstart snippet in the supplied text. So the honest answer to how you get it running is: clone the repository, confirm the Python version, install the dependencies the repository declares, and follow the docs site. I cannot give you a verified pip command or a config key because none appears in the material I have. The repository layout does show a docs-site directory with per-category algorithm pages under docs-site/docs/tutorial-algorithm, which is where the algorithm reference lives. One further gap matters for deployment: the README never names the graph backend or storage system the algorithms execute against. Whether YiGraph expects an embedded graph library, a server-based graph database, or its own in-memory representation is not stated in the supplied text. Until that is confirmed, capacity planning is guesswork.

Where YiGraph is the wrong tool

Two failure modes follow from the design. First, dependency on an LLM endpoint. The README assigns intent understanding, task decomposition and output organization to large language models, and the AAG loop calls the model at several stages. There is no described offline or model-free mode. An air-gapped environment, a strict data-residency rule, or a cost ceiling on inference makes YiGraph a poor fit, and the README does not discuss model choice, hosting, or what happens when the model returns a malformed plan. Second, the fixed-library ceiling. If your question is a graph query (return all paths under a length threshold matching a pattern), a graph database with a query language is the direct instrument, and inserting an LLM planner between the analyst and the query adds a failure surface without adding capability. YiGraph is also not a graph visualization or exploration tool; the README describes reports, not interactive graph browsing. And nothing in the supplied material addresses incremental updates, streaming ingestion, or how the graph is refreshed when source data changes.

Neo4j plus an LLM assistant: the same surface, a different split of work

The closest conventional alternative is a graph database such as Neo4j with an LLM assistant layered on top. The architectural difference is where the model sits. In that arrangement the model generates Cypher, the database executes it, and the analyst reads the returned rows or a rendered subgraph. YiGraph inverts this: the model produces a plan over a fixed set of named algorithms, and the algorithms, not generated queries, do the computation. The practical consequences run in both directions. Generated queries can express almost anything, including the bespoke metric YiGraph's library lacks, but they can also be wrong in ways that return plausible-looking results. YiGraph's fixed modules are auditable and repeatable, but they cap what can be asked. A second difference is output: a Cypher result is raw and the analyst interprets it, while YiGraph's stated goal is a generated report that interprets the numbers. If you want the numbers and will do your own reading, the database route is more direct. If you want a written analysis with the computation held fixed, YiGraph is the more specific tool, provided its library covers your questions.

Maintenance, licence and what to verify before committing

The repository metadata reports the licence as unknown, while the README displays an MIT badge. That badge is not the LICENSE file. Anyone planning to ship YiGraph inside a product should read the LICENSE file in the repository root and, if the two disagree, treat the file as the operative text and ask the maintainers to reconcile them. This is not legal advice; it is a discrepancy you can resolve in one minute by opening the file. On maintenance, there are no retrieved releases, so the upgrade path is the main branch rather than tagged versions. The last push recorded in the metadata is 2026-07-24, which suggests active development, but without releases there is no changelog to diff against and no version to pin. Plan for tracking main and re-reading the docs site when algorithm categories change. The project also routes support through a WeChat official account, a WeChat group, Xiaohongshu and an X account rather than an issue tracker visible in the material, which shapes how you would report a bug or follow fixes. Verify the LICENSE file, confirm the graph backend and its scale limits, and check the full algorithm list on the docs site against your actual questions before you build anything on top.

Editorial conclusion

YiGraph suits teams that already hold relational or event data and want graph metrics (centrality, community detection, path analysis) without hand-writing Cypher or Gremlin, and who accept that the LLM plans while fixed algorithm modules compute. It is the wrong choice if you need a general graph database, a visual exploration tool, or a system you can run without an LLM endpoint. Before adopting, verify three things against the repository: the LICENSE file (the badge says MIT but the metadata reports the licence as unknown), the docs site at iDC-NEU.github.io/YiGraphDocs for the full algorithm list and configuration reference, and the graph backend the code actually writes to.

Official sources

1. iDC-NEU/YiGraph on GitHub
2. Issues
3. README