IMPACT: Intent-based Multi-agent Platform for Architectural Change Tracking

IMPACT is a language-agnostic multi-agent framework designed to monitor and manage the structural evolution of software systems. Drawing inspiration from Intent-Based Networking (IBN) in autonomic computing, IMPACT enables human software architects to specify high-level structural intents, such as preventing cyclic dependencies or limiting complexity growth. A swarm of cooperative agents then evaluates codebase transitions, detects violations, and provides explainable, natural-language refactoring advice.

This project is built to align with the paradigm of Human-AI Collaboration, establishing a structured feedback loop where human expertise guides agentic analysis and governance.

Repository Structure

The repository is organized as follows:

core/: The core Python package of the IMPACT framework:
- schema/: Standardized JSON schema for software dependency graphs.
- agents/: Specialized agent implementations including the Coordinator, Graph, Diff, Metrics, and LLM agents.
- graph_utils.py: Utility functions for loading graphs and computing structural diffs.
- run_demo.py: Execution script to run the multi-agent evolution tracker.
- run_dashboard.py: Launch script for the architect dashboard.
adapters/: Pluggable source code extraction layers:
- java/: Python-based parser that walks Java project directories, extracts FQCNs, resolves dependency call-graphs, and exports JSON graphs.
test_projects/: Datasets and source folders simulating software evolution:
- telemetry_service_v1/: Version 1.0.0 Java source code of TelemetryService.
- telemetry_service_v2/: Version 2.0.0 Java source code of TelemetryService.
- v1_graph.json: Extracted dependency graph for Version 1.0.0.
- v2_graph.json: Extracted dependency graph for Version 2.0.0.
tests/: Automated test suite containing unit tests, crawler verifications, and architectural regression checks:
- test_crawler.py: Verifies crawler functionality, rate-limiting, and SQLite queue transitions.
- test_db_migration.py: Simulates database schema migrations.
- test_extractor.py: Unit tests for Java AST extraction and regex fallback parser.
- test_impact.py: Verifies graph loading, diff calculations, and coordinator orchestration.
- test_regression.py: Verifies end-to-end extraction, cycle detection, and SHACL schema validation logic.

Installation & Setup

IMPACT targets Python 3.8 or higher. The package (impact-core) is published to PyPI. You can install it directly or from source.

Install from source (recommended while in active development)

On modern Linux/macOS distributions (under PEP 668), Python environments are externally managed. It is recommended to install the package inside a virtual environment:

# 1. Clone the repository
git clone https://github.com/IMPACT-Project/IMPACT.git
cd IMPACT

# 2. Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows, run: .venv\Scripts\activate

# 3. Install in editable mode with development dependencies
pip install -e ".[dev]"

Or install only what you need:

pip install -e .                        # core only
pip install -e ".[java]"               # + Java AST extractor
pip install -e ".[crawler]"            # + full crawler stack (SQLite)
pip install -e ".[crawler-distributed]" # + PostgreSQL distributed crawler
pip install -e ".[all]"               # everything

Install from PyPI

# Core stack — graph loading, diff, coordinator, W3C SHACL (rdflib + pyshacl) validator
pip install impact-core

# + Java AST extractor (recommended for local extraction)
pip install impact-core[java]

# + Full crawler stack (javalang, SQLite queue)
pip install impact-core[crawler]

# + Distributed crawler (PostgreSQL backend)
pip install impact-core[crawler-distributed]

# Everything
pip install impact-core[all]

Releasing a new version to PyPI

git tag v1.x.y && git push origin v1.x.y   # GitHub Actions does the rest

See DEPLOY.md for the full release workflow, one-time PyPI Trusted Publisher setup, Docker, and Kubernetes deployment instructions.

Console scripts

After installation the following commands are available on your PATH:

Command	Description
`impact-crawl`	GitHub ecosystem crawler CLI
`impact-export`	Export crawled repositories from queue to CSV (or `.graph` files via `-g`)
`impact-export-graphs`	Bulk-export crawled JSON graphs from queue to human-readable `.graph` files
`impact-extract`	Java AST dependency graph extractor (generates both `.json` and `.graph`)
`impact-demo`	Run the built-in TelemetryService evolution demo
`impact-dashboard`	Launch the interactive architect dashboard

Running the Project

Running Graph Extraction (Java Adapter)

To support both computational and publishing needs, IMPACT exports graphs in two formats:

.json: The primary computational representation, containing rich metadata, class-level metrics (LOC, complexity, fan-in, fan-out, coupling, depth), and ontology context. Used for SHACL validation and agent-based reasoning.
.graph: A clean, human-readable topological software network file containing class/module node types and dependency edges (calls, inheritance, imports), matching the paper's description.

