Usage Guide

Installation

The Code Analysis Agent can be run either locally or via Docker.

Option 1: Local Installation (Recommended with uv)

  1. Create and activate a virtual environment:
uv venv .venv
source .venv/bin/activate
  1. Sync dependencies from pyproject.toml:
uv sync
  1. Create a .env file with your environment variables:
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_password
OPENAI_API_KEY=your_openai_key
  1. Start the Streamlit app:
streamlit run src/streamlit_app.py

Option 2: Docker Deployment

  1. Ensure Docker and Docker Compose are installed.

  2. Set environment variables as above.

  3. Set up virtual environment:

uv venv
uv sync --locked
  1. Build and start containers:
docker-compose up -d
  1. Access the app at http://localhost:8501.

Note: Requires a running Neo4j instance. Optimized for Python 3.10+.

Basic Usage

After launching the application:

  • Clone a Repository: Enter a GitHub repository URL and click “Clone Repository.”
  • Select Source Folders: Choose folders you want to analyze (e.g., src, backend/api, .).
  • Initialize the Database: Start the analysis pipeline to extract code structure and relationships.
  • Ask Questions: Use natural language queries to explore code relationships and architecture.
  • Visualize: Generate interactive graphs and downloadable diagrams of the codebase.

Example Queries

To ensure the agent provides an accurate response, the user must specify the exact locations of the nodes. Different prompts activate different pipelines within the agent. Below are example prompts, using a sample repository, to illustrate how to get the response you want.

  • Example Repository: https://github.com/psf/requests.git

  • Micro Agent with Text (GraphRAG + RAG): How is the Requests.Help.Requests_Version related to the Requests.Init module?

  • Micro Agent with Text (RAG): What does the Requests.Auth.Httpdigestauth class do?

  • Micro Agent with Visualization (GraphRAG): Give me a visualization of how the Requests.Exceptions module is related to the Requests.Api module.

  • Macro Agent: Give me a high-level overview of the codebase.

Demonstration

For a full demonstration of the system in action — including repository ingestion, graph construction, querying, and visualization — please watch our 5-minute demo video:

YouTube Demo:

The video covers:

  • Setting up the application
  • Cloning and analyzing a repository
  • Interacting with both the micro and macro agents
  • Viewing and downloading visualizations
  • Example natural language queries