{"id":26484934,"url":"https://github.com/mrorigo/agentic-deep-graph-reasoning","last_synced_at":"2025-03-20T05:53:47.297Z","repository":{"id":279039341,"uuid":"937551645","full_name":"mrorigo/agentic-deep-graph-reasoning","owner":"mrorigo","description":"Agentic Deep Graph Reasoning Implementation","archived":false,"fork":false,"pushed_at":"2025-03-03T16:20:32.000Z","size":867,"stargazers_count":11,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-03T16:42:25.055Z","etag":null,"topics":["ai-learning","entity-extraction","knowledge-distillation","knowledge-graph","reasoning-models"],"latest_commit_sha":null,"homepage":"","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/mrorigo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-23T10:46:11.000Z","updated_at":"2025-03-03T16:31:45.000Z","dependencies_parsed_at":"2025-02-23T11:39:54.998Z","dependency_job_id":null,"html_url":"https://github.com/mrorigo/agentic-deep-graph-reasoning","commit_stats":null,"previous_names":["mrorigo/agentic-deep-graph-reasoning"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrorigo%2Fagentic-deep-graph-reasoning","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrorigo%2Fagentic-deep-graph-reasoning/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrorigo%2Fagentic-deep-graph-reasoning/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrorigo%2Fagentic-deep-graph-reasoning/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mrorigo","download_url":"https://codeload.github.com/mrorigo/agentic-deep-graph-reasoning/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244560369,"owners_count":20472219,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["ai-learning","entity-extraction","knowledge-distillation","knowledge-graph","reasoning-models"],"created_at":"2025-03-20T05:53:46.815Z","updated_at":"2025-03-20T05:53:47.289Z","avatar_url":"https://github.com/mrorigo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agentic Deep Graph Reasoning\n\nThis repository contains an implementation inspired by concepts from [\"Agentic Deep Graph Reasoning\"](https://arxiv.org/abs/2502.13025) by [Markus J. Buehler](https://orcid.org/0000-0002-4173-9659). This implementation focuses on core concepts of iterative knowledge graph expansion through language model-driven reasoning.\n\n\u003e [!IMPORTANT]\n\u003e  ⚠️ **Note:** This implementation has been significantly updated since the previous version. Key changes include the addition of vector embedding using pgvector for enhanced similarity comparisons and conflict resolution, a dedicated conflict resolution service, and improved model configuration options.  See the \"Key Features\" and \"Technical Architecture\" sections for more details.  Please review the updated installation and configuration instructions carefully.\n\n\n## 📝 Scope Note\n\nThis is an implementation that focuses on basic autonomous knowledge graph expansion and implements core concepts of iterative reasoning and structured knowledge extraction. It provides a practical starting point for experimenting with agentic knowledge graphs.\n\nKey characteristics:\n- Focuses on autonomous knowledge graph expansion\n- Implements iterative reasoning and structured knowledge extraction\n- Provides a practical starting point\n\n## 🌟 Key Features\n\n- **Iterative Graph Expansion**: Grows knowledge graphs through recursive reasoning, exploring related concepts over multiple iterations.\n- **Multi-Model Architecture**:  Leverages separate language models for reasoning, entity extraction, and conflict resolution, each configurable for optimal performance.\n- **Neo4j Integration**: Provides persistent storage and querying of the generated knowledge graph using Neo4j.\n- **Streaming Output**: Displays the reasoning process in real-time, providing insights into the knowledge graph generation.\n- **Flexible Model Configuration**: Supports different LLM providers through configurable API endpoints, including OpenAI and local models via Ollama.\n- **Vector Embedding**: Implements vector embeddings using pgvector for semantic similarity comparisons and conflict resolution.\n- **Conflict Resolution**:  Addresses potential conflicts between existing and new entities using an LLM-driven conflict resolution service.\n\n## Examples\n\n**Prompt:** \"Describe the role and stance of Sweden during World War II\"\n\n**Iterations:** 2\n\n![Sweden during WW2, 2 iterations](images/SwedenWW2_2_Iterations_thumb.png)[Large version of image](images/SwedenWW2_2_Iterations.png)\n\n\n**Prompt:** \"Describe a way to design impact resistant materials\"\n\n**Iterations:** 100+\n\n![Large Knowledge Graph](images/LargeGraph.thumb.png)[Large version of image](images/LargeGraph.png)\n\n## 🔧 Technical Architecture\n\nThe system consists of several key components:\n\n1.  **Reasoning Service**: Generates detailed reasoning traces about a given topic using a configured language model.\n2.  **Knowledge Extractor Service**: Converts unstructured reasoning into graph-structured data (entities and relationships) based on a defined prompt.\n3.  **Graph Population Service**: Handles Neo4j database operations, including creating nodes and relationships, and manages potential conflicts.\n4.  **Embedding Service**: Provides vector embeddings for entities, enabling similarity searches and conflict resolution.\n5.  **Conflict Resolution Service**: Resolves conflicts between existing and new entities using an LLM.\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Python 3.8+\n- Docker and Docker Compose (for Neo4j and pgvector)\n- Access to OpenAI API or a compatible LLM API endpoint (e.g., Ollama).\n- A running PostgreSQL instance with the `pgvector` extension enabled.\n- Access to a local LLM API endpoint (e.g., Ollama) is recommended for faster iteration, especially for the reasoning and embedding models.\n\n### Installation\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/yourusername/agentic-deep-graph-reasoning.git\ncd agentic-deep-graph-reasoning\n```\n\n2. Install dependencies:\n```bash\npip install -r requirements.txt\n```\n\n3. Start Neo4j and pgvector using Docker Compose:\n```bash\ndocker-compose up -d\n```\n\n4.  **Set up PostgreSQL with pgvector:**\n\n    *   If you don't have a PostgreSQL instance, you can use Docker:\n\n        ```bash\n        docker-compose up -d postgres\n        ```\n\n    *   Connect to the PostgreSQL instance (e.g., using `psql`):\n\n        ```bash\n        psql -h localhost -P54321 -U postgres -d postgres\n        ```\n\n    *   Create the `pgvector` extension:\n\n        ```sql\n        CREATE EXTENSION vector;\n        ```\n\n### Configuration\n\n1. Copy the example environment file:\n```bash\ncp .env.example .env\n```\n\n2. Configure your environment variables in `.env`:\n\n```env\n# Neo4j Configuration\nNEO4J_URI=bolt://localhost:7687\nNEO4J_USER=neo4j\nNEO4J_PASSWORD=testtest\n\n# Reasoning Model Configuration\nREASONING_MODEL_CONFIG='{\"model_name\": \"openthinker:7b-q8_0\", \"api_key\": \"dummy\", \"base_url\": \"http://localhost:11434/v1/\", \"prefix_message\": \"\"}'\n\n# Entity Extraction Model Configuration\nENTITY_EXTRACTION_MODEL_CONFIG='{\"model_name\": \"gpt-4o-mini\", \"api_key\": \"sk---\", \"base_url\": \"https://api.openai.com/v1/\", \"prefix_message\": \"\"}'\n\n# Embedding Model Configuration\nEMBEDDING_MODEL_CONFIG='{\"model_name\": \"granite-embedding:30m-en-fp16\", \"api_key\": \"dummy\", \"base_url\": \"http://localhost:11434/v1/\", \"prefix_message\": \"\"}'\n\n# Conflict Resolution Model Configuration\nCONFLICT_RESOLUTION_MODEL_CONFIG='{\"model_name\": \"gpt-4o-mini\", \"api_key\": \"sk---\", \"base_url\": \"https://api.openai.com/v1/\", \"prefix_message\": \"\"}'\n\n# Reasoning Tag Configuration.  These tags are used to extract the reasoning trace from the LLM output.\n# For deepscaler models:\n#THINK_TAGS=\"[\\\"\u003cthink\u003e\\\",\\\"\u003c/think\u003e\\\"]\"\n# For openthinker models:\nTHINK_TAGS=\"[\\\"\u003c|begin_of_thought|\u003e\\\",\\\"\u003c|end_of_thought|\u003e\\\"]\"\n\n# PgVector Configuration\nPGVECTOR_DBNAME=postgres\nPGVECTOR_USER=postgres\nPGVECTOR_PASSWORD=postgres\nPGVECTOR_HOST=localhost\nPGVECTOR_PORT=54321\nPGVECTOR_TABLE_NAME=entity_embeddings\nPGVECTOR_VECTOR_DIMENSION=1536  # optional\n```\n\n#### Model Configuration Options\n\n- For OpenAI models:\n  - `base_url`: \"https://api.openai.com/v1/\"\n  - `model_name`: \"gpt-4\", \"gpt-3.5-turbo\", \"gpt-4o-mini\", etc.\n  - `api_key`: Your OpenAI API key.\n  - `prefix_message`: Optional message to prepend to the prompt.\n\n- For local models (e.g., Ollama):\n  - `base_url`: \"http://localhost:11434/v1/\"\n  - `model_name`: The name of the model you have pulled from Ollama (e.g., \"llama2\", \"mistral\", \"openthinker:7b-q8_0\", \"granite-embedding:30m-en-fp16\", etc.).\n  - `api_key`:  A dummy value like \"dummy\" can be used.\n  - `prefix_message`: Optional message to prepend to the prompt.\n\n**Important notes on model configuration:**\n\n*   The `REASONING_MODEL_CONFIG`, `ENTITY_EXTRACTION_MODEL_CONFIG`, and `CONFLICT_RESOLUTION_MODEL_CONFIG` settings define which models are used for reasoning, entity extraction, and conflict resolution, respectively. You can use different models for these tasks.\n*   The `EMBEDDING_MODEL_CONFIG` specifies the model used for generating text embeddings.\n*   Different models may require different reasoning tag formats. Ensure that the `THINK_TAGS` setting is correctly configured to match the output format of your reasoning model. Refer to the model's documentation for the correct tags. Some example configurations are provided in the `.env.example` file.\n*   The `prefix_message` field in the model configurations allows you to prepend a message to the prompt. This can be useful for models that require a specific prefix to function correctly.\n\n### Reasoning Trace Format\n\nThis implementation expects the reasoning model to output its reasoning within the tags specified in the `THINK_TAGS` environment variable. This format is particularly suited for models that are trained to provide structured reasoning traces.\n\nExample expected output for `openthinker:7b-q8_0`:\n```\n\u003c|begin_of_thought|\u003e\nOkay, so I need to figure out the ...\nNow, thinking about ...\n\u003c|end_of_thought|\u003e\n```\n\nWhen using custom models or different LLM providers, ensure they:\n1.  Always wrap reasoning in the configured tags.\n2.  Provide structured, step-by-step reasoning.\n3.  End the reasoning trace with the closing tag.\n\nThe system uses these tags to properly parse and process the reasoning trace for knowledge extraction. If your model doesn't natively support this format, you may need to modify the system prompt or post-process the output.\n\n### Running the Application\n\nRun the knowledge graph generation with:\n```bash\npython src/application.py \"Your initial prompt\" \u003cnumber-of-iterations\u003e\n```\n\nExample:\n```bash\npython src/application.py \"Describe a way to design impact resistant materials\" 3\n```\n\n## 📖 Example Prompts\n\n- \"Describe a way to design impact resistant materials\"\n- \"Describe the role and stance of Sweden during World War II\"\n- \"Explain how photosynthesis works in plants\"\n\n## ⚙️ Utilities\n\nThe `utilities` directory contains helpful scripts:\n\n*   `extract_to_dot.py`: Exports the knowledge graph from Neo4j to a `.dot` file for visualization using Graphviz.\n*   `re_embed_pgvector.py`: Re-embeds all entities in the pgvector database.  Useful after changing the embedding model.\n\n## 🎯 Core Innovation\n\nUnlike traditional knowledge graph systems, this implementation follows an agentic approach where the system:\n\n- Autonomously determines what knowledge to expand.\n- Maintains contextual awareness across iterations.\n- Structures knowledge organically through reasoning.\n\n## 🔍 Monitoring and Debugging\n\n- Check Neo4j browser interface at `http://localhost:7474`\n- View logging output in real-time during execution in the console.\n- Monitor entity and relationship creation in the console output.\n- Examine the generated knowledge graph in Neo4j to verify the accuracy and completeness of the extracted information.\n- Monitor pgvector database for embeddings.\n\n## 🤝 Contributing\n\nContributions are welcome!\n\n## 📚 Citation\n\nIf you use this implementation in your research, please cite the original paper:\n\n```bibtex\n@article{deepgraphreasoning2025,\n  title={Agentic Deep Graph Reasoning},\n  author={[Markus J. Buehler]},\n  journal={arXiv preprint arXiv:2502.13025},\n  year={2025}\n}\n```\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrorigo%2Fagentic-deep-graph-reasoning","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrorigo%2Fagentic-deep-graph-reasoning","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrorigo%2Fagentic-deep-graph-reasoning/lists"}