DepsRAG

KO | EN

gitlite — search

#javascript #typescript #go #golang #android #machine-learning #macos #awesome #pytorch #security #ios #mcp #openai #open-source

(★ 34)

Interactive LLM Chatbot that constructs direct and transitive software dependencies as a knowledge graph and answers user's questions leveraging RAG and critic-agent approach

DepsRAG 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# DepsRAG (Agno Version)

## Overview

`DepsRAG` is an AI-powered chatbot that answers questions about software dependencies by representing them as a Knowledge Graph (KG) using Neo4j. It uses a multi-agent system powered by Agno to provide comprehensive, validated answers.

### Key Features

- 🗂️ **Dependency Graph Construction**: Build complete dependency trees (direct & transitive) as Neo4j knowledge graphs
- 🌐 **Multi-Ecosystem Support**: PyPI, NPM, Cargo, and Go packages
- 🔗 **Cross-Dependency Graph Assembly**: Recursively collect dependency data across ecosystems, enrich all collected package nodes with artifact/native-module metadata across supported ecosystems, then upload the assembled graph to Neo4j in one write operation
- 🤖 **Multi-Agent System**: Specialized agents for different tasks
- 🔍 **Automatic Query Generation**: Natural language to Cypher query translation
- 🔒 **Security Analysis**: Integration with OSV vulnerability database
- 🌍 **Web Search Integration**: DuckDuckGo search for additional information
- ✅ **Answer Validation**: Critic agent for quality assurance

## Architecture

DepsRAG uses a **multi-agent system** with the following specialized agents:

### 1. **Team Coordinator** (Agno Team)
- Orchestrates the end-to-end workflow
- Delegates package/graph tasks to DependencyGraphAgent
- Delegates web/security tasks to SearchAgent
- Synthesizes member outputs into one response
- Delegates to CriticAgent for validation before final delivery

### 2. **DependencyGraphAgent**
- Builds dependency graphs using the deps.dev API
- Assembles the full dependency graph in memory first, including cross-ecosystem dependencies
- Enriches collected graph nodes with artifact/native-module metadata (PyPI, NPM, Cargo, and Go)
- Uploads nodes and relationships to Neo4j in one atomic write query
- Translates natural language to Cypher queries
- Executes queries on the Neo4j knowledge graph
- Provides graph visualization capabilities

**Tools:**
- `construct_dependency_graph`: Build the KG for a package
- `execute_cypher_query`: Query the Neo4j database
- `get_graph_schema`: Get database structure info
- `visualize_dependency_graph`: Create HTML visualizations

### 3. **SearchAgent**
- Performs web searches using DuckDuckGo
- Checks security vulnerabilities using OSV database
- Provides package information and documentation links

**Tools:**
- `web_search`: Search the web for information
- `check_vulnerability`: Query OSV vulnerability database

### 4. **CriticAgent**
- Validates responses synthesized by the Team coordinator
- Provides feedback on reasoning and completeness
- Ensures high-quality, accurate answers

## Workflow

```
1. User provides package info (name, version, ecosystem)
   ↓
2. Team Coordinator → DependencyGraphAgent: Build dependency graph
  - Recursively collect dependencies from deps.dev (including cross-ecosystem links)
  - Enhance collected package metadata (for example, native modules across supported ecosystems)
  - Upload assembled graph to Neo4j in one write operation
   ↓
3. User asks questions about dependencies
   ↓
4. Team Coordinator breaks down complex questions
   ↓
5. Team Coordinator delegates:
   - DependencyGraphAgent: Graph queries
   - SearchAgent: Web search / vulnerability checks
   ↓
6. Team Coordinator aggregates member outputs
   ↓
7. CriticAgent validates and provides feedback
   ↓
8. Final answer returned to user
```

## Native Dependency Identification Approach

DepsRAG identifies native dependencies as an artifact-analysis step layered on top of dependency graph collection.

