aicodetools 0.1.5

A powerful framework for providing tools to AI agents with Docker/local deployment support

aicodetools

A powerful framework for providing tools to AI agents with Docker/local deployment support.

CodeInstance is a class that wraps deployment environments (Docker/local) and provides various code tools to AI agents including file operations, bash sessions, search capabilities, and more.

Installation

You can install the package using pip:

pip install aicodetools

Or for development:

pip install -e .

Quick Start

from aicodetools import CodeInstance

# Create instance with Docker environment
config = {
    'docker': {
        'image': 'python:3.12',
    },
    'tool_config': {}
}

# ~~

class DockerDeploymentConfig(BaseModel):
    """Configuration for running locally in a Docker container."""

    image: str = "python:3.11"
    """The name of the docker image to use."""
    port: int | None = None
    """The port that the docker container connects to. If None, a free port is found."""
    docker_args: list[str] = []
    """Additional arguments to pass to the docker run command. If --platform is specified here, it will be moved to the platform field."""
    startup_timeout: float = 180.0
    """The time to wait for the runtime to start."""
    pull: Literal["never", "always", "missing"] = "missing"
    """When to pull docker images."""
    remove_images: bool = False
    """Whether to remove the image after it has stopped."""
    python_standalone_dir: str | None = None
    """The directory to use for the python standalone."""
    platform: str | None = None
    """The platform to use for the docker image."""
    remove_container: bool = True
    """Whether to remove the container after it has stopped."""

    type: Literal["docker"] = "docker"
    """Discriminator for (de)serialization/CLI. Do not change."""

    model_config = ConfigDict(extra="forbid")


# Create and start the instance
instance = CodeInstance('docker', config, auto_start=True)

# Get specific tools for your agent
tools = instance.get_tools(include=['read_file', 'write_file', 'run_command'])

# Use with your AI agent framework (e.g., Swarms)
from swarms import Agent

agent = Agent(
    agent_name="CodingAgent",
    system_prompt="You are a helpful coding assistant with file and command tools.",
    tools=tools
)

# Clean up when done
instance.stop_sync()

Available Tools

The CodeInstance provides access to these tools:

• File Operations: read_file, write_file, edit_file
• Directory Operations: list_directory
• Command Execution: run_command, run_bash_session, create_bash_session
• Code Analysis: format_code, analyze_project_structure, get_file_dependencies
• Search Operations: glob_files, grep_files, find_references

Usage Examples

Basic Usage (Async)

import asyncio
from aicodetools import CodeInstance

async def example_usage():
    config = {
        'docker': {'image': 'python:3.12'},
        'tool_config': {}
    }
    
    # Using async context manager (recommended)
    async with CodeInstance('docker', config) as instance:
        print(f"Started CodeInstance with {instance.get_deployment_type()} deployment")
        
        # Get available tools
        tools = instance.get_available_tools()
        print(f"Available tools: {len(tools)}")
        
        # Get wrapped tools for your agent
        wrapped_tools = instance.get_tools(include=['read_file', 'write_file', 'list_directory'])
        print(f"Wrapped tools: {len(wrapped_tools)}")

asyncio.run(example_usage())

Agent Integration Example

from dotenv import load_dotenv
from swarms import Agent
from swarms.structs import Conversation
from aicodetools import CodeInstance

load_dotenv()

def create_coding_agent_with_tools():
    """Create a coding agent with read, write, and run_command tools using Docker"""
    
    config = {
        'docker': {
            'image': 'python:3.12',
        },
        'tool_config': {}
    }
    
    # Create CodeInstance with auto_start=True to immediately get tools
    instance = CodeInstance('docker', config, auto_start=True)
    
    # Get the three main tools: read, write, run_command
    tools = instance.get_tools(include=['read_file', 'write_file', 'run_command'])
    
    # Create the coding agent with tools
    coding_agent = Agent(
        agent_name="CodingAgent",
        system_prompt="""You are a helpful coding agent with access to file operations and command execution in a Docker container.
        You can:
        1. Read files to understand code structure
        2. Write/modify files to implement features
        3. Run commands to test and execute code
        
        You are running in a Python 3.12 Docker container environment.
        Always be careful with file operations and command execution.""",
        model_name="gemini/gemini-2.0-flash",
        max_loops=3,
        max_tokens=4096,
        temperature=0.3,
        output_type="str",
        tools=tools
    )
    
    return coding_agent, instance

# Create and use the agent
agent, instance = create_coding_agent_with_tools()

# Run a task
response = agent.run("Create a simple Python script called 'hello_world.py' that prints 'Hello, World!' and then run it")
print(response)

# Clean up
instance.stop_sync()

Features

• Docker & Local Deployment: Run tools in isolated Docker containers or local environment
• Tool Statistics: Track tool usage and performance metrics
• Async Support: Full async/await support with context managers
• Safety Features: Read-before-write protection for file operations
• Agent Integration: Works seamlessly with AI agent frameworks like Swarms
• Comprehensive Tools: 14+ built-in tools for file operations, command execution, and code analysis

Requirements

• Python 3.10+
• Docker (for Docker deployment)
• Dependencies: swarms, swerex

Development

Code Quality 🧹

• make style to format the code
• make check_code_quality to check code quality (PEP8 basically)
• black .
• ruff . --fix

Tests 🧪

pytests is used to run our tests.

Publishing 🚀

poetry build
poetry publish

License

MIT