Librarian

An LLM-Powered Tool for Fixing Dependency Upgrade Compatibility Issues

Librarian Logo

Make dependency upgrades painless and code fixing smarter.

Project Introduction

Librarian is a revolutionary AI-driven tool for automatically fixing compilation errors, specifically designed to solve the compatibility nightmare after dependency upgrades.

Core Philosophy: Combine advanced Large Language Model (LLM) technology with deep code analysis to achieve intelligent error diagnosis and automated fixes.

Technical Breakthrough: For the first time, we have deeply integrated the context of client-side compilation errors with the repair knowledge of dependency libraries, significantly improving the success rate of fixes.

The docs folder contains competition-related documentation.

Core Features

Feature	Capability
Intelligent Error Analysis	Deep AST Parsing + Semantic Understanding
AI-Driven Fixes	GPT + Context-Aware
Knowledge Base Support	Massive Dependency Library Knowledge Graph
Automated Workflow	One-Click Intelligent Fix
Visualized Results	Interactive Fix Reports

Applicable Scenarios

graph LR
    A[Enterprise Projects] --> B[Dependency Upgrade]
    C[CI/CD Pipelines] --> B
    D[Project Migration] --> B
    B --> E[Librarian Fix]
    E --> F[Perfectly Compatible]
    
    style E fill:#ff6b6b,stroke:#fff,color:#fff
    style F fill:#4caf50,stroke:#fff,color:#fff

Enterprise-level Maven Projects: Fixing compatibility issues for dependency version upgrades in large projects.
CI/CD Integration: Automated error handling and fixing in continuous integration pipelines.
Project Migration: Batch intelligent fixing of errors during large-scale project migrations.
Quality Assurance: Improving code quality and clearing technical debt.

Fix Result of `Librarian`

Librarian Logo

System Architecture

Core Module Details

Module	Description	Core Responsibilities	Tech Stack
librarian-cli-starter	Core Command-Line Entry	Parameter parsing & validation Automatic environment configuration Process orchestration	`Spring Boot3`
librarian-fix-engine	AI Fix Engine Core	Intelligent LLM calls Code generation optimization Fix strategy decision-making	`LLM` `Soot` `Eclipse JDT`
librarian-broken-api-analyzer	Broken API Intelligent Analyzer	Precise detection of broken APIs Usage pattern analysis Root cause localization	`Eclipse JDT`
librarian-ast-analyzer	AST Deep Analyzer	Intelligent extraction of compilation errors Deep parsing of AST structure Semantic context analysis	`Eclipse JDT`
librarian-maven-dependency-resolver	Dependency Resolver	Maven dependency tree construction Version conflict detection Dependency tree management	`Maven API`
librarian-code-diff-viewer	Visual Diff Viewer	Visualization of fix results HTML report generation Interactive code comparison	`Velocity` `Code Diff`
librarian-common	Core Utility Library	Encapsulation of common utility classes Unified configuration management Constant and enum definitions	`Hutool`
librarian-library-knowledge-collector	Knowledge Base Builder	Automatic download of library JARs	`JAR Analysis`

Architectural Advantages: Modular design, loosely coupled architecture, supports plug-in extensions. Each module can be independently tested and deployed, ensuring high system availability and maintainability.

Intelligent Workflow

graph TD
    A[Client Project] --> B[Compilation Error Analysis]
    B --> C[Broken API Detection]
    C --> D[Knowledge Base Query]
    D --> E[LLM Fix Generation]
    E --> F[Apply Code]
    F --> G[Result Report]
    
    %% Feedback Loop
    G -.->|Fix Failed| E
    G -.->|New Errors Found| B
    G -.->|New Issues Detected| C
    
    %% Style Definitions
    classDef inputNode fill:#e1f5fe,stroke:#01579b,stroke-width:3px,color:#000,font-weight:bold
    classDef processNode fill:#f3e5f5,stroke:#4a148c,stroke-width:3px,color:#000,font-weight:bold
    classDef aiNode fill:#fff3e0,stroke:#e65100,stroke-width:4px,color:#000,font-weight:bold
    classDef outputNode fill:#e8f5e8,stroke:#1b5e20,stroke-width:3px,color:#000,font-weight:bold
    classDef reportNode fill:#fce4ec,stroke:#880e4f,stroke-width:3px,color:#000,font-weight:bold
    
    %% Apply Styles
    class A inputNode
    class B,C,D processNode
    class E aiNode
    class F outputNode
    class G reportNode

Environment Requirements

Tool	Version Requirement	Description	Download Link
Java	`17+`	OpenJDK 17 LTS is recommended	Download Now
Apache Maven	`3.8.8+`	Project build and dependency management tool	Download Now
Jenv	`0.5.7+`	Java version management tool (optional)	Install Now

Quick Start with `Librarian`

This guide will explain how to configure and run `Librarian`

Overview

graph LR
    A[Step 1: Download Library Artifacts] --> B[Step 2: Configure Librarian]
    B --> C[Step 3: Build & Run]
    
    style A fill:#e8f5e8,stroke:#4caf50,stroke-width:3px,color:#000,font-weight:bold
    style B fill:#fff3e0,stroke:#ff9800,stroke-width:3px,color:#000,font-weight:bold
    style C fill:#e3f2fd,stroke:#2196f3,stroke-width:3px,color:#000,font-weight:bold

Step 1: Download Library Artifacts

Before running Librarian, you need to download the artifacts of the target libraries.

Download a Single Library

Call SingleLibraryKnowledgeCollector with the target library’s groupId and artifactId:

public static void main(String[] args) {
    SingleLibraryKnowledgeCollector collector = new SingleLibraryKnowledgeCollector("org.locationtech.jts", "jts-core");
    collector.collect();
    log.info("✅ Collect Finish");
}

Batch Download Libraries

Configure the Library List
List all target library artifacts in librarian-library-knowledge-collector/src/main/resources/library_list.json:
```
[
  {
    "group_id": "com.aliyun.openservices",
    "artifact_id": "aliyun-log-producer"
  }
  // ... add more as needed
]
```

Start Batch Download
Start the application to perform the batch download:

public static void main(String[] args) throws IOException {
    SpringApplication.run(LibraryKnowledgeApplication.class, args);
    server.start();
}

Configure Download Parameters
Configure the download parameters in librarian-library-knowledge-collector/src/main/resources/application.properties:

# Spring Boot application name
spring.application.name=library-knowledge-collector-server

# Library list file path (relative to classpath)
config.library-list-file-name=library_list.json

# Root directory for storing downloaded library artifacts
config.knowledge-root-path=/path/to/your/storage

# Number of concurrent download threads (adjust according to your environment)
config.collect-thread-number=80

Step 2: Configure `Librarian`

After downloading the library artifacts, configure the CLI in librarian-cli-starter/src/main/resources/application.properties:

Configuration Key	Description	Example
`library-database-path`	Root directory of library artifacts	`/path/to/your/library/database`
`fix-space-dir`	Output directory for fixes	`/path/to/your/fix/output`
`llm.api-key`	LLM API Key	`your-api-key`
`llm.base-url`	API Base URL	`https://api.example.com/v1`
`llm.model-name`	Model Name	`your-model-name`

# Root directory of the library artifacts downloaded in Step 1
config.library-database-path=/path/to/your/library/database

# Output directory for the fixed project
config.fix-space-dir=/path/to/your/fix/output

# Your LLM API Key
config.llm.api-key=your-api-key

# LLM API Base URL
config.llm.base-url=https://api.example.com/v1

# LLM Model Name
config.llm.model-name=your-model-name

Step 3: Build & Run `Librarian`

Build `Librarian`

bash build.bash  # Compile and package

Build Artifact Location: librarian-cli-starter/target/strange-cli-1.0-SNAPSHOT.jar

Run `Librarian`

java -jar strange-cli/target/strange-cli-1.0-SNAPSHOT.jar [-p [PROJECT_PATH]]

Parameter	Description	Details
`-p [PROJECT_PATH]`	Project Path	The path to the client project that needs incompatibility errors fixed

License

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

If Librarian is helpful to you, please give us a Star!

Thank you for your support!