### Instance Configuration File Example

Source: https://context7.com/jd-opensource/joycode-agent/llms.txt

An example of the 'instance_id.txt' file used to configure which SWE-bench instances the JoyCode agent should process. Each line specifies a single problem instance.

```text
# instance_id.txt - List of SWE-bench instances to process
django__django-11099
django__django-11234
matplotlib__matplotlib-23562
sympy__sympy-18189
scikit-learn__scikit-learn-13779
pytest-dev__pytest-5495
sphinx-doc__sphinx-8721
requests__requests-4718
flask__flask-4045
xarray__xarray-3364
```

--------------------------------

### Python: Docker Container Management for SWE-Bench

Source: https://context7.com/jd-opensource/joycode-agent/llms.txt

Manages the lifecycle of Docker containers for the SWE-bench project, including pulling images, starting containers with git initialization, and terminating them. It provides utilities to get the appropriate Docker image name for a given issue and configures the project workspace. The container automatically initializes a git repository, creates an initial commit, and adds a marker commit for diff generation.

```python
from utils.docker_utils import (
    configure_project_space,
    start_container,
    terminate_runtime_pod,
    get_issue_image_name,
    MAX_RUNTIME_PARALLELISM
)
from pathlib import Path
import threading

# Get the Docker image name for a specific problem
problem_id = "django__django-11099"
workspace = Path("/tmp/workspace/django")
image_name = get_issue_image_name(problem_id, workspace)
# Returns: "swebench/sweb.eval.x86_64.django_1776_django-11099:latest"

# Configure workspace and start container
lock = threading.Lock()
semaphore = threading.Semaphore(MAX_RUNTIME_PARALLELISM)  # Default: 8

env, container_id = configure_project_space(
    workspace=workspace,
    problem_id=problem_id,
    lock=lock,
    semaphore=semaphore
)

# env contains environment variables set for the workspace:
# - ISSUE_ID: problem_id
# - SWEBENCH_WORKSPACE: workspace path
# - PATH: updated with workspace python wrappers
# - PYTHONPATH: includes JoyCode root

print(f"Container started: {container_id}")
print(f"Environment: {env}")

# The container automatically:
# 1. Initializes git repository in /testbed
# 2. Creates initial commit with repository state
# 3. Adds marker commit for diff generation

# After work is complete, terminate container
terminate_runtime_pod(
    container_id=container_id,
    remove_image=""  # Optionally specify image name to remove
)
```

--------------------------------

### Install Dependencies with Pip

Source: https://github.com/jd-opensource/joycode-agent/blob/main/README.md

Installs the necessary Python dependencies for the JoyCode agent from a requirements file. Ensure you have Python 3.11+ and a conda environment activated.

```bash
conda activate joycode
pip install -r requirements.txt
```

--------------------------------

### Run JoyCode Agent in Batch Mode

Source: https://github.com/jd-opensource/joycode-agent/blob/main/README.md

Processes multiple software issue instances in batches, with a specified limit on the number of examples and parallel processes. This allows for efficient processing of multiple issues.

```bash
python run_patch_pipeline.py --num-examples 10 --num-processes 4
```

--------------------------------

### Initialize and Execute PatchEngine

Source: https://context7.com/jd-opensource/joycode-agent/llms.txt

Provides a programmatic interface to the PatchEngine class, demonstrating component initialization, task execution, and metric retrieval. This allows for fine-grained control over the patch generation process.

```python
from tools.patch_agent import PatchEngine
from llm_server.simple_client import create_simple_client
from utils.workspace_manager import ProjectSpaceHandler
from rich.console import Console
import logging

client = create_simple_client("patch_generation")
workspace_manager = ProjectSpaceHandler(root=Path("/tmp/workspace/project"), container_workspace="/testbed")
console = Console()
logger = logging.getLogger("patch_agent")
logger.setLevel(logging.INFO)

patch_engine = PatchEngine(
    llm_client=client,
    workspace_manager=workspace_manager,
    console=console,
    activity_logger=logger,
    max_response_tokens=32768,
    max_iterations=200,
    enable_token_budgeting=True,
    require_user_confirmation=False,
    container_id="docker_container_abc123",
    quiet_mode=False
)

result = patch_engine.execute_patch_generation(
    task_instruction="Fix the IndexError in the data processing module when handling empty arrays",
    resume_from_previous=False,
    context_guidance=None
)

metrics = patch_engine.get_execution_metrics()
phase = patch_engine.get_current_phase()
patch_engine.clear_engine_state()
```

--------------------------------

### Configure and Use SimpleLLMClient in Python

