# aicodegraph

**Repository Path**: alexjunqi/aicodegraph

## Basic Information

- **Project Name**: aicodegraph
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-14
- **Last Updated**: 2026-05-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Code Graph Analyzer

A comprehensive Python application that analyzes GitHub repositories containing Python code, extracts structural information, stores it in a GraphQL database using a GraphQL MCP Server, and provides visualization and reporting capabilities with AI-powered insights.

## Features

- 🔍 **Repository Analysis**: Clone and analyze Python repositories from GitHub
- 🌳 **Code Structure Extraction**: Parse Python files using AST to extract classes, functions, imports, variables, and relationships
- 🤖 **AI-Powered Analysis**: Use OpenAI-compatible APIs (LM Studio) for intelligent code analysis and insights
- 🔧 **Environment Variable Detection**: Automatically detect and track environmental variable usage
- 📊 **GraphQL Database**: Store analysis results in a GraphQL database with full CRUD operations
- 🛠️ **MCP Tools**: Model Context Protocol tools for AI agents to interact with the GraphQL database
- 🧹 **Dead Code Detection**: Identify unused/dead code, dangling imports, and unreferenced variables with AI assistance
- 📈 **Interactive Visualization**: Web-based visualizer for exploring code graphs and relationships using GraphViz
- 📝 **Comprehensive Reporting**: Generate detailed reports with AI-enhanced insights and recommendations
- 🚀 **FastAPI GraphQL Server**: Modern, async GraphQL API for data access
- 💻 **CLI Interface**: Powerful command-line interface with flexible configuration options
- ⚙️ **Environment Configuration**: Support for `.env` files with runtime configuration loading

## Recent Updates

### January 2025
- ✅ **Fixed GraphQL Client**: Resolved KeyError issues with safe `.get()` operations
- ✅ **Environment Configuration**: Added `python-dotenv` support with runtime loading
- ✅ **Test Organization**: Reorganized tests into unit/integration/manual categories
- ✅ **Integration Tests**: Added 13+ automated GraphQL integration tests
- ✅ **Project Structure**: Moved visualizer to `src/aicodegraph/templates/`
- ✅ **Documentation**: Comprehensive test and configuration documentation
- ✅ **Git Ignore**: Updated with project-specific patterns
- 📊 **Test Coverage**: 30+ automated tests (14 unit + 13 integration + 3 e2e)

## Architecture

```
aicodegraph/
├── src/aicodegraph/          # Main application code
│   ├── templates/            # HTML templates (visualizer)
│   ├── cli.py               # Command-line interface
│   ├── analysis_engine.py   # Analysis orchestration
│   ├── parser.py            # AST-based code parser
│   ├── repository.py        # GitHub repository access
│   ├── graphql_server.py    # FastAPI GraphQL server
│   ├── graphql_client.py    # GraphQL client for data access
│   ├── graphql_schema.py    # GraphQL schema definition
│   ├── data_mapper.py       # Data mapping to GraphQL
│   ├── ai_analysis.py       # AI-powered code analysis
│   ├── openai_client.py     # OpenAI API client
│   ├── visualizer.py        # GraphViz visualization
│   ├── mcp_tools.py         # Model Context Protocol tools
│   └── models.py            # Pydantic data models
├── tests/                    # Test suite
│   ├── unit/                # Unit tests (14 tests)
│   ├── integration/         # Integration tests (13+ tests)
│   ├── manual/              # Manual test scripts
│   └── test_integration.py  # End-to-end tests (3 tests)
├── docs/                     # Documentation
│   ├── tasks/               # Task breakdown files
│   └── plan.md              # Project plan
├── logs/                     # Application logs
├── reports/                  # Generated reports
└── temp/                     # Temporary files

Total: 30+ automated tests
```

### Key Components

