personal-graphrag-agent - Multi-domain GraphRAG agent for scientific computi

项目说明

Personal GraphRAG Agent

![CI]()
![Python 3.12]()
![FastAPI]()

Personal GraphRAG Agent is a Python platform for answering technical questions and running long scientific-computing jobs. It chooses simple retrieval for direct questions and bounded graph tra when relationships or workflow context matter. The same orchestration layer can dispatch chemistry, CAD/CFD, structural-analysis, and defensi tools to local or remote workers.

!FreeCAD to OpenFOAM to Blender demonstration

60-second local demo

Docker is the shortest path to a running API. It requires an explicit API key and exposes the service only on 127.0.0.1.

In PowerShell, generate a key with Python, then start Compose and call the protected endpoint:

The application rejects the placeholder value formerly shown in .en. Save the generated key securely if you want to reuse it after closing the shell. Interactive API documentation is a at

Design goals

This is not a chat wrapper around a database. It separates retrieval, authorization, durable execution, worker selection, domain adapters, and artifact handling.

| Engineering concern | Implemented approach |
|---|---|
| Retrie | Conditional routing between RAG and retrie, bounded GraphRAG |
| Agent authorization | Named agents with explicit domain:tool routes |
| Long-running work | SQLite-backed jobs with atomic claiming, retries, events, and restart recovery |
| Heterogeneous compute | Capability- and health-aware selection of local or remote workers |
| Domain extensibility | Tool adapters for chemistry, docking, MD, CAD, CFD, FEA, and defensi |
| E | Portable CI, a public GraphRAG benchmark, reproducible demos, and a Terraform lifecycle |
| Safety | API-key protection, localhost-bound Docker exposure, remote-execution policy, and bounded security tooling |

snapshot

| E | Result |
|---|---:|
| Portable CI suite | 91 passed, 15 skipped |
| Ruff | All checks passed |
| Deterministic router benchmark | 32/32 expected routes (100%); 17/17, graph 15/15 |
| Expanded RAG run | Pending a complete, manually re run with the documented general model |
| CAD/CFD demo | FreeCAD → OpenFOAM → Blender workflow completed |
| Structural FEA | CalculiX asynchronous execution path completed with return code 0 |
| AWS portfolio deployment | 17 resources created, , drift-checked, and destroyed |

These results demonstrate engineering behavior, not uni GraphRAG superiority or experimental scientific . See workflows for scope and limitations.

Run a complete portable job

Submit an RDKit descriptor job using the generated API key. Replace the marked
value with a public, nonconfidential test structure; ne an unpublished
candidate into a demo or issue:

The API returns 202 Accepted with a durable job ID:

Poll the persisted result:

Architecture

The generic orchestration layers do not contain FreeCAD-, GROMACS-, or CalculiX-specific routing algorithms. A new compute mechanism is added through capability declaration, a domain adapter, tool registration, agent authorization, and runtime composition.

See Architecture for component responsibilities and request lifecycles.

Read the core implementation

The main engineering paths are directly browsable without cloning the repository:

| Concern | Source |
|---|---|
| Named-agent authorization | app/agent/named_agent_registry.py |
| Durable asynchronous dispatch | app/agent/jobs/job_dispatcher.py |
| Capability-aware worker routing | app/agent/workers/workload_router.py |
| Conditional retrie | app/graphrag/retrie.py |
| GraphRAG orchestration | app/graphrag/graphrag_service.py |
| Persistent bounded graph tra | app/knowledge_graph/graph_store.py |
| Remote-execution policy | app/agent/workers/remote_execution_policy.py |
| API composition and job endpoints | app/api/main.py |

Supported capabilities

| Domain | Tools | Execution profile |
|---|---|---|
| Drug discovery | RDKit, ADMET-AI, AutoDock Vina, Smina, GROMACS | Bundled RDKit; optional ADMET Python stack; external docking/MD executables |
| CAD and CFD | FreeCAD, OpenFOAM, Blender | External applications on a machine-specific worker |
| Structural FEA | CalculiX | External application on a remote worker |
| Defensi | Authorized private/loopback TCP discovery | Portable, explicitly bounded |

Registered tool routes include:

Installation profiles

Supported adapters do not imply that every scientific application is bundled into the core Python en.

| Profile | Install or provide | Purpose |
|---|---|---|
| Core/API | python -m pip install -r requirements.txt | FastAPI, retrieval, local generation, document ingestion, and portable RDKit execution |
| De/CI | python -m pip install -r requirements-dev.txt | Core plus pytest and Ruff |
| ADMET | python -m pip install -r requirements-sci.txt | Core plus pinned PyTorch and ADMET-AI |
| Remote execution | System OpenSSH client | Used through subprocess; Paramiko is not required |
| Docking/MD/CAD/CFD/FEA | Tool executable on the selected worker | Vina, Smina, GROMACS, FreeCAD, OpenFOAM, Blender, or CalculiX |