### 1. Collect package graph first
- Recursively fetch package dependencies from deps.dev.
- Normalize each package node with identity `(ecosystem, name, version)`.
- Build a full in-memory graph snapshot (package nodes + package-package edges) before upload.

### 2. Analyze package artifacts per node
- For each collected package node, download the package artifact from its ecosystem registry.
- Extract artifact contents in a temporary workspace.
- Scan extracted files for native indicators using ecosystem-aware extensions:
  - PyPI: `.c`, `.cpp`, `.dylib`, `.dll`, `.so*`
  - npm: `.c`, `.cc`, `.cpp`, `.h`, `.node`, `.dylib`, `.dll`, `.so*`
  - cargo: `.c`, `.cc`, `.cpp`, `.h`, `.a`, `.dylib`, `.dll`, `.so*`
  - go: `.c`, `.cc`, `.cpp`, `.h`, `.syso`, `.a`, `.dylib`, `.dll`, `.so*`
- Attach per-package metadata:
  - `main_package_size`
  - `total_size`
  - `native_modules` (deduplicated basenames)

### 3. Safety and resilience
- HTTP calls use retry/backoff for transient failures.
- Archive extraction validates member paths before extraction to prevent path traversal.
- Artifact analysis is best-effort per package node: failures on one node do not block the whole graph.

### 4. One-shot graph upload
- Upload package nodes, package-package edges, and package-native edges in one atomic Cypher write.
- This keeps graph state consistent and avoids partial ingestion.

## Current Graph Schema

DepsRAG currently stores graph data with two node labels and one relationship type.

### Node Labels

1. `Package`
- Identity key: `(name, version, ecosystem)`
- Main properties:
  - `name`: package name
  - `version`: package version
  - `ecosystem`: package ecosystem (for example `pypi`, `npm`, `cargo`, `go`)
  - `package_name`: duplicated canonical name field
  - `package_version`: duplicated canonical version field
  - `root`: whether this is the requested root package
  - `native_modules`: list of detected native module filenames
  - `main_package_size`: downloaded artifact size
  - `total_size`: total downloaded size during artifact analysis
  - `error`: optional error from dependency/artifact processing

2. `Native`
- Identity key: `(package_name, package_version, package_ecosystem, module)`
- Main properties:
  - `name`: native module filename
  - `module`: native module filename
  - `package_name`: owning package name
  - `package_version`: owning package version
  - `package_ecosystem`: owning package ecosystem
  - `ecosystem`: fixed value `native`
  - `is_native_module`: fixed value `true`

### Relationship Types

1. `DEPENDS_ON`
- `(:Package)-[:DEPENDS_ON]->(:Package)` for package dependencies from deps.dev
- `(:Package)-[:DEPENDS_ON]->(:Native)` for detected native modules
- Relationship property:
  - `requirement`: version/constraint when available (empty string for Package->Native edges)

## Installation

### Requirements

- **Python**: 3.11 or higher
- **Neo4j**: Cloud account or local instance
- **LLM Provider** (choose one):
  - **OpenAI** API Key
  - **Azure OpenAI** credentials
  - **Google Gemini** API Key

### Setup

1. **Clone the repository:**
```bash
git clone https://github.com/Mohannadcse/DepsRAG.git
cd DepsRAG
```

2. **Install dependencies:**
```bash
# Using poetry (recommended)
poetry install

# Or using pip
pip install -e .
```

3. **Set up Neo4j (choose one):**

**Option A: Neo4j Aura (cloud)**
  - Create a free account at [neo4j.com](https://neo4j.com/cloud/platform/aura-graph-database/)
  - Note your URI, username, and password

**Option B: Local Neo4j with Docker**
  - Start a local Neo4j instance:

```bash
docker run -d \
  --name depsrag-neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password \
  -e NEO4J_PLUGINS='["apoc"]' \
  -e NEO4J_dbms_security_procedures_unrestricted=apoc.* \
  -v neo4j_data:/data \
  neo4j:5
```

- Open the Neo4j Browser at http://localhost:7474
  - Use the following credentials:
    - URI: bolt://localhost:7687
    - Username: neo4j
    - Password: password

4. **Configure environment variables:**
```bash
cp .env-template .env
# Edit .env with your credentials
```

Required environment variables:
```bash
# Option 1: OpenAI
OPENAI_API_KEY=your_openai_api_key

# Option 2: Azure OpenAI
AZURE_OPENAI_API_KEY=your_azure_key
AZURE_OPENAI_ENDPOINT=https://your-endpoint.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT=gpt-4o

# Option 3: Google Gemini
GOOGLE_API_KEY=your_google_api_key
GOOGLE_MODEL_ID=gemini-2.0-flash  # Optional, defaults to gemini-2.0-flash-exp

# Neo4j (required for all options)
NEO4J_URI=neo4j+s://your-instance.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_password
NEO4J_DATABASE=neo4j
```

**Note:** If `--provider` is not specified, the system auto-detects in this order:
1. Azure OpenAI (if `AZURE_OPENAI_API_KEY` is set)
2. Google Gemini (if `GOOGLE_API_KEY` is set)
3. OpenAI (default fallback)

5. **Install optional dependencies:**
```bash
# For web search functionality
pip install duckduckgo-search
```

## Usage

### Command Line Interface

**Basic usage (auto-detects provider from environment):**
```bash
python dependencyrag/main.py
```

**With specific provider:**
```bash
# Using Google Gemini
python dependencyrag/main.py --provider google --model gemini-2.0-flash

# Using Azure OpenAI
python dependencyrag/main.py --provider azure --model gpt-4o

# Using OpenAI
python dependencyrag/main.py --provider openai --model gpt-4o
```

**Available options:**
- `--provider`: LLM provider (`openai`, `azure`, `google`). Auto-detects if not specified
- `--model`: Model ID to use (default: gpt-4o)
- `--db-file`: SQLite database file (default: depsrag.db)
- `--debug`: Enable debug mode
- `--no-stream`: Disable streaming responses

### Example Session

```
You: Please analyze chainlit version 1.1.200 from PyPI

DepsRAG (Team Coordinator): I'll help you analyze chainlit 1.1.200. Let me start by 
constructing the dependency graph...

[DependencyGraphAgent constructs the graph]

DepsRAG (Team Coordinator): The dependency graph has been created! What would you like 
to know about the dependencies?

You: What are the direct dependencies?

DepsRAG (Team Coordinator): Let me query the graph for direct dependencies...

[Returns list of direct dependencies]

You: Are there any known vulnerabilities in this version?

DepsRAG (Team Coordinator): Let me check the OSV vulnerability database...

[SearchAgent checks for vulnerabilities]

DepsRAG (Team Coordinator): I found the following security information...
```

### Programmatic Usage

```python
from dependencyrag import create_depsrag_team

# Create the team (auto-detects provider from environment)
team = create_depsrag_team(
    model_id="gpt-4o",
    db_file="my_analysis.db"
)

# Or specify a provider explicitly
team = create_depsrag_team(
    model_id="gemini-2.0-flash",
    provider="google",  # "openai", "azure", or "google"
    db_file="my_analysis.db"
)

# Run a query
response = team.run(
    "Analyze the dependencies for requests version 2.31.0 from PyPI"
)

print(response.content)

# Ask follow-up questions
response2 = team.run("What are the direct dependencies?")
print(response2.content)
```

## Example Questions

After constructing a dependency graph, you can ask:

- **Graph structure:**
  - "What's the depth of the dependency graph?"
  - "How many total packages are in the graph?"
  - "What are the direct dependencies?"

- **Specific packages:**
  - "Is there a dependency on pytorch? Which version?"
  - "What's the path between package-1 and package-2?"
  - "Which packages depend on numpy?"

- **Analysis:**
  - "Which packages have the most dependencies relying on them?"
  - "Tell me 3 interesting things about this dependency graph"
  - "What are the leaf nodes in the graph?"

- **Security:**
  - "Are there any known vulnerabilities in this package?"
  - "Check all dependencies for security issues"

- **General info:**
  - "What's the latest version of this package?"
  - "Can I upgrade any dependencies?"

## Testing

Run the test suite:

```bash
# Run Neo4j tools integration tests
python tests/test_neo4j_tools.py

# Run integration tests
python tests/test_integration.py

# Or use pytest
pytest tests/ -v
```

Current integration coverage in `tests/test_neo4j_tools.py` includes:
- Successful/failed graph construction checks
- Case-sensitivity and query execution checks
- Cross-language enrichment check (`Package -> Native` edges)
- Multi-ecosystem graph construction checks (NPM, Cargo, Go)
- Cargo native persistence check after fresh root rebuild

Run the example script:

```bash
python examples/basic_example.py

# Cross-ecosystem smoke check (graph + native nodes)
python examples/ecosystem_smoke_check.py
```

## Project Structure

```
DepsRAG/
├── dependencyrag/
│   ├── __init__.py              # Package initialization
│   ├── main.py                  # CLI entry point
│   ├── agno_agents.py           # Agent definitions
│   ├── agno_tools.py            # Tool definitions
│   ├── depsrag_team.py          # Team orchestration
│   ├── neo4j_tools.py           # Neo4j utilities
│   └── cypher_message.py        # Cypher query templates
├── tests/
│   ├── test_neo4j_tools.py      # Neo4j tools integration tests
│   ├── test_integration.py      # Integration tests
│   └── README.md                # Test documentation
├── examples/
│   └── basic_example.py         # Usage example
│   └── ecosystem_smoke_check.py # Cross-ecosystem smoke validation
├── docs/                        # Documentation assets
├── .env-template                # Environment template
├── pyproject.toml               # Dependencies
└── README.md                    # This file
```

## Troubleshooting

### Neo4j Connection Issues
- Verify your Neo4j credentials in `.env`
- Check that your Neo4j instance is running
- Ensure you're using the correct URI format

### API Key Issues
- Verify your API key is valid for your chosen provider (OpenAI, Azure, or Google)
- Check that you have sufficient API credits/quota
- Ensure the key is properly set in `.env`
- For Azure: verify endpoint URL and deployment name are correct
- For Google: check that you haven't exceeded free tier limits

### Package Installation Issues
- Use Python 3.11 or higher
- Install with `pip install -e .` for development mode
- Try `poetry install` if pip fails

### Ecosystem Availability Notes
- DepsRAG supports graph and native analysis for PyPI, NPM, Cargo, and Go.
- End-to-end Go graph construction depends on deps.dev returning metadata for the selected module/version.
- If deps.dev returns 404 for Go, use a different module/version candidate or run artifact-only native checks.

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see LICENSE file for details

## Citation

If you use DepsRAG in your research, please cite:

```bibtex
@software{depsrag2024,
  title={DepsRAG: Dependency Analysis with RAG and Multi-Agent Systems},
  author={Mohannad Alhanahnah},
  year={2024},
  url={https://github.com/Mohannadcse/DepsRAG}
}
```

## Acknowledgments

- Original DepsRAG implementation using Langroid
- [Agno](https://github.com/agno-agi/agno) multi-agent framework
- [deps.dev](https://deps.dev/) API for dependency data
- [OSV](https://osv.dev/) vulnerability database
- Neo4j graph database

## Contact

- **Author**: Mohannad Alhanahnah
- **Email**: mohannad.alhanahnah@gmail.com
- **GitHub**: [@Mohannadcse](https://github.com/Mohannadcse)

DepsRAG

DepsRAG 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

DepsRAG

DepsRAG 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README