- **Repository Access** (`repository.py`): Handles GitHub repository cloning and file enumeration
- **Code Parser** (`parser.py`): Uses Python's AST module to extract code structure
- **GraphQL Server** (`graphql_server.py`): FastAPI server with Graphene for GraphQL API
- **GraphQL Client** (`graphql_client.py`): Client for querying and mutating GraphQL data
- **Data Mapper** (`data_mapper.py`): Maps parsed data to GraphQL mutations
- **Analysis Engine** (`analysis_engine.py`): Orchestrates the entire analysis workflow
- **AI Analysis** (`ai_analysis.py`): AI-powered code analysis and insights
- **Visualizer** (`visualizer.py`): Creates GraphViz diagrams and interactive HTML views
- **CLI** (`cli.py`): Command-line interface with environment configuration support

## Requirements

- **Python 3.14+** (Required)
- **Poetry** (for dependency management)
- **Git** (for repository cloning)
- **GraphViz** (for visualization - `brew install graphviz` on macOS)
- **LM Studio** (for AI analysis) - optional but highly recommended

### Optional AI Models

For best results with AI analysis, we recommend:
- `qwen/qwen3-coder-30b` - Fast, efficient coding model
- `bytedance/seed-oss-36b` - High-quality code analysis
- Any OpenAI-compatible model through LM Studio

## AI Setup

The application includes AI-powered analysis capabilities using OpenAI-compatible APIs. We recommend using [LM Studio](https://lmstudio.ai/) for local AI analysis:

1. **Install LM Studio**
2. **Download the qwen/qwen3-code-30b model**
3. **Start the local server** on port 1234
4. **Configure the application** (see Configuration section)

The AI features provide:
- Intelligent code analysis and explanations
- Code improvement suggestions
- Issue detection and recommendations
- Enhanced reporting with AI insights

## Quick Start

### 🚀 Automated Setup (Recommended)

The `setup.sh` script will automatically:
- Install dependencies
- Create necessary directories
- Generate `.env` configuration
- Run tests
- Start both GraphQL and HTTP servers
- Display usage instructions

```bash
# Clone the repository
git clone <repository-url>
cd aicodegraph

# Run the automated setup script
./setup.sh
```

This will start:
- **GraphQL Server**: http://localhost:8000/graphql
- **Visualizer**: http://localhost:8080/visualizer.html

### ⚡ Quick Analysis (One Command)

Use the `analyze_and_report.sh` script for one-command analysis and reporting:

```bash
# Analyze and generate AI-powered report in one step
./analyze_and_report.sh https://github.com/psf/requests

# Or set TARGET_REPOSITORY in .env and run without arguments
echo 'TARGET_REPOSITORY=https://github.com/psf/requests' >> .env
./analyze_and_report.sh
```

This script will:
- ✅ Start GraphQL server if needed
- ✅ Analyze the repository
- ✅ Generate AI-powered report
- ✅ Save report to `reports/` directory

See `docs/ANALYZE_AND_REPORT_SCRIPT.md` for detailed documentation.

### 🛠️ Manual Setup

```bash
# Install dependencies
poetry install

# Run tests
poetry run pytest tests/ -v

# Start the GraphQL server (in background)
poetry run aicodegraph server &

# Analyze a repository
poetry run aicodegraph analyze https://github.com/psf/requests

# Generate a report with AI analysis
poetry run aicodegraph report https://github.com/psf/requests --ai

# View results in the visualizer
# 1. Start HTTP server for visualizer
cd src/aicodegraph/templates
python3 -m http.server 8080 &

# 2. Open browser
open http://localhost:8080/visualizer.html
```

## Usage

### Command Line Interface

The application provides a comprehensive CLI with the following commands:

#### Start GraphQL Server
```bash
poetry run aicodegraph server [--host HOST] [--port PORT] [--reload]
```

#### Analyze Repository
```bash
poetry run aicodegraph analyze REPO_URL [--branch BRANCH] [--temp-dir DIR]
```

#### Generate Report
```bash
poetry run aicodegraph report REPO_URL [--output FILE] [--ai/--no-ai]
```

#### Get Summary
```bash
poetry run aicodegraph summary REPO_URL
```

#### Detect Unused Code
```bash
poetry run aicodegraph unused REPO_URL
```

### AI Configuration Options

The CLI supports flexible AI configuration through command-line options or `.env` file:

```bash
# Use custom OpenAI-compatible API endpoint
poetry run aicodegraph --openai-url http://localhost:1234 analyze REPO_URL

# Use different AI model
poetry run aicodegraph --openai-model bytedance/seed-oss-36b analyze REPO_URL

# Combine multiple options
poetry run aicodegraph \
  --openai-url http://localhost:1234 \
  --openai-model qwen/qwen3-coder-30b \
  analyze REPO_URL

# Generate report with AI analysis
poetry run aicodegraph report REPO_URL --ai

# Generate basic report without AI
poetry run aicodegraph report REPO_URL --no-ai
```

**Configuration Priority**: CLI arguments > `.env` variables > hardcoded defaults

### GraphQL API

The GraphQL server provides endpoints for:

- **Query**: Retrieve stored analysis data
- **Mutation**: Store new analysis data

Example GraphQL query:
```graphql
query GetRepository {
  repositories {
    id
    url
    name
    branch
  }
}
```

### Python API

You can also use the analysis engine programmatically:

```python
from aicodegraph.analysis_engine import AnalysisEngine

engine = AnalysisEngine()
analysis = engine.analyze_repository("https://github.com/user/repo")

# Generate report
report = engine.generate_report("https://github.com/user/repo")

# Get summary
summary = engine.get_analysis_summary("https://github.com/user/repo")
```

## Configuration

### Environment Variables

The application uses `.env` files for configuration with runtime loading support. Create a `.env` file in the project root:

```env
# GraphQL Server Configuration
GRAPHQL_ENDPOINT=http://localhost:8000/graphql
GRAPHQL_HOST=localhost
GRAPHQL_PORT=8000

# OpenAI-compatible API Configuration (LM Studio)
OPENAI_BASE_URL=http://127.0.0.1:1234
OPENAI_MODEL=qwen/qwen3-coder-30b
# Or use: bytedance/seed-oss-36b for better analysis
OPENAI_API_KEY=not-needed-for-lm-studio

# Logging Configuration
LOG_LEVEL=INFO

# Temporary Directory
TEMP_DIR=./temp
```

**To change the AI model:**
1. Load the new model in LM Studio
2. Update `OPENAI_MODEL` in `.env`
3. Restart services (or no restart needed - changes load at runtime!)

**Note**: The `setup.sh` script automatically creates a `.env` file with default values if one doesn't exist.

### Poetry Dependencies

The application uses Poetry for dependency management. Key dependencies include:

**Core Dependencies:**
- `fastapi` - Modern async web framework
- `uvicorn` - ASGI server for FastAPI
- `graphene` - GraphQL implementation
- `gitpython` - Git repository access
- `graphviz` - Graph visualization
- `pydantic` - Data validation and settings
- `click` - CLI framework
- `requests` - HTTP client for AI API
- `python-dotenv` - Environment variable management

**Development Dependencies:**
- `pytest` - Testing framework
- `pytest-cov` - Coverage reporting
- `black` - Code formatter
- `isort` - Import organizer
- `flake8` - Code linter
- `mypy` - Static type checker

Install all dependencies with:
```bash
poetry install
```

## Development

### Running Tests

The test suite is organized into unit tests, integration tests, and manual test scripts.

```bash
# Run all automated tests (30+ tests)
poetry run pytest tests/

# Run only unit tests (fast, no dependencies)
poetry run pytest tests/unit/

# Run integration tests (requires GraphQL server)
poetry run aicodegraph server &  # Start server first
poetry run pytest tests/integration/ -m integration

# Run with coverage
poetry run pytest tests/ --cov=src/aicodegraph --cov-report=html

# View coverage report
open htmlcov/index.html

# Run specific test file
poetry run pytest tests/unit/test_parser.py -v

# Run tests matching a pattern
poetry run pytest tests/ -k "test_parse"
```

**Test Organization:**
- `tests/unit/` - Unit tests (14 tests) - No external dependencies
- `tests/integration/` - Integration tests (13+ tests) - Requires live GraphQL server
- `tests/manual/` - Manual test scripts - For development/verification
- `tests/test_integration.py` - End-to-end tests (3 tests) - Full workflow tests

See `tests/README.md` for comprehensive testing documentation.

### Code Quality

```bash
# Format code
poetry run black src/

# Sort imports
poetry run isort src/

# Lint code
poetry run flake8 src/

# Type checking
poetry run mypy src/
```

### Adding New Features

1. Create a new module in `src/aicodegraph/`
2. Add tests in `tests/`
3. Update the CLI if needed
4. Update this README

## GraphQL Schema

The GraphQL schema includes types for:

- **Repository**: GitHub repository information
- **File**: Source code files
- **Class**: Python classes
- **Function**: Python functions and methods
- **Import**: Import statements
- **Variable**: Global variables
- **Relationship**: Relationships between code elements

## Visualization

### Interactive Web Visualizer

The application includes a comprehensive web-based visualizer at `src/aicodegraph/templates/visualizer.html`:

**Features:**
- 📊 Repository overview with statistics
- 📁 File structure visualization
- 🔗 Class and function relationship graphs
- 🧹 Dead code analysis viewer
- 📦 Import dependency visualization
- 🔍 Interactive GraphQL queries

**Access the visualizer:**
```bash
# Via setup script (automatic)
./setup.sh
# Then open: http://localhost:8080/visualizer.html

# Or manually
cd src/aicodegraph/templates
python3 -m http.server 8080
# Then open: http://localhost:8080/visualizer.html
```

### Programmatic Visualization

Generate GraphViz diagrams programmatically:

```python
from aicodegraph.visualizer import CodeVisualizer
from aicodegraph.graphql_client import GraphQLClient

client = GraphQLClient()
visualizer = CodeVisualizer(client)

# Generate repository graph (PNG)
visualizer.create_repository_graph("https://github.com/psf/requests")

# Generate class hierarchy diagram
visualizer.create_class_hierarchy("https://github.com/psf/requests")
```

**Output formats:** PNG, SVG, PDF (via GraphViz)

## Docker Support

The application can be containerized with Docker:

```dockerfile
FROM python:3.14-slim

WORKDIR /app
COPY pyproject.toml poetry.lock ./
RUN pip install poetry && poetry install --no-dev

COPY src/ ./src/
EXPOSE 8000

CMD ["poetry", "run", "aicodegraph", "server"]
```

## Project Structure

```
aicodegraph/
├── .env                      # Environment configuration (create from setup.sh)
├── .gitignore               # Git ignore patterns
├── pyproject.toml           # Poetry configuration
├── setup.sh                 # Automated setup script
├── README.md                # This file
│
├── src/aicodegraph/         # Main application code
│   ├── __init__.py
│   ├── cli.py               # Command-line interface
│   ├── analysis_engine.py   # Analysis orchestration
│   ├── parser.py            # AST-based code parser
│   ├── repository.py        # GitHub repository access
│   ├── graphql_server.py    # FastAPI GraphQL server
│   ├── graphql_client.py    # GraphQL client
│   ├── graphql_schema.py    # GraphQL schema
│   ├── data_mapper.py       # Data mapping
│   ├── ai_analysis.py       # AI-powered analysis
│   ├── openai_client.py     # OpenAI API client
│   ├── visualizer.py        # GraphViz visualization
│   ├── mcp_tools.py         # MCP tools
│   ├── models.py            # Data models
│   └── templates/           # HTML templates
│       ├── README.md        # Template documentation
│       └── visualizer.html  # Interactive visualizer
│
├── tests/                   # Test suite (30+ tests)
│   ├── README.md            # Test documentation
│   ├── conftest.py          # Shared fixtures
│   ├── test_all.py          # Unified test runner
│   ├── test_integration.py  # End-to-end tests
│   ├── unit/                # Unit tests
│   │   ├── test_parser.py
│   │   └── test_repository.py
│   ├── integration/         # Integration tests
│   │   ├── README.md
│   │   └── test_graphql_server.py
│   └── manual/              # Manual test scripts
│       ├── README.md
│       ├── test_config.py
│       ├── test_graphql.py
│       ├── test_openai.py
│       └── test_visualize.py
│
├── docs/                    # Documentation
│   ├── plan.md              # Project plan
│   ├── tasks/               # Task breakdown
│   ├── ENV_CONFIG_FIX.md    # Config documentation
│   └── VISUALIZER_RELOCATION.md
│
├── logs/                    # Application logs (generated)
├── reports/                 # Generated reports (generated)
└── temp/                    # Temporary files (generated)
```

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes following the coding standards
4. Add tests for new functionality
5. Run tests: `poetry run pytest tests/`
6. Format code: `poetry run black src/` and `poetry run isort src/`
7. Commit your changes (`git commit -m 'Add amazing feature'`)
8. Push to the branch (`git push origin feature/amazing-feature`)
9. Open a Pull Request

### Coding Standards

- Follow PEP 8 style guide
- Use type hints
- Write docstrings for all functions/classes
- Maintain >80% test coverage
- Use black for formatting
- Use isort for import organization

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Troubleshooting

### GraphQL Server Not Starting
```bash
# Check if port 8000 is already in use
lsof -i :8000

# Kill existing process
kill -9 <PID>

# Restart server
poetry run aicodegraph server
```

### LM Studio Connection Issues
```bash
# Verify LM Studio server is running
curl http://127.0.0.1:1234/v1/models

# Check your .env configuration
cat .env | grep OPENAI

# Test configuration
poetry run python tests/manual/test_config.py
```

### Environment Configuration Not Loading
```bash
# Verify .env file exists
ls -la .env

# Test configuration loading
poetry run python tests/manual/test_config.py

# Check for syntax errors in .env
cat .env
```

### Tests Failing
```bash
# Run tests with verbose output
poetry run pytest tests/ -v

# Check for specific errors
poetry run pytest tests/unit/test_parser.py -v

# View test coverage
poetry run pytest tests/ --cov=src/aicodegraph --cov-report=term-missing
```

## Documentation

- **Project Plan**: `docs/plan.md` - Overall project structure and goals
- **Task Breakdown**: `docs/tasks/` - Detailed task documentation
- **Test Documentation**: `tests/README.md` - Comprehensive testing guide
- **Environment Config**: `docs/ENV_CONFIG_FIX.md` - Configuration management
- **Visualizer**: `src/aicodegraph/templates/README.md` - Visualizer usage

## Future Enhancements

- [x] ✅ GraphQL database integration
- [x] ✅ AI-powered code analysis
- [x] ✅ Dead code detection
- [x] ✅ Interactive web visualizer
- [x] ✅ Environment configuration support
- [x] ✅ Comprehensive test suite (30+ tests)
- [ ] 🔄 Web-based UI for repository management
- [ ] 🔄 Integration with CI/CD pipelines (GitHub Actions)
- [ ] 🔄 Support for additional programming languages (JavaScript, TypeScript)
- [ ] 🔄 Advanced code quality metrics and complexity analysis
- [ ] 🔄 Real-time analysis updates via WebSocket
- [ ] 🔄 Plugin system for custom analyzers
- [ ] 🔄 Docker containerization
- [ ] 🔄 Multi-repository comparison and analysis
- [ ] 🔄 Code evolution tracking over time
- [ ] 🔄 Integration with issue trackers (GitHub Issues, Jira)