Source: https://context7.com/jd-opensource/joycode-agent/llms.txt

Demonstrates how to create and use the SimpleLLMClient for different LLM tasks such as patch generation, test generation, and trajectory compression. It shows how to configure the client with specific purposes, handle responses including tool calls, and extract token usage metadata. Dependencies include the llm_server library.

```python
from llm_server.simple_client import (
    create_simple_client,
    create_simple_client_for_purpose,
    extract_tool_calls_from_response
)
from llm_server.client_manager import ModelPurpose

# Create client for specific purposes
patch_client = create_simple_client("patch_generation")
test_client = create_simple_client("test_generation")
retry_client = create_simple_client("retry_agent")

# Using enum for type safety
from llm_server.client_manager import ModelPurpose
client = create_simple_client_for_purpose(ModelPurpose.TRAJECTORY_COMPRESSION)

# Generate a response with tools
messages = [
    {"role": "user", "content": "Analyze this code and find the bug"}
]

tools = [
    {
        "type": "function",
        "function": {
            "name": "read_file",
            "description": "Read contents of a file",
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {"type": "string", "description": "File path to read"}
                },
                "required": ["path"]
            }
        }
    }
]

response, metadata = patch_client.generate(
    messages=messages,
    max_tokens=8192,
    system_prompt="You are an expert code debugger.",
    temperature=0.1,  # None uses config default
    tools=tools,
    max_retries=10  # None uses config default
)

# Process response
for block in response:
    if hasattr(block, 'text'):
        print(f"Text response: {block.text}")
    elif hasattr(block, 'tool_name'):
        print(f"Tool call: {block.tool_name}")
        print(f"Arguments: {block.tool_input}")

# Extract tool calls from response
tool_calls = extract_tool_calls_from_response(response)
for tc in tool_calls:
    print(f"Tool: {tc.tool_name}, Input: {tc.tool_input}")

# Check token usage from metadata
print(f"Input tokens: {metadata.get('usage', {}).get('input_tokens', 0)}")
print(f"Output tokens: {metadata.get('usage', {}).get('output_tokens', 0)}")
```

--------------------------------

### Run JoyCode Agent with Custom Configuration

Source: https://github.com/jd-opensource/joycode-agent/blob/main/README.md

Runs the JoyCode agent pipeline with custom settings, such as enabling post-processing and specifying the number of parallel processes. This allows for fine-tuning the pipeline's execution.

```bash
python run_patch_pipeline.py --enable-post-processing --num-processes 2
```

--------------------------------

### Run Patch Pipeline via CLI

Source: https://context7.com/jd-opensource/joycode-agent/llms.txt

Demonstrates how to execute the main patch generation and test verification workflow using the run_patch_pipeline.py script. It supports parallel processing, specific problem targeting, and configurable test generation settings.

```bash
python run_patch_pipeline.py --num-processes 4 --enable-post-processing
python run_patch_pipeline.py --simple-mode --num-processes 2
python run_patch_pipeline.py --problem-id django__django-11099 --num-processes 1
python run_patch_pipeline.py --num-examples 10 --num-processes 4 --generate-tests --validate-with-tests
python run_patch_pipeline.py --no-generate-tests --no-validate-with-tests --num-processes 2
```

--------------------------------

### Test Docker Connectivity

Source: https://github.com/jd-opensource/joycode-agent/blob/main/README.md

Verifies that Docker is running and accessible, and can pull images from the specified registry. This is crucial for the containerized execution of the JoyCode pipeline.

```bash
docker pull docker.1ms.run/swebench/sweb.eval.x86_64.django__django-11099:latest
```

--------------------------------

### Run JoyCode Agent in Simple Mode

Source: https://github.com/jd-opensource/joycode-agent/blob/main/README.md

Executes the JoyCode agent pipeline in a simplified mode, focusing only on patch generation without test case creation or validation. Useful for quick patch generation tasks.

```bash
python run_patch_pipeline.py --simple-mode
```

--------------------------------

### Configure LLM API Key

Source: https://github.com/jd-opensource/joycode-agent/blob/main/README.md

Sets up the LLM configuration, including API key, base URL, model name, and token limits. This JSON file is used by the pipeline to interact with language models for tasks like patch generation.

```json
{
  "patch_generation": {
    "api_key": "your_api_key_here",
    "base_url": "https://api.openai.com/v1",
    "model_name": "gpt-5",
    "max_tokens": 4000,
    "temperature": 1
  }
}
```

--------------------------------

### Trajectory Compression and Similar Case Search with search_zip