Direct extraction automatically generates both formats (writing a .graph file alongside the target .json file):

# Via installed console script (after pip install impact-core[java])
impact-extract <projectName> <version> <srcDirectory> <outputJsonPath>

# Or directly
python3 adapters/java/extractor.py <projectName> <version> <srcDirectory> <outputJsonPath>

For example, to extract graphs for the mock TelemetryService project:

impact-extract TelemetryService 1.0.0 test_projects/telemetry_service_v1/src test_projects/v1_graph.json
impact-extract TelemetryService 2.0.0 test_projects/telemetry_service_v2/src test_projects/v2_graph.json

This generates the JSON files (v1_graph.json, v2_graph.json) along with their human-readable counterparts (v1_graph.graph, v2_graph.graph).

Running the Demo

# Via installed console script
impact-demo

# Or directly
python3 -m core.run_demo

This runs the Coordinator agent, orchestrates the swarm, evaluates intents against the graph diffs, and generates the compliance report.

Running the Architect Dashboard (UI)

# Via installed console script
impact-dashboard

# Or directly
python3 -m core.run_dashboard

This starts a local development server and automatically opens the dashboard interface at http://localhost:8080/index.html. In the dashboard, you can visually explore the dependency graphs (with cycles highlighted in red), add new intents, trigger evolution analyses, and view tabular diff metrics.

Dashboard LLM Analysis API Server

The architect dashboard includes a double-click conformance report feature on every crawl success message. The 📊 Metrics tab (instant, local) is always available. The 🤖 LLM Analysis tab is powered by the IMPACT API server, which starts automatically alongside the dashboard — no separate command needed.

When you run impact-dashboard (or python3 -m core.run_dashboard) you will see:

Starting IMPACT Architect Dashboard...
[LLM API]   Serving on http://localhost:7842/api/llm-analysis
[Dashboard] Serving on http://localhost:8080/index.html
[Browser]   Opening http://localhost:8080/index.html

Both servers stop together when you press Ctrl+C.

Configuring GitHub API Rate Limits

To crawl public GitHub repositories live via the dashboard queue, unauthenticated API requests are capped at 60 requests per hour. To raise this limit to 5,000 requests per hour, you can configure a GitHub Personal Access Token.

For detailed step-by-step instructions on how to generate and configure this token, please refer to the GitHub Personal Access Token Setup Guide. The dashboard and crawler servers automatically load this .env file on startup and use the token to authenticate outgoing API requests.

The server uses whichever LLM backend is configured via environment variable (see LLM / AI Configuration below). Without any key set, it falls back to the built-in rule-based LLMAgent analyser — useful offline.

Running Unit Tests

python3 -m unittest discover -s tests -p "test_*.py"

Running the Model Context Protocol (MCP) Server

To run the stdio-compliant Model Context Protocol server:

python3 -m core.mcp_server

This starts the server on stdio. Any MCP-compatible client (such as Claude Desktop) can connect to it and invoke the run_evolution_analysis and extract_java_graph tools.

Running PMD Static Analysis Merger

To integrate PMD static analysis reports into the extracted dependency graph, run:

python3 adapters/java/static_analyzer.py <graphJsonPath> <pmdJsonPath>

For example, to merge our mock PMD report into the Version 2 graph:

python3 adapters/java/static_analyzer.py test_projects/v2_graph.json test_projects/pmd_report_v2.json

Running the SHACL Structural Validator

To validate your JSON-LD software graphs against our SHACL structural shapes, execute:

python3 core/shacl_validator.py <graphJsonPath>

How It Works

Codebase Extraction: Pluggable language adapters parse a codebase and export its structural dependency network and metrics conforming to the standardized JSON schema.
Orchestration: The Coordinator agent manages the evaluation loop.
Graph Analysis: The Graph agent loads the JSON-LD files, and the Metrics agent calculates network centralities to identify coupling hubs.
Version Comparison: The Diff agent compares adjacent versions to discover added, removed, or modified nodes and edges, as well as newly introduced cycles.
Intent Conformance: The LLM agent evaluates the diff metrics against the user-specified architectural intents, outputting a compliance report and refactoring recommendations.

LLM / AI Configuration

The LLMAgent (used by both the CLI coordinator and the dashboard API server) supports three LLM backends, selected automatically based on which environment variables are present. Priority order:

Priority	Variable	Backend
1	`LLM_API_URL` + (optionally) `OPENAI_API_KEY`	Any OpenAI-compatible endpoint (Ollama, vLLM, LM Studio, Azure OpenAI, …)
2	`OPENAI_API_KEY`	OpenAI API (`gpt-4o-mini` by default, override with `LLM_MODEL`)
3	`GEMINI_API_KEY`	Google Gemini Developer API (`gemini-1.5-flash`)
—	(none set)	Built-in rule-based fallback — no external calls, works offline

Quick setup

# Option A — Google Gemini (free tier available)
export GEMINI_API_KEY="AIza..."

# Option B — OpenAI
export OPENAI_API_KEY="sk-..."
export LLM_MODEL="gpt-4o"          # optional, default: gpt-4o-mini

# Option C — Local model via Ollama (or any OpenAI-compatible server)
export LLM_API_URL="http://localhost:11434/v1/chat/completions"
export LLM_MODEL="llama3"

# Then simply start the dashboard (the API server launches automatically)
impact-dashboard

To make the variables permanent, add them to your shell profile (~/.bashrc, ~/.zshrc) or a .env file (already in .gitignore).

Security note: Never commit API keys to version control. The .gitignore already excludes .env.

Distributed Ecosystem Crawler

IMPACT ships a GitHub ecosystem crawler that discovers, downloads, and analyses large numbers of open-source projects at scale. It can run as a single local process (backed by SQLite) or as a distributed multi-node cluster (backed by PostgreSQL).

Key Features

Multi-Language Support: The discovery command can filter for any repository language (e.g., --language java or --language rust).
Query Partitioning: To bypass GitHub's search query limit (max 1,000 results per search), the crawler automatically slices queries into sliding star intervals (e.g. 500..550, 551..600, etc., up to >50000). This allows building a much larger queue of repositories. Disable via --no-partition.
Robust Rate-Limit & Backoff: The crawler dynamically intercepts GitHub's rate-limiting mechanisms. It respects Retry-After headers (for secondary/abuse limits), sleeps for primary rate-limit resets (X-RateLimit-Reset), and falls back to exponential backoff (2s up to 60s) on HTTP 403/429 codes if headers are missing.
Resumability & Fault Tolerance: If a crawler run is interrupted or crashes, it can be resumed safely. Completed tasks are skipped, and any repository left in the processing state without a heartbeat update for more than 30 minutes is automatically reclaimed and reset to pending to be retried.

Database Configuration

By default, the crawler queue is stored in a local SQLite database in the workspace at: test_projects/github_benchmarks/crawler_queue.db

You can override this database path or switch to PostgreSQL for distributed environments by setting the IMPACT_DB_PATH environment variable:

SQLite: export IMPACT_DB_PATH="/path/to/custom_queue.db"
PostgreSQL: export IMPACT_DB_PATH="postgresql://user:pass@host:port/dbname"

Running Locally (SQLite, single process)

The crawler operates as a two-step producer-consumer workflow:

Discovery (Producer): Queries the GitHub search API once to find matching repositories and populate the local SQLite queue.
Crawl (Consumer): Downloads, parses, and analyzes the queued repositories. By default, it runs in unlimited mode (processing all pending repositories in the queue). You can optionally pass a --limit (e.g., --limit 50) to cap the number of processed repositories. This stage can be run repeatedly or split across multiple parallel workers.

# 1. Discover and populate the queue (run this ONCE first)
python3 -m core.ecosystem_crawler discover --language java --min-stars 1000
# Or: impact-crawl discover --language java --min-stars 1000

# 2. Process the queued repositories (runs the analysis loop; defaults to unlimited)
# (Automatically extracts and saves graphs in both .json and .graph formats)
python3 -m core.ecosystem_crawler crawl
# Or: impact-crawl crawl

# 3. Check the queue status and progress
python3 -m core.ecosystem_crawler status
# Or: impact-crawl status

# 4. Export completed crawled repositories to CSV (can be run in parallel)
python3 -m core.export_crawled --output crawled_repos.csv
# Or: impact-export --output crawled_repos.csv

# 5. Bulk-export/regenerate human-readable .graph files for all crawled repositories
python3 -m core.export_crawled --graphs
# Or: impact-export-graphs (or: impact-export --graphs)

The CSV export command (python3 -m core.export_crawled) automatically ensures the database schema is up-to-date, retroactively harvests any missing metrics, paths, and reports for already-completed crawls on disk, and exports the following enriched details for each repository:

Basic info: Owner, repo name, star count, and language.
Git release tags: Evolution endpoints (tag1 -> tag2).
Timestamps: Processed timestamp and precise extraction start and end/completion timestamps.
Codebase sizes: Total Lines of Code (LOC) and class count for both $V_1$ and $V_2$ versions.
SHACL validation flags: Conformance checks (conforms_v1 and conforms_v2).
Structural diff metrics: Counts of added/removed classes (nodes), added/removed dependencies (edges), and newly introduced or broken dependency cycles.
LLM analysis & coupling metrics:
- top_hubs: Top coupled class/package hubs in $V_2$.
- coupling_anomalies: Outlier coupling anomalies with corresponding Z-scores.
- intent_status: Overall classification ("CONFORMING" or "VIOLATION").
- report_content: The full natural-language architectural evolution report.
Local file paths: Relative paths to graph_v1_path, graph_v2_path, and report_path.

