# Digital Employee Core

A Python library for building and managing AI-powered digital employees with support for tools, MCPs (Model Context Protocol), and flexible configuration management.

## Documentation

For comprehensive developer documentation and guides, please refer to the [Digital Employee Developer Documentation](https://gdplabs.gitbook.io/catapa/developer-documentation/digital-employee) on GitBook.

## Prerequisites

### IDE Recommendation

We recommend using one of the following IDEs for developing with this library:

**Option 1: PyCharm**
- Professional Python IDE with comprehensive features
- **Download**: [https://www.jetbrains.com/pycharm/](https://www.jetbrains.com/pycharm/)
- Editions: Professional (paid) or Community (free)

**Option 2: Visual Studio Code (and its forks)**
- Lightweight, extensible editor with Python support
- **VSCode**: [https://code.visualstudio.com/](https://code.visualstudio.com/)
- **Cursor** (AI-powered fork): [https://www.cursor.com/](https://www.cursor.com/)
- **Windsurf** (AI-enhanced fork): [https://codeium.com/windsurf](https://codeium.com/windsurf)
- Install the Python extension for full Python support

### Python Installation

This project requires **Python 3.12** (supports Python 3.11-3.12).

**Installation Instructions:**

- **Linux/WSL**:
  ```bash
  # Ubuntu/Debian
  sudo apt update
  sudo apt install python3.12 python3.12-venv python3.12-dev
  
  # Fedora
  sudo dnf install python3.12
  ```

- **macOS**:
  ```bash
  # Using Homebrew
  brew install python@3.12
  ```

- **Windows**:
  - Download from [python.org](https://www.python.org/downloads/)
  - Or use [pyenv-win](https://github.com/pyenv-win/pyenv-win) for version management

### Package Manager (uv)

This project uses **uv** as its package manager for fast and reliable dependency management.

**Installation Instructions:**

- **Linux/macOS**:
  ```bash
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```

- **Windows (PowerShell)**:
  ```powershell
  powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
  ```

- **Alternative (using pip)**:
  ```bash
  pip install uv
  ```

- **Verify Installation**:
  ```bash
  uv --version
  ```

For more information about uv, visit: [https://docs.astral.sh/uv/](https://docs.astral.sh/uv/)

## Setup

### 1. Install Dependencies

```bash
make install
```

### 2. Configure Environment

Copy the example environment file and add your credentials:

```bash
cp .env.example .env
```

Edit `.env` with your configuration:

```bash
# Required
AIP_API_URL=https://your-ai-platform-url.com
AIP_API_KEY=your-api-key
```

**How to Obtain API Credentials:**

To get the `AIP_API_URL` and `AIP_API_KEY` values, contact **Squad 4 (Claudia)** team:
- **Email**: `koi-claudia@gdplabs.id`
- **Contact**: `berty.c.l.tobing@gdplabs.id`

## Tool-Specific Requirements

### E2B Sandbox Tool

This tool requires an `api_key` parameter to be provided. You can either:
- Pass the API key directly as a parameter when using the tool, or
- Set the `E2B_API_KEY` environment variable (the tool will use this automatically if no parameter is provided)

### Hybrid Vector Retrieval Tool

This tool requires AWS credentials to be configured in the AIP environment where the digital employee is deployed.

## Configuration Management

### Understanding MCP Configuration Placeholders

The library uses YAML configuration templates (`digital_employee_core/config_templates/mcp_configs.yaml` and `tool_configs.yaml`) that contain **placeholder keys** in dollar-brace format (e.g., `${GOOGLE_CALENDAR_MCP_URL}`). These placeholders need to be replaced with actual values at runtime.

**How Placeholders Work:**

1. **Configuration Template** (in `mcp_configs.yaml`):
```yaml
digital_employee_google_calendar_mcp:
  config:
    url: ${GOOGLE_CALENDAR_MCP_URL}
    allowed_tools: ${GOOGLE_CALENDAR_MCP_ALLOWED_TOOLS:[]}
  authentication:
    type: api-key
    key: X-API-Key
    value: ${GOOGLE_MCP_X_API_KEY}
```

2. **Supply Values** using `DigitalEmployeeConfiguration`:

```python
from digital_employee_core import DigitalEmployeeConfig

configurations = [
    DigitalEmployeeConfig(
        key="GOOGLE_CALENDAR_MCP_URL",
        value="https://api.example.com/calendar/mcp"
    ),
    DigitalEmployeeConfig(
        key="GOOGLE_MCP_X_API_KEY",
        value="your-secret-api-key"
    ),
]
```

3. **Pass to Digital Employee**:

```python
from digital_employee_core import DigitalEmployee
from digital_employee_core.connectors.mcps import google_calendar_mcp

de = DigitalEmployee(
    identity=identity,
    mcps=[google_calendar_mcp],
    configs=configurations  # Placeholder values will be replaced automatically
)

de.deploy()
```

### Available Placeholder Keys

For a complete and up-to-date list of available placeholder keys, refer to the configuration template files:

- **MCP Configurations**: [`digital_employee_core/config_templates/mcp_configs.yaml`](digital_employee_core/config_templates/mcp_configs.yaml)
- **Tool Configurations**: [`digital_employee_core/config_templates/tool_configs.yaml`](digital_employee_core/config_templates/tool_configs.yaml)

Look for keys in the `${PLACEHOLDER_NAME}` format within these files. Common categories include:
- **Google MCPs**: Calendar, Docs, Drive, Mail, Sheets (+ shared `GOOGLE_MCP_X_API_KEY`)
- **GitHub MCP**: URL and API key configurations
- **SQL Tool MCP**: Database connection and authentication settings

### Configuration Priority

Configurations can be supplied in three ways:

1. **At Initialization** (applied during `deploy()`):
```python
de = DigitalEmployee(
    identity=identity,
    mcps=[google_calendar_mcp],
    configurations=configurations
)
```

2. **At Runtime** (applied per `run()` call):
```python
response = de.run(
    message="Check my calendar",
    configurations=runtime_configurations
)
```

3. **Combined** (initialization configs + runtime configs are merged):
```python
# Initialization configs for persistent settings
de = DigitalEmployee(
    identity=identity,
    configurations=base_configurations
)
de.deploy()

# Runtime configs for per-request overrides
response = de.run(
    message="Send email",
    configurations=request_specific_configurations
)
```

## Run Examples

### Basic Example

```bash
uv run python examples/basic_example.py
```

### Subclass Example

```bash
uv run python examples/subclass_example.py
```

## Run Tests

```bash
# Run unit tests (excludes integration tests)
make test

# Run with verbose output
uv run pytest -v

# Run with coverage report
make coverage

# Run with coverage HTML report
make coverage FORMAT=html
# Open htmlcov/index.html in browser

# Run specific test file
uv run pytest tests/digital_employee/test_core.py
```