The graph store is implemented in the repository and does not require NetworkX. Cloud generation uses Python's standard-library HTTP client and does not directly require aiohttp or provider SDKs. See Dependency and runtime profiles for the complete boundary.

Conditional RAG / GraphRAG

Callers may request auto, , or graph retrieval. In automatic mode, direct document questions normally stay on the path; relationship, workflow, or boundary questions may recei graph context.

Graph tra is seeded from entities found in e. This reduces unrelated graph expansion and keeps the graph branch tied to retrie.

Every response records:

Public benchmark

The repository includes a 32-question benchmark built only from public RDKit, AutoDock Vina, and GROMACS documentation. It contains 17 direct, 10 cross-source, and 5 boundary questions. Every question has an expected retrie, independently maintained gold sources, and claim-le.

The runner reports router accuracy and a confusion matrix, retrie recall, claim co, token use, latency, and population standard de across repeated runs. and GraphRAG generation order alternates to reduce ordering bias. Long runs checkpoint after every completed question and can resume with model, corpus, and protocol settings; optional generation and between-question cooldowns support thermally constrained local hardware.

The deterministic router has been executed against all 32 expected-route labels: 32/32 correct (100%). Its confusion matrix is 17 questions routed to , 15 graph questions routed to graph, and zero cross-route errors. The machine-readable router result records every decision and the SHA-256 identity of the gold-question file. These labels belong to the public de suite rather than an independently held-out set, so this result the present routing rules; it is not a generalization claim.

The pre published six-question run is retained in workflows as a clearly labelled historical pilot, not as e for a general performance claim. The expanded suite must be run and manually re before new model-comparison numbers are published.

See the benchmark methodology for reproducibility and interpretation limits.

Durable agentic execution

A computational request does not directly invoke an executable:

1. A named agent authorizes the requested domain and tool.
2. The dispatcher persists and queues the job.
3. The manager resol worker capabilities.
4. Worker health and compatibility determine placement.
5. The tool registry invokes the domain adapter.
6. Results, events, attempts, errors, and supported artifacts are persisted.

Job states include:

The recovery policy is deliberately conser because silently duplicating an expensi job can be worse than requiring operator review.

API

| Method | Endpoint | Purpose | Authentication |
|---|---|---|---|
| GET | /health | Service and dispatcher health | Public |
| GET | /runtime | Runtime, queue, tool, and agent status | API key |
| GET | /capabilities | Registered domains and tools | API key |
| GET | /agents | Named-agent discovery | API key |
| POST | /jobs | and submit a durable job | API key |
| GET | /jobs/{job_id} | Read persisted job state | API key |

Protected endpoints accept the key in the X-API-Key header. Startup fails when GRAPH_RAG_API_KEY is unset. A loopback-only de may explicitly opt out with GRAPH_RAG_ALLOW_INSECURE_LOCAL=true; never use that setting on a shared or remotely reachable service.

Remote scientific-compute workers

Remote workers are configured through en rather than repository-specific host addresses:

Additional allowlists constrain job roots, artifact roots, OpenFOAM case roots, and appro names. If remote configuration is absent, the API starts without registering a remote compute worker.

The base Compose configuration does not mount SSH material. To enable a remote worker, point GRAPH_RAG_SSH_DIR at a dedicated least-pri SSH directory and apply the opt-in o:

Read Security model before enabling remote execution.

Generation pro

Grounded text generation supports:

Ollama is the default local provider:

Cloud credentials are read from en and must never be committed. Generation-provider selection does not change the embedding model used by existing Chroma collections.

Local de and CI

Python 3.12 is the supported de .

Tests marked external require local models, private data, WSL, or an SSH-accessible worker and are skipped by the portable CI en.

Optional scientific dependencies are listed in requirements-sci.txt.

AWS deployment

The Terraform configuration pro a deliberately small portfolio deployment:

See AWS Terraform deployment. Scientific applications remain on local or remote workers; the EC2 deployment hosts the orchestration API rather than GPU or sol.

Repository map

Security and responsible use

Scope and limitations

Documentation

Contributing

Issues and focused pull requests are welcome. Run the portable test and lint suites before submitting changes. See CONTRIBUTING.md for the de workflow and review checklist.

License

Released under the MIT License.

项目信息

开发语言：Python

Star 数：5

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Multi-domain GraphRAG agent for scientific computing, CAD simulation and defensive security workflows展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。