Running with Docker (single node)

Build the crawler image:

docker build -t impact-crawler:latest .

Run discovery then crawl with a local SQLite database:

docker run --rm \
  -v "$(pwd)/test_projects:/app/test_projects" \
  impact-crawler:latest discover --language java --min-stars 1000

docker run --rm \
  -v "$(pwd)/test_projects:/app/test_projects" \
  impact-crawler:latest crawl --limit 50

To use a GitHub token (recommended to avoid rate limits):

docker run --rm \
  -e GITHUB_TOKEN=ghp_yourtoken \
  -v "$(pwd)/test_projects:/app/test_projects" \
  impact-crawler:latest discover --language java --min-stars 1000

Running on Kubernetes (multi-node distributed)

The k8s/ directory contains all Kubernetes manifests. Multiple crawler worker pods coordinate on a shared PostgreSQL queue using SELECT FOR UPDATE SKIP LOCKED — each pod atomically claims a repository and no two pods process the same one.

Prerequisites

A running Kubernetes cluster (local: minikube or kind)
kubectl configured to point at it
The impact-crawler:latest image built and available in the cluster

Step 1 — Create the namespace

kubectl apply -f k8s/namespace.yaml

Step 2 — Create the database secret (not committed to git)

# Option A: imperative (nothing touches disk — recommended)
kubectl create secret generic postgres-secret \
  --from-literal=username=impact \
  --from-literal=password=yourpassword \
  -n impact-crawler

# Option B: file-based (stays local, already gitignored)
cp k8s/secret.yaml.example k8s/secret.yaml
# Edit k8s/secret.yaml — replace REPLACE_WITH_BASE64_* with real values:
#   echo -n 'impact' | base64
#   echo -n 'yourpassword' | base64
kubectl apply -f k8s/secret.yaml

Security note: k8s/secret.yaml is listed in .gitignore and must never be committed. Only k8s/secret.yaml.example (with placeholder values) is tracked in git.

Step 3 — Deploy PostgreSQL and configuration

kubectl apply -f k8s/configmap.yaml
kubectl apply -f k8s/postgres.yaml

# Wait for PostgreSQL to be ready
kubectl wait --for=condition=ready pod -l app=postgres \
  -n impact-crawler --timeout=60s

Step 4 — Run the discovery Job (populates the queue)

kubectl apply -f k8s/discovery-job.yaml
kubectl wait --for=condition=complete job/crawler-discovery \
  -n impact-crawler --timeout=300s

Step 5 — Start the distributed crawler workers

kubectl apply -f k8s/crawler-deployment.yaml

This starts 4 parallel worker pods by default. Watch them drain the queue:

kubectl logs -l role=worker -n impact-crawler --follow

Scaling workers up or down

kubectl scale deployment crawler-worker --replicas=8 -n impact-crawler

Applying everything at once (after the secret exists)

kubectl apply -k k8s/

Removing the deployment

kubectl delete namespace impact-crawler

Name		Name	Last commit message	Last commit date
Latest commit History 78 Commits
.github		.github
adapters/java		adapters/java
core		core
docs		docs
k8s		k8s
statistics		statistics
test_projects		test_projects
tests		tests
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

IMPACT: Intent-based Multi-agent Platform for Architectural Change Tracking

Repository Structure

Installation & Setup

Install from source (recommended while in active development)

Install from PyPI

Releasing a new version to PyPI

Console scripts

Running the Project

Running Graph Extraction (Java Adapter)

Running the Demo

Running the Architect Dashboard (UI)

Dashboard LLM Analysis API Server

Configuring GitHub API Rate Limits

Running Unit Tests

Running the Model Context Protocol (MCP) Server

Running PMD Static Analysis Merger

Running the SHACL Structural Validator

How It Works

LLM / AI Configuration

Quick setup

Distributed Ecosystem Crawler

Key Features

Database Configuration

Running Locally (SQLite, single process)

Running with Docker (single node)

Running on Kubernetes (multi-node distributed)

Prerequisites

Step 1 — Create the namespace

Step 2 — Create the database secret (not committed to git)

Step 3 — Deploy PostgreSQL and configuration

Step 4 — Run the discovery Job (populates the queue)

Step 5 — Start the distributed crawler workers

Scaling workers up or down

Applying everything at once (after the secret exists)

Removing the deployment

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages