# fastgraph

**Repository Path**: techwolf/fastgraph

## Basic Information

- **Project Name**: fastgraph
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-05
- **Last Updated**: 2026-09-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# fastgraph

A FastGPT v4.15+ plugin and workflow bundle that builds and queries a
Neo4j knowledge graph from a FastGPT dataset, with **all LLM calls
delegated to FastGPT workflow AI nodes** so they go through the
platform's model proxy, secret management, retry, and audit.

## What's in this repo

```
fastgraph/
├── docs/
│   └── k.md                # Original design doc (k.md)
├── packages/
│   └── tools/
│       └── neo4j-kg-toolset/   # The plugin (TypeScript, ESM)
│           ├── src/
│           │   ├── lib/        # shared: errors, retry, neo4j, fastgpt, secret, chunk_hash
│           │   └── tools/      # the 8 tool handlers
│           ├── test/           # vitest unit tests
│           ├── dist/           # CLI build output
│           └── out/            # .pkg package output
└── workflows/
    ├── pipeline-a-build.json   # offline batch build
    ├── pipeline-b-query.json   # online graph-augmented Q&A
    └── README.md
```

## Eight tools, no in-plugin LLM

| ID | Purpose |
|---|---|
| `kg_init` | Idempotently create Neo4j constraints, vector index, GDS projection |
| `kg_list_chunks` | Paginate all chunks in a FastGPT dataset with hashes |
| `kg_sync` | Single-hash incremental existence check |
| `kg_reconcile` | Diff supplied hashes against graph; clean orphans |
| `kg_write` | Batch `MERGE` triples + Chunk `MENTIONS` in one transaction |
| `kg_embed_entities` | Fetch entity embeddings via FastGPT API and write back |
| `kg_query` | Multi-hop subgraph retrieval by entity names |
| `kg_community` | Leiden community detection via GDS |

## Quick start

```bash
cd packages/tools/neo4j-kg-toolset
pnpm install
pnpm run check       # static check
pnpm run test        # unit tests
pnpm run build       # build dist/
pnpm run pack        # produce out/neo4j-kg-toolset.pkg
```

Upload `out/neo4j-kg-toolset.pkg` to FastGPT admin → Plugin Market →
Upload local package.

In the plugin settings, configure only Neo4j credentials:

| Field | Secret? |
|---|---|
| `neo4jUri` | no |
| `neo4jUser` | no |
| `neo4jPassword` | yes |
| `neo4jDatabase` (default `neo4j`) | no |
| `vectorDimensions` (default `1536`) | no |

FastGPT API auth is **automatic** via `ctx.systemVar.invokeToken` — no
FastGPT credentials in the secretSchema.

Then import the two workflow JSONs from `workflows/` and bind
`pipeline-b-query` to a Simple App (Workflow mode).

## How LLM operations are wired

The `k.md` design proposed having `kg_extract`, `kg_query`, and
`kg_community` call an LLM directly inside the plugin via a
`ctx.llm.chat.completions` endpoint that **does not exist** in the
real `@fastgpt-plugin/sdk-factory` v0.0.1. Instead, those LLM
operations live in FastGPT workflow AI nodes (`chatNode`):

- **Entity extraction** (pipeline A): AI node with `response_format: json_object` extracts triples per chunk; the workflow code node parses JSON and feeds `kg_write`.
- **Query entity recognition** (pipeline B): AI node extracts entities from the user query; workflow feeds `kg_query`.
- **Community summary** (pipeline A end): AI node summarizes each Leiden cluster.

This keeps all model calls under FastGPT's model proxy and secret
management — the plugin never holds an LLM API key.

## Reference

- `docs/USAGE.md` — full usage guide (build, deploy, tools, workflows, FAQ).
- `docs/k.md` — original design doc, kept for context.
- `packages/tools/neo4j-kg-toolset/README.md` — plugin details.
- `workflows/README.md` — workflow import instructions.