Skip to content

About

CARA: Contract-Aware Refactoring Agent for Distributed Systems

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

11 Commits

Folders and files

Repository files navigation

CARA: Contract-Aware Refactoring Agent

Paper: "CARA: A Contract-Aware Refactoring Agent for Distributed Systems with Client-Exposed Data Models"

CARA is a ReAct-style LLM agent that treats schema migration and API contract evolution as a unified refactoring lifecycle. When a data model changes, CARA simultaneously analyzes both the storage layer (SQL/Protobuf schemas) and the interface layer (REST/gRPC API specs) to produce a zero-downtime expand-contract migration plan with generated adapter code.

Quick Start

pip install -r requirements.txt
python examples/demo_field_rename.py

Run Evaluation

# No API key required (deterministic direct runner)
python run_eval.py --provider direct                         # all cases
python run_eval.py --provider direct --cases case_01 case_07 # specific cases
python run_eval.py --provider direct --language kotlin        # Kotlin adapters
python run_eval.py --provider direct --output results.json    # save to file

# With a local Ollama model (no API key required)
# Install Ollama from https://ollama.com, then: ollama pull llama3.2
python run_eval.py --provider ollama

# With Claude via Anthropic API
export ANTHROPIC_API_KEY=<your-key>
python run_eval.py

Project Structure

cara-research/
├── agent/
│   ├── cara_agent.py       # ReAct agent + tool dispatch
│   └── prompts.py          # System prompt
├── tools/
│   ├── schema_diff.py      # SQL/Protobuf/JSON Schema diffing
│   ├── api_diff.py         # OpenAPI/Protobuf/GraphQL diffing
│   ├── consumer_tracer.py  # Cross-codebase consumer tracing
│   ├── change_classifier.py # SAFE/BACKWARD_COMPATIBLE/BREAKING
│   ├── plan_generator.py   # Expand-contract plan generation
│   ├── code_generator.py   # Adapter code generation
│   └── plan_validator.py   # Plan completeness scoring
├── eval/
│   ├── dataset/            # 15 annotated test cases
│   ├── runner.py           # Evaluation harness
│   └── metrics.py          # Precision/recall/F1 + plan metrics
├── paper/
│   ├── main.tex            # arXiv paper (LaTeX)
│   └── references.bib
└── examples/
    └── demo_field_rename.py

Key Results

Results on the 515-case benchmark (5-run mean; std = 0.000):

Metric CARA Rule-only LLM-only
Breaking Change F1 0.86 0.77 0.59
Plan Completeness 0.97 N/A 0.41
Expand-Contract Compliance 1.00 N/A 0.33
Adapter Generation Rate 0.97 N/A 0.00
Overall Pass Rate 0.88 0.47 0.20

Compile Paper

cd paper
pdflatex main.tex
bibtex main
pdflatex main.tex && pdflatex main.tex

About

CARA: Contract-Aware Refactoring Agent for Distributed Systems

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages