Metadata-Version: 2.4
Name: graphaide
Version: 0.6.3
Summary: Multi-agentic knowledge graph construction and reasoning system
Author-email: Sumit Purohit <sumit.purohit@pnnl.gov>
License: MIT
Project-URL: Homepage, https://github.com/pnnl/GraphAide
Project-URL: Source, https://github.com/pnnl/GraphAide/tree/develop
Project-URL: Documentation, https://github.com/pnnl/GraphAide#quickstart
Project-URL: Tracker, https://github.com/pnnl/GraphAide/issues
Project-URL: License, https://github.com/pnnl/GraphAide/blob/develop/LICENSE.txt
Keywords: knowledge-graph,llm,neo4j,multi-agent,rag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Programming Language :: Python :: 3.15
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.16,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
License-File: NOTICE
License-File: AUTHORS.rst
Requires-Dist: importlib-metadata>=8.0.0
Requires-Dist: openai>=2.15.0
Requires-Dist: langfuse>=4.0.0
Requires-Dist: langchain<1.2.0,>=1.0.7
Requires-Dist: sentence_transformers>=5.2.0
Requires-Dist: langchain_community
Requires-Dist: langchain_openai
Requires-Dist: langchain-chroma
Requires-Dist: langgraph==1.0.8
Requires-Dist: langgraph-prebuilt==1.0.8
Requires-Dist: langchain-aws
Requires-Dist: botocore[crt]>=1.42.0
Requires-Dist: boto3>=1.42.0
Requires-Dist: langchain-anthropic
Requires-Dist: langchain_google_genai
Requires-Dist: langchain-mcp-adapters
Requires-Dist: langchain-neo4j>=0.8.0
Requires-Dist: fastmcp>=2.14.5
Requires-Dist: neo4j>=6.1.0
Requires-Dist: ragas>=0.4.3
Requires-Dist: pathlib==1.0.1
Requires-Dist: pypdf==6.6.2
Requires-Dist: pydantic>=2.12.0
Requires-Dist: rdflib>=6.0.0
Requires-Dist: numba==0.68.0
Requires-Dist: umap-learn==0.5.11
Requires-Dist: plotly==6.5.2
Requires-Dist: kaleido==0.2.1
Requires-Dist: pandas>=3.0.0
Requires-Dist: numpy>=2.3.0
Requires-Dist: matplotlib>=3.10.0
Requires-Dist: dash>=3.4.0
Requires-Dist: py2neo>=2021.2.4
Requires-Dist: autogen-agentchat>=0.7.5
Requires-Dist: autogen-ext[openai]>=0.7.5
Requires-Dist: python-dotenv>=1.2.0
Requires-Dist: ipykernel>=7.1.0
Requires-Dist: jupyterlab>=4.5.0
Requires-Dist: webencodings>=0.5.1
Requires-Dist: langchain-text-splitters>=1.1.0
Requires-Dist: typer>=0.9.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn[standard]>=0.29.0
Requires-Dist: rich>=13.0.0
Requires-Dist: qdrant-client<=1.18.0,>=1.18.0
Requires-Dist: langchain-qdrant>=0.1.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: pdf2image>=1.16.0
Provides-Extra: testing
Requires-Dist: setuptools; extra == "testing"
Requires-Dist: pytest; extra == "testing"
Requires-Dist: pytest-cov; extra == "testing"
Dynamic: license-file

# GraphAide

<p align="center">
  <img src="https://raw.githubusercontent.com/pnnl/GraphAide/develop/tests/notebooks/GraphAideLogo_Label_Final.png" alt="GraphAide Logo" width="400">
</p>

**Build knowledge graphs from any document with LLMs and Neo4j.** GraphAide is a multi-agentic system that extracts entities and relationships from diverse sources, constructs knowledge graphs, and enables natural language reasoning over them—all with minimal setup.

## 30-Second Example

### Simplest (Recommended)
```python
from graphaide import GraphAide, ModelConfig, get_sample_data_path

# Setup (once) - uses default Neo4j at localhost:7687
graphaide = GraphAide(
    model_config=ModelConfig(
        provider="openai", 
        model_name="gpt-4o",
        api_key="sk-..."
    )
)

# Extract from sample document
sample_pdf = get_sample_data_path("PNNL_About.pdf")
sample_ontology = get_sample_data_path("ontology_cyber.nt")
result = graphaide.extract(file_path=sample_pdf, ontology_path=sample_ontology)
print(f"✓ Extracted {len(result.nodes)} entities, {len(result.edges)} relationships")
```

### With Custom Neo4j
```python
from graphaide import GraphAide, ModelConfig, GraphDBConfig, get_sample_data_path

graphaide = GraphAide(
    model_config=ModelConfig(provider="openai", model_name="gpt-4o", api_key="sk-..."),
    graphdb_config=GraphDBConfig(uri="neo4j://my-server:7687", username="neo4j", password="password"),
)

sample_pdf = get_sample_data_path("PNNL_About.pdf")
result = graphaide.extract(file_path=sample_pdf)
graphaide.ingest(file_path=sample_pdf)
answer = graphaide.query("What organizations are mentioned?")
```

## What It Does

- **Extract** entities & relationships from PDFs, text, images, or web data
- **Ground** entities to Wikidata for semantic enrichment
- **Load** to Neo4j for queryable knowledge graphs
- **Reason** over graphs with natural language questions
- **Track** chunk provenance for result attribution

## Supported Providers

| LLM | Embedding | Vector Store |
|-----|-----------|--------------|
| OpenAI, Anthropic, Google, AWS Bedrock, LMStudio | OpenAI, Sentence Transformers, AWS Bedrock | ChromaDB, Qdrant |

## Documentation

📚 **Full documentation:** https://pnnl.github.io/GraphAide

**Quick links:**
- **[Installation](https://pnnl.github.io/GraphAide/installation/)** — Get started in minutes
- **[Configuration](https://pnnl.github.io/GraphAide/configuration/)** — Set up LLMs, databases, embeddings
- **[Extraction Guide](https://pnnl.github.io/GraphAide/extraction/)** — Learn entity/relationship extraction
- **[API Reference](https://pnnl.github.io/GraphAide/api/)** — Complete API documentation

## Install

```bash
pip install graphaide
```

See **[QUICKSTART.md](https://github.com/pnnl-int/GraphAide/blob/develop/QUICKSTART.md)** for detailed setup, Docker, and environment configuration.

## Use Cases

- **Knowledge Graph Generation** — Extract structured data from documents into queryable graphs
- **Semantic Search** — Find related entities and concepts across datasets
- **Domain-Specific Reasoning** — Answer questions requiring cross-document reasoning
- **Data Integration** — Merge disparate sources with automated entity grounding
- **Compliance & Audit** — Track relationships and dependencies with provenance

## Architecture

GraphAide uses a multi-agent architecture orchestrated by [LangGraph](https://langchain.com/docs/langgraph):

```
Document → [FileLoader] → [Extractor] → [Nodes4EdgesLoader] 
         → [NodesLoader] → [EdgesLoader] → Neo4j
         ↓
      [VectorDB] ← [Embeddings] ← RAG Context
```

**Factory pattern** manages LLMs, vector stores, and graph databases:
- `ModelFactory` — Loads LLMs from OpenAI, Anthropic, Google, AWS Bedrock, or local LMStudio
- `GraphDBFactory` — Manages Neo4j/Neptune connections
- `VectorStoreFactory` — Manages ChromaDB or Qdrant vector indices
- `AgentFactory` — Builds extraction, loading, and query agents

**Agents communicate** via `KGGenerationState` (append-only shared state with reducers):
- `raw_text`, `file_path` — Input document
- `nodes`, `edges` — Extracted entities and relationships  
- `rag_context` — Ontology constraints and Wikidata metadata
- `messages` — Status and debug info

## Tested Configurations

| Provider | LLM | Embedding |
|----------|-----|-----------|
| OpenAI | gpt-4o, gpt-4o-mini | text-embedding-3-small |
| Anthropic | claude-3-5-sonnet | claude-3-5-sonnet (native) |
| AWS Bedrock | anthropic.claude-3-5-sonnet | amazon.titan-embed-text-v1 |
| LMStudio (local) | google/gemma-3-27b:2 | text-embedding-nomic-embed-text-v1.5 |

## Run Modes

| Mode | Command |
|------|---------|
| **CLI** | `graphaide extract doc.pdf` |
| **Docker** | `docker compose up` then `docker exec` |
| **Python** | `from graphaide import GraphAide` |
| **REST** | `graphaide serve` → `http://localhost:8000` |

## Support

Please reach out to Sumit.Purohit@pnnl.gov for any questions.

## Authors and acknowledgment
Please reach out to Sumit.Purohit@pnnl.gov for any questions.

## Citation
If you use GraphAide in your research, please cite:

```bibtex
@inproceedings{purohit2024graphaide,
  title={GraphAide: Advanced Graph-Assisted Query and Reasoning System},
  author={Purohit, Sumit and Chin, George and Mackey, Patrick S and Cottam, Joseph A},
  booktitle={2024 IEEE International Conference on Big Data (BigData)},
  pages={3485--3493},
  year={2024},
  organization={IEEE}
}
```

The research described in this paper is partially supported
by the Resilience Through Data Driven, Intelligently Designed
Control (RD2C) Initiative at Pacific Northwest National Laboratory (PNNL) and the United States federal government.
Pacific Northwest National Laboratory is a multiprogram
national laboratory operated for the US Department of Energy
(DOE) by Battelle Memorial Institute under Contract No. DEAC05-76RL01830. PNNL Information Release PNNL-SA205147.

## License & Legal

GraphAide is licensed under the **BSD 2-Clause License** (Simplified BSD).

**Important:** Please review the following legal documents:

- **[LICENSE.txt](LICENSE.txt)** — Full license terms
- **[DISCLAIMER](DISCLAIMER)** — Limitations and use restrictions
- **[ACKNOWLEDGMENT](ACKNOWLEDGMENT)** — Credits, funding, citations
- **[NOTICE](NOTICE)** — Software identification and legal notices

See the [Legal section](https://pnnl.github.io/GraphAide/legal/) in documentation for more details.

## Project status

**Status:** Active development  
**Version:** 0.5.29  
**Last Updated:** October 2026
