digital-employee-core 0.0.16

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.

Setup

1. Install Dependencies

poetry 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

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 DigitalEmployeeConfiguration

configurations = [
    DigitalEmployeeConfiguration(
        key="GOOGLE_CALENDAR_MCP_URL",
        value="https://api.example.com/calendar/mcp"
    ),
    DigitalEmployeeConfiguration(
        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],
    configurations=configurations  # Placeholder values will be replaced automatically
)

de.deploy()

Available Placeholder Keys

Refer to digital_employee_core/config_templates/mcp_configs.yaml and tool_configs.yaml to see all available placeholders. Common ones include:

Google MCPs:

• GOOGLE_CALENDAR_MCP_URL
• GOOGLE_CALENDAR_MCP_ALLOWED_TOOLS
• GOOGLE_DOCS_MCP_URL
• GOOGLE_DOCS_MCP_ALLOWED_TOOLS
• GOOGLE_DRIVE_MCP_URL
• GOOGLE_DRIVE_MCP_ALLOWED_TOOLS
• GOOGLE_MAIL_MCP_URL
• GOOGLE_MAIL_MCP_ALLOWED_TOOLS
• GOOGLE_SHEETS_MCP_URL
• GOOGLE_SHEETS_MCP_ALLOWED_TOOLS
• GOOGLE_MCP_X_API_KEY

GitHub MCP:

• GITHUB_MCP_URL
• GITHUB_MCP_X_API_KEY

SQL Tool MCP:

• SQL_TOOL_MCP_URL
• SQL_AUTH_TOKEN
• SQL_API_KEY
• SQL_IDENTIFIER

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 Usage

poetry run python examples/basic_usage.py

Configuration Usage

poetry run python examples/configuration_usage.py

Subclass Example

poetry run python examples/subclass_example.py

Run Tests

# Run all tests
poetry run pytest

# Run with verbose output
poetry run pytest -v

# Run with coverage
poetry run coverage run -m pytest
poetry run coverage report

# Run with coverage HTML report
poetry run coverage run -m pytest
poetry run coverage html
# Open htmlcov/index.html in browser

# Run specific test file
poetry run pytest tests/digital_employee/test_digital_employee.py