Source: https://context7.com/jd-opensource/joycode-agent/llms.txt

Utilizes the search_zip module for compressing trajectories and finding similar cases, aiding in experience-driven retries. It provides functionalities for processing trajectories, managing workflows, and directly finding similar cases.

```python
from search_zip.flow import (
    FlowManager,
    TrajectoryProcessor,
    SimilarCaseFinder,
    process_trajectories_and_compress,
    find_similar_case
)
```

```python
success = process_trajectories_and_compress()
# This reads agent_logs.txt and predictions.json from output_files/<instance_id>/
# and creates compressed_trajectory.json for each instance
```

```python
flow_manager = FlowManager(output_files_dir="output_files")

# Step 1: Process and compress all trajectories
if flow_manager.process_all_trajectories():
    print("Trajectories compressed successfully")

    # Step 2: Find similar case for a failed instance
    failed_instance = "django__django-12345"
    successful_ids = ["django__django-11099", "django__django-11234", "matplotlib__matplotlib-23562"]

    similar_case = flow_manager.find_similar_case_for_failure(
        failed_instance_id=failed_instance,
        successful_ids=successful_ids
    )

    if similar_case:
        print(f"Found similar case: {similar_case.get('instance')}")
        print(f"Similarity score: {similar_case.get('similarity_score')}")
        print(f"Strategy: {similar_case.get('strategy')}")
        print(f"Key changes: {similar_case.get('key_changes')}")
```

```python
similar = find_similar_case(
    failed_instance_id="sympy__sympy-18189",
    successful_ids=["sympy__sympy-18100", "sympy__sympy-17630"]
)
```

```python
processor = TrajectoryProcessor(output_files_dir="output_files")
compressed_trajectories = processor.extract_and_compress_trajectories(
    successful_ids=["django__django-11099"]  # Optional: only compress specific instances
)
```

```python
finder = SimilarCaseFinder(compressed_trajectories_file="./compressed_trajectories.json")
available = finder.get_available_success_instances(
    successful_ids=["django__django-11099", "django__django-11234"]
)
print(f"Available instances for similarity search: {available}")
```

--------------------------------

### Interact with CLI Agent

Source: https://context7.com/jd-opensource/joycode-agent/llms.txt

Shows how to use the cli.py module to interact with the patch generation agent. It supports both interactive and automated modes, allowing users to specify workspaces, problem statements, and agent purposes.

```bash
python cli.py --workspace ./my_workspace
python cli.py --workspace ./workspace --problem-statement "Fix the authentication bug in the login module" --docker-container-id abc123def456 --use-container-workspace /testbed --logs-path ./agent_logs.txt --minimize-stdout-logs
python cli.py --agent-purpose patch_generation
python cli.py --agent-purpose test_generation
python cli.py --agent-purpose retry_agent
python cli.py --needs-permission --workspace ./workspace
```

--------------------------------

### File Manipulation with Editor API

Source: https://context7.com/jd-opensource/joycode-agent/llms.txt

Demonstrates creating a new file, performing string replacements, inserting content at a specific line, and undoing edits using the editor.run_impl method. These operations are fundamental for automated code modification and refactoring.

```python
result = editor.run_impl({
    "command": "create",
    "path": "/testbed/src/new_module.py",
    "file_text": '''"""New module for handling data processing."""

def process_data(data):
    """Process input data and return results."""
    if not data:
        return []
    return [item.strip() for item in data]
'''
}, dialog_messages=None)
```

```python
result = editor.run_impl({
    "command": "str_replace",
    "path": "/testbed/src/module.py",
    "old_str": '''def old_function():
    return None''',
    "new_str": '''def new_function():
    """Updated function with proper error handling."""
    try:
        return compute_result()
    except ValueError as e:
        logger.error(f"Computation failed: {e}")
        return None'''
}, dialog_messages=None)
```

```python
if result.success:
    print("Replacement successful!")
else:
    print(f"Replacement failed: {result.tool_output}")
```

```python
result = editor.run_impl({
    "command": "insert",
    "path": "/testbed/src/module.py",
    "insert_line": 5,  # Insert after line 5
    "new_str": "import logging\nlogger = logging.getLogger(__name__)"
}, dialog_messages=None)
```

```python
result = editor.run_impl({
    "command": "undo_edit",
    "path": "/testbed/src/module.py"
}, dialog_messages=None)
```

--------------------------------

### Patch Voting System using LLM

Source: https://context7.com/jd-opensource/joycode-agent/llms.txt

Implements a patch voting system that compares multiple patch candidates and selects the best one through LLM analysis. It involves preparing input files, building a voting prompt with problem statements and diffs, and calling an LLM for the decision.

```python
import json
from vote import open_ai_sdk, prompt_template, call_and_parse
```

```python
# Prepare input files:
# - patch_1.json: Primary patch candidates {"instance_id": {"model_patch": "..."}, ...}
# - patch_2.json: Alternative patch candidates
# - test-00000-of-00001.parquet: Instance metadata with problem statements
```

```python
# Build voting prompt for a single instance
problem_statement = "Fix the authentication bypass vulnerability in the login handler"
diff_1 = """
-- a/auth/login.py
+++ b/auth/login.py
@@ -45,6 +45,8 @@ def authenticate(username, password):
+    if not username or not password:
+        raise ValueError("Credentials required")
     user = User.query.filter_by(username=username).first()
"""
diff_2 = """
-- a/auth/login.py
+++ b/auth/login.py
@@ -45,6 +45,10 @@ def authenticate(username, password):
+    # Validate inputs
+    if username is None or password is None:
+        return None
+    username = str(username).strip()
     user = User.query.filter_by(username=username).first()
"""

prompt = prompt_template.format(
    problem_statement=problem_statement,
    diff_1=diff_1,
    diff_2=diff_2
)
```

```python
# Call LLM for voting decision
response = open_ai_sdk(prompt, max_retries=10)
```

--------------------------------

### Run JoyCode Agent for Single Instance

Source: https://github.com/jd-opensource/joycode-agent/blob/main/README.md

Processes a specific software issue instance identified by its problem ID. This command is useful for debugging or focusing on a particular issue, with a single process.

```bash
python run_patch_pipeline.py --problem-id django__django-11099 --num-processes 1
```

--------------------------------

### Run JoyCode Agent Pipeline

Source: https://github.com/jd-opensource/joycode-agent/blob/main/README.md

Executes the JoyCode agent pipeline with default settings, enabling post-processing and specifying the number of parallel processes. This is the primary command for running the automated code fixing process.

```bash
python run_patch_pipeline.py --num-processes 1 --enable-post-processing
```

--------------------------------

### Generate Test Cases in Docker using Python

Source: https://context7.com/jd-opensource/joycode-agent/llms.txt

Illustrates the process of generating test cases (Fail2Pass and Pass2Pass) within Docker containers for validating code patches. This Python script utilizes functions from the `test_case_generator.integration` module to manage test case generation and validation, integrating with the broader patch generation workflow. Dependencies include `rich` and `pathlib`.

```python
from test_case_generator.integration import (
    generate_test_cases_in_container,
    validate_test_cases_against_original_code,
    copy_test_cases_to_output
)
from rich.console import Console
from pathlib import Path

console = Console()
container_id = "swe-bench-agent.django__django-11099_abc123"

# Generate test cases
result = generate_test_cases_in_container(
    container_id=container_id,
    problem_statement="Fix the IndexError when processing empty QuerySets in Django ORM",
    problem_id="django__django-11099",
    console=console,
    workspace_path=Path("/tmp/workspace/django__django-11099"),
    output_file=Path("/tmp/workspace/test_generation_logs.txt"),
    quiet=True  # Reduce verbose output
)

```

--------------------------------

### Execute Full Voting Workflow via Python Script

Source: https://context7.com/jd-opensource/joycode-agent/llms.txt

This command initiates the full voting workflow of the JoyCode agent. It processes all instances defined in the input files and outputs the voting decisions to 'result.json'.

```bash
python vote.py
```

--------------------------------

### Configure LLM Models using JSON

Source: https://context7.com/jd-opensource/joycode-agent/llms.txt

Defines the structure for configuring various LLM models for different pipeline stages using a JSON file. This configuration allows customization of model names, API endpoints, retry counts, temperature, token limits, and timeouts for each purpose. The file `llm_server/model_config.json` is used for this purpose.

```json
{
  "description": "LLM Configuration for JoyCode Pipeline",
  "version": "2.0",
  "models": {
    "patch_generation": {
      "model_name": "gpt-5",
      "max_retries": 10,
      "temperature": 0.1,
      "max_tokens": 32000,
      "api_key": "sk-your-openai-api-key",
      "base_url": "https://api.openai.com/v1",
      "timeout": 120
    },
    "test_generation": {
      "model_name": "claude-sonnet-4",
      "max_retries": 8,
      "temperature": 0.1,
      "max_tokens": 32000,
      "api_key": "sk-your-api-key",
      "base_url": "https://api.anthropic.com/v1",
      "timeout": 120
    },
    "trajectory_compression": {
      "model_name": "gpt-4.1",
      "max_retries": 8,
      "temperature": 0,
      "max_tokens": 32000,
      "api_key": "sk-your-api-key",
      "base_url": "https://api.openai.com/v1",
      "timeout": 300
    },
    "similarity_search": {
      "model_name": "gpt-4",
      "max_retries": 8,
      "temperature": 0,
      "max_tokens": 32000,
      "api_key": "sk-your-api-key",
      "base_url": "https://api.openai.com/v1",
      "timeout": 300
    },
    "retry_agent": {
      "model_name": "gpt-5",
      "max_retries": 10,
      "temperature": 0.1,
      "max_tokens": 32000,
      "api_key": "sk-your-api-key",
      "base_url": "https://api.openai.com/v1",
      "timeout": 120
    }
  }
}
```

--------------------------------

### Python: Execute and Validate Tests in Container

Source: https://context7.com/jd-opensource/joycode-agent/llms.txt

Executes generated tests within a Docker container and validates the quality of the code diff based on test outcomes. It uses the test executor module to run tests and provides a structured result including pass/fail status, output, and exit codes. The validation logic assesses the diff quality based on test success rates and provides detailed debug information. Results are saved to a JSON file.

```python
from test.test_executor import (
    execute_tests_in_container,
    validate_diff_quality,
    save_test_results
)
from rich.console import Console
from pathlib import Path

console = Console()
container_id = "swe-bench-container-abc123"

# Execute tests in container
all_passed, test_results = execute_tests_in_container(container_id, console)

# test_results structure:
# {
#     "test_happy_path.py": {"status": "PASSED", "output": "...", "exit_code": 0},
#     "test_edge_case.py": {"status": "PASSED", "output": "...", "exit_code": 0},
#     "test_failure_scenario.py": {"status": "FAILED", "output": "...", "exit_code": 1}
# }

# Validate diff quality based on test results
validation_result = validate_diff_quality(test_results, console)

# validation_result structure:
# {
#     "total_tests": 3,
#     "passed_tests": 2,
#     "failed_tests": 1,
#     "success_rate": "66.7%",
#     "quality": "GOOD",  # EXCELLENT (>=80%), GOOD (>=60%), FAIR (>=40%), POOR (<40%)
#     "test_summary": {...},
#     "debug_info": {...}
# }

print(f"Quality: {validation_result['quality']}")
print(f"Success rate: {validation_result['success_rate']}")

# Save results to file
output_path = Path("output_files/django__django-11099/test_validation.json")
save_test_results(test_results, validation_result, output_path)
```

--------------------------------

### Python: Advanced String Replace Editor Tool

Source: https://context7.com/jd-opensource/joycode-agent/llms.txt

Provides an advanced file editing tool for sophisticated string replacement operations within a project workspace. It supports intelligent validation, backup management, and smart matching strategies. The tool can view entire file contents or specific line ranges, ensuring precise and safe modifications.

```python
from tools.str_replace_tool import StrReplaceEditorTool
from utils.workspace_manager import ProjectSpaceHandler
from pathlib import Path

# Initialize editor
workspace_manager = ProjectSpaceHandler(root=Path("/testbed"))
editor = StrReplaceEditorTool(
    workspace_manager=workspace_manager,
    ignore_indentation_for_str_replace=False,  # Strict matching
    expand_tabs=False
)

# View file contents
result = editor.run_impl({
    "command": "view",
    "path": "/testbed/src/module.py"
}, dialog_messages=None)
print(result.tool_output)

# View specific line range
result = editor.run_impl({
    "command": "view",
    "path": "/testbed/src/module.py",
    "view_range": [10, 50]  # Lines 10-50
}, dialog_messages=None)
```

--------------------------------

### Run JoyCode Agent Disabling Test Generation

Source: https://github.com/jd-opensource/joycode-agent/blob/main/README.md

Executes the JoyCode agent pipeline while explicitly disabling the generation and validation of test cases. This can be used when only patch generation is desired.

```bash
python run_patch_pipeline.py --no-generate-tests --no-validate-with-tests
```

--------------------------------

### Parse JSON Response in Python

Source: https://context7.com/jd-opensource/joycode-agent/llms.txt

Parses a JSON string from a response, expecting 'solution_index' and 'Basis of reasoning'. It extracts these values and prints them. This is useful for processing LLM outputs.

```python
result = json.loads(response.split("```json")[1].split("```")[0].strip())
print(f"Selected solution: {result['solution_index']}")
print(f"Reasoning: {result['Basis of reasoning']}")
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.