digital-employee-core 0.1.8

No project description provided

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 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/
• 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/
• Cursor (AI-powered fork): https://www.cursor.com/
• Windsurf (AI-enhanced fork): 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:

  # Ubuntu/Debian
  sudo apt update
  sudo apt install python3.12 python3.12-venv python3.12-dev
  
  # Fedora
  sudo dnf install python3.12
  

• macOS:

  # Using Homebrew
  brew install python@3.12
  

• Windows:

  • Download from python.org
  • Or use 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:

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

• Windows (PowerShell):

  powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
  

• Alternative (using pip):

  pip install uv
  

• Verify Installation:

  uv --version
  

For more information about uv, visit: https://docs.astral.sh/uv/

Setup

Automated Setup (Recommended)

For a complete automated setup that installs all prerequisites and configures the project, run:

./setup.sh

This script will:

1. Detect your operating system
2. Install Python 3.12 (if not already installed)
3. Install uv package manager (if not already installed)
4. Check/install gcloud CLI (optional, for private packages)
5. Install project dependencies via make install
6. Create a .env file template

Note: The script may require sudo privileges for installing system packages. After running the script, edit the .env file with your API credentials (see below).

Manual Setup

Alternatively, you can set up the project manually:

1. Install Dependencies

make install

2. Configure Environment

Copy the example environment file and add your credentials:

cp .env.example .env

Edit .env with your configuration:

# 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: [e-mail]
• Contact: [e-mail]

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):

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:

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:

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
• Tool Configurations: 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()):

de = DigitalEmployee(
    identity=identity,
    mcps=[google_calendar_mcp],
    configurations=configurations
)

2. At Runtime (applied per run() call):

response = de.run(
    message="Check my calendar",
    configurations=runtime_configurations
)

3. Combined (initialization configs + runtime configs are merged):

# 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

uv run python examples/basic_example.py

Subclass Example

uv run python examples/subclass_example.py

Run Tests

# 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