Metadata-Version: 2.4
Name: graph-dependency-analyzer
Version: 2.0.1
Summary: Knowledge Graph for multi-language repository dependency analysis — Java, TypeScript, Python, Groovy, SQL/Oracle
Author: Graph Project Team
License: MIT
Project-URL: Homepage, https://github.com/ciandt/new-arch-explorer-service
Project-URL: Repository, https://github.com/ciandt/new-arch-explorer-service
Project-URL: Issues, https://github.com/ciandt/new-arch-explorer-service/issues
Keywords: dependency-analysis,knowledge-graph,tree-sitter,neo4j,qdrant,architecture,impact-analysis,java,typescript,python,groovy,oracle
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn>=0.32.0
Requires-Dist: qdrant-client>=1.13.0
Requires-Dist: neo4j>=5.15.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: structlog>=24.1.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: dependency-injector>=4.41.0
Requires-Dist: tenacity>=8.2.0
Requires-Dist: tree-sitter>=0.25.2
Requires-Dist: tree-sitter-java>=0.23.5
Requires-Dist: tree-sitter-typescript>=0.23.2
Requires-Dist: tree-sitter-c-sharp>=0.23.0
Requires-Dist: lxml>=5.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: click>=8.1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: ruff>=0.9.0; extra == "dev"

# Knowledge Graph Dependency Analyzer

Analyze dependencies across all your repositories — Java, TypeScript, Python, Groovy, SQL/Oracle — and visualize cross-repo connections in an interactive graph.

[![PyPI](https://img.shields.io/pypi/v/graph-dependency-analyzer)](https://pypi.org/project/graph-dependency-analyzer/)
[![Python](https://img.shields.io/badge/python-3.11+-blue)](https://python.org)

---

## What it does

- **Indexes** source code from multiple repositories (Java, TypeScript/JavaScript, Python, Groovy, SQL/Oracle)
- **Extracts** classes, methods, endpoints, imports, DB tables, procedures, pipeline stages
- **Connects** cross-repo dependencies: frontend → backend HTTP calls, procedures → tables, shared libraries
- **Visualizes** everything in an interactive graph with drill-down per repository
- **Answers** business questions: *"what is impacted if I change this endpoint?"* via `/graph-impact`

---

## Requirements

Before installing, make sure you have:

| Dependency | Install |
|-----------|---------|
| **Python 3.11+** | [python.org](https://python.org) |
| **Docker Desktop** | [docs.docker.com/get-docker](https://docs.docker.com/get-docker/) |
| **Ollama** (optional) | `brew install ollama` or [ollama.com/download](https://ollama.com/download) |

> **Note:** Docker is required to run Neo4j and Qdrant locally.
> Ollama is recommended for local embeddings (no API key, no rate limits).

---

## Installation

```bash
pip install graph-dependency-analyzer
```

Or install from source:

```bash
git clone https://github.com/ciandt/new-arch-explorer-service.git
cd new-arch-explorer-service
pip install -e .
```

---

## Quick Start

Run these commands **in order** the first time:

```bash
# 1. Create docker-compose.yml (Neo4j + Qdrant + Redis)
graph-explorer docker-init

# 2. Create .env.graph configuration file
graph-explorer env-init
#    → Edit .env.graph: set REPOSITORIES_PATH and EMBEDDING_PROVIDER

# 3. Install Ollama + embedding model (local, free)
graph-explorer ollama-setup

# 4. Install Claude Code skills (/graph-index, /graph-link, /graph-impact)
graph-explorer skills

# 5. Run the full setup wizard
graph-explorer init

# 6. Start the API server
graph-explorer start
#    → API running at http://localhost:8000

# 7. Index your repositories
graph-explorer index repo1 repo2 repo3

# 8. Connect cross-repo dependencies
graph-explorer link

# 9. Open the graph in browser
graph-explorer open
```

---

## CLI Reference

### `graph-explorer env-init`

Creates a `.env.graph` configuration file in the current directory.

```bash
graph-explorer env-init                    # creates .env.graph in current dir
graph-explorer env-init --path ~/myproject # creates in specific path
graph-explorer env-init --force            # overwrite existing
```

**Required settings to edit after creation:**

```bash
REPOSITORIES_PATH=/absolute/path/to/your/repos   # ← required
EMBEDDING_PROVIDER=ollama                          # or: flow / openai
```

---

### `graph-explorer docker-init`

Creates `docker-compose.yml` with Neo4j, Qdrant and Redis.

```bash
graph-explorer docker-init                    # creates in current dir
graph-explorer docker-init --path ~/myproject # creates in specific path
graph-explorer docker-init --force            # overwrite existing
```

After creating, start the containers:

```bash
docker compose up -d
```

Services:
- **Neo4j** → http://localhost:7474 (user: `neo4j` / pass: `medline2024`)
- **Qdrant** → http://localhost:6333/dashboard
- **Redis** → localhost:6379

---

### `graph-explorer ollama-setup`

Installs Ollama and downloads the `nomic-embed-text` embedding model (274MB, 768-dim).

```bash
graph-explorer ollama-setup               # install Ollama + pull model
graph-explorer ollama-setup --skip-install  # only pull model (Ollama already installed)
```

Detects your OS and installs automatically:
- **Mac**: via Homebrew or direct download
- **Linux**: via official install script
- **Windows**: opens download page

---

### `graph-explorer ollama-start`

Starts the Ollama server in the background.

```bash
graph-explorer ollama-start               # start in background (default)
graph-explorer ollama-start --background  # explicit background
```

---

### `graph-explorer skills`

Installs `/graph-index`, `/graph-link` and `/graph-impact` commands into Claude Code.

```bash
graph-explorer skills                      # install globally (~/.claude/skills/)
graph-explorer skills --target ./myproject # install in specific project only
graph-explorer skills --list               # show installation status
graph-explorer skills --uninstall          # remove graph skills
```

After installing, use in Claude Code:

```
/graph-index wdc-packing-list wdc-ui       # index repos
/graph-link                                 # connect dependencies
/graph-impact quero criar tela de usuario  # business impact analysis
```

---

### `graph-explorer init`

Guided setup wizard — checks all dependencies and configures the project.

```bash
graph-explorer init                  # full wizard
graph-explorer init --skip-docker    # skip Docker setup
graph-explorer init --skip-ollama    # skip Ollama setup
```

Runs checks for: `.env.graph`, Docker containers, Ollama, Claude skills.

---

### `graph-explorer start`

Starts the API server (FastAPI + Uvicorn).

```bash
graph-explorer start                   # default: port 8000, auto-reload
graph-explorer start --port 9000       # custom port
graph-explorer start --no-reload       # disable auto-reload
```

Once running:
- **API docs**: http://localhost:8000/docs
- **Graph UI**: http://localhost:8000/api/analysis/repository-relationships/graph.html

---

### `graph-explorer index`

Indexes one or more repositories into the Knowledge Graph.

```bash
graph-explorer index wdc-packing-list wdc-ui wdc-ui-external
graph-explorer index wms-oracle --parallel 1   # use parallel=1 for large repos
graph-explorer index wmsportal --parallel 1    # wmsportal = 3k+ files
```

Auto-detects parallel limit:
- Large repos (`wmsportal`, `wms-oracle`, `wms-oracle-fork`) → `parallel: 1`
- All others → `parallel: 3`

Supported languages: **Java, TypeScript, JavaScript, Python, Groovy, SQL/Oracle**

---

### `graph-explorer link`

Connects cross-repository dependencies after indexing.

```bash
graph-explorer link            # run both linkers
graph-explorer link --http-only  # only connect HTTP calls (frontend→backend)
graph-explorer link --db-only    # only resolve DB refs (procedures→tables)
```

Runs two operations:
1. **cross-language-link** — matches `axios.get('/api/users')` → `@GetMapping("/api/users")`
2. **resolve-db-refs** — connects Oracle procedures/packages to their tables

---

### `graph-explorer status`

Shows the current state of all services and graph statistics.

```bash
graph-explorer status
```

Output example:
```
📊 Knowledge Graph Status

  ✅ API running
     ✅ qdrant: Vector database operational
     ✅ neo4j: Graph database operational
  ✅ Docker
  ✅ Ollama running
     ✅ nomic-embed-text installed

  📈 Graph: 131 repos | 89 relationships
```

---

### `graph-explorer open`

Opens the dependency graph in your browser.

```bash
graph-explorer open                          # open full repository map
graph-explorer open --repo wdc-packing-list  # open specific repo graph
```

---

## Embedding Provider Options

Edit `.env.graph` to choose your embedding provider:

### Option A — Ollama (recommended)
No API key, no rate limits, runs locally.

```bash
EMBEDDING_PROVIDER=ollama
OLLAMA_EMBEDDING_MODEL=nomic-embed-text
QDRANT_VECTOR_SIZE=768
```

Setup: `graph-explorer ollama-setup`

### Option B — CI&T Flow
Uses the CI&T Flow proxy.

```bash
EMBEDDING_PROVIDER=flow
OPENAI_API_KEY=your-flow-token
OPENAI_BASE_URL=https://flow.ciandt.com/ai-orchestration-api
QDRANT_VECTOR_SIZE=1536
```

### Option C — OpenAI
Direct OpenAI API.

```bash
EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-your-key
QDRANT_VECTOR_SIZE=1536
```

> ⚠️ **Changing provider** requires clearing Qdrant and re-indexing everything
> because vector dimensions differ between providers.

---

## Re-indexing

Re-indexing is safe — Neo4j uses `MERGE` so no duplicates are created.
Use it when you add new repos or update existing code:

```bash
graph-explorer index repo1 repo2
graph-explorer link
```

---

## Architecture

```
src/
├── domain/          entities, value objects, interfaces
├── application/     use cases, DTOs, services
├── infrastructure/  Neo4j, Qdrant, OpenAI/Ollama, parsers
│   └── parsing/     Java, TypeScript, Python, Groovy, SQL
├── presentation/    FastAPI routers
└── cli.py           graph-explorer CLI
```

**Stack:** Python 3.11 · FastAPI · Neo4j · Qdrant · Tree-sitter · Ollama · Click

---

## API Reference

Full API docs at: http://localhost:8000/docs

Key endpoints:

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/indexing/index/batch` | Index repositories |
| POST | `/api/analysis/impact/cross-language-link` | Link HTTP calls |
| POST | `/api/analysis/impact/resolve-db-refs` | Resolve DB references |
| POST | `/api/analysis/impact/search` | Semantic search |
| GET | `/api/analysis/repository-relationships` | Cross-repo relationships |
| GET | `/api/analysis/repository-relationships/graph.html` | Interactive graph |
| GET | `/api/export/graph.html?repository=X` | Repo internal graph |

---

## License

